4.3.4. Update the message definition tree

Once a new message format has been saved or during edition of existing messages, the message tree is rendered in the Visual Editor in a hierarchical and graphical form as illustrated below.

In Visual Editor, you can further configure and set up message format as well as add verification rules as explained in following sections.

Message edit screen

Figure 4.65. Message edit screen


Left panel - understand tree structure

The left part of the screen shows the structure of the message, as a tree. It describes all the elements that the message format may contain.

People familiar with xml files will find many similarities between the tree definition used here and the structure of a xml file. The reason is the following: In Babelway, all message formats are first translated into xml, that is used to apply all message transformations. The structure defined here is in fact the xml representation of your message.
Structure of message

Figure 4.66. Structure of message


The tree uses different types of nodes:

  • (1) A value node is just a "normal" node. It corresponds to one element in the message format that we are describing. It can just contain a value, or also be a structural element that contains other nodes.

    • represents an element structure in the corresponding xml.

    • represents an element structure in the corresponding xml which is hidden.

    • represents an element in the corresponding xml.

    • represents an element in the corresponding xml which is hidden.

    • represents an element in the corresponding xml, that contains a fixed static value.

    • represents an element in the corresponding xml, that contains a fixed static value which is hidden.

    • represents an attribute in the corresponding xml.

    • represents an attribute in the corresponding xml which is hidden.

    • represents an attribute in the corresponding xml, that contains a fixed static value.

    • represents an attribute in the corresponding xml, that contains a fixed static value which is hidden.

    A message item will be defined as an xml element or attribute depending on xml generation or translation tool that has been used. The main difference for Babelway platform is that an attribute is unique and cannot be repeated inside an element. So you cannot use loops with these attribute items.

  • (2) Other nodes are virtual nodes. They do not have any correspondence in the messages, but are used to tell additional information to the Babelway platform, like the fact that some elements can be repeated, or have possible structure alternatives.

    • represents a loop node. It means that its content can be repeated multiple times.

    • and indicate that the message can have multiple alternatives. The first icon is used to group all choices, and the second one for every option.

Note: From the message definition if you selected element structure node then hide it using the "Hide in transformations" button and its child node is mapped in the transformation, When opening this transformation after hiding it you may face the error message which says "Can not display mapping because of :" or when saving the transformation you will not be able to save it and no error message will be displayed.

Right panel - edition of element node

The right part of the screen shows how the details about the selected node. From there, you can edit all the properties of the node, or make actions on it to change the structure of the tree (delete, duplicate, ...).

Details of selected node

Figure 4.67. Details of selected node


General parameters are:

Label

The label is the text used to show this node in the message definition tree. It can be changed freely, as it has no impact on the processing of the messages.

Description

The description allows you to save some more documentation about this node.

Name

The name identifies the element in the xml representing the messages. Change only with care, for example XML language doesn't accept spaces.

Default value

Only for message definition OUT. The default value will be used in the message out for this field if no mapping is done for this field.

Filter value

Only for message definition IN. When this value is filled, only the records with this precise value will be used.

You can also add validations on nodes. The validations are assertions that will be checked when we receive a message in this format, or before we send a message in this format. If one of the validations fails, it means that the message does not comply with the definition, and the message will be put in error.

We strongly recommend that you fill the validations, and reject messages that are wrong. If you don't enforce validations, there is a big risk that you send to the receiving partner files that are not correct, because your mapping will probabaly not foresee all of these cases. Validations on message OUT will also allow you to detect early problems in your mappings, detecting it immediately when one of your mapping generates a message that do not comply with the definition.

The following validations are available:

Mandatory

When a field is marked as mandatory, it must have a non-empty value. From the xml point of view, it means that the element must be present, and may not be empty.

Type

Type of the data in the field (String, Number, Date, ...). This field will also affect the other validations that will be available.

Length (only for Strings)

Min or Max length (in characters) for the value.

Regexp (only for Strings)

Regular expression that the value must match.

Min/max value (only for Numbers)

Indicates that the number value must be between the two given limits.

Format (only for Dates/Datetimes)

Format that are accepted, like 'yyyy/MM/dd', ... Full description of accepted formats can be found at ... Multiple allowed formats can be entered, separated by a comma.

Custom

Custom xpath expressions that the value must match (if non-empty).

