THIRD-PARTY XML INTEGRATION MANUAL

Transcription

1 THIRD-PARTY XML INTEGRATION MANUAL PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

2 THIRD-PARTY XML INTEGRATION MANUAL Contents METRA Demo Client Software... 3 METRA Demo Server Software... 6 ELS NET... 9 ELS NET - Clear Reservation ELS NET - Event Info ELS NET - Info ELS NET - Locker Info ELS NET - Locker State and Past Events...38 ELS NET - Locker State ELS NET - Sale ELS NET - Unlock Specific Locker ELS NET - White List LCC NET LCC NET - Card Info LCC NET - Card Info LCC NET - Event Info LCC NET - Exit LCC NET - External Interface Event LCC NET - External Interface LCC NET - Get Card LCC NET - Interface LCC NET - Item Issue LCC NET - Repair LCC NET - Tickets Erase LCC NET External Interface LCC NET - External Interface Event LCC NET - External Interface LCC NET - Interface ELS Interface ELS Interface - Event Info ELS Interface - Locker Info ELS Interface - Locker State ELS Interface - Unlock Specific Locker ELS Interface - White List Format Media SN Encoding PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

3 THIRD-PARTY XML INTEGRATION MANUAL METRA DEMO CLIENT SOFTWARE PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

4 Help: Metra DEMO Client Software Metra DEMO Client software is used to test Metra Software XML interfaces. To create a XML package you can use different build-in wizards or you can import a XML package from a file (file can be created manually or exported from 3rd party software). Metra DEMO Client software can also be used to test XML interfaces of 3rd party software, when 3rd party software acts as a server and Metra software as a client (e.g. Metra ELS Delivery systems, 3rd Party Access Control systems with Metra access control devices, etc.). NOTE: if all tabs are not displayed correctly try maximizing the window. CONNECTION To connect with a Server use a "XML over TCP/IP" or "Web services" connection. Metra Software supports both. XML over TCP/IP connection: Fill in the Server field. Use " " if the server software is installed on the same computer or computer's name (e.g. "mserver") if server software is installed on other computer in the network. For Metra Server Software use port "6771" and for 3rd party software as required. To establish the connection click on button "Connect". Web services connection: Fill in the server's URL field. Use " if you want to connect to Metra Server Software installed on the same computer or computer's name followed by port ":6781" (e.g. "//mserver:6781"). To connect to a 3rd party server software use the same type of URL address, but mind that the port may be different. PREPARE PACKAGE To prepare a XML package use one of the build in wizards or open the "XML samples" tab and all XML files stored in the same directory as the "client.exe" will be listed. You can also add your own samples. After you configure a XML wizard or select a XML file from a list click on the "Prepare" button. Content of the XML package will be shown in the left bottom window. In this phase you still manually edit a prepared XML package before sending. NOTE: Double clicking the XML file in "XML samples" tab automatically prepares it.

5 SEND PACKAGE To send a package over TCP/IP connection click on "Send - Receive" button along with server/port fields or to send a package over Web services click on a "Send - Receive" button along with URL field. Received reply from the server will be shown in bottom right window. EXAMPLE This example shows how to prepare, edit and send a "Locker ELS NET Info" XML package. Click Play icon bellow screen image. If your browser does not support flash animation, you can view the same video in different format here. ( Back )

6 THIRD-PARTY XML INTEGRATION MANUAL METRA DEMO SERVER SOFTWARE PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

7 Help: Metra DEMO Server Software Metra DEMO Server software is used to test 3rd party to Metra Software XML interfaces. Like Metra Software it supports different types of communication, a XML packages via TCP/IP or Web services. Build-in wizards allow you to define/change XML results for some XML interfaces and for the other XML interfaces there are editable XML result files included. START THE SERVER Start the DEMO server by clicking one of the "Start" buttons along the port entry fields. Ports are preset to Metra Software defaults. NOTE: If you get an error message "Could not bind socket. Address and port are already in use." you already have Metra Software running on the same computer. Select other port (e.g. 6791) and try to start the server. DEFINING THE DESIRED RESULT To emulate Metra software in desired situation you will need to prepare a result. For some XML interfaces you can use one of the build-in wizards and for the others you need to place a XML result files into the same directory as the DEMO server executable. XML result example files for each interface are already included with the DEMO software.

8 COMMUNICATION Once the XML result files are set, server running all the XML communication is shown in the bottom window. EXAMPLE This example shows communication between Metra DEMO server software and Metra DEMO client software. Click Play icon bellow screen image. If your browser does not support flash animation, you can view the same video in different format here. You do not have the latest version of Flash installed. Please visit this link to download it: ( Back )

9 THIRD-PARTY XML INTEGRATION MANUAL ELS NET PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

10 XML packages Locker ELS NET Free XMLenfU5.docx Locker ELS NET Free XML package Revision: Date Comment Creation of document Added datetimefrom, datetimeto and ID Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

11 XML packages Locker ELS NET Free XMLenfU5.docx 1 General This XML package is sent by 3 rd party SW through TCP/IP interface to release (Free) a locker reservation to a card/wristband in the Metra ELS NET system. Depending on the settings in the Metra ELS NET SW locker reservations that expire by date can be automatically deleted by Metra SW or not and have to be made free by using this XML package. Usage of this package also applies in cases when a locker reservation has not yet expired but the locker is to be changed or simply reversing a false operation. Result Codes returned by the interface: Result codes used: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded For this XML package the result gives only the result code. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. 1.2 Parameters Mandatory: Item Item ID, which is normally a type of locker. E.g. locker for one person, two (in ski resorts), big locker, small locker, etc. Defined in the Metra SW. Locker number Optional: Pos and user reference for tracking and analysing reservations in Metra SW DateTimeFrom & DataTmeTo are used to specify a time frame between which locker reservations matching other parameters are freed. Only entries which are within the given time frame are freed. ELS NET Entry unique ID from Metra DB can be used to free a specific known entry. In order to use this parameter, it should be stored in 3 rd party SW (DB) from initial ELS NET Sale operation. Page 2

12 XML packages Locker ELS NET Free XMLenfU5.docx 2 Examples XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>lockerelsnetfree</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <pos>1</pos> Point of sale code Small integer If parameter is not given, lowest from Metra DB is used <user>2</user> User code Small integer If parameter is not given, lowest from Metra DB is used <item>depo2</item> Item ID Varchar (30) Unique Item ID from Metra SW Tables <locker>5012</locker> Locker number Integer Possible values <datetimefrom> t09:50:00</datetimefrom> Date & time from Given in example Start of validity <datetimeto> t09:50:00</datetimeto> Date & time to Given in example End of validity <id> </id> ELS NET Entry ID Integer Unique reference from Metra DB </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Page 3

13 XML packages Locker ELS NET Free XMLenfU5.docx Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 4

14 XML packages Locker ELS NET Free XMLenfU5.docx 3 Appendix An XML file is attached to the document with same structure as the example XML package and result. Page 5

15 XML packages Event Info XMLeviU5.doc Event Info XML package v1.0 Revision: Date Comment Creation of document Revision Revision Added new events and modes to list of events and modes Added MEW DAT additional events Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

16 XML packages Event Info XMLeviU5.doc 1 General This XML package is sent by Metra SW to 3 rd party SW to give event information of events that happen in Metra systems. These events are sent online in real time. Also they are queued in Metra DB if communication is not possible at the time of event, so they are sent later when connection is re-established. Which events are sent can be filtered in the Metra SW to avoid unnecessary traffic with info not needed. Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. It must be sent by 3 rd party SW, else event is queued and sent again later. Page 2

17 XML packages Event Info XMLeviU5.doc 2 Example XML package - entrance Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>eventinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <event> Event / <eventid> </eventid> Event id Integer Unique event id from Metra DB <card> d e634162</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <dt> t09:40:00</dt> Date & time of event Given in example DT as recorded in Metra DB <code>30</code> Event Code Integer 30 for locking, 40 for unlocking, <codedescription>locking</codedescription> Event description Varchar (36) Locking, Unlocking, <mode>1</mode> Mode of event Code Integer 1, 5 or 71, see below for respective descriptions <modedescription>user key</modedescription> Mode of event description Varchar (36) USER key, MASTER key, DELIVERY key <iddevice>102</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) <devicedescription>cu 102</devicedescription> Device description from Metra tables Varchar (36) <locker>1234</locker> Locker number Integer <idlocation>1</idlocation> Location ID Integer Same locker numbers are possible on different locations <locationdescription>lobby</locationdescription> Location description Varchar (36) </event> / / </parameters> / / </package> / / Page 3

18 XML packages Event Info XMLeviU5.doc Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / </package> / / Page 4

19 XML packages Event Info XMLeviU5.doc 3 Events and Modes Not all events or modes apply to all integration scenarios. 3.1 Events 1 Read wristband, CardInfo01 2 Card Issue 3 Procedure (Points, Tokens, Borrow), Repair, Exit, Entrance 4 Erase wristband, Tickets erase 5 Barcode 6 External 7 Member Export 8 Member Import 10 Entrance 12 Entrance Denied 20 Exit 22 Exit Denied 30 Locking OK 31 Payed Locking OK 32 Locking Denied 33 Locking failed 34 Locking/Unlocking Error 40 Unlocking OK 43 Unlocking failed 49 Unlocking OK - Alarm Delay 50 Passage 52 Passage Denied 60 Push-button 61 Do Not Disturb 62 Make my Room 63 Room Cleaned 64 Reception Request 70 Deposit Activated 75 Deposit Deactivated 90 ALARM 91 Supervised locker break-in 100 Card 101 PIN 102 External / Remote 120 Card - Deposit 200 OK 201 Set Pay 202 Reset Pay 203 Activate Deposit 204 Deactivate Deposit 250 Denied 251 Wrong Reader Unit 252 Deposit Denied 300 Coin accepted 301 Temporary saldo erased 320 Vending OK 321 Vending Error 401 Locker closed after prelock Page 5

20 XML packages Event Info 402 Locker closed after unlocking 403 Locker opened after warning 404 Locker remained prelocked 405 +UWT 406 Prelocking not confirmed 450 "Pin" temporarily inhibited 451 "CodE" temporarily inhibited 452 "Scod" temporarily inhibited 460 Prelocking inhibited 490 Unlock request accepted 500 Free passage ON 501 Free passage OFF 510 Signal Alarm 511 Signal Armed ON 512 Signal Armed OFF 513 Signal PIN 514 Signal Test 515 Alarm Sensor Activated 516 Alarm Sensor Deactivated 517 Door Unlocked 518 Door Locked 519 Door Opened 520 Door Closed 521 Entrance Deactivated 522 Exit Deactivated 601 Update sold Tickets 602 Assign Procedure 603 Unlocking request 604 ELS Key Exchange Request 605 ELS Key Exchange Answer 606 WBC Closed After Timeout 607 Buyer Export 608 Buyer Import 609 Settle All Cards 610 External Payment 611 SMS Interface 612 S.M.SW Member Import 613 S.M.SW Locker ELS NET Export 614 WBC Closed 900 Power ON 901 General interrogation received 902 Start responding 903 Stop responding 904 Start multiple responses 905 Stop multiple responses 910 Time Set 911 New Time 912 Summer Time 913 Winter Time 920 Box Opened 921 Box Closed 930 Operating parameters OK 931 Operating parameters constructional 932 Requested initialization XMLeviU5.doc Page 6

21 XML packages Event Info 933 Automatic initialization 940 Error Terminated 941 Error 953 Coin acceptor start responding 954 Coin acceptor stop responding 960 SECURE Card 961 DOWNLOAD Card 962 SERVICE Card 963 CLEAN Card 964 ERASE Card 965 WARD Card 966 MASTER key 967 FAILSAFE key 990 Buffer overrun 999 State XMLeviU5.doc Page 7

22 XML packages Event Info XMLeviU5.doc 3.2 Modes 1 User Key 2 Ticket 3 Ticket Captured 4 Multi user key 5 MASTER key 6 MULTI key 7 FAILSAFE key 8 Push-button 9 ALARM 10 Entrance 11 Passage 12 Date 13 Time 14 Last Day 15 Day 16 Points 17 D Points 18 Direction 19 Not Valid 20 Exit 21 Tokens 22 MINI Card 23 Entrance delay 24 Locker 25 Add Charge 26 Refund 27 Borrow/PAY 28 Exit Counter 29 Cancelled LCC Card 30 Cancelled LCC Ticket 31 Denied LCC Ticket 32 Device Break-in 33 Door Break-in 34 Door Opened too long 35 Borrow 36 Delivery 37 Deny Exit 38 Electronic Money 39 WBC Full 40 Deposit 41 Maid key 42 OFF 43 ON 44 External 45 Busy 46 Minutes 47 Ring 48 Unfinished Document 49 Entrance Time Date 50 Passage 51 Child Page 8

23 XML packages Event Info XMLeviU5.doc 52 Pay Set 53 Pay Reset 54 Pay Set/Reset 55 Request 56 Answer 57 Event 58 One passage 59 Permanent Passage Change 60 First Day 61 Key denied 62 Not payed 63 User abort 64 Prelock 65 Timeout 66 Opened 67 Card Removed 68 D Minutes 69 D Minutes Gross 70 Clock 71 DELIVERY key 72 Delivery Not Possible 73 Extra 74 Group ticket 80 Motor error 81 "Err1" 82 "Err2" 85 Power off 86 Download required 87 File updated 90 Service required 91 Reader 1 92 Reader 2 95 Serial channel 97 Direct port 99 Unknown 101 Package 102 Result 111 EMERGENCY Key 112 Secret Code 113 Master Code 114 Network Time Table 115 Network Pushbutton 116 Automatic Opening 117 Pushbutton PCB 118 Door Opened 119 Free 120 Permanent key 121 Additional Payment 122 Occupy 123 Release Page 9

24 XML packages Event Info XMLeviU5.doc 4 Appendix An XML file is attached to the document which is same as the example XML package. Page 10

25 XML packages Locker ELS NET Info XMLeniU5.docx Locker ELS NET Info XML package Revision: Date Comment Creation of document Added DT fields Added ID to package and result Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

26 XML packages Locker ELS NET Info XMLeniU5.docx 1 General This XML package is sent by 3 rd party SW through TCP/IP interface to query among locker reservations and non-assigned lockers in the Metra ELS NET system. Result Codes returned by the interface: Result codes used: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and all given parameters of existing locker reservations and non-assigned lockers. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. 1.2 Package parameters All are optional. If none are given all reservations will be in the result, using more PARAMETERS will narrow the result. Free only returns only available lockers for which reservations can be made using ELS NET Sale XML package. Locker will produce a query based on locker number; several lockers can exist in an ELS NET system but are linked to different items. Item returns all lockers and exiting reservations of particular item. Card returns all locker reservations that exist for a particular card; one card can exist in several locker reservations. Name If name was given in the ELS NET Sale XML package upon making the reservation, a query can be made based on name; this is useful when guests lose their card and forget the locker number. DateTimeFrom & DataTmeTo are used to specify a time frame between which locker reservation status is required. ELS NET Entry unique ID from Metra DB can be used to narrow down the search to a specific entry. In order to use this parameter, it should be stored in 3 rd party SW (DB) from initial ELS NET Sale operation. 1.3 Result parameters All with same meaning as in the package. When a locker is listed with no other parameters only number, it is a free = non assigned locker that is available to be assigned through ELS NET Sale XML package. All other lockers are listed as occupied with all the belonging parameters. Page 2

27 XML packages Locker ELS NET Info XMLeniU5.docx A locker which is occupied within the time frame of the given DateTimeFrom and DataTimeTo is listed occupied even if there exists a reservation for only the smallest time within the filter limits. E.g.: A locker is occupied from :00:00 till :59:00. Info package includes DateTimeFrom and DateTimeTo Locker is listed as occupied (with all the belonging parameters). Page 3

28 XML packages Locker ELS NET Info XMLeniU5.docx 2 Examples XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>lockerelsnetinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <freeonly>1</freeonly> Show free only small integer Result will list free lockers only if 1, if tag omitted all in result <item>depo2</item> Item ID Varchar (30) Unique Item ID from Metra SW Tables <locker>55</locker> Locker number Integer Possible values <card> e c74cfa</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <name>john Doe</name> Name assigned to reservation Varchar (30) <datetimefrom> t09:50:00</datetimefrom> Date & time from Given in example Start of validity <datetimeto> t09:50:00</datetimeto> Date & time to Given in example End of validity <id> </id> ELS NET Entry ID Integer Unique reference from Metra DB </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Page 4

29 XML packages Locker ELS NET Info XMLeniU5.docx Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <items> Items / <item> Item / <id>lrh</id> Item ID Varchar (30) Unique Item ID from Metra SW Tables <lockers> Lockers / <locker> Locker / <number>1</number> Locker number Integer Possible values <name>john Doe</name> Name assigned to reservation Varchar (30) <datetimefrom> t09:50:00</datetimefrom> Date & time from Given in example Start of validity <datetimeto> t09:50:00</datetimeto> Date & time to Given in example End of validity <cards> Cards / Several cards can be assigned to one locker <card> e c74cea</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <card> e c74cfa</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </cards> / / <id> </id> ELS NET Entry ID Integer Unique reference from Metra DB <invoice>0</invoice> Invoice ** **Internal Metra use <price>0</price> Price ** **Internal Metra use </locker> / / <locker> Locker / <number>4</number> Locker number Integer </locker> / / </lockers> / / </item> / / </items> / / </parameters> / / Possible values ; Lockers with no other parameters are free lockers Page 5

30 XML packages Locker ELS NET Info XMLeniU5.docx <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 6

31 XML packages Locker ELS NET Info XMLeniU5.docx 3 Appendix An XML file is attached to the document with same structure as the example XML package and result. Page 7

32 XML packages Locker Info XMLlriU5.doc Locker Info XML package Revision: Date Comment Creation of document Revision of comments of XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

33 XML packages Locker Info XMLlriU5.doc 1 General This XML package is sent by 3 rd party SW to obtain information (in the respective result package) about particular locker status parameters and last 50 events from Metra ELS system. Locations are used in locker systems where several lockers exist with the same locker number. Therefore they are assigned to different locations to enable unique treatment of each. The package is sent to Metra interface server through the Metra TCP/IP interface. Information is returned from Metra interface server in the result package. Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and additional locker parameters depending on the parameters given in the Locker Info package. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. Page 2

34 XML packages Locker Info XMLlriU5.doc 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>lockerinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <locker>1234</locker> Locker number (1-7999) integer mandatory field <location>1</location> Location ID (1-9999) integer mandatory field if locations are used in the system </parameters> / / <userdata>xyz</userdata> Userdata Varchar (30) Result of this XML package includes same userdata if sent here </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <locker> Locker / <location>1</location> Location ID (1-9999) of locker integer Same locker numbers are possible on different locations <locker>1234</locker> Locker number integer <state>0</state> State ID Integer <statedescription>vacant</statedescription> State Description Varchar (30) In English only <events> Events <event> Event <eventid> </eventid> Event id Integer Unique event id from Metra DB Page 3

