4.3.3. 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.
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.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.
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, ...).
General parameters are:
|
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. |
|
|
The description allows you to save some more documentation about this node. |
|
|
The name identifies the element in the xml representing the messages. Change only with care, for example XML language doesn't accept spaces. |
|
|
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. |
|
|
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.
The following validations are available:
|
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 of the data in the field (String, Number, Date, ...). This field will also affect the other validations that will be available. |
|
|
Min or Max length (in characters) for the value. |
|
|
Regular expression that the value must match. |
|
|
Indicates that the number value must be between the two given limits. |
|
|
Format that are accepted, like 'yyyy/MM/dd', ... Full description of accepted formats can be found at that link, Multiple allowed formats can be entered, separated by a comma. |
|
|
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:
|
This element will always appear in the output file whether or not it's filled or not. |
|
|
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: Example of element that will NOT appear in the output: |
|
|
If all sub-elements decided to appear in the output file Example of element that will appear in the output: Example of element that will NOT appear in the output: |
|
|
(applies only to element without children) Will appear in the output file if it has a value. |
On the top of the left panel, a search bar allows you to easily find nodes in big documents.
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.
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.
Note:
- The managing choice is deprecated and it is not recommended to be used any more in the new transformation created because the new transformation don't support it and any mapping which is under a "Choice" and "Option" will be filtered out.
- This is kept in the message definition tree "Message In" and "Message Out" for backward compatibility where it is used and working properly for old mapping because this is supported by the old transformation mapping.
- The "Choice" and "Option" will be generated when the user generate the message definition tree from the XSD file.
- If the user did any change in the old transformation mapping and when the click the save button the old transformation mapping will be migrated to the new transformation mapping which don't support the managing choice.
- When the user open/save a transformation a notification will pop-up only if the transformation is implemented using the old transformation mapping so the user will know if this transformation is affected by this or not.
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:
There are two Choice nodes, one for the Code information, that accepts either a company code or the company GLN value. The other Choice node is for the name of an company.
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).
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:
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.
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
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).
We now have a loop on all trucks and a sub loop on all the items in the truck.
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.
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].
XML Group-by example:
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.
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.