Introduction

In this blog post, I will explain the importance of the Message Implementation Guideline (MIG) in the Integration Advisor (IA). I will also explain the importance of enriching a MIG with as much semantic information as possible. There are numerous ways to impart this semantic knowledge into a MIG, and one of the most important ways is using qualifiers. In this blog post I attempt to de-mystify the concept of qualifiers and illustrate how it later simplifies and speeds up the mapping process.

If you first wish to find out more information on what a MIG actually is and how to create one, I would recommend to read the blog post Integration Advisor: Create a customized interface using the MIG editor. If you are completely new to Integration Advisor and wish to have an overall understanding of the product I would recommend to start with the blog post titled integration content advisor: Overview of components and further reading. From this blog post you will be able to access many other blogs and read them in a logical sequence.

 

The importance of rich semantics in a Message Implementation Guideline

One of the major paradigm shifts that Integration Advisor introduces is the move away from mapping exercises being the realm of the Technical Developer. The goal of Integration Advisor is to empower you, the Business Domain expert to perform the design and implementation end-2-end with little or no aid from a technical person.

In order to achieve this goal, there is a shift in importance away from the actual mapping, the Mapping Guideline (MAG), and towards the message definitions themselves, the MIGs. The ultimate goal is to make the MIGs so enriched semantically that the mapping process becomes a simple one-2-one drag-and-drop mechanism from source to target. Enriching the MIGs semantically allows the documentation that can be generated to be clear and concise, but also makes the mappings much simpler. Simplification of the mappings reduces or eliminates the need for complex technical functions and therefore the need for Technical Developers.

 

Qualifiers – what are they?

Many message types across the different standards that have been developed in the world (e.g. ASC X12, UN/EDIFACT, SAP IDOCs) are designed to be flexible, configurable and handle different business situations or contexts all within the same message structure.

In order to achieve this flexibility, a common approach is to group logically related information into data segments and then use a so-called ‘qualifier’ field that gives business meaning to the rest of the data in that segment. A good example of this would be Address segments. An Address segment will generally contain a similar set of fields – Street, City, State or County, Postal Code, Country, etc. When transmitting information between trading partners, however, there may be more than one set of addresses to be sent, a delivery address, a contact address, a billing address, and so on. In these situations, you could utilise a common address segment structure and then use a qualifier field to specify which type of address is stored within a particular instance of the data segment.

An example of this is shown below using an SAP IDOC in XML format to illustrate the concept. In this case the example relates to the Partner Information segments within a Purchase Order IDOC. In each case the data segment is the same, however the highlighted fields PARVW indicates which type of partner is being provided (AG=Sold-To, LF=Vendor and WE is the Good Recipient). You will also note that for each segment instance, different fields are filled in.

While the use of qualifiers can make a data payload more compact and flexible, it does add challenges programmatically when you wish to interpret and transform this data structure into something else. Suddenly the complexity of your mapping increase significantly. If you step back for a second and consider – if, rather than having these so-called qualified segments (or nodes), your structure was instead a much flatter one where you had a segment called ‘SoldToPartner’, a separate segment called ‘BillToPartner’ and so on, your mapping logic would become so much easier. And imagine if this was the same for both the source and the target; suddenly you have a much simpler one-2-one mapping with no requirement to implement a function that checks the qualifier value in the source structure, and no requirement to implement a value mapping to the target qualifier value.

In addition to the above advantage, another opportunity for simplification appears. As illustrated above, with these flexible configurable ’multi-purpose’ data segments you will always find a super-set of fields. These are there in order to attempt to cater for the multiple business purposes that the data segment is designed to accommodate. Take a ‘ContactInformation’ segment as a classic example. In such a segment you will most likely find not only the address details, but also the name of the contact, and numerous fields for tele-communication mediums (Home phone, Telefax, Mobile, Work phone, email); and to top it off other fields such as Gender and Date of birth may also be present. Depending on the business context, many of the fields will not be required, but also, importantly many may be mandatory depending on the semantics. Imagine again you could ‘flatten’ out this multi-purpose segment and have individual segments representing the different contexts. And each of these could be specialised to show only the fields that may be needed as well as which ones are mandatory for that business context.

This is exactly what the MIG Editor of Integration Advisor provides; through the concept of qualified nodes, Integration Advisor provides you with the ability to semantically shorten and ‘flatten out’ these structures. For each qualified structure you can specify which type it is, and the sub-set of fields it uses. In addition, you can then further tailor the structures by restricting allowed values on fields, indicating which are mandatory, changing field lengths, etc.

The diagram above illustrates this concept. I have used the MIG editor of Integration Advisor to create a Message Implementation Guideline based on an ORDERS.ORDERS05 IDOC. In this portion of the definition you will notice several key points:

