-
Notifications
You must be signed in to change notification settings - Fork 75
Data Structure Guidelines
This document illustrates how to structure data for OriginTrail protocol to utilize data sharing and connectivity functionalities of the Alpha version of the OriginTrail Distributed Network (ODN). It corresponds to attachments and examples that are provided with this file and the documentation on GitHub. The defined structure was developed on the best practices observed over the last several years of experience in implementing transparency solutions within the food supply chain industry, and is based on GS1 standards.
OriginTrail is a protocol that enables exchange of standardized data among disparate IT systems in multi organizational environments in a tamper proof way. Therefore, each participant of the exchange should provide their data in a common and standardized format. To utilize the OriginTrail protocol to showcase its full potential, the communication from ERP systems of at least two entities within a supply chain towards ODN needs to be established. The communication is done periodically by sending standardized XML files to the OriginTrail network node, the structure of which will be further explained in this document.
The upload of data in the XML format to the OriginTrail protocol node is performed via the web-service endpoint. The process of extracting data from the ERP system, including its periodic forwarding to the OriginTrail node API endpoint is out of the scope of this document. This document focuses on the XML data structure that the Alpha network can import and utilize.
OriginTrail is using a GS1 based XML structure for the Alpha version, aiming for full compatibility in near future. You can view relevant GS1 EPCIS standards on following link https://www.gs1.org/sites/default/files/docs/epc/EPCIS-Standard-1.2-r-2016-09-29.pdf
The OriginTrail XML file contains three main logical parts –** master data**, transaction and visibility events data. The system is flexible, as it doesn’t require all these data sets to be in one single file.
The example XML file (here), as well as the XSD scheme (here) contains most of the explanations in comments. Data guidelines specified in the provided XML are modular, extensible and layered and will likely be updated according to requirements of each specific use case. Please see both files for more details.
The XML consists of 3 main logical parts.
The first part of the file contains the ID of the data provider, which is the ParticipantID. This value should be unique for each participant of the chain, and in the Alpha version we encourage the use of the Ethereum address associated with your Wallet.
Master data is the core data that is essential to operations in a specific business or business unit. It represents the business objects which are handled and shared across the enterprise. In our current XML structure, the Master Data entities are:
- ParticipantsList and Participant – Description of all entities (participants) in the supply chain
- BusinessLocationsList and BusinessLocation - describe all physical or system locations where business processes are executed
- ObjectsList and Object – entities that are subjects of business processes (items or goods being described)
Transaction data describes interactions between entities described with master data by the data provider. OriginTrail distinguishes two types transaction data:
-
Internal transactions are related to processes of object movements or transformations (production, repackaging etc) within the scope of one supply chain participants business location. For example, this could be production or assembly transactions that result in product output for further production or sale (repackaging, labeling etc).
-
External transactions are related to processes between different supply chain participants (sales / purchases, transport). They represent processes where the jurisdiction or ownership of the objects gets changed in the supply chain.
Each transaction should have a unique ID that represents the primary key within the ERP transaction table from the data source. The transaction data implies that the provider of that data is one of the active participants in the transaction process.
Visibility event data covers details about physical or digital activity in the supply chain of an object batch (explained by the master and transaction data above). It references information collected by either sensors or other external entities (i.e. lab test results) which provide more details about a specific object batch in a specific point in time or time span.
- Providing XML structured data to OriginTrail Decentralized Network
To start integration with OriginTrail, a periodic upload of the appropriately structured XML file (according to the XSD scheme above) should be set up. Please check https://github.com/OriginTrail/ot-node/wiki/Installation-Instructions for further details.