Deploying message maps

By default, message map files are deployed in BAR files as a part of an application, integration service, or library that provides an integration solution. You can also deploy a map as an independent resource if you are managing your message flows that way. If you change a message map, you must redeploy your integration solution or independent message flows.

About this task

When an integration solution or message flow containing a Mapping node is deployed, message maps that are referenced in the Mapping routine property of the Mapping node are resolved and validated. This preparation occurs at deployment time, rather than when the first message is flowed through the node.

This behavior has the following advantages:
  • There is no drop in performance from initializing a message map when the first message is flowed through the node.
  • The message map and its dependencies, such as any referenced message models, are resolved and validated during deployment to ensure that the message map runs successfully on first message.
  • The message map syntax is validated during deployment to ensure that the message map runs successfully on first message.
  • When IBM® App Connect Enterprise is restarted, the message map syntax and its dependencies are validated before the message flow can be restored.

To avoid a deployment failure, you must include all the message map dependencies, referenced schemas, ESQL modules, Java™ classes, and other resources in your BAR file. You must resolve any message map static errors such as an invalid XPath expression. If these requirements are not met, you receive a BIP message that reports the map generation failure.

By default, any map that is in the BAR file but not referenced in the Mapping routine property of the Mapping node is not validated on deployment. If the map is used dynamically by a Mapping node, by selecting it in a LocalEnvironment override (LocalEnvironment.Mapping.MappingRoutine = '{brokerSchemaName}:mapName'), it is validated and prepared when it is first used.

You can configure an integration node or server to validate and prepare all message maps on deployment, by setting the generateAllMapsOnDeploy property to true in the server.conf.yaml configuration file or on the mqsichangeproperties command. For example, to set the property for an integration node, you can use the following command:
mqsichangeproperties --integration-node integrationNodeName --property generateAllMapsOnDeploy --value true
To set the property for an integration server (either an independent integration server or a server that is managed by an integration node), you can set it in the server.conf.yaml configuration file:
generateAllMapsOnDeploy: true
The integration server must then be restarted for this change to take effect.

If you set the generateAllMapsOnDeploy property to true, ensure that all .map files in your application, library, and integration project are intended for use by a Mapping node that is in the BAR file. If any other .map files are found in the application, library, or integration project, they might cause deployment to fail.

Procedure

When you deploy message maps, the behavior of IBM App Connect Enterprise is as follows:

  • Behavior when you deploy or redeploy a BAR file:
    1. All message maps are validated to ensure that all the map dependencies can be resolved at run time. This validation step checks that the referenced message models such as XML schema files, DFDL schema files, and message set files, and the referenced submaps can be resolved.
    2. The message maps and their dependencies are generated to an executable form. This step also checks that the contents of the map and submaps are valid, and that they have no errors such as an invalid XPath expression.
    3. If the message maps and their dependencies are valid and can be successfully generated, they are persisted in both the deployed and generated forms to the configuration store. Otherwise, the deployment is stopped and you receive a BIP message that reports the map generation failure.
  • Behavior after deployment:
    1. Background processing is started to compile the generated message maps to Java byte code so that they can benefit from JIT optimization. The Java byte code for each map is persisted on completion of the compilation.
  • Behavior when the first message flows runs after deployment or redeployment:
    1. If the background compilation processing is complete, the Mapping node runs the java byte code and the JIT optimization starts.
    2. If the background compilation processing is not complete, the Mapping node runs the map initially in the generated form until the compilation is complete. Then, JIT optimization starts.
  • Behavior for any subsequent messages that flow after deployment or redeployment:
    1. The prepared message map runs. If the background processing is completed, the JIT optimization starts.
  • Behavior when you restart IBM App Connect Enterprise, that is, when you restart an integration node, an integration server, an integration solution, or a message flow:
    1. If the compiled Java byte code for the map is available, it is loaded and the Mapping node runs this code as soon as the first message is processed. Then, JIT optimization starts.
    2. If the generated form for the map is available and loaded, background processing is started to compile the generated map to Java byte code so that they can benefit from JIT optimization. The Java byte code for each map is persisted on completion of the compilation.
    3. If neither the generated or the compiled map code are available, the map is processed in the same way as when you deploy or redeploy a BAR file.