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) on the 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 message can be sent directly through a web service (e.g. new Message), 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
structure. Please note: these are only the mandatory components; in this case only the presence of a message
. In many functions the message
will be more extensive, including an AFD-structure. See later in this section for a more detailed example.
commonTechnical
; contains among other things the identification of the message exchange platform provider, the sender of the container, date and time of creation. ThecommonTechnical
is always mandatory within amessageStructure
.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.
A message
structure cannot have a proprietary attribute on the highest level. A possible unique id of the message
is stored as messageId
within the commonTechnical
entity of the message
structure, 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 (after 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 chapter Design principles 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 also provide additional/alternative properties to facilitate routing, handling and workflow for messages.
A general description of AFD structures is provided in introduction to AFD structures, while information on details of AFD structures is available in chapter Where to find details about AFD structures.
Name | Occur. | Type | Description |
---|---|---|---|
messageStructure | 1..1 | entity | Structure for messages. |
commonTechnical | 1..1 | entity | Covers all information about sending or storing the message. |
entityType | 1..1 | string | Set to ‘default’. |
senderId | 1..1 | string | The unique identification on the message exchange platform of the party that submits a container to the platform. |
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 | 1..1 | entity | Entity for general information with regard to structure, handling and processing. |
entityType | 1..1 | string | Set to ‘default’. |
dataCatalogType | 1..1 | ADNDCT | Type of datacatalog. |
dataCatalogVersion | 0*..1 | ADNAFM | Version of the data catalog on which the message is based. |
functionVariant | 1..1 | APIVAR | The function variant is used to determine the additional set of required and optional input and output data. |
*Mandatory when the dataCatalogType is AFD.
When making use of the GRS-protocol (see: AFD-functies (dutch)) the following attributes are additionally mandatory (in other cases those are optional) to be compliant with the protocol:
Name | Occur. | Type | Description |
---|---|---|---|
messageStructure | |||
commonFunctional | |||
messageSubject | 1..1 | string | Description of the subject (with GRS this attribute contains the product ID). |
messageContext | 1..1 | APICON | Code indicating the type of context of the message. |
messageFunction | 1..1 | APIFUN | Code indicating the type of function of the message. |
JSON example
Below is an example of a message. Note that at the top level within JSON, the messageStructure
is not explicitly mentioned. In XML, the structure is always explicitly defined (as messageStructure
) at the highest level.
{
"commonTechnical": [ {
"entityType": "default",
"messageId": "c4eef3a3-8f6d-440b-8b34-8b785fa1301f",
"mepId": "MEP2020",
"senderAliasType": "05",
"senderAlias": "poBox",
"senderId": "I095678905678901",
"receiverAliasType": "05",
"receiverAlias": "poBox",
"receiverId": "I095678905678901",
"creationDate": "2020-01-01",
"creationTime": "08:00:00"
} ],
"commonFunctional": [ {
"entityType": "default",
"dataCatalogVersion": "35C",
"dataCatalogType": "AFD",
"functionVariant": "MeSu01",
"messageSubject": "1",
"messageContext": "100",
"messageFunction": "2000"
} ],
"document": [ {
"entityType": "default",
"contentEncoding": "base64",
"contentType": "text/xml; charset=cp858",
"fileName": "afd001.xml",
"fileExtension": "xml",
"content": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGV4YW1wbGUg"
} ]
}
Post your comment on this topic.