EPCIS developer section

Co to jest EPCIS ?

EPCIS czyli Electronic Product Code Information Services jest częścią sieci EPCglobal, która dostarcza bezpiecznego środowiska do przechowywania konkretnych danych o produktach oraz ich wymiany pomiędzy partnerami. Innymi słowy jest to standard używany do śledzenia postępu obiektów, w czasie rzeczywistym, w trakcie ich przepływu w łańcuchu dostaw. EPCIS przechowuje informacje o tym kiedy dany obiekt został zarejestrowany, w jakim miejscu oraz z jakim krokiem biznesowym; dla każdego rejestrowanego obiektu.

Zdarzenia (Event)

System EPCIS operuje na definicjach zdarzeń. Każda dana w systemie jest przechowywana w formie jednego z 5 typów zdarzeń:

ObjectEvent
AggregationEvent
TransactionEvent
TransformationEvent
SensorEvent

Każde ze zdarzeń zdefiniowane jest jako plik w formacie XML o określonej strukturze, zgodnej ze standardem GS1 EPCIS 1.1. Przykłady definicji zdarzeń:

Object event

Object event jest wykorzystywany kiedy (EPC) obiektu pojawi się w danej lokacji.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE project>
<epcis:EPCISDocument
  xmlns:epcis="urn:epcglobal:epcis:xsd:1"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  creationDate="2005-07-11T11:30:47.0Z"
  schemaVersion="1.2">
  <EPCISBody>
    <EventList>
      <ObjectEvent>
        <eventTime>2005-04-03T20:33:31.116-06:00</eventTime>
        <eventTimeZoneOffset>-06:00</eventTimeZoneOffset>
        <epcList>
          <epc>urn:epc:id:sgtin:0614141.107346.2017</epc>
          <epc>urn:epc:id:sgtin:0614141.107346.2018</epc>
        </epcList>
        <action>OBSERVE</action>
        <bizStep>urn:epcglobal:cbv:bizstep:shipping</bizStep>
        <disposition>urn:epcglobal:cbv:disp:in_transit</disposition>
        <readPoint>
          <id>urn:epc:id:sgln:0614141.07346.1234</id>
        </readPoint>
        <bizTransactionList>
          <bizTransaction type="urn:epcglobal:cbv:btt:po">
            http://transaction.acme.com/po/12345678
          </bizTransaction>
        </bizTransactionList>
      </ObjectEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Aggregation event

Aggregation event wykorzystywany jest w procesie kompletacji - kiedy wiele obiektów staje się jednym.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<epcis:EPCISDocument
  xmlns:epcis="urn:epcglobal:epcis:xsd:1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  creationDate="2005-07-11T11:30:47.0Z"
  schemaVersion="1.2">
  <EPCISBody>
    <EventList>
      <AggregationEvent>
        <eventTime>2013-06-08T14:58:56.591Z</eventTime>
        <eventTimeZoneOffset>+02:00</eventTimeZoneOffset>
        <parentID>urn:epc:id:sscc:0614141.1234567890</parentID>
        <childEPCs>
          <epc>urn:epc:id:sgtin:0614141.107346.2017</epc>
          <epc>urn:epc:id:sgtin:0614141.107346.2018</epc>
        </childEPCs>
        <action>OBSERVE</action>
        <bizStep>urn:epcglobal:cbv:bizstep:receiving</bizStep>
        <disposition>urn:epcglobal:cbv:disp:in_progress</disposition>
        <readPoint>
          <id>urn:epc:id:sgln:0614141.00777.0</id>
        </readPoint>
        <bizLocation>
          <id>urn:epc:id:sgln:0614141.00888.0</id>
        </bizLocation>
        <extension>
          <childQuantityList>
            <quantityElement>
              <epcClass>urn:epc:idpat:sgtin:4012345.098765.*</epcClass>
              <quantity>10</quantity>
            </quantityElement>
            <quantityElement>
              <epcClass>urn:epc:class:lgtin:4012345.012345.998877</epcClass>
              <quantity>200.5</quantity>
              <uom>KGM</uom>
            </quantityElement>
          </childQuantityList>
        </extension>
      </AggregationEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Transaction event