35 XML packages Locker Info XMLlriU5.doc <dt> t11:51:40</dt> Timestamp of event Given in example <code>288</code> Event code integer <codedescription>unlocking OK</codedescription> Event code Description Varchar (30) In English only <mode>9</mode> Mode ID Integer <modedescription>pushbutton</modedescription> Event mode Description Varchar (30) In English only <statebefore>2</statebefore> State ID Integer <statebeforedescription>occupied</statebeforedescription> State Description Varchar (30) In English only <stateafter>0</stateafter> State ID Integer <stateafterdescription>vacant</stateafterdescription> State Description Varchar (30) In English only <card> d cfde639</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </event> / / <event> Already described Already described <eventid> </eventid> Already described Already described <dt> t11:51:01</dt> Already described Already described <code>289</code> Already described Already described <codedescription>locking OK</codedescription> Already described Already described <mode>3</mode> Already described Already described <modedescription>user KEY</modedescription> Already described Already described <statebefore>2</statebefore> Already described Already described <statebeforedescription>occupied</statebeforedescription> Already described Already described <stateafter>2</stateafter> Already described Already described <stateafterdescription>occupied</stateafterdescription> Already described Already described <card> d cfde639</card> Already described Already described </event> / / <event> Already described Already described <eventid> </eventid> Already described Already described <dt> t11:50:48</dt> Already described Already described <code>288</code> Already described Already described <codedescription>unlocking OK</codedescription> Already described Already described <mode>3</mode> Already described Already described <modedescription>user KEY</modedescription> Already described Already described <statebefore>2</statebefore> Already described Already described <statebeforedescription>occupied</statebeforedescription> Already described Already described <stateafter>0</stateafter> Already described Already described Page 4

36 XML packages Locker Info XMLlriU5.doc <stateafterdescription>vacant</stateafterdescription> Already described Already described <card> d cfde639</card> Already described Already described </event> / / </events> / / </locker> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 5

37 XML packages Locker Info XMLlriU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 6

38 XML packages Locker Info XMLlriU5.doc Locker Info XML package Revision: Date Comment Creation of document Revision of comments of XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

39 XML packages Locker Info XMLlriU5.doc 1 General This XML package is sent by 3 rd party SW to obtain information (in the respective result package) about particular locker status parameters and last 50 events from Metra ELS system. Locations are used in locker systems where several lockers exist with the same locker number. Therefore they are assigned to different locations to enable unique treatment of each. The package is sent to Metra interface server through the Metra TCP/IP interface. Information is returned from Metra interface server in the result package. Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and additional locker parameters depending on the parameters given in the Locker Info package. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. Page 2

40 XML packages Locker Info XMLlriU5.doc 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>lockerinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <locker>1234</locker> Locker number (1-7999) integer mandatory field <location>1</location> Location ID (1-9999) integer mandatory field if locations are used in the system </parameters> / / <userdata>xyz</userdata> Userdata Varchar (30) Result of this XML package includes same userdata if sent here </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <locker> Locker / <location>1</location> Location ID (1-9999) of locker integer Same locker numbers are possible on different locations <locker>1234</locker> Locker number integer <state>0</state> State ID Integer <statedescription>vacant</statedescription> State Description Varchar (30) In English only <events> Events <event> Event <eventid> </eventid> Event id Integer Unique event id from Metra DB Page 3

41 XML packages Locker Info XMLlriU5.doc <dt> t11:51:40</dt> Timestamp of event Given in example <code>288</code> Event code integer <codedescription>unlocking OK</codedescription> Event code Description Varchar (30) In English only <mode>9</mode> Mode ID Integer <modedescription>pushbutton</modedescription> Event mode Description Varchar (30) In English only <statebefore>2</statebefore> State ID Integer <statebeforedescription>occupied</statebeforedescription> State Description Varchar (30) In English only <stateafter>0</stateafter> State ID Integer <stateafterdescription>vacant</stateafterdescription> State Description Varchar (30) In English only <card> d cfde639</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </event> / / <event> Already described Already described <eventid> </eventid> Already described Already described <dt> t11:51:01</dt> Already described Already described <code>289</code> Already described Already described <codedescription>locking OK</codedescription> Already described Already described <mode>3</mode> Already described Already described <modedescription>user KEY</modedescription> Already described Already described <statebefore>2</statebefore> Already described Already described <statebeforedescription>occupied</statebeforedescription> Already described Already described <stateafter>2</stateafter> Already described Already described <stateafterdescription>occupied</stateafterdescription> Already described Already described <card> d cfde639</card> Already described Already described </event> / / <event> Already described Already described <eventid> </eventid> Already described Already described <dt> t11:50:48</dt> Already described Already described <code>288</code> Already described Already described <codedescription>unlocking OK</codedescription> Already described Already described <mode>3</mode> Already described Already described <modedescription>user KEY</modedescription> Already described Already described <statebefore>2</statebefore> Already described Already described <statebeforedescription>occupied</statebeforedescription> Already described Already described <stateafter>0</stateafter> Already described Already described Page 4

42 XML packages Locker Info XMLlriU5.doc <stateafterdescription>vacant</stateafterdescription> Already described Already described <card> d cfde639</card> Already described Already described </event> / / </events> / / </locker> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 5

43 XML packages Locker Info XMLlriU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 6

44 XML packages Lockers Info XMLlsiU5.doc Revision: Date Comment Creation of document Lockers Info XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

45 XML packages Lockers Info XMLlsiU5.doc 1 General This XML package is sent by 3 rd party SW to obtain information (in the respective result package) about several lockers status parameters from Metra ELS system. Locations are used in locker systems where several lockers exist with the same locker number. Therefore they are assigned to different locations to enable unique treatment of each. The package is sent to Metra interface server through the Metra TCP/IP interface. Information is returned from Metra interface server in the result package. Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and additional locker parameters depending on the parameters given in the Lockers Info package. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. Page 2

46 XML packages Lockers Info XMLlsiU5.doc 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>lockersinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <location>1</location> Location ID (1-9999) of lockers integer If none is given result will contain lockers from all locations </parameters> / / <userdata>xyz</userdata> Userdata Varchar (30) Result of this XML package includes same userdata if sent here </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <lockers> Lockers / <locker> Locker / <location>5</location> Location ID (1-9999) of locker integer <locker>1</locker> Locker number integer <state>0</state> State ID Integer <statedescription>vacant</statedescription> State Description Varchar (30) In English only </locker> / / <locker> Already described Already described <location>5</location> Already described Already described Page 3

47 XML packages Lockers Info XMLlsiU5.doc <locker>2</locker> Already described Already described <state>0</state> Already described Already described <statedescription>vacant</statedescription> Already described Already described </locker> / / <locker> Already described Already described <location>5</location> Already described Already described <locker>3</locker> Already described Already described <state>0</state> Already described Already described <statedescription>vacant</statedescription> Already described Already described </locker> / / </lockers> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 4

48 XML packages Lockers Info XMLlsiU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 5

49 XML packages Locker ELS NET Sale XMLensU5.docx Locker ELS NET Sale XML package Revision: Date Comment Creation of document Added ID to result Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

50 XML packages Locker ELS NET Sale XMLensU5.docx 1 General This XML package is sent by 3 rd party SW through TCP/IP interface to make a locker reservation to a card/wristband in the Metra ELS NET system. Result Codes returned by the interface: Result codes used: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded For this XML package the result package gives the result code and ELS NET Entry unique ID from Metra DB. This ID can be used for further operations (ELS NET Info and ELS NET Free). 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. 1.2 Package Parameters Mandatory: Item Item ID, which is normally a type of locker. E.g. locker for one person, two (in ski resorts), big locker, small locker, etc. Defined in the Metra SW. Locker number Date from and to validity of the reservation Card number (s) several can be assigned to open the same locker Optional: POS and user reference for tracking and analysing reservations in Metra SW Name enables search of reservations also by name with ELS NET Info XML package Page 2

51 XML packages Locker ELS NET Sale XMLensU5.docx 2 Examples XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>lockerelsnetsale</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <pos>1</pos> Point of sale code Small integer If parameter is not given, lowest from Metra DB is used <user>2</user> User code Small integer If parameter is not given, lowest from Metra DB is used <item>lrh</item> Item ID Varchar (30) Unique Item ID from Metra SW Tables <locker>1</locker> Locker number Integer Possible values <name>john Doe</name> Name to be assigned to reservation Varchar (30) Optional, if given, reservation can be found by name also <cards> Cards / Several cards can be assigned to one locker <card> e c74cfa</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <card> e c74cea</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </cards> / / <datetimefrom> t09:50:00</datetimefrom> Date & time from Given in example Start of validity <datetimeto> t09:50:00</datetimeto> Date & time to Given in example End of validity </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Page 3

52 XML packages Locker ELS NET Sale XMLensU5.docx Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <id> </id> ELS NET Entry ID Integer Unique reference from Metra DB </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 4

53 XML packages Locker ELS NET Sale XMLensU5.docx 3 Appendix An XML file is attached to the document with same structure as the example XML package and result. Page 5

54 XML packages Unlock XMLunlU5.doc Revision: Date Comment Creation of document Revision Unlock XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

55 XML packages Unlock XMLunlU5.doc 1 General This XML package is sent by 3 rd party SW to unlock a particular locker in Metra ELS or ELS NET system. In Metra ELS NET system driven by 3 rd party SW through Metra ELS Locker reservation interface the parameter Location is not supported by the ELS NET reservation interface and therefore omitted in this XML package! In Metra ELS NET installations location is supported. Result Codes returned by the interface: Codes used in Metra interface are: ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. Page 2

56 XML packages Unlock XMLunlU5.doc 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>unlock</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <locker>555</locker> Locker number from 1 to 9999 <location>1</location> Locker location Integer Used when lockers with same numbers exist in the system </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 3

57 XML packages Unlock XMLunlU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 4

58 XML packages White List XMLwliU5.doc Revision: Date Comment Creation of document Added removeall White List XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page

59 XML packages White List XMLwliU5.doc 1 General This XML package is sent by 3 rd party SW to add/remove card/wristband to/from the White list; applies to ELS, ELS NET and LCC NET systems. Media on the white list is valid to be used on Metra ELS lockers and in general in the above mentioned systems. Packages are sent as strings through the Metra TCP/IP interface. Sent cardnumber is obtained from 3 rd party SW; it must be sent in Metra format. See document Metra_ELS_SN_Encoding.pdf. Result Codes returned by the interface: Codes used in Metra interface are: ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. Page

60 XML packages White List XMLwliU5.doc 2 Examples 2.1 Add to white list XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>whitelist</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> e eb223</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <whitelist>add</whitelist> add parameter / Card will be added to white list </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

61 XML packages White List XMLwliU5.doc 2.2 Remove from white list XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>whitelist</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> e eb223</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <whitelist>remove</whitelist> remove parameter / Card will be removed from white list </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

62 XML packages White List XMLwliU5.doc 2.3 Remove all from white list XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>whitelist</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <whitelist>removeall</whitelist> remove all parameter / All cards will be removed from white list </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

63 XML packages White List XMLwliU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page

64 THIRD-PARTY XML INTEGRATION MANUAL LCC NET PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

65 XML packages Card Info 01 XMLci1ver1.1U5.doc Revision: Date Comment Creation of document Card Info 01 XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page

66 XML packages Card Info 01 XMLci1ver1.1U5.doc 1 General This XML package is sent by 3 rd party SW to obtain information about a card/wristband from Metra NET systems. Result Codes returned by the interface: Result codes used with CardInfo01v1.1: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid cardnumber), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 (0x0) - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and parameters depending on the current status of the wristband/card. Only result code is returned if there are no additional parameters. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. Page

67 XML packages Card Info 01 XMLci1ver1.1U5.doc 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>cardinfo01</name> Package name / <version>1.1</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.1</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <functions> Functions <function>master Key</function> Master Key Varchar (36) If card is a Master Key in Metra NET system <function>multi Key</function> Multi Key Varchar (36) If card is a Multi Key in Metra NET system <function>black List</function> Black List Varchar (36) If card is on the Black List in Metra NET system <function>white List</function> White List Varchar (36) If card is on the White List in Metra NET system </functions> / / <member> Member / If card is assigned to a Member in Metra NET system <id>123456</id> Metra Member ID from Metra DB Integer <title>mr.</title> Title Varchar (30) Page

68 XML packages Card Info 01 XMLci1ver1.1U5.doc <firstname>john</firstname> First name Varchar (30) <lastname>doe</lastname> Last name Varchar (30) </member> / / <services> Services / If card has services sold to it in Metra NET system <service> Service / There can be several services sold to one card <doc> Document info / Document info for particular service <posyeardoc>14/2010/284/277</posyeardoc> Ducument id Varchar (30) Format POSid/year/document/invoice from metra DB <line>1</line> Document line Integer This service was sold on this line of given document </doc> / / <code>101</code> Service code Integer Service code from Metra tables <iditem>t20101</iditem> Item ID Varchar (36) Item ID with which this service was sold <passages> Passages / Algorithms-Check engines assignes to this card <passage> Passage / There can be check engines assigned on several passages <passageid>1</passageid> Passage ID Integer Passage ID from Metra tables <passagedescription>main entrance</passagedescription> Passage Description Varchar (36) Passage Description from Metra tables <checkengines> Check engines / Check engines assigned on this passage <checkengine> Check engine / There can be several check engines assigned on particular passage <name>dt Limits</name> Check engine name / Date time absolute limits <datetime> Date & Time limits / <from> t15:30:00</from> Timestamp from Given in example Timestamp of absolute validity begining <to> t23:59:59</to> Timestamp to Given in example Timestamp of absolute validity end </datetime> / / </checkengine> / / <checkengine> Check engine / <name>guest</name> Check engine name / If ticket is a Guest ticket. Only one at a time is possible among guest, staff, service </checkengine> / / <checkengine> Check engine / <name>service</name> Check engine name / If ticket is a Service ticket. Only one at a time is possible among guest, staff, service </checkengine> / / <checkengine> Check engine / <name>staff</name> Check engine name / If ticket is a Staff ticket. Only one at a time is possible among guest, staff, service </checkengine> / / <checkengine> Check engine / <name>locker LCC NET</name> Check engine name / Information about LCC NET lockers for the given card Page

69 XML packages Card Info 01 XMLci1ver1.1U5.doc <lockedlockers> Locked lockers / <locker> Locker / Several locked lockers are possible for one card <number>1234</number> Locker number Integer <location>1</location> Location ID Integer Same locker numbers are possible on different locations <locationdescription>ladys changing room</locationdescription> Location description Varchar (36) <dt> t09:55:00</dt> Timestamp of locking Given in example <controlunit>5</controlunit> Locker Control Unit ID Integer <controlunitdescription>ladys CU 5</controlunitdescription> Locker Control Unit description Varchar (36) </locker> / / <locker> Locker / Several locked lockers are possible for one card <number>1234</number> Locker number Integer <location>3</location> Location ID Integer Same locker numbers are possible on different locations <locationdescription>sauna</locationdescription> Location description Varchar (36) <dt> t10:55:00</dt> Timestamp of locking Given in example <controlunit>16</controlunit> Locker Control Unit ID Integer <controlunitdescription>sauna CU left</controlunitdescription> Locker Control Unit description Varchar (36) </locker> / / </lockedlockers> / / <allowedlockers> Lockers allowed for locking <locker> Locker / Several locked lockers are possible for one card <count>1</count> Number of lockers Integer Number of lockers allowed <location>1</location> Location ID Integer Same locker numbers are possible on different locations <locationdescription>ladys changing room</locationdescription> Location description Varchar (36) <lockers>1-9999</lockers> Allowed locker range Blob </locker> / / </allowedlockers> / / </checkengine> / / <checkengine> Check engine / <name>minutes</name> Check engine name / Additional charge parameters <minutes>23</minutes> Number of minutes integer Number of minutes over the predefined limit to charge for <entrance> t09:50:00</entrance> Timestamp of entrance Given in example Can be used to obtain confirmation of card entrance <item>123030</item> Item ID Varchar (36) Item ID with additional payment interval; Item ID 123 with interval 030 min </checkengine> / / <checkengine> Check engine / Page

70 XML packages Card Info 01 XMLci1ver1.1U5.doc <name>refund</name> Check engine name / Refund charge parameters <minutes>23</minutes> Number of minutes integer Number of minutes to the predefined limit to refund <entrance> t09:50:00</entrance> Timestamp of entrance Given in example Can be used to obtain confirmation of card entrance <item>123030</item> Item ID Varchar (36) Item ID with refund interval; Item ID 123 with interval 030 min </checkengine> / / <checkengine> Check engine / <name>points</name> Check engine name / Points <dt> t09:50:00</dt> Timestamp of last entrance Given in example Can be used to obtain confirmation of last card entrance <used>3</used> Used points Integer <total>10</total> Total defined points Integer </checkengine> / / <checkengine> Check engine / <name>daily Points</name> Check engine name / Daily Points <dt> t09:50:00</dt> Timestamp of last entrance Given in example Can be used to obtain confirmation of last card entrance <used>2</used> Used points Integer <total>3</total> Total defined points Integer </checkengine> / / <checkengine> Check engine / <name>daily Minutes</name> Check engine name / Daily minutes <minutes>23</minutes> Number of minutes integer Number of minutes to the predefined limit to refund <entrance> t09:50:00</entrance> Timestamp of entrance Given in example Can be used to obtain confirmation of card entrance <item>123030</item> Item ID Varchar (36) Item ID with additional payment interval; Item ID 123 with interval 030 min </checkengine> / / <checkengine> Check engine / <name>daily Minutes Gross</name> Check engine name / <minutes>23</minutes> Number of minutes integer Number of minutes to the predefined limit to refund <entrance> t09:50:00</entrance> Timestamp of entrance Given in example Can be used to obtain confirmation of card entrance <item>123030</item> Item ID Varchar (36) Item ID with additional payment interval; Item ID 123 with interval 030 min </checkengine> / / <checkengine> Check engine / <name>entrance Time A</name> Check engine name / Entrance Time A <time> Entrance Time limits <from>07:00:00</from> Time of day from Given in example Entrance time beggining of validity <to>17:00:00</to> Time of day to Given in example Entrance time end of validity Page

