The basic goal of a message exchange platform is the secure interchange of structured and unstructured data, as well as documents among trusted partners. In the insurance industry these parties may be instance insurance providers and (managing) agents, but also vendors delivering services in the fulfilment of policy and claim processes.
A message exchange platform supports a number of functions related to message exchange, accessible through an API.
Data and documents are transported to and from the message exchange platform in containers. A container is a vehicle that holds a collection of messages. A container must have at least one message when used in a request, the container entity in a response may be empty. The maximum number of messages in a container is specified by the message exchange platform provider. The message exchange platform provider assigns a unique Id to a container and keeps record of the composition of its content in order to provide an audit trail.
In the context of transport and handling it is important to have information about which messages are included in the specific container. Once the logistic process is complete, the information is no longer of any operational value and needs not to be registered or archived for specific auditing purposes. Therefore, message exchange platform clients are strongly advised to log information regarding container content and handling for their own internal audit and QA purposes.
Message exchange platform functions
The diagram shows the relation between the different operations with regard to the message exchange platform and its users.
The following message exchange platform functions and their variants are described in the next sections.
- submitContainer-client; post a container to the message exchange platform.
- changeContainer-retract; patch the status of a container on the message exchange platform to be retracted if there are issues with the content.
- retrieveContainer-request; get one or more messages from the message exchange platform based on query parameters (pull).
- changeContainer-confirm; patch the status of a container to report successful processing of a requested container to the message exchange platform.
- changeContainer-cancel; patch the status of a container to report unsuccessful processing of a requested container to the message exchange platform.
- submitContainer-deliver; post received messages from the message exchange platform to the API of the receiver (push).
- submitContainer-roaming; post received messages for receivers which subscribe to another message exchange platform to the API of that MEP.
- retrieveMessage-list; get a list of available messages from the message exchange platform.
In order to use a message exchange platform correctly, a good understanding is required of the key elements used.
- Container; this element is explained in detail in the section “Use of containers” below.
- Message, details of this element can be found in the Message structure paragraph.
- Message exchange platform provider (MEP); an organization who offers a platform to which companies can subscribe in order to send and/or receive messages.
- Message exchange platform client; an organization that subscribes to a message exchange platform, and can submit and retrieve messages.
- Message sender; the originating party of a message.
- Message receiver; the destination party of a message.
- Container sender; the party that submits a container to the message exchange platform.
- Container receiver; the party that receives a container from the message exchange platform.
- Roaming; an agreement between message exchange platform providers to forward messages which are destined for receivers that subscribe to another message exchange platform.
Use of containers
The message exchange platform uses containers to transport a collection of messages. From the perspective of the message exchange platform, there are incoming and outgoing containers.
An incoming container is created by a message exchange platform client and is subsequently submitted to the message exchange platform. An outgoing container is created by the message exchange platform and is subsequently sent to a message exchange platform client. This can be either be in response to a query request from a message exchange platform client (pull), or as a delivery service which collects incoming messages from a client PO box and forwards these to an API provided by the receiver (push).
The diagram shows the composition and direction of the container with regard to the message exchange platform.
In certain situations, a container will hold only a single message. In those specific cases this may seem unnecessary overhead, but the advantage is the fact that one single, uniform process can be used to handle the processing of a container. The relative overhead of packing and unpacking a container is negligible when compared to the overhead of developing and maintaining two separate processes for single and multiple messages.
The container structure is made up by a fixed section of meta-data to support the handling of the container, and the messages transported by the container.
For a detailed definition of the container and message, please refer to container structure and message structure
The content of a container cannot be changed once it has been created. However, it is possible to change the status of a container, depending on the progress of the routing and handling processes. A change of status applies in the following situations:
- A submitted container appears to contain incorrect/erroneous content, and the sender wants to undo the submitting of the container (retract the content from the message exchange platform).
- A requested container has been processed successfully by the receiver, who upon completion notifies the message exchange platform that the messages can be marked as retrieved.
- A requested container was processed unsuccessfully by the receiver, who notifies the message exchange platform that the status of the messages has to be reset, in order for the messages to be requested anew.
Note that an internal status is set while the container is being processed by the platform. If a submitted container is unpacked and the messages are distributed to the respective receiver mailboxes, as shown in the previous paragraph, the message exchange platform sets the status of the container to ‘distributed’. This only applies to incoming containers which are submitted to the message exchange platform.
Outgoing containers are created by the message exchange platform upon reception of a query (requestContainer) from a client, or as a result of an internal process that forwards incoming messages from a client PO box to a client’s API (deliverContainer). In these cases the initial status will be set to ‘delivered’. The client can confirm receipt of the container, or cancel the container.
Overview of status changes
|functionVariant||Status before||Status after||Remarks|
|submitContainer-client||empty||Submitted||New container submitted to the message exchange platform by a message exchange platform client.|
|internal process||Submitted||Distributed||The message exchange platform unpacks a submitted container and distributes the messages to the respective mailboxes of the message recipients.|
|changeContainer-retract||Submitted||Retracted||Full retraction. The container has not been processed, no messages were retrieved by the receiver, all messages are retracted.|
|changeContainer-retract||Distributed||Retracted||Partial retraction. The container has already been processed and some messages were retrieved by the receiver, a copy of those messages is included in the response.|
|retrieveContainer-request||empty||Delivered||A message exchange platform client sends a query and receives a container (pull).|
|submitContainer-deliver||empty||Delivered||A message exchange platform provider delivers incoming messages in a container to the receiver API (push).|
|changeContainer-confirm||Delivered||Confirmed||Processing of the received container content was successful.|
|changeContainer-cancel||Delivered||Cancelled||Processing of the received container content was unsuccessful.|
When a container is submitted by a client, the container will be processed by the message exchange platform. This process consists of unpacking the individual messages from the container, and distributing them by moving them to the respective PO boxes of the individual message receiver. The message exchange platform is completely unaware of the content of the message, it will only handle the payload based on the meta-data. Once the messages from a container have been distributed to their respective receiver PO boxes, the container becomes inactive.
Messages in an incoming (submitted) container are awarded an internal status on the message exchange platform to indicate that they are ‘in transit’. As long as a message is linked to an active container, it cannot be selected to be added to an outgoing container. Once the container is processed, the messages from the container are ‘released’ for further processing on the message exchange platform..
When a container is submitted to the message exchange platform, it can be processed directly or queued to be processed at a later stage. The final status is awarded no matter whether the container was processed right away or later. The only difference is the way in which the result of the processing is communicated.
- If a container is processed immediately upon arrival, the final status is communicated directly in the response.
- If processing of a container is delayed, for instance in case of a large bulk, an initial status ‘submitted’ will be communicated in the response.
Once processing is complete, the final status will be communicated by a separate message that is placed in the PO box of the sender.
If there are any messages that could not be distributed, a copy of those messages will be included in this response.
The message exchange platform provider issues a
containerId which is communicated in the response message. The response may also contain a body section with a copy of the messages that could not be distributed. This will enable the submitting party to investigate and correct any causes of error, and resend the failed messages, or notify the receivers by other means.
|Direct processing||yes||Distributed||OK + copy of the meta-data from the non-distributed messages in the response.|
|Indirect processing initial response||n/a||Submitted||Received.|
|Indirect processing status update||no||Distributed||Response via a message exchange platform message.|
|Indirect processing status update||yes||Distributed||Response via a message exchange platform message + copy of the meta-data from the non-distributed messages in the response.|
The standard message exchange platform functions are conceived with a webservices (HTTP) implementation in mind. With current technology even large volumes can be streamed over a webservice.
However, a message exchange platform provider can also choose to support delivery through FTP. In that case the message format in the file will be exactly the same as in the content of the submitContainer request.
mepId identifies the message exchange platform of the receiver. For audit purposes, this is a mandatory attribute.
The sender and receiver of an individual message are contained in the
receiverId attributes. The default assumption is that both sender and receiver are clients of the same message exchange platform. When roaming is supported, the
mepId of the message will be different from the
mepId of the message exchange platform handling the message (see next section ‘Roaming’).
receiverAliasType attributes enable delivery of messages based on different sender and receiver alias types. For example, a sender may identify a receiver by an e-mail address instead of the PO box ‘number’ on the message exchange platform. The message exchange platform that facilitates the alias option will look up the corresponding PO box based on the e-mail address alias by means of an internal mapping table. This allows a party to send messages from within an application, without the need of maintaining an address structure for the message exchange platform within this application.
An alias can be used to facilitate two different situations; cross-domain addressing and address differentiation within a single organization (message exchange platform client).
Clients of a message exchange platform can operate in different business domains (e.g. insurance, mortgage, notary), and by consequence, they will exchange data with parties in different domains. The address type of a party will vary for each domain. The use of an alias enables the message exchange platform client to address a receiving party with a
receiverAliasType that corresponds with their (main) business domain. Financial advisers can send messages over the message exchange platform of their choice, while addressing insurers, banks and notaries by using their typical domain identification in an alias. This simplifies the communication because the financial adviser does not have to send messages through domain specific networks.
Note The message exchange platform only provides logistic services and is not aware of the actual content of the messages. Using aliases does not imply that the message content will be transformed into formats corresponding to the
In large organizations like insurance companies or banks the work is organized in departments and teams, which play a role in internal routing and workflows. The use of departmental or team e-mail addresses enables targeted addressing of messages. At the same time, the alias construction causes them to be delivered to the same, central PO box from the organization (a single message exchange platform client). The various aliases will converge to the same company PO box on the message exchange platform. After their retrieval they diverge by internal routing and distribution within the receiver environment based on the different e-mail address aliases.
Note When a receiver alias is used for a message, the message is excluded from roaming. Roaming can only be applied when the default
receiverId is used under which the receiver is registered at the message exchange platform.
Several providers of message exchange platforms are active on the Dutch market. Each provider is responsible for its own market access (both for sending and receiving). Because of the standardization and certification of the message exchange platform functions, the technical complexity for this will be limited but these arrangements must be made nevertheless. By facilitating roaming functionality, parties are not required to subscribe to each platform. Roaming will forward messages in containers from the message exchange platform where they are delivered by the sender to the message exchange platform where the respective receivers of the messages subscribe to. It is up to the individual message exchange platform providers to determine for which other platforms roaming will be supported.
A copy of messages destined for a message exchange platform for which roaming is not supported, will be added to the response with an error code to indicate that the destination message exchange platform is not supported.
To facilitate the roaming functionality, all messages destined for other message exchange platforms will be collected to be forwarded in new containers to the respective message exchange platforms. These inter-platform containers are submitted in a similar way as platform clients submit a container to the message exchange platform. They can also be processed in a similar way by the receiving message exchange platform provider.
The only exception in the processing is that there is no need to check for messages destined for other message exchange platforms because the container will only contain messages for the receiving message exchange platform.
Submitting a container by one message exchange platform to another in the context of roaming is is a simple forwarding process of a ‘fire-and-forget’ nature. The platform that submits will not take any further action with regard to the status and processing of the submitted container.
Note Roaming is only supported for messages using the default
receiverId (the unique identification of the receiver as assigned by the message exchange platform provider) and does not work with receiver aliases.
Note ‘HTTP’ and ‘FTP’ are used in this chapter only as a a reference to transfer protocol types. As a best practice for implementation it is advisable to use the secure version of these protocols, HTTPS and FTPS respectively.
Compression on file level is no longer used. Instead, REST API implementations commonly use compression on the (HTTP) transport level as part of the agreement between the message exchange platform provider and its client. The recommended type is end-to-end compression, when the body of a message is compressed by the server and will remain unchanged until it reaches the client.
Notification about compression is exchanged between client and server by the use of HTTP header parameters;
Accept-encoding header is used in the client request to inform the server that compression can be used, and to indicate the supported algorithm(s).
Content-encoding header is used in the server response to indicate the algorithm that was used to compress the response.
Gzip is currently the best practice for end-to-end compression for REST APIs.
Two optional attributes are available in the meta-data of the container to ensure and verify the integrity of the container content. The
hashType attribute is used to provide the type of algorithm that is applied in the calculation of the hash total, and the
hashTotal attribute contains the calculated value of the content of the “messages” object. Technical specifications are provided by the party that operates the message exchange platform.
Depending on the sensitivity of the data it may be required to encrypt the message content in addition to the SSL transport encryption, For more details, see the Security chapter.
The actual technical specifications for encryption are part of the agreement between the sending and receiving party of the message.
The message exchange platform may facilitate non-repudiation by offering an asynchronous hash-function and have the sender supply a signature rather than a hash. However, this requires support on both the sender and the receiver side of a container on top of a public-key exchange.