Transaction event opisuje transakcje biznesowe związane z przedmiotem.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<epcis:EPCISDocument
  schemaVersion="1.2"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  creationDate="2013-06-04T14:59:02.099+02:00"
  xmlns:epcis="urn:epcglobal:epcis:xsd:1">
  <EPCISBody>
    <EventList>
      <TransactionEvent>
        <eventTime>2005-04-03T20:33:31.116-06:00</eventTime>
        <eventTimeZoneOffset>-06:00</eventTimeZoneOffset>
        <bizTransactionList>
          <bizTransaction type="urn:epcglobal:cbv:btt:po">
            http://transaction.acme.com/po/12345678
          </bizTransaction>
        </bizTransactionList>
        <parentID>urn:epc:id:sscc:0614141.1234567890</parentID>
        <epcList>
          <epc>urn:epc:id:sgtin:0614141.107346.2017</epc>
          <epc>urn:epc:id:sgtin:0614141.107346.2018</epc>
        </epcList>
        <action>ADD</action>
        <bizStep>urn:epcglobal:cbv:bizstep:shipping</bizStep>
        <disposition>urn:epcglobal:cbv:disp:in_transit</disposition>
        <readPoint>
          <id>urn:epc:id:sgln:0614141.07346.1234</id>
        </readPoint>
        <bizLocation>
          <id>urn:epc:id:sgln:0614141.00888.0</id>
        </bizLocation>
        <extension>
          <quantityList>
            <quantityElement>
              <epcClass>urn:epc:class:lgtin:4012345.011111.4444</epcClass>
              <quantity>10</quantity>
              <uom>KGM</uom>
            </quantityElement>
          </quantityList>
          <sourceList>
            <source type="urn:epcglobal:cbv:sdt:possessing_party">
              urn:epc:id:sgln:4012345.00001.0
            </source>
            <source type="urn:epcglobal:cbv:sdt:location">
              urn:epc:id:sgln:4012345.00225.0
            </source>
          </sourceList>
          <destinationList>
            <destination type="urn:epcglobal:cbv:sdt:owning_party">
              urn:epc:id:sgln:0614141.00001.0
            </destination>
            <destination type="urn:epcglobal:cbv:sdt:location">
              urn:epc:id:sgln:0614141.00777.0
            </destination>
          </destinationList>
        </extension>
      </TransactionEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Transformation event

Transformation event jest wykorzystywany w sytuacjach kiedy obiekt przekształca się (Przykład produkcyjny - surowce przekształcane są w produkt).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE project>
<epcis:EPCISDocument
  schemaVersion="1.2"
  creationDate="2013-06-04T14:59:02.099+02:00"
  xmlns:epcis="urn:epcglobal:epcis:xsd:1">
  <EPCISBody>
    <EventList>
      <extension>
        <TransformationEvent>
          <eventTime>2013-10-31T14:58:56.591Z</eventTime>
          <eventTimeZoneOffset>+02:00</eventTimeZoneOffset>
          <inputEPCList>
            <epc>urn:epc:id:sgtin:4012345.011122.25</epc>
            <epc>urn:epc:id:sgtin:4000001.065432.99886655</epc>
          </inputEPCList>
          <inputQuantityList>
            <quantityElement>
              <epcClass>urn:epc:class:lgtin:4012345.011111.4444</epcClass>
              <quantity>10</quantity>
              <uom>KGM</uom>
            </quantityElement>
            <quantityElement>
              <epcClass>urn:epc:class:lgtin:0614141.077777.987</epcClass>
              <quantity>30</quantity>
            </quantityElement>
            <quantityElement>
              <epcClass>urn:epc:idpat:sgtin:4012345.066666.*</epcClass>
              <quantity>220</quantity>
            </quantityElement>
          </inputQuantityList>
          <outputEPCList>
            <epc>urn:epc:id:sgtin:4012345.077889.25</epc>
            <epc>urn:epc:id:sgtin:4012345.077889.26</epc>
            <epc>urn:epc:id:sgtin:4012345.077889.27</epc>
            <epc>urn:epc:id:sgtin:4012345.077889.28</epc>
          </outputEPCList>
          <bizStep>urn:epcglobal:cbv:bizstep:transforming</bizStep>
          <disposition>urn:epcglobal:cbv:disp:in_progress</disposition>
          <readPoint>
            <id>urn:epc:id:sgln:4012345.00001.0</id>
          </readPoint>
        </TransformationEvent>
      </extension>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Sensor event