71 XML packages Card Info 01 XMLci1ver1.1U5.doc </time> / / <dayofweek>monday, tuesday, wednesday</dayofweek> Day of week Varchar (100) Day of week when valid <date> Date limits <from> </from> Date from Given in example Entrance date beggining of validity <to> </to> Date to Given in example Entrance date end of validity </date> / / </checkengine> / / <checkengine> Check engine / <name>entrance Time B</name> Check engine name / Entrance Time B <time> Entrance Time limits <from>07:00:00</from> Time of day from Given in example Entrance time beggining of validity <to>17:00:00</to> Time of day to Given in example Entrance time end of validity </time> / / <dayofweek>monday, tuesday, wednesday</dayofweek> Day of week Varchar (100) Day of week when valid <date> Date limits <from> </from> Date from Given in example Entrance date beggining of validity <to> </to> Date to Given in example Entrance date end of validity </date> / / </checkengine> / / <checkengine> Check engine / <name>entrance Delay</name> Check engine name / Delay between consecutive entrances <minutes>5</minutes> Defined number of minutes Integer </checkengine> / / <checkengine> Check engine / <name>first Day</name> Check engine name / First Day Entrance time; for long term tickets <time> Entrance Time limits <from>07:00:00</from> Time of day from Given in example Entrance time beggining of validity for first day <to>17:00:00</to> Time of day to Given in example Entrance time end of validity for first day </time> / / </checkengine> / / <checkengine> Check engine / <name>last Day</name> Check engine name / Last Day Entrance time; for long term tickets <time> Entrance Time limits <from>07:00:00</from> Time of day from Given in example Entrance time beggining of validity for last day Page

72 XML packages Card Info 01 XMLci1ver1.1U5.doc <to>17:00:00</to> Time of day to Given in example Entrance time end of validity for last day </time> / / </checkengine> / / <checkengine> Check engine / <name>capture</name> Check engine name / Ticket is to be captured on exit when other parameters allow it </checkengine> / / <checkengine> Check engine / <name>exit Counter</name> Check engine name / Exit Counter is enabled; exit must be made before next entrance and vice versa </checkengine> / / <checkengine> Check engine / <name>validate Ring Entrance</name> Check engine name / If ring entrance is not made, entrance, locking or spending is denied </checkengine> / / <checkengine> Check engine / <name>borrow</name> Check engine name / Items are borrowed to this card <items> Borrowed Items / <item> Borrowed Item / Several items are possible for borrow <description>towel</description> Item description Varchar (36) <doc> Document info / Document info for particular item <posyeardoc>14/2010/284/277</posyeardoc> Ducument id Varchar (30) Format POSid/year/document/invoice from metra DB <line>1</line> Document line Integer This service was sold on this line of given document </doc> / / </item> / / </items> / / </checkengine> / / <checkengine> Check engine / <name>deposit</name> Check engine name / Deposit is made for this card <item> Deposit Item / <value>10</value> Item value Integer <doc> Document info / Document info for deposit <posyeardoc>14/2010/284/277</posyeardoc> Ducument id Varchar (30) Format POSid/year/document/invoice from metra DB <line>2</line> Document line Integer This service was sold on this line of given document </doc> / / </item> / / </checkengine> / / Page

73 XML packages Card Info 01 XMLci1ver1.1U5.doc <checkengine> Check engine / <name>delivery</name> Check engine name / Delivery to card <allowdeliverylimit>50</allowdeliverylimit> Limit Integer Credit value <electronicmoney>50</electronicmoney> Electroni money Integer Debit value <spent>70</spent> Spent amount Integer <available>30</available> Available amount Integer </checkengine> / / </checkengines> / / </passage> / / </passages> / / </service> / / </services> / / <events> Events / <event> Event / Events of last card lifecycle is given <eventid> </eventid> Event id Integer Unique event id from Metra DB <dt> t09:50:00</dt> Timestamp of event Given in example <code>250</code> Event Code Integer See table of available event codes <codedescription>deny</codedescription> Event description Varchar (36) See table of available event descriptions <mode>24</mode> Mode of event Code Integer See table of available mode codes <modedescription>locker</modedescription> Mode of event description Varchar (36) Defined in Metra SW <iddevice>301</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) <devicedescription>left 3R</devicedescription> Device description Varchar (36) Defined in Metra SW <passageid>1</passageid> Passage ID Integer Passage ID from Metra tables <passagedescription>main entrance</passagedescription> Passage Description Varchar (36) Passage Description from Metra tables <direction>exit</direction> Device direction Varchar (36) Defined in Metra SW (entrance or exit) </event> / / <event> Event / Events of last card lifecycle is given <eventid> </eventid> Event id Integer Unique event id from Metra DB <dt> t09:40:00</dt> Timestamp of event Given in example <code>100</code> Event Code Integer See table of available event codes <codedescription>card</codedescription> Event description Varchar (36) See table of available event descriptions <mode>1</mode> Mode of event Code Integer See table of available mode codes <modedescription>user key</modedescription> Mode of event description Varchar (36) Defined in Metra SW <iddevice>102</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) Page

74 XML packages Card Info 01 XMLci1ver1.1U5.doc <devicedescription>cu 102</devicedescription> Device description Varchar (36) Defined in Metra SW <idpassage>1</idpassage> Passage ID Integer Passage ID from Metra tables <passagedescription>main entrance</passagedescription> Passage Description Varchar (36) Passage Description from Metra tables <idlocation>1</idlocation> Location ID Integer Same locker numbers are possible on different locations <locationdescription>ladys changing room</locationdescription> Location description Varchar (36) <locker>1</locker> Locker number Integer </event> / / </events> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

75 XML packages Card Info 01 XMLci1ver1.1U5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page

76 XML packages Card Info 01 XMLci1ver1.2U5.docx Card Info 01 v1.2 XML package Revision: Date Comment Creation of document Added Delivered Items Added <UID> and <tax2> in result and new filter in package <mode> Copyright 2014 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

77 XML packages Card Info 01 XMLci1ver1.2U5.docx 1 General This XML package is sent by 3 rd party SW to obtain information about a card/wristband from Metra NET systems. Result Codes returned by the interface: Result codes used with CardInfo01v1.1: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid cardnumber), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 (0x0) - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and parameters depending on the current status of the wristband/card. Only result code is returned if there are no additional parameters. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. 1.2 Mode Using mode tag enables narrowing the result data to desired contents. Can be used to save bandwidth in slower networks or over Wi-Fi. Supported modes are Services and Events. Listing one or the other will narrow the result contents to the respective section. Omitting the tag all together results in all contents being listed in the result. Page 2

78 XML packages Card Info 01 XMLci1ver1.2U5.docx 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>cardinfo01</name> Package name / <version>1.2</version> Version / </header> / / <parameters> Parameters / <card> d b46b41fe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <mode>services,events</mode> Mode Varchar (36) Select sections to be returned in result; if omitted, all is returned </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.2</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <functions> Functions <function>master Key</function> Master Key Varchar (36) If card is a Master Key in Metra NET system <function>multi Key</function> Multi Key Varchar (36) If card is a Multi Key in Metra NET system <function>black List</function> Black List Varchar (36) If card is on the Black List in Metra NET system <function>white List</function> White List Varchar (36) If card is on the White List in Metra NET system </functions> / / <member> Member / If card is assigned to a Member in Metra NET system <id>123456</id> Metra Member ID from Metra DB Integer Page 3

79 XML packages Card Info 01 XMLci1ver1.2U5.docx <title>mr.</title> Title Varchar (30) <firstname>john</firstname> First name Varchar (30) <lastname>doe</lastname> Last name Varchar (30) </member> / / <services> Services / If card has services sold to it in Metra NET system <service> Service / There can be several services sold to one card <doc> Document info / Document info for particular service <posyeardoc>14/2010/284/277</posyeardoc> Ducument id Varchar (30) Format POSid/year/document/invoice from metra DB <uid> </uid> External UID Varchar(64) Shown if sent with ItemIssue XML package <line>1</line> Document line Integer This service was sold on this line of given document </doc> / / <code>101</code> Service code Integer Service code from Metra tables <iditem>t20101</iditem> Item ID Varchar (36) Item ID with which this service was sold <passages> Passages / Algorithms-Check engines assignes to this card <passage> Passage / There can be check engines assigned on several passages <passageid>1</passageid> Passage ID Integer Passage ID from Metra tables <passagedescription>main entrance</passagedescription> Passage Description Varchar (36) Passage Description from Metra tables <checkengines> Check engines / Check engines assigned on this passage <checkengine> Check engine / There can be several check engines assigned on particular passage <name>dt Limits</name> Check engine name / Date time absolute limits <datetime> Date & Time limits / <from> t15:30:00</from> Timestamp from Given in example Timestamp of absolute validity begining <to> t23:59:59</to> Timestamp to Given in example Timestamp of absolute validity end </datetime> / / </checkengine> / / <checkengine> Check engine / <name>guest</name> Check engine name / </checkengine> / / <checkengine> Check engine / <name>service</name> Check engine name / </checkengine> / / <checkengine> Check engine / If ticket is a Guest ticket. Only one at a time is possible among guest, staff, service If ticket is a Service ticket. Only one at a time is possible among guest, staff, service Page 4

80 XML packages Card Info 01 XMLci1ver1.2U5.docx <name>staff</name> Check engine name / </checkengine> / / <checkengine> Check engine / If ticket is a Staff ticket. Only one at a time is possible among guest, staff, service <name>locker LCC NET</name> Check engine name / Information about LCC NET lockers for the given card <lockedlockers> Locked lockers / <locker> Locker / Several locked lockers are possible for one card <number>1234</number> Locker number Integer <location>1</location> Location ID Integer Same locker numbers are possible on different locations <locationdescription>ladys changing room</locationdescription> Location description Varchar (36) <dt> t09:55:00</dt> Timestamp of locking Given in example <controlunit>5</controlunit> Locker Control Unit ID Integer <controlunitdescription>ladys CU 5</controlunitdescription> Locker Control Unit description Varchar (36) </locker> / / <locker> Locker / Several locked lockers are possible for one card <number>1234</number> Locker number Integer <location>3</location> Location ID Integer Same locker numbers are possible on different locations <locationdescription>sauna</locationdescription> Location description Varchar (36) <dt> t10:55:00</dt> Timestamp of locking Given in example <controlunit>16</controlunit> Locker Control Unit ID Integer <controlunitdescription>sauna CU left</controlunitdescription> Locker Control Unit description Varchar (36) </locker> / / </lockedlockers> / / <allowedlockers> Lockers allowed for locking <locker> Locker / Several locked lockers are possible for one card <count>1</count> Number of lockers Integer Number of lockers allowed <location>1</location> Location ID Integer Same locker numbers are possible on different locations <locationdescription>ladys changing room</locationdescription> Location description Varchar (36) <lockers>1-9999</lockers> Allowed locker range Blob </locker> / / </allowedlockers> / / </checkengine> / / <checkengine> Check engine / Page 5

81 XML packages Card Info 01 XMLci1ver1.2U5.docx <name>minutes</name> Check engine name / Additional charge parameters <minutes>23</minutes> Number of minutes integer Number of minutes over the predefined limit to charge for <entrance> t09:50:00</entrance> Timestamp of entrance Given in example Can be used to obtain confirmation of card entrance <item>123030</item> Item ID Varchar (36) Item ID with additional payment interval; Item ID 123 with interval 030 min </checkengine> / / <checkengine> Check engine / <name>refund</name> Check engine name / Refund charge parameters <minutes>23</minutes> Number of minutes integer Number of minutes to the predefined limit to refund <entrance> t09:50:00</entrance> Timestamp of entrance Given in example Can be used to obtain confirmation of card entrance <item>123030</item> Item ID Varchar (36) Item ID with refund interval; Item ID 123 with interval 030 min </checkengine> / / <checkengine> Check engine / <name>points</name> Check engine name / Points <dt> t09:50:00</dt> Timestamp of last entrance Given in example Can be used to obtain confirmation of last card entrance <used>3</used> Used points Integer <total>10</total> Total defined points Integer </checkengine> / / <checkengine> Check engine / <name>daily Points</name> Check engine name / Daily Points <dt> t09:50:00</dt> Timestamp of last entrance Given in example Can be used to obtain confirmation of last card entrance <used>2</used> Used points Integer <total>3</total> Total defined points Integer </checkengine> / / <checkengine> Check engine / <name>daily Minutes</name> Check engine name / Daily minutes <minutes>23</minutes> Number of minutes integer Number of minutes to the predefined limit to refund <entrance> t09:50:00</entrance> Timestamp of entrance Given in example Can be used to obtain confirmation of card entrance <item>123030</item> Item ID Varchar (36) Item ID with additional payment interval; Item ID 123 with interval 030 min </checkengine> / / <checkengine> Check engine / <name>daily Minutes Gross</name> Check engine name / <minutes>23</minutes> Number of minutes integer Number of minutes to the predefined limit to refund <entrance> t09:50:00</entrance> Timestamp of entrance Given in example Can be used to obtain confirmation of card entrance <item>123030</item> Item ID Varchar (36) Item ID with additional payment interval; Item ID 123 with interval 030 min Page 6

82 XML packages Card Info 01 XMLci1ver1.2U5.docx </checkengine> / / <checkengine> Check engine / <name>entrance Time A</name> Check engine name / Entrance Time A <time> Entrance Time limits <from>07:00:00</from> Time of day from Given in example Entrance time beggining of validity <to>17:00:00</to> Time of day to Given in example Entrance time end of validity </time> / / <dayofweek>monday, tuesday, wednesday</dayofweek> Day of week Varchar (100) Day of week when valid <date> Date limits <from> </from> Date from Given in example Entrance date beggining of validity <to> </to> Date to Given in example Entrance date end of validity </date> / / </checkengine> / / <checkengine> Check engine / <name>entrance Time B</name> Check engine name / Entrance Time B <time> Entrance Time limits <from>07:00:00</from> Time of day from Given in example Entrance time beggining of validity <to>17:00:00</to> Time of day to Given in example Entrance time end of validity </time> / / <dayofweek>monday, tuesday, wednesday</dayofweek> Day of week Varchar (100) Day of week when valid <date> Date limits <from> </from> Date from Given in example Entrance date beggining of validity <to> </to> Date to Given in example Entrance date end of validity </date> / / </checkengine> / / <checkengine> Check engine / <name>entrance Delay</name> Check engine name / Delay between consecutive entrances <minutes>5</minutes> Defined number of minutes Integer </checkengine> / / <checkengine> Check engine / <name>first Day</name> Check engine name / First Day Entrance time; for long term tickets <time> Entrance Time limits <from>07:00:00</from> Time of day from Given in example Entrance time beggining of validity for first day <to>17:00:00</to> Time of day to Given in example Entrance time end of validity for first day Page 7

83 XML packages Card Info 01 XMLci1ver1.2U5.docx </time> / / </checkengine> / / <checkengine> Check engine / <name>last Day</name> Check engine name / Last Day Entrance time; for long term tickets <time> Entrance Time limits <from>07:00:00</from> Time of day from Given in example Entrance time beggining of validity for last day <to>17:00:00</to> Time of day to Given in example Entrance time end of validity for last day </time> / / </checkengine> / / <checkengine> Check engine / <name>capture</name> Check engine name / Ticket is to be captured on exit when other parameters allow it </checkengine> / / <checkengine> Check engine / <name>exit Counter</name> Check engine name / Exit Counter is enabled; exit must be made before next entrance and vice versa </checkengine> / / <checkengine> Check engine / <name>validate Ring Entrance</name> Check engine name / If ring entrance is not made, entrance, locking or spending is denied </checkengine> / / <checkengine> Check engine / <name>borrow</name> Check engine name / Items are borrowed to this card <items> Borrowed Items / <item> Borrowed Item / Several items are possible for borrow <description>towel</description> Item description Varchar (36) <doc> Document info / Document info for particular item <posyeardoc>14/2010/284/277</posyeardoc> Ducument id Varchar (30) Format POSid/year/document/invoice from metra DB <line>1</line> Document line Integer This service was sold on this line of given document </doc> / / </item> / / </items> / / </checkengine> / / <checkengine> Check engine / <name>deposit</name> Check engine name / Deposit is made for this card <items> Deposit Items / <item> Deposit Item Page 8

84 XML packages Card Info 01 XMLci1ver1.2U5.docx <value>10</value> Item value Integer <doc> Document info / Document info for deposit <posyeardoc>14/2010/284/277</posyeardoc> Ducument id Varchar (30) Format POSid/year/document/invoice from metra DB <line>2</line> Document line Integer This service was sold on this line of given document </doc> / / </item> / / </items> / / </checkengine> / / <checkengine> Check engine / <name>allow Delivery</name> Check engine name / Delivery to card <limit>5000</limit> Limit Integer Credit value </checkengine> / / </checkengines> / / </passage> / / </passages> / / </service> / / <service> Service / There can be several services sold to one card <doc> Document info / Document info for particular service <posyeardoc>21/2012/77</posyeardoc> Ducument id Varchar (30) Format POSid/year/document/invoice from metra DB <uid> </uid> External UID Varchar(64) Shown if sent with CardDelivery XML package <line>0</line> Document line Integer This service was sold on this line of given document </doc> / / <code>0</code> Service code Integer Service code from Metra tables <iditem></iditem> Item ID Varchar (36) Item ID with which this service was sold <passages> Passages / Algorithms-Check engines assignes to this card <passage> Passage / There can be check engines assigned on several passages <passageid>0</passageid> Passage ID Integer Passage ID from Metra tables <passagedescription></passagedescription> Passage Description Varchar (36) Passage Description from Metra tables <checkengines> Check engines / Check engines assigned on this passage <checkengine> Check engine / There can be several check engines assigned on particular passage <name>delivery</name> Check engine name / Deliveries made to the RFID media <posyeardoc>21/2012/77</posyeardoc> Ducument id Varchar (30) Format POSid/year/document/invoice from metra DB <uid> </uid> External UID Varchar(64) Shown if sent with CardDelivery XML package <items> Items / Delivered Items Page 9

85 XML packages Card Info 01 XMLci1ver1.2U5.docx <item> Item / <id>fx50a</id> Unique Item ID Varchar (36) <export>t1f</export> Unique Item export ID Varchar (30) <idservice>5018</idservice> Unique service ID Integer <servicegroup> Service group / <id>103</id> Service group ID Integer <export>t1f</export> Service group export ID Varchar (30) </servicegroup> / / <num>1</num> Number of items Integer <price>7</price> Item price of one Item Decimal (15,4) <discount> Discount / <id>2</id> Discount code Integer <rate>20</rate> Discount rate Double precision <value>1.4</value> Discount value for one Item Decimal (15,4) <export>d2</export> Unique Discount export ID Varchar (30) </discount> / / Item value of one Item incl. <value>5.6</value> discount Decimal (15,4) <tax> Tax / <id>1</id> Tax code Integer <export>1</export> Unique Tax export ID Varchar (30) <rate>8.5</rate> Tax rate Double precision <value>0.44</value> Tax value for one Item Decimal (15,4) </tax> / / <tax2> Tax2 / <id>1</id> Already described / <export></export> Already described / <rate></rate> Already described / <value></value> Already described / </tax2> / / </item> / / Can be freely changed in Metra SW to enable id sync between Metra SW and 3rd party SW Can be freely changed in Metra SW to enable id sync between Metra SW and 3rd party SW Dicount can be without code. If discounts are not predefined and rate can be defined freely Dicount can be without export ID. If discounts are not predefined and rate can be defined freely Can be freely changed in Metra SW to enable id sync between Metra SW and 3rd party SW If dual taxes are used in Metra SW; both taxes are calculated and added to same nett price Can be freely changed in Metra SW to enable id sync between Metra SW and 3rd party SW Page 10

86 XML packages Card Info 01 XMLci1ver1.2U5.docx <item> Already described / <id>dr0102</id> Already described / <export>t1f</export> Already described / <idservice>1007</idservice> Already described / <servicegroup> Already described / <id>105</id> Already described / <export>t1f</export> Already described / </servicegroup> Already described / <num>1</num> Already described / <price>4</price> Already described / <discount> Already described / <id>2</id> Already described / <rate>20</rate> Already described / <value>0.8</value> Already described / <export>d2</export> Already described / </discount> Already described / <value>3.2</value> Already described / <tax> Already described / <id>1</id> Already described / <export>1</export> Already described / <rate>8.5</rate> Already described / <value>0.25</value> Already described / </tax> / / </item> / / </items> / / </checkengine> / / </checkengines> / / </passage> / / </passages> / / </service> / / </services> / / <events> Events / <event> Event / Events of last card lifecycle are given <eventid> </eventid> Event id Integer Unique event id from Metra DB Page 11

87 XML packages Card Info 01 XMLci1ver1.2U5.docx <dt> t09:50:00</dt> Timestamp of event Given in example <code>250</code> Event Code Integer See table of available event codes <codedescription>deny</codedescription> Event description Varchar (36) See table of available event descriptions <mode>24</mode> Mode of event Code Integer See table of available mode codes <modedescription>locker</modedescription> Mode of event description Varchar (36) Defined in Metra SW <iddevice>301</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) <devicedescription>left 3R</devicedescription> Device description Varchar (36) Defined in Metra SW <passageid>1</passageid> Passage ID Integer Passage ID from Metra tables <passagedescription>main entrance</passagedescription> Passage Description Varchar (36) Passage Description from Metra tables <direction>exit</direction> Device direction Varchar (36) Defined in Metra SW (entrance or exit) </event> / / <event> Event / Events of last card lifecycle is given <eventid> </eventid> Event id Integer Unique event id from Metra DB <dt> t09:40:00</dt> Timestamp of event Given in example <code>100</code> Event Code Integer See table of available event codes <codedescription>card</codedescription> Event description Varchar (36) See table of available event descriptions <mode>1</mode> Mode of event Code Integer See table of available mode codes <modedescription>user key</modedescription> Mode of event description Varchar (36) Defined in Metra SW <iddevice>102</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) <devicedescription>cu 102</devicedescription> Device description Varchar (36) Defined in Metra SW <idpassage>1</idpassage> Passage ID Integer Passage ID from Metra tables <passagedescription>main entrance</passagedescription> Passage Description Varchar (36) Passage Description from Metra tables <idlocation>1</idlocation> Location ID Integer Same locker numbers are possible on different locations <locationdescription>ladys changing room</locationdescription> Location description Varchar (36) <locker>1</locker> Locker number Integer </event> / / </events> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 12

88 XML packages Card Info 01 XMLci1ver1.2U5.docx 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 13

89 XML packages Event Info XMLeviU5.doc Event Info XML package v1.0 Revision: Date Comment Creation of document Revision Revision Added new events and modes to list of events and modes Added MEW DAT additional events Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

90 XML packages Event Info XMLeviU5.doc 1 General This XML package is sent by Metra SW to 3 rd party SW to give event information of events that happen in Metra systems. These events are sent online in real time. Also they are queued in Metra DB if communication is not possible at the time of event, so they are sent later when connection is re-established. Which events are sent can be filtered in the Metra SW to avoid unnecessary traffic with info not needed. Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. It must be sent by 3 rd party SW, else event is queued and sent again later. Page 2

91 XML packages Event Info XMLeviU5.doc 2 Example XML package - entrance Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>eventinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <event> Event / <eventid> </eventid> Event id Integer Unique event id from Metra DB <card> d e634162</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <dt> t09:40:00</dt> Date & time of event Given in example DT as recorded in Metra DB <code>30</code> Event Code Integer 30 for locking, 40 for unlocking, <codedescription>locking</codedescription> Event description Varchar (36) Locking, Unlocking, <mode>1</mode> Mode of event Code Integer 1, 5 or 71, see below for respective descriptions <modedescription>user key</modedescription> Mode of event description Varchar (36) USER key, MASTER key, DELIVERY key <iddevice>102</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) <devicedescription>cu 102</devicedescription> Device description from Metra tables Varchar (36) <locker>1234</locker> Locker number Integer <idlocation>1</idlocation> Location ID Integer Same locker numbers are possible on different locations <locationdescription>lobby</locationdescription> Location description Varchar (36) </event> / / </parameters> / / </package> / / Page 3

92 XML packages Event Info XMLeviU5.doc Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / </package> / / Page 4

93 XML packages Event Info XMLeviU5.doc 3 Events and Modes Not all events or modes apply to all integration scenarios. 3.1 Events 1 Read wristband, CardInfo01 2 Card Issue 3 Procedure (Points, Tokens, Borrow), Repair, Exit, Entrance 4 Erase wristband, Tickets erase 5 Barcode 6 External 7 Member Export 8 Member Import 10 Entrance 12 Entrance Denied 20 Exit 22 Exit Denied 30 Locking OK 31 Payed Locking OK 32 Locking Denied 33 Locking failed 34 Locking/Unlocking Error 40 Unlocking OK 43 Unlocking failed 49 Unlocking OK - Alarm Delay 50 Passage 52 Passage Denied 60 Push-button 61 Do Not Disturb 62 Make my Room 63 Room Cleaned 64 Reception Request 70 Deposit Activated 75 Deposit Deactivated 90 ALARM 91 Supervised locker break-in 100 Card 101 PIN 102 External / Remote 120 Card - Deposit 200 OK 201 Set Pay 202 Reset Pay 203 Activate Deposit 204 Deactivate Deposit 250 Denied 251 Wrong Reader Unit 252 Deposit Denied 300 Coin accepted 301 Temporary saldo erased 320 Vending OK 321 Vending Error 401 Locker closed after prelock Page 5

94 XML packages Event Info 402 Locker closed after unlocking 403 Locker opened after warning 404 Locker remained prelocked 405 +UWT 406 Prelocking not confirmed 450 "Pin" temporarily inhibited 451 "CodE" temporarily inhibited 452 "Scod" temporarily inhibited 460 Prelocking inhibited 490 Unlock request accepted 500 Free passage ON 501 Free passage OFF 510 Signal Alarm 511 Signal Armed ON 512 Signal Armed OFF 513 Signal PIN 514 Signal Test 515 Alarm Sensor Activated 516 Alarm Sensor Deactivated 517 Door Unlocked 518 Door Locked 519 Door Opened 520 Door Closed 521 Entrance Deactivated 522 Exit Deactivated 601 Update sold Tickets 602 Assign Procedure 603 Unlocking request 604 ELS Key Exchange Request 605 ELS Key Exchange Answer 606 WBC Closed After Timeout 607 Buyer Export 608 Buyer Import 609 Settle All Cards 610 External Payment 611 SMS Interface 612 S.M.SW Member Import 613 S.M.SW Locker ELS NET Export 614 WBC Closed 900 Power ON 901 General interrogation received 902 Start responding 903 Stop responding 904 Start multiple responses 905 Stop multiple responses 910 Time Set 911 New Time 912 Summer Time 913 Winter Time 920 Box Opened 921 Box Closed 930 Operating parameters OK 931 Operating parameters constructional 932 Requested initialization XMLeviU5.doc Page 6

95 XML packages Event Info 933 Automatic initialization 940 Error Terminated 941 Error 953 Coin acceptor start responding 954 Coin acceptor stop responding 960 SECURE Card 961 DOWNLOAD Card 962 SERVICE Card 963 CLEAN Card 964 ERASE Card 965 WARD Card 966 MASTER key 967 FAILSAFE key 990 Buffer overrun 999 State XMLeviU5.doc Page 7

96 XML packages Event Info XMLeviU5.doc 3.2 Modes 1 User Key 2 Ticket 3 Ticket Captured 4 Multi user key 5 MASTER key 6 MULTI key 7 FAILSAFE key 8 Push-button 9 ALARM 10 Entrance 11 Passage 12 Date 13 Time 14 Last Day 15 Day 16 Points 17 D Points 18 Direction 19 Not Valid 20 Exit 21 Tokens 22 MINI Card 23 Entrance delay 24 Locker 25 Add Charge 26 Refund 27 Borrow/PAY 28 Exit Counter 29 Cancelled LCC Card 30 Cancelled LCC Ticket 31 Denied LCC Ticket 32 Device Break-in 33 Door Break-in 34 Door Opened too long 35 Borrow 36 Delivery 37 Deny Exit 38 Electronic Money 39 WBC Full 40 Deposit 41 Maid key 42 OFF 43 ON 44 External 45 Busy 46 Minutes 47 Ring 48 Unfinished Document 49 Entrance Time Date 50 Passage 51 Child Page 8

97 XML packages Event Info XMLeviU5.doc 52 Pay Set 53 Pay Reset 54 Pay Set/Reset 55 Request 56 Answer 57 Event 58 One passage 59 Permanent Passage Change 60 First Day 61 Key denied 62 Not payed 63 User abort 64 Prelock 65 Timeout 66 Opened 67 Card Removed 68 D Minutes 69 D Minutes Gross 70 Clock 71 DELIVERY key 72 Delivery Not Possible 73 Extra 74 Group ticket 80 Motor error 81 "Err1" 82 "Err2" 85 Power off 86 Download required 87 File updated 90 Service required 91 Reader 1 92 Reader 2 95 Serial channel 97 Direct port 99 Unknown 101 Package 102 Result 111 EMERGENCY Key 112 Secret Code 113 Master Code 114 Network Time Table 115 Network Pushbutton 116 Automatic Opening 117 Pushbutton PCB 118 Door Opened 119 Free 120 Permanent key 121 Additional Payment 122 Occupy 123 Release Page 9

98 XML packages Event Info XMLeviU5.doc 4 Appendix An XML file is attached to the document which is same as the example XML package. Page 10

99 XML packages Exit XMLexiU5.doc Exit XML package Revision: Date Comment Creation of document Revision Revision; correction of clerical mistakes Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page

100 XML packages Exit XMLexiU5.doc 1 General This XML package is sent by 3 rd party SW to deny or allow exit to a card/wristband in the Metra LCC NET or LCC NET MF system. When items are purchased to an account in 3 rd party SW (which is linked to a unique card/wristband number), exit from the system is denied by sending this package. When the account is settled by payment this same package (with different parameter) is sent to allow exit from the system. Error Codes returned by the interface: Codes used in Metra interface are: ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. Page

101 XML packages Exit XMLexiU5.doc 2 Example 2.1 Deny Exit XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>exit</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <exit>deny</exit> Deny exit parameter Varchar (36) Exit will be denied for given card </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

102 XML packages Exit XMLexiU5.doc 2.2 Allow Exit XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>exit</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <exit>allow</exit> Allow exit parameter Varchar (36) Exit will be allowed again for given card </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

103 XML packages Exit XMLexiU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page

104 XML packages Event XMLeve11U5.doc Event XML package v1.1 Revision: Date Comment Creation of document Table of modes added Corrections in event id, added samples Correction of tags Added DT parameter Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page

105 XML packages Event XMLeve11U5.doc 1 General This XML package is sent by Metra SW to 3 rd party SW to give event information about a certain wristband/media in the Metra LCC NET system. Info about entrance to the system, exit and wristband capture before exit from the system is available. Also all wristbands denied are send with the reason (mode). Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. Page

106 XML packages Event XMLeve11U5.doc 2 Example XML package - entrance Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>event</name> Package name / <version>1.1</version> Version / </header> / / <parameters> Parameters / <card> d e634162</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <iddevice>301</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) <idpassage>1</idpassage> Passage id assigned to device Integer Defined in Metra SW (1-9999) <direction>exit</direction> Device direction Varchar (36) Defined in Metra SW (entrance or exit) <event> Event / <eventid> </eventid> Event id Integer Unique event id from Metra DB <dt> t09:50:00</dt> Date & time of event Given in example DT as recorded in Metra DB <code>250</code> Event Code Integer 10 for entrance, 20 for exit or 250 for Deny <codedescription>deny</codedescription> Event description Varchar (36) Enter, Exit or Deny <mode>24</mode> Mode of event Code Integer See table of available mode codes <modedescription>locker</modedescription> Mode of event description Varchar (36) See table of available mode descriptions </event> / / </parameters> / / </package> / / Page

107 XML packages Event XMLeve11U5.doc Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.1</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / </package> / / Page

108 XML packages Event XMLeve11U5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. 3.1 Possible mode codes Mainly apply to Deny event. 3 Capture 11 Location 12 Date 13 Time 14 Last Day 15 Day 16 Points 17 D Points 18 Direction 19 Not Valid 20 Exit 21 Tokens 23 Entrance delay 24 Locker 25 Add Charge 26 Refund 27 Borrow/PAY 28 Exit Counter 29 Cancelled Card 35 Borrow 36 Delivery 37 Deny Exit 38 Electronic Money 39 WBC Full 44 External 45 Busy 46 Minutes 47 Ring Note: Only mode Capture is sent without event code or description; only mode code and mode description. 3.2 Sample packeges Deny Not Valid on entrance <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d c4ce739</card> <iddevice>333</iddevice> <idpassage>1</idpassage> <direction>entrance</direction> <event> <eventid> </eventid> <code>250</code> <codedescription>deny</codedescription> <mode>19</mode> <modedescription>notvalid</modedescription> </event> </parameters> </package> Deny Locker on exit <?xml version="1.0" encoding="utf-8" standalone="yes"?> Page

109 XML packages Event <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d e634162</card> <iddevice>301</iddevice> <idpassage>1</idpassage> <direction>exit</direction> <event> <eventid> </eventid> <code>250</code> <codedescription>deny</codedescription> <mode>24</mode> <modedescription>locker</modedescription> </event> </parameters> </package> XMLeve11U5.doc Enter <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d c4ce739</card> <iddevice>333</iddevice> <idpassage>1</idpassage> <direction>entrance</direction> <event> <eventid> </eventid> <code>10</code> <codedescription>enter</codedescription> </event> </parameters> </package> Exit <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d d4de739</card> <iddevice>301</iddevice> <idpassage>1</idpassage> <direction>exit</direction> <event> <eventid> </eventid> <code>20</code> <codedescription>exit</codedescription> </event> </parameters> </package> Capture & Exit (note 2 packages!) First Capture: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d c4ce739</card> <iddevice>301</iddevice> <idpassage>1</idpassage> <direction>exit</direction> Page

110 XML packages Event <event> <eventid> </eventid> <mode>3</mode> <modedescription>capture</modedescription> </event> </parameters> </package> Follwed by Exit: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d c4ce739</card> <iddevice>301</iddevice> <idpassage>1</idpassage> <direction>exit</direction> <event> <eventid> </eventid> <code>20</code> <codedescription>exit</codedescription> </event> </parameters> </package> XMLeve11U5.doc Page

111 XML packages External XMLextU5.docx External XML package Revision: Date Comment Creation of document Revision New parameters added; iddevice, idpassage, Lockers, WBC New parameter added: data Added PIN functionality Typo corrections idpassage->passage, iddevice->device MDB typo and explanation added Added captureonlysignal and allowonlysignal Copyright 2014 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

112 XML packages External XMLextU5.docx 1 General These XML package is sent to 3 rd party SW through Metra TCP/IP interface to perform external authorisation of action based on different parameters. E.g. acquire authorisation for some passage or door, acquire action for wristband collector (capture wristband) or drive a MDB vending machine. Result Codes returned by the interface: Codes used in Metra interface and expected from 3 rd party SW are: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded Not all fields in the Result package that are generated by 3 rd party SW are mandatory. Different scenarios are explained in the following chapters. 1.1 Communication In order to map a result XML package from the 3 rd party SW to a sent XML package from Metra SW it is mandatory to implement <userdata\> tag. It can contain up to Varchar (36) value. 3 rd party SW must echo the userdata string from the sent XML package in the respective Result package. This allows for unique identification of a Result in multithread scenarios. 1.2 Driving access control devices including Wristband Collector (WBC) When a wristband is presented to a Metra access control device reader or WBC (which is incorporated in Turnstile access terminal - TAT), and it is defined to be externally authorised, a package is sent with the parameters card, ID of the device, ID of the passage the device is defined in (Metra SW tables), device direction, Lockers locked with this card and WBC state (if presented to WBC). If reading of Mifare card contents is turned on (access key and sector information is needed in Metra SW), the package includes also data read from the card; in tag <data\>; length of tag contents varies due to number of selected sectors to be read. If the device is an exit device from the system and there are lockers locked with presented card, the package will carry this information and exit can be automatically denied by 3 rd party SW due to this reason. Person should be sent back to unlock (free) the locker. If WBC is in state of warning or alarm it means the bin for retaining wristbands is full or nearly full and wristbands to be capture should be denied capture by 3 rd party SW. This is to preserve WBC HW. A ticket which is only to be granted passage without capture can be allowed even if WBC is in any of the mentioned states. Expected result can be: capture - wristband is retained by the device and let through the gate deny - wristband is denied allow - Wristband is let through the gate, but not captured allowonlysignal UI on the device will signal as allow but gate will not activate captureonlysignal wristband is retained by the device, UI on device will signal as capture, but gate will not activate Page 2

113 XML packages External XMLextU5.docx pin request - PIN is requested from user at access control device if supported on device UI In case of PIN request, PIN must be entered at access control device and External package is sent with card and pin parameter (both for reference reasons); expected result is allow or deny. Parameters of saldo & limit are obsolete in this scenario (driving access control device). 1.3 External Payment for passage When a wristband is presented to a Metra Payment Access Terminal (PAT) and it is issued in Metra SW to be externally authorised, a package is sent with the parameters card, ID of the device, ID of the passage the device is defined in (Metra SW tables), device direction and quota. Expected result can be Capture (wristband is retained by the device), Deny (wristband is denied) or Allow (Wristband is let through the gate, but not captured). Parameters of saldo & limit are optional, but desired as they can be shown on the PAT. 1.4 Driving MDB Devices (Vending Machines) This cycle are performed in two steps, each comprising of the same package and result but with different parameters. Regularly both are performed in sequence. If not, e.g. first step is repeated for the same or different RFID media, the RFID media has not sufficient balance, the user has interrupted the cycle or only checked for the balance, but performed no purchase st step User presents RFID media to the Metra MDB terminal. RFID media is only read and can be removed from the antenna field for the rest of the cycle. First the RFID media presented to the Metra MDB terminal and the Metra MDB Terminal ID (unique in one system) is sent to the 3 rd party SW. This is done to obtain the available balance to be spent. This balance must be returned in the result package. This balance is displayed on the MDB driven device display. This value is taken by the vending machine as the max price of one particular item that can be selected and delivered. If balance is too low, some items will be unavailable nd step User selects the item to be delivered on the vending machine keyboard or similar. Now another External package is send with parameters like before in 1 st step and additionally the selected item ID and the price; both are defined on the vending machine itself through vending machine GUI, keyboard or such (depends on the actual vending machine). When this package is sent from Metra, the item has already been delivered, so the result package is of technical nature, but still it is required to clean up open TCP connections and not leave them to timeout. Page 3

