Capture interface

Capture Interface

Capture of EPCIS data is done by calling the HTTP endpoints POST /v1_2/Capture or POST /v2_0/Capture. These endpoints allow to capture both EPCIS events and CBV masterdata

Event Capture

One capture request can contain one or multiple EPCIS events.

There is no practical limit on the number of data contained in a single request, although the capture of a huge number of events in a single requests can lead to performance issues in both capture and subscriptions methods.

Format

FasTnT repository allows the capture of EPCIS event in XML format (as defined in GS1's 1.2 specification) on endpoint /v1_2/Capture. Allowed content-types are text/xml and application/xml

Example XML request

$curl -X http://localhost:54805/v1_2/Capture -d 
<?xml version="1.0" encoding="utf-8"?>
<EPCISDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" creationDate="2005-07-11T11:30:47+00:00" schemaVersion="1.2" xmlns="urn:epcglobal:epcis:xsd:1">
  <EPCISBody xmlns="">
    <EventList>
      <ObjectEvent>
        <eventTime>2013-06-08T14:58:56.591+00:00</eventTime>
        <eventTimeZoneOffset>+02:00</eventTimeZoneOffset>
        <epcList />
        <action>OBSERVE</action>
        <bizStep>urn:epcglobal:cbv:bizstep:receiving</bizStep>
        <disposition>urn:epcglobal:cbv:disp:in_progress</disposition>
        <extension>
          <quantityList>
            <quantityElement>
              <epcClass>urn:epc:class:lgtin:4012345.012345.998877</epcClass>
              <quantity>200</quantity>
              <uom>KGM</uom>
            </quantityElement>
          </quantityList>
        </extension>
        <example:myField xmlns:example="http://ns.example.com/epcis">Example of a vendor/user extension</example:myField>
      </ObjectEvent>
    </EventList>
  </EPCISBody>
</EPCISDocument>

Response: HTTP/1.1 204 No Content

Masterdata Capture

There are 2 different ways to capture CBV masterdata using FasTnT EPCIS repository. The first one is to send a MasterDataDocument to the /v1_2/Capture endpoint, like this:

$curl -X http://localhost:54805/v1_2/Capture -d
<epcismd:EPCISMasterDataDocument xmlns:epcismd="urn:epcglobal:epcis-masterdata:xsd:1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" schemaVersion="1.0" creationDate="2005-07-11T11:30:47.0Z">
  <EPCISBody> 
    <VocabularyList> 
      <Vocabulary type="urn:epcglobal:epcis:vtype:BusinessLocation"> 
        <VocabularyElementList> 
          <VocabularyElement id="urn:epc:id:sgln:0037000.00729.8201">
            <attribute id="urn:epcglobal:cbv:mda:sst">201</attribute>
          </VocabularyElement>
          <VocabularyElement id="urn:epc:id:sgln:0037000.00729.8202">
            <attribute id="urn:epcglobal:cbv:mda:sst">202</attribute>
            <attribute id="urn:epcglobal:cbv:mda:ssa">402</attribute>
          </VocabularyElement>
        </VocabularyElementList>
      </Vocabulary>
    </VocabularyList>
  </EPCISBody>
</epcismd:EPCISMasterDataDocument>

Response: HTTP/1.1 204 No Content

The second option is to include the MasterData in the header of an EPCIS Event capture. See the PostMan collections for more details and examples.

Capture Result

The capture response contains no data if it succeeds. The calling application should rely on the HTTP status code to determine if the capture operation succeeded.

A failure, however, should comply with the EPCIS standard, and thus contain one of these exception responses:

• ImplementationException
• InvalidURIException
• ValidationException

FasTnT EPCIS repository will always capture all or none of the data sent in a single request, should it be EPCIS events or CBV masterdata.

Related Informations

More example of event capture can be found in the Postman and SoapUI collection in the repository's source code.