General properties

A message structure can be considered to be a kind of electronic envelope; it carries information about the sender and receiver on the outside, and a content (letter) inside. The envelope/letter can be sent directly to the receiver, or it can be sent to the PO box of the receiver, who will pick it up later at the post office. In its electronic form the direct send of a message is through a web service, and the post office variant is available in the shape of message exchange platforms.

Mandatory components

The table below contains the mandatory entities and attributes of the message, which can have three components:

  1. commonTechnical; among others the identification of the message exchange platform provider, the sender of the container, date and time of creation. The commonTechnical is always mandatory within a message structure.
  2. commonFunctional; a set of fields that can be used for the routing and handling/workflow of the message without the need to consult the content.
  3. document; the actual business content of the message as input for, or output from, a business process.

In line with the other structure entities, message cannot have a proprietary attribute on the highest level. A possible unique id of the message is stored as messageId within the commonTechnical entity, along with other technical information about the message. For example a unique identifier for a message on a message exchange platform, assigned to a message at the moment it is initially received on the platform (by submitContainer). This messageId is assigned by the message exchange platform; this attribute may not be used by the client who sends the message to the message exchange platform.

The commonTechnical section contains the sender and receiver of a message, these are the senderId and receiverId attributes. These attributes both have a corresponding ‘type’ attribute to provide information about the identification of the sender and receiver. The senderAliasType and receiverAliasType attributes enable the message exchange platform to determine the corresponding internal PO box to where the message has to be delivered. For example, a sender may identify a receiver by an e-mail address instead of the PO box ‘number’ of the message exchange platform client. The message exchange platform will look up the corresponding PO box based on the e-mail address alias. See also the design principles chapter for more information. The mepId is mandatory when a message is sent via a message exchange platform. The mepId identifies the exchange platform on which the message receiver can be found. This can be the same message exchange platform where the sender delivers the message in a container, but the receiver can also be a client from another message exchange platform. In the latter case, the roaming facility is available (if supported) to forward the message to the other message exchange platform.

The commonFunctional section is part of the meta-data which can be used to categorize a message without the need of looking at the content. The sender enables the receiver to compose specific queries by providing this information. This helps to make handling, distribution and workflow more efficient, especially when a codelist is used for these properties, like the AFD function code components for instance. A message exchange platform may provide additional/other properties to facilitate routing, handling and workflow for messages.

The latter part of the structure, including the message content itself, is stored in a document entity. The content itself can have any format and is stored in the content attribute, as long as a character-based notation is used. Commonly used options are:

  • Structured data in JSON, XML, EDIFACT, CSV or other format (either escaped plain text notation or base64 encoded)
  • Binary files like PDF, Word, Excel etc. (base64 encoded)

When the content is encoded, the attributes contentEncoding and contentType are required. In practice, the (non-mandatory) fileName attribute will often also occur here.

Name Occur. Type Description
message 1..* entity Individual message in direct exchange, or part of a container for a message exchange platform.
commonTechnical 1..1 entity Covers all information about sending or storing the message.
entityType 1..1 string Set to ‘default’.
messageId 0..1 string Unique identification of the message.
mepId 0..1 string The unique registration/identification issued by SIVI, to identify a message exchange platform (MEP). Only required for MEP environments.
senderAliasType 1..1 APIALIA Category of senderId, can be used for specific check and verification of the senderId.
senderId 1..1 string The unique identification on the message exchange platform of the party that submits a container to the platform.
receiverAliasType 1..1 APIALIA Category of receiverId, can be used for specific check and verification of the receiverId,
receiverId 1..1 string The unique identification on the message exchange platform of the party that receives a container from the platform.
creationDate 1..1 date Creation date of the message or file.
creationTime 1..1 time Creation time of the message or file.
commonFunctional 0..1 entity Additional meta-data about the content of the message.
entityType 1..1 string Set to ‘default’.
dataCatalogVersion 1..1 ADNAFM Version of the data catalog on which the message is based.
dataCatalogType 1..1 APIDCT Type of data catalog.
messageSubject 1..1 string Description of the subject.
messageContext 1..1 APICON Code that indicates the context of the message.
messageFunction 1..1 APIFUN Code that indicates the function of the message.
document 0..1 entity The actual content of the message.
entityType 1..1 string Set to ‘default’.
contentType 0..1 CNTTYPE Internet media type (MIME) of the original file. Only required when the content is encoded.
contentEncoding 0..1 ENCOD Encoding of the content attribute. Only required when the content is encoded.
content 1..1 string The actual content of the message, either plain text or (base64) encoded.

JSON example

Below is an example of a message. Note that at the top level within JSON, the message entity is not explicitly mentioned. When the message is nested within other structures, such as within the container, the message is given an explicit tag. In XML, the structure is always explicitly defined at the highest level as well.

{
	"commonTechnical": [ {
		"entityType": "default",
		"messageId": "c4eef3a3-8f6d-440b-8b34-8b785fa1301f",
		"mepId": "MEP2020",
		"senderAliasType": "poBox",
		"senderId": "I095678905678901",
		"receiverAliasType": "poBox",
		"receiverId": "I095678905678901",
		"creationDate": "2020-01-01",
		"creationTime": "08:00:00"
	} ],
	"commonFunctional": [ {
		"entityType": "default",
		"dataCatalogVersion": "35C",
		"dataCatalogType": "AFD",
		"messageSubject": "autoverzekering",
		"messageContext": "200",
		"messageFunction": "2000"
	} ],
	"document": [ {
		"entityType": "default",
		"contentEncoding": "base64",
		"contentType": "text/xml; charset=cp858",
		"fileName": "afd001.xml",
		"fileExtension": "xml",
		"content": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGV4YW1wbGUg"
	} ]
}

Feedback

Thanks for your feedback.

Post your comment on this topic.

Post Comment