114 XML packages External XMLextU5.docx 2 Examples 2.1 Driving access control devices XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>external</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <data>34cb3efe34cb3efe34cb3efe34cb3e</data> Data read from card Varchar (xy) Offline data read from Mifare card; optional <pin>0856</pin> PIN up to 12 digits including leading zeroes <device>332</device> ID of Device from Metra tables Integer To determine device position e.g. Sauna, Fitness <passage>2</passage> ID of Passage from Metra tables Integer To determine device position e.g. Sauna, Fitness <direction>entrance</direction> Direction of requested access Varchar (36) Possible: Entrance, exit <lockers> Lockers / Information about lockers locked with the given card <locker> Locker / <number>1234</number> Locker number integer <location>1</location> Location of locker integer Same locker numbers are possible on different locations <dt> t09:55:00</dt> Timestamp of locking ISO, Given in example </locker> / / <locker> Locker / <number>102</number> Locker number integer <location>2</location> Location of locker integer Same locker numbers are possible on different locations <dt> t10:55:00</dt> Timestamp of locking ISO, Given in example </locker> / / </lockers> / / <wbc> WBC status / <state>warning or alarm</state> WBC state Varchar (36) Possible alarm or warning </wbc> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package must include same userdata </package> / / Page 4

115 XML packages External XMLextU5.docx Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <action>capture</action> Device action Varchar (36) Possible: capture, deny, allow, pin request; mind all letters in lower case </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with External XML package </package> / / Page 5

116 XML packages External XMLextU5.docx 2.2 External payment of passage XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>external</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <quota>123abc</quota> Quota from Metra tables Varchar (36) Can be price of particular e.g. solarium, or just a description <device>332</device> ID of Device from Metra tables Integer To determine device position e.g. Sauna, Fitness <passage>2</passage> ID of Passage from Metra tables Integer To determine device position e.g. Sauna, Fitness <direction>entrance</direction> Direction of requested access Varchar (36) Possible: Entrance, exit </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package must include same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <balance>25.45</balance> Wristbands saldo Integer SUM of current spending on the wristband; from 3rd party SW <limit>60.00</limit> Wristbands limit integer Limit to which spending is allowed; from 3rd party SW <action>allow</action> Device action Varchar (36) Possible: capture, deny, allow </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with External XML package </package> / / Page 6

117 XML packages External 2.3 Driving MDB Devices (Vending Machines) XMLextU5.docx First step XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>external</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <device>332</device> ID of Device from Metra tables Integer To determine device </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package must include same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <balance>25.45</balance> Wristbands balance Integer Balance to be shown on the vending machine display </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with External XML package </package> / / Page 7

118 XML packages External XMLextU5.docx Second step XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>external</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <device>332</device> ID of Device from Metra tables Integer To determine device <item>a51</item> ID of Item that was delivered Varchar (36) ID is defined on the vending machine <price>11.60</price> Price of Item that was delivered Numeric (18,2) Price is defined on the vending machine </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package must include same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with External XML package </package> / / Page 8

119 XML packages External XMLextU5.docx 3 Appendix An XML file is attached to the document which is same as the example XML package. External.Result.xml External.xml Page 9

120 XML packages Get Card XMLgcaU5.doc Get Card XML package Revision: Date Comment Creation of document Added Metra USB desktop reader support and direct access to POS service Copyright 2014 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

121 XML packages Get Card XMLgcaU5.doc 1 General This XML package is sent by 3 rd party SW to obtain a card/wristband unique card number from Metra NET systems. Number can be obtained using two different HW desktop readers. Result Codes returned by the interface: Result codes used with GetCard XML package: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list (only through interface server) or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and card number. If error code is returned, there is no card. 1.1 Metra USB Desktop POS Reader Must be connected to PC where Metra POS service is installed. This HW and SW configuration supports communicating to Metra Interface server or directly to POS service. When interfacing to Metra interface server addressing of the USB Metra desktop POS reader for communication purposes is performed by POS ID (defined in Metra SW). When interfacing directly to POS service the PCs HOSTNAME/IP is used to identify the reader. This direct option also supports reading of several cards in one request. Only one reader per PC is supported in any of the above scenarios. 1.2 Metra desktop POS reader Must be connected to Metra NET network. This HW and SW configuration supports communicating to Metra Interface server only to access the reader. When interfacing to Metra interface server addressing of the Metra desktop POS reader for communication purposes is performed by POS ID (defined in Metra SW) or readers unique network code/id. Page 2

122 XML packages Get Card XMLgcaU5.doc 2 Example 2.1 Metra USB Desktop POS reader Communication through Metra interface server XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>getcard</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <pos>1</pos> POS code from Metra tables Integer This code must be used to identify the reader via POS relation </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <card> d b46b41fe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 3

123 XML packages Get Card XMLgcaU5.doc Communication directly to Metra POS service (example for reading / requesting 1 card) XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <request> / / <header> / / <name>getcard</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <issuecount>1</issuecount> Number of cards expected Integer Result will list all cards if all expected are read <timeout>10000</timeout> Timeout in ms Integer Within this time reader is activated to find a card </parameters> / / </request> Userdata Varchar (36) Result of this XML package includes same userdata Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <card> d aeada712</card> Unique Cardnumber(s) in Metra format Varchar (36) Confirm with Metra for different types of media </parameters> / / </package> / / Page 4

124 XML packages Get Card XMLgcaU5.doc Communication directly to Metra POS service (example for reading / requesting 2 cards) XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <request> / / <header> / / <name>getcard</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <issuecount>2</issuecount> Number of cards expected Integer Result will list all cards if all expected are read <timeout>10000</timeout> Timeout in ms Integer Within this time reader is activated to find a card </parameters> / / </request> Userdata Varchar (36) Result of this XML package includes same userdata Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <card> d aeada712, D BCADA714</card> Unique Cardnumber(s) in Metra format Varchar (36) Confirm with Metra for different types of media </parameters> / / </package> / / Page 5

125 XML packages Get Card XMLgcaU5.doc 2.2 Metra Desktop POS reader Communication only through Metra interface server. XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>getcard</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <pos>1</pos> POS code from Metra tables Integer Either this code or device code must be used <device>550</device> Desktop POS reader network code Integer Either this code or POS code must be used </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <card> d b46b41fe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 6

126 XML packages Get Card XMLgcaU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 7

127 Metra LCC NET interface

128 Metra LCC NET interface Table of contents Metra LCC NET interface... 2 Glossary... 2 General... 2 Metra devices... 2 Metra SW... 3 Check Engines... 3 Metra LCC NET System outline... 3 Metra LCC NET as slave rd party SW as master... 3 Local Metra servers network topology scenario... 4 Central Metra server (like central 3 rd Party server) network topology scenario... 5 Metra LCC NET Interface... 5 Communication... 6 Integration & testing... 6 XML data packages... 6 Item Issue... 6 Disable... 6 Tickets Erase... 6 Exit Deny / Allow... 6 Card Info... 6 Card Info Repair... 7 Card Info White List... 7 Black List... 7 External... 7 Event... 7 Occupation... 7 Unlock... 7 Page 1

129 Metra LCC NET interface Metra LCC NET interface Glossary HW: SW: DB: Access Control: Metra LCC NET: Metra NET Network: Check engine: Passage: TCP/IP: XML: RFID: POS: User: DT: Item ID: PMS: HIS: Gastro: Hardware components Software components Database Access control is the ability to permit or deny the use of a particular resource by a particular entity. Metra HW and SW components working as a whole Metra LCC system. Metra devices driven by Check Engines from Metra SW with Firebird DB. Industry standard CAN network that is used for interconnection of Metra devices. Check engines are assigned to tickets upon issue. Different Check Engine performs different algorithms for cards on Metra devices. A physical (area/location) or logical (functional) whole to which different Check Engine can be assigned. Transmission Control Protocol (TCP) and the Internet Protocol (IP) The Extensible Mark-up Language (XML) is a general-purpose mark-up language. Its primary purpose is to facilitate the sharing of data across different information systems, particularly via the Internet. Radio-frequency identification (RFID) is an automatic identification method, relying on storing and remotely retrieving data using devices called RFID tags or transponders. Point Of sale People working with the Metra system and/or SW. Date and time usually limits. Unique ID of Items in Metra SW, which can be a group of rules (Ticket) for cards or just plain Items such as food/drinks. Property management system Hotel information system Gastronomy information system a SW used for restaurant sales and management. General The Metra LCC NET system is a combination of Metra devices and Metra SW working as one whole and/or interfacing with 3 rd party PMS, HIS or Gastro systems. Metra devices They are driven by check engines assigned to cards upon issue. All of the devices are connected to the Metra NET Network and they are online devices with certain offline functionality that only makes the Metra LCC NET system more robust. Page 2

130 Metra LCC NET interface Metra SW Metra software is a multilingual web application running on Firebird database. It is a capable of defining, setting and maintaining all Metra devices and driving them using Check Engines assigned to cards. The POS part of the application is capable of issuing charging Items to cards, producing analyses of sale and guest flow reports. When collaboration is needed with 3 rd party SW, it can interface with a TCP/IP based interface exchanging XML packages. Check Engines Check Engine are rules by which cards are granted on denied a certain service inside the Metra LCC NET system. They are of internal or external nature. Internal ones are driven by Metra SW algorithms, external ones ask a 3 rd party SW for permission to a certain service (Access to area, Solarium, Vending machines, etc.) through the Metra TCP/IP interface. Metra LCC NET System outline The Metra LCC NET system always consists of HW and SW components and can be integrated to a facility as a master or a slave application in regards to the 3 rd party SW it is being integrated with. The same media (cards) are used throughout the whole system; even in other system such as Fitness, Hotel, etc. Metra LCC NET as slave In a slave position Metra SW user interface is used by system operators only to supervise and maintain the Metra LCC NET system. It takes care of all the Metra HW devices (definition, parameterisation, maintenance). Check engines are defined and parameterised in the Metra SW and combined in groups of rules Tickets. All the Metra HW devices are driven by Check Engine issued to cards as Tickets at sale (not from Metra SW). Reports of events (guest flow) are obtained from the Metra SW. Optionally exported. The Metra TCP/IP interface is used to enable the master system complete guest control: Issuing Tickets to cards, erasing Tickets, performing external checks for particular services, denying/allowing exit from the system on Metra LCC NET access devices. 3 rd party SW as master In this situation a 3 rd party SW is in charge of the system. Its user interface is used by system operators performing all the sales of Tickets or Items on the main receptions and cash desks where money changes hands where bills are issued. Additionally for the purpose of e.g. sales inside the system (from the access point of view). Sales (items) are charged to the guest s unique card number to the 3 rd party SW DB. Metra POS readers can be used or 3 rd party readers to obtain this card number on POS inside the system. At this point a delivery note is issued upon purchase (NOT a bill), as no money changes hand. XML packages sent to the Metra DB through the Metra TCP/IP interface used to enable complete integration of the Metra LCC NET system are: Item Issue Item issue using Metra wristband issuer Ticket erasing Page 3

131 Metra LCC NET interface External check engine Deny/allow exit CardInfo (01, 02) Disable Local Metra servers network topology scenario Through Metra TCP/IP interface with ItemIssue, CardInfo, TicketsErase, BlackList, and other XML packages the following operations with tickets are supported: programming, extending validity, erasing, adding to the black list, etc. In case of link failure to main server, Metra access control still works. Several Metra server licences and server HW. Page 4

132 Metra LCC NET interface Central Metra server (like central 3 rd Party server) network topology scenario i) Through Metra TCP/IP interface with ItemIssue, CardInfo, TicketsErase, BlackList, and other XML packages the following operations with tickets are supported: programming, extending validity, erasing, adding to the black list, etc. ii) Direct real time authorisation of media through Metra TCP/IP interface with external XML package. Single Metra server licence and server HW. External control of devices when media is presented (option ii only). In case of link failure to main server, Metra access control does not work. Time delay possible due to 3 rd party SW performance (option ii only). Metra LCC NET Interface Metra LCC NET Interface is an interface transmitting XML packages through TCP/IP. Several XML packages are used which enable total integration of the Metra LCC NET system with 3 rd party SW. These packages are exchanged between the Metra server and the 3 rd party server or clients; depending on the type of 3 rd party SW application. Page 5

133 Metra LCC NET interface Communication Data is transmitted over TCP/IP in text format. All of the packages are sent using STX (ASCII 0x02) before the package and ETX (ASCII 0x03) after. Content of the package is between these two. Coding of the XML package must be UTF-8! Integration & testing To illustrate communication and for testing purposes demo programs (client & server) with sources are supplied by Metra. For all the XML packages samples are supplied by Metra. XML data packages XML data packages are used to interact with the Metra SW. There are several packages, which apply to different functionalities of the system. Issuing items to cards, Erasing data for a particular card, Issuing Metra wristbands using the Metra wristband issuer, Deny/Allow exit from the Metra system for a particular card, performing external authorisation for a card on a particular device. Item Issue This XML package is sent by 3 rd party SW to issue an Item to a card/wristband in the Metra LCC NET system. An Item is a group of rules inside the Metra LCC NET system e.g. Ticket. The rules are predefined in the Metra SW using check engines; internal (access), external (access or payment), etc. Items can be issued to a known media or unknown media/wristband using Metra Wristband Issuer. See XMLitiU5.pdf for package and result details. Disable This XML package is sent by 3 rd party SW to disable a certain check engine previously assigned to a card/wristband by Item Issue in the Metra LCC NET system. E.g. If a wristband is issued with refund functionality this can be disabled, turning it into a normal daily ticket, without any duration of stay limitations. See XMLdisU5.pdf for package and result details. Tickets Erase This XML package is sent by 3 rd party SW to erase all the Check Engine assigned to a particular card from the Metra SW DB. Used when wristband/card is not retained by Metra device, but returned manually to personnel. See XMLtieU5.pdf for package and result details. Exit Deny / Allow This XML package is sent by 3 rd party SW to deny or allow an exit from the Metra LCC NET system on exit devices. It is used mainly in when selling items to cards and wanting to collect money for them on the main cash desk upon guests exit from the controlled area. Therefore exit must be denied when purchases are made to a card (inside the system) and allowed when paid for (on main reception/cash desk). See XMLexiU5.pdf for package and result details. Card Info This XML package is sent by 3 rd party SW to obtain information about media (a card/wristband/key) in the Metra ELS system regarding lockers occupied by a particular media. Typically used in 3 rd party access control systems to deny or allow exit from the controlled area. See XMLciU5.pdf for package and result details. Page 6

134 Metra LCC NET interface Card Info 01 This XML package is sent by 3 rd party SW to obtain information about a card/wristband in the Metra LCC NET system regarding additional charge, refund parameters, Locker usage and media usage in general. See XMLci1U5.pdf for package and result details. Repair This XML package is sent by 3 rd party SW to repair parameters of a particular wristband/card in the Metra LCC NET system so that exit from the system is allowed. This applies only to parameters such as duration time limitations. It does not apply to status given by the Exit XML package. See XMLrepU5.pdf for package and result details. Card Info 02 This XML package is sent by Metra SW to 3 rd party SW to obtain information about a card/wristband from 3 rd party SW regarding account parameters. Current spending saldo and limit are given. See XMLci2U5.pdf for package and result details. White List This XML package is sent by 3 rd party SW to add/remove card/wristband to/from the White in the Metra LCC NET system. Media on the white list is valid to be used on Metra ELS lockers and in general. Packages are sent as strings through the Metra TCP/IP interface. Sent card number is obtained from 3 rd party SW; it must be sent in Metra format. See document Metra_ELS_SN_Encoding.pdf. Black List This XML package is sent by 3 rd party SW to add/remove card/wristband to/from the Black list in the Metra LCC NET system. Media on the black list is not valid to be used on Metra ELS lockers and in general. Packages are sent as strings through the Metra TCP/IP interface. Sent card number is obtained from 3 rd party SW; it must be sent in Metra format. See document Metra_ELS_SN_Encoding.pdf. External This XML package is sent to 3 rd party SW through Metra TCP/IP interface to perform external authorisation of action based on different parameters. E.g. acquire authorisation for some passage or door or acquire action for wristband collector (capture wristband). Event This XML package is sent by Metra SW to 3 rd party SW to give event information about a certain card in the Metra LCC NET system. Info about entrance to the system and wristband capture upon exit from the system is available. Occupation This XML package is sent by 3 rd party SW to obtain information about access control area occupation and locker occupation parameters. The package is sent to Metra DB server through the Metra TCP/IP interface. Information is returned from Metra DB server in the result package. Unlock This XML package is sent by 3 rd party SW to unlock a particular locker in Metra LCC NET system. Page 7

135 XML packages Item Issue XMLitiU5.docx Item Issue XML package Revision: Date Comment Creation of document Revision Revision; Wristband Issuer functionality added Revision; Wristband issuer additional parameter added DT omit option supported Barcode added Barcode Coupon functionality Description field added to document UID field added Magazine field added Duration field added Copyright 2014 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

136 XML packages Item Issue XMLitiU5.docx 1 General This XML package is sent by 3 rd party SW through TCP/IP interface to issue an Item to a card/wristband in the Metra LCC NET system. An Item is a group of rules inside the Metra LCC NET system e.g. Ticket. The rules are predefined in the Metra SW using check engines; internal (access), external (access or payment), etc. Items can be issued to a known cardnumber/media or unknown cardnumber/media using the Metra Wristband Issuer (HW component) - WBI. Result Codes returned by the interface: Result codes used with ItemIssue: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 85 (0x55) - ERROR_ALREADY_ASSIGNED The media already has a ticket programmed to it. XML package EraseTickets must be used first. 21 (0x15) - ERROR_NOT_READY - The device (only WBI) is not ready. 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and cardnumber. Cardnumber only if the Wristband issuer is used! Cardnumber is used as a guest reference in the 3 rd party SW. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. 1.2 Issuing to known media In this case the cardnumber is obtained by the 3 rd party SW by using Metra or 3 rd party Desktop POS readers. Mandatory parameters: Item, Card, datetimefrom, datetimeto. Note: datetimefrom and datetimeto can be omitted if services predefined in the Metra SW tables have the date validity defined as xy days, else they must be supplied using this package. If parameters are not supplied and not predefined, media is issued with one day validity; from the moment of sending the package until midnight same day. If supplied with the package they override, anything predefined in the Metra SW tables Duration Used to define gross locker usage duration per media lifecycle when using Reader Terminal Touch Assign ELS NET systems. Page 2

