Updated: October 16, 2020 10:42am

Customization Guide

This page has information about creating custom plugins to extend Prism functionality. For example, you might want to add a special button or special field to the Prism interface.

Basic Steps

  1. Review the Prism API documentation and refer to it as you create the customization. To access the API documentation, point your browser to the Prism server, followed by: "/api-explorer".    For example: http://myprism.mycompany.com/api-explorer
  2. When the customization is ready, add it to the Prism server (Admin Console > Customizations area).
  3. Modify the Customization.js and Customization.html files.
  4. Assign the customization to individual workstations.
  5. Restart the Proxy. The Customization is now available for use. For example, if you have created a side-button customization, the side button will be available in the Prism menu (access by clicking the Retail Pro button).

 Customizations are placed in C:\ProgramData\RetailPro\Server\Modules

Add Proxy Customization via Admin Console UI

  1. Navigate to the Admin Console > Customizations.    
  2. Click Add New Customization.    
  3. Enter configuration information. Refer to the New Customization Fields table for details. Click the Save button when finished.    

 Customization Fields

Field Description
Name Enter the name of the customization. Must be a unique name. For example, you can concatenate developer name and developer ID at beginning of the customization name to create a customization namespace.
Version Enter the version number of the customization. Used to trigger automatic updates
Developer ID  Enter the developer ID of the developer who created the customization. Note: Contact Retail Pro for a Developer ID if you don't have one yet.
Customization Enter customization ID. Allows you to leverage licensing info for the customization.
Control Address  Enter the IP Address of the controller for the customization.
Control Port Enter the port number that will be used for the customization to communicate with RP Prism.
Manifest File Location Enter the full path to the manifest file for the customization.
Selection Location Select where the customization will operate: Undefined, Remote, or Local.
Retry The Retry setting for Customizations defines the maximum number of times the customization will attempt to establish a connection to the Prism Proxy. By default, the system will try three times to establish a connection to the Proxy. You can change the Retry setting to the desired number. The Retry setting is stored in the CUSTOMIZATION table as MAX_NOTIFICATION_TRIES.
Configuration Data This area enables you to define preferences (using JSON file, etc.) for a given store or a given workstation.
Auto Start
Auto Deploy/Update
Auto Stop
Required 
These options are only available for local customizations, meaning those that run on the same machine.

 Sample Customization screen:

customizationsprefs
Add Customization to Proxy
This section explains how to add a customization to an individual proxy via the Admin Console UI. This step will need to be repeated for each proxy that will use the customization.

  1. Drill down to the workstation level. Click the Edit button for the desired workstation.    
  2. Click the HAL Settings tab    
  3. Select the workstation from the HAL dropdown.    
  4. Click the Customizations tab.    
  5. Click Add Customization.    
  6. Enter configuration information and save.    

 Add Customization via Prism API
This section explains how to configure a Proxy customization by entering the information via the Prism API. The example presented here is a generic example that should be adapted for your own customizations and workstation environment.

High-Level Steps

  1. Create the customization by doing a POST that includes configuration info.
  2. Get the Proxy SID via a GET command.
  3. Add the Customization to the Proxy via a POST.

Each of these steps is explained in more detail in the sections that follow.

