GCS - Generate Group POS Interface

Transcription

1 GCS - Generate Group POS Interface Golf Computer Systems MMS_Generate_Interface Version July 2009

2 Introduction Golf Computer Systems Generate Group Point of Sale Interface (named the Interface for the remainder of this document) is a module designed to accept data across a TCP/IP connection from Generate Group Point of Sale terminals or Back Office server into GCS s Membership Management System and return information about members or accept payments. Generate Group will also have an interface application which will similarly facilitate 2-way data communication from POS and/or back office. Functionally the interfaces will enable member validation from MMS to occur when a member is identified at POS. Following successful validation the member POS transactions may pass across the interface and record against appropriate ledgers within MMS, either for account charging or reduction of credit account balances. Additionally the interface will enable account balance queries on a per member basis, and account payments by members to any applicable ledgers within MMS. In the latter case the payment will register for cash reconciliation in POS but will not form part of sales revenue. Interface traffic should be able to be logged to an external file for support purposes. Contact Questions relating to the Interface specification should be directed to Chris Matheson of Golf Computer Systems by phone on (07) or to chris@golfclub.com.au. 2 GCS-Generate Interface

3 Interface Settings... 4 MMS Configuration... 4 Interface Configuration... 4 Data Format... 7 Functions... 7 Sales Transaction... 8 Transmission... 8 Sale Data... 9 Response... 9 Balance Enquiry Transmission Response Balance Data Payment Transmission Response Check Interface Transmission Response Member Details Transmission Response Member Data Lookup Details Transmission Response Lookup Data Journals Transmission Response Member Information Transmission Response Output Format Error Checking GCS-Generate Interface 3

