Interface Specification POSLOGISTICS-10697 Interface specification for Columna Service Logistics - Track Services Version 1.12, reduced for tracking purposes Prepared for: Integrators SSE/10697/IFS/0002$Revision: 1.62$ $Date: 21 Sep 2015$
Interface Specification Project: $POSLOGISTICS-10697 Revision: $Revision: 1.62$ $Date: 21 Sep 2015$ Document: $SSE/10697/IFS/0002 Copyright (c) 2013 by Systematic Group. It shall not be copied, reproduced, disclosed or otherwise made available to third party without previous consent from Systematic Group 1
Table of Contents 1 Introduction... 3 1.1 Scope... 3 1.2 Definitions... 4 1.3 References... 4 1.4 Change log... 4 2 Communication Flows... 7 3 Capturing events... 9 2
1 Introduction This document describes the service API for Track Services. The Track Services system distributes tracking events from tracking systems that are based on technologies such as RFID, Wi-Fi, and barcodes. Such events can be consumed without understanding the details of the underlying tracking systems. The API is based on the EPCIS standard [EPCIS] and consequently, many design decisions originates in the standard. A separate, proprietary interface is defined for functionality that is not covered by the EPCIS specification. This document is aimed at software developers constructing systems that consume tracking events from Track Services or publish tracking events to Track Services using its standard interface. It should be possible to use the Track Services API based solely on this document, and detailed API information provided by the Track Services API itself. The document describes intent and design decisions, while the API itself provides details about protocols and data formats. However, to fully understand the context and design decisions, the EPCIS specification [EPCIS] and the Reference Architecture for tracking systems [REFARC] are recommended reading. 1.1 Scope Track Services provides two APIs: One used by tracking systems to feed events into Track Services. One used for communicating tracking events and related data from Track Services to Consumer Systems. Tracking event subscriptions are not configured through an API but in Track Services database by system administrators. This document describes how in section Error! Reference source not found.. Information about locations is provided by Service Logistics Location Service. See [LOCSVC] for details. 3
1.2 Definitions EPC EPCIS Object ID Tracking ID Electronic Product Code. GS1 Standard describing the use of identifiers in tracking scenarios. EPC Information Services Specification. GS1 Standard describing the exchange of tracking events. The ID of a tracked object which is tied to the object itself. For example a social security number. Often referred to as Genuine ID though that term is not used in this document. The ID of a tracked object which is tied to a tag that is used for tracking it. Often referred to as a Pseudo ID though that term is not used in this document. A tracked object can have more than one tag and therefore more than one tracking IDs 1.3 References [EPCIS] EPC Information Services Specification version 1.0.1 http://www.gs1.org/gsmp/kc/epcglobal/epcis/ep cis_1_0_1-standard-20070921.pdf [EPCIS WSDL] Web service definition for the EPCIS interface. http://www.gs1.org/gsmp/kc/epcglobal/epcis/ep cis_1_0-schema-20070412/epcglobal-epcisquery-1_0.wsdl [REFARC] Referencearkitektur for Sporbarhed og Emneidentifikation i Region Midtjylland, version 2.1 1.4 Change log This chapter describes the major changes involved in each change set. 4
Version Date Notes 1.0 December 2 2013 First draft version 1.1 March 4 2014 First full-scope version 1.2 April 1 2014 Extended with subscription of tracked object data 1.3 May 27 2014 Modifications to Tracked Object API. Track Services specific extensions to EPCIS output. Track Services specific extensions to business steps. 1.4 June 25 2014 Modifications to Tracked Object API: A tracked object can now have multiple tracking ids A tracked object is now uniquely identified by class id and object id, as a consequence the URL for querying a single tracked object now requires the class id as well XML namespace of tracked objects has been added. Added method for posting multiple tracked objects More description of when to expect specific http status codes. Error! Reference source not found. updated with some additional classes. A few classes were renamed. 1.5 August 12 2014 Modifications to Tracked Object API: A tracked object is identified by a globally unique URN Subscription data format is XML Updated endpoints 1.6 August 26 2014 Modifications to EPCIS subscription schema (Section Error! Reference source not found.): Position and Locations moved to element ObjectEvent from element ObjectEventExtension 1.7 September 4 2014 Modifications to Event Queries section. Removal of Master Data Queries section Description of how to encode URNs 1.8 September 18 2014 Modifications to Event Queries section: EPCISconformant SOAP request. Error! Reference source not found. updated with some additional classes. A few classes were renamed. 5
1.9 November 5 2014 Added tracked objects error contract to tracked objects management API Corrected identifier for Tracked Object class Vehicle Added namespace to TrackedObjectChangeList 1.10 November 19 2014 Error! Reference source not found. extended with description of casing policy on APIs. 1.11 February 11 2015 Example event updated to February 2015 edition. Query interface updated to version 2. Version 1 (document version 1.10) is still supported. 1.12 September 18 2015 Capture interface for sending events to Track Services added to this document. No changes to the query or subscription interface. 6
2 Communication Flows An overview of the essential communication flow is shown in Figure 1. The systems involved in this communication are: A Consumer System that needs to receive tracking events and be able to interpret them. A Tracking System that actually tracks certain objects. This could e.g. be an RFID system, an ultra-sound tracking system, or a barcode system. Track Services that distributes tracking events from one or more Tracking Systems to Consumer Systems. Track Services also exposes master data needed to interpret events, and to relate tracked objects to physical objects (described below). An Object Data Authority that is the authoritative data source for one or more types of tracked objects. This could e.g. be an equipment management system that stores information about medical equipment. Typically this is also where the mapping between object IDs (e.g. equipment number) and tracking IDs (e.g. RFID-identifier) is stored. Track Services has an API that allows object data authorities to register the mapping between object IDs and tracking IDs. In the EPCIS standard tracking events only contain the tracking ID. However, Track Services exposes a non-standard API so Consumer Systems can fetch the relevant ID mappings from a single source. In some cases, the Consumer System will retrieve other object data directly from the Object Data Authority. If the ID mapping is part of this object data, it need not be retrieved from Track Services. In other cases there is no Object Data Authority and the ID mapping can be entered manually in the Track Services administration UI. If no ID mapping is recorded anywhere, objects can only be tracked by their tracking IDs. Location Services which stores information about physical locations. Often data from location services will be needed to interpret the events received from Track Services because events only contain the ID of a location. Location services expose the location s name, type etc. 7
Object Data Authority Objects Consumer System Master data Events ID mapping Scope of this specification Track Services Location Services Events Tracking System Figure 1: Essential data flows between the systems involved. Seen from a consumer system s perspective these are these essential steps in the communication flow: 1. A system administrator configures subscriptions for tracking events, essentially by specifying an EPCIS Event Query and a callback URL. See section Error! Reference source not found.. 2. A Consumer System fetches event data objects using an EPCIS Event Query. See section Error! Reference source not found.. 3. Track Services continuously sends events to Consumer Systems as defined by the configured subscriptions. Each event may say where objects are located, that a new object is now being tracked, or that an object is no longer being tracked. 4. If a Consumer System ever gets out of sync (e.g. if the system is shut down for a longer period) it must fetch event data for all objects using an EPCIS Event Query. Master data queries and event queries are made via SOAP according to [EPCIS], while event notifications and object management uses XML over HTTP. In the following sections all elements of this communication flow is described in detail. 8
3 Capturing events This section describes the standard interface for sending new events to Track Services. The information that must be provided in this interface is based on the EPCIS Capture specification. However, the protocol and data format may differ from the typical EPCIS formats, just as Track Services supports custom built protocols for integrating to existing tracking systems. The following general purpose format can be used to send tracking events to Track Services via HTTP POST: { } "trackingsystemid": "My tracking system", "telegramid": "1", "events": [{ "locationid": urn:epc:id:sgln:57980100.3450.0 "dataid": "1", "tagid": urn:dev:mac.000000000003,, "regtime": 2015-01-01T12:00:00Z }, { "locationid": urn:epc:id:sgln:57980100.3456.0, "dataid": "2", "tagid": urn:epc:id:grai:112233.445566.775000000000, "regtime": 2015-01-01T12:00:00Z }] Parameter trackingsystemid telegramid locationid dataid tagid regtime Description Identifies the tracking system who is the dispatcher of this event Used for uniquely identifying the telegram Location of where the event occurred Identifies the event within the telegram The tracking id for the that has moved The time the event occurred. This value must be specified is ISO 8601. If no time zone is specified local time is assumed. 9