137 XML packages Item Issue XMLitiU5.docx Barcode - Coupon When a barcode is created and printed in 3 rd party SW and sent to Metra interface server, the card tag must be omitted. In this case a reservation of the sent item is created in the Metra SW via Coupon functionality. A wristband from the Coupon Ticket item sent is issued to a guest when barcode is read in Metra POS or Metra self service terminal. 1.3 Wristband issuer Mandatory parameters: Mode, Issue device, Item, datetimefrom, datetimeto. The result package does not only have a generic technical meaning, but also returns the cardnumber of the wristband issued by the wristband issuer. Parameter IssueDevice is used to directly address the wanted wristband issuer device. Note: datetimefrom and datetimeto can be omitted if services predefined in the Metra SW tables have the date validity defined as xy days, else they must be supplied using this package. If parameters are not supplied and not predefined, media is issued with one day validity; from the moment of sending the package until midnight same day. If supplied with the package they override, anything predefined in the Metra SW tables <magazine> If parameter magazine is used, wristbands can be requested from particular chain/magazine with wristband. Magazine 1, 2 or 3 is a possible value with current model of WBI. This enables colour differentiation of wristbands and such Extdata Parameter extdata is used to transfer/write custom 3 rd party SW data to a wristband using wristband issuer. 1.4 Description Is used in file system interfaces to transfer e.g. guests name to file interface. Also the data is written to Metra DB and can be accessed through result of cardinfo01 XML package referenced to a particular card. Can be used to store guests name, ticket type, custom external data, etc. 1.5 UID UID tag is used to store external unique identifier for identification of actions (applying to particular document in Metra system) from result of cardinfo01 XML package. Page 3

138 XML packages Item Issue XMLitiU5.docx 2 Examples 2.1 Full Package XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>itemissue</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <pos>1</pos> Point of sale code Small integer If parameter is not given, lowest from Metra DB is used <user>2</user> User code Small integer If parameter is not given, lowest from Metra DB is used <issuedevice>571</issuedevice> Metra NET device address Small integer Metra network ID of Wristband Issuer (WBI) <mode>wristbandissuer</mode> Mode of issuing Varchar (30) Used only with WBI <magazine>2</magazine> WBI magazine Integer Used to request a wristband from specific magazine <item>100abc</item> Unique Item ID Varchar (36) <param>30</param> Item Parameter Integer Used to extend minutes of stay duration & Electronic money <card> d fe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <citem>1001abc</citem> Unique Item ID Varchar (36) Item to be sold when importing Barcode / Coupon <cticket>1234bde</cticket> Unique Item ID Varchar (36) Ticket item to be sold when issuing media from Barcode / Coupon <barcode> </barcode> Barcode INT64 Barcode generated in 3rd party SW <extdata> abcdef abcdef</extdata> External data Varchar (63) Data which is written on the media using Wristband Issuer <datetimefrom> t09:50:00</datetimefrom> Date & time from Given in example Start of validity <datetimeto> t09:50:00</datetimeto> Date & time to Given in example End of validity <description>john Doe</description> Guest description or custom external info Varchar (30) Used with file interfaces and cardinfo01 XML package <duration>180</duration> Duration in minutes Integer Only used with ELS NET Reader Terminal Touch Assign Systems <uid> abcdefghi</uid> External UID Varchar(64) Used to follow actions in cardinfo01 XML package </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Page 4

139 XML packages Item Issue XMLitiU5.docx 2.2 Issuing to known media: Programming RFID media XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>itemissue</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <pos>1</pos> Point of sale code (Optional) Small integer If parameter is not given, lowest from Metra DB is used <user>2</user> User code (Optional) Small integer If parameter is not given, lowest from Metra DB is used <item>100abc</item> Unique Item ID Varchar (36) <param>30</param> Item Parameter (Optional) Integer Used to extend minutes of stay duration & Electronic money QTY <card> d fe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <datetimefrom> t09:50:00</datetimefrom> Date & time from (Optional) Given in example Start of validity <datetimeto> t09:50:00</datetimeto> Date & time to (Optional) Given in example End of validity <description>john Doe</description> Guest description Varchar (30) Used with file interfaces <uid> abcdefghi</uid> External UID Varchar(64) Used to follow actions in cardinfo01 XML package </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Page 5

140 XML packages Item Issue XMLitiU5.docx Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 6

141 XML packages Item Issue XMLitiU5.docx Making a reservation to a barcode through Coupon functionality XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>itemissue</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <pos>1</pos> Point of sale code (Optional) Small integer If parameter is not given, lowest from Metra DB is used <user>2</user> User code (Optional) Small integer If parameter is not given, lowest from Metra DB is used <citem>1001abc</citem> Unique Item ID Varchar (36) Item to be sold when importing Barcode / Coupon <cticket>1234bde</cticket> Unique Item ID Varchar (36) Ticket item to be sold when issuing media from Barcode / Coupon <barcode> </barcode> Barcode INT64 Barcode generated in 3rd party SW <datetimeto> t09:50:00</datetimeto> Date & time to (Optional) Given in example End of validity of barcode </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 7

142 XML packages Item Issue XMLitiU5.docx 2.3 Wristband issuer XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>itemissue</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <pos>1</pos> Point of sale code (Optional) Small integer If parameter is not given, lowest from Metra DB is used <user>2</user> User code (Optional) Small integer If parameter is not given, lowest from Metra DB is used <issuedevice>571</issuedevice> Metra NET device address Small integer Metra network ID of Wristband Issuer <mode>wristbandissuer</mode> Mode of issuing Varchar (30) Used only with WBI <magazine>2</magazine> WBI magazine Integer Used to request a wristband from specific magazine <item>123abc</item> Unique Item ID Varchar (36) <extdata> abcdef abcdef</extdata> External data (Optional) Varchar (63) Data which is written on the media using Wristband Issuer <datetimefrom> t09:50:00</datetimefrom> Date & time from (Optional) Given in example Start of validity <datetimeto> t09:50:00</datetimeto> Date & time to (Optional) Given in example End of validity </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Page 8

143 XML packages Item Issue XMLitiU5.docx Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <card> d fe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 9

144 XML packages Item Issue XMLitiU5.docx 3 Appendix An XML file is attached to the document which is same as the full example XML package and result. Page 10

145 XML packages Repair XMLrepU5.docx Revision: Date Comment Creation of document Added <mode/> support Repair XML package Copyright 2014 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

146 XML packages Repair XMLrepU5.docx 1 General This XML package is sent by 3 rd party SW to repair parameters of a particular wristband/card in Metra NET systems so that exit from the access control system is allowed and/or other financial transactions are settled. **The Repair package does not affect status given by the Exit XML package. For this XML package the result is generic, giving only the result code without any additional parameters. Result Codes returned by the interface: Result codes used with Repair: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded 1.1 Mode There are 4 modes for this operation; if all or none are listed or tag <mode/> is omitted all 4 are performed. If individual (or two or three) are listed as in example only the respective actions are performed. CardDelivery Operation will settle all opened delivery notes made by Card Delivery. ElectonicMoney Operation will settle the debit value of Electronic Money. Access Operation will settle access control parameters preventing an exit such as visit duration time limitations, etc. Locker Operation will clear the occupied locker(s) association in Metra DB. Locker mode should be implemented in a way that it is not automatic/default, only for borderline situations. E.g. a guest is attempting an exit and is denied due to Locker and/or other parameters. Firstly the guest should be instructed to go and release the locker, if reluctant the Locker mode can be used. If Locker mode is used it must be clear to the system operator that the guest will leave whilst leaving an occupied locker that will not be available for other guests until released by cleaning or other daily maintenance system procedures. 1.2 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. Page 2

147 XML packages Repair XMLrepU5.docx 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>repair</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <mode>carddelivery,access,locker,electronicmoney</mode> Mode of repair (all possibilities are in example) Varchar (256) Possible modes can be individual or grouped as in example </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 3

148 XML packages Repair XMLrepU5.docx 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 4

149 XML packages Tickets Erase XMLtieU5.docx Tickets Erase XML package Revision: Date Comment Creation of document Revision Barcode / Coupon functionality added <mode/> tag added Copyright 2014 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

150 XML packages Tickets Erase XMLtieU5.docx 1 General This XML package is sent by 3 rd party SW to erase all the Check Engines programmed to a particular card/wristband/barcode in Metra NET systems. 1.1 Mode When <mode/> is not used particular card is erased that is specified in <card/>. <mode/> enables bulk deletion of media distinguishing between RFID and Barcode media. If all media is to be erased, both must be listed like in example. <card/> must be omitted in this case. 1.2 Coupon When using Coupon functionality, the barcode tag is used to erase not yet used coupons; used in case of wrong input of coupons through Item issue package, etc. <mode/> is not supported for Coupon functionality. Error Codes returned by the interface: Codes used in Metra interface are: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. Page 2

151 XML packages Tickets Erase XMLtieU5.docx 2 Examples 2.1 RFID / Barcode Media XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>ticketserase</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / 2.2 Bulk erase with <mode/> XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>ticketserase</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <mode>rfid,barcode</mode> Mode for erasing Varchar (36) RFID, Barcode or both as listed; case sensitive </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Page 3

152 XML packages Tickets Erase XMLtieU5.docx 2.3 Coupon / Barcode XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8"?> / / <package> / / <header> / / <name>ticketserase</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <barcode> </barcode> Barcode INT64 </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / 2.4 Result Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 4

153 XML packages Tickets Erase XMLtieU5.docx 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 5

154 THIRD-PARTY XML INTEGRATION MANUAL LCC NET EXTERNAL INTERFACE PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

155 XML packages Event XMLeve11U5.doc Event XML package v1.1 Revision: Date Comment Creation of document Table of modes added Corrections in event id, added samples Correction of tags Added DT parameter Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page

156 XML packages Event XMLeve11U5.doc 1 General This XML package is sent by Metra SW to 3 rd party SW to give event information about a certain wristband/media in the Metra LCC NET system. Info about entrance to the system, exit and wristband capture before exit from the system is available. Also all wristbands denied are send with the reason (mode). Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. Page

157 XML packages Event XMLeve11U5.doc 2 Example XML package - entrance Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>event</name> Package name / <version>1.1</version> Version / </header> / / <parameters> Parameters / <card> d e634162</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <iddevice>301</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) <idpassage>1</idpassage> Passage id assigned to device Integer Defined in Metra SW (1-9999) <direction>exit</direction> Device direction Varchar (36) Defined in Metra SW (entrance or exit) <event> Event / <eventid> </eventid> Event id Integer Unique event id from Metra DB <dt> t09:50:00</dt> Date & time of event Given in example DT as recorded in Metra DB <code>250</code> Event Code Integer 10 for entrance, 20 for exit or 250 for Deny <codedescription>deny</codedescription> Event description Varchar (36) Enter, Exit or Deny <mode>24</mode> Mode of event Code Integer See table of available mode codes <modedescription>locker</modedescription> Mode of event description Varchar (36) See table of available mode descriptions </event> / / </parameters> / / </package> / / Page

158 XML packages Event XMLeve11U5.doc Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.1</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / </package> / / Page

159 XML packages Event XMLeve11U5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. 3.1 Possible mode codes Mainly apply to Deny event. 3 Capture 11 Location 12 Date 13 Time 14 Last Day 15 Day 16 Points 17 D Points 18 Direction 19 Not Valid 20 Exit 21 Tokens 23 Entrance delay 24 Locker 25 Add Charge 26 Refund 27 Borrow/PAY 28 Exit Counter 29 Cancelled Card 35 Borrow 36 Delivery 37 Deny Exit 38 Electronic Money 39 WBC Full 44 External 45 Busy 46 Minutes 47 Ring Note: Only mode Capture is sent without event code or description; only mode code and mode description. 3.2 Sample packeges Deny Not Valid on entrance <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d c4ce739</card> <iddevice>333</iddevice> <idpassage>1</idpassage> <direction>entrance</direction> <event> <eventid> </eventid> <code>250</code> <codedescription>deny</codedescription> <mode>19</mode> <modedescription>notvalid</modedescription> </event> </parameters> </package> Deny Locker on exit <?xml version="1.0" encoding="utf-8" standalone="yes"?> Page

160 XML packages Event <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d e634162</card> <iddevice>301</iddevice> <idpassage>1</idpassage> <direction>exit</direction> <event> <eventid> </eventid> <code>250</code> <codedescription>deny</codedescription> <mode>24</mode> <modedescription>locker</modedescription> </event> </parameters> </package> XMLeve11U5.doc Enter <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d c4ce739</card> <iddevice>333</iddevice> <idpassage>1</idpassage> <direction>entrance</direction> <event> <eventid> </eventid> <code>10</code> <codedescription>enter</codedescription> </event> </parameters> </package> Exit <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d d4de739</card> <iddevice>301</iddevice> <idpassage>1</idpassage> <direction>exit</direction> <event> <eventid> </eventid> <code>20</code> <codedescription>exit</codedescription> </event> </parameters> </package> Capture & Exit (note 2 packages!) First Capture: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d c4ce739</card> <iddevice>301</iddevice> <idpassage>1</idpassage> <direction>exit</direction> Page

161 XML packages Event <event> <eventid> </eventid> <mode>3</mode> <modedescription>capture</modedescription> </event> </parameters> </package> Follwed by Exit: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <package> <header> <name>event</name> <version>1.1</version> </header> <parameters> <card> d c4ce739</card> <iddevice>301</iddevice> <idpassage>1</idpassage> <direction>exit</direction> <event> <eventid> </eventid> <code>20</code> <codedescription>exit</codedescription> </event> </parameters> </package> XMLeve11U5.doc Page

162 XML packages External XMLextU5.docx External XML package Revision: Date Comment Creation of document Revision New parameters added; iddevice, idpassage, Lockers, WBC New parameter added: data Added PIN functionality Typo corrections idpassage->passage, iddevice->device MDB typo and explanation added Added captureonlysignal and allowonlysignal Copyright 2014 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

163 XML packages External XMLextU5.docx 1 General These XML package is sent to 3 rd party SW through Metra TCP/IP interface to perform external authorisation of action based on different parameters. E.g. acquire authorisation for some passage or door, acquire action for wristband collector (capture wristband) or drive a MDB vending machine. Result Codes returned by the interface: Codes used in Metra interface and expected from 3 rd party SW are: 87 (0x57) - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 (0x5) - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 1 (0x1) - ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed 0 (0x0) - ERROR_SUCCESS Operation succeeded Not all fields in the Result package that are generated by 3 rd party SW are mandatory. Different scenarios are explained in the following chapters. 1.1 Communication In order to map a result XML package from the 3 rd party SW to a sent XML package from Metra SW it is mandatory to implement <userdata\> tag. It can contain up to Varchar (36) value. 3 rd party SW must echo the userdata string from the sent XML package in the respective Result package. This allows for unique identification of a Result in multithread scenarios. 1.2 Driving access control devices including Wristband Collector (WBC) When a wristband is presented to a Metra access control device reader or WBC (which is incorporated in Turnstile access terminal - TAT), and it is defined to be externally authorised, a package is sent with the parameters card, ID of the device, ID of the passage the device is defined in (Metra SW tables), device direction, Lockers locked with this card and WBC state (if presented to WBC). If reading of Mifare card contents is turned on (access key and sector information is needed in Metra SW), the package includes also data read from the card; in tag <data\>; length of tag contents varies due to number of selected sectors to be read. If the device is an exit device from the system and there are lockers locked with presented card, the package will carry this information and exit can be automatically denied by 3 rd party SW due to this reason. Person should be sent back to unlock (free) the locker. If WBC is in state of warning or alarm it means the bin for retaining wristbands is full or nearly full and wristbands to be capture should be denied capture by 3 rd party SW. This is to preserve WBC HW. A ticket which is only to be granted passage without capture can be allowed even if WBC is in any of the mentioned states. Expected result can be: capture - wristband is retained by the device and let through the gate deny - wristband is denied allow - Wristband is let through the gate, but not captured allowonlysignal UI on the device will signal as allow but gate will not activate captureonlysignal wristband is retained by the device, UI on device will signal as capture, but gate will not activate Page 2

164 XML packages External XMLextU5.docx pin request - PIN is requested from user at access control device if supported on device UI In case of PIN request, PIN must be entered at access control device and External package is sent with card and pin parameter (both for reference reasons); expected result is allow or deny. Parameters of saldo & limit are obsolete in this scenario (driving access control device). 1.3 External Payment for passage When a wristband is presented to a Metra Payment Access Terminal (PAT) and it is issued in Metra SW to be externally authorised, a package is sent with the parameters card, ID of the device, ID of the passage the device is defined in (Metra SW tables), device direction and quota. Expected result can be Capture (wristband is retained by the device), Deny (wristband is denied) or Allow (Wristband is let through the gate, but not captured). Parameters of saldo & limit are optional, but desired as they can be shown on the PAT. 1.4 Driving MDB Devices (Vending Machines) This cycle are performed in two steps, each comprising of the same package and result but with different parameters. Regularly both are performed in sequence. If not, e.g. first step is repeated for the same or different RFID media, the RFID media has not sufficient balance, the user has interrupted the cycle or only checked for the balance, but performed no purchase st step User presents RFID media to the Metra MDB terminal. RFID media is only read and can be removed from the antenna field for the rest of the cycle. First the RFID media presented to the Metra MDB terminal and the Metra MDB Terminal ID (unique in one system) is sent to the 3 rd party SW. This is done to obtain the available balance to be spent. This balance must be returned in the result package. This balance is displayed on the MDB driven device display. This value is taken by the vending machine as the max price of one particular item that can be selected and delivered. If balance is too low, some items will be unavailable nd step User selects the item to be delivered on the vending machine keyboard or similar. Now another External package is send with parameters like before in 1 st step and additionally the selected item ID and the price; both are defined on the vending machine itself through vending machine GUI, keyboard or such (depends on the actual vending machine). When this package is sent from Metra, the item has already been delivered, so the result package is of technical nature, but still it is required to clean up open TCP connections and not leave them to timeout. Page 3

