Updated: March 23, 2021 8:56am

Prism Tech Toolkit

Prior version: 1.14.6 Tech Toolkit PDF

Prior version: 1.14.7 Tech Toolkit PDF

Prism 2.0 Tech Toolkit

The Prism Tech Toolkit provides a central portal for administrators to carry out various system tasks. In earlier releases of Prism, users accessed the toolkit via a separate .exe (techtoolkit.exe). Beginning with Prism 1.14.7, the toolkit is web-based so users can access the toolkit via the same web browser they use to launch and run Prism.
To launch Tech Toolkit:
Append /TTK to the Prism server FQDN or hostname:
Example:
myserver.mycompany.com/TTK
Enter login credentials. Log into the Tech Toolkit as an Administrator. Many functions of the toolkit, such as starting/stopping services with Service Manager, require administrator privileges.

Top Menu Options
Along the top of the Tech Toolkit screen is a set of tabs that provide access to different areas of the toolkit.
TTK top menu 
The following table lists the top menu options:

Tab Description
System  System information. This is the default.
Services The Service Manager area of the toolkit enables you to easily start/stop services and change configuration from a central portal.
SSL SSL Manager. In this area, users can install SSL certificates on machines running Prism
Scheduler Schedule tasks to be run on a regular interval using Scheduler
Logs Log Viewer. View/search logs for Prism services from one central portal.
Data injection Currently this area is used to load ZIP and Postal Code data for use with the ZIP Code Lookup feature.


Side (hamburger) Menu Enterprise Management Options
On the side menu, the enterprise nodes are displayed. In the screenshot below, a single node with the default name of HQ is displayed. By clicking on the icon next to the server name, users can access a menu for doing things like add/remove subordinate servers and export the server identity file.

Server Menu Option Description
Client Details Information about the client machine.
Add Subordinate server Prism servers must be added to the enterprise in a top-down manner. Select this option to add a subordinate server to the root authority server (or to an intermediate-level POA).
Add Former Server If a server was previously joined to a Prism enterprise and then that server was later removed, use the "Add Former Server" option to rejoin the server to the enterprise.
Remove Server Remove a subordinate server from the enterprise.
Export Identity  Create the Export Server Identity file. If Prism needs to be reinstalled, you must reference the Server Identity File during the Prism Server installation.
Rename Server Provides access to the Rename Server tool.
Log Out Log out of the currently logged-in server.

System
Click the System tab to display information about the logged-in user's system. Technicians can view operating system, hard disk and memory information as well as Prism component build information. This information can be useful during troubleshooting.
Sample System Info in Tech Toolkit
TTK System tab

The following table has information about the System tab information:
Operating System Information

Fiel Description
Machine name Name of the host or virtual machine.
Operating system Operating system installed on the machine.
OS Details OS version and build information.
OS Architecture OS architecture (e.g. intel x64).
OS Platform OS Platform. (Currently Windows is the only supported platform)
OS System Path Path to the OS system files.

CPU Information

Field Description
CPU Name Name of the processor being used.
CPU Speed Processor speed. For example, a reading of 3392 indicates a processor speed of 3.4 GHz.
CPU Count Number of CPU cores on the system.
CPU Architecture CPU Architecture (e.g. x86).
CPU Identity Additional information that identifies the manufacturer of the processor.
CPU Revision Revision number of the processor.

Hard Disk Information

Field Description
HD Space Amount of hard disk space on the system (in kilobytes).
HD Space Available Amount of hard disk space currently available.
HD Type Hard Disk type (e.g. Fixed Disk).
HD File System Hard Disk file system type.  Currently NTFS is the only file system supported.
HD Volume Name Hard Disk volume name.

Memory Information

Field Description
Memory Total Amount of total RAM on the system
Memory Available Amount of RAM currently available.
Memory in Use Percentage of the total RAM that is currently in use.

Version Information
The Version Information area enables you to easily see the specific build of individual Prism applications and services.

System Information via REST API
Returns details about the host machine in same format as the current TTK.
Endpoint:
/api/common/systeminformation?cols=*,sysinfomodule.*

Services
In the Services area, you can start and stop services, view info about dependencies and change configuration settings. To stop or start services in Services Manager, you must have administrator privileges.
Select the Service Manager tab from the menu and select the desired service from the list.
Click the service you want to start, stop or configure. A set of buttons enable you to start or stop the service.
Click the gear icon to change configuration settings.
Sample Services tab:
TTK Services tab

Prism HealthCheck
The HealthCheck monitors Prism stability and integrity. It monitors Prism services and log files. Each of these monitoring processes can be turned off/on and configured in the PrismTechToolKit.ini file. All keys of the ini file can be updated from the UI. By default, the HealthCheck runs every 60 seconds; you can configure the interval. At the entry point of each run cycle, the HealthCheck monitor checks the config file to determine which monitoring checkpoints are turned on or off, as well as their settings. These settings are loaded dynamically each run cycle so there is no need to restart PrismTechToolKitService when there is a change.
The HealthCheck includes a Service Monitor and a System Monitor. These are turned off by default.
•    The Service Monitor, when enabled, checks Prism services' status every 60 seconds and restarts any Prism-related service that has stopped or did not start. If there is a Prism service you do not want the Monitor to restart, enter its exact name  (as shown in the ToolKit's Service Manager listing) in the "Service Monitor-Service Exclusions" edit box.
•    The System Monitor, when enabled, checks available memory, and other system attributes.
Service Monitor
The system continually checks that all Prism services, including Apache, the DB services, licensing, and RabbitMQ are not in a "STOPPED" status. If a service is stopped, the monitor starts the service, unless the Server Maintenance Flag is "ON" or the service is excluded from the Service Monitor.
Starting and Stopping the Service Monitor
PrismTechToolKitService and the HealthCheck only require the Prism DB service to be running to log in and start running. The HealthCheck and its Service Monitor start approximately 60 seconds after PrismTechToolKit service starts. Once logged in, the monitor can start all other services, including the DB service, if it stops, as well as Apache and PrismPOSV1Service.
Excluding a Service from Service Monitor
The Service Monitor uses separate threads for starting each service, enhancing performance. It is possible to specify services that the monitor should not try to start by adding the service name to PrismTechToolKit.ini config key SERVICE_MONITOR_EXCLUSIONS as a comma delimited string. Monitoring of services can be turned off. The Service Monitor is automatically turned off when ServiceManager sends a request to stop a service.
Log File Purge
The system monitors the accumulation of log files, once per day, and deletes log files older than days. is specified in the PrismTechToolKit.ini config file.
PrismTechToolkitService Health Check and Monitor Settings

