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® App Connect Enterprise 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.

Procedure

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.
    For more information, see Setting the value of an output element by using 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.
    For more information, see Referencing message maps in your solution.
  • You can diagnose and solve problems that you encounter when you use a message map.
    For more information, see Troubleshooting a message map.
  • IBM App Connect Enterprise does not support WebSphere® Message Broker Version 7.0 legacy message maps (.msgmap). You can import message flows that contain legacy message maps into the IBM App Connect Enterprise Toolkit. However, you can view these message flows in read-only mode only, and you cannot deploy and run them. If you try to deploy a BAR file that contains a legacy message map, you see a BIP2355 error message. Before you run a message flow that contains a legacy message map or a legacy Mapping node, you must convert them by following the instructions in Using or converting legacy resources into message maps.
  • You can use the Graphical Data Mapping editor to access a user-defined policy.
    For more information, see Accessing a user-defined policy from a graphical data map