4 Interface Settings MMS Configuration The settings for the Interface are stored in the database and access by the Membership Management System (MMS) application. In MMS; click View Configuration on the main menu. Go to the POS Interface tab. Set the POS System to Generate. Configure other settings and click Save. The other settings on this tab, and the other tabs, are explained in greater detail in the Membership Management System User manual (available from the Golf Computer Systems webiste at Interface Configuration When the Interface is launched, it appears as an icon on the system tray. Right-click and select Open or double-click to show the main form. 4 GCS-Generate Interface

5 The Status tab shows the state of the Nexus database connection and the number of current connections. Image Status No problems encountered Error or function disabled check Logs for more detail The status could not be determined An internal application error has occurred The Settings tab allows changes to the configuration of the Interface: Application These settings relate to the application. Registered Name the name of the entity the Interface is registered to Registration Code the registration code Registration Expires this is generated automatically based on the registration code Log Filename the file where all interface information is logged Log Information when this is checked, the log will contain non-error information Append to log check this to append to the log file instead of overwriting Close button minimises changes the behaviour of the Close button Hide application on startup hides the interface on startup GCS Database Settings for the GCS database connection. Nexus Server name or IP address of the GCS Nexus database server Alias name of the database alias Interface Settings for the Interface TCP Port sets the TCP/IP port to be used Auto-Start Interface automatically starts the interface when run System Tray Icon The system tray icon shows the status of the interface. Image Status Interface is running and ready to receive connections There is a problem preventing the interface from starting An error has occurred, see the log for more information An application exception has occurred, contact GCS GCS-Generate Interface 5

6 Information Log The Interface logs errors and exceptions in the log file specifed. If the Log Information option is enabled, then warnings and information entries are also recorded. Use the GCS Log Viewer to read this log file. The GCS Log Viewer uses icons for information types: Image Status Information there were no problems Warning the operation proceeded regardless Error the operation was halted due to a problem Exception an internal application error has occurred Log Viewer The information log is a Microsoft Excel compatible CSV text file and can be read in notepad. It contains some information such as date/time that is numerical and the GCS Log Viewer was created to make this file easier to read. Enter the path to the log file to open it. Double click a log entry to open the Message in a separate window. Click Types to toggle the four information types on or off. If the log file is very large, use the option to Load last X lines only in the Options screen. Click Refresh (or press F5) to re-load the log file. Note: There may be slight changes to the appearance of the Interface form or GCS Log Viewer not covered in this document, contact Golf Computer Systems on (07) if required. 6 GCS-Generate Interface

7 Data Format All communication with the Interface is done via a blocking TCP connection. The data sent over this connection uses the following format: SOH FT EOT FS Data All communication with the Interface begins with a Start of Header (SoH), contain a Function Type (FT) and ends with an End of Transmission (EoT). Additionally, any number of Data fields separated by the Field Separator (FS) may be included. Some functions may use another separator character to embed multiple records within a single Data field. This sub level data uses Pipe as a field separator and Tilde as a record separator. Character Code Hex Example Use SOH Start of Header FS 28 1C Field Separator EOT End of Transmission Pipe 124 7C Sub level Field Separator Tilde 126 7E ~ Sub level Record Separator Functions The following is a list of all the Interface functions available after version Function Sales Transaction Balance Enquiry Payment Check Interface Member Details Lookup Details Journals Member Information Description Point of Sale transaction sent to MMS to be written to a Member s account. Returns the balance of all ledgers and all fee links for a Member. Makes a payment onto a Members account. Checks the state of the Interface and returns version information. This can be used like an echo request (ping) to check the Interface is running and will accept transactions. A lack of response to this request after a few seconds is a good indication that the Interface is not running. Returns a list of all Members and their available balances for use in offline transactions. Returns the contents of a GCS lookup table. For example the Tender Types table is required for the Payment function. Writes a journal directly to a Member s account. Returns a list of member numbers and names in a customisable format or sends that list to a file. GCS-Generate Interface 7

8 Sales Transaction Transmission (Sales Items in blue) SOH Function Type FS Member Number FS POS Reference FS Reference ID FS Sent Date FS Sent Time FS Transaction Type FS Billing Link FS Charge Amount FS Charge Description FS Ledger Code FS Offline Transaction FS Item Name Quantity Price Inc Tax Tax Amount Stock Name Ledger Code [~ Sale Item ] EOT Function Type Integer 1 POS Sale Transaction (must be 1) Member Number String[10] Membership number of GCS Member. If numerical and prepended with + then this is read as a GCS Player ID. Depending on the settings in MMS, the member number may be padded to a number of zeroes. Eg 2 may be converted to before being used to lookup the member. POS Reference String[20] POS Terminal Reference for this transaction GCS Reference Integer GCS internal reference ID. Manditory if transaction is a Resend or Reverse. Optional for New transaction or set to 0 for internal creation. Sent Date Date Any date format, but prefer as yyyy-mm-dd Sent Time Time Any time format, but prefer 24hr as hh:mm:ss Transaction Type Integer 1 New transaction 2 Resend existing transaction (Reference ID must be set) 3 Reverse existing transaction (Reference ID must be set) Billing Link String[10] Membership number of Linked GCS Member. If numerical and prepended with + then is read as a GCS Player ID. Set to 0 to show no link. Charge Amount Float Total value of the transaction Charge Description String[50] Description of transaction Ledger Type (AR) String[4] Ledger Type (AR) for this transaction. The valid codes for this field are available from Balance Enquiry and other Interface functions. Offline Transaction Integer 0 Transaction is live 1 This transaction was created while the Interface was not contactable. Sale Items Sale Data See notes for more information :30: Pro Shop purchase Golf Club ~Golf ball GCS-Generate Interface

9 Sale Data Item Name Quantity Price Inc Tax Tax Amount Stock Name Ledger Code [~ Sale Item ] Item Name String[20] Description of sale item Quantity Float Quantity of this item Price Inc Tax Float Gross per unit item price Tax Amount Float Tax amount of per unit item price Ledger Code (GL) Ledger Type (AR) String[4] String[4] Used to find the Ledger Code (GL) for this item. Must match the Code field of the lookup table. If not supplied Susp will be used. Ledger Type (AR) for this item. This must match the Ledger Type of the Sale record. Response SOH Function Type FS POS Reference FS Reference ID FS Result EOT Function Type Integer 1 POS Sale Transaction (always 1) POS Reference String[20] POS Terminal Reference for this transaction GCSReference Integer GCS POS Reference ID, this is used for any further communication regarding this particular transaction. This is returned as -1 if there is no GCS transaction record. Result String[50] If the transaction is successful, this will be blank, otherwise it will contain the reason for the failure Insufficient funds GCS-Generate Interface 9

10 Balance Enquiry Transmission SOH Function Type FS Member Number FS POS Reference FS Ledger Type EOT Function Type Integer 2 Balance Enquiry (must be 2) Member Number String[10] Membership number of GCS Member. If numerical and prepended with + then this is read as a GCS Player ID. POS Reference String[20] POS Terminal Reference for this transaction Ledger Type (AR) String[4] If specified, then only the requested ledger is returned. Note: Depending on the settings in MMS, the member number may be padded to a certain length with zeroes. Eg 2 may be converted to before being used to lookup the member. In the following example, the same member is returned abc UA Response (Balance Data in blue) SOH Function Type FS POS ReferenceFS Ledger Type Code Ledger Description Payments Allowed Visible Ledger Period End Date Period End Balance Current Balance [~ Balance Data ] FS Result FS Last Name FS First/Preferred Name EOT Function Type Integer 2 Balance Enquiry (always 2) POS Reference String[20] POS Terminal Reference for this transaction Balances Balance Data Balances of all available Ledger Types. Result String[50] This will return any problems with the input parameters or information like the member account being on hold. If it is blank then no problems were encountered. Last Name String[25] Member s last name Preferred Name String[50] Member s preferred first name User Defined String CSV of User Defined fields from Member Category and Member. Includes "On Hold,True" if Member s account is on hold. On hold accounts cannot process Sales. 10 GCS-Generate Interface

11 Balance Data Ledger Type Code Ledger Description Payments Allowed Visible Ledger Period End Date Period End Balance Current Balance [~ Balance Data ] Ledger Type (AR) String[4] GCS Code for this Ledger type Ledger Description String[30] Display name Visible Ledger Integer Always 1 Payments Allowed Integer 0 Payments cannot be made to this ledger 1 Payments can be made to this ledger via the Interface Transactions Allowed Integer 0 Sales transactions cannot be made to this ledger 1 This ledger can be used for sales Charge to Account Integer 0 You cannot spend more than the current balance 1 There is no credit limit on this ledger Current Balance Float The balance as at the current date Main Ledger ~0001 Loyalty Points ~UA U sable Advance Adams Harold UserDefined= Subs ~0001 House Adams Harold "On Hold,Tru e" Note: A negative balance means the member has their own money (credit) in the account, positive means they owe the club money. Note: Only POS Visible ledgers are returned. GCS-Generate Interface 11

12 Payment Transmission SOH Function Type FS Member Number FS POS Reference FS Reference ID FS Sent Date FS Sent Time FS Transaction Type FS Billing Link FS Charge Amount FS Charge Description FS Ledger Code FS Offline Transaction FS Tender Type EOT Function Type Integer 3 Payment (must be 3) Member Number String[10] Membership number of GCS Member. If numerical and prepended with + then this is read as a GCS Player ID. Depending on the settings in MMS, the member number may be padded to a number of zeroes. Eg 2 may be converted to before being used to lookup the member. POS Reference String[20] POS Terminal Reference for this transaction Reference ID Integer GCS POS Reference ID, must be set if this transaction is a Resend or Reverse. Sent Date Date Any date format, but prefer as yyyy-mm-dd Sent Time Time Any time format, but prefer 24hr as hh:mm:ss Transaction Type Integer 1 New transaction 2 Resend existing transaction (Reference ID must be set) 3 Reverse existing transaction (Reference ID must be set) Billing Link String[10] Membership number of Linked GCS Member. If numerical and prepended with + then is read as a GCS Player ID. Set to 0 to show no link. Charge Amount Float Total value of the transaction Charge Description String[50] Description of transaction Ledger Type (AR) String[4] Ledger Type (AR) this transaction will be applied to. The valid codes for this field are available from Balance Enquiry and other Interface functions. Offline Transaction Integer 0 Transaction is live 1 This transaction was created while the Interface was not contactable. Payment Type String[4] Code from GCS Payment_Type lookup table ABC :30: Payment GCS-Generate Interface

13 Response SOH Function Type FS POS Reference FS Reference ID FS Result EOT Function Type Integer 3 Payment Transaction (always 3) POS Reference String[20] POS Terminal Reference for this transaction Reference ID Integer GCS POS Reference ID, this is used for any further communication regarding this particular transaction. This is returned as -1 if there is no GCS transaction record. Result String[50] If the transaction is successful, this will be blank, otherwise it will contain the reason for the failure. GCS-Generate Interface 13

14 Check Interface Transmission SOH Function Type EOT Function Type Integer 4 Check Interface (must be 4) Response SOH Function Type FS Accept Transactions FS Current Version FS Update Requirement EOT Function Type Integer 4 Check Interface (always 4) Accept Transactions Integer 0 The Interface can not accept transactions at this time 1 The Interface is functioning and can be used Current Version Float The current version of the Interface Update Requirement Float The GCS Database Update requirement. If this requirement is not met, the Interface cannot be started GCS-Generate Interface

15 Member Details Transmission SOH Function Type FS Ledger Balance FS UA Balance EOT Function Type Integer 5 Member Details (must be 5) Ledger Type (AR) String[4] If a Ledger Type (AR) code is received, the balance for that ledger is returned. UA ledger code not valid. Leave blank for no balance check. Set to ALL to get the sum of all POS chargeable balances. UA Balance Integer Set to 1 to include current Usable Advance balance Response (Member Data in blue) SOH Function Type FS Member Number Last Name First Name Player ID Ledger Balance UA Balance [~Member Data ] EOT Function Type Integer 5 Member Details (always 5) Member Details Member Data Details of Members and their balances Member Data Member Number Last Name First Name Player ID Ledger Balance UA Balance [~Member Data ] Member Number String[10] The Membership number of this Member Last Name String[25] Member s last name Preferred Name String[50] Member s preferred first name Player ID Integer GCS unique Player ID Ledger Balance Float Balance of requested ledger(s) UA Balance Float Balance of Usable Advance Adams Harold ~00003 Adams Vic 3 0 0~00243 Smith John GCS-Generate Interface 15

16 Lookup Details Transmission SOH Function Type FS Lookup Table EOT Function Type Integer 6 Lookup Details (must be 6) Lookup Table String[30] Name of the lookup table to be returned, valid inputs are: Payment_Type, Ledger_Type, Ledger 6 Ledger_Type Response (Lookup Data in blue) SOH Function Type FS Code Comment [~Lookup Data ] EOT Function Type Integer 6 Lookup Details (always 6) Lookup Details Lookup Data Details of the Lookup Table Lookup Data Code Comment [~Lookup Data ] Code String[4] The GCS internal code for this Lookup item Comment String[30] The display name for this item this is displayed on the screen when using this lookup item Main~0001 Points~UA Usable Advance Cash~0001 Cheque~0002 Credit Card 16 GCS-Generate Interface

17 Journals Transmission SOH Function Type FS Member Number FS POS Reference FS Reference ID FS Amount FS Description FS Ledger Type FS Ledger EOT Function Type Integer 7 Journals (must be 7) Member Number String[10] Membership number of GCS Member. If numerical and prepended with + then this is read as a GCS Player ID. Depending on the settings in MMS, the member number may be padded to a number of zeroes. Eg 2 may be converted to before being used to lookup the member. POS Reference String[20] POS Terminal Reference for this transaction Reference ID Integer GCS POS Reference ID (not used, must be 0) Amount Float Total value of the journal Description String[100] Journal description Ledger Type (AR) Ledger Code (GL) String[4] String[4] T Loyalty Credit Ledger Type (AR) this transaction will be applied to. The valid codes for this field are available from Balance Enquiry and other Interface functions. Ledger Code (GL) for this journal. The journal description is appended to the Ledger Code comment. Response SOH Function Type FS POS Reference FS Reference ID FS Result EOT Function Type Integer 7 Journals (always 7) POS Reference String[20] POS Terminal Reference for this transaction Reference ID Integer GCS Journal Reference ID Result String[50] If the transaction is successful, this will be blank, otherwise it will contain the reason for the failure T GCS-Generate Interface 17

18 Member Information Transmission SOH Function Type FS Output Format FS Output File EOT Function Type Integer 8 Member Information (must be 8) Output Format String[20] This string determines the format of the member information returned. See below for more information on the format characters. If not specified, the following format is used: 000mmmmmss L p Output Filename String[120] If specified, the output of this function will be written to this file instead of being returned by the interface. 8 mmmmm L f 8 \\server\share\filename.txt Response (Member Information in blue) SOH Function Type FS Result FS [Member Information...] EOT Function Type Integer 8 Member Information (always 8) Result String[50] This will return any problems with the input parameters or information like the member account being on hold. If it is blank then no problems were encountered. Member Information String If a filename was specified for the output, this field will be empty. Otherwise it will contain the member information. Output Format Format Information Character 0 Zero literal m Member number. Repeat for the number of characters required to be padded to. Eg mmmmm is member number padded to 5 characters with zeros. s Sequence number. As with member number, repeat for padding. Pipe literal, field separator L or l Member last name, use L to capitalise the last name or l to set it to mixed case. Eg. L for SMITH and l for Smith. F or f Member first name can be multiple names, up to 50 characters. P or p Member preferred name is one name up to 15 characters. 18 GCS-Generate Interface

19 HAZER Matthew~ SMITH Robert 8 Invalid characters were received in the Output Format 8 The output file could not be created: Access denied 8 The output file could not be created: Insufficient disk space GCS-Generate Interface 19

20 Error Checking Checks are made on received data and the following is a list of errors and their causes. Any post that returns an error is not entered onto a Member s account. Error returned Reason Invalid date Data read as a date is not in a valid date format Invalid time Data read as a time is not in a valid time format Invalid reference number The supplied reference number does not appear to be numeric Unable to validate member Unable to locate a member with this member number or PlayerID Unable to validate linked member Unable to locate a linked member with this member number or PlayerID Invalid status The supplied status is not one of the valid statuses Invalid amount The amount does not appear to be numeric Insufficient Usable Advance The member does not have enough Usable Advance balance balance to cover this transaction and the UA ledger is not set to allow members to charge to account Unable to charge to this Ledger This ledger is not flagged as Redeemable at POS Unable to communicate with The interface has lost connection with the Nexus database database. Check the interface settings are correct and the Nexus server is running Credit limit exceeded The member has met or exceeded their credit limit Insufficient funds The requested ledger does not have enough balance to cover this transaction and is not set to allow members to charge to account Account on hold This member s account is flagged as On Hold and no transactions can be applied to it Unable to add to Usable Advance An internal error occurred updating the UA balance balance field, contact GCS Invalid quantity The quantity of a sale item does not appear to be numeric Invalid tax The tax amount of a sale item does not appear to be numeric An unknown error occurred An exception occurred converting received data, converting the transaction contact GCS Unable to write transaction to tables An exception occurred writing data to the database, contact GCS Unable to post to Member POS An exception occurred writing data to the database, table contact GCS Unable to post to Member POS An exception occurred writing data to the database, Item table contact GCS Unable to post to Member Journal An exception occurred writing data to the database, table contact GCS Unable to post to Member Journal An exception occurred writing data to the database, Item table contact GCS Ledger type (%s) invalid %s is the name of a supplied ledger type that is not 20 GCS-Generate Interface

21 Ledger code invalid or not found Payment type does not exist Unable to start database transaction Unable to end database transaction Unable to reverse original transaction A problem was encountered. Transaction has not completed successfully The received data was not valid Lookup Table not valid The Journal record was not created Usable Advance is not available Transaction total does not match sale items valid The supplied ledger code is not valid The supplied payment type code is not valid Unable to start a database transaction, contact GCS Unable to end a database transaction, contact GCS An error occurred trying to reverse an existing transaction, contact GCS The received payment was not processed, contact GCS The number of fields received does not match the transaction type. For example a balance enquiry has four fields. The table requested by a Lookup routine is not valid An exception occurred writing data to the database, contact GCS Usable Advance was selected but is not enabled or configured in MMS The total supplied does not match the sum of the sale items. GCS-Generate Interface 21