View source for Section 15 – Data Exchange

= Data Exchange =
<div class="mw-collapsible mw-collapsed">
    <div>
== Introduction ==
Animal Recording involves the collection, storage and exchange of data. Over time the use of electronic systems has spread from initially, in the early 1970s, being used just for centralised data processing to now (in 2016) being used in all aspects of animal recording.  The electronic systems for collecting, storing, transmitting, and processing data and information have evolved to be used widely by technicians, farmers, advisors and central systems.  The evolution is continuing at a rapid pace worldwide.  With this spread of electronic systems the need for standards to facilitate the ready transfer of data between systems has also grown very rapidly.

This part of the ICAR guidelines (chapter 15) is devoted to standards for facilitating data transfers and to processes for ensuring electronic systems comply with the ICAR guidelines.

== Goals ==
The goals of these guidelines are:

# To provide the developers of data processing systems with standards and processes that they can use to ensure the devices and systems they develop can be readily and reliably linked with the full range of animal data information systems used by ICAR members.
# Harmonization of the definitions of exchanged data in order to be able to exchange information between heterogeneous information systems.
# Development of global consensual data dictionaries for livestock.
# Development and installation of standardized systems to support data exchange between information systems and farm equipment.

== Scope ==
Animal data exchange consists of:

# Business requirements and technical specifications.
# Data descriptions provided by files in compliance with the recommendations from W3C for XML schemas, UNCEFACT and ISO.
# Interface specifications provided by files in compliance with the recommendations from W3C for web service description languages (WSD).

This Guideline gives business requirements which are divided into three types:

# General business requirements which address any type of data exchange.
# Specific business requirements which address a given type of data exchange (Procedure two to five).
# Data descriptions (Appendix A).

For a given type of data exchange, specific business requirements detail the:

# purpose of data exchange;
# business context of data exchange; and
# requirements to exchange data which includes exchanged message descriptions.

Data description encompasses:

# Service description
# Message composition
# Entity description
# Data item description
# Code set description

Technical implementation deals with the implementation of the same business requirements according different ways:

# Primarily by using W3C and UNCEFACT recommendations for data and interface definition (SOAP).
# Alternatively, by using the existing ISO standards (17532:2007) for data exchange on farm with stationery equipment and REST technology (This has to be elaborated more in detail in a future version of the ICAR ADE specification).

== Presentation of animal data exchange ==

=== Background ===
At the moment, data exchanges between equipment and external information systems do not exist or require a sort of middleware (see Figure 1) between the equipment and the information system. It is based mainly on regional, manufacturer specific or outdated international standards (ISO ADED 1996 - ISO 11788-1, ISO 11788-2 , ISO 11788-3 see here for details).
[[File:Imagebackground1.png|center|thumb|499x499px|''Figure 1. Current situation for data exchange.'']]


This middleware is costly to implement, difficult to maintain. It requires manual operations and does not allow to reduce the delay between an event and its registration by an external information system and to exchange large amount of data. 

Equipped with modern high-speed IT infrastructure todays animal recording data centres are capable of processing huge amount of data created by an exponentially growing number of on farm equipment, sensors and analytical methods. In order to get reliable access to this data a high level of automation and standardization of data exchange has to be organized. 

A data exchange in real time of a large amount of data would allow:

# animal breeding on new traits;
# improved animal monitoring by the aggregation of data from different sources: equipment, analysis laboratories etc; and  
# improved farm equipment calibration in order to get more accurate measurements.

=== Objective of animal data Exchange ===
The objective is to establish direct, permanent, reliable, easy to implement and to maintain, and cost-effective exchanges of large amounts of data both ways: between equipment and external information systems and from equipment to external information systems.

=== How to achieve the objectives ===

==== Content of ADE ====
This objective may be achieved by a framework consisting of:

# an architecture to support data exchange;
# standards for messages and data;
# tools to facilitate its implementation; and
# a reactive maintenance process.

The architecture is based on a service-oriented approach where the equipment is the client of the external information system which is a service provider (see Figure 2). This architecture may be implemented by using different information technologies which are specified by this document.
[[File:Imagebackground2.png|center|thumb|517x517px|''Figure 2. Animal data exchange architecture.'']]
:The standards encompass:

# Business requirements to use the service
# Business requirements to deliver the service
# Business requirements for exchanged data
# Semantic definition of exchange data as well as their code set
# Syntax specifications for the exchanged data according W3C, UNCEFACT and ISO
# Interface specifications according W3C, UNCEFACT and ISO

The tools to facilitate the implementation encompass:

# A web site to download:
#* Files of xml data types (XSD files)
#* Files of web service specifications (WSDL files)
# A test platform

==== ADE implementation ====
Figure 3 below describes the process.
[[File:Imagebackground3.png|center|thumb|''Figure 3. Life cycle of the framework.'']]



The process is triggered by a business need.

Business requirements should be the result of collaboration between ICAR and manufacturers. They are independent from the techniques used to implement them.

Two types of implementations are considered:

# W3C and UNCEFACT standards, the primary one; and
# ISO (17532:2007) / REST, the upcoming alternatives.

The W3C implementation consists of:

# Data element technical description as “xsd” files based on UNCEFACT data types.
# Interface technical specifications as “wsdl” files.
# From WSDL:
#* Client implementation by the manufacturer
#* Server implementation by the external information system

=== Business context ===
Figure 4 describes the business context.
[[File:Imagebackground4.png|center|thumb|509x509px|''Figure 4. Background business context.'']]
Service providers are organizations who provide milking equipment owners with services whose purpose is:

# to have their data registered by a multipurpose data base, and
# to deliver aggregated information.

These organizations may be milk recording organizations, breeding organizations or other data base service providers.

The owner of the milking equipment and the service provider should agree on the conditions to use services and namely the parameters which are required for data exchange. Generally, this agreement is formalized by a contract.

Milking equipment is a set of hardware and software encompassing at least the following functions:

# Measuring milk quantity and characteristics.
# Filling bottles of milk sample and registering the links between the bottle identifier and that of the animals.
# Storing milking results.
# Connecting, sending and receiving data from external information systems.

Milking equipment may have several other functions which are not considered by that data exchange: animal monitoring, milking monitoring. However, characteristics not directly linked to milking but recorded during the milking process, e.g. weighing in the milking box, could be transported.  

A milking system may correspond to different types of equipment: robot, electronic milking meters etc.

The milking equipment is operated under the supervision of a milking operator who is staff dependent from the owner and designated as ‘Operator’ throughout the rest of the document. A milking operator has the right and the capacity:

# to feed the milking equipment with parameters for data exchange and milk samples;
# to install and to remove the bottles used for milk sample; and
# to send milk samples to a milk analysis laboratory.

A milking equipment operator may correspond to different actors: farmer, a staff dependent from a farmer, a technician from a service provider such as a milk recording organizations etc.

The service provider operates an information system which provides the services. That information system consists of server, data bases and software, which are not a part the milking equipment and which is connected to the milking equipment by a network. It has at least the following functions:

# Receiving and processing requests from the milking system.
# Updating the data base of the information system according the requests of the milking system.
# Providing the results of milk analytic laboratories which analyze the samples collected by the requesting milking equipment.

