Aloha Configuration Guide
Summary
This document describes the various configuration parameters for the Sparkfly integration to the Aloha POS system. There are two main configuration files:
| file | system | typical location | purpose |
|---|---|---|---|
| sparkfly.ini | BOH | [AlohaDir]\DATA\sparkfly.ini |
Contains main configuration for the Sparkfly Aloha integration. |
| gateway.ini | BOH | [ProgramFiles]\Sparkfly HTTP Gateway\gateway.ini |
Contains configuration for the Sparkfly HTTP Gateway. |
File paths will vary based on your environment. Each file is described in detail in the following sections.
Main Configuration (sparkfly.ini)
[api]
The api section deals with settings that are related to configuration to API commuications, such as API credentials and unique site identifiers.
| key | type | description |
|---|---|---|
| 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. This should be the address where the Sparkfly HTTP Gateway is running. For example, if you have installed the Sparkfly HTTP Gateway on the Aloha BOH with the hostname ALOHABOH, this value should be http://ALOHABOH:6003. Note that the port specified here should match the listenPort specified in the Sparkfly HTTP Gateway Configuration. |
| 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) |
[site]
The site section deals with store-specific configurations, that are likely to vary by location.
| key | type | description |
|---|---|---|
| siteId | string | The site ID for this location. Unique by store. |
| itemCode | number | The Aloha item number for the Sparkfly credential item. |
| voidManagerId | number | The Aloha employee number for a manager to use when performing protected void operations, such as removing our credential item from the check. |
| voidManagerJobCode | number | The Aloha role number to use when impersonating the manager specified by voidManagerId. The role must have voiding capabilities. |
| promoCode | number | The Aloha promotion item number for the Sparkfly promotion trigger. |
| externalIdSource | enum | External Identifier source type. Valid Values are: ato, itemDescription. |
| externalIdItemCode | number | The Aloha item number to use when looking up the External ID by item number. Used with externalIdSource of itemDescription. |
| transactionBlockItemCode | number | If this item is present on the check, Sparkfly will not be allowed to interact with the transaction. |
[config]
| key | type | description |
|---|---|---|
| keyboard | enum | type of keyboard to use when accepting codes from the user program. Valid values are: qwerty, numeric, aloha |
| automaticBarcodeFormats | string | Patterns to match when intercepting Aloha barcode scanning events. See Barcode Matching Formats for details. |
| maxLogLevel | enum | the maximum log verbosity. Default is 'info'. Levels are (in increasing verbosity): error, warn, info, debug |
| finalizeAllTransactions | boolean | Whether or not the integration will transmit all transactions, including those without coupons or loyalty members, to our platform. This feature requires an account-level license, and will only function if such a license has been acquired. |
| dialogTimeout | int | Number of seconds until Sparkfly code entry form times out and the code entry form is cancelled. If not specified the code entry form will not timeout. |
| voidReasonNumber | int | This void reason number is provided by our integration when a Sparkfly item is voided from the check. Void reason numbers can be found in ConfigurationCenter > Maintenance > System Settings > Void Reasons, and use the Number associated with the intended reason number. |
[amountOverride]
| key | type | description |
|---|---|---|
| keyboard | enum | type of keyboard to use when accepting codes from the user program. Valid values are: qwerty, numeric, aloha |
| itemCode | number | The Aloha item number for the AmountOverride trigger. |
| promoCode | number | The Aloha promotion item number for the AmountOverride trigger. |
[localization]
| Name | Description | Default Value |
|---|---|---|
| backspaceButton | Backspace button in the aloha keyboard. |
<- |
| cancelButton | Cancel button in the aloha, qwerty, and numeric keyboards. |
Cancel |
| clearButton | Clear button in the aloha, qwerty, and numeric keyboards. |
Clear |
| continueButton | Continue button in numeric keyboard. |
Continue |
| deleteButton | Delete button in numeric keyboard. |
Del |
| okButton | Clear button in the aloha and qwerty keyboards. |
Ok |
| spaceButton | Space button in the aloha keyboard. |
Space |
| amountOverrideLabel | Amount override title form label. | Amount Override |
| promotionCodeLabel | Amount override promotion code label. | Promotion Code |
| discountAmountLabel | Amount override discount amount label. | Discount Amount |
| amountOverridePromoCodeSubtitle | Amount override promotion code selected label. | Enter or scan the code you intend to override. |
| amountOverrideDiscountSubtitle | Amount override discount selected label. | Enter desired discount amount. |
| alohaErrorMessage | Message for Aloha errors. | There was an error communicating with Aloha. Please contact support. |
| genericErrorMessage | Message for generic errors. | There was an error processing your request. Please contact support. |
| networkErrorMessage | Message for network related errors. | There was an error while communicating with the Sparkfly server. Please contact support. |
| invalidEntryMessage | Message for Sparkfly credential input errors. | Invalid entry. |
| invalidVoidManagerMessage | Message for void manager configuration errors. | Warning - Sparkfly configuration is invalid. VoidManagerId is specified, but VoidManagerJobCode is missing. |
| cantApplyOfferMessage | Message for offer application errors. | Unable to apply the offer. Please contact IT Support for assistance. |
| cantApplyOfferAfterPaymentMessage | Message for inability to apply offer after a payment is applied. | WARNING: A discount was available but could not be applied as payment has already been received. |
| blockedTransactionMessage | Message displayed when a transaction cannot be accessed by the Sparkfly agent due to TransactionBlockItemCode being present on the check. |
Cannot apply coupons or loyalty to this transaction. |
| currencySymbol | Symbol to use when displaying currency. | $ |
| noDrawerAssignedMessage | Message when our integration cannot respond to an action because QS employee doesn't have a drawer assigned yet. | Cannot preform any Sparkfly action without a drawer assigned. |
[loyalty]
| key | type | description |
|---|---|---|
| useLoyaltyUI | bool | When set to true, all credentials will be treated as loyalty credentials, and the reward selection UI will follow code entry. |
| maxRewards | number | The maxium number of rewards allowed per check. |
Barcode Matching Formats
The configuration key automaticBarcodeFormats allows filters to be configured to match specific sequences of characters when Aloha scans barcodes or magnetic cards at any point during the transaction. When a scan event occurs in Aloha, our integration is notified of the scan and must decide whether to handle the scan, or allow Aloha or other integrations to handle the scan. This configuration key determines which scans our integration will intercept and handle.
The field can contain multiple filters, separated by commas:
automaticBarcodeFormats=<filter1>,<filter2>,<filter3>,...
Each filter has 3 fields:
<prefix, may be omitted>|<length>|<Exclude or Include>
This allows for many combinations, and they can become quite complicated. Below are several examples of common use cases. If your use cases is not comparable to one of the below, please do not hesitate to reach out to support@sparkfly.com for configuration assistance.
Example 1: Match any 10-digit sequence
automaticBarcodeFormats=|10|Include
Example 2: Match any 10-digit sequence starting with 0
automaticBarcodeFormats=0|10|Include
Example 3: Match any 10-digit sequence starting with 0, or any 8-digit sequence
automaticBarcodeFormats=0|10|Include, |8|Include
Example 4: Match any 10-digit sequence, except those which starting with '1'
automaticBarcodeFormats=|10|Include, 1|10|Exclude
Example 5: Match any 5-digit sequence starting with A, B, or C
automaticBarcodeFormats=A|5|Include, B|5|Include, C|5|Include
Gateway Configuration (gateway.ini)
[logging]
The logging section primarily deals with the log files produced by the Sparkfly HTTP 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. |
[httpGateway]
The httpGateway section configures how the HTTP gateway routes API traffic to our platform. This section is useful for adjusting port numbers, or redirecting traffic to our staging environment.
| key | type | description |
|---|---|---|
| destination | string | The HTTP destination for API traffic. Defaults to our production API endpoint. For staging: https://posapi-staging.sparkfly.com For production: https://posapi.sparkfly.com |
| destinationTimeout | number | The timeout, in seconds, for requests forwarded to the Destination. |
| listenPort | number | The port used to listen for requests from our Aloha integration. Defaults to 6003. This value must be synchronized with the equivalent value in sparkfly.ini. |