Setting Description
HealthCheck Run Interval (Secs) The service will check Prism services' status every 60 seconds and restart any Prism-related services that have stopped or are not running.  Enter the number of seconds between each health check. Default = 60.
Service Monitor Enabled If selected, service monitoring is enabled. The service monitoring tasks include restarting services. Default = Disabled
Service Monitor Service Exclusions Enter the names of any Prism services that should be excluded from monitoring. By default, all services are monitored.
Service Monitor-Restart All Services If selected, all services are restarted automatically during a full Prism restart. Default = Enabled
System Monitor Enabled If selected, system monitoring is enabled. Default = Disabled

SSL
In the SSL area, install SSL certificates.
Browse to the location of the certificate file.
Browse to the location of the .pem file.
Click Update Prism Config.
TTK SSL tab

Special Steps for Proxy Only Machines
Machines that have only the Proxy installed (no Prism Server, no DRS) require special consideration.
1.    Install the certificate and the key files.
2.    Click Update Prism. A confirmation is displayed, explaining that Apache and RabbitMQ must be stopped and then restarted.
3.    Launch the Proxy using the desktop shortcut.
4.    You will be prompted to enter the domain name for the certificate. Enter your company's domain name. Click OK. (If you don't enter the domain name, the connection will be insecure.)

SSL Manager check of Prism Components
The SSL Manager will detect which Prism components are on the machine: Prism Server, RabbitMQ, and/or the Prism Proxy. This is especially important when the machine in question is a "Proxy only" machine.

  • If Prism Server is on the machine, the SSL Manager will modify the prism.conf file to apply the certificates.
  • If RabbitMQ is installed, the SSL Manager will modify the rabbitmq.config file.
  • If the Proxy is installed, the SSL Manager will apply the certificate file names to the Proxy.ini file.

Once the certificates are applied, the SSL Manager will alert the user to restart Apache or RabbitMQ as needed. If the proxy is being secured, that will also need a restart.
The CA cert is only required for configuring RabbitMQ. There is a RabbitMQ checkbox; if checked, this enables the CA Cert file to be applied. If unchecked, this field is disabled. If RabbitMQ is not installed, the checkbox and CA Cert fields are disabled automatically.

Scheduler
The Scheduler user interface in Tech Toolkit enables users to adjust the timing and other settings of the currently defined tasks. End users cannot add new tasks to Scheduler at this time other than by doing do from Prism, e.g., by creating a new Markdown. The main use for the Scheduler UI in Tech Toolkit, is to provide an easy way for users to adjust the settings of existing scheduled tasks such as time of day to run, interval/how often (daily, every other day), or to turn a task off.
Key Uses of Scheduler UI in Tech Toolkit

  • Adjust default settings of tasks to better match business hours, data loads, or other factors
  • Check the success or status of specific scheduled tasks
  • From time to time, delete once-only tasks that have successfully run

If a REST connection does not already exist, you will have to create one in Tech Toolkit Connection Manager. Select the REST connection in the Current Connection dropdown.
Click the Scheduler tab on the Tech Toolkit menu. You will see the list of defined tasks:
 
The Tech Toolkit Scheduler is a user interface to the Retail Pro PrismSchedulingService. The PrismSchedulingService is a Windows service that runs in the background and executes tasks defined in Scheduler. Tasks are API processes, technically termed "actions," which perform specific functions.
Existing Tasks in Scheduler

Task Description
Customer History Daily Process Generates Customer History records from POS transactions and customer orders. Repeats every 15 minutes.
Customer History Initialize Process This is a one-time operation set to run during the night after  the new CH feature is first installed. This process generates CH records from past transactions. After that, the CH Daily process is responsible for generating CH records as customer transactions are created.
Purge ScheduledTaskRun records This is a system housekeeping task that clears out past task run history records based on the value in DaysOfRunHistory field in each task record. A value of 0 means keep all task run records. A value greater than 0 means keep only the most recent days. All repeating tasks, should have an appropriate number of "keep" days otherwise the DB will be overloaded needlessly.
Update active season This task updates the Active Season, if needed, based on the date range for Seasons defined in Prism preferences. The Active Season is used for seasonal pricing and is displayed in Subsidiary and Store records.
Cleanup PI Sheet 1) PI Sheet results will show a 'Creation' status(to give info about creation of new PI Sheet only) column with these values : Completed, Failed, Pending(shows Spinner)
2) If there is pending PI Sheet to be created, that PI Sheet can't be selected in the grid and no further actions are possible unless the PI creation is completed or failed
3) Inactive PI Sheets can be deleted from UI, new 'Delete'  button is added to button bar. [Only Inactive PI Sheets can be deleted - Behind the scene deletion process is actually handled by the scheduler-TTK, in UI it just filters out PI Sheets which are marked for deletion]
4) If the new PI Sheet creation is failed then it would be made inactive and shows the PI result grid

View Task Information
Click a task in the list to display details about the task. Note: There are restrictions on what fields can be edited and which tasks can be deleted.

Task Parameters