== General Specifications ==
The general specifications are contained in Procedure 1 of these Section 15 ICAR Guidelines – link [https://wiki.icar.org/index.php/Section_15_%E2%80%93_Data_Exchange#Procedure_1:_Methodology here.]

== Specific Services ==

=== Milking ===
Specifications for milking services are contained in Procedure 2 of these Section 15 ICAR Guidelines – link [https://wiki.icar.org/index.php/Section_15_%E2%80%93_Data_Exchange#Procedure_2:_Milking_Data_Services here].

=== Exchange of Animal Data ===
Specifications for exchange of animal data services are contained in Procedure 3 of these Section 15 ICAR Guidelines – link [https://wiki.icar.org/index.php/Section_15_%E2%80%93_Data_Exchange#Procedure_3:_Animal_Data here].

=== Exchange of Reproduction Events ===
Specifications for exchange of animal data services are contained in Procedure 4 of these Section 15 ICAR Guidelines – link [https://wiki.icar.org/index.php/Section_15_%E2%80%93_Data_Exchange#Procedure_4:_Reproduction_Data_Services here'''.''']

=== Technical Services ===
Specifications for exchange of technical services are contained in Procedure 5 of these Section 15 ICAR Guidelines – link [https://wiki.icar.org/index.php/Section_15_%E2%80%93_Data_Exchange#Procedure_5:_Technical_Data_Services here].

== Data Dictionary ==
The data dictionary is contained in Appendix A to these Section 15 ICAR Guidelines – link [https://wiki.icar.org/index.php/Section_15_%E2%80%93_Data_Exchange#Appendix_A:_Data_Dictionary here].

== References ==
1.      Semantics for Smart Dairy Farming: a milk production registration standard – SDF June 2013

2.     UN / UNCEFACT Modeling Methodology User Guide (CEFACT / TMG/N093)

3.     UN / UNCEFACT Business Requirements Specifications Document Template (CEFECT/ICG/005)

4.     ISO 11787: Electronic data interchange between information systems in agriculture —Agricultural data interchange syntax

5.     ISO 11788: Electronic data interchange between information systems in agriculture — Agricultural data element dictionary —Part 1: General description —Part 2: Dairy farming

6.     ISO 17532: Stationary equipment for agriculture —Data communications network for livestock farming 

7.      ISO 11784: Radio frequency identification of animals - code structure

8.     ISO 3166 -1: Country code

9.     ICAR Guidelines 
</div>
</div>

= Procedure 1: Methodology =
<div class="mw-collapsible mw-collapsed">
    <div>
== Introduction ==
For electronic data exchange a lot of technologies exist and new technologies are continously evolving. However, in order to establish standardized data exchange we have to concentrate on a defined set of accepted and mature technologies and describe the usage in detail.  

This procedure, as part of Section 15 Guidelines, introduces  the common methodology and technology used by the specific business processes described in procedures 2, 3 and 4: 

# '''General Data Transport Specifications:''' describes the applied web service transport protocols and data protocols
# '''Access to the Service:''' describes some aspects to be taken into account when implementing and installing the services
# '''Communication work flow:''' covers the communication work flow aspects in a business process session like request, response and data processing. 
# '''Dealing with Local Requirements:''' describes in detail how locally obligatory data elements which are not covered by the ICAR scope can be added to the interfaces
# '''Common Components:''' describes all the common protocol components which are reused in the specific business processes

== Definitions and Terminology ==
Table 1 contains a list of important definitions for terms and abbreviations used in these guidlelines.
<center>
{| class="wikitable" style="text-align:center;"
| colspan="2" align = "left"|'''''Table 1.  Definitions of Terms used in these guidelines.'''''
|- style="background-color:#efefef;
|'''Term'''
|'''Definition'''
|-
|TCP/IP
|Transmission Control Protocol
|-
|HTTP
|Hyper Text Transfer Protocol
|-
|XML
|Extensible Markup Language
|-
|XSD
|XML Schema Definition
|-
|SOAP
|Simple Object Access Protocol
|-
|WSDL
|Web Service Description Language
|-
|REST
|Representational State Transfer
|-
|ADIS
|Agricultural Data Interchange  Syntax
|-
|ADED
|Agricultural Data Element Dictionary
|-
|JSON
|JavaScript Object Notation
|-
|UNCEFACT
|UN/CEFACT is the United Nations  Centre for Trade Facilitation and Electronic Business
|-
|ISO
|International Organization for  Standardization
|-
|IANA
|Internet Assigned Numbers  Authority
|}
</center>

== Scope ==
gives a pictorial summary of the main elements of this procedure. The numbers in this figure refer to the heading numbers of this procedure.
[[File:Imagescope1.png|center|thumb|422x422px|''Figure 1. Scope of procedure 1 of Section 15 of ICAR Guidelines.'']]

== General Data Transport Specifications ==

=== SOAP/XML Web Services ===
For the primary data transmission method the W3C standard SOAP/XML version 1.2 has been chosen. Detailed descriptions of this standard can be found here:

http://www.w3.org/TR/2007/REC-soap12-part0-20070427/

Since a “top down” approach has been adapted, ICAR ADE provides WSDL files and a set of XSD files which make up a complete set of machine readable definition files from which SOAP web service implementations can be created. Most modern programming languages e.g. Java, .NET etc. provide tools which facilitate an easy setup process of interfaces classes to be used as a link between data transport layer and business process layer.

For each release of the ICAR ADE specifications a specific set of WSDL/XSD files can be downloaded from the ICAR ADE website – '''[https://icar-web.atlassian.net/wiki/spaces/ADE/overview link here]'''. See Table 2. ICAR ADE schema files” for a description of the files. The files will be provided in a zip archive file e.g. “ADE_Schema20150309_1.8.zip” for version 1.8 available '''[https://icar-web.atlassian.net/wiki/spaces/ADE/pages/1835044/WSDL-files+1.8 here]'''.

The WSDL/XSD files describe different aspects of the transport protocol:

# Service end points
# Input and output messages
# Basic data type definitions (XSD types, UNCEFACT types etc.)
# Complex data type definitions : (entity tags, item tags, compositions, attributes, usage of basic data types)
# Constraints (data type and value range restrictions)

{| class="wikitable"
| colspan="2" |'''''Table 2. ICAR ADE schema files'''''
|-
|'''File  Name /''' 

'''File  Name Schema'''
|'''File Description'''
|-
|*.XSD
|XML Schema Definition files, machine readable  description of the ICAR ADE XML data structures
|-
|ICAR_*.XSD
|Data element definitions created by the ICAR ADE  group
|-
|ISO_*.XSD
|Data element definitions derived from ISO standards
|-
|UNECE_*.XSD
|XSD files provided by the UN/CEFACT project:

(see <nowiki>http://www.unece.org/cefact/xml_schemas/index.html</nowiki>)
|-
|UnqualifiedDataType_13p0.XSD
|XSD file which defines the unqualified UNCEFACT data  types. These data types extend the standard XSD data types with additional  attributes. In the ICAR and UNCEFACT definitions they are used instead of the  standard XSD types.
|-
|*_CODE_*
|XSD files defining code lists
|-
|wsMrAde.wsdl
|ICAR ADE SOAP service description, (WSDL = Web Service  Description Language)

It defines a set of message pairs each consisting in  a request and a response message.
|-
|ADE_v1p8.xsd
|This file provides the entry point to the ICAR ADE  message data structure definitions
|}


Throughout this document messages and data definitions are illustrated using graphical presentations of XSD structures created by the commercial software XMLSPY from ALTOVA.

See for example Figure 2 Example “GetHerdListRequest”
[[File:Mw.png|center|thumb|374x374px|''Figure 2 Example “GetHerdListRequest”'']]


Below the symbols used to represent the XSD schemas in the following pages:

Table 3 XSD schema symbols
[[File:Mw1.png|none|thumb|457x457px]]

=== Alternative Transport Protocols (ADIS/ADED/IsoAgriNet, REST) ===
Parallel to SOAP other international transport protocols exist. This is for example the ISO ADIS/ADED standard and its last extensions described in ISO 17532(2007).  On the other hand the REST protocol, based on the HTTP transport protocol using XML, JSON and other data encoding technology, has gained a broader acceptance in the domain of internet data transfer during the recent years.

The ADE-WG is working on the development of  a standardized  REST-API description.

=== ICAR Types and Code Lists ===
Elements created within the process of the ICAR ADE specification can be identified by the prefix “'''icar:'''” within the WSDL/XSD files and descriptions below.

All data items are based on UNCEFACT data types (see section UNCEFACT Data Types)

A detailed description of the data elements is given below.

=== External Elements ===
It is the aim of the ICAR ADE standardization process to make as far as possible use of elements already defined within existing standardization frameworks as ISO, IANA and UNCEFACT.

==== UNCEFACT Data types ====
The ICAR ADE WSDL/XSD definitions make extended use of UNCEFACT basic types.

UNCEFACT basic types are types derived from basic XSD types. The concept consists mainly of adding further attributes and restrictions to the XSD types. They are defined in file UnqualifiedDataType_13p0.xsd.

In the WSDL/XSD files and descriptions below those elements can be identified by the prefix “'''udt:'''”

Table 4 UNCEFACT basic data types” lists the UNCEFACT types currently used for the types of a data item.
{| class="wikitable"
| colspan="4" |'''''Table 4 UNCEFACT basic data types'''''
|-
|Name
|Description
|Comment
|XSD  Type
|-
|udt:CodeType

|A character  string that may be used to represent or replace the definitive value.
|A code is  referring to an enumeration
|String
|-
|udt:DateType
|A particular  point in the progression of date
|Representation  as defined by transport protocol 
|String
|-
|udt:DateTimeType
|A particular  point in the progression of time
|Representation  as defined by transport protocol
|String
|-
|udt:IDType
|A character  string used uniquely to establish the identity of, and distinguish, one  instance of an object within an identification scheme from all other objects  within the same scheme.
|
|String
|-
|udt:MeasureType
|A numeric  value determined by measuring an object
|Measures are  specified with a unit attribute holding a measure unit, a resolution and when  it is required a minimum and a maximum value.
|Decimal
|-
|udt:NameType
|A word that  constitutes the distinctive designation of a person, place, thing, or concept
|
|String
|-
|udt:BinaryObjectType
|Base64 coded  binary data
|Used e.g. for  zip compressed message
|String
|-
|udt:TextType
|A general  text type
|
|String
|-
|udt:IndicatorType
|A Boolean  indicator or true and false
|
|Boolean
|}

==== UNCEFACT Code Lists ====
UNCEFACT provides an extensive set of code lists. See Table 5 UNCEFACT Code Lists” for the code lists used by the ICAR ADE specifications.
{| class="wikitable"
| colspan="2" |'''''Table 5 UNCEFACT Code Lists'''''
|-
|'''Code  List'''
|'''Description'''
|-
|AgencyIdentificationCode
|A list of agencies responsible for code list  maintenance to be used as value of the attribute '''listAgencyID''' in the UNCEFACT data type '''udt:CodeType'''
|-
|CharacterSetEncodingCode
|A list of character set encoding codes to be used as  value of the attribute '''encodingCode'''  in the UNCEFACT data type '''xsd:base64Binary'''
|-
|MeasurementUnitCommonCode
|An extensive set of commonly used units to be used  as value of the attribute '''unitCode'''  in the UNCEFACT data type '''udt:MeasureType'''
|}

==== ISO Code Lists ====
See Table 6 ISO code lists for the ISO code lists used by the ICAR ADE specifications.
{| class="wikitable"
| colspan="2" |'''''Table 6 ISO code lists'''''
|-
|'''Code  List'''
|'''Description'''
|-
|ISO3AlphaCurrencyCode
|A list of ISO currency codes to be used as value of  the attribute '''currencyID''' in the  UNCEFACT data type '''udt:AmountType'''
|-
|ISOTwoletterCountryCode
|A list of two letter ISO country codes to be used as  value of the item '''Country'''
|}

==== IANA Code Lists ====
See Table 7 IANA Code Lists for the IANA code lists used by the ICAR ADE specifications.
{| class="wikitable"
| colspan="2" |'''''Table 7 IANA Code Lists'''''
|-
|'''Code  List'''
|'''Description'''
|-
|CharacterSetCode
|A list of IANA character set codes to be used as  value of the attribute '''characterSetCode'''  in the UNCEFACT data type '''xsd:base64Binary'''
|-
|MIMEMediaType
|A list of IANA MIME media type codes to be used as  value of the attribute '''mimeCode''' in  the UNCEFACT data type '''xsd:base64Binary'''
|}

== Access to the Service ==

=== Exchange Parameters ===
The equipment should provide the operator with an interface to capture exchange parameters for a given service provider consisting of:

# Service provider URL
# Authentication information (user/password, token)
# Sender ID
# Sender name
# Sender country
# Recipient ID
# Recipient name
# Recipient country
# Type of location
# Type of identifier of the location
# Identifier of the location
# Name of the location
# Country of the location
# Type of primary animal identifier
# Type of secondary animal identifiers (e.g. on farm animal id, animal name)
# Other manufacturer or service provider specific parameters

For a given service provider the exchange parameters should be the same for all the consumed services.

=== Data Transmission ===
As the services are not permanently accessible, no request should be sent by the equipment before having checked if there is access to:

# The network
# The service provider server
# The service itself


Any new data should be registered by the information system as soon as possible.

No new data should be sent to the information system as long as previous data is still being processed. The service consumer has to wait for a processing result or a ticket in case of asynchronous processing.

No ticket should be sent to the information system before the time given by the information system.

Any message whose syntax is not in compliance with the syntax requirements should not be sent.

As soon as a data is included in a request an answered by a response it should be considered as sent to the information system.

Service providers and consumers should be prepared for updates and deletes. The service provider should take also take into account that the sending party is declaring updates as a create operation not knowing that the data is already present in the service provider’s data base. (e.g. in case of retransmission initiated by the consumer)

Preparing a request in compliance with business requirements should be performed separately from preparing a message whose syntax depends on the type of technical mapping (web service with SOAP at the moment).

=== Encryption ===
If possible encryption should be used in order to insure privacy and authenticity. The process of encryption itself is not described here. The encryption capabilities of the applied transport protocol should be used e.g. HTTPS for HTTP-Transport.

=== Compression ===
In order to minimize the transport delay of big messages, especially when coded in xml, compression should be applied. Some transport protocols offer compression features like transparent gzip compression of http responses. However since http compression is only applicable to the response it is not usable for the compression of data loads in http requests.

In order to avoid this limitation a special XML based compression mechanism is described for ICAR data exchange. Specific messages can be defined as zip compressible offering the alternative of uncompressed or zip compressed Base64 binary encoded xml structures both for request and response. For details see chapter “Message Design” below.

=== User Right Verification ===
The right of a given user to use a given service is verified by either using an “'''authentication token'''” which prevents him from sending a user ID and a password at each request or by a '''user name authenticated by a password'''.

'''''Authentication by'' user name and password ''should only be used with encrypted transport'''''.

== Communication work flow ==

=== Data Processing ===
Any service may be provided either in real time or in time differed.

A response should be sent to any response within several seconds.

Any request and any response should be stored by the equipment and the information system.

The requirements to update the data base of the information system differ from one service provider to another one.

Any request which is not in compliance with one the following conditions should not be processed:

# Compliance with the syntax
# Validity of the identification token
# Validity of the ticket if any

=== Request Specification ===
Any request should consist of three parts:

# A single '''message header'''  (see the entity MessageHeader of Type “ADEExchangedDocumentType”  in  ‘Data description’) The sender of the request creates and provides his own unique MessageID  (Item ADEExchangedDocumentType.Identifier). See chapter “Best Praxis for MessageID Creation” below.
# A single '''standard request''' (see the entity StandardRequest in ‘Data description’)
# A '''specific request''' which may consist of  a specific message for a given service  or the zip compressed base64 binary of the specific message or a ticket. A ticket is sent in order to retrieve the results of an asynchronous message processing task. (see diagrams below)

[[File:Mw2.png|center|thumb|''Figure 3 Request with a specific request'']]


=== Response Specification ===
Any messsage response should consist of three parts:

# A single message header (see the entity MessageHeader of Type  “ADEExchangedDocumentType” in ‘Data description’) The sender of the response creates and provides his own unique Message id. (See chapter “Best Praxis for MessageID Creation” below)
# A single standard response (see the entity StandardResponse in ‘Data description’. In the standard response the original MessageID from the sender is returned in the item RequestID. The standard response contains the item RequestProcessingStatus which identifies the status of the request processing on the side of the service provider:

{| class="wikitable"
| colspan="2" |'''''Table 8 RequestProcessingStatusCodeType (base xsd:string)'''''
|-
|'''Key'''
|'''Description'''
|-
|O
|Processed without errors
|-
|P
|Data accepted for  asynchronous processing (client can retrieve the processing result later  using provided ticket)
|-
|E
|Processed and  rejected due to errors
|-
|W
|Processed with warnings
|}
c. A specific response which may consist of either a ticket or specific message for a given service or the zip compressed base64 binary of the specific message.

The existence and content of the specific response depends on the definition of the service and the content of the RequestProcessingStatus item. 

In case of RequestProcessingStatus = ‘P’ the specific response holds a Ticket

If a specific response message is defined it can either be represented uncompressed or zip compressed of type Base64binary.

If RequestProcessingStatus = ‘P’, ‘E’ or ‘W’ there might be no specific response at all depending on the message definition.
[[File:Mw3.png|center|thumb|''Figure 4 Response with a Specific Response'']]
[[File:Mw4.png|center|thumb|498x498px|''Figure 5 Specific Response Schema'']]
[[File:Mw5.png|center|thumb|''Figure 6 Standard Response'']]


=== Best Praxis for Message-Id Creation ===
The message ID created by both service consumer and service provider should be globally unique in order to allow a simple identification of each message e.g. for tracing and debugging purposes.

The MessageID should be based on a chain of unique hardware identifier, a unique software identifier and an additional distinguishing component large enough to uniquely identify messages created at very fast rates. This dynamic component could be a timestamp with ms precision or a sequence. The unique hardware identifier could be the globally unique MAC address of the network interface. The unique software identifier should be unique on the system running the software.

There are tools in different programming languages which provide simple means of unique id creation e.g. Guid.NewGuid() in C#

== Dealing with Local Requirements ==
The ICAR ADE standardization process cannot take into account all local requirements. In the first place it offers a common basis to build on. 

In the first place “local” is a placeholder for national standards. However it is also possible to add local extensions based on an agreement between a service consumer and a service provider (e.g. for special projects, prototypes etc.).

In order to allow local extensions and to fill standardization gaps which cannot be covered by ICAR the ADE specifications provide two ways of local variations and extensions:

# '''Local Code Lists''': Local code lists for all items of type '''udt:CodeType''' for which ICAR is not yet able to provide a commonly accepted code set
# '''Local Additional Data''': An optional list of key value pairs in each specific entity to be used for locally required data elements

Local variation should be reduced to a minimum since it is contradictory to the goal of ICAR to establish global standards, leads to increased complexity, complicates software development and creates additional costs.

=== 2.1        Local Code Lists ===
Local code lists must be provided for items of type '''udt:CodeType''' in the context of a local standardization process, e.g. breed codes.

The content cannot be checked with the SOAP/XML validation procedure but must be evaluated in an extra program step before filling the XML data structures and after extracting the data from the XML structures. It is the responsibility of the software developers to assure that the data exchange is in accordance to ICAR and to local specifications.

In order to help manufacturers with the maintenance and integration of local code lists these specifications define the service '''GetLocalCodeList''' which can be used to query local code lists from the local service providers. For details see section “Technical Services”.

=== Local Additional Data ===
Sometimes it is necessary for local implementations of the ICAR messages to add local data items to the specific messages which are not known or not covered by the ICAR specification process. 

For those scenarios a simple and flexible extension ('''LocalAdditionalData''') has been added to each specific entity.

It consists of an optional list of code/value pairs of type udt:textType which can be filled according to local definitions.

It is the responsibility of the local business process owners to document and assure the proper handling of this code/value pairs. The ICAR wsdl/xsd definitions only check the proper usage of the XML structure not the content.

For details see the wsdl/xsd files and the section 

“CommonComponents”-”LocalAdditionalDataType”.

== Common Components ==
This part describes common components which are used in all the specific services described in anex B, C and D.

=== ADE Exchanged Document Type ===
The entity '''ADEExchangedDocumentType''' (Figure 7 ADEExchangedDocumentType) gives information describing general aspects of the message.

Used by data element: '''MessageHeader'''
[[File:Mw6.png|center|thumb|540x540px|''Figure 7 ADEExchangedDocumentType'']]

# '''Identifier''': Unique identifier of the message given by the sender
# '''Issueing''': The date and the time where the message is issued.
# '''Version''': Version number of the message
# '''Language''': Language used for the message
# '''LocalAdditionalData''': Optional list of key/value pairs used in a local context as described in section “Common Components – Local Adaptions”
# '''SenderParty''': Organization or person responsible for the content of the message, not a server identifier.
# '''RecipientParty''': Organization or person responsible for processing the message, not a server identifier.

=== ADE Party Type ===
The entity '''ADEPartyType''' (Figure 8 ADEPartyType) gives the name and the identifier of a party which may be either the sender or the recipient of a message.

Used by data elements: '''SenderParty''', '''RecipientParty'''
[[File:Mw7.png|center|thumb|493x493px|''Figure 8 ADEPartyType'']]

* '''Name''': Identifier of the specified party
* '''ID''': Identifier of the specified party
* '''Country''': Country of the specified party in accordance to code list '''ISOTwoletterCountryCodeIdentifierContent'''

=== Standard Request Type ===
The entity '''StandardRequestType''' (Figure 9 StandardRequestType) gives the standard content of a request.

Two different types of authentication can be used, token or user/password based.

Used by data element: '''StandardRequest'''
[[File:Mw8.png|center|thumb|534x534px|''Figure 9 StandardRequestType'']]

# '''AuthenticationToken:''' temporal code used for verification of the user’s identity and of its right to use a service.
# '''AuthentificationLogin''': Pair of username and password used for login
# '''UserName''': User name used for authentication
# '''Password''': Password used for authentication

=== Standard Response Type ===
The entity '''StandardResponseType ('''Figure 10 StandardResponseType''')''' gives the standard content of a response.

Used by data element: '''StandardResponse'''
[[File:Mw9.png|center|thumb|531x531px|''Figure 10 StandardResponseType'']]

# '''RequestProcessingStatus''': Status of request processing returned by server according to code list '''RequestProcessingStatusCode'''
# '''RequestID''': Copy of the message identification in the '''request’s MessageHeader.Identifier''' item
# '''RequestProcessingError''': In case an error happens during the processing of the request an error description is provided here

=== Error Type ===
The entity '''ErrorType''' (Figure 11 ErrorType) gives the request processing errors.

Used by data element: '''RequestProcessingError'''
[[File:Mw10.png|center|thumb|400x400px|''Figure 11 ErrorType'']]

# '''ErrorID''': Identifier the error, e.g. error text message, local error code etc.
# '''ErrorSeverity''': Severity of the error according to code list '''ErrorSeverityCode'''
# '''ErrorDescription''': Human readable description of the error as text

=== Ticket Response Type ===
The entity '''TicketResponseType''' (Figure 12TicketResponseType) conveys a ticket in order to retrieve a response processed in time differed (asynchronous processing mode).

It is used in '''SpecificRequest''' and '''SpecificResponse''' by data element '''TicketResponse'''.
[[File:Mw11.png|center|thumb|443x443px|''Figure 12TicketResponseType'']]

# '''TicketID''': Identify the response to retrieve
# '''NotBefore''': Date time of probable response availability

=== ZIP Message Type ===
'''ZipMessageType''' (Figure 13 ZipMessageType) is a wrapper type designed to transport the zip compressed version of the specific data part of a message. Contrary to http compression method which can only be used for the response part this method can be applied to request and response. It is defined as a choice for each specific request or response which transports data entities.
[[File:Mw12.png|center|thumb|405x405px|''Figure 13 ZipMessageType'']]

# '''ZIPMessage''': zip compressed data

=== Local Additional Data Type ===
The entity '''LocalAdditionalDataType''' (Figure 14 LocalAdditionalDataType) is a container for code value pairs for local usage outside the ICAR specification scope.

It is used as an optional list element '''LocalAdditionalData''' in each specific entity. 
[[File:Mw13.png|center|thumb|418x418px|''Figure 14 LocalAdditionalDataType'']]

# '''AdditionalDataCode''': Name of the code value pair
# '''AdditionalDataValue''': Value of the code value pair
# '''AdditionalDataComment''': Optional description of the local data

=== Time Period Type ===
The utility type '''TimePeriodType''' (Figure 15TimePeriodType) is a wrapper type designed to transport the beginning and end of a time period.
[[File:Mw14.png|center|thumb|422x422px|''Figure 15TimePeriodType'']]

# '''StartTime''': The start of the time period
# '''EndTime''': The optional end of the time period

== Naming Rules ==
Names of data elements, operations and messages use upper camel case.

Service name consist of:

# A prefix which gives the type of operation according the following:
#* Create: Insert data into a data base
#* Update: update of a data base
#* Get: retrieve data from data base
#* Delete: delete data from data base
# The name of the service For example UpdateMilkingResult is the service which allows updating a data base from milking results exchange. Message name consists of:
## The name of the service
## A suffix, gives the type of message:
##* Request
##* Response

For example, UpdateMilkingResultRequest is the request to trigger the service UpdateMilkingResult.

== References ==
1.       Semantics for Smart Dairy Farming: a milk production registration standard – SDF June 2013

2.      UN / UNCEFACT Modeling Methodology User Guide (CEFACT / TMG/N093)

3.      UN / UNCEFACT Business Requirements Specifications Document Template (CEFECT/ICG/005)

4.      ISO 11787 : Electronic data interchange between information systems in agriculture —Agricultural data interchange syntax

5.      ISO 11788 : Electronic data interchange between information systems in agriculture — Agricultural data element dictionary —Part 1: General description —Part 2: Dairy farming

6.      ISO 17532 : Stationary equipment for agriculture —Data communications network for livestock farming 

7.       ISO 11784: Radio frequency identification of animals - code structure

8.      ISO 3166 -1 : Country code

9.      ICAR G 

</div>
</div>

= Procedure 2: Milking Data Services =
<div class="mw-collapsible mw-collapsed">
    <div>
== Introduction ==
The milking, milk sampling and milk analysis process is a fundamental part of dairy performance recording. Automatic, fast and reliable data exchange is a pre-requisite for effective monitoring of dairy herds.

The business process “Exchange of Milking Data” is designed to

# Exchange data linked to a milking event
# Exchange data linked to milk analysis

It provides several methods designed to help synchronizing the equipment data base and the farm management database without efforts:

# '''UpdateMilkingResult''': Transfer details on milking events, milk sampling and on farm measurements
# '''GetMilkingLabResults''': Request the results of a milk sample analysis done in a laboratorium

The service descriptions follow the principals described in “Guideline 1 Methodology” - [https://icarsecretariat.bitrix24.eu/~egZDL '''link here'''] - and reuse the basic elements defined there.

The complete description of the codelists referenced here can be found in Appendix A ([https://icarsecretariat.bitrix24.eu/~keoFw '''link here''']) data dictionary.

== Scope ==
Figure 1 gives a pictorial summary of the main elements of this guideline. The numbers in this figure refer to the heading numbers of this procedure.
[[File:Mww1.png|center|thumb|413x413px|''Figure 1.  Scope of Guideline.'']]


== Common Components ==

=== Milk Characteristics Type ===
The component Characteristics conveys a list of milking characteristics. A characteristic of type MilkCharacteristicsType is used here as a synonym for the results of a measurement or a classification applied to a milk sample, on farm or in a laboratory. It can also be used for recording parameters describing of the environmental situation or the status of the cows during the milking process, e.g. weight of the animal during milking.

The characteristic is identified by a unique code which references a characteristic definition according to code list “ICAR_MilkCharacteristicCode”. Table “Milk Characteristics Codes“ in section “Annex.ICAR Milk Characteristics Codes” lists a basic set of ICAR defined characteristics. It can easily be extend by locally used characteristic definitions.
[[File:Mww2.png|center|thumb|431x431px|''Figure 2 Milk Characteristics Type'']]

# '''MilkCharacteristicCode''': The mandatory identifier of a milk characteristic.
# '''MilkCharacteristicValue''': A milk characteristic measure value. The attribute “unitCode” must be set according to the table “Milk Characteristics Codes”

=== Milk Characteristics Local Type ===
Similar to MilkCharacteristicsType this container conveys a list of locally used milking characteristics which are not part of the official “ICAR Milk Characteristics Codes” list.

# '''Local Milk Characteristic Code''': The mandatory identifier of a local milk characteristic. The code list must be provided locally.
# '''Milk Characteristic Value''': A milk characteristic measure value. 

[[File:Mww3.png|center|thumb|454x454px|''Figure 3 Milk Characteristics Local Type'']]

== 1             Exchange of Milking Event Data ==
'''Service Description: UpdateMilkingResult'''

=== Purpose ===
To allow the owner of the equipment to have registered by an external information system:

# Milking results
# Links between animal identifiers and those of bottles of milk sample in order to register later the results of the milk laboratory.
# Results of on farm measurements and milk analysis

=== Request description ===
Message UpdateMilkingResultRequest (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications). 

It is used to send new or changed data of one or more milking events to the service provide.

Figure 4 UpdateMilkingResultRequest
[[File:Mww4.png|center|thumb|473x473px|''Figure 4 Update Milking Result Request'']]

=== AnimalMilkingResults ===
AnimalMilkingResult conveys the main feature of a given milking:

# '''AnimalIdentity''': One unique animal identifier used for data exchange holding id and label of the milked animal. The ID optionally references entity AnimalDetail transported by Service “UpdateAnimal” if required for further animal details.
# '''Location''': One milking location ID identifying the location where the animal has been milked. The ID optionally references an entity LiveStockLocation transported by Service UpdateLiveStockLocation if required for further location details.
# '''MilkingParlourUnit, MilkingBoxNumber''': optionally identify the location of milking more detailed
# '''MilkingStartingTime, MilkingDuration, MilkingVisitDuration, MilkingType, MilkingMilkWeight, MilkingSucces''': Items describing the milking itself:
# '''Characteristics''': Milk characteristics (classification or measurements) which are conveyed by the entity '''MilkCharacteristics'''. In principal it is a list of key value pairs with keys identifying the type of characteristics and the values holding the result. The current list of characteristics key definitions is shown in table “Milk Characteristic Codes”
# '''LocalCharacteristics''': Locally defined milk characteristics (classification or measurements) which are conveyed by the entity LocalCharacteristics.
# It conveys a list of locally used milking characteristics which are not part of the official “ICAR Milk Characteristics Codes” list.
# '''QuarterMilking''': Up to four optional entities quarter milking results, optionally including a quarter milk samples and quarter milk characteristics. This result may not be provided by every equipment.
# '''AnimalMilkingSample''' : One  optional entity describing the details of a sample of milk taken for laboratory analyses
# '''MilkingDeviceID''': One optional item holds an id of the device used for milking. The ID optionally references an entity Device transported by Service “UpdateDevice” if required for further device details.
# '''MeasureDeviceID''': One optional item holds an id of the device used for measuring. The ID optionally references an entity Device transported by Service “UpdateDevice” if required for further device details.
# '''LocalAdditionalData''': Optional list of key/value pairs used in a local context as described in section “Common Components – Local Adaptions”

=== Characteristics ===
The entity conveys the milk characteristics recorded during the milking event.

For details see the description of “MilkCharacteristcsType” in section “Common Components” above.

=== Animal Milking Sample ===
[[File:Mww5.png|center|thumb|375x375px|''Figure 5 Animal Milking Sample'']]
The entity gives the identification and the main features of a milk sample.

# '''Bottle Identifier Type''': The type of bottle identifier according to code list “BottleIdentifierCodeType”
# '''Rack Number''': Number of the sample rack
# '''Bottle Position''': Position of the bottle in the sample rack
# '''Bottle Identifier''': Bottle identifiers read from barcode or RFID
# '''Valid Sample Filling Indicator''': Indicator of valid sample filling compared with expected value according to code list “'''ValidSampleFillingIndicatorCodeType'''”

=== Quarter Milking ===
[[File:Mww6.png|center|thumb|408x408px|''Figure 6 Quarter Milking'']]
The entity QuarterMilking gives the milking result and optionally sampling and characteristic details for one of four given quarters.

# '''Quarter ID''': Identification of the quarter for which the results apply (1..4)
# '''Quarter Milking Duration''': Milking duration of the quarter, default unit seconds
# '''Quarter Milking Weight''': Milk weight of the quarter, default unit kg
# '''Quarter Characteristics''': Milk characteristics of the quarter. For details see description of entity Characteristics above.
# '''Local Quarter Characteristics''': Locally used milk characteristics of the quarter. For details see description of entity LocalCharacteristics above.
# '''Quarter Milking Sample''' : One optional entity describing the details of a sample of milk taken from the quarter for laboratory analyses. For details see description of entity Animal Milking Sample above.

=== Response description ===
[[File:Mww7.png|center|thumb|453x453px|''Figure 7 Update Milking Result Rsponse'']]

== Exchange of Milk Analysis Result Data ==
'''Service Description: GetMilkingLabResults'''

=== Purpose ===
To allow the owner of the equipment to retrieve the analysis results of milk samples from an external information system for herd management and calibration purposes. The link between the sample identification and analysis results must be provided by the information system of the MRO.

=== Request Description ===
Message '''GetMilkingLabResultsRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications). 

It is used to request the results of a laboratory analysis stored in the farm management system. 
[[File:Mww8.png|center|thumb|460x460px|''Figure 8 Get Milking Lab Results Request'']]
The size of the response can be controlled by request parameters in 

Milking Lab Result Request Type (see diagram below):
[[File:Mww9.png|center|thumb|469x469px|''Figure 9 Milking Lab Result Request Type'']]

# '''Location''': The identification of the farm for which laboratory results are requested
# '''AnimalIdentifier''': The anmial id for which laboratory results are requested
# '''EventTimePeriod''': Period of sampling moments at which the requested results have been sampled
# '''RegistrationTimePeriod''': Period of registration moments at which the requested results have been registered at the farm management system

It is the responsibility of the farm management system to define the requirements and the valid ranges for these parameters.

=== Response Description ===
Message GetMilkingLabResultsResults (see diagram below) is in compliance with the general specifications for results (see General specifications / Response specifications)

It is used to receive the results of a laboratory milk sample analysis stored by the service provider. Since the registration of a milk sample at a farm management system or a laboratory is done by the entity AnimalMilkingSample its returned data in entity AnimalMilkingLabResults is very similar to this entity. Instead of characteristics recorded on the equipment however characteristics based on a laboratory analysis are returned.
[[File:Mww10.png|center|thumb|464x464px|''Figure 10 Get Milking Lab Results Results'']]

=== Animal Milking Lab Result ===
Animal Milking Lab Result conveys the main feature of a given milking analysis result:

# '''AnimalIdentity''': One unique animal identifier used for data exchange holding id and label of the milked animal. The ID optionally referenes an entity AnimalDetail transported by Service “'''UpdateAnimal'''” if required for further animal details.
# '''Location''': One milking location ID identifying the location where the animal has been milked The ID optionally referenes an entity LiveStockLocation transported by Service UpdateLiveStockLocation if required for further location details.
# '''MilkingStartingDateTime''': The precise time of the milking and sampling
# '''Characteristics''': Milk lab analysis characteristics (classification or measurements) which are conveyed by the entity MilkCharacteristics. In principal it is a list of key value pairs with keys identifying the type of characteristics and the values holding the result. The current list of characteristics key definitions is shown in table “Milk Characteristic Codes”
# '''LocalCharacteristics''': Locally defined milk characteristics (classification or measurements) which are conveyed by the entity LocalCharacteristics. It conveys a list of locally used milking characteristics which are not part of the official “ICAR Milk Characteristics Codes” list.
# '''QuarterMilking''': For analysis results of quarter specific samples. Up to four optional entities quarter milking results, optionally including a quarter milk sample and quarter milk analysis characteristics.
# '''AnimalMilkingSample''' : One  optional entity describing the details of a sample of milk taken for laboratory analyses
# '''MilkingDeviceID''': One optional item holds an id of the device used for milking. The ID optionally references an entity Device transported by Service “UpdateDevice” if required for further device details.
# '''MeasureDeviceID''': One optional item holds an id of the device used for measuring. The ID optionally references an entity Device transported by Service “UpdateDevice” if required for further device details.
# '''MeasureDeviceID''': One optional item holds an id of the device used for measuring. The ID optionally references an entity Device transported by Service “UpdateDevice” if required for further device details.
# '''LabAnalyzerModelCode''': Specifies the model of the milk analyzing instrument
# '''LabAnalysisDateTime''': Date and time of the analysis of this sample.
# '''LocalAdditionalData''': Optional, unlimited number of locally used key/value pairs

=== Characteristics ===
The entity conveys the milk characteristics produced by a laboratory analysis of a given milking. The characteristics is identified by a unique code which references a characteristics definition in the table “Milk Characteristics Codes“,  a basic set of ICAR defined characteristics. It can easily be extend by special laboratory specific definitions.

For details see the description of “MilkCharacteristcsType” in section “Common Components” above.

=== Animal Milking Sample ===
The entity AnimalMilkingSample conveys details of the sampling of the milk on the equipment for which the laboratory analysis has been done. It is provides the data given in the process of milking result registration at the farm management system. This helps the equipment in verifying the link between sampling on the equipment and results provided by the farm management system.

For details see the description of “Entity AnimalMilkingSample” in section “Milking Results”.

=== Quarter Milking ===
[[File:Mww11.png|center|thumb|434x434px|''Figure 11 Quarter Milking'']]
</div>
</div>

= Procedure 3: Animal Data =
<div class="mw-collapsible mw-collapsed">
    <div>
== Introduction ==
A carefully maintained list of animals in the herd is a prerequisite of reliable animal recording. The animal lists on the equipment and on the farm management system are likely to be different because of:

# Different input sources (manual maintenance by farmer, legal registration in the farm management system)
# Different availability of data The business process “Exchange of Animal Data” is designed to 
# initialize the database of the equipment or herd management system
# propagate new or changed data to or from the farm management system
# help detecting data conflicts earlier It provides several methods designed to help synchronizing the equipment data base and the farm management database without efforts:

# '''Get Herd List''': Initialize animal lists on the equipment or herd management system
# '''Get Animal''': Request animal descriptions from the service provider
# '''Update Animal''': Send animal description changes to the service provider
# '''Get Arrival''': Request animal arrival changes from the service provider
# '''Update Arrival''': Send animal arrival changes to the service provider
# '''Get Departure''': Request animal departure changes from the service provider
# '''Update Departure''': Send animal departure changes to the service provider


The service descriptions follow the principals described in “Guideline A Methodology” and reuse the basic elements defined there.

The complete description of the codelists referenced here can be found in the Annex document.

== Scope ==
Figure 1 gives a pictorial summary of the main elements of this procedure. The numbers in this figure refer to the heading numbers of this procedure.[[File:Mwww1.png|center|thumb|463x463px|''Figure 1.  Scope of Guideline.'']]

== Common Components ==

=== Animal Identity Type ===
The entity gives official (official ear tag numbers etc.) and alternative animal identification used by farmers, equipment (farm number, necklace number, animal name etc.)

Only official identifiers should be used as primary identifier for data exchange. Alternative identifiers are used to detect changes of names or on farm numbers in addition to the AnimalID. At robot level farmers often work with on farm numbers or names which can be reused for other animals and cause errors in the identification of samples.

Alternative identification should be never used as the primary identifier for data exchange.
[[File:Mwww2.png|center|thumb|438x438px|''Figure 2 Animal Identity Type'']]

* '''Identifier''': Alternative animal identifier
* '''Label''': Type of alternative animal identifier according to code list '''LabelCode'''

=== Animal Core Data Set Type ===
The entity gives the core characteristics of a given animal.
[[File:Mwww3.png|center|thumb|755x755px|''Figure 3 Animal Core Data Type'']]

# '''Identifier''': primary unique identifier of an animal
# '''Alternative Identity''': secondary animal identifiers
# '''Specie''': Specie of the animal
# '''Gender''': Gender of the animal
# '''Birth''': Birth date of the animal
# '''Breed''': Local breed code of the animal
# '''Sire''': Sire description entity
#* '''Sire Identifier''': Animal identifier of the sire
#* '''Sire Alternative Identity''': Alternative animal identifiers of the sire
# '''Recipient Dam''': receiving dam description entity in case of embryo transfer
#* '''Recipient Dam Identifier''': Animal identifier of the receiving dam
#* '''Recipient Dam Alternative Identity''': Alternative animal identifiers of the receiving dam
# '''Genetic Dam''': genetic dam description entity in case
#* '''Genetic Dam Identifier''': Animal identifier of the genetic dam
#* '''Genetic Dam Alternative Identity''': Alternative animal identifiers of the genetic dam

=== ArrivalCoreDataSetType ===
The entity gives the core characteristics of an animal arrival to a location.

Figure 4 ArrivalCoreDataSetType
[[File:Mwww4.png|center|thumb|543x543px|''Figure 4 Arrival Core DataSet Type'']]

# '''Arrival Date''': Date of the arrival of the animal
# '''Arrival Reason Code''': local code specifying the reason of the arrival
# '''Origin Location''': The location the animal is arriving from
# '''Local Additional Data''': List of locally defined code/value pairs

=== Departure Core DataSet Type ===
The component gives the core characteristics of an animal departure from a location.
[[File:Mwww5.png|center|thumb|563x563px|''Figure 5 Departure Core DataSet Type'']]

# '''Departure Date''': Date of the departure of the animal
# '''Departure Reason Code''': local code specifying the reason of the departure
# '''Destination Location''': The location the animal is departing to
# '''Local Additional Data''': List of locally defined code/value pairs



=== Animal Description Type ===
The component conveys the description of an animal. Currently it comprises core data, extended data and movement data. 
[[File:Mwww6.png|center|thumb|530x530px|''Figure 6 Animal Description Type'']]

# '''Animal Core DataSet''': Core description of an animal (for details see entity description in section “Common Components.AnimalCoreDataSetType” above)
# '''Animal Extended DataSet''': Conveys the optional elements
#* '''Last Localization''': date of last arrival of the animal on the location
#* '''Last Parturition''': last recorded parturition of the animal
#* '''Last Insemination''': last recorded insemination of the animal
# '''Animal Movement DataSet''': List of the animal’s movements
#* '''Location''': A location on which the animal has been registered
#* '''Arrival''': Conveys the arrival details of the animal on this location  (see entity description in section  “Common Components.ArrivalCoreDataSetType” above)
#* '''Departure''': Conveys the departure details of the animal on this location (see entity description in section  “Common Components.DepartureCoreDataSetType” above)

=== MovementRequest ===
The entity '''MovementsRequest''' (see diagram below) is designed to provide optional parameters which can be used to control the size of the result of a movement response.

It is e.g. used in the messages Get Arrival and Get Departure.
[[File:Mwww7.png|center|thumb|521x521px|''Figure 7 Movement Request'']]

# '''EventTimePeriod''': Limit the extend of the response to the given period of arrival event (see entity description in section “Common entities”,”TimePeriodType” above)
# '''RegistrationTimePeriod''': Limit the extend of the response to the given period of the registration of arrival events (see entity description in section “Common entities”,”TimePeriodType” above)
# '''Location''': If provided the extend of the response will be limited to the animals registered for this (sub)location. With the parameter missing the service provider has to deduce the location from the login credentials or can reject the request.
# '''AnimalIdentifier''': If provided the extend of the response will be limited to the arrivals of the given animal.

== Exchange of Herd List ==

=== Service Description: GetHerdList ===

==== Purpose ====
To allow the owner of the equipment to retrieve the animal herd list including animal movement data and recent reproduction events like last calving and last insemination.

The result size can be narrowed by providing request parameters like location, gender and a period of time. 

==== Request description ====
Message GetHerdListRequest (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications). 

It is used to request the herd list for a given location stored in the farm management system. 
[[File:Mwww8.png|center|thumb|488x488px|''Figure 8 Get Herd List Request'']]


The extend of the result can be controlled by providing optional parameters (see diagram below):
[[File:Mwww9.png|center|thumb|510x510px|''Figure 9 Herd List Request'']]

# '''Gender''': restrict herd list results to male or female animals
# '''Periode''': If provided the result will include also data from the herd’s history within the period range to be interpreted as days. With the parameter missing or of value 0 the herd list result will convey only the animals currently in the herd
# '''Location''': If provided the herd list result will be restricted to the animals registered for this (sub)location. With the parameter missing the service provider has to deduce the location from the login credentials or can reject the request.

==== Response description ====
Message '''Get Herd List Response''' (see diagram below) is in compliance with the general specifications for results (see General specifications / Response specifications)
[[File:Mwww10.png|center|thumb|517x517px|''Figure 10 Get Herd List Response'']]
The result data container '''Herd List Message''' conveys the '''Location''' descriptor and a list of animal descriptions in '''Herd List Animal Description''' of type Animal Description (for details see entity description in section “'''Common Components Animal Description Type'''” above).

=== Service Description: Update Herd List ===

==== Purpose ====
To allow the owner of the equipment to send changes in the animal herd list including animal movement data and recent reproduction events like last calving and last insemination to the service provider.

==== Request description ====
Message '''Update Herd List Request''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications).
[[File:Mwww11.png|center|thumb|549x549px|''Figure 11 Update Herd List Request'']]
The container '''HerdListMessage''' conveys the '''Location''' descriptor and a list of animal descriptions to be processed at the service provider in '''HerdListAnimalDescription''' of type AnimalDescription (for details see entity description in section “'''Common Components'''.'''AnimalDescriptionType'''” above).

==== Response description ====
Message '''UpdateHerdListResponse''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Response specifications)

It is used to receive the status of herd list data processing by the service provider.
[[File:Mwww12.png|center|thumb|491x491px|''Figure 12 Update Herd List Response'']]

== Exchange of Animal Core Information ==

=== Service Description: GetAnimal ===

==== Purpose ====
The service '''GetAnimal''' allows the equipment to retrieve animal core information from the farm management system.

==== Request description ====
Message '''GetAnimalRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications). 

It is used to request the core data describing an animal stored in the farm management system. 
[[File:Mwww13.png|center|thumb|529x529px|''Figure 13 Get Animal Request'']]
'''AnimalIdentifier''': the identifier of the animal for which the data is requested 

==== Response description ====
Message '''GetAnimalResponse''' (see diagram below) is in compliance with the general specifications for results (see General specifications / Response specifications).

It conveys the animal core data for an animal specified by the request parameter '''AnimalIdentifier'''.
[[File:Mwww14.png|center|thumb|540x540px|''Figure 14 Get Animal Response'']]
'''AnimalMessage''': conveys the animal descriptions for the requested animal 

using type '''AnimalDescription''' (for details see entity description in section 

“'''Common Components'''.'''AnimalDescriptionType'''” above).

=== Service Description: UpdateAnimal ===

==== Purpose ====
The service '''UpdateAnimal''' allows the equipment to send information describing a list of animals to the farm management system.

==== Request description ====
Message '''UpdateAnimalRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications).
[[File:Mwww15.png|center|thumb|523x523px|''Figure 15 Update Animal Response'']]
'''AnimalListMessage''': A list of '''AnimalData''' components of type 

'''AnimalListMessageType''' conveying the details of animals currently managed by the equipment
[[File:Mwww16.png|center|thumb|555x555px|''Figure 16 Animal List Message Type'']]

# '''AnimalCoreDataSet''': Core description of an animal (for details see entity description in section “Common Components.AnimalCoreDataSetType” above)
# '''AnimalMovementDataSet''': A list of animal movement information known to the equipment
# '''Location''': The location of the animal
# '''ArrivalCoreDataSet''': The details of the animal’s arrival in this location. (see entity description in section “Common Components.ArrivalCoreDataSetType” above)
# '''DepartureCoreDataSet''': The details of the animal’s departure from this location.  (see entity description in section “Common Components.DepartureCoreDataSetType” above)

==== Response description ====
Message '''UpdateAnimalResponse''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Response specifications)

It is used to receive the status of animal data processing by the service provider.
[[File:Mwww17.png|center|thumb|561x561px|''Figure 17 Update Animal Response'']]

== Exchange of Animal Arrival in Herd ==

=== Service Description: GetArrivals ===

==== Purpose ====
The service '''GetArrivals''' allows the owner of the equipment to retrieve the arrivals of animals for a given location, animal and/or period.

==== Request description ====
Message '''GetArrivalsRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications). 

It is used to request the list of animal arrivals stored in the farm management system. 
[[File:Mwww18.png|center|thumb|553x553px|''Figure 18 Get Arrival Request'']]
The size of the result can be controlled by providing optional parameters in the entity MovementsRequest (see description in section “Common Components” above).

==== Response description ====
Message '''GetArrivalsResponse''' (see diagram below) is in compliance with the general specifications for results (see General specifications / Response specifications).

It provides a list of arrival data sets registered in the farm management system limited by the request parameters.
[[File:Mwww19.png|center|thumb|540x540px|''Figure 19 Get Arrival Response'']]

# '''ArrivalListMessage''': List of animal arrival events conveyed as  '''ArrivalDataSetType'''

[[File:Mwww20.png|center|thumb|538x538px|''Figure 20 Arrival DataSet'']]

# '''AnimalCoreDataSet''': Core description of an animal (for details see entity description in section “Common Components.AnimalCoreDataSetType” above)
# '''Location''': The location of arrival
# '''ArrivalCoreDataSet''': It conveys the details of an animal arrival. (see entity description in section “Common Components.ArrivalCoreDataSetType” above)

=== Service Description: UpdateArrivals ===

==== Purpose ====
The service '''UpdateArrivals''' is designed for registering new or updated animal arrival events in the farm management system.

==== Request description ====
Message '''UpdateArrivalsRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications).

A list of arrival events is transferred to the service provider.
[[File:Mwww21.png|center|thumb|511x511px|''Figure 21 Update Arrival Request'']]

# '''ArrivalListMessage''': List of animal arrival events conveyed as  '''ArrivalDataSetType'''

[[File:Mwww22.png|center|thumb|507x507px|''Figure 22 : Arrival DataSet'']]

# '''AnimalCoreDataSet''': Core description of an animal (for details see entity description in section “Common Components.AnimalCoreDataSetType” above)
# '''Location''': The location of arrival
# '''ArrivalCoreDataSet''': It conveys the details of an animal arrival. (see entity description in section “Common Components.ArrivalCoreDataSetType” above)

=== Response description ===
Message UpdateArrivalsResponse (see diagram below) is in compliance with the general specifications for requests (see General specifications / Response specifications)

It is used to receive the status of arrival events processing by the service provider.
[[File:Mwww23.png|center|thumb|515x515px|''Figure 23 Update Arrival Response'']]

== Exchange of Animal Departure from Herd ==

=== Service Description: GetDepartures ===

==== Purpose ====
The service GetDepartures allows the owner of the equipment to retrieve the departures of animals for a given location, animal and/or period.

==== Request description ====
Message GetDepartureRequest (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications). 

It is used to request the list of animal departuress stored in the farm management system. 
[[File:Mwww24.png|center|thumb|514x514px|''Figure 24: Get Departure Request'']]
The size of the result can be controlled by providing optional parameters in the entity MovementsRequest (see description in section “Common Components” above).

==== Response description ====
Message GetDepartureResponse (see diagram below) is in compliance with the general specifications for results (see General specifications / Response specifications).

It provides a list of arrival data sets registered in the farm management system limited by the request parameters.
[[File:Mwww25.png|center|thumb|516x516px|''Figure 25: Get Departure Response'']]

# '''DepartureListMessage''': List of animal departure events conveyed as '''DepartureDataSetType'''

[[File:Mwww26.png|center|thumb|519x519px|''Figure 26: Departure DataSet'']]

# '''AnimalCoreDataSet''': Core description of an animal (for details see entity description in section “Common Components.AnimalCoreDataSetType” above)
# '''Location''': The location of arrival DepartureCoreDataSet: It conveys the details of an animal arrival. (see entity description in section “Common Components.DepartureCoreDataSetType” above).

=== Service Description: UpdateDepartures ===

==== Purpose ====
The service '''UpdateDepartures''' is designed for registering new or updated animal departure events in the farm management system.

==== Request description ====
Message '''UpdateDeparturesRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications).

A list of departure events is transferred to the service provider.
[[File:Mwww27.png|center|thumb|510x510px|''Figure 27: Update Departure Request'']]

# '''DepartureListMessage''': List of animal arrival events conveyed as  '''DepartureDataSetType'''

[[File:Mwww28.png|center|thumb|513x513px|''Figure 28:  Departure Data Set'']]

# '''AnimalCoreDataSet''': Core description of an animal (for details see entity description in section “Common Components.AnimalCoreDataSetType” above)
# '''Location''': The location of arrival
# '''DepartureCoreDataSet''': It conveys the details of an animal arrival. (see entity description in section “Common Components.DepartureCoreDataSetType” above)

==== Response description ====
Message UpdateDeparturesResponse (see diagram below) is in compliance with the general specifications for requests (see General specifications / Response specifications)

It is used to receive the status of departure events processing by the service provider
[[File:Mwww29.png|center|thumb|540x540px|''Figure 29: Update Departure Response'']]
</div>
</div>

= Procedure 4: Reproduction Data Services =
<div class="mw-collapsible mw-collapsed">
    <div>
== Introduction ==
Monitoring and controlling reproduction is a key issue for livestock farming. It is based on the registration and the analysis of the following events:

# Heat
# Artificial insemination
# Natural service
# Pregnancy check
# Abortion
# Parturition
# Dry off Farmers need:
# to retrieve any types of events to allow the AMS to control precisely milking
# to retrieve heats and parturitions which may be captured by reproduction monitoring devices
# to send part or all the reproduction events they have captured manually on the farm
# Precise reproduction monitoring requires to transmit the hour in addition to the date of the event.

The service descriptions follow the principals described in “Guideline A Methodology” and reuse the basic elements defined there.

The complete description of the codelists referenced here can be found in the Annex document.

== Definitions and Terminology ==
Table 1 contains a list of important definitions for terms and abbreviations used in these guidlelines.
{| class="wikitable"
| colspan="2" |'''''Table 1.  Definitions of Terms used in these guidelines.'''''
|-
|'''Term'''
|'''Definition'''
|-
|CBD
|Central  Database
|}

== Scope ==
Figure 1 gives a pictorial summary of the main elements of this guideline. The numbers in this figure refer to the section numbers of this guideline.
[[File:Mwwww1.png|center|thumb|604x604px|''Figure 1.  Scope of Guideline.'']]

== Exchange of Reproduction Events ==

=== Common Components ===

==== ReproductionEventMessage ====
A '''ReproductionEventMessage''' (see diagram below) may be transmitted by the on-farm device to be recorded by the CBD or retrieved from CBD.
[[File:Mwwww2.png|center|thumb|550x550px|Figure 2: Reproduction Event Message]]
The component includes:

# '''Animal Core DataSet''': mandatory; (see General specifications / Common component)
# '''Location''': mandatory; (see General specifications / Common component)
# '''Event Date Time''': mandatory; date time when the event occurred.
# '''Reproduction Event Extended DataSet''': mandatory, it must be one the following components which are described below:
# Heat
# ArtificialInsemination
# PregnancyCheck
# Abortion
# Parturition
# DryOff
# '''Local Additionnal Data''': (see General specifications / Common component)

=== Specific Event Component Description ===

==== Heat ====
The component includes:

# '''Method''': mandatory; Chemical, Visual, Spectral Pedometers and Other;  see ADE code list.
# '''Accuracy''': optional.

[[File:Mwwww3.png|center|thumb|579x579px|''Figure 3 Heat component'']]

==== ArtificialInsemination ====
The component includes: 

# '''ServiceSireIdentifier''': mandatory; official identifier of the sire used to produce the semen.
# '''SireName''': optional
# '''SireHerdBookID''': optional; only if different from ServiceSireIdentifier
# '''InseminationOrganisation''': optional; only when the artificial insemination is performed by a service provider; locally defined.
# '''Inseminator''': optional; only when the artificial insemination is performed by a service provider; locally defined.
# '''SemenBox''': optional; the number of the box where the straws of semen are stored; locally defined.
# '''SemenProvider''': optional; the identifier of body which produced the straws: locally defined.
# '''TypeOfSemen''': optional; Fresh or Frozen; see ADE code list.
# '''SexingSemen''': optional; sexing male, sexing female; see ADE code list.

[[File:Mwwww4.png|center|thumb|537x537px|''Figure 4 Artificial insemination component'']]

==== Natural Service ====
The component includes: 

# '''EventEndDateTime''': optional; only in case of mating period.
# '''ServiceSireIdentifier''': mandatory; official identifier of the sire used to produce the semen.
# '''SireName''': optional
# '''SireHerdBookID''': optional; only if different from ServiceSireIdentifier

[[File:Mwwww5.png|center|thumb|556x556px|''Figure 5 Natural service component'']]

==== PregnancyCheck ====
It includes.

# '''Result''': mandatory, see ADE code list.
# '''PregancyCheckMethod''': mandatory; Palpation, Echography, Other; see ADE code list

[[File:Mwwww6.png|center|thumb|561x561px|''Figure 6: Pregnancy check component'']]

==== Specific component description: Abortion ====
To be used in case of loss of embryos. No specific information.

==== Specific component description: Parturition ====
To be used when the result of the gestation is not embryos whatever live or dead.

The parturition incudes:

# '''Parturition ease''': optional; a local code list should be provided.
# '''Offspring''': optional; the list of animals further to that parturition.
# '''Parity''': optional; number of parturitions for that female since its birth.
# '''EmbryoTransfer''': yes or no.

[[File:Mwwww7.png|center|thumb|576x576px|''Figure 7 Parturition component'']]

==== DryOff ====
No specific information.

=== Service Description: GetReproductionEvents ===

==== Purpose ====
To retrieve reproduction events.

==== Request description ====
'''GetReproductionEventRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications)
[[File:Mwwww8.png|center|thumb|557x557px|''Figure 8 Overall description of GetReproductionEventRequest'']]
The component ReproductionEventsRequest (see diagram below) contains the parameters of the request.
[[File:Mwwww9.png|center|thumb|463x463px|''Figure 9 Detailed description of ReproductionEventsRequest'']]
The parameters include:

# '''A time period''': optional; if specified, only events which occurred during the specified time period are retrieved; otherwise all the events are retrieved whatever the date. A time period may be :
#* '''EventTimePeriod''': the dates which are considered to select the events are the dates when the events occurred. Although event dates are recorded by all the servers, it is not the most appropriate method to retrieve data to update the equipment.
#* '''RegistrationTimePeriod''': the dates which are considered to select the events are the dates when the events was registered by the server. Although registration dates are not recorded by all the servers, it is the best practice to retrieve data to update the equipment.
# '''Location''': mandatory; to retrieve the events of a specified location.
# '''AnimalIdentifier''': optional; if specified, only events of the specified animal are retrieved.
# '''ReproductionEventType''': optional; a list of event types; if specified, only events whose types have been specified are retrieved.

==== Response description ====
'''GetReproductionEventResponse''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications)
[[File:Mwwww10.png|center|thumb|485x485px|''Figure 10 Overall description of Get Reproduction Event Response'']]
The response contains a list of '''ReproductionEventMessage'''. 

There is one '''ReproductionEventMessage''' per event 

(see '''Specific Event Component Description''')

=== Service Description: Update Reproduction Events ===

==== Purpose ====
To have reproduction events registered by the CDB.

==== Request description ====
'''UpdateReproductionEventsRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications)
[[File:Mwwww11.png|center|thumb|525x525px|''Figure 11 Overall description of Update Reproduction Event Request'']]
The request contains a set of ReproductionEventMessage (see Specific component description) to be registered.

==== Response description ====
'''UpdateReproductionEventsResponse''' is in compliance with the general specifications for responses (see General specifications / Request specifications)
</div>
</div>

= Procedure 5: Technical Data Services =
<div class="mw-collapsible mw-collapsed">
    <div>
== Introduction ==
Technical services are used to support the correct functionality of data exchange software.

In order to minimize the data transfer size often just a reference is transferred in the messages described above e.g. the location identifier or the device identifier. The describing details of the referenced object have to be transferred in the context of creation or changes by using specific technical services.

Furthermore the equipment must be enabled to retrieve the current content of locally used code lists in order to be able to react to changes. 

A number of services has been designed to meet these requirements:

# '''UpdateDevice''': transfer details of a device
# '''UpdateLocation''': transfer details of a location or sub location
# '''GetLocalCodeList''': retrieve local code lists from local service providers

== Definitions and Terminology ==
Table 1 contains a list of important definitions for terms and abbreviations used in these guidlelines.
{| class="wikitable"
| colspan="2" |'''''Table 1.  Definitions of Terms used in these guidelines.'''''
|-
|'''Term'''
|'''Definition'''
|-
|
|
|}

== Scope ==
Figure 1 gives a pictorial summary of the main elements of this guideline. The numbers in this figure refer to the section numbers of this guideline.
[[File:Mwwwww1.png|center|thumb|519x519px|''Figure 1: . Scope of Guideline.'']]

== Service GetLocalCodeList ==

=== Purpose ===
The service '''GetLocalCodeList''' is designed to retrieve local code lists from local service providers. It is the responsibility of

# the service provider to provide the correct set of codes as well as a description
# the equipment manufacturer to retrieve the local code lists and maintain a correct mapping to internal code lists
# the equipment manufacturer to make sure that local code lists are kept up-to-date on the operational equipment

=== Request description ===
Message '''GetLocalCodeListRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications). 

It is used to request the list of local codes for all code list or for a specified code list name from the local service provider. 
[[File:Mwwwww2.png|center|thumb|447x447px|''Figure 2: Get Local Code List Request'']]
[[File:Mwwwww3.png|center|thumb|452x452px|''Figure 3 Specific Request Get Local Code List'']]

# '''LocalDodeList''': Conveys the code of the LocalCodeListCode according to the code list '''LocalCodeListCodeType''' for which the local code list is requested. If missing the content of all local code lists will be returned.

=== Response description ===
Message '''GetLocalCodeListResponse''' (see diagram below) is in compliance with the general specifications for results (see General specifications / Response specifications).

It provides the content of one or all local code lists depending on the request parameter '''LocalCodeList'''.
[[File:Mwwwww4.png|center|thumb|493x493px|''Figure 4 Get Local Code List Response'']]
The component '''LocalCodeListMessage''' conveys a list of '''LocalCodeLists''' with each of it representing the content of a single local code list.
[[File:Mwwwww5.png|center|thumb|486x486px|''Figure 5 LocalCodeList'']]

# '''LocalCodeListCode''': The identifier of a local code list according to the ICAR code list '''LocalCodeListCodeType''' (see section “Code Lists”)
# '''VersionLocalList''': Version identifier of the provided local code list in order to detect changes and assure compatibility
# '''LocalCodeListDataSet''': the list of code details of the code list
#* '''LocalCode''': the unique code of a code list record
#* '''ShortDescription''': Abbreviation of the code description e.g. to be displayed as a small label
#* '''FullDescription''': Full code description e.g. to be displayed in wider display components
#* '''Description''': Description of a code e.g. used by developers for a better understanding

== Service UpdateDevice ==

=== Purpose ===
The service '''UpdateDevice''' is designed to inform the farm management system about details of a milking or analysis device reverenced by device id in the services described above. The details might be useful for correct interpretation of the data produced on this device. Updates should be transmitted as soon as devices are referenced or relevant information of referenced devices has changed.

=== Request description ===
Message '''UpdateDeviceRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications).
[[File:Mwwwww6.png|center|thumb|448x448px|''Figure 6 Update Device Request'']]
'''DeviceListMessage''': A list of components of type '''DeviceType''' describing devices referenced by device id in the messages described above. 
[[File:Mwwwww7.png|center|thumb|446x446px|''Figure 7 DeviceListMessage'']]

# '''Device:''' conveys the identifier and the characteristics of a device used to get a set of given results
# '''Identifier''': unique identifier of the device Best practice proposals on the creation of unique device identifiers:
#* The device could be identified by the MAC address of its network interface which is globally unique
#* In case two and more devices share one network interface, a local unique postfix should be added to the MAC address
# '''Location''': current location of the device
# '''Manufacturer''': manufacturer of the device according to code list '''ManufacturerCode'''
# '''SoftwareVersion''': current version of the device software
# '''HardwareVersion''': current version of the device hardware
# '''LocalAdditionalData''': List of locally defined code/value pairs

=== Response description ===
Message '''UpdateDeviceResponse''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Response specifications)

It is used to receive the status of device detail processing by the service provider.
[[File:Mwwwww8.png|center|thumb|529x529px|''Figure 8 UpdateDeviceResponse'']]

== Service UpdateLivestockLocation ==

=== Purpose ===
The service '''UpdateLivestockLocation''' is designed to inform the farm management system about details of a locations reverenced by Location id in the services described above. Updates should be transmitted as soon as locations are referenced or relevant information of referenced locations has changed.

A livestock location is an identified place where an information system can localize the animals.

It is not possible to define a concept which may be usable everywhere. Different types of livestock location exist: farm, barn, holding, premise… Moreover for given type of location, a farm for example, different identifiers may exist: that given by the milk recording organization, that given by the government… For the European Union, in most cases, the holding identifier as defined by the EU regulation for animal traceability is used. The type of livestock location as well as its identifier depends on the business context. Hence before starting data exchange, the sender and the recipient should agree on the 

# The type of location
# The type of identifier

=== Request description ===
Message '''UpdateLivestockLocationRequest''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Request specifications).
[[File:Mwwwww9.png|center|thumb|452x452px|''Figure 9 UpdateLivestockLocationRequest'']]
[[File:Mwwwww10.png|center|thumb|462x462px|''Figure 10 LivestockLocationListMessage'']]

# '''Identifier''': Identifier of a livestock location according to the locally defined schema of location id creation
# '''IdentifierType''': Type of location identifier according to code list '''LivestockLocationIdentifierCode''' and locally permitted identifier schemas
# '''Name''': The name of the location
# '''Country''': The country the location is belonging to according to code list ISOTwoletterCountryCode
# '''LocalAdditionalData''': List of locally defined code/value pairs

=== Response description ===
Message '''UpdateLivestockLocationResponse''' (see diagram below) is in compliance with the general specifications for requests (see General specifications / Response specifications)

It is used to receive the status of location detail processing by the service provider.
[[File:Mwwwww11.png|center|thumb|488x488px|''Figure 11 UpdateLivestockLocationResponse'']]
</div>
</div>

= Appendix A: Data Dictionary =
<div class="mw-collapsible mw-collapsed">
    <div>
== Introduction ==
For standardized electronic data exchange a data dictionary is a basic requirement. It provides a complete listing, definition and description of all elements in use.  

The xsd files are from now on regarded as the primary data dictionary. Descriptions of the elements have to be maintained inside the xsd files using special xsd:document elements:
[[File:Mwwwwww1.png|center|thumb|663x663px|''Figure 1. Example of xsd file contents.'']]
A human readable hyperlink document will be created from the xds files using the export features of tools like e.g. XMLSpy. The dictionary document will be published on the ICAR ADE website together with the specifications and the wsdl/xsd files.

== Definitions and Terminology ==
Table 1 contains a list of important definitions for terms and abbreviations used in these guidlelines.
<center>
{| class="wikitable" style="text-align:center;
| colspan="2" aligh = "left"|'''''Table 1.  Definitions of Terms used in these guidelines.'''''
|- style="background-color:#efefef;
|'''Term'''
|'''Definition'''
|-
|wsdl
|Web Services  Description Language (WSDL /ˈwɪz dəl/) is an XML-based interface definition language that is used for  describing the functionality offered by a web service.
|-
|XMLSpy
|XMLSpy is a  proprietary XML editor and integrated development environment (IDE) developed  by Altova.
|-
|xsd
|XSD (XML Schema  Definition), a recommendation of the World Wide Web Consortium (W3C),  specifies how to formally describe the elements in an Extensible Markup  Language (XML) document.
|}
</center>

== Scope ==
This appendix contains code lists and milking characteristic codes.

== Code Lists ==

=== IANA_CharacterSetCode ===
For a full code list see file IANA_CharacterSetCode_20130108.xsd

=== IANA_MIMEMedia ===
In this context only code “application/zip” is used.

For a full code list see file IANA_MIMEMediaType_20130103.xsd

=== ICAR_BottleIdentifierCode ===
The type of bottle identifier method.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|BRC
|Barcode
|-
|RFD
|RFID
|}
</center>

=== ICAR_ErrorSeverityCode ===
The error severity code.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|0
|Warning
|-
|1
|Data error
|-
|2
|Fatal error
|}
</center>
=== ICAR_GenderCode ===
The gender code.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|F
|Female
|-
|M
|Male
|}
</center>
=== ICAR_HeatDetectionMethodCode ===
The heat detection method.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|C
|Chemical
|-
|V
|Visual
|-
|P
|Pedometer
|-
|O
|Other
|}
</center>
=== ICAR_LabAnalyzerCode ===
The lab analyzer model. 
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|11
|Foss FT6000
|-
|12
|Foss FT+
|-
|21
|Delta FTIR  automatic
|-
|22
|Delta FTIR 600
|-
|31
|Bentley FTS
|}
</center>
=== ICAR_LabelCode ===
The type of animal identifier.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|EVN
|EU legal visual  identifier
|-
|ISM
|Animal ISO RFID  identifier starting with a manufacturer code (ISO 11 784)
|-
|ISL
|Animal ISO RFID  legal identifier starting with a country code (ISO 11 784)
|-
|FAN
|Farm animal name
|-
|HBN
|Herd Book name
|-
|FNB
|Farm number
|-
|NKN
|Necklace number
|}
</center>
=== ICAR_LivestockLocationIdentifierCode ===
The type of livestock location identifier.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|LEH
|Legal Location Identifier
|-
|MRO
|Location ID  provided by a milk recording organization
|-
|HBO
|Location ID  provided by a herd book organization
|-
|OLI
|Other local  location identifier type
|}
</center>
=== ICAR_LivestockLocationTypeCode ===
The type of location identifier.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|LEH
|Legal European  holding
|-
|
|TODO: No clear  idea of the usage at the moment.

