AMA Event import

Introduction

Asset expects that every event found, related to a given EPC (asset), contains the whole state. This means that you should never update an asset EPC by uploading events directly to the EPCIS server as it may create inconsistency in the captured data.

This endpoint will extend any ObjectEvents received with the missing extensions, (extensions found in previous event) before importing the events into the EPCIS service. The endpoint will also split any ObjectEvents that contains more than one epc in the epcList.

This endpoint accepts only ObjectEvents and AggregationEvents, where all AggregationEvents will be send to the EPCIS server without any change.

On this page:

Event Extensions

The following extensions in namespace http://www.tracetracker.com/data and can be used when importing ObjectEvents related to an EPCs known by Asset.

Name	Description	Type	Example
`asset_department`	The extension describes what department the asset is currently assigned to	DEPARTMENT	`urn:tracetracker:asset:idpat:department:9999.5144c63.*`
`asset_location`	The extension describes what project the asset is current at, the value should be a project EPC.	EPC-BIZ	`urn:gtnet:id:gsli:1.2652`
`asset_status`	The extension describes the current status for an asset, the value must be a status id.	StatusId	`10_idle`
`comment`	A text comment that will be visible in the details about an asset.	Text	`<![CDATA[My comment]]>`
`current_entity`	Describes the current entity an asset is in.	EPC	`urn:gtnet:id:gsii:1.441502.441501`
`enter_location`	Project history uses this extension when searching for asset entering a location, the the extension should be used on the first event when an asset entered a new project. It should contain EPC for the project the asset is entering.	EPC-BIZ	`urn:gtnet:id:gsli:1.2652`
`entering_entity`	The extension can be used in the first event when an asset was entering a new project.	EPC	`urn:gtnet:id:gsii:1.441502.441501`
`geo_location`	This extension is for storing the current position of the asset, the value should be latitude and longitude separated by comma.	latlng	`1.766227,4.875130`
`into_entity`	The extension can be used in the first event when an asset was put into another asset (container/vehicle).	EPC	`urn:gtnet:id:gsii:1.441502.441501`
`leave_location`	Is for storing the project that the asset was last leaving.	EPC-BIZ	`urn:gtnet:id:gsli:1.2652`
`leaving_entity`	Tells what is leaving a project.	EPC	`urn:gtnet:id:gsii:1.441502.441501`
`outof_entity`	Tells what is leaving another asset, like an asset is taken out of a container.	EPC	`urn:gtnet:id:gsii:1.441502.441501`
`asset_service_schedule`	Schedule a one-time-reminder on a particular asset.	Event time	`2014-04-11T16:25:03.000+03:00`
`asset_service_repeat_reminder`	Schedule a repeat reminder that is auto-snoozed by asset when they expire.	Event time	`2014-04-11T16:25:03.000+03:00`
`service_notes`	Make comments about an asset servicing.	Text	`Changed Steering Hydraulic fluid`
`service_performed`	Record a servicing event for a given Asset EPC.	Event Time	`2014-04-11T16:25:03.000+03:00`

Restricted Extensions

The following extension in namespace http://www.tracetracker.com/data are reserved and may not be used when importing events. The whole import will fail if any of the event is using one of the extensions.

Name	Description	Type
active_vehicle	EPC is an vehicle that participates in Driver Logbook, used by the driver log.	EPC
asset_category	Describes the category for the EPC.	CategoryId
correction	Included in events that was created to correct inventory	type of corrrection
distance	The current distance of a trip, used by the driver log.	Number
driver	The driver id for a trip, used by the driver log.	username
end_location	The geo position where a trip ended, used by the driver log.	latlng
end_location_alias	The address where a trip ended, used by the driver log.	Text
end_time	The time when the trip ended, used by the driver log.	DateTime
module_asset_access	Flag indicating if the event should be visible in the asset module	boolean
module_driver_access	Flag indicating if the event should be visible in the driver module.	boolean
start_location	The geo position where a trip started, used by the driver log.	latlng
start_location_alias	The address where a trip started, used by the driver log.	Text
start_time	The time when the trip started, used by the driver log.	DateTime
status_changed	Extension included when status is changed by user.	boolean
trip	The id of a trip, used by the driver log.	EPC
type	The trip type, used by the driver log.	TripType
updated_by	Identity of what is updating the EPC	username
vehicle	The id of the vehicle, used by driver log.	EPC
asset_sign_off	The last user to perform an update on an item. Note that if this extension is included by user, its value is over-written to match current user performing any AMA event that modifies an asset.

module_asset_access and module_asset_driver

Functions for these extensions can be overridden by settings in the Master Data Service. For example to view assets with no access to the Asset Module (module_asset_access = false) within the Asset module, set the attribute showAllVehiclesInAssetModule of the configuration element urn:tracetracker:%companyPrefix%:asset:config:SettingsConfiguration to true.

Validation

Any use of extension defined in Event Extensions table will be validated according to their type. The whole import will fail if any events fails the validation.

EPC/EPC-BIZ type must be a reference to an entity that Asset knows about.
StatusId type must be one of the status id the Asset instance is configured with, contact the administrator of the instance to get the complete list.
Text type can contain anything and will not be validated, we recommend to wrap the text in a CDATA element to avoid creating invalid XML.
latlng type must be a latitude and longitude value separated by comma.
Any import of events that both uses asset_location and geo_location will fail if the geo_location is outside of the asset_location boundary.
Any import of events that uses one of the extensions defined in the Event Extensions table will fail if the events includes epc that are not known in Asset.

Example