165 XML packages External XMLextU5.docx 2 Examples 2.1 Driving access control devices XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>external</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <data>34cb3efe34cb3efe34cb3efe34cb3e</data> Data read from card Varchar (xy) Offline data read from Mifare card; optional <pin>0856</pin> PIN up to 12 digits including leading zeroes <device>332</device> ID of Device from Metra tables Integer To determine device position e.g. Sauna, Fitness <passage>2</passage> ID of Passage from Metra tables Integer To determine device position e.g. Sauna, Fitness <direction>entrance</direction> Direction of requested access Varchar (36) Possible: Entrance, exit <lockers> Lockers / Information about lockers locked with the given card <locker> Locker / <number>1234</number> Locker number integer <location>1</location> Location of locker integer Same locker numbers are possible on different locations <dt> t09:55:00</dt> Timestamp of locking ISO, Given in example </locker> / / <locker> Locker / <number>102</number> Locker number integer <location>2</location> Location of locker integer Same locker numbers are possible on different locations <dt> t10:55:00</dt> Timestamp of locking ISO, Given in example </locker> / / </lockers> / / <wbc> WBC status / <state>warning or alarm</state> WBC state Varchar (36) Possible alarm or warning </wbc> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package must include same userdata </package> / / Page 4

166 XML packages External XMLextU5.docx Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <action>capture</action> Device action Varchar (36) Possible: capture, deny, allow, pin request; mind all letters in lower case </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with External XML package </package> / / Page 5

167 XML packages External XMLextU5.docx 2.2 External payment of passage XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>external</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <quota>123abc</quota> Quota from Metra tables Varchar (36) Can be price of particular e.g. solarium, or just a description <device>332</device> ID of Device from Metra tables Integer To determine device position e.g. Sauna, Fitness <passage>2</passage> ID of Passage from Metra tables Integer To determine device position e.g. Sauna, Fitness <direction>entrance</direction> Direction of requested access Varchar (36) Possible: Entrance, exit </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package must include same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <balance>25.45</balance> Wristbands saldo Integer SUM of current spending on the wristband; from 3rd party SW <limit>60.00</limit> Wristbands limit integer Limit to which spending is allowed; from 3rd party SW <action>allow</action> Device action Varchar (36) Possible: capture, deny, allow </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with External XML package </package> / / Page 6

168 XML packages External 2.3 Driving MDB Devices (Vending Machines) XMLextU5.docx First step XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>external</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <device>332</device> ID of Device from Metra tables Integer To determine device </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package must include same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <balance>25.45</balance> Wristbands balance Integer Balance to be shown on the vending machine display </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with External XML package </package> / / Page 7

169 XML packages External XMLextU5.docx Second step XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>external</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> d cb3efe</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <device>332</device> ID of Device from Metra tables Integer To determine device <item>a51</item> ID of Item that was delivered Varchar (36) ID is defined on the vending machine <price>11.60</price> Price of Item that was delivered Numeric (18,2) Price is defined on the vending machine </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package must include same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with External XML package </package> / / Page 8

170 XML packages External XMLextU5.docx 3 Appendix An XML file is attached to the document which is same as the example XML package. External.Result.xml External.xml Page 9

171 Metra LCC NET interface

172 Metra LCC NET interface Table of contents Metra LCC NET interface... 2 Glossary... 2 General... 2 Metra devices... 2 Metra SW... 3 Check Engines... 3 Metra LCC NET System outline... 3 Metra LCC NET as slave rd party SW as master... 3 Local Metra servers network topology scenario... 4 Central Metra server (like central 3 rd Party server) network topology scenario... 5 Metra LCC NET Interface... 5 Communication... 6 Integration & testing... 6 XML data packages... 6 Item Issue... 6 Disable... 6 Tickets Erase... 6 Exit Deny / Allow... 6 Card Info... 6 Card Info Repair... 7 Card Info White List... 7 Black List... 7 External... 7 Event... 7 Occupation... 7 Unlock... 7 Page 1

173 Metra LCC NET interface Metra LCC NET interface Glossary HW: SW: DB: Access Control: Metra LCC NET: Metra NET Network: Check engine: Passage: TCP/IP: XML: RFID: POS: User: DT: Item ID: PMS: HIS: Gastro: Hardware components Software components Database Access control is the ability to permit or deny the use of a particular resource by a particular entity. Metra HW and SW components working as a whole Metra LCC system. Metra devices driven by Check Engines from Metra SW with Firebird DB. Industry standard CAN network that is used for interconnection of Metra devices. Check engines are assigned to tickets upon issue. Different Check Engine performs different algorithms for cards on Metra devices. A physical (area/location) or logical (functional) whole to which different Check Engine can be assigned. Transmission Control Protocol (TCP) and the Internet Protocol (IP) The Extensible Mark-up Language (XML) is a general-purpose mark-up language. Its primary purpose is to facilitate the sharing of data across different information systems, particularly via the Internet. Radio-frequency identification (RFID) is an automatic identification method, relying on storing and remotely retrieving data using devices called RFID tags or transponders. Point Of sale People working with the Metra system and/or SW. Date and time usually limits. Unique ID of Items in Metra SW, which can be a group of rules (Ticket) for cards or just plain Items such as food/drinks. Property management system Hotel information system Gastronomy information system a SW used for restaurant sales and management. General The Metra LCC NET system is a combination of Metra devices and Metra SW working as one whole and/or interfacing with 3 rd party PMS, HIS or Gastro systems. Metra devices They are driven by check engines assigned to cards upon issue. All of the devices are connected to the Metra NET Network and they are online devices with certain offline functionality that only makes the Metra LCC NET system more robust. Page 2

174 Metra LCC NET interface Metra SW Metra software is a multilingual web application running on Firebird database. It is a capable of defining, setting and maintaining all Metra devices and driving them using Check Engines assigned to cards. The POS part of the application is capable of issuing charging Items to cards, producing analyses of sale and guest flow reports. When collaboration is needed with 3 rd party SW, it can interface with a TCP/IP based interface exchanging XML packages. Check Engines Check Engine are rules by which cards are granted on denied a certain service inside the Metra LCC NET system. They are of internal or external nature. Internal ones are driven by Metra SW algorithms, external ones ask a 3 rd party SW for permission to a certain service (Access to area, Solarium, Vending machines, etc.) through the Metra TCP/IP interface. Metra LCC NET System outline The Metra LCC NET system always consists of HW and SW components and can be integrated to a facility as a master or a slave application in regards to the 3 rd party SW it is being integrated with. The same media (cards) are used throughout the whole system; even in other system such as Fitness, Hotel, etc. Metra LCC NET as slave In a slave position Metra SW user interface is used by system operators only to supervise and maintain the Metra LCC NET system. It takes care of all the Metra HW devices (definition, parameterisation, maintenance). Check engines are defined and parameterised in the Metra SW and combined in groups of rules Tickets. All the Metra HW devices are driven by Check Engine issued to cards as Tickets at sale (not from Metra SW). Reports of events (guest flow) are obtained from the Metra SW. Optionally exported. The Metra TCP/IP interface is used to enable the master system complete guest control: Issuing Tickets to cards, erasing Tickets, performing external checks for particular services, denying/allowing exit from the system on Metra LCC NET access devices. 3 rd party SW as master In this situation a 3 rd party SW is in charge of the system. Its user interface is used by system operators performing all the sales of Tickets or Items on the main receptions and cash desks where money changes hands where bills are issued. Additionally for the purpose of e.g. sales inside the system (from the access point of view). Sales (items) are charged to the guest s unique card number to the 3 rd party SW DB. Metra POS readers can be used or 3 rd party readers to obtain this card number on POS inside the system. At this point a delivery note is issued upon purchase (NOT a bill), as no money changes hand. XML packages sent to the Metra DB through the Metra TCP/IP interface used to enable complete integration of the Metra LCC NET system are: Item Issue Item issue using Metra wristband issuer Ticket erasing Page 3

175 Metra LCC NET interface External check engine Deny/allow exit CardInfo (01, 02) Disable Local Metra servers network topology scenario Through Metra TCP/IP interface with ItemIssue, CardInfo, TicketsErase, BlackList, and other XML packages the following operations with tickets are supported: programming, extending validity, erasing, adding to the black list, etc. In case of link failure to main server, Metra access control still works. Several Metra server licences and server HW. Page 4

176 Metra LCC NET interface Central Metra server (like central 3 rd Party server) network topology scenario i) Through Metra TCP/IP interface with ItemIssue, CardInfo, TicketsErase, BlackList, and other XML packages the following operations with tickets are supported: programming, extending validity, erasing, adding to the black list, etc. ii) Direct real time authorisation of media through Metra TCP/IP interface with external XML package. Single Metra server licence and server HW. External control of devices when media is presented (option ii only). In case of link failure to main server, Metra access control does not work. Time delay possible due to 3 rd party SW performance (option ii only). Metra LCC NET Interface Metra LCC NET Interface is an interface transmitting XML packages through TCP/IP. Several XML packages are used which enable total integration of the Metra LCC NET system with 3 rd party SW. These packages are exchanged between the Metra server and the 3 rd party server or clients; depending on the type of 3 rd party SW application. Page 5

177 Metra LCC NET interface Communication Data is transmitted over TCP/IP in text format. All of the packages are sent using STX (ASCII 0x02) before the package and ETX (ASCII 0x03) after. Content of the package is between these two. Coding of the XML package must be UTF-8! Integration & testing To illustrate communication and for testing purposes demo programs (client & server) with sources are supplied by Metra. For all the XML packages samples are supplied by Metra. XML data packages XML data packages are used to interact with the Metra SW. There are several packages, which apply to different functionalities of the system. Issuing items to cards, Erasing data for a particular card, Issuing Metra wristbands using the Metra wristband issuer, Deny/Allow exit from the Metra system for a particular card, performing external authorisation for a card on a particular device. Item Issue This XML package is sent by 3 rd party SW to issue an Item to a card/wristband in the Metra LCC NET system. An Item is a group of rules inside the Metra LCC NET system e.g. Ticket. The rules are predefined in the Metra SW using check engines; internal (access), external (access or payment), etc. Items can be issued to a known media or unknown media/wristband using Metra Wristband Issuer. See XMLitiU5.pdf for package and result details. Disable This XML package is sent by 3 rd party SW to disable a certain check engine previously assigned to a card/wristband by Item Issue in the Metra LCC NET system. E.g. If a wristband is issued with refund functionality this can be disabled, turning it into a normal daily ticket, without any duration of stay limitations. See XMLdisU5.pdf for package and result details. Tickets Erase This XML package is sent by 3 rd party SW to erase all the Check Engine assigned to a particular card from the Metra SW DB. Used when wristband/card is not retained by Metra device, but returned manually to personnel. See XMLtieU5.pdf for package and result details. Exit Deny / Allow This XML package is sent by 3 rd party SW to deny or allow an exit from the Metra LCC NET system on exit devices. It is used mainly in when selling items to cards and wanting to collect money for them on the main cash desk upon guests exit from the controlled area. Therefore exit must be denied when purchases are made to a card (inside the system) and allowed when paid for (on main reception/cash desk). See XMLexiU5.pdf for package and result details. Card Info This XML package is sent by 3 rd party SW to obtain information about media (a card/wristband/key) in the Metra ELS system regarding lockers occupied by a particular media. Typically used in 3 rd party access control systems to deny or allow exit from the controlled area. See XMLciU5.pdf for package and result details. Page 6

178 Metra LCC NET interface Card Info 01 This XML package is sent by 3 rd party SW to obtain information about a card/wristband in the Metra LCC NET system regarding additional charge, refund parameters, Locker usage and media usage in general. See XMLci1U5.pdf for package and result details. Repair This XML package is sent by 3 rd party SW to repair parameters of a particular wristband/card in the Metra LCC NET system so that exit from the system is allowed. This applies only to parameters such as duration time limitations. It does not apply to status given by the Exit XML package. See XMLrepU5.pdf for package and result details. Card Info 02 This XML package is sent by Metra SW to 3 rd party SW to obtain information about a card/wristband from 3 rd party SW regarding account parameters. Current spending saldo and limit are given. See XMLci2U5.pdf for package and result details. White List This XML package is sent by 3 rd party SW to add/remove card/wristband to/from the White in the Metra LCC NET system. Media on the white list is valid to be used on Metra ELS lockers and in general. Packages are sent as strings through the Metra TCP/IP interface. Sent card number is obtained from 3 rd party SW; it must be sent in Metra format. See document Metra_ELS_SN_Encoding.pdf. Black List This XML package is sent by 3 rd party SW to add/remove card/wristband to/from the Black list in the Metra LCC NET system. Media on the black list is not valid to be used on Metra ELS lockers and in general. Packages are sent as strings through the Metra TCP/IP interface. Sent card number is obtained from 3 rd party SW; it must be sent in Metra format. See document Metra_ELS_SN_Encoding.pdf. External This XML package is sent to 3 rd party SW through Metra TCP/IP interface to perform external authorisation of action based on different parameters. E.g. acquire authorisation for some passage or door or acquire action for wristband collector (capture wristband). Event This XML package is sent by Metra SW to 3 rd party SW to give event information about a certain card in the Metra LCC NET system. Info about entrance to the system and wristband capture upon exit from the system is available. Occupation This XML package is sent by 3 rd party SW to obtain information about access control area occupation and locker occupation parameters. The package is sent to Metra DB server through the Metra TCP/IP interface. Information is returned from Metra DB server in the result package. Unlock This XML package is sent by 3 rd party SW to unlock a particular locker in Metra LCC NET system. Page 7

179 THIRD-PARTY XML INTEGRATION MANUAL ELS INTERFACE PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

180 XML packages Event Info XMLeviU5.doc Event Info XML package v1.0 Revision: Date Comment Creation of document Revision Revision Added new events and modes to list of events and modes Added MEW DAT additional events Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

181 XML packages Event Info XMLeviU5.doc 1 General This XML package is sent by Metra SW to 3 rd party SW to give event information of events that happen in Metra systems. These events are sent online in real time. Also they are queued in Metra DB if communication is not possible at the time of event, so they are sent later when connection is re-established. Which events are sent can be filtered in the Metra SW to avoid unnecessary traffic with info not needed. Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. It must be sent by 3 rd party SW, else event is queued and sent again later. Page 2

182 XML packages Event Info XMLeviU5.doc 2 Example XML package - entrance Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>eventinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <event> Event / <eventid> </eventid> Event id Integer Unique event id from Metra DB <card> d e634162</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <dt> t09:40:00</dt> Date & time of event Given in example DT as recorded in Metra DB <code>30</code> Event Code Integer 30 for locking, 40 for unlocking, <codedescription>locking</codedescription> Event description Varchar (36) Locking, Unlocking, <mode>1</mode> Mode of event Code Integer 1, 5 or 71, see below for respective descriptions <modedescription>user key</modedescription> Mode of event description Varchar (36) USER key, MASTER key, DELIVERY key <iddevice>102</iddevice> Device id where event happened Integer Defined in Metra SW (1-999) <devicedescription>cu 102</devicedescription> Device description from Metra tables Varchar (36) <locker>1234</locker> Locker number Integer <idlocation>1</idlocation> Location ID Integer Same locker numbers are possible on different locations <locationdescription>lobby</locationdescription> Location description Varchar (36) </event> / / </parameters> / / </package> / / Page 3

183 XML packages Event Info XMLeviU5.doc Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / </package> / / Page 4

184 XML packages Event Info XMLeviU5.doc 3 Events and Modes Not all events or modes apply to all integration scenarios. 3.1 Events 1 Read wristband, CardInfo01 2 Card Issue 3 Procedure (Points, Tokens, Borrow), Repair, Exit, Entrance 4 Erase wristband, Tickets erase 5 Barcode 6 External 7 Member Export 8 Member Import 10 Entrance 12 Entrance Denied 20 Exit 22 Exit Denied 30 Locking OK 31 Payed Locking OK 32 Locking Denied 33 Locking failed 34 Locking/Unlocking Error 40 Unlocking OK 43 Unlocking failed 49 Unlocking OK - Alarm Delay 50 Passage 52 Passage Denied 60 Push-button 61 Do Not Disturb 62 Make my Room 63 Room Cleaned 64 Reception Request 70 Deposit Activated 75 Deposit Deactivated 90 ALARM 91 Supervised locker break-in 100 Card 101 PIN 102 External / Remote 120 Card - Deposit 200 OK 201 Set Pay 202 Reset Pay 203 Activate Deposit 204 Deactivate Deposit 250 Denied 251 Wrong Reader Unit 252 Deposit Denied 300 Coin accepted 301 Temporary saldo erased 320 Vending OK 321 Vending Error 401 Locker closed after prelock Page 5

185 XML packages Event Info 402 Locker closed after unlocking 403 Locker opened after warning 404 Locker remained prelocked 405 +UWT 406 Prelocking not confirmed 450 "Pin" temporarily inhibited 451 "CodE" temporarily inhibited 452 "Scod" temporarily inhibited 460 Prelocking inhibited 490 Unlock request accepted 500 Free passage ON 501 Free passage OFF 510 Signal Alarm 511 Signal Armed ON 512 Signal Armed OFF 513 Signal PIN 514 Signal Test 515 Alarm Sensor Activated 516 Alarm Sensor Deactivated 517 Door Unlocked 518 Door Locked 519 Door Opened 520 Door Closed 521 Entrance Deactivated 522 Exit Deactivated 601 Update sold Tickets 602 Assign Procedure 603 Unlocking request 604 ELS Key Exchange Request 605 ELS Key Exchange Answer 606 WBC Closed After Timeout 607 Buyer Export 608 Buyer Import 609 Settle All Cards 610 External Payment 611 SMS Interface 612 S.M.SW Member Import 613 S.M.SW Locker ELS NET Export 614 WBC Closed 900 Power ON 901 General interrogation received 902 Start responding 903 Stop responding 904 Start multiple responses 905 Stop multiple responses 910 Time Set 911 New Time 912 Summer Time 913 Winter Time 920 Box Opened 921 Box Closed 930 Operating parameters OK 931 Operating parameters constructional 932 Requested initialization XMLeviU5.doc Page 6

186 XML packages Event Info 933 Automatic initialization 940 Error Terminated 941 Error 953 Coin acceptor start responding 954 Coin acceptor stop responding 960 SECURE Card 961 DOWNLOAD Card 962 SERVICE Card 963 CLEAN Card 964 ERASE Card 965 WARD Card 966 MASTER key 967 FAILSAFE key 990 Buffer overrun 999 State XMLeviU5.doc Page 7