Item will be  removed in the final version if nobody gives good reasons and provides a  useful list of codes during the review period.
|}
</center>
=== ICAR_LocalCodeListCode ===
This code list conveys a list of items of type udt:CodeType for which a local code list must be provided. 

It also provides a list of code list names for locally allowed values in item '''AdditionalDataCode''' of entity '''LocalAdditionalDataType'''. These code lists can be identified by the prefix LocalAdditional + the name of the entity wherein the '''LocalAdditionalData''' entity is used.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|ArrivalReason
|Arrival Reason  for an animal
|-
|Breed
|Breed for an  animal
|-
|DepartureReason
|Departure Reason  for an animal
|-
|InseminationOrganisation
|Insemination  Organisation
|-
|LocalAdditionalAnimalCoreData
|Local code for  AnimalCoreData
|-
|LocalAdditionalAnimalMilkingResultData
|Local code for  AnimalMilkingResultData
|-
|LocalAnimalMilkingLabResult
|Local code for  AnimalMilkingLabResult
|-
|LocalAdditionalArrivalData
|Local code for  ArrivalData
|-
|LocalAdditionalDepartureData
|Local code for  DepartureData
|-
|LocalAdditionalDeviceData
|Local code for  DeviceData
|-
|LocalAdditionalLiveStockLocationData
|Local code for  LiveStockLocationData
|-
|LocalMilkCharacteristic
|Codes for  locally used milk characteristic
|-
|ParturitionEase
|Ease level for a  parturition
|}
</center>
=== ICAR_ManufacturerCode ===
The code for the manufacturer of a device.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|LL
|Lely
|-
|DL
|Delaval
|-
|FW
|Fullwood
|-
|GE
|GEA
|-
|BM
|Boumatic
|-
|AF
|Afikim
|}
</center>
=== ICAR_MilkCharacteristicCode ===
A list of ICAR approved milk characteristcs.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|SCC
|Somatic cell count
|-
|FAT
|Fat 
|-
|PROTEIN
|Protein 
|-
|LAC
|Lactose 
|-
|UREA
|Urea
|-
|BLOOD
|Blood
|-
|ACTETONE
|Acetone
|-
|BHB
|Beta  hydroxybutyrate
|-
|LDH
|Lactate dehydrogenase
|-
|PRO
|Progesteron
|-
|AVGCOND
|Average  conductivity value of the milk  at 25 °  C
|-
|MAXCOND
|Maximum  conductivity value of the milk at 25 ° C
|-
|AVGFLWR
|AverageFlowRate
|-
|MAXFLWR
|MaxFlowRate
|-
|WEIGHT
|Weight of animal
|}
</center>
=== ICAR_MilkingTypeCodeType ===
A list of codes representing the types of milking.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|1
|Official milk  result supplied by milk recording organisation
|-
|2
|Measure by ICAR  approved equipment
|-
|3
|Measure of not  approved equipment
|}
</center>
=== ICAR_PregnancyCheckCode ===
A list of codes representing the result types of a pregnancy check.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|U
|Unknown
|-
|E
|Empty
|-
|P
|Pregnant
|}
</center>
=== ICAR_PregnancyCheckMethodCode ===
A list of codes representing the methods of a pregnancy check.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|E
|Echography
|-
|P
|Palpation
|-
|O
|Other
|}
</center>
=== ICAR_QuarterCode ===
A list of codes representing the position of an udder quarter.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|LF
|Left front
|-
|RF
|Right front
|-
|LR
|Left rear
|-
|RR
|Right rear
|}
</center>
=== ICAR_ReproductionEventTypeCode ===
A list of codes representing the types of reproduction event.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|CAL
|Calving
|-
|PGC
|Pregnancy Check
|-
|INS
|Artificial  insemination, Embryo transfer, Assisted mating
|-
|PEM
|Period mating
|-
|DRO
|Dry off
|-
|HET
|Heat
|-
|ABT
|Abortion
|}
</center>
=== ICAR_RequestProcessingStatusCode ===
A list of codes representing the possible return status of a request processing.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|O
|Processed without errors
|-
|P
|Data accepted for  asynchronous processing 

