A submap is a reusable graphical data map. Graphical data maps, known as message maps in IBM Integration Bus or WebSphere Message Broker, offer the ability to achieve the transformation of a message without the need to write code, providing a visual image of the transformation, simplifying its implementation and ongoing maintenance.
In IBM Integration Bus, a Mapping node invokes a message map. You can configure in a map the message map that is invoked, or you can configure Local Environment.>Mapping>MappingRoutine property to define the mapping routine that is invoked dynamically by the Mapping node. This top level map will define the source and target Message Assembly that the Mapping node will receive and propagate as a result of executing the map.
Within the map, as discussed in How to design a graphical data map for IBM Integration Bus you should be looking to structure the map into nested mappings that deal with parts of the data transformation.
Reuse transform logic via Submaps
In a map, you can use the Local map transform to provide this nesting to contain the detailed mapping of a section of your data. However, often the same source and target data elements that you map will re-occur within the same overall transformation or between different transformations throughout your business processes. This is the key usage for submaps in Graphical Data Mapping. This reuse might not be apparent during the initial map development, however provided you have followed the approach of using nesting to provide a good structure to your map, that is not an issue. The Graphical Data Map editor provides a “refactor to submap” action which enables the nested mapping of a Local map to be relocated to a new separate .map file and the main map to be updated to have a Submap transform configured to reference this new submap.
The editor’s refactoring also supports you in moving transforms into a new Local map. Say you had mapped the children of a complex type source and target element so that they were not nested in a Local map, and later you identified as a common transformation that could be reused. If you add a connection from the source to target a nested mapping transform, such as Local map or For each will be created. This will then cause the existing transforms of the child elements to show errors because the structure is mapped both at the parent folder and child elements. However a quick fix action is provided to relocate the transform inside the new parent container mapping. Once this is done you are then ready to refactor to a submap.
The Graphical Data Mapper is also used in other IBM products, such as IBM Integration Designer and IBM Master Data Management. You can look to extend the reuse of common transformations via submaps across these products.
For example, in IBM Integration Bus, the Mapping node is dealing with a Message Assembly at the top level map, which is unique to IBM Integration Bus maps. However provided that you avoid using product specific features in the submap, cross product reuse is achievable.
Using Submps
In general, submaps can be utilised where the input and output are defined by a global schema element or type. The IBM Integration Toolkit will validate that the schema type of the Submap transform input and output match the input and output of the referenced submap.
Note: When you are transforming text and binary data defined by an IBM Data Format Description Language (DFDL) message model, the structures will typically be modeled as local elements. However the DFDL editor provides a simple context menu action to “make a local element global” when you click at the left hand of the required element in the DFDL editor.
However that there are two key aspects where variation in the type matching between main and submap can be exploited.
- Invoke a typed submap from a wildcard in the main map.
The schema “xsd:any” wildcard allows the data model to declare an unspecified structure. Classic examples of the usage of this is in the SOAP message Body.
In a Graphical Data Map you can wire a Submap transform from and to xsd:any. The submap can then define the particular schema type of the data in order to implement the transformation.
You might use this when running a SOAP gateway type service in which conditional If transforms could be used to invoke a particular submap .
- Mapping derived or extension types
The Graphical Data Map allows you to pass the base schema type to a submap which is build to transform a particular derived type from that base.
Multi-Input Submps
Another key feature of submaps that is often overlooked is that you can implement submaps with multtiple inputs wired to the Submap transform. This can be useful in a number of use cases including
- Passing additional “context” data required to process a particular complex data type. A typical example could be when processing an invoice structure you might need to pass in an additional values for the currency and exchange rate
- Achieving reusable mapping of data folders with identical child fields which do not have a common ancestor schema type that can be used as the submap source or target type.
Note this situation can arise when mapping text or binary data modeled via DFDL v1.0 since it does not allow complex type inheritance.
Note: Prior to the availability of APAR IBM IT08394 which allows you to add inputs from within a submap, to create a multi-input submap, you must adopt a top down approach, that is, from the top map, connect multiple inputs to the Submap transform. If you use a bottom up approach, you use the wizard to create a submap, and the submap wizard only allows you to select a single input.Then,once inside the editor you are not allowed to add more inputs.
To create a multiple input submap, you can start in the main map creating a transform between one of the source leaf elements and the target. Then add additional inputs by dragging from the next leaf element and dropping on the transform and adding it as “primary input” when prompted. Once all the connections have been made, change the transform type to Submap. Now use the “New” button on the properties page to create the .map file for this submap. This internally populates the new submap dialog with the multiple input selections, which you can’t do otherwise. Alternatively in the latest releases you can create a new submap with a single input and then use the add input action in the editor.
Note that since the new submap dialog orders the selection dialog alphabetically, the inputs to the submap get created in this order. Depending on the order you connected inputs to the Submap transform in the main map, they might not match this alphabetical ordering, in which case you have to use the “Order” properties page of the Submap transform in the main map to match the actual submap and avoid parameter type matching issues.
Summary
In this post I’ve covered some key aspects to consider with regards exploiting submaps in your Graphical Data Mapping solutions. Look out for future posts in which we will cover many more aspects around exploiting the full capability of graphical mapping. Also please let me know what topics you’d like to see.