Appearance in output file is enabling you to decide the conditions in which the selected element will appear in the output file.

Here are all the possible conditions:

Always

This element will always appear in the output file whether or not it's filled or not.

If at least one non-default sub-element appears

This element will appear if at least he has a value or if one of his non-default sub-element decided to appear. By non-default, we mean an element which doesn't have a default value. In short, only structural sub-element (white) and non-default field (blue).

Example of element that will appear in the output:

One out of two blue sub-element mapped

Figure 4.68. One out of two blue sub-element mapped


One blue and 1 green sub-element

Figure 4.69. One blue and 1 green sub-element


1 structural sub-element appears out of 3 sub-elements.

Figure 4.70. 1 structural sub-element appears out of 3 sub-elements.


1 attribute sub-element appears.

Figure 4.71. 1 attribute sub-element appears.


Example of element that will NOT appear in the output:

Two green sub-elements (because they are default values).

Figure 4.72. Two green sub-elements (because they are default values).


One blue with no value and one green sub-elements.

Figure 4.73. One blue with no value and one green sub-elements.


If all sub-elements appear

If all sub-elements decided to appear in the output file

Example of element that will appear in the output:

All blue sub-elements

Figure 4.74. All blue sub-elements


Example of element that will NOT appear in the output:

Two green sub-elements or One blue not filled and one green

Figure 4.75. Two green sub-elements or One blue not filled and one green


Only one out of two blue sub-elements

Figure 4.76. Only one out of two blue sub-elements


Not Empty

(applies only to element without children) Will appear in the output file if it has a value.

Search

On the top of the left panel, a search bar allows you to easily find nodes in big documents.

Search

Figure 4.77. Search


To search nodes, just type part of the name that your searching.

  • All the items that match will be highlighted.

  • The first matching item will be selected, and details shown in right panel.

  • Numbers of matching items will be displayed, with arrows to iterate between matches.

  • If needed, tree will be opened, or scroll will be adjusted, so that current match is made visible.

Updating tree structure

Search

Figure 4.78. Search


To update the tree structure, you have different possibilities

  • When a node is selected, all actions that apply to this node are available on the bottom of the right panel. You just have to click on it to call the wanted action.

  • Move operations can be done immediately in the tree, by just drag-and-dropping your node to the new selected validation. Duplication can be done the same way, by pressing the Ctrl key before the drag.

Managing Choice

You can create choice to manage conditional processing of your message definition.

To identify a node or a set of nodes that can have several alternatives in its structure and/or value, you need to enclose the set of related alternatives within a Choice node and each alternative branch into an Option node.

A Choice node is a virtual node identifying alternative branches. Each alternative branch is a possible option and is represented by an Option virtual node as illustrated in the following example:

Example of a choice

Figure 4.79. Example of a choice


There are two Choice nodes, one for the buyer's information, that accepts either a company structure with a VAT number value, or a person structure with firstname, lastname and address values. The other Choice node is for the price of an Item, it can accept either a price with a 0% or a 21% VAT.

In this latter case, both alternative branches have the same structure, but they have different static values (0 or 21) for their VAT node (static value nodes are green).

It is mandatory that each Option of a Choice is uniquely identifiable compared to each other. They could be identified by having different structures (like the buyer's Choice example) or by having the same structure with different static values (like in the price Choice example).

Managing Loops

Create loops to manage repetitive parts of your message definition.
Loops and grouping

A message is based on three node types as defined in the Message Definition chapter.

To specify that a value or a structural node can occur more than once, you need to enclose it in a Loop. A Loop is a virtual node representing the multiplicity of a node or a set of nodes. It is defined by its minOccurs and maxOccurs properties:

  • MinOccurs defines the minimum number of repetition of the node or the set of nodes that should occur. It may be 0 or any positive number.

  • MaxOccurs defines the maximum number of repetition of the node or the set of nodes that should occur. It is either a positive number or the value " unbounded " (that represents an undetermined number of repeat).

CSV Sample:

By definition a CSV message is composed of a header containing some header items, followed by one or many lines containing line items. The number of line items correspond to the number of header items.

header1,header2,header3,header4
123,aaa,abc,000
456,bbb,def,111
789,ccc,ghi,222
...

Here is the message tree for this CSV:

Message tree

Figure 4.80. Message tree


The headers and line nodes are structural nodes, while header and line items are value nodes. To specify that the line can appear more than once, there is a virtual Loop node enclosing the line node.

Grouping

A Loop can define the multiplicity of a node sequence. To identify a node sequence in a Loop, you must manually group those relevant nodes using one of the following grouping types:

  • Group By: groups together all nodes that have the same value as the Grouping value.

  • Group Adjacent: groups together all nodes that have the same value as the Grouping value, provided that they are also adjacent in the message sequence.

  • Group Starting With: processes the nodes in the supplied sequence in turn, starting a new group whenever one of the node matches the Grouping value.

  • Group Ending With: processes the nodes in the supplied sequence in turn, closing the current group whenever one of the node matches the Grouping value.

Loop parameters can be edited by left-clicking on the loop node in the message tree in the In or Out message tab during channel editing.

Loop parameters

Figure 4.81. Loop parameters


The grouping value is an XPath expression identifying the grouping pattern.

By left clicking on any node, you can:

  • Create Loop: to enclose the selected node in a new loop node.

  • Remove from Loop: to remove the selected node from its parent loop.

  • Put in next/previous Loop: if the selected node is adjacent to a loop node you can make it join that loop to create a multiplicity on a nodes sequence (in that case, specify a Grouping value ).

Regrouping a Loop

An existing loop can also be regrouped using one of the Grouping type. To do this you can use the Regroup this Loop in the loop contextual menu. This will create a new enclosing loop that requires specifying the Grouping type and the Grouping value.

Example with a DESADV message in a CSV format:

TruckId,PalletId,PacketId,Quantity,Item
 1,       1,       1,       5,Item 1
 1,       1,       1,      25,Item 2
 1,       1,       1,       1,Item 3
 1,       1,       2,       3,Item 4
 1,       1,       2,      15,Item 5
 1,       2,       1,     100,Item 6
 1,       2,       1,       2,Item 7
 1,       2,       3,      20,Item 8
 1,       2,       3,      11,Item 9
 1,       2,       3,       9,Item 10
 1,       2,       4,      72,Item 11
 2,       1,       1,      91,Item 12
 2,       2,       1,     423,Item 13
 2,       3,       1,      88,Item 14
 2,       4,       1,       3,Item 15
 3,       1,       1,      12,Item 16
 3,       1,       1,      21,Item 17
 3,       1,       1,     666,Item 18
 3,       1,       2,       3,Item 19
 3,       1,       2,      22,Item 20
 3,       1,       2,       2,Item 21
 3,       2,       1,     211,Item 22
 3,       2,       1,      64,Item 23
 4,       1,       1,      61,Item 24
 4,       1,       1,      17,Item 25
 4,       1,       2,       2,Item 26
 4,       1,       2,       9,Item 27
 4,       1,       2,      85,Item 28
 5,       1,       1,      57,Item 29
Default message tree

Figure 4.82. Default message tree


In this example, we have a loop of lines defining an item to dispatch, where each line has the truck id for where the item is stored.

We could regroup this loop of lines by TruckId so that we can loop on all trucks and then loop inside each truck on all the items in that truck.

To do that we select the Regroup this Loop action on the loop, select the Group By value for Grouping type and set it to ' field[1] ' (as this is the XPath of the TruckId element).

Regroup this loop

Figure 4.83. Regroup this loop


We now have a loop on all trucks and a sub loop on all the items in the truck.

Sub loop

Figure 4.84. Sub loop


When we want to group by the loop using two fields for example (Code and Area) then we can use the concat() function, as shown below.

Using concat() function with CSV "Message In"

Figure 4.85. Using concat() function with CSV "Message In"


Note: When the "Message In" is of type CSV then we will need to use "field" value in the field of the group by and by using the [ ] characters we will filter the needed field, For example if we want the get the first and third positions fields we will use field[1] and field[3].

When the "Message In" is of type XML then we will use the field name, In this case it will be concat(Code,Area), as shown below.

Using concat() function with XML "Message In"

Figure 4.86. Using concat() function with XML "Message In"


We can even go further and decide to group by PalletId and PacketId, that would give us four nested loops, one for all trucks, the next one for all pallets in a truck, the next one for all packets in a pallet and the last one, for all items in a packet.

Regroup this loop of lines by TruckId, PalletId and PacketId

Figure 4.87. Regroup this loop of lines by TruckId, PalletId and PacketId