Specifications

Specifications of the EUCARIS envelope, as well as specifications on message processing and validations, can be downloaded here (credentials required).

Envelope structure

In the EUCARIS v8 architecture, all messages exchanged are wrapped into the EUCARIS Envelope (hereafter referred to as just envelope), which is a generic XML message, that consists of three parts:

  1. Workflow information
  2. Routing information
  3. Content

The workflow information is provided  by the initiator of the workflow, in the envelope that starts the workflow. If a reacting message is sent that prolongs a workflow, the envelope contains a reference to the workflow, so that EUCARIS can add the message to an existing workflow.

The workflow information identifies the initiator (organisation, person), may denote a reason to start the workflow, and denotes the message service to use, with various parameters like  synchronous or asynchronous use.

The routing information consists of the Sender Member State and Recipient Member State of the envelope.

The content consists of one or more messages with metadata.

MessageService

A workflow always relates to one message service, which is declared in the workflow information of the initiating envelope. To populate an envelope correctly, it is not only required to comply to the general, broad envelope specifications, but it is also required to comply to specific requirements of the message service used. Specific message service requirements are denoted in the XML Message Specifications. The specifications contain a section that denotes specific envelope requirements for a client application that initiates a workflow. It also contains a section that denotes specific envelope requirements for a legacy service that receives the initiating envelope and reacts to it.

Single case and multiple case

The envelope contains one or more messages. This means that for services that can be used single case as well as multiple case, e.g. Toll-EETS, there is no difference in the message used for single case or multiple case (In the v7 architecture, there is, e.g. for CBE there is a message for single case use as well as a message for multiple case use). In single case use, the envelope contains one message, and in multiple case use, it contains many (with a certain maximum number, e.g. 250, which may depend on the message service that is consumed).

Priority

The initiator of the workflow denotes the type of processing it wants, by the PriorityCode. Currently, there are three options :

  • Synchronous processing (PriorityCode = 1)
  • Asynchronous processing (PriorityCode = 2)
  • Asynchronous processing with forwarding of the workflow result, i.e. the response message (Priority = 3)

It depends on the message service what priorities are allowed. Example: For the Toll-EETS service, all priorities are allowed, but for the IssuedCPC service, only PriorityCode = 1 is allowed. Also, there are rules about the number of messages that can be submitted, combined with the priority chosen. Example: For the Toll-EETS service, synchronous processing is allowed, but in this case, the envelope shall contain only one message.

Workflow and message identification

The envelope contains workflow and message identifications. EUCARIS uses WorkflowId and MessageId for workflow and message identification, assigned by EUCARIS itself and used by EUCARIS to correctly process envelopes.

The initiator of the workflow also assigns an identification to the workflow (ExternalWorkflowId). This id will be echoed to the initiator in reacting messages. In asynchronous processing, this id can also be used to retrieve messages from EUCARIS.

Each participant creating a message, assigns an identification to it (ExternalMessageId). Messages directly related to a previous one, particularly a response to a request, contain a reference to that message (ReferenceMessageId refers to the MessageId of the directly related message, while ReferenceExternalMessageId refers to the ExternalMessageId).

Detailed specifications on how to use identifications are given in the general envelope specs, as well as XML Message Specification of the message services.

Validation

Everytime an envelope is offered to EUCARIS, the envelope and its contents are validated. Validations are described in UC-11.

If an envelope does not pass validation, it will not be processed. If the envelope contains a workflow initiating message, no workflow will be started, and the sender of the envelope receives an error notification without workflow reference (also referred to as a negative acknowledgement or NACK). The error observed is specified in as much detail as possible (refer to UC-11 for a list of error situations).

If the envelope refers to a known workflow, the sender of the envelope receives an error notification, with a detailed error. Since the workflow cannot be completed successfully, the initiator of the workflow also receives an error notification. This error notification contains a more general error.

Envelope content

Envelopes submitted to EUCARIS by the outside world (client application, legacy service) contain the message or messages created by that application. For a client application, this usually is a workflow initiating message (or a set of workflow initiating messages of the same MessageType). For a legacy service, this usually is a reacting message (or a set of reacting messages of the same MessageType).

If EUCARIS submits a workflow initiating message to a legacy service, in the envelope, it provides the WorkflowId (assigned by EUCARIS), one MessageId per message (assigned by EUCARIS) and the workflow info (provided by the initiating participant).

When the legacy service reacts to the message, it creates a new envelope, and provides the WorkflowId as well as a reference to the MessageId  (ReferenceMessageId). The workflow info can be used by the legacy service, e.g. for logging purposes, but there is no need to echo this information in the response envelope, since this information is already recorded in EUCARIS with the workflow.

If EUCARIS submits a response envelope to a client application (containing one or more reacting messages) it includes the workflow initiating message in the envelope, i.e. the message or messages to which the reacting messages refer. Sometimes, this may be an ‘enriched’ version of the initiating message, e.g. because EUCARIS has added NYSIIS search keys to a request message. So, the client application receives a response envelope containing the workflow initating message, together with all reacting messages. The reacting message is either the response message belonging to the Message Service that has been executed, or an error notification, or a mixture. A mixture of regular response messages and error notifications is possible if the workflow initiating message is an ‘MCI’ request (Multi Country Inquiry) or a multiple case ‘batch’ request.

If a client application retrieves messages from EUCARIS, it will receive a response envelope. Also in this case, the envelope contains the workflow initiating message (the ‘enriched’ version, if applicable), together with all reacting messages that match the input criteria.