Sensor event wykorzystywany jest do raportowania informacji sensorycznych .


    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE project>
<epcis:EPCISDocument
  schemaVersion="1.2"
  creationDate="2013-06-04T14:59:02.099+02:00"
  xmlns:epcis="urn:epcglobal:epcis:xsd:1">
  <EPCISBody>
    <EventList>
      <SensorEvent>
        <eventTime>2017-02-24T11:58:56.591Z</eventTime>
        <eventTimeZoneOffset>+01:00</eventTimeZoneOffset>
        <readPoint>
          <id>gps_tracker</id>
        </readPoint>
        <measurmentList>
          <measurment>
            <value>25</value>
            <uom>Longtitude</uom>
          </measurment>
	 <measurment>
            <value>32</value>
            <uom>Lattitude</uom>
          </measurment>
          <measurment>
            <value>1</value>
            <uom>StatusStatus</uom>
            <eventTime>2020-10-31T10:58:56.591Z</eventTime>
            <eventTimeZoneOffset>+02:00</eventTimeZoneOffset>
          </measurment>
        </measurmentList>
      </SensorEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Zapytania (Query)

Zapytania do bazy EPCIS definiowane są jako dokumenty XML. Konstrukcja zapytania jest relatywnie prosta. Każda sekcja param definiuje kolejny parametr odfiltrowujący wyniki. Przykładowe zapytanie przedstawiono poniżej:

<?xml version="1.0" ?>
        <epcisq:EPCISQueryDocument
        xmlns:epcisq="urn:epcglobal:epcis-query:xsd:1"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        schemaVersion="1"
        creationDate="2016-07-29T09:13:06.368Z">
        <EPCISBody>
            <epcisq:Poll>
            <queryName>SimpleEventQuery</queryName>
            <params>
                <param>
                <name>WD_ReadPoint</name>
                <value xsi:type="epcisq:ArrayOfString">
                    <string>urn:epc:id:sgln:4012345.00001.0</string>
                </value>
                </param>
            </params>
            </epcisq:Poll>
        </EPCISBody>
        </epcisq:EPCISQueryDocument>

Jak zacząć ?

Serwis do akwizycji i odpytywania danych jest oparty o zasady serwisów typu REST. Do obsługi służą dwa interfejsy:

Capture: Rejestracja danych. adres bazy testowej: https://epcis.ilim.poznan.pl/api/capture
Query: Odpytywanie bazy. adres bazy testowej: https://epcis.ilim.poznan.pl/api/query

Przy zapisywaniu danych do bazy (Capture) oraz odpytywaniu (Query) należy pamiętać aby do nagłówków zapytań POST dodać następujące nagłówki:

Content-Type application/xml
token TOKEN UZYSKANY PO ZALOGOWANIU

Aby przetestować działanie polecamy wykorzystanie klienta RESTowego (przykładowo RESTLET lub POSTMAN)

Logowanie

Aby rozpocząć korzystanie z serwisu, należy się zalogować. Każde logowanie powoduje zmianę/odświeżenie TOKENU. Czas sesji ustalony jest na 20 minut. Jeśli czas bezczynności jest dłuższy niż 20 minut, należy zadbać aby zaktualizować TOKEN. Przykład logowania o paramertach: login: test hasło: test. Adres do logowania: https://epcis.ilim.poznan.pl/api/login