(client can retrieve the processing result later using provided ticket)
|-
|E
|Processed and rejected due  to errors
|-
|W
|Processed with warnings
|}
</center>
=== ICAR_SemenTypeCode ===
A list of codes representing the semen types.
<center>
{| class="wikitable" style="text-align:center;"
|'''Code'''
|'''Definition'''
|-
|F
|Fresh
|-
|Z
|Frozen
|-
|
|
|}
</center>
=== ICAR_SexingSemenCode ===
A list of codes representing the sexed semen type.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|Y
|Sexing semen :  Male or Female
|-
|F
|Sexing semen :  Female
|-
|M
|Sexing semen : Male
|-
|N
|No sexing semen
|}
</center>

=== ICAR_SpecieCode ===
The code for the animal species.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|BUF
|Buffalo
|-
|OVI
|Ovine
|-
|BOV
|Bovine
|-
|GOT
|Goat
|}
</center>
=== ICAR_ValidSampleFillingIndicatorCode ===
A list of codes representing the milk sample filling indicator.
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Definition'''
|-
|0
|successful  milking (> 80% of expected milk)
|-
|1
|incomplete (<  20 % of expected milk) or interrupt milking
|-
|2
|milking  complete, measurement  not complete  (between 20 and 80 %)
|}
</center>

=== ISO_ISO3AlphaCurrencyCode_20120831 ===
A list of two letter codes representing the currencies according to ISO.

For details see file ISO_ISO3AlphaCurrencyCode_20120831.xsd

=== ISO_ISOTwoletterCountryCode ===
A list of two letter codes representing the countries according to ISO.

For details see file ISO_ISOTwoletterCountryCode_SecondEdition2006VI-13.xsd

=== UNECE_AgencyIdentificationCode ===
A list of codes representing the measurement unit defining agencies according to UNECE.

For details see file UNECE_AgencyIdentificationCode_D12A.xsd

=== UNECE_CharacterSetEncodingCode ===
A list of codes representing character set encodings according to UNECE.

For details see file UNECE_CharacterSetEncodingCode_40106.xsd

=== UNECE_MeasurementUnitCommonCode ===
A list of codes representing measurement units according to UNECE.

For details see file UNECE_MeasurementUnitCommonCode_8.xsd

== ICAR Milk Characteristics Codes ==
Measurement of milk characteristics or characteristics related to milking like “weighing during milking” is a quickly evolving domain. For that reason the preference of the ICAR ADE standardization body tended toward defining a flexible container conveying milk characteristics as an open list of key value pairs with the identifying key being the characteristics code. 

For details see section 5.1 “Milking.Common Components.MilkCharacteristicsType”
<center>
{| class="wikitable" style="text-align:center;"
|- style="background-color:#efefef;
|'''Code'''
|'''Description'''
|'''Unit'''
|'''TYPE'''
|'''DIGITS DECIMAL  PLACES'''
|'''PATTERN'''
|'''MIN'''
|'''MAX'''
|'''UnitCode UNCEFACT'''
|'''Annotation UNCEFACT'''
|-
|SCC
|Somatic cell  count
|x1000 cells/ml
|NR
|4
|9990
|0
|9999
|NCL
|number of cells
|-
|FAT
|Fat 
|percentage
|NR
|4.2
|90.99
|0
|15.00
|VP
|percent volume
|-
|PROTEIN
|Protein 
|percentage
|NR
|3.2
|0.99
|0
|9.99
|VP
|percent volume
|-
|LAC
|Lactose 
|percentage
|NR
|3.2
|0.99
|0
|9.99
|VP
|percent volume
|-
|UREA
|Urea
|ppm, mg/l 
|NR
|3
|990
|0
|999
|M1
|milligram per litre
|-
|BLOOD
|Blood
|boolean
|NR
|1
|<nowiki>0|1</nowiki>
|0
|1
|undefined
|implied
|-
|ACTETONE
|Acetone
|mmol/l
|NR
|4.3
|0.999
|0
|9.999
|M33
|milli mole per  liter
|-
|BHB
|Beta hydroxybutyrate
|mmol/l
|NR
|4.3
|0.999
|0
|9.999
|M33
|milli mole per  liter
|-
|LDH
|Lactate  dehydrogenase
|IU/l
|NR
|4.3
|0.999
|0
|9.999
|undefined
|implied
|-
|PRO
|Progesteron
|mmol/l
|NR
|4.3
|0.999
|0
|9.999
|M33
|milli mole per  liter
|-
|AVGCOND
|Average  conductivity value of the milk  at 25 °  C
|mS/cm
|NR
|2.1
|0.9
|0
|9.9
|H61
|millisiemens per  centimetre
|-
|MAXCOND
|Maximum  conductivity value of the milk at 25 ° C
|mS/cm
|NR
|2.1
|0.9
|0
|9.9
|H61
|millisiemens per  centimetre
|-
|AVGFLWR
|AverageFlowRate
|Kg/min
|NR
|3.2
|0.99
|0
|9.99
|F31
|kilogram per minute
|-
|MAXFLWR
|MaxFlowRate
|Kg/min
|NR
|3.2
|0.99
|0
|9.99
|F31
|kilogram per minute
|-
|WEIGHT
|Weight of animal
|Kg
|NR
|4
|9990
|0
|1500
|KGM
|kilogram
|}
</center>
</div>
</div>