Step 1. Create Customization
This section explains how to create the customization using a POST that includes configuration info for the customization. Details about URL format and configuration fields are listed after the steps.
Note: The RESPONSE to the POST will include the "customization sid" - a unique system-assigned ID for the customization. You will need to include this customization sid when adding the customization to the Proxy (Step 3).

  1. Point your browser to the Prism server, followed by: "/api-explorer".    
  2. Login using you' your Prism username and password.    
  3. Click the Raw Requests tab.     
  4. Select POST.     
  5. Select application/json.    
  6. Enter the Configuration Data in the text box.   
  7. Click Send Request.    
  8. The RESPONSE to the POST includes a "sid". This is the customization sid that you will reference this SID in Step 3.    

 [
  {
    ...
    "sid" : "441321587000101047",
    ...
  {
]

Step 1 Example URL Format
https://[fqdn]:[port]/v1/rest/customization
Example: https://myworkstation.mycompany.com/v1/rest/customization
Step 1 Example Configuration Data
[
  {
    "control_address": "127.0.0.1",
    "control_port": "5678",
    "customization_id": "000",
    "developer_id": "000",
    "location": 2,
    "name": "EventLogger",
    "origin_application": "RProPrismWeb",
    "shutdown_flag": true,
    "startup_flag": true,
    "timeout": "120000",
    "version": "1.0.0"
  }
]

Configuration Data Fields (for Step 1)

Field Description
control_address Enter the IP Address of the controller for the customization. For a "local" customization, use the loopback address.
control_port Enter the port number that will be used for the customization to communicate with RP Prism.
customization_id Customization ID
developer_id Developer ID.
location 0 = Undefined, 1 = Remote, 2 = Local  (Local indicates the customization is on the same machine as the Proxy.)
name Enter the name of the customization. Must be a unique name. (Tip: concatenate developer name and developer ID at beginning of the customization name to create a customization namespace)
origin_application V9 or Prism
shutdown_flag If set to true, the customization will shut down automatically.
startup_flag If set to true, the customization will start up automatically.
max_retries The number of times the customization will attempt to establish a connection with the Proxy. Default = 3.
timeout The number of milliseconds that will cause a timeout error if a connection cannot be made.
version The customization's version number. For a new customization, this should be 1.0.0

Step 2. Get the Proxy SID

Do a GET to obtain the Proxy SID. You will enter the Proxy SID in Step 3.

  1. Select GET.     
  2. Select application/json.    
  3. Enter the URL.    
  4. Enter the configuration data in the text box. Note: You must put a back slash in front of every forward slash in the path.    
  5. Enter the URL of the resource. Click Send Request    

Example URL Format (for Step 2 )

https://myworkstation.mycompany.com:8081/v1/rest/proxy?filter=(workstation_name,eq,"myworkstation_8081")

Step 3. Add the Customization to Proxy

This last step adds the customization to the proxy via a POST. The configuration data for the POST includes the Customization SID from Step 1 and the Proxy SID from Step 2.

  1. Select POST.     
  2. Select application/json.    
  3. Enter the URL    
  4. Enter the configuration data in the text box.    
  5. Select "Reload HW Configuration" from the Proxy right-click menu.     
  6. Select "Open Browser" from the Proxy right-click menu.    
  7. Login to Prism. The Proxy customization should now be running.    

Example URL Format (for Step 3 )

Sample

https://myworkstation.mycompany.com:8081/v1/rest/proxy/415563465000186028/extension
Example Configuration Data (for Step 3 )
[
  {
    "control_port_override": 5678,
    "customization_sid": "441321587000101047",  From Step 1
    "local_path": "C:\\Program Files (x86)\\RetailPro\\PrismProxy\\EventViewer.exe",
    "origin_application": "RProPrismWeb",
    "proxy_sid": "415563465000186028",
    "required_flag": true
  }
]
Configuration Data Fields (for Step 3 )

Field Description
control_port_override Port number used to communicate with the Proxy.
customization_sid The Customization SID (from Step 1)
local_path Path to the customization.
origin_application In our example, the origin application is RProPrismWeb.
proxy_sid The Proxy SID (from Step 2).
required_flag If enabled, the proxy requires the customization to exist.


Modify Customizaton.js, Customization.html Files

For Prism to correctly recognize and use the customization, the following two files must be modified: Customizations.html and Customizations.js   Both files are located in the directory C:\ProgramData\RetailPro\Server\WebClient (assuming default installation path). Please make a backup of these files before you modify them.

Customizations.html

  1. Navigate to the \ProgramData\RetailPro\Server\WebClient folder. Make a backup copy of the Customizations.html file. Open the Customizations.html file in a text editor that can correctly display html, e.g. Notepad++ or Sublime Text.    
  2. Add <script> tags for each javascript file that is used by the customization. Save the file after making these changes.

<script type="text/javascript" src="/plugins/filename.js">

<script type="text/javascript" src="/plugins/filename.js">

customizations html file

Customizations.js
Open the customizations.js file in a text editor that can correctly display html and similar files, e.g. Notepad++. Save the file after you have made the changes.

  1. Navigate to the …\ProgramData\RetailPro\Server\WebClient folder. Make a backup copy of the Customizations.js file.   
  2. Open the Customizations.js file in a text editor that can correctly display html, e.g. Notepad++ or Sublime Text.  
  3. Add a line similar to the following for each file used by the customization.

dependencies.push(‘pluginFile');    

customizations js file

Assign Customization to Workstation

  1. Launch the Prism Proxy and log in.     
  2. Go into the Admin Console and drill down to the desired workstation. Click the Edit button.    
  3. Click the HAL Settings tab.     
  4. Select a Proxy from the drop-down.    
  5. Click Add Customization.     
  6. Navigate to the drop-down and select the Shopper Display customization.    
  7. Enter a Port Override. Default = Port 5678    
  8. Click the Save button.    
  9. Click the Exit button.    
  10. Repeat until you have added the Shopper Display customization and a Port to all Proxies.    
  11. Exit the Proxy and then restart.    

Restart the Proxy
After installing a customization and assigning it to a workstation, you must restart the Proxy. Customizations are identified by the Proxy during startup.

Required ZeroMQ DLL - libzmq-v100-mt-3_2_3.dll

 

The Proxy uses the ZeroMQ messaging protocol to exchange information between the Proxy and a customization. You have to provide the ZeroMQ .dll where the customization lives. When the customization starts up, the Proxy will look for that .dll. The ZeroMQ DLL is located in the Program Files(x86)\Retail Pro\PrismProxy\libzmq-v100-mt-3_2_3.dll directory. Grab a copy of that .dll, put it wherever your customization is and you are good to go.

Location of Customizations
Customizations can be located anywhere; however, if you are trying to control a piece of hardware in the lane, it will have to be installed in the lane. If Prism can talk to the customization via TCP/IP, that's all that matters. How you set up your customization will also determine a little about how Retail Pro interfaces with it. If building a customization that runs in the lane, there will be one proxy talking to that customization. But if a customization is on the server in the store, that customization must be able to handle multiple connections and will require multiple ports to be opened (because each Proxy to customization request requires a unique port).

Translations for Customizations
You can easily implement translations for their third-party UI customizations by making simple edits to a copy of the appropriate language-specific .json file. Simply type (or copy/paste) the desired translation text next to the base (native) text and save the file to the \locale folder with  -custom appended to the file name. When loading the page, Prism will check if a -custom version exists and load the -custom version instead. This change provides developers with an easy-to-implement standard for handling translations. For example, if the file was named  en-us.json, then name the file en-us-custom.json. We recommend using the English text of the translation for the key.

  1. Navigate to the C:\ProgramData\RetailPro\Server\WebClient\locale folder.     
  2. Scroll down to the JSON files. Copy the JSON file for the language you want to translate.     
  3. Save the file to the \locale folder and append -custom to the file name. For example, if the file was named  en-us.json, then name the file en-us-custom.json    
  4. Add translations for individual strings as needed and save the changes. The contents of the file must be a single JSON object with unique key-value pairs. Keys should be an alphabetic string. Numeric values should not be used as they will conflict with the core translation keys. It is suggested to use the English text of the translation for the key. Log out and log back in to see the translations.   

en-us-custom.json
{
"Theater":"Theater",
"Math":"Math",
"Shopping Cart":"Shopping Cart"
}

en-gb-custom.json
{
"Theater":"Theatre",
"Math":"Maths",
"Shopping Cart":"Trolly"
}