Defining a message format

Last modified by Erik Bakker on 2023/01/24 15:04

Earlier in this module, we already learned what message definitions are.
In this microlearning, we focus on setting the message format correctly in design. Setting this correct in Design helps build your integration in Create.

In this microlearning, we will learn which options you have for defining a message format in Design and how you can set it.

Should you have any questions, please contact academy@emagiz.com.

1. Prerequisites

Basic knowledge of the eMagiz platform

2. Key concepts

This microlearning centers around defining a message format.

With message format we mean: The form in which the message is sent to or received from an external party the moment it can be validated by the system

In other words, whether the message that you need to send or the message that you receive is in JSON or XML.

3. Defining a message format

You can define your message format in two places in Design:

On the system level
On integration level

3.1 Defining a message format on system level

When you go to Design and double click on a system you will see the following configuration. In this case, we are interested in the default message format

crashcourse-platform-design-defining-a-message-format--define-message-format-system-level.png

By switching between XML and JSON you indicate that all messages that are being sent and received concerning this system are defined in XML or JSON.
This is an easy way of correctly defining the message format of all your integrations related to a specific system.

3.2 Defining a message format on integration level

However, it could be that one of the integrations related to a system deviates from the default setting. If so, you can register this on the integration level.
To be more precise on the system message level. When you go to your system message and enter ‘editing mode’ there will be an option called Change message format.

Selecting this option will result in the following pop-up. In this pop-up, you can switch between both formats and save the result.

crashcourse-platform-design-defining-a-message-format--change-message-format-system-message.png

3.3 The message formats explained

In this microlearning, we talked a lot about message formats and the options eMagiz provides on choosing a message format.
In this segment, we will take a deeper look at those two to give you some context of why they exist and what they mean.

Note that in eMagiz we speak of message definitions which can be either XML, JSON or EDI. Validating these messages is therefore also done in a standardized way (with the help of an XSD).

3.3.1 XML

XML stands for eXtensible Markup Language. An XML is simply put, information wrapped in tags.
By defining those tags and agreeing on those tags you can validate the XML and transform based on the input XML to an output XML.

How the tags are named is determined by the person that defined the structure of the XML and therefore could be anything.

The contract of how a message should look is written down in an XSD document (XML Schema Definition) with the help of 'rules'.
Some examples of these rules are:

Ordering of elements and attributes
Maximum length of an attribute
Whether an attribute or entity is optional
Which data type an attribute has (string, boolean, integer, decimal, etc.)
The XSD can check any XML that passes its station to see whether or not it is allowed to continue or not.

Because XML has these characteristics it has become one of the standards in transporting data between systems.

3.3.2 JSON

JSON stands for JavaScript Object Notation. JSON is newer than XML and works based on name/value pairs.
This way the data that is transported comes with less overhead compared to XML.

The names of the name/value pair are determined by the person that defined the structure of the JSON and therefore could be anything.
The way a tag should be named, which datatype (i.e. string, boolean, integer, etc.), how long the information wrapped in the tag can be,
whether the tag is optional or not is written down in a JSON schema.

A JSON schema can check any JSON message that passes its station and see whether or not it is allowed to continue.

Because JSON has these characteristics it has become one of the standards in transporting data between systems.

3.3.3 EDI

EDI stands for Electronic Data Interchange. EDI is a very old standard that is used mainly in retail and transport and logistics to communicate between parties within the supply chain. Each type of EDI message (i.e. Order, Invoice, Aperak) has a pre-defined structure that is periodically updated. Therefore you can exchange orders for example in the D96.A format.

EDI messages are flat-file messages that adhere to a predefined structure. By selecting this option in Design you notify eMagiz that you want to process EDI messages and eMagiz will as a result add the relevant support objects to your flow.

This functionality for EDI messages only works in the new runtime architecture.

4. Key takeaways

By defining your message format you register to which format (XML or JSON) you will validate all messages related to a certain system
Defining a message format can be done in two places (system level and integration level)

5. Suggested Additional Readings

If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the information provided on the following links: