This page describes the handling of versioning in asynchronous communication.

If you are interested in message versioning in synchronous 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. It is described how EUCARIS  collects and maintains the maximum supported version of each Member States. It is described how to enable and configure the async forwarding feature. Finally, the essential prerequisites for the correct asynchronous 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. If new elements are added, they must be optional (because these new items cannot populated by Member States still using the old version).
  2. Old items cannot be removed (because in old versions, they are still used, and it would require effort to remove them).
  3. Value lists can be extended, but it is not possible to remove values.
  4. 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.
  5. A change in definition of a value in a value list, is done by adding a new value.

 

Compatibility issues

In an asynchronous message exchange, there are three points in the flow where it is relevant what version of the message is exchanged, vs. what version of the message is supported.

 

EUCARIS2EUCARIS communication

The first point in the flow is when a message is exchanged between the EUCARIS platforms of two Member States, one being the sender, the other being the receiver of a message. The sender of the message supports and produces a message of a certain version (version x.0), while the EUCARIS platform of the receiver of that message, will also support a certain maximum message version y.0. 

 

 

There are no compatibility issues if x is lower than or equal to y. An example, the sender sends message version 1.0, while the max supported version on the receiving EUCARIS platform 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 receiving EUCARIS platform. Since the message is valid, the receiving EUCARIS platform is able to process it.

However, if x is higher than y, there is a compatibility issue to overcome. In the figure below, the sender sends message version 2.0, while the max supported version on the receiving platform 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, which is implemented at the receiver’s side.

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

Retrieval from download queue

The second point in the flow is when a message (of a certain version x.0) has been submitted in the download queue of a certain EUCARIS platform, for retrieval by a certain application (Examples: EUCARIS web client, a domestic, customised client application, or BatchProcessor). The application retrieving the message will support a certain maximum version (y.0).

 

 

 

 

Once again, there are no compatibility issues if x is lower than or equal to y (e.g. the message available in the queue is 1.0, while the retrieving application supports is 2.0).

Message version 2.0 contains all content that may be available in a 1.0 message, so the retrieving application will be able to process the message.

However, if x is higher than y (message available v2.0, while the retrieving application only supports v1.0), there is a compatibility issue to overcome, since the message available contains information that is undefined in the client application that retrieves the message. It is necessary to downgrade the available message to the max supported version of the retrieving client application.

 

Async forwarding

The third and final point in the flow is async forwarding, i.e. a message (of a certain version x.0) is forwarded to a client application (supporting version y.0).

As in the previous examples, a downgrade of the message is needed if x is greater than y, e.g. if the message version available is 2.0, while the max supported version of the application to which the message is forwarded, is 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.

Retrieving a message from EUCARIS

For retrieval of messages from EUCARIS the Generic Async Service is used, described in the Custom Development Manual (login required).

Important notice: If a client supports a higher version than message version 1.0, and wants to retrieve a message version higher than message version 1.0, it must specify the supported version number in the retrieval request. If no version is specified, EUCARIS assumes that the requesting client only supports version 1.0, and, for that reason, will downgrade messages to version 1.0, even though a higher version may be available in the download queue.

 

Knowledge needed in the EUCARIS Platform

Max supported version

In the chapter on compatibility issues, it has been outlined that the supported versions of sender and receiver of a message, may be different, and that in some scenarios it is possible to send the message without modification, while in other scenarios it is necessary to downgrade .

To decide if a downgrade is necessary, at the EUCARIS platform of the sender of the message, it must be known what version is supported by the receiver of the message. This knowledge is part of the EUCARIS service configuration. In the table ServiceCountryInfo, for each service and for each Member State, it is recorded what is the max supported version (EUC.ServiceCountryInfo.MessageVersionSupported). Everytime a message is to be sent asynchronously, the version of the message (denoted in the header element MessageVersion) is compared to the max supported version, recorded for the RecipientCountry of the message. If EUC.ServiceCountryInfo.MessageVersionSupported is smaller than MessageVersion, the message is downgraded to version = max supported version.

Note: Besides downgrading, there is also the option, in async communication, to not send the message at all. If no downgrade script to the max supported version exists, the message is kept in the upload queue of the sender country, and EUCARIS keeps checking the max supported version of the recipient. As soon as the recipient has upgraded its max supported version, the message can be sent.

This policy can be used if it can be expected that the migration period from the old message version to the new message version is short (a few days only), so that sending can be postponed until the upgrade has taken place.

Maintaining the max supported version

Since the EUCARIS platform records the max supported version of a certain service,  of other EUCARIS platforms, and since the max supported version can change over time because a platform is upgraded to a newer version, it is necessary to repeat determining the max supported version,  to update the recorded version after a upgrade, at other platforms than the platform that has been upgraded.

This is done via the EUCARIS message service ‘Get Supported Message Version’. This is a synchronous message dialogue, implemented at each EUCARIS platform, that requests the max supported version of the EUCARIS asynchronous services, daily. The request message (ServiceMessageVersionRequest) is sent to all members of a service (denoted via ServiceId). The response to the request is provided by the EUCARIS platform, based on the installed version of EUCARIS and the version of the plugin the message belongs to.

The response consists of the max supported version number of that service, which is compared to the max supported version recorded in EUC.ServiceCountryInfo.MessageVersionSupported. If there is a difference, EUC.ServiceCountryInfo is updated (EUC.ServiceCountryInfo.MessageVersionSupported = version obtained and EUC.ServiceCountryInfo.MessageVersionSupportedUpdate = current date and time).

Note:  It is required to correctly set authorisations for the service ‘Get Supported Message Version’. If this service does not work correctly, the platform will have no recordings of max supported versions, which means that EUCARIS assumes the max supported version is 1.0. So, in this case, the platform will never receive messages of a higher version.

Async forwarding

It is a Member States’ design decision if the feature of async forwarding is used. By default, async forwarding is not enabled.

Note: If you use EUCARIS web client for retrieving messages from the download queue, async forwarding does not apply and cannot be used.

If it is convenient for you that your domestic processing application gets messages ‘pushed’ (rather than retrieving them from the EUCARIS download queue), you can choose to enable async forwarding. This means that messages, after arriving in your domestic download queue, are also forwarded to your domestic application. To configure async forwarding, you will have to specify a (domestic) url to which to forward. You must also specify what maximum version of the message is supported by your domestic application . This is done via the EUCARIS Management Client, menu Service Configuration. Async forwarding is set per service (allowing you to use it for some but not all services, and allowing you to specify different domestic destinations per service).

If the url or the max supported version changes, the configuration must be updated manually by a Member States’ administrator.

 

Things to keep in mind

For versioning in asynchronous exchange to work correctly, the following requirements must be met

  • If your domestic client retrieves a message from the download queue, it should specify the version it supports, unless it only supports version 1.0. If you upgrade your client to a higher version, you must adapt the version requested to prevent a downgrade.
  • If you want to enable async forwarding, you have to update the EUCARIS Service Configuration with a url of a domestic system, and a max supported version, using the EUCARIS Management Client. If there is a url change in your domestic application, or if you upgrade your application to a higher message version, you must adapt the EUCARIS Service Configuration.
  • EUCARIS Operations is responsible, via configuration updates, to set authorisations for service ‘Get Supported Message Version’.
  • The service ‘Get Supported Message Version’ must run daily. It may be worthwhile to check periodically if it still does.

Also important to know:

  • The message version received by the recipient Member State, will always be equal to or lower than the max supported version. The max supported version depends on the EUCARIS version installed on the platform, as well as the version of the plugin. The sender may have produced a higher version.
  • It is possible and allowed that the message version you receive in the download queue, is higher than the version you ask for when retrieving, or the version you specify in async forwarding (assumed that this is a conscious decision).
  • Specifically for BatchProcessor: The version of the final response (which is a multiple version) will be equal to the version supported by the legacy system for the single version response. BatchProcessor always asks the highest known version, but may receive a lower version from the legacy system, in which case the multiple response will be of that version.