This page describes the handling of versioning in synchronous communication.

If you are interested in message versioning in asynchronous communication (which works in a different way) please visit this page. 

First, it is outlined why it is needed to support different versions of one and the same message. The downgrading mechanism used to support exchange between Member States on different versions is described. Finally, the essential prerequisites for correct synchronous message version handling, are summed up.

Rationale behind versions

Different versions of one and the same message exists, if there is a requirement for change (e.g., new elements, extensions of value lists) together with the requirement that Member States, in upgrading to a new version,  are free to choose their own planning. This means there is no big bang date at which the old version expires, and the new version  is to be used by all. Instead, there is a migration period, a transition period in which multiple versions of the same message are used and supported, which means that EUCARIS must support information exchange between Member States that use different versions.

Design principles

The requirement to keep supporting one or more older versions, imposes requirements on the design of a new message version. To sustain message exchange,  a new version must be backwards compatible with all previous versions that are still supported,  i.e. the new message version must contain all information  of the previous versions (nothing can be removed).  Furthermore, the new information that is added, must be removable, to prevent that Member States that use an old version, receive information that does not comply with that version.

In practice, the following design principles are used:

  1. Versioning only applies to response messages. If a request message needs change, it is more feasible to create a new message with a different name than the old request message (versions coexist if the old request message can also still be used).
  2. If new elements are added, they must be optional (because these new items cannot populated by Member States still using the old version).
  3. Old items cannot be removed (because in old versions, they are still used, and it would require effort to remove them).
  4. Value lists can be extended, but it is not possible to remove values.
  5. A change in definition of an element (max length becomes longer or its datatype changes), is done by adding a new version of the same element (with a different name and definition.
  6. A change in definition of a value in a value list, is done by adding a new value.

 

Compatibility issue

In synchronous communication, one Member State sends a request, to one or more than one other Member States. All Member States receiving the request, provide a response. If multiple versions of the response message are available, it is important to know:

A. What is the maximum version supported by the client application making the request (x.0).

B. What response version is provided by the Member State or Member States sending a response (y.0).

 

There are no compatibility issues if x is higher than or equal to y. An example, the legacy service produces message version 1.0, while the max supported version of the client application that sent the request, is 2.0.

Since versions are backwards compatible, the 1.0 message will validate against the 2.0 version xsd schema that is implemented on the EUCARIS platform that receives the response message. Since all message content of a 1.0 version message is also present in a 2.0 version message, the client application is able to process it.

However, if x is smaller than y, there is a compatibility issue to overcome. In the figure below, the legacy service produces message version 2.0, while the max supported version of the client application making the request, is 1.0. This means it is not possible to simply send the message, since the 2.0 version of the message contains information that is invalid against the xsd schema of version 1.0, and is undefined in the client application.

Before sending the message, it is now necessary to downgrade the message to the max supported version of the client application, in this case 1.0.

 

Downgrade

Downgrading a message aims to modify the source message, which contains information that does not validate against the xsd schema of  a lower message version, in such a way that the target message does validate against the schema.

In practice, this means:

  1. New elements added in the higher version, are removed when downgrading to a lower versions.
  2. If more than one version of the same element exists (with different definitions), only the ‘old’ element is retained. The new element is removed.
  3. Values in value lists that have been added in higher versions, are either completely removed, or converted to a value allowed in the lower version.

Version denomination

Versions are specified in the EUCARIS header, in the element MessageVersion. In the request message, the client application populates MessageVersion with the maximum supported version of the response message. In the response message, the legacy system populates MessageVersion with the version number of the response message it provides.

Things to keep in mind

For versioning in synchronous message exchange to work correctly, the following requirements must be met:

Custom client application

  • In request messages, a client application shall denote what (maximum) version of the response message it supports, using the header element MessageVersion.
  • A client application is able to handle response messages of all versions lower than or equal to, the maximum supported message version.
  • If a client application is upgraded to support a higher response message version, it shall update MessageVersion in request messages, to the version it now supports.

Legacy system

  • In response messages, a legacy system shall denote what (maximum) version of the response message it supports, using the header element MessageVersion.
  • A legacy system always provides one and the same version of the response message, for every inquiry.
  • If a legacy system is upgraded to a higher version of the response message, it shall update MessageVersion in response message, to the version it now supports.

Important note: The legacy system shall not echo MessageVersion from the request. Doing this, EUCARIS will not be able to detect a compatibility issue and downgrade when this is required.

EUCARIS

  • Will compare the max supported version of the client application, to the message version provided by the legacy system, and downgrade the message if necessary.

EUCARIS Web Client

  • Is maintained by EUCARIS Operations.
  • If for a certain service, a new message version is developed, the Web Client is adapted to support this new version, and ask for this new version in request messages.
  • Member States are upgraded to a new version, after applying the system update containing the new version.