Customization Guide

About Customizations
Retailers can easily create their own custom plugins to extend Prism functionality.
Basic Steps for Creating and Using Customizations with Prism
1.    Create the customization. If creating a customization in .NET or C#, compile the build into an .exe.
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, if necessary.
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).
Add Proxy Customization via Admin Console UI
This section has information about configuring a customization via the Admin Console UI.
Steps    Instructions    Screen Elements
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

 Customization Fields

 Sample Customization screen:

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",
    ...
  {
]

Example URL Format
https://myworkstation.mycompany.com/v1/rest/customization
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

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
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
https://myworkstation.mycompany.com:8081/v1/rest/proxy/415563465000186028/extension
Example Configuration Data
[
  {
    "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

Modify Customizaton.js, Customization.html Files
For Prism to correctly recognize and use the customization, the following two files must be modified:

• Customizations.html
• 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.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');    

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 in the Program Files(x86)\Retail Pro\PrismProxy\libzmq-v100-mt-3_2_3.dll directory. Copy that .dll and put it wherever your customization is.

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"
}