• Both E1EDK03 and E1EDKA1 are repeated, and against each instance a qualifier value has been specified. This is indicated by the blue arrows and the numeric or alphabetical values in blue.
• As these are now represented as separate structural instances you have total freedom to select and deselect fields and segment within them to meet the precise business requirements for that segment
• To aid the business analyst or functional consultant in performing the task of MIG creation, the business meaning of each field or segment is specified, in addition to the technical name.
• To further enhance the semantics, the meaning of the qualifiers are also added in order to enrich the readability of the MIG.

 

So how do I add qualifiers to segments?

Adding qualifiers is easy and intuitive. In the example below, I have started the creation of a new MIG (this time based on an ORDERS message type from the UN/EDIFACT Type System).

You will notice in the Constraint column that there are some arrows. The starting point of the arrow indicates the field that can be used as a qualifier, and the end-points indicates which nodes can be qualified (and these can be segments or fields).

You will also notice that in the Codelist column there is a tick to indicate that these fields have code-lists assigned. This is one of the key pre-requisites for a qualifier field. When creating a qualified node, you can then choose the qualifier value from that Codelist.

To create a qualified node, you first highlight the field you wish to qualify so that the row turns blue:

You can then right-click to open the context menu. From this menu you select the Qualify Node… option:

A dialog box opens and from this you can now select your qualifier value. As you can see in the example, some codelists can be extremely long (74 pages in this case), so there is a Search option available that speeds up the process of finding the correct value. If necessary, you can also use the paging option to locate the required value.

Once you click the Add button, a qualified node is created.

In order to create additional Qualified nodes, simply highlight and right-click on the node again and you will see 2 options in the context menu.

The Duplicate Qualified Node option allows you to create another qualified node, while the Delete Qualified Instance(s) option allows you to delete either the currently selected qualified node, or All qualified nodes of this type.

Can I create my own qualifiers?

The simple answer is yes. For fields that have standard codelists assigned (as can be seen highlighted in blue below) you can simply select the field and in the Details tab click the Add button to add one or more fields to qualify.

A dialog box opens, and you can select the node you wish to qualify. If you want to qualify more than one, simply press the Add button again.

The appropriate constraint arrow is added:

 

Can I use my own Codelists?

In many situations there may be fields where no standard codelists are delivered as part of the Type System definition.

There may be other situations where there is a standard codelist, but your customer or trading partner has decided to use their own set of values instead.

For these situations, Integration Advisor provides the capability to create local codelists within your MIG Definition. You can assign these to the fields of your choice and then use these fields as qualifiers.

To create a local codelist, select the Local Codelists tab and then click on the Add button.

In terms of naming convention for the Id, there is no official convention, but my recommendation is to use the name of the field you will assign the codelist to, and add Local as either a prefix or a suffix. So, if the field is called 4439 for example, name the codelist either Local_4439 or 4439_Local.

This makes it clear which field the codelist is designed for and that it is a local codelist.

Add an appropriate Name and Definition and then click on the CodeValues label to start adding values:

In the lower pane on the screen, switch to the Code Values tab and add your values:

NOTE: There is also an option to upload the values from a CSV file. This is useful when you have a large number of values, or already maintain the codelist values in a spreadsheet or CSV file.

Once you have completed the creation of your Local Codelist you can assign this to the required field(s):

In this example we have overridden the standard codelist with our own…

NOTE: Rather than creating local codelists, you can also use codelists from some of the other Type Systems

When you now choose to use this field as your qualifier, the values from your local codelist will be available for qualification purposes:

So why are qualifiers so cool?

The benefit of using qualifiers speaks for itself as soon as you look at your mapping. Below is an example portion of a MAG where MIGs with qualifiers are used on both sides.

Rather than having to use Node functions as you would have to do in a ‘traditional’ mapping editor it now becomes a simple one-2-one mapping.

The screenshot does not illustrate it, but under each qualified segment, the source-to-target field mappings again are simple one-2-one maps.

 

So that is why Qualifiers are so cool…

Summary

Integration Advisor is a rapidly evolving product with new features being added on a regular basis. As an example, we will soon be introducing the capability to qualify nodes based on more than one qualifier simultaneously. This will enrich the capabilities even further.

Please re-visit our blog posts on a regular basis for news on any changes and enhancements.

Further Reading

Read the following blog posts for more information:

Overview of Integration Advisor:  Integration content advisor: Overview of components and further reading

Creating MIGs using the MIG Editor: Integration Advisor: Create a custom interface using the MIG Editor

Creating a MAG using the MAG Editor: Integration content advisor: Create a mapping using MAG editor