Parameter Description
Start Date Day and time the task will start.
End Date Day and time the task will end, If null then no end date.
Start Time Start time for the time frame that the task can be run.
End Time End time for the time frame that the task can be run.
Active True if the task should be run currently. Inactive tasks will not be run.
Task Run Interval (Once Only, Daily, Weekly).
Recur Every Recur Every is based on Frequency, for instance if set to Daily and Recur Every is 1 the task will run every day, If set to 2 the task will run every other day.
Repeat Every (Min) Repeat every N Seconds or Minutes.
TimeOut(Secs) Number of seconds to wait for service to start. Default 60 seconds with a 0 meaning wait forever, -1 meaning do not wait at all, Positive integer is how many seconds to wait.
Days of Week (weekly tasks only) Seven-character string of 0s or one. specifying SMTWTFS with 0 being false and 1 being true.
Max Retries on Error  Tells the Scheduling service to set a task to not active if it throws consecutive errors. User can re-set task to active and execution cycle will attempt again. If Max Retries is null or zero, it is ignored by Scheduling service.
Days of Run History Tells the Scheduling service to keep only number of days of task run records for the task, with days being calculated from the current date. Therefore, this is intended only for those tasks that run on a continual cycle such as Customer History Daily Process. Default is 0, meaning keep all history. Positive number of days will define how many days of run history to keep.
Workstation Must be populated only for some tasks whose action requires a workstation "sit", such as Price Manager actions. Otherwise, can be left blank. However, if populated for a task that does not require it, the workstation populated must be valid otherwise the task will not run.
Action Url Action URL with parameters. This is the path to the resource in the Prism API and the type of action that will be performed
(e.g.  /api/common/?action=updateseason )
Note: You should not edit the Action URL.
Action Payload If required, a JSON CLOB for the request payload.
Note: You should not edit the Action Payload.
Task Edit/Delete Settings Default = OK Edit & Delete.
Task Type Code Four-character alpha-numeric free-form field to allow users to group or filter tasks. For example: PM for price manager, PMM for price manager markdown, or SYS for system. (Note: Currently grouping and filtering has not been implemented in the UI but will be in later release as more tasks get added to the Scheduler.)   
Public Flag Only Public schedules will be replicated. (Note: Currently not implemented)

Note: Adjust Customer History Daily Process for High Volume Environments
If you will be operating Prism in a high-volume environment in which all or most of the customers are defined customers in the database, special configuration is required to ensure that Customer History is processed more quickly than the default setting of once every 15 minutes. In a high-volume environment, when using the default Customer History settings, transactions will accumulate before the next processing. By setting the processing timer to a smaller value, e.g. two minutes or five minutes, customer history will be processed more quickly, preventing the build-up of unprocessed transactions.
•    High Volume POS transactions for Customer History purposes means transactions with customers that have an account. If half of the transactions are to customers without an account with the store, Customer History processing ignores those when fetching documents to process - so no impact on memory.
•    When setting RepeatEvery to a lower number, Days of Run History should be reduced to 2 or 3 so that Prism is not storing needless thousands of run history records.
•    These edits can also be made directly in the Scheduled Task grid.
•    Default Start and EndTimes should be tweaked per store business hours. Otherwise Customer History will run needlessly and create task run records.

Logs
Prism Tech Toolkit includes a built-in Log Viewer that makes it easy to review logs of system activity. Click the Logs tab on the top menu to access the Log Viewer.
A separate log in is required to view logs. The default username/password is "loguser/loguser". After successful login you will see a list of available log areas.
After viewing a log, to return to the log list click the arrow button.
 
Log Folder Authorization - Creating Users and Passwords
When opening the Web TTK, Log Files tool, the user is prompted to enter valid credentials created using the Apache password tool. After installing 1.14.7 release (or later), at least one password must be created to access the Logs folder from Web TTK. New users and passwords are created or updated using the Apache password tool, htpasswd:
https://httpd.apache.org/docs/2.4/programs/htpasswd.html
PrismLogging.ini
Log settings (for things like the number of days of logs to retain) are stored in the PrismLogging.ini file. The PrismLogging.ini file is found in …\ProgramData\RetailPro\Server\Conf). PrismLogging.ini has a [global] section and sections for each Prism service. The settings defined in the [global] section apply to all services by default. To override the default settings in the [global] section of the PrismLogging.ini file, edit the corresponding section for the service. The settings in the [global] section apply to all services unless a different setting is entered in the file for the individual service.
Changes to PrismLogging.ini are loaded dynamically. There is no need to restart the service. This applies to all Prism services; however, the PrismLicenseService and PrismResiliencyService only reload log settings, not other settings in the .ini file.
Override Global Settings
A service or app can override a global setting by creating its own section in the PrismLogging.ini file. This section or a setting in the section can be made at any time and the service will load it even when running. The section name must be the base name of the executable, case-insensitive, not the app's base INI filename. A change to a service's log setting in the Web client that is different from the global setting will automatically create a section for the service if it does not yet exist and add the key/value pair. If a change results in the same setting as the global setting, the service's current key will be removed if it exists.
[PrismMQ]
FORCELOGINFO=true
RetainXLogs=12
[PrismCommon]
LOGLEVEL=3
RetainXLogs=15
PrismLogging API
You can use API calls to retrieve logging information. Details about using the API are found in the Appendix.

Data Utilities - ZIP Code Injection
The Data Utilities - ZIP Code Injection area of Tech Toolkit is where you populate the database with the list of ZIP Codes defined in Admin Console > Node Preferences > System > General: ZIP Code Lookup.
The ZIP Code lookup feature enables a user to type in a ZIP Code for a customer or vendor address and Prism will fill in the City and State information. In Admin Console > Node Preferences > System > General, specify which address fields should be populated with the City and State information (e.g. Address 3).
Using ZIP Code lookup has several benefits:

  • Ensures addresses have correct address information. It is easier to correctly enter a five-digit ZIP Code than the city, state and zip.
  • Ensures state information is entered in a consistent format (e.g. California is entered as CA, instead of California, Calif., CAL or other variation).