<epcis:EPCISAuth>
    <login>test@test.com</login>
    <password>test</password>
</epcis:EPCISAuth>

W odpowiedzi na poprawną próbę logowania, serwis odpowiada komunikatem, w którym zawarty jest TOKEN. Token należy umieszczać w nagłówkach zapytań do bazy

Odpowiedź na zapytanie

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" creationDate="2017-03-01T13:00:18.012+01:00">
    <errors>
        <0>
    </errors>
    <results>
        <0>
            <token>TOKEN</token>
        </0>
    </results>
</response>

Zapisanie danych do bazy (Capture)

Jak wcześniej nadmieniono, do zapytania typu Capture należy dodać nagłówki token oraz Content-Type

Przykład:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE project>
<epcis:EPCISDocument
  xmlns:epcis="urn:epcglobal:epcis:xsd:1"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  creationDate="2005-07-11T11:30:47.0Z"
  schemaVersion="1.2">
  <EPCISBody>
    <EventList>
      <ObjectEvent>
        <eventTime>2005-04-03T20:33:31.116-06:00</eventTime>
        <eventTimeZoneOffset>-06:00</eventTimeZoneOffset>
        <epcList>
          <epc>urn:epc:id:sgtin:0614141.107346.2017</epc>
          <epc>urn:epc:id:sgtin:0614141.107346.2018</epc>
        </epcList>
        <action>OBSERVE</action>
        <bizStep>urn:epcglobal:cbv:bizstep:shipping</bizStep>
        <disposition>urn:epcglobal:cbv:disp:in_transit</disposition>
        <readPoint>
          <id>urn:epc:id:sgln:0614141.07346.1234</id>
        </readPoint>
        <bizTransactionList>
          <bizTransaction type="urn:epcglobal:cbv:btt:po">
            http://transaction.acme.com/po/12345678
          </bizTransaction>
        </bizTransactionList>
      </ObjectEvent>
    </EventList>
  </EPCISBody>
</epcis:EPCISDocument>

Odpytanie bazy danych o dane (Query)

Podobnie jak przy wykorzystaniu interfejsu Capture, do nagłówków zapytań typu Query należy dodać nagłówki token oraz Content-Type

Przykład:

<?xml version="1.0" ?>
<epcisq:EPCISQueryDocument
  xmlns:epcisq="urn:epcglobal:epcis-query:xsd:1"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  schemaVersion="1"
  creationDate="2016-07-29T09:13:06.368Z">
  <EPCISBody>
    <epcisq:Poll>
      <queryName>SimpleEventQuery</queryName>
      <params>
        <param>
          <name>WD_ReadPoint</name>
          <value xsi:type="epcisq:ArrayOfString">
            <string>urn:epc:id:sgln:4012345.00001.0</string>
          </value>
        </param>
      </params>
    </epcisq:Poll>
  </EPCISBody>
</epcisq:EPCISQueryDocument>

Zmiana hasła/zapomniane hasło

Aby zresetować hasło w celu jego zmiany, lub ustawić nowe hasło w przypadku zapomnienia poprzedniego należy dokonać operacji resetu hasła. W tym celu należy wysłać XML z prośbą o reset hasła. Adres: https://epcis.ilim.poznan.pl/api/forgot

<epcis:EPCISAuth>
    <login>test@test.com</login>
</epcis:EPCISAuth>

Po chwili na adres email (podany przy rejestracji, który w systemie używany jest również jako login użytkownika) przyjdzie email zawierający TOKEN do resetu hasła. Należy wtedy wysłać komunikat XML ustawiający nowe hasło. Adres: https://epcis.ilim.poznan.pl/api/reset

<epcis:EPCISAuth>
    <password>nowe_haslo</password>
    <token>token_otrzymany_mailem</token>
</epcis:EPCISAuth>

Po przeprowadzeniu tej procedury możliwe jest zalogowanie się przy wykorzystaniu nowo ustawionego hasła.