Home - AgroConnect-Dairy/Home GitHub Wiki

Welcome to the eDAIRY GitHub Wiki home page.

Introduction, background

The use case

eDAIRY is developed in The Nederlands as a standard interface for data exchange with dairy companies. The eDAIRY REST Json interface is to be used for digital machine-to-machine data exchange with dairy companies (cow milk as well as goat milk), for instance between:

  • the farmer’s management information system (FMIS) and the dairy company
  • the farmer's accountant and the dairy company
  • the farmer’s feed supplier and the dairy company
  • the farmer’s breeding organisation and the dairy company

eDAIRY message types

To be able to provide the DAIRY data, depending on the role and the permissions of the requesting party, three different message types are specified:

  • eDAIRY Delivery message
  • eDAIRY Quality message
  • eDAIRY Invoice message

The Delivery message is to retrieve data about each milk delivery by each farmer; it is mainly about the delivery date-time and the quantity of delivered milk. The Quality message is to retrieve data about the quality of the delivered milk; it concerns for instance the amount of protein, fat, lactose, etc. The Invoice message reports the details about the payments of each milk delivery.

All three messages are based on the same overall data model (the same UML class model).

Transition, from EDI-Zuivel to eDAIRY

The eDAIRY message set is developed to replace, in time, the existing Dutch EDI-Zuivel standard messages. Besides the standard eDAIRY REST Json messages, eDAIRY also covers the agreements about the architecture / infrastructure and protocol to be used for sharing the data. For this, functional and technical requirements were drafted (only available in Dutch language):

eDAIRY design

eDAIRY class model

The eDAIRY class model is developed using Enterprise Architect as a modelling and publishing tool. The Enterprise Architect source file is to be downloaded as an EA-file. The definitions of the classes and of all data elements are published as an html version of the Enterprise Architect model. In de class model, a data element definition might refer to a specific code list (enumeration). The eDAIRY code lists are published in a separate zip-file.

Documentation:

eDAIRY architecture

It is agreed is that different dairy companies support exactly the same REST Json calls to publish and gather their data, but they are free in how their web-services should be approached; via an intermediate platform or peer-to-peer. For the Dutch situation several dairy companies use the cloud routing service JoinData to allow third party applications to retrieve data, other dairy companies might allow a direct connection to their web services.

The messages need to be pulled by the data consumer from the data sources, in this case from the REST Json services of the dairy company.

Standard messages

Json standard messages

Based on the class model, three standard Json messages are implemented. See the Json schemas and examples of the Json standard messages:

  • Json example eDAIRY Delivery
  • Json example eDAIRY Quality
  • Json example eDAIRY Invoice

In case of using JoinData as a data-hub to exchange dairy-data, relevant links are:

For error messaging and other types of responses to requests, the global standard response to a REST call is leading: Each call results in either:

  • a response with the requested payload (a body with content);
  • a standard status message, indicating the status of the processing of the request (successful of not successful).

For the specifications of the standards REST status codes see: https://restfulapi.net/http-status-codes/ .

UBL standard invoice

The digital self billing invoice from the dairy company to the farmer or to his accountant, can be retrieved in two different syntaxes:

  • as the Json eDAIRY Invoice
  • as a UBL-xml eDAIRY Invoice

UBL stands for Universal Business Language (an OASIS standard message). The UBL standard messages (Order, DespatchAdvice, Invoice) are globally used at a large scale for digital data exchange in supply chains.

Documentation UBL-xml eDAIRY Invoice:

Differences Qlip versus RFC

In the current version (v1_0) of the eDAIRY APIs there are small differences in requesting data from Qlip versus RFC. These are to be taken into account when implementing the eDAIRY API's. These differences are specified in this document. It is the intention, for the long run, to minimize these differences.

Onboarding, step by step

Use case “data consumer solution provider”

As a data consumer, I would like to make use of the new REST Json API to get data about the milk deliveries of my clients and to exchange other type of data with my client’s dairy company.

The dairy data are provided by either:

  1. Royal Friesland Campina (RFC)
  2. Qlip (Partico members and other dairy companies)

JoinData

Both RFC and Qlip make use of JoinData to provide access to the data.

  • As a data consumer solution provider, make sure you are connected to JoinData. If not so, contact JoinData to get connected.
  • As a data consumer solution provider, make sure that your clients are connected to JoinData. If they are not, inform them to contact JoinData to get connected.
  • As a data consumer solution provider, use JoinData to get the clients permissions to exchange the clients data between the application of the solution provider and the dairy company.
  • If there are existing EDI-Zuivel permissions that need to be transferred to JoinData eDAIRY permissions, then there is the option to import the existing permissions batch-wise into the JoinData register. Please contact JoinData about the exact procedure to do so.
  • Be aware of the fact that the eDAIRY web-services provide a set separate API’s to GET or POST data (Delivery, Quality, Invoice, FocusPlanet, etc.). The client needs to give the data consumer solution provider separate permissions for each of these API’s.
  • As a data consumer solution provider, implement the standard eDAIRY REST Json interface:
  • Study the documentation and specifications as mentioned on this web-page. If there are any questions, contact the AgroConnect-support service.
  • As a solution provider, develop the API connection.
  • As a solution provider contact JoinData to get instructions about the Development, Testing, Acceptance and Production (DTAP) process; schedule these phases.

The persons involved in developing and maintaining the standard and in supporting the implementation are.

  • Royal FrieslandCampina, Esther Beuker: As chair of the eDAIRY-working group and maintenance committee. [email protected]
  • Royal FrieslandCampina, Bob de Ruiter: For support in connection to the RFC eDAIRY data service. [email protected]
  • Qlip, Floris Ruiterkamp:For support in connection to Qlip’s eDAIRY data service. Qlip provides the data for the Partico dairy companies and for Elda. [email protected]
  • CRV, Erwin Speybroeck: As REST Json expert in data exchange with breedingorganization CRV and for implementing the ICAR standard. [email protected]
  • JoinData, Huub van Workum: For explaining how to implement JoinData for managing permissions and getting access to the APIs of the data providers. [email protected]
  • AgroConnect, Conny Graumans: For explaining the eDAIRY class model, and the Json standard eDAIRY messages. [email protected]

Issue and change management

Change requests regarding the content of the standard messages can be addressed to the secretary of the AgroConnect work group Dairy at [email protected].

Issues regarding connecting to the application / platform that provides the dairy data should be addressed to respectively JoinData, Qlip, Elda. JoinData, for instance, uses a special issue ticketing system to keep track of all the pending issues.