The following sections gives you an example of what extension should be included in operations like updating the status, location and position of an asset. The events must include the http://www.tracetracker.com/data namespace.

<?xml version="1.0" encoding="utf-8"?>
<epcis:EPCISDocument xmlns:epcis="urn:epcglobal:epcis:xsd:1" xsi:schemaLocation="urn:epcglobal:epcis:xsd:1 
 http://www.epcglobalinc.org/standards/epcis/epcis_1_0-schema-20070412/epcglobal_1_0.xsd"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" schemaVersion="1"
 xmlns:tt="http://www.tracetracker.com/data"  creationDate="2012-06-14T07:41:16.452+02:00" >
 <EPCISBody>
  <EventList>
   <!-- ObjectEvent -->
  </EventList>
 </EPCISBody>
</epcis:EPCISDocument>

Update location

Update the location of an Asset by including asset_location extension containing the EPC of the location, the bizLocation id. AMA will update the geo_location extension with the position resolved from the asset_location value.

<ObjectEvent>
 <eventTime>2012-06-16T02:51:29.523+02:00</eventTime>
 <eventTimeZoneOffset>+03:00</eventTimeZoneOffset>
 <epcList>
  <epc>urn:gtnet:id:gsii:1.441502.441501</epc>
 </epcList>
 <tt:asset_location>urn:gtnet:id:gsli:1.2652</tt:asset_location>
</ObjectEvent>

Update geo-position

Update the geo-position of an Asset by including geo_location extension containing the latitude and longitude for the new position. AMA will update the asset_location extension with the location resolved from the geo_location value.

<ObjectEvent>
 <eventTime>2012-06-16T01:51:29.523+02:00</eventTime>
 <eventTimeZoneOffset>+03:00</eventTimeZoneOffset>
 <epcList>
  <epc>urn:gtnet:id:gsii:1.441502.441501</epc>
 </epcList>
 <tt:geo_location>59.910811,10.746421 </tt:geo_location>
</ObjectEvent>

Update status

Update the status of an asset by including the asset_status extension containing a status id.

<ObjectEvent>
 <eventTime>2012-06-16T01:51:29.523+02:00</eventTime>
 <eventTimeZoneOffset>+03:00</eventTimeZoneOffset>
 <epcList>
  <epc>urn:gtnet:id:gsii:1.441502.441501</epc>
 </epcList>
 <tt:asset_status>10_idle</tt:asset_status>
</ObjectEvent>

Schedule a Reminder

Schedule a Servicing reminder for an asset by using extension asset_service_schedule extension containing a given date.

<ObjectEvent>
 <eventTime>2012-06-16T01:51:29.523+02:00</eventTime>
 <eventTimeZoneOffset>+03:00</eventTimeZoneOffset>
 <epcList>
  <epc>urn:gtnet:id:gsii:1.441502.441501</epc>
 </epcList>
 <tt:service_schedule>2014-04-07T17:30:02.100+03:00</tt:service_schedule>
</ObjectEvent>

Record a Service

Record a Service by including service_notes and service_performed extensions as described in the extensions above.

<ObjectEvent>
 <eventTime>2012-06-16T01:51:29.523+02:00</eventTime>
 <eventTimeZoneOffset>+03:00</eventTimeZoneOffset>
 <epcList>
  <epc>urn:gtnet:id:gsii:1.441502.441501</epc>
 </epcList>
  <tt:service_performed>2014-04-07T17:30:02.100+03:00</tt:service_performed>
   <tt:service_notes>Changed the Exhaust manifold system</tt:service_notes>
</ObjectEvent>

Response

The following response will be returned from a import of two EPCIS documents, each with two events. A errorMessage will be included in the importResult if the status is not 200.

<?xml version="1.0" encoding="UTF-8"?> 
 <importResults> 
  <importResult>
   <eventCount>1</eventCount>
   <fileName>ama-event-1340014376855-location-update.xml</fileName>
   <userId>administrator</userId>
   <status>200</status>
 </importResult>
 <importResult>
  <eventCount>1</eventCount>
  <fileName>ama-event-1340014376859-geo-location-update.xml</fileName>
  <userId>administrator</userId>
  <status>200</status>
 </importResult>
</importResults>

Example: Change status using TAG/LEGACY

This is an example for how you can change the status of an asset by importing ObjectEvent containing TAG/LEGACY ids.

Preparation: Assign a TAG to an Asset.

POST https://server/asset/api/1/asset/admin/asset

legacyId=999999&internalId=TAG-1&forceUpdate=true

The POST request will assign TAG-1 to the asset with legacy id 999999, and you can now use TAG-1 in the epcList instead of the assets complete EPC.

Change status via TAG

<ObjectEvent>
 <eventTime>2012-09-18T11:49:37.571+02:00</eventTime>
 <eventTimeZoneOffset>+03:00</eventTimeZoneOffset>
 <epcList>
  <epc>TAG-1</epc>
 </epcList>
 <action>OBSERVE</action>
 <tt:asset_status>20_idle</tt:asset_status>
</ObjectEvent>

Change status via LEGACY

<ObjectEvent>
 <eventTime>2012-09-18T11:49:37.571+02:00</eventTime>
 <eventTimeZoneOffset>+03:00</eventTimeZoneOffset>
 <epcList>
  <epc>999999</epc>
 </epcList>
 <action>OBSERVE</action>
 <tt:asset_status>20_idle</tt:asset_status>
</ObjectEvent>

Any tags must be mapped before using them in the event API. Events containing unknown tags will be stored directly in the EPCIS server without any transformation to EPC (as long as they don't use any reserved extension). Use of reserved extension with an unknown TAG will result in error.