Using message maps

You can use a message map to graphically transform an input message into a required output message; to enrich the output message with data from a database; to dynamically set routing or destination control for the output message; and 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.

About this task

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.

A message map offers the ability to achieve the transformation of a message without the need to write code. It provides a visual image of the transformation, and simplifies its implementation and ongoing maintenance.

You can use a message map to adopt any of the following integration requirements graphically:
  • Transform a message: You can use a message map to graphically transform a message assembly, message body, and properties, according to the transforms and XPath functions defined in the message map. You can use the full set of XPath 2.0 expressions and functions to implement data calculations and manipulations in a message map. To define the input and output messages to a map, you can use a schema base message model, which defines the structure of the data and provides information about the data type, or you can define it dynamically in the map by using the Add user defined function.
  • Enrich a message with data available in an external database: You can use a message map to enrich, or conditionally set the output message with data from a database table. The table data structure must be defined to the message map, and an SQL where clause can be used to select specific rows. The resulting row data is presented as an extra input in the message map, according to the database schema.
  • Modify data located in an external database.
  • Route a message based on content: You can use a message map to graphically route a message. You can modify the local environment tree to set a dynamic message destination.


Read the following sections to learn how to design, create, configure, and troubleshoot a message map and its associated resources:

  • Graphical data maps offer the ability to achieve the transformation of a message without the need to write code. Depending on the data transformation re-usability and manageability requirements, you can use a message map, a submap, or a local map. For more information, see Graphical Mapping overview.
  • You can create a graphical data map, a message map, or a submap to transform a message.
    For more information, see Creating message maps.
  • You can edit a message map by using the Graphical Data Mapping editor.
    For more information, see Editing message maps.
  • You can use the Graphical Data Mapping editor to set the value of an output element by using an expression, a transform, or a function.
  • You can reference a message map during the development phase. You can also reference a message map dynamically at run time.
  • You can diagnose and solve problems that you encounter when you use a message map.
    For more information, see Troubleshooting a message map.
  • You can compile and deploy a legacy message map in IBM Integration Bus. However, to modify the legacy message map, you must first convert the legacy message map to a message map.