Basic Steps for ZIP Code Lookup
1.    Enable the ZIP Code lookup in preferences.
2.    Use the Data Utilities - ZIP Code Injection feature in Tech Toolkit to populate the database with ZIP Code data (approximately two hours required; plan accordingly)
3.    When entering a customer or vendor address, you must enter complete postal codes 5 digits for US and 7 digits for Canada including the space.
Enable ZIP Code Lookup in Preferences
Navigate to Admin Console > Node Preferences > System > General.
Click the Enable Postal Code Lookup checkbox.
In the City dropdown, select the Address field where the City information will be written.
In the State dropdown, select the field where the State information will be written.
In the State Format dropdown, select Full or Abbreviated. Save the changes.

Populate the database with ZIP Code data
Populating the database with ZIP Code data takes one to two hours. Plan accordingly.
Before you can run the Data Utilities tool to populate the database with ZIP Code data, you need a database connection (not a REST connection). Add a new connection or edit an existing connection so that the Type field is set to "Database."
Launch the Prism Technician's Toolkit.
Select Data Utilities > ZIP Code Injection. ZIP Code Injection will take between 1 and 2 hours depending on several factors. Once completed there is a message dialog indicating the data has been injected.
Postal Code Lookup at POS
Start a new customer (or vendor) record or edit an existing record. Customers and vendors can have multiple addresses. Add a new address or edit an existing address.
In the Postal Code field, enter a complete five-digit ZIP Code for the U.S. or seven-digit code for Canada. Navigate out of the Postal Code field. The City and State information is automatically entered in the field(s) specified in preferences. During address creation/edit, if the entered ZIP Code matches a specific City and State and then the user edits the City/State values to differ from the automatically populated values, the manually entered values take precedent. In some cases, a single postal code will match multiple locales. If that happens, a list of the matching results is displayed so the user can select the desired locale to use to populate the City and State info.

Data Utilities - SRO Tool
The Prism SRO tool enables you to update sold, received, and order totals for items, vendors, or departments. This provides a clearer picture of Company On-Hand and Store On-Hand quantities. Running SRO on a regular basis helps managers and other key personnel make better decisions about replenishing inventory and avoiding stockouts. For example, if after running SRO, the retailer sees that several quantities of an item are due in on a transfer, then a new order may be unneeded.
You can run SRO at any time to update sold, received, on order and in-transit totals for any single:

  • Inventory Item
  • Department
  • Vendor

You choose which documents to include when running SRO: Receipts, Vouchers, Purchase Orders and/or ASNs. You also define the date range to consider for each document type.
SRO can be run as a one-time manual operation and/or as a scheduled task.
Why is SRO necessary?
Items are constantly being sold, received, transferred, etc., throughout the enterprise. As a result, the store on-hand and company on-hand quantities that a user sees may be different than the "true" OH Qty when taking all documents into account. Running the SRO utility gives retailers the most accurate snapshot of Inventory.

Basic Steps for SRO
Navigate to Technician's Toolkit and log in. To navigate to Technician's Toolkit, append /TTK to the Prism server address:
http://myserver.myco.com/TTK
Select Data Utilities > SRO Tool
Define one or more presets that include the documents and date ranges you want to analyze.
Schedule the preset to run at certain times or run it immediately.
View the results. The results are viewed in the following database tables:
SBS_INVN_ITEM_QTY (SOLD_QTY, RCVD_QTY, ON_ORDERED_QTY)
DOCUMENT (SOLD_QTY, ORDER_QTY)
In each table, the following values are updated: ORDER_QTY, SOLD_QTY and RCVD_QTY
Permissions
You can control employee access to the SRO tool using the following permissions:

Permission Description
Tech Toolkit - Configure SRO Analysis Allows user to edit SRO configuration.
Tech Toolkit - Run SRO Analysis Allows user to perform SRO analysis.


Access SRO
Navigate to Technician's Toolkit and log in. To navigate to Technician's Toolkit, append /TTK to the Prism server address:
http://myserver.myco.com/TTK
Once you are logged in, click Data Utilities on the top menu and then select SRO Tool.
The SRO Tool user interface enables you select the subsidiaries, stores, document types and date ranges to include in the report. The table that follows has a brief description of the UI elements.

SRO Tool User Interface

SRO Tool UI Element Description
Load Preset  Select a predefined preset or click New Preset to create a new preset on the fly.
Preset Name Enter the name of the preset. Maximum 75 characters.
Select SBS/STore The SRO analysis can be limited to specific subsidiaries/stores. Click the pencil icon to display a list of available subsidiaries/stores
Receipts Click the Receipts checkbox to include receipts in the analysis. Including Receipts in the analysis updates the SOLD_QTY value in the database.
Vouchers Click the Vouchers checkbox to include vouchers in the analysis. When you click the checkbox, the Date Range element becomes active, enabling you to define a date range for the analysis. Only purchase orders created within the date range will be included. Including vouchers in the analysis updates the RCVD_QTY value in the database.
For Advanced Shipping Notices (ASNs), you have the option of using the Arrival Date instead of the Created Date. By default, the Arrival Date on an ASN is the same as the Created Date; however, it can be changed. For example, say an ASN is generated from a PO. The retailer's relationship with the vendor calls for once-a-month deliveries on the final day of the month. In this type of situation, using the Arrival Date can lead to more accurate results.
SRO tool document date range options:
PO on Order

Click the checkbox to include purchase orders in the analysis. Including purchase orders in the analysis updates the ON_ORDERED_QTY value in the database.
If you select Use Order Date, the analysis for PO will be based on the PO order date rather than the created date.

Date Range You can define a separate date range for each document type. The analysis is limited to documents created within the specified date range.


Presets for SRO
Presets are a way of simplifying and speeding up the process of running SRO. Instead of redefining the same set of criteria each time, presets enable you to define the documents and date ranges to include and save the settings as a group. When it comes time to run the report, simply load the desired preset.
You can create as many presets as needed ahead of time or create a new preset on the fly when running the SRO report.
When a preset is selected, it will repopulate the SRO fields with the preset's settings. SRO can only be run for a saved preset, so if creating a preset on the fly, you will have to save it first before you can run the tool.
Once the needed presets are defined, a user just selects the desired preset when running the tool. Users with the required permission can edit presets if needed.
Preset Name is a required field to give a name to the SRO analysis that is about to be created.

Dynamic Date Options
The SRO tool is meant to be run on a subset of the document history.
Each SRO Date Range has two components:

  • Start point: The point from which the duration will start.
  • Duration: The Duration is relative to the Start Point.

Examples

  • Four weeks starting five weeks ago: Four weeks' worth of data will be shown, starting five weeks previous. This means data for the current week is not included.
  • One week starting one week ago: Updates SRO by analyzing the last seven days' worth of documents. Note: This could also be achieved by select a Date Range of Seven Days starting Seven Days Ago.
  • Today: For example, run multiple times throughout the day to keep totals updated.
  • Yesterday: For example, run the SRO in the morning, and select Yesterday for the Dynamic Date.

When adding/editing a preset, you define a date range for each included document type. You can select a manual date range or select one of the predefined dynamic date options.

Date Range Options

Date Range option Description
Specific range Enter specific Start and End dates
n day(s), starting n days ago Duration of days starting X days ago.
n week(s), starting n weeks ago Duration of weeks starting X weeks ago
n month(s), starting n months ago Duration of months starting X months ago.
Today The word Today is inserted, and the date is the current date
Yesterday The word Yesterday is inserted, and the date is the date prior to today
WTD (first of week to today) Date from the previous Sunday as the start date and only includes the dates to the current date. (make sure it does not include the whole week.)
MTD (first of month to today) Begins with the 1st day of the month and only include the dates up to the current date. (Make sure it does not include the whole month)
YTD (first of year to today)  Begins with January 1st and only include dates up to current date. (make sure it does not include the whole months date unless current date is the EOM.)
  Includes the number of days specified starting with the date selected.
N Days from n  

New SRO Report
Users will typically schedule the SRO tool to run on a regularly scheduled basis; however, you can run the SRO tool at any time.
Navigate to Tech Toolkit > Data Utilities > SRO Tool
Click the dropdown and load the desired preset. Alternatively, click New Preset to create a new preset.
When you load a preset, the Subsidiaries, Stores, Documents and Document ranges defined in the preset are entered on the new report. To select different individual stores, click the pencil icon next to "Select SBS/Store."The documents selected as part of the preset are shown below the store selection.
Click the run button.
The user will not see any indication that anything has happened; however, behind the scenes the following values are updated in the database. These values can be viewed using a tool like PLSQL Developer.
Scheduling SRO
After the user saves the preset the user can select the SCHEDULE button to transfer the preset to the scheduler module and complete the editing of the record that is required to run the task.
Task Scheduler user will complete the task by entering the Days to be ran, frequency and any other required field.
User will be able to run the task. Check the history of the task to verify it ran. Delete the task from scheduler.Launch the SRO Tool.
Select the desired preset
Click the Scheduler button.
Clicking the button opens the Scheduler module.
The task is added to the list of tasks.

Viewing SRO Task Run
Once the task has been scheduled, you can launch it from the list of scheduled tasks.
Navigate to the Scheduler area of TTK. A list is displayed of the tasks being run by Scheduler, including any defined presets.
In the list, click the preset you defined.
When you click the task, A UI for working with the task is displayed.
Scroll down to the buttons at the bottom of the task. The Task Run History is displayed.
Click the ‘X' to close the dialog.

Enterprise Management
The left side of the Technician's Toolkit main screen displays the servers in the enterprise in a hierarchical format. The Technician's Toolkit includes functionality for adding and removing servers from the enterprise hierarchy. The process of adding servers to the enterprise is also referred to as joining the enterprise.
Detailed information can be found in the Prism Getting Started Guide and Prism Enterprise and Connection Manager.
The following table briefly summarizes the server menu tasks available in Technician's Toolkit:

Task Notes
Add Subordinate server to... This task enables a server to join the enterprise. At the POA, select Add Subordinate Server To and then enter the new server's details.
Add former server to ... This task enables a server to rejoin the enterprise if it left the enterprise or was removed.
Remove subordinate server    Forcibly remove a server from the enterprise. Special steps are required to safely remove a subordinate server. See the Prism Enterprise and Connection Manager document.
Export Identity Export the server identity file. The server identity file is required when reinstalling Prism, should that become necessary.
Rename Server Perform necessary reconfiguration when a Prism server has had its named changed in Windows System Properties.

Enterprise Manager API
This section describes the POST requests to invoke Enterprise Manager functionality. All Enterprise Manager processes, except Export Identity Script, are protected by Locks to guard against two instances of the web client simultaneously performing Enterprise Manager actions on the same Prism server.
Export Identity Script
Endpoint: http:///api/techtoolkit/?action=exportidentity
{
  "data" : [
    {
      "oracle" : true,
      "mysql" : false,
      "controllersid" : "452650935000052000",
      "exportfile" : " Prism_Oracle_IDScript.sql"
    }
  ]
}

 

The api requires a base filename (no file extension) in the payload and the active Controller's sid. The api generates the sql script file and places it in a download folder (location & name TBD) and returns a response payload with the HTTP link where the file can be downloaded by the user or opened it in a text editor of choice.
Join the Enterprise
Endpoint: http:///api/techtoolkit/?action= joinenterprise
Webclient should require user to first test the connection to the POA before attempting to join. There are several reasons a connection can fail (see below) and, in some cases, the response payload will provide user options to accept the reason for the failure and proceed anyway. The webclient will need to present the the user with the appropriate choices based on the payload response. For this reason, it is more manageable for the webclient to deal with the testconnection step first.
However, as a safeguard, a request to join without a preceding test request will still cause the api to run the testing process first and reject the "join" if test fails.
Example payload for the initial request to test the connection with the POA:
{
  "data" : [
    {
      "poaserveraddress" : "xx-ora-em64",
      "poausername" : "adminuser",
      "poapassword" : "adminpassword",
      "usessl" : false,
      "testconnectiononly" : true  
    }                                     
  ]                                                                                                                        
}
Testconnection failure reasons include:
•    POA offline
•    Unable to log into POA
•    Different Prism server versions between POA and local Prism
•    Duplicate controller records - User can accept this, Join can be allowed if user indicates in response to test/join failure that local Prism "claims" the duplicate.
•    Conflicts exist - POA and local have some of the same subsidiaries, store records, etc. - User can accept this, Join can be allowed if user indicates in response to test/join failure if user accepts the conflicts, meaning POA data will overwrite the local Prism where conflicts exist.
•    ReversInitialization Required - User can accept this, Join can be allowed if user indicates in response to test/join failure that user accepts the conflicts, meaning POA
Payload to join is same as above with "testconnectiononly": true. If there were testconnection issues that user accepted in order to join, the following payload indicates additional properties (red color) that can be included to proceed with a join.
{
  "data" : [
    {
      "poaserveraddress" : "xx-ora-em64",
      "poausername" : "adminuser",
      "poapassword" : "adminpw",
      "usessl" : false,
      "testconnectiononly" : false,  
      "ClaimsDuplicateController" : true,
      "AcceptsConflictsList" : true,
      "AcceptsReverseInit" : true
    }                                     
  ]                                                                                                                        
}

Leave the Enterprise
Endpoint: http:// /api/techtoolkit/?action=leaveenterprise
{
  "data" : [
    {
      "poaserveraddress" : "panda-em64",
      "poausername" : "adminuser",
      "poapassword" : "adminpw",
      "usessl" : false,
      "AllowLeaveIfPOANotConnected" : false
    }
  ]
}
Remove Subordinate
POA can only remove an immediate subordinate if the subordinate is offline. When subordinate is removed all Prism/controllers that are child and siblings and children thereof are also removed.
Endpoint: http:// /api/techtoolkit/?action= removesubordinateprism
{
  "data" : [
    {
      "poaserveraddress" : "xx-ora-em64",
      "poausername" : "adminuser",
      "poapassword" : "adminpw",
      "usessl" : false,
      "subordinatecontrollersid" : "502165604000020255"
    }                                     
  ]                                                                                                                        
}

PrismLogging API
This section has information about specific tasks that can be done using the PrismLogging API.
Specifying Alternate Log Folder
Note: The feature described here is only intended for use in certain specific situations and should only need to be used once or twice at a Prism installation.
To implement this feature, the WebClient makes a PUT request with the path to the alternate log folder as shown in the API sample above. The folder specified in the path does not have to already exist. The API will validate that the folder can be created and then write to it. The API will reject any attempt to write to the root directory or a path that includes the Retail Pro app data path. The latter are reserved for Retail Pro default data paths.
The API will update prismimage.conf as well as PrismLogging.ini and restart Apache to apply the configuration changes.
Apply Log Folder Change during Maintenance Window
If you specify an Alternate Log Folder, do it during non-business hours. Restart all Prism services or reboot the machine after executing the change. The other Prism services will only recognize the log folder change when they are restarted. The log folder change affects Prism services' logging, including the WebModule, but not RabbitMQ or the DB services. So the latter do not need to be restarted.
Revert to Default Log Folder
To revert to the Prism default Log Folder, send an empty string as the value or send "${programdata}/RetailPro/Server/Logs". The api will enter this same value if empty string is sent.
Notes about API updates of PrismLogging.ini
    Review the settings in the PrismLogging.ini file before AND after making changes to the log settings from the API.
    If a log setting change that is requested for a service is different from the exiting [global] keyvalue for the setting, the setting is placed in a section for that service (identified by the base name of the binary). If the section or key does not exist it is created.
    If a log setting change is the same as the [global] value and the service has an existing setting in its section PrismLogging.ini, the key is removed since the global value can now be used by the Logger. This minimizes clutter and redundancy in the .ini file as there are numerous apps and services that will use the Logger.

 

Log Entry Types
The following table lists the available log entry types:
Type    Description
ltError    Error. Used to log errors and error related information. Developers should be using ltError in TRY>EXCEPT blocks.
ltWarn    Warning. Used to log warnings or irregular flow control.
ltInfo    Information. Used to log information NOT related to other entry types. Developers should use this to log additional information. This entry type should be used the least.
ltFlow    Flow. Used to log flow control markers in the code execution. Developers should use this to track the flow of code execution through blocks of code that are NOT the normal path. This should not be used to track every If/Case/Repeat/Do operation. Care should be used inside of high performance loops to not bog down the execution. Instead log before and after and use ltDebug for the inside of the loop.
ltEntry    Entry Point. Used to track the entry point in a method. Developers should use this as the first line in each method.
ltExit    Exit Point. Used to track the exit point of a method
Developers should wrap the method in a "try" block and this should be in the final section.
ltDebug    Debug Used to provide additional debug information at runtime. Remove once a problem has been debugged.

Log Levels
The following logging levels are supported.
Log Level    Description
None = 0    No log entries will be written and the log file will not exist
Minimal = 1    ltError only
Normal = 2    ltError and ltWarn
Verbose = 3    ltError, ltWarn, ltInfo, ltFlow, ltEntry and ltExit
Debug =4    ltError, ltWarn, ltInfo, ltFlow, ltEntry, ltExit and ltDebug

StartLogSession()
procedure StartLogSession(const AAppLogFileName: string; ALogIsSegmented: boolean = true; AAppLogDir: string = '');
Parameter    Description
AAppLogFileName    (Required) This is typically the base name of the binary although some services and apps have chosen to use a slightly different name for the log file.
ALogIsSegmented    ALogIsSegmented should be true unless for some reason the intent is to use only one file for logging with no rollover based on size or date change.
AAppLogDir    AAppLogDir should only be used when the app does not have access to the server\logs folder or there is a special need. Two examples:
    Prism installers logging the DB scripts need to write to the Documents folder because in a fresh install the RP server\logs folder does not exist.
    PrismProxy (when it is converted to use the new logger) may need an alternate logs folder when it is running on a different machine than the Prism server. For 1.14.7 release PrismProxy will continue using the prior Logger.

Log Method Call Syntax
Logger.Log( ‘The message', TlogEntryType);
Example: Logger.Log(‘Some information', ltInfo);

LogFile Virtual Resource
LogFile is now a virtual resource. The LogFile properties match the data elements returned in the Win32 TechToolKit, except LogFileEndpoint, which has been added.
property LogFileName: Nullable read FLogFileName write FLogFileName;
property LogFileType: Nullable read FLogFileType write FLogFileType;
property LogFileDate: Nullable read FLogFileDate write FLogFileDate;
property LogFileSize: Nullable read FLogFileSize write FLogFileSize;
property ErrorCount: Nullable read FErrorCount write FErrorCount;
property LogFilePath: Nullable read FLogFilePath write FLogFilePath;
property LogFileEndpoint: Nullable read FLogFileEndpoint write FLogFileEndpoint;
The names can be changed. For example, you might prefer to remove the "Log" prefix as redundant:
GET Endpoint:
http:///api/techtoolkit/logfile
Returns a listing of all Prism-related log files with the sample info shown below.
"logfilename" : "PrismPOSV1AsService_190905_120515615.log",
"logfiletype" : "PrismPOSV1",
"logfiledate" : "2019-09-05T17:41:05.582-07:00",
"logfilesize" : "20744",
"errorcount" : "0",
"logfilepath" : "C:\\ProgramData\\RetailPro\\Server\\Logs\\PrismPOSV1AsService_190905_120515615.log",
"logfileendpoint" : null
Setting Filters
Filter by LogFile Type to return a payload with only the specified log file type:
Example Request:
http:///api/techtoolkit/logfile?filter=logfiletype,eq,prismcommon
Filter by LogFile Date
Currently only used to include log files with a date greater than or equal to the specified date. The api uses the date value, starting at midnight for that date. Therefore passing only a date value in the yyyy-mm-dd format will also work.
Example Request:
http:///api/techtoolkit/logfile?filter=logfiledate,ge,2019-09-01T07:00:01.886Z
Filter by LogFiles with Errors to return a list containing only log files that have errors:
Example Request:
http:///api/techtoolkit/logfile?filter=(errorcount,ge,1)
Multiple Filters
Example Request:
http:///api/techtoolkit/logfile?filter=(logfiletype,eq,PrismPOSV1)AND(errorcount,ge,1)AND(logfiledate,ge,2019-02-01T17:41:05.582-07:00)
Log File Types the api returns
(Note: These are also the values that populate the LogFileType property in the payload.)
The webclient should use these values when setting filters by logfiletype: PrismBackOffice, PrismCommon, RPSRestServiceModule, LicenseServer, PrismMQService, PrismScheduling, TechToolKit, PrismV9, EFTServiceModule, PrismResiliencyServer, PrismPOSV1, PrismWebModule, PubSubService, V9DRSPubSub, PrismProxy, HardwareServices, JTEInstaller

Opening a specific log file
To open a specific log file, select the file from the list that is currently displayed in the UI and click the Open or Download button. The GET request will set the log filename in the filter as follows:
http:///techtoolkit/logfile?filter=(logfilename,eq,PrismTechToolKitAsService_190916_154037697.log)
The api will copy the requested file to a new folder and return a payload with the http link where the user can download the file or open it in their editor of choice.
SSL Manager API
SSL Manager
SSLApply implements an SSL certificate. SSLRevert reverts SSL to unsecured. The actions affect the Prism Server and Prism Proxy. The SSL cert and key file must be generated first, using an available SSL tool, such as OpenSSL.
Applying SSL
Endpoint: /api/techtoolkit/?action=sslapply  
Payload:
{
  "data" : [
    {
      "certfile" : "C:\\ProgramData\\RetailPro\\Cert\\hostname.crt",
      "keyfile" : "C:\\ProgramData\\RetailPro\\Cert\\hostname.key"
    }
  ]
}
Revert to Unsecured
Endpoint: /api/techtoolkit/?action=sslrevert
There is no payload to revert an SSL certificate.

Service API
ServiceManager Notes

Currently, the api prevents stopping, i.e., shutting down, the following services, either independently or as part of a Prism RPC call:

  • PrismTechToolKitService - if stopped, neither the TTK webclient or the service can function.
  • PrismPOSV1Service - if stopped, webclient requests will not have access to the auth service and would be unusable
  • Apache - if stopped, webclient requests will not have access to the auth service and would be unusable

A TCriticalSection lock is applied before processing any request to change the state of a service. This protects against the possibility of more than one webclient instance on the same server attempting to operate on the host at the same time.
Prism Config File Updates
Prism configuration files are in the format of .ini files and reside on the Prism server's hard disk. Key values may be updated by Prism Admin users when needed but keys may not be added.
The api supports:

  • Single File Update - Update the settings for any or all keys of a single config file.
  • Global Config Updates - Update specified keys of all config files on local Prism Server.

Only existing keys will be updated by the api. If a key and value are passed to the api that does not exist in the config file, the update will be ignored for that key. The api will not add the key to the config file.
PUT Requests to Update Config Files
To enable PUT requests on configuration files, a generic configuration file virtual resource has been created. The generic virtual resource can handle all sections, keys, and values whether new or removed or renamed - without having to change virtual models or code base.
PUT Endpoint for single or global config update requests:
/api/techtoolkit/prismconfig

Example Payload to Update PrismScheduling.ini
{
"data" : [
{
"configname" : "PrismScheduling.ini",
"configkeys" : [
{
"section" : "log",
"keyname" : "loglevel",
"keyvalue" : "3"
},
{
"section" : "Scheduler",
"keyname" : "enabled",
"keyvalue" : "true"
},
{
"section" : "Scheduler",
"keyname" : "MAXALLOWEDTASKS",
"keyvalue" : "15"
},
{
"section" : "SERVICE",
"keyname" : "RECVTHREADCNT",
"keyvalue" : "6"
}  ]
}
]
}
Payload Notes

  • The sequence of sections or keys can be in any order.
  • Only include keys being changed
  • If the section & key in the payload does not exist it will be ignored
  • All values in the payload are strings.
  • Webclient does not need to specify the datatype
  • Sections, keys and values are case-insensitive.
  • Username, Password, and HostName may not be changed. If an invalid keyname is included in the request, the api will raise an exception with message to webclient noting the invalid keyname.

A typical update payload, changing LOGLEVEL for BackOffice:
{
      "data": [
                {
                  "configname": "PrismBackOfficeService.ini",
                  "configdata": [
                 {
                    "section"  : "Log",
                    "keyname"  : "LOGLEVEL",
                    "keyvalue" : "2"
                }
            ]
         }
    ]
}
Global config updates payload
Set the configname to the "prism".
Global updates are limited to:

  • All Logging keys
  • RECEIVETIMEOUTSECONDS
  • RECVTHREADCNT
  • RECONNECTDELAY

If any other key is included in the request, the api will raise an exception with a message to webclient noting the invalid keyname.
{
    "data": [
        {
            "configname": "prism",
            "configdata": [
            {
              "section"  : "GENERAL",
              "keyname"  : "RECEIVETIMEOUTSECONDS",
              "keyvalue" : "8"
            },
            {
              "section"  : "GENERAL",                                            
              "keyname"  : "RECONNECTDELAY",
              "keyvalue" : "6"
            },           
            {
              "section"  : "LOG",
              "keyname"  : "LOGLEVEL",
              "keyvalue" : "2"
            },     
            {
              "section" : "SERVICE",
              "keyname"  : "RECVTHREADCNT",
              "keyvalue" : "7"
            }    
            ]
        }
    ]
}

Scheduler

CRUD URI for ScheduledTask resource is :
http///api/scheduling/scheduledtask
Notes:

  • In webclient, ScheduledTask records are sorted by Taskname property.
  • Child ScheduledTaskRun records are never added, edited, or deleted by the UI and are excluded from any update requests.
  • ScheduledTaskRun has foreign key on ScheduledTask_Sid column that links it to the parent's Sid.
  • ScheduledTaskRun records are grouped by ScheduledTaskSid property and sorted by CreatedDateTime desc

Rename Prism Server Computer Tool
Endpoint: /api/techtoolkit/?action= renameservercomputer
Step 1 Example Payload:
{
"data" : [
   {
      "currentcomputername" : "xxx-ora-em64",
      "currentfullcomputername" : "xxx-ora-em64.retailpro.com",
      "newcomputername" : "yyy-ora-em64",
      "newfullcomputername" : "yyy-ora-em64.retailpro.com",
      "osusername" : "dev",      
      "databasetype" : "oracle",
      "renameprocessstep" : 1,
      "newfullcomputernameyuppercase" : false,
  }
]
}


Scaling a Service (future release)
Scaling refers to adding instances of a service. Scaling of Prism services is currently disabled; however, the capability is included in the api. The switch to disable scaling is controlled by a Boolean key in the PrismTechToolKit.ini file: SCALESERVICE_ENABLED (default = False). When scaling is disabled, an RPC call to scale a service will return an exception with a message that "Scaling of services is currently not permitted".
Services that can be scaled
When scaling is enabled, only services are identified as scaleable can be scaled, which currently are:

  • PrismPOSV1Service
  • PrismCommonService
  • PrismBackOfficeService

A request to scale a non-scaleable service returns error message that "Scaling is not supported for service ".
Scale service endpoint: /api/techtoolkit/?action= scalewinservice
Payload to add two instances to the current one instance of PrismBackOfficeService:
{
  "data" : [
    {
      "servicename" : "PrismBackOfficeService",
      ''scaledto": 3
    }
  ]
}
Webclient ScaledTo Notes
A service that is not scaled will have a "scaledto" property value of 1. This is assigned by the Windows OS and represents one instance of the service.
When sending a request to either increase or decrease, the scaledto value sent by the webclient should be the total number of desired instances of the service. For example, to reduce scaling from an existing 3 to 1, assign 1 to the scaledto property.
To automatically determine the scaledto # to send to the server, the webclient can simply add or subtract the appropriate number of instances to/from the service's existing scaledto value which the webclient has access to from the GET response payload.

Starting and Stopping Scaled Service Instances
When the computer boots, Windows OS automatically starts a service's scaled instances if they are set to start "Automatic" or "Automatic (delayed)", as displayed in the Services console. If the primary instance of a service that is scaled is stopped using the Services console, Windows will stop all instances. Programatically starting or stopping the primary instance of a service that is scaled, does not automatically start or stop the state of the scaled instances. However, the api has added code to replicate the behavior of the Windows OS handling of scaled instances. That is, starting or stopping the primary instance will also be applied to the scaled instances.