187 XML packages Event Info XMLeviU5.doc 3.2 Modes 1 User Key 2 Ticket 3 Ticket Captured 4 Multi user key 5 MASTER key 6 MULTI key 7 FAILSAFE key 8 Push-button 9 ALARM 10 Entrance 11 Passage 12 Date 13 Time 14 Last Day 15 Day 16 Points 17 D Points 18 Direction 19 Not Valid 20 Exit 21 Tokens 22 MINI Card 23 Entrance delay 24 Locker 25 Add Charge 26 Refund 27 Borrow/PAY 28 Exit Counter 29 Cancelled LCC Card 30 Cancelled LCC Ticket 31 Denied LCC Ticket 32 Device Break-in 33 Door Break-in 34 Door Opened too long 35 Borrow 36 Delivery 37 Deny Exit 38 Electronic Money 39 WBC Full 40 Deposit 41 Maid key 42 OFF 43 ON 44 External 45 Busy 46 Minutes 47 Ring 48 Unfinished Document 49 Entrance Time Date 50 Passage 51 Child Page 8

188 XML packages Event Info XMLeviU5.doc 52 Pay Set 53 Pay Reset 54 Pay Set/Reset 55 Request 56 Answer 57 Event 58 One passage 59 Permanent Passage Change 60 First Day 61 Key denied 62 Not payed 63 User abort 64 Prelock 65 Timeout 66 Opened 67 Card Removed 68 D Minutes 69 D Minutes Gross 70 Clock 71 DELIVERY key 72 Delivery Not Possible 73 Extra 74 Group ticket 80 Motor error 81 "Err1" 82 "Err2" 85 Power off 86 Download required 87 File updated 90 Service required 91 Reader 1 92 Reader 2 95 Serial channel 97 Direct port 99 Unknown 101 Package 102 Result 111 EMERGENCY Key 112 Secret Code 113 Master Code 114 Network Time Table 115 Network Pushbutton 116 Automatic Opening 117 Pushbutton PCB 118 Door Opened 119 Free 120 Permanent key 121 Additional Payment 122 Occupy 123 Release Page 9

189 XML packages Event Info XMLeviU5.doc 4 Appendix An XML file is attached to the document which is same as the example XML package. Page 10

190 XML packages Locker Info XMLlriU5.doc Locker Info XML package Revision: Date Comment Creation of document Revision of comments of XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

191 XML packages Locker Info XMLlriU5.doc 1 General This XML package is sent by 3 rd party SW to obtain information (in the respective result package) about particular locker status parameters and last 50 events from Metra ELS system. Locations are used in locker systems where several lockers exist with the same locker number. Therefore they are assigned to different locations to enable unique treatment of each. The package is sent to Metra interface server through the Metra TCP/IP interface. Information is returned from Metra interface server in the result package. Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and additional locker parameters depending on the parameters given in the Locker Info package. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. Page 2

192 XML packages Locker Info XMLlriU5.doc 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>lockerinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <locker>1234</locker> Locker number (1-7999) integer mandatory field <location>1</location> Location ID (1-9999) integer mandatory field if locations are used in the system </parameters> / / <userdata>xyz</userdata> Userdata Varchar (30) Result of this XML package includes same userdata if sent here </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <locker> Locker / <location>1</location> Location ID (1-9999) of locker integer Same locker numbers are possible on different locations <locker>1234</locker> Locker number integer <state>0</state> State ID Integer <statedescription>vacant</statedescription> State Description Varchar (30) In English only <events> Events <event> Event <eventid> </eventid> Event id Integer Unique event id from Metra DB Page 3

193 XML packages Locker Info XMLlriU5.doc <dt> t11:51:40</dt> Timestamp of event Given in example <code>288</code> Event code integer <codedescription>unlocking OK</codedescription> Event code Description Varchar (30) In English only <mode>9</mode> Mode ID Integer <modedescription>pushbutton</modedescription> Event mode Description Varchar (30) In English only <statebefore>2</statebefore> State ID Integer <statebeforedescription>occupied</statebeforedescription> State Description Varchar (30) In English only <stateafter>0</stateafter> State ID Integer <stateafterdescription>vacant</stateafterdescription> State Description Varchar (30) In English only <card> d cfde639</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media </event> / / <event> Already described Already described <eventid> </eventid> Already described Already described <dt> t11:51:01</dt> Already described Already described <code>289</code> Already described Already described <codedescription>locking OK</codedescription> Already described Already described <mode>3</mode> Already described Already described <modedescription>user KEY</modedescription> Already described Already described <statebefore>2</statebefore> Already described Already described <statebeforedescription>occupied</statebeforedescription> Already described Already described <stateafter>2</stateafter> Already described Already described <stateafterdescription>occupied</stateafterdescription> Already described Already described <card> d cfde639</card> Already described Already described </event> / / <event> Already described Already described <eventid> </eventid> Already described Already described <dt> t11:50:48</dt> Already described Already described <code>288</code> Already described Already described <codedescription>unlocking OK</codedescription> Already described Already described <mode>3</mode> Already described Already described <modedescription>user KEY</modedescription> Already described Already described <statebefore>2</statebefore> Already described Already described <statebeforedescription>occupied</statebeforedescription> Already described Already described <stateafter>0</stateafter> Already described Already described Page 4

194 XML packages Locker Info XMLlriU5.doc <stateafterdescription>vacant</stateafterdescription> Already described Already described <card> d cfde639</card> Already described Already described </event> / / </events> / / </locker> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 5

195 XML packages Locker Info XMLlriU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 6

196 XML packages Lockers Info XMLlsiU5.doc Revision: Date Comment Creation of document Lockers Info XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

197 XML packages Lockers Info XMLlsiU5.doc 1 General This XML package is sent by 3 rd party SW to obtain information (in the respective result package) about several lockers status parameters from Metra ELS system. Locations are used in locker systems where several lockers exist with the same locker number. Therefore they are assigned to different locations to enable unique treatment of each. The package is sent to Metra interface server through the Metra TCP/IP interface. Information is returned from Metra interface server in the result package. Result Codes returned by the interface: Codes used in Metra interface are: 87 - ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing 5 - ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW 0 - ERROR_SUCCESS Operation succeeded For this XML package the result gives the result code and additional locker parameters depending on the parameters given in the Lockers Info package. 1.1 Communication In order to map a result XML package from the Metra Interface service to a request XML package from 3 rd party SW it is recommended to implement <userdata\> tag. If used, userdata can contain a Varchar (36) value. The Metra interface service will echo the userdata string from the request XML package in the respective Result package. This allows for unique identification of a Result in multi thread scenarios. Usage of this is highly recommended in integrations where certain procedures are not user dependant (e.g. cashier issues a ticket), but are executed using e.g. batch procedures. Page 2

198 XML packages Lockers Info XMLlsiU5.doc 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>lockersinfo</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <location>1</location> Location ID (1-9999) of lockers integer If none is given result will contain lockers from all locations </parameters> / / <userdata>xyz</userdata> Userdata Varchar (30) Result of this XML package includes same userdata if sent here </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer <lockers> Lockers / <locker> Locker / <location>5</location> Location ID (1-9999) of locker integer <locker>1</locker> Locker number integer <state>0</state> State ID Integer <statedescription>vacant</statedescription> State Description Varchar (30) In English only </locker> / / <locker> Already described Already described <location>5</location> Already described Already described Page 3

199 XML packages Lockers Info XMLlsiU5.doc <locker>2</locker> Already described Already described <state>0</state> Already described Already described <statedescription>vacant</statedescription> Already described Already described </locker> / / <locker> Already described Already described <location>5</location> Already described Already described <locker>3</locker> Already described Already described <state>0</state> Already described Already described <statedescription>vacant</statedescription> Already described Already described </locker> / / </lockers> / / </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 4

200 XML packages Lockers Info XMLlsiU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 5

201 XML packages Unlock XMLunlU5.doc Revision: Date Comment Creation of document Revision Unlock XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page 1

202 XML packages Unlock XMLunlU5.doc 1 General This XML package is sent by 3 rd party SW to unlock a particular locker in Metra ELS or ELS NET system. In Metra ELS NET system driven by 3 rd party SW through Metra ELS Locker reservation interface the parameter Location is not supported by the ELS NET reservation interface and therefore omitted in this XML package! In Metra ELS NET installations location is supported. Result Codes returned by the interface: Codes used in Metra interface are: ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. Page 2

203 XML packages Unlock XMLunlU5.doc 2 Example XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>unlock</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <locker>555</locker> Locker number from 1 to 9999 <location>1</location> Locker location Integer Used when lockers with same numbers exist in the system </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page 3

204 XML packages Unlock XMLunlU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page 4

205 XML packages White List XMLwliU5.doc Revision: Date Comment Creation of document Added removeall White List XML package Copyright 2007 All rights reserved. No part of this document may be reproduced in any form or by any means without prior written permission of Metra inženiring d.o.o. The contents of this manual are subject to change without notice. All efforts have been made to ensure the accuracy of the contents of this document at the time of going to press. However, should any errors be detected, METRA would greatly appreciate being informed of them. METRA can assume no responsibility for any errors in this manual. Page

206 XML packages White List XMLwliU5.doc 1 General This XML package is sent by 3 rd party SW to add/remove card/wristband to/from the White list; applies to ELS, ELS NET and LCC NET systems. Media on the white list is valid to be used on Metra ELS lockers and in general in the above mentioned systems. Packages are sent as strings through the Metra TCP/IP interface. Sent cardnumber is obtained from 3 rd party SW; it must be sent in Metra format. See document Metra_ELS_SN_Encoding.pdf. Result Codes returned by the interface: Codes used in Metra interface are: ERROR_INVALID_PARAMETER If parameters are not in the right format (e.g. invalid date format), or if some are missing ERROR_ACCESS_DENIED If the sender is not allowed to communicate through the Metra LCC NET interface; defined in Metra SW ERROR_INVALID_FUNCTION If card is on the black list or certain operation is not allowed ERROR_SUCCESS Operation succeeded For this XML package the result is generic, giving only the result code without any additional parameters. Page

207 XML packages White List XMLwliU5.doc 2 Examples 2.1 Add to white list XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>whitelist</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> e eb223</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <whitelist>add</whitelist> add parameter / Card will be added to white list </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

208 XML packages White List XMLwliU5.doc 2.2 Remove from white list XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>whitelist</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <card> e eb223</card> Unique Cardnumber in Metra format Varchar (36) Confirm with Metra for different types of media <whitelist>remove</whitelist> remove parameter / Card will be removed from white list </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

209 XML packages White List XMLwliU5.doc 2.3 Remove all from white list XML package Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>whitelist</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <whitelist>removeall</whitelist> remove all parameter / All cards will be removed from white list </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Result of this XML package includes same userdata </package> / / Result Comment Type Comment #2 <?xml version="1.0" encoding="utf-8" standalone="yes"?> / / <package> / / <header> / / <name>result</name> Package name / <version>1.0</version> Version / </header> / / <parameters> Parameters / <result>0</result> Result code Integer </parameters> / / <userdata>xyz</userdata> Userdata Varchar (36) Same userdata as sent with XML package </package> / / Page

210 XML packages White List XMLwliU5.doc 3 Appendix An XML file is attached to the document which is same as the example XML package. Page

211 THIRD-PARTY XML INTEGRATION MANUAL FORMAT MEDIA SN ENCODING 1.8 PO Box 531, Moonee Ponds, Victoria, Australia METRA AUS

212 R&D Media Encoding rules for when used in Metra LCC & ELS systems OB03_01 rev. 0 Project: Metra ELS & LCC Systems Document revision: 1.8 Date: 1. July 2012 Document Name: Metra Format Media SN Encoding.doc Brief description: This document describes Encoding of the unique serial number for different media (RFID tickets, barcodes) used in Metra LCC & ELS systems. It is intended as Encoding reference for programmers interfacing third party software (that reads RFID serial number by its own readers) to Metra LCC and ELS systems. Page 1

213 REVISION HISTORY: VERSION DATE AUTHOR CHANGES T. Rugelj First version of the document. Describes MIFARE T. Rugelj Paragraph 2.3 added L. Arnšek Technogym Paragraph added T. Rugelj ISO Paragraph added T. Rugelj Corrections T. Rugelj LF Multitag added. Few corrections in text T. Rugelj PIN added T. Rugelj Legic added L. Arnšek Barcode added Page 2

214 INDEX 1. FOREWORD MIFARE ENCODING RULES MIFARE CLASSIC (S50 AND S70) MIFARE ULTRALIGHT DIFFERENT MIFARE READERS FORMAT TECHNOGYM ENCODING RULES EXAMPLE ISO ENCODING RULES BYTE SERIAL NUMBER (I-CODE, TAG-IT) FUTURE EXTENSIONS FOR MORE THAN 8-BYTE SERIAL NUMBER LOW FREQUENCY (125 KHZ) MULTITAG ENCODING RULES PIN CODE ENCODING RULES LEGIC ENCODING RULES BYTE SERIAL NUMBER (LEGIC PRIME, LEGIC ADVANT ATC2048) BYTE SERIAL NUMBER (LEGIC ADVANT ATC256) FUTURE EXTENSIONS FOR MORE THAN 8-BYTE SERIAL NUMBER BARCODE ENCODING RULES CODING UP TO 14 BYTES LENGTH RECOGNISED FORMATS HEX ASCII CODING Page 3

215 1. FOREWORD When third party software needs to be interfaced to the Metra LCC or ELS systems the common point is the Media (RFID Ticket or Barcode) unique Serial Number. RFID: Third party software operates its own RFID Readers which must be capable of reading the RFID Unique Serial Number. The number must be then transformed to Metra format that is accepted by Metra software Interfaces. Barcode: Third party SW can generate 1D or 2D barcodes on its own. Depending on the type (DEC, HEX or ASCII) and length different transformation rules to Metra format apply. Metra formatted Ticket Unique Serial number is always 18 bytes long. Page 4

216 2. MIFARE ENCODING RULES Mifare RFID cards have either 4-byte or 7-byte serial number. Encoding rules for Metra ELS are as follows. 2.1 Mifare Classic (S50 and S70) Mifare Classic: Mifare 1K / Mifare S50 Mifare 4K / Mifare S70 Have 4-byte unique Serial Number Metra Prefix Mifare Unique Serial Number (14 bytes fixed value) (4-bytes) D SN SN SN SN 2.2 Mifare Ultralight Unique Serial Number which is 7 bytes long have the following Mifare RFID Tags: Mifare Ultralight Mifare Desfire Future Mifare Plus Metra Prefix Mifare Unique Serial Number (11 bytes fixed value) (7-bytes) SN SN SN SN SN SN SN 2.3 Different Mifare Readers format Some Mifare readers presents Mifare Unique Serial Number in different formats (half byte or byte order differs). Metra offers customers possibility to analyse their existing Mifare Tag and suggest how to compose Metra ELS Serial Number format from serial number read with existing 3 rd party reader. Customer should: Send one sample Mifare Tag to Metra Give Metra information what is the interpretation of media Unique Serial Number read from existing 3 rd party Mifare Reader. Page 5

217 3. TECHNOGYM ENCODING RULES TechnoGym RFID keys have a 4-byte Club Code and a 3-byte Customer Code. Encoding rules for Metra ELS are as follows: Metra Prefix TechnoGym Club Code TechnoGym Customer Code (11 bytes fixed value) (4-bytes) (3-bytes) SN SN SN SN SN SN SN 3.1 Example Club Code: 11ABDCEF Customer Code: TechnoGym key in Metra format ABCDEF Page 6

218 4. ISO ENCODING RULES byte serial number (I-CODE, TAG-it) Metra Prefix ISO15693 Unique Serial Number (10 bytes fixed value) (8-bytes) SN SN SN SN SN SN SN SN 4.2 Future extensions for more than 8-byte serial number Metra Prefix Leading zeroes and RFID Unique Serial Number (2 bytes fixed value) (16 bytes in total) SN SN SN SN SN SN SN SN SN Page 7

219 5. Low Frequency (125 khz) Multitag ENCODING RULES Metra Prefix TAG Type prefix (9 bytes fixed value) (1 byte) 00 0B EM Marin Hitag 1 or Hitag S 02 Hitag 2 03 EM Marin 4450 TAG Unique Serial Number (8-bytes) SN SN SN SN SN SN SN SN If serial number is less than 8 bytes upper bytes are fixed to 00! Page 8

220 6. PIN code ENCODING RULES PIN code maximum length is 12 digits coded in ASCII. Leading characters are all 0x00. PIN length is seen from number of non 0x00 characters. PIN can have leading zeroes itself coded in ASCII as 0x30. EXAMPLES: PIN = (length 5) Metra Prefix (2 bytes fixed value) Leading Zeroes (4 bytes) PIN (12 bytes) 0x x x PIN = (length 6) Metra Prefix (2 bytes fixed value) Leading Zeroes (4 bytes) PIN (12 bytes) 0x x x Page 9

221 7. LEGIC ENCODING RULES byte serial number (Legic PRIME, Legic ADVANT ATC2048) Metra Prefix Legic Unique Serial Number (14 bytes fixed value) (4 - bytes) SN SN SN SN byte serial number (Legic ADVANT ATC256) Metra Prefix Legic Unique Serial Number (10 bytes fixed value) (8 - bytes) SN SN SN SN SN SN SN SN 7.3 Future extensions for more than 8-byte serial number Metra Prefix Leading zeroes and RFID Unique Serial Number (2 bytes fixed value) (16 bytes in total) SN SN SN SN SN SN SN SN SN Page 10

222 8. BARCODE ENCODING RULES Third party SW can generate 1D or 2D barcodes on its own. Depending on the type (HEX or ASCII) and length different transformation rules to Metra format apply. Metra devices currently support 2D barcode readers, hence the prefix value (3 rd & 4 th byte). 8.1 Coding up to 14 bytes length Recognised formats HEX Barcodes recognised as purely HEX values (same goes for DEC) are coded by the following rules. This applies if the whole barcode in recognised as purely HEX! Barcode maximum length is 14 bytes. Leading characters are all 0x00. E.g. signs 1 and b are joined in one byte as 0x1B. This way the max length of a HEX barcode is 28 characters (14 bytes). Metra Prefix Leading zeroes and Barcode Serial Number (4 bytes fixed value) (14 bytes in total) SN SN SN SN SN SN SN SN SN Page 11

223 Examples No. Value Length Comment Barcode Metra format 2D reader 1D CODE Max DEC only D PDF Max DEC only D QR Max DEC only D CODE ABCDEF AB 28 Max HEX Only ABCDEF AB 2D PDF ABCDEF AB 28 Max HEX Only ABCDEF AB 2D QR ABCDEF AB 28 Max HEX Only ABCDEF AB Page 12

224 8.1.2 ASCII coding Barcodes not recognised as purely HEX or DEC are coded as ASCII characters by the following rues. Barcode maximum length is 14 bytes coded in ASCII. Leading characters are all 0x00. Metra Prefix Leading zeroes and Barcode Serial Number (4 bytes fixed value) (14 bytes in total) SN SN SN SN SN SN SN SN SN Page 13

225 Examples No. Value Length Comment Barcode Metra format 2D reader 1D CODE METRAABCD 14 Max ASCII D D PDF METRAABCD 14 Max ASCII D D QR METRAABCD 14 Max ASCII D Page 14