Managing Assets from AMA

This document describes how AMA can be used to manage assets. The same operation is available from the admin page in the web application Asset.

Definitions

In this context, any reference to an asset will be an entity that is inactive and has no support for updating its own properties like status or location. All updates for an asset must be done by other parties (like a user updates the status) or a device with a relation to the asset. A device in this context is an entity with the capability to update its own properties and any asset with a relationship to the device. A vehicle with GPS is an example of a device, where its location can be updated automatically.

Terms

The below following terms is used by the API resources related to managing asset/devices. The sometimes confusing fact is that three - 3 - different identifiers are used to represent one single asset, the legacyId, the internalId and the epc. Read about them below.

Terms	Description	Example
legacyId	The custom asset identifier displayed in Asset, an ID that most be unique within one Asset installation. This is the identifier that web users will see and be able to use in searches etc.	999999
internalId	The "raw" and low level ID that can be associated with a legacyId through a mapping. External sensors can use the internal ID when sending in updates through Herder	ANY-THING
assertType	This is the product identifier for an asset or device, more specifically - the maser data key to lookup master data on the asset	urn:epc:idpat:giai:0000000.*
internalType	InternalType defines the internalId type, possible values are IMEI for devices and EPC for assets	IMEI/EPC
epc	This is the globally unique ID used by Asset for tracking assets and devices, is is the epc that will populate the EPCIS events in Asset's EPCIS backend.	urn:epc:idpat:giai:0000000.1234
timestamp	The commisson time to use, defaults to server time if not used. ISO-8601 with format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.	2010-11-04T14:00:29+01:00
latitude/logitude	GPS position, valid values are ±90 for latitude and ±180 for longitude.

Register new asset or device

The following AMA endpoints can be used to add asset and devices. Both endpoints supports the flag forceUpdate, the flag should only be used when associating a new internalId to an already registered asset or device.

/api/1/asset/admin/asset
/api/1/asset/admin/device

Example

Register a new device from AMA.

POST /api/1/asset/admin/device

internalId=device-id&internalId=device-internal-id&assetType=urn:epc:idpat:giai:0000000.*

POST /api/1/asset/admin/device (lat/lng alternative)

internalId=device-id&internalId=device-internal-id&assetType=urn:epc:idpat:giai:0000000.*&latitude=61.76622029999999&longitude4.875090199999931

Response

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns4:amaResponse xmlns:ns2="urn:epcglobal:epcis-masterdata:xsd:1" 
 xmlns:ns3="urn:epcglobal:epcis:xsd:1" 
 xmlns:ns4="http://schema.tracetracker.com/ttAMA" 
 xmlns:ns5="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" 
 xmlns:ns6="urn:epcglobal:epcis-query:xsd:1">
  <status>
    <statusCode>10000</statusCode>
    <statusMessage>Request OK, parameters legal with legal values.</statusMessage>
  </status>
  <params>
    <legacyId>device-id</legacyId>
    <internalId>device-internal-id</internalId>
    <internalType>IMEI</internalType>
    <forceUpdate>false</forceUpdate>
  </params>
  <backendStatistics>
    <herder>
      <updated>false</updated>
      <updateCode>40001</updateCode>
      <updateMessage>Herder not updated.</updateMessage>
    </herder>
    <epcis>
      <updated>false</updated>
      <updateCode>20000</updateCode>
      <updateMessage>Commission event created for legacy id device-id</updateMessage>
    </epcis>
    <mds>
      <updated>true</updated>
      <updateCode>30000</updateCode>
      <updateMessage>MDS updated.</updateMessage>
    </mds>
  </backendStatistics>
  <MasterDataElement id="urn:epc:idpat:giai:0000000.*" 
   urn__tracetracker__asset__mda__asset_name="Bajonettsag REMS CAT VE" />
</ns4:amaResponse>

Description of "updateCode" returned in amaResponse.

Description of the value returned in the updateCode child element of mds, epcs and heder in backendStatistics. Note that there are multiple codes that represents success.

MDS

Herder

EPCIS

code	description
30000	Success, mapping created
30001	Success, mapping not created
30501	Unable to connect to MDS.
30503	Unexpected response from MDS server.

code	description
40000	Success, New device created in Herder
40001	Success, Herder not updated.
40100	Success, Herder device deleted.
40500	Internal error in Herder.
40501	Unable to connect to Herder.
40502	Unable to read response from Herder.

code	desciption
20000	Success, Commission event created
20001	Success, EPCIS not updated
20100	Success, Decommission event created
20500	Internal error in EPCIS server.
20501	Unable to connect to EPCIS server.
20503	Unexpected response from EPCIS server

List and edit asset and device

The following endpoints can be used for listing all registered assets and devices and for removing of associated internalIds.

/api/1/asset/admin/mapping
/api/1/asset/admin/mapping/list

API Documentation

The documentation for the API is found at ASSET-URL/api, it contains details about all AMA resources.