Message maps

You can use a message map to graphically transform, route, and enrich a message. You can use a message map to modify data in a database system. You can use drag actions to make connections, select transforms, and build logic to transform your message data without programming.

A message map is the IBM® Integration Bus implementation of a graphical data map. It is based on XML schema and XPath 2.0 standards, with additional support for JSON schema draft 4 and Swagger 2.0.

You can use a message map to achieve the transformation of a message without the need to write code, providing a visual image of the transformation, and simplifying its implementation and ongoing maintenance.

The message map can be in the same container as the Mapping node (such as an application), or it can be in a referenced shared library. If multiple solutions are likely to use the same message map, store the map in a shared library.

Input and output data to a message map

In IBM Integration Bus, the logical tree structure is the internal representation of a message. It is also known as the message assembly.

When a message arrives to IBM Integration Bus, a parser is called. Each parser is suited for a particular type of message, and is known as a message domain. A parser converts the bit stream of an input message to its internal format. The data structure that you define in a message map for an input or an output message is the IBM Integration Bus internal representation of the message.

To configure the input and the output to a message map, you define an input message assembly and one or more output message assemblies.
  • You can have 1 input to a message map.
  • You can have multiple outputs in a message map.

For more information, see Input and output messages to a message map.

Supported message domains

The following message domains are supported when you use message maps:
  • DFDL: You use this domain to manipulate general text or binary data streams including industry standards.
  • XMLNSC: You use this domain to manipulate XML documents.
  • SOAP: You use this domain to manipulate SOAP messages.
  • DataObject: You use this domain to manipulate data without a stream representation.
  • BLOB: You use this domain to manipulate messages with content that cannot be interpreted and subdivided into smaller sections of information.
  • JSON: You use this domain to manipulate JSON documents.
  • MRM: This domain is maintained for compatibility with earlier versions of IBM Integration Bus.

Message assembly components

You can configure a message map to include the following message assembly components:
Note: Other message assembly components, such as the Exception list tree, are passed on unchanged. They cannot be modified in a message map.

Message body

You define the message body by defining a message model in any of the following ways:
  • Define a message model by using a predefined message model.
  • Define a message model by using a user-provided message model.
  • Define a message model by adding user-defined elements

You can use message models for any messages that you want to include in a mapping. You can select the message model from your existing message models in your application, integration service, or library when you create a message map. The mapping facility supports message models that are provided in DFDL schema and XML schema files, REST API swagger 2.0 documents, JSON schema draft 4, or MRM message sets. For more information, see Input and output messages to a message map.

In a message map, input and output body objects are defined by reference to message models, which provide a definition of the message structure and type through the following components:
  • Simple elements and attributes, which define the type, range, and default values
  • Complex elements, which build the structure of the message
  • Repeating simple or complex elements
  • Other (embedded) messages

If your message model includes wildcards (xsd:any), you can use a Cast function to redefine these data elements to a global type or element from any message schema in your application. For more information, see Casting elements in a message map. You can also qualify your wildcards by adding dynamically user-defined elements.

Creating a message map

When you create a new message map, you can select the model that defines the input and output messages for that map. You can select data type defined models from XML, DFDL or JSON schema, or Message Sets. You can also select predefined messages for SOAP, JSON, or BLOB. Alternatively, when you implement an operation in a REST API project and you create a message map from within the subflow for that operation, you can choose to create the map with inputs and outputs for that REST API operation defined automatically, including the path and query parameters. To create the message map with input and outputs defined automatically, select Message map with the input and output for REST API operation operation_name in the Specify a new message map file dialog. For more information, see Creating a message map.

Editing a message map

You edit a message map in the Graphical Data Mapping editor. You can create, modify, or delete a message map.

The Graphical Data Mapping editor saves message maps as .map files.

For more information, see Editing message maps.

Mapping behavior

By default, any message assembly component that is not included in the message map is copied from input to output unchanged.

To modify a message assembly component, you add the header or folder to the input and output message assembly in the message map, and provide transformations.

To delete a message assembly component, you add the component to the input message assembly, but not the output message assembly in the message map.

To create a message assembly component, you add the component only to the output message assembly in the message map.

Mapping operations

You can use any of the following transforms to map graphically your data in the Graphical Data Mapping editor:
  • Core mapping transforms: You can use built-in structural and functional mapping operations to graphically construct the required message transformations to build the output message.
  • Custom transforms: You can use custom transformations to define specialized transformations in XPath 2.0, Java™, or ESQL functions.
  • XPath functions (fn:functionName): You can use XPath 1.0 and XPath 2.0 functions to transform data in a message map.
  • Database transforms:
    • You can use the Select transform to query one or more database tables, and retrieve data that you can use in the message map. You can use the data to set output element values, define conditions, or use as input to build other transforms conditions. Database tables can be set as extra outputs of a message map.
    • You can use a database routine transform to call a stored procedure from a database, and retrieve data that you can use in the message map. You can use the data to set output element values, define conditions, or use as input to build other transforms conditions.
      Note: For information about the support for stored procedures, see Support for stored procedures.
    • You can use the Insert transform to add one new row of data, or multiple rows of data, into a database table.
    • You can use the Update transform to modify a row of data, or multiple rows of data, in a database table.
    • You can use the Delete transform to delete a row of data, or multiple rows of data, in a database table.
  • Cast function: You can use the Cast function to cast schema types.

For more information, see Transforms (Mapping operations).

Local maps

You can use local maps as navigation aids. You view the map elements in a hierarchical way. Unlike submaps, local maps are not separate files and they are not reusable. They provide a way of breaking up a large map into nested groups of mapping elements and processing the complex elements of the whole message.

Deploying a message map

Message map files are deployed to the IBM Integration Bus run time environment to enable them to be run in a message flow.

When you build and deploy a BAR file for an integration solution, the message map files are automatically included.

When you deploy independent resources, the BAR file editor provides a resource category to allow message maps to be selected for deployment.

If your message map file is used by multiple solutions, you might store the map in a shared library. Shared libraries that are referenced by applications must be deployed with or before the applications that refer to them. You can deploy the shared libraries directly to the integration server before you deploy the applications. Alternatively, you can include the applications and shared libraries in a BAR file and deploy the BAR file. If you update the message map in a shared library, those changes are available automatically to all applications that refer to that shared library.