4.1.5. Metadata – Babelway

When users think about a message processed in Babelway, they usually first think about the content of the message, typically a xml/csv/pdf/... file.

But to process your message, you may need access to additional info, that are not stored in the content of the message itself. For example, you could need to access the date and time when the message was received, information about the sender of the message, the name of the file in which the content was stored, ...

Babelway gives you access to all of these information through metadata. Metadata are all the information that are associated with the message, in addition to its content.

There are 2 types of metadata :

System metadata are automatically made available to you by Babelway, like when the message was received, from which sender, in which file name, ... The complete list of system metadata can be found here.
User metadata allows you to store any information at any step of the message processing, and access it again later.

How to access metadata

Inside the mapping tool, you access easily any metadata using the metadata function.

For system metadata, you only need to know the name of the metadata. Available metadata are listed here.

For user metadata, just use the name that you have chosen when you have defined the metadata.

You should just be aware that this metadata function will always return a textual representation of the data stored in the metadata. In some cases, users store binary files into the metadata, and accessing it like a text will result in a conversion that will damage the file. In that case, you should use the function metadataBinary, that will return your binary data untouched.

You can also access metadata from most of the fields in the application. For example, in the below screenshot, we have used metadata to configure an email Gateway OUT, to include the message reference, the file name, the receive timestamp, ... inside the subject and the body of the email, or to return the email to the sender of the original file. See fields highlighted in blue.

You can type the metadata name, enclosed by brackets, directly in the fields, or use the + icon at the right of the field (highlighted in yellow), to be able to select your metadata in a more user-friendly list.

How to define metadata

In huge majority of the cases, metadata are defined during the transformation step, by defining them in the dedicated section (on top of the output tree), and defining the value using formulas, like for any other field.

Using the function setMetadata is also possible. This method stores the metadata as requested, then return its value. This behavior can make this function also very helpful to debug complex formulas, by storing an intermediate result into a metadata, and for example check the value in the context Out.

If you need to define metadata at another step, it is also possible through some extra processings. But this usage is often more complex, and reserved to advanced users.

For example, in the below example, a formula was used to access the messageType very soon in the process (still during the gateway IN step). This can for example be used later in a routing. The formula that was used is :

bbw:xmlToXmlNode(bbw:metadata('com_babelway_messaging_context_message'))//*:Header/@messageType

Message reference

Message reference is a system metadata. You can access it like any other system metadata, through the key com_babelway_messaging_context_message_reference. But it has the specificity that you can change this value.

You can do this easily in the mapping tool, where Message reference is always available in the User defined metadatas zone (on top of the output message).

Unless you use this message later in the processing, defining this message reference will not change the processing of your messages. But it can be very interesting because this is a searchable field in the MessageList. By setting there a good reference (like the invoice number), you will be able to find it back very easily in all of your messages.

User Metadata transfer strategy

For the processing of some complex messages, it can happen that the message goes successively through multiple channels. In this case, user metadata are often used to calculate some information in a prior channel (ex: the first channel), and then to access it whenever needed (ex: in second and third channel).

Doing that is perfectly legitimate, but you need to be aware that user metadata are not necessarily transferred from one channel to the next one. This is controlled by a parameter User metadata transfer strategy that will be present on all gateways OUT that send to another channel. You should check this parameter to have the expected behavior. Sometimes, you could want to transfer all the properties from one channel to the next one. Sometime, you could want that none is transferred, to avoid any interference.