POSitouch Configuration Guide
Summary
This document describes the various configuration parameters for the Sparkfly integration to the POSitouch POS system. There are two main configuration files:
| file | system | location | purpose |
|---|---|---|---|
| gateway.ini | BOH | C:\Sparkfly\Gateway\gateway.ini |
Contains configuration for the Sparkfly POSitouch Gateway. This is the main configuration file for our POSitouch integration. |
| agent.ini | FOH | C:\Sparkfly\Agent\agent.ini |
Contains minimal configuration for the Sparkfly POSitouch Agent, if needed. Mainly used if FOH terminal software is not located in C:\SC. |
Each file is described in detail in the following sections.
Gateway Configuration (gateway.ini)
[logging]
The logging section primarily deals with the log files produced by the Sparkfly POSitouch Gateway.
| key | type | description |
|---|---|---|
| maxLogLevel | enum | the maximum log verbosity. Default is 'info'. Levels are (in increasing verbosity): error, warn, info, debug |
| logRetentionDays | number | the number of days to retain logs for. Default is 10 days. |
[general]
The general section deals with settings that affect basic behavior of the Sparkfly POSitouch gateway.
| key | type | description |
|---|---|---|
| listenPort | number | This is the port the gateway will listen on. Default is 7100. The terminal configuration must match this. |
| keyboard | enum | type of keyboard to use when accepting codes from the user program. Valid values are: qwerty, numeric, aloha |
| hideCredentialIdentifier | boolean | If set to true, credential identifiers (e.g. member identifiers, coupon codes) will use the hiddenMemo memo, which should be configured to not print on the receipt. |
| purgeCredentialsOnMerge | boolean | If set to true, credentials will be purged following a check merge action. Defaults to true. |
| maxOfferSelect | number | Limits the number of offers that can be selected in the offer selection dialog box.
|
[sparkfly]
The sparkfly section deals with settings that are related to configuration at Sparkfly, such as API credentials and unique site identifiers.
| key | type | description |
|---|---|---|
| siteId | string | The site ID for this location. Unique by store. This key or siteIdPrefix must be specified. |
| siteIdPrefix | string | The site ID prefix to use. If specified, siteId should not be provided. The site ID will be constructed dynamically by combining the POSitouch Store Number with the siteIdPrefix. Using siteIdPrefix is the preferred method and should be chosen when possible. |
| apiUsername | string | Sparkfly platform API user provided by Sparkfly. |
| apiPassword | string | Sparkfly platform API password provided by Sparkfly. |
| apiEndpoint | string | Sparkfly platform API endpoint to use when making requests. For staging: https://posapi-staging.sparkfly.com For production: https://posapi.sparkfly.com |
| apiTimeout | number | Timeout to use when making requests to the Sparkfly cloud platform. The value is specified in milliseconds and defaults to 10000 (10 seconds) |
[positouchItems]
The positouchItems section deals with item configuration inside of POSitouch. The Sparkfly POSitouch Gateway uses this information when creating items on the check. The items referenced in this section are created during the install process.
Keys in this section may have values taking the form of "x,y" if referencing a screen/cell or "x" if referencing an item via PLU#. For exmaple, the value 100 will be interpreted as "POSitouch inventory item #100", whereas "20,1" will be intepreted as "POSitouch screen #20, cell #1".
NOTE: Sparkfly recommends using the "screen number/cell number" method of referencing items, as it is the least error prone.
| key | type | description |
|---|---|---|
| mainItem | string | the screen/cell or plu# number of the 0$ item used to place the Sparkfly item on the check. |
| memo | string | the screen/cell or plu# number of the memo modifier to be applied to the 0$ item. This will be used to display the member's identifier, and to display offer names. |
| hiddenMemo | string | the screen/cell or plu# number of the memo modifier to be applied to the 0$ item. This will be used to store hidden data that is only shown to the POS users, and not printed on the check. |
[positouchXml]
The positouchXml section deals with the XML I/O feature of POSitouch. The directories referenced in this section are created during the install process, and should align with the values in the virtual printers defined in Restaurant Misc. Data → XML I/O.
The recommended pattern is laid out in the installation guide, but the basic pattern is C:\SC\XML\SPARKFLY_IN for XML service inputs and C:\SC\XML\SPARKFLY_OUT for XML service outputs. The exception to this rule is for the XML Ordering interface which should use different input and output directories such as C:\SC\XML\SPARKFLY_ORDERIN and C:\SC\XML\SPARKFLY_ORDEROUT respectively.
| key | type | description |
|---|---|---|
| xmlServicesIn | string | Corresponds with XML Services/Input Folder in POSitouch. |
| xmlOrderingIn | string | Corresponds with XML Ordering/Input Folder in POSitouch. |
| xmlOrderingOut | string | Corresponds with XML Ordering/Output Folder in POSitouch. |
| xmlOpenChecksIn | string | Corresponds with Open Checks Request/Input Folder in POSitouch. |
| xmlOpenChecksOut | string | Corresponds with Open Checks Request/Output Folder in POSitouch. |
| xmlSendOrderOut | string | Corresponds with Send Order/Output Folder in POSitouch. |
| xmlCloseCheckOut | string | Corresponds with Close Check/Output Folder in POSitouch. |
| xmlCheckUpdateOut | string | Corresponds with Check Update/Output Folder in POSitouch. |
| xmlCanceledCheckOut | string | Corresponds with Canceled Check/Output Folder in POSitouch. |
| xmlUserProgramsOut | string | Corresponds with User Programs/Output Folder in POSitouch. |
| xmlPrintOut | string | Corresponds with Print Checks/Output Folder in POSitouch. |
[acl]
This section contains ACL configuration. Each key represents a feature function within the menus presented on the terminal. If no value is specified, the ACL is not enforced and all users will have access to the feature. Multiple user types can be specified by using a comma.
Example (allow all users to access):
nonTxActivateMember = any
Example (allow user type server to access):
nonTxActivateMember = server
Example (allow user type server and manager to access):
nonTxActivateMember = server, manager
Example (disable button entirely):
nonTxActivateMember = none
NOTE: giving access to a lower tier user (e.g. SERVER) will not automatically grant access to the higher type (MANAGER). If all user types must have access, they should all be specified.
| key | type | description |
|---|---|---|
| nonTxMemberReport | acl | The user types allowed to use the 'Member Report' button outside of a transaction |
| nonTxActivateMember | acl | The user types allowed to use the 'Activate Member' button outside of a transaction |
| txAssignMember | acl | The user types allowed to use the 'Assign Member' button inside of a transaction |
| txUnassignMember | acl | The user types allowed to use the 'Unassign Member' button inside of a transaction |
| txMemberReport | acl | The user types allowed to use the 'Member Report' button inside of a transaction |
| txPickRewards | acl | The user types allowed to use the 'Pick Rewards' button inside of a transaction |
[localization]
Configuration in this section allows the changing of normally hard-coded UI labels and buttons. If no configuration is provided, English defaults are used.
| key | type | description |
|---|---|---|
| assignMemberButton | string | the text to be displayed on the "Assign Member" button |
| pickRewardsButton | string | the text to be displayed on the "Pick Rewards" button |
| printMemberReportButton | string | the text to be displayed on the "Print Member Report" button |
| unassignMemberButton | string | the text to be displayed on the "Unassign Member" button |
| activateMemberButton | string | the text displayed on the "Activate Member" button |
Agent Configuration (agent.ini)
[logging]
The logging section deals with the log files produced by the Sparkfly POSitouch Agent.
| key | type | description |
|---|---|---|
| maxLogLevel | enum | the maximum log verbosity. Default is 'info'. Levels are (in increasing verbosity): error, warn, info, debug |
| logRetentionDays | number | the number of days to retain logs for. Default is 10 days. |
[positouch]
The positouch section provides configuration for locating and interacting with POSitouch. There is only one setting, and it tells the agent where it can locate WINTERM.INI. The agent will load that file and use the data inside to locate the POSitouch BOH. Once a connection to the BOH is established, the remainder of the configuration will be loaded from the Sparkfly POSitouch Gateway. This is why the majority of configuration is located in gateway.ini, which reduces the amount of configuration that must exist on FOH terminals.
| key | type | description |
|---|---|---|
| wintermIniPath | string | Path to the WINTERM.INI on the terminal this agent is running on. Defaults to C:\SC\WINTERM.INI |
[general]
The general section provides configuration for base functionality of the agent.
| key | type | description |
|---|---|---|
| serverPort | number | The port number to use when communicating with the Sparkfly POSitouch Gateway service. This should match the value of listenPort in the gateway.ini file. Defaults to 7100. |