Article ID: 208

FAQ - Retail Pro Prism Customizations

FAQ - Retail Pro Prism Customizations

This article answers common questions relating to Retail Pro Prism customizations.

 

General API Questions


Q: Where can I find documentation on the Prism APIs?
A: On your Prism server. https://SERVERNAME/api-documentation as well as https://SERVERNAME/docs
(Change SERVERNAME to the name of your server)

Q: Where can I find code samples for building customizations?
A: For Proxy Customizations: On the Prism Bit Bucket Repo. https://bitbucket.org/RetailProPrism/prism-sdk
For Web Customizations: On your Prism server (ex C:\Program Data\Retail Pro\Server\WebClient\plugin\sample\cayan)

Q: Where can I ask questions if I get stuck?
A: On the Retail Pro Talk Forums. https://rprotalk.retailpro.com/

Q: Where can I see the objects, properties and methods exposed through the Prism API?
A: On your Prism server. https://SERVERNAME/api-explorer (Change SERVERNAME to the name of your server)

Q: When I browse https://SERVERNAME/api-explorer many of the resources are not showing up. Why not?
A: Edit your RPSRestServiceModule.ini file and add the following
  [SYSTEM]
  PREALLOCATE=TRUE
Then Stop>Start Apache
NOTE: Do not do this on production servers.

 

General UI Customization Questions


Q: What programming languages do I need to know to build client customizations?
A: HTML, CSS, JavaScript, AngularJS.

Q: How do I customize the way Prism looks?
A: You can modify the CSS and or the HTML files to adjust the positioning and "theme" of the client.

Q: How do I remove something from the prism screen?
A: Copy the HTML file to the customizations folder for the web client. Make sure you put them in the same path and in the copy, remove the element from the HTML that you want to remove from the screen.

Q: I want to completely replace a screen with a custom screen?
A: Place your custom screen in the customizations folder for the web client. Make sure you put them in the same path and name for the screen you want to replace.

Q: I modified the HTML files in the web client but a new install overwrote them. How can I stop this from happening?
A: Place your modified HTML files in the customizations folder for the web client. Make sure you put then in the same path and name for the screen you want to replace.

Q: How do I connect to another server from the client?
A: You cannot due to the browsers XSS rules. Build a Proxy Customization for this this instead.

Q: How can I talk to my hardware from the client?
A: You cannot due to the browsers sandbox rules. Build a Proxy Customization for this this instead.

Q: How can I change something on the document when a customer/item is added?
A: There are event hooks that will allow you run code when a customer or item is added to a document. You would need to write JavaScript code in a client customization to change the document.

Q: How do I get different data from the server for my custom code?
A: The client will in most cases have all the data that is currently being worked on, but if you need to get additional data from the server you make an HTTP request. See the REST FAQ below.

 

General Prism Proxy Customizations


Q: What language can I use to build a proxy customization?
A: Any language with ZMQ bindings. As of 9/2017 there are 52 languages that have bindings for ZMQ. See http://zeromq.org/bindings:_start/p/1 for a complete list.

Q: Do I build a DLL for a customization?
A: No, you should build an EXE or windows service

Q: What is the difference between building an EXE or windows service?
A: As a windows service, you can guarantee that your customization is started with windows and the there is no application a user can close. We do recommend building an EXE first and getting all your functionality working before converting your application to a service.

Q: How does the Proxy know what messages to send to my customization?
A: During the initial communication between the proxy and a customization the GetSubscriptions message expects a list of the communications you want to know about.

Q: How do I set up my proxy customization to get custom messages?
A: In the GetSubscriptions response include a resource that is not a Prism resource. A best practice here is to prefix the name of the customization i.e. SwiftEFT_StartTransaction as an example.

Q: How do I stop custom messages from going to the server?
A: Set the Continue for the message to False and Provide a valid HTTP response code in the StatusCode parameter i.e. 200 = Success, 500 = Error of some sort.

Q: How do I get the proxy to load my customization?
A: First do this once for your installation
      Go to Admin Console > Customizations and add your customization to the list there.
   Then do this for each workstation that will load the customization
      Go to Admin Console > Preferences & Settings > Node Selection and select your workstation and edit.
      Select the HAL Setting Tab
      Select the Proxy for your workstation from the drop-down list
      Select the Customizations tab
      Add your customization to the list for this proxy

Q: Where do I put my customization?
A: For hardware customizations, we recommend a proxy and customization on each lane. For service customizations, these can be located anywhere.

Q: I have a customization on my store server but only one proxy can connect to it. How do I fix this?
A: Each proxy connects to the customization on a dedicated port. If you want to build a customization to support 10 different proxies you will need to open and listen to 10 different ports. One for each proxy.

Q: How do I set up global configuration data for my customization?
A: No, you can put that data in any format you want (JSON, XML, INI) in the configuration area for your customization in Admin Console > Customizations

Q: Can I set up per lane configuration data from the server?
A: Yes, in the Customizations Tab for linking a customization to a proxy you can add configuration data that is specific to that proxy.

Q: How do I make the proxy talk to my customization after I stopped and started it?
A: Either restart the proxy or Right click on the proxy icon in the system tray and select "Reload HW Config"

Q: My customization uses an external service that takes a long time to respond. How can I stop the proxy from timing out the call to my customization?
A: Admin Console > Customizations you can set a custom timeout in milliseconds for communication between the proxy and your customization. Remember this is a blocking call, so extremely long timeouts will degrade performance or cause the browser to fail the communication. 

 

REST


Q: How would I get a list of the customers from the server?
A: GET http://SERVERNAME/v1/rest/customer  or for web customizations ModelService.get(?Customer?)

Q: When I call http://SERVERNAME/v1/rest/customer my server crashes. Why?
A: When you call http://SERVERNAME/v1/rest/customer without a filter or a SID you are asking for every customer record on the server. The memory required to prepare the response can overrun the memory available to Apache on the server. You should always filter root level elements or ask for a specific SID.

Q: How do I reduce the number of records I get back to what I can display in the UI?
A: Using pagination. You can use the Page Size, Page_No, and Count URL parameters to control pagination.
NOTE: Use of count will degrade performance as a database table scan is required to complete this operation.

Q: Why can?t I access http://SERVERNAME/v1/rest/address to get customer addresses?
A: Address is a sub resource of customer to get the addresses of a specific customer you need to get the SID of that customer and call http://SERVERNAME/v1/rest/customer/SID/address or for web customizations ModelService.get(?Address?,{customer_sid:SID}) and the server will return with the addresses of that customer.

Q: How can I control what attributes(fields) the server returns?
A: Use the cols parameter. e.g. http://SERVERNAME/v1/rest/customer?cols=last_name,first_name or for web customizations ModelService.get(?Customer?,{cols:?last_name,first_name?})

Q: What is row_version for?
A: Row Version is a field we use to allow stateless locking of a record. Every time a record is PUT (saved) the server increments the Row Version, when you PUT changes to a record if the row version does not match what the server has, then something else has changed the record and you should reread the record to get the latest changes before sending your changes to the server.

Q: When I call http://SERVERNAME/v1/rest/customer I get a response with a 403 error?
A: You must authenticate/logon to the server before most resources can be accessed

 

Common Use Cases


Fiscalization Reporting

Problem

In this use case, there is a need to report to an external source (web service, hardware, etc.) when transactions are started, when items are added or removed from a document, and when the document is finalized.

Solution

A Proxy customization that is subscribed to the following events:

- POST of document will let you know when a document is started. You can add tracking data to the document say in the notes field.
- POST of document/items will let you know when an item is added
- POST of document/tender will let you know when tenders are added to the document
- PUT of document/item will let you know when a quantity or price has changed
- DELETE of document/tender will let you know if a tender has been removed
- PUT of document will let you know if the document is finalized or cancelled

When these events fire you can capture the data needed for the fiscal reporting and make a connection to the fiscal reporting entity and report the data.

Best Practice

For the case where you do not need to modify the item, tender, document etc. have the communication with the fiscal reporting entity happen in a separate thread allowing the server to continue processing without waiting.

 

Custom EFT Solution

Problem

In this use case, there needs to be a custom EFT solution created to work with a third parts EFT provider.

Solution

Client/UI

Start by copying the Cayan customization from ProgramData\Retailer\Server\WebClient\plugins\sample\cayan to the ProgramData\RetailPro\Server\WebClient\plugins\EFT\YourEFTSolutionName.

You can then begin to customize the client UI for the solution needed.

Proxy

Create a proxy customization that subscribes to the EFT messages from the UI that you need.

When these events are called you can make connections to your EFT Hardware and/or the external EFT gateway as needed.

Best Practice

Consider changing the timeouts for long running processes.

 

Data Synchronization

Problem

An external CRM system is used and needs to keep customers synchronized between prism and the external system.

Solution

Create a proxy customization that subscribes to PUT, POST, DELETE on customer, customer/address, customer/email, and customer/phone. When data changes communicate those changes with your external CRM system.

Create an external application/service that monitors your CRM solution and POSTs, PUTs, DELETEs customers to Prism when those changes take place.

Best Practice

Do not try to bulk insert/update customers into prism while in production. Depending on the number of customers and the level of changes this will cause performance issues for other users of the system.

Note: In the future, we will be opening access to the high-speed data bus that Prism uses for its own day to day synchronization.

 

Custom Hardware

Problem

You need to integrate custom hardware into Prism.

Solution

Create a client customization with the UI needed to trigger and respond to the custom hardware requests. Add custom calls to the server for your hardware.

Create a proxy customization to intercept the custom calls from the client and the necessary code to communicate with the hardware and respond to the client.

Best Practice

Remember that to share the hardware for multiple workstations that you need to create a customization that can communicate on multiple ports and arrange the calls to and from the hardware interface.