Migrating a message flow

Before you start:

Read about differences between Version 2.1 and Version 6.0 products.

You can migrate the message flows that you have created in your Version 2.1 product (WebSphere MQ Event Broker, WebSphere MQ Integrator Broker, or WebSphere MQ Integrator) and use them in WebSphere Message Broker Version 6.0.

If you are migrating from WebSphere MQ Event Broker Version 2.1, all information in this topic that refers to user-defined plug-ins and ESQL does not apply; these facilities are not available on WebSphere MQ Event Broker Version 2.1.

If you have migrated from WebSphere MQ Integrator Broker Version 2.1, you might have written message flows that handle XML messages that use XML namespaces. In Version 2.1, such XML messages are parsed in a different way to that used by WebSphere Message Broker Version 6.0. While such message flows will continue to work correctly when hosted by Version 6.0, upgrade them to make them namespace aware.

You might want to change the message flows that you migrate to take advantage of the new nodes and features that are available in Version 6.0. For example, you might want to replace a user-defined node that receives web services requests with the built-in HTTPInput node.

You can migrate more than one message flow at one time if you want them to be defined in the same message flow project. You must migrate subflows and user-defined nodes with the message flows in which they are included to ensure consistent references.

If you have defined more than one message flow with the same name, or the message flow has been exported into more than one export file, the migration task overwrites, without warning, any existing message flow with the next flow that it finds of the same name. Therefore, be careful to avoid conflicts, and to ensure that the most recent version of a message flow that has been defined more than once is the last one that you migrate.

If you have multiple versions of the same message flow, which you use as a subflow in other flows in the same migration directory, the results of the import process are unpredictable.

To migrate a message flow:

  1. Before you uninstall Version 2.1, export the message flow or flows from the Control Center using the Version 2.1 tools (see the Version 2.1 documentation for detailed information).

    The migration process is most efficient when all referenced subflows are included in the same export file, therefore export all message flows that you want to migrate to a single message flow project into a single export file.

  2. Transfer the export file or files to the new system on which you are running the workbench.
    • Check that the directory in which you store these files does not contain any other files.
    • Store the files that you intend to import into a single message flow project in a separate directory and migrate each directory separately.
    • Make sure that you do not store any files in subdirectories of the project directory, because these files are ignored by the migrate command.
  3. If a workbench session is active, close it. You cannot run the migrate command if the workbench is running.
  4. At a command prompt, invoke the mqsimigratemsgflows command, specifying the new project name and the directory in which you stored the export files. When the command has completed:
    • The message flows that are contained in the export files in the specified directory are imported into the specified message flow project. If the project already exists, the additional message flows are included with current content, if any. If the project does not exist before you invoke the command, it is created for you. The command is more effective if it creates the message flow project for you.
    • Message flows and subflows are created and their definitions are stored in files named flow_name.msgflow. User-defined nodes are created and their definitions are stored in files named node_name.msgnode.

      After you have imported them, if you want to rename any of these message flows or nodes to conform to your local naming conventions, use only the facilities that are provided by the workbench, in order to preserve consistency and integrity of all references. Do not rename any files within the file system.

    • If any of the nodes in the message flows contain ESQL, the code is extracted from the node itself and stored in the ESQL file message_flow_name.esql. The ESQL for each node is wrapped between the appropriate CREATE and END MODULE statements (for Compute, Database, or Filter). The command creates the ESQL file if it does not already exist.

      When you add a message flow to a bar file, runtime ESQL code is generated at Version 6.0 level. This code is incompatible with Version 2.1 brokers. If you want the bar file to include Version 2.1 runtime ESQL, check the Compile ESQL for brokers version 2.1 box. If you do so, you cannot include Version 6.0 enhancements in the ESQL code, but you can deploy the flows to both Version 2.1 and Version 6.0 brokers.

      For more information, see Adding files to a broker archive.

  5. Check the report file mqsimigratemsgflows.report.txt, which is written to the directory from which you invoked the command. The command provides the following information:
    • The name of each message flow, subflow, and user-defined node that has been migrated. If any of these resources had a name that is incompatible with Version 6.0, the command updates the name and all references to that name to ensure consistency. (If you migrate a resource with an invalid name more than once, the correction that is made to the name is always the same.)
    • The success or failure of each resource that is migrated.
    • An indication of a subflow that cannot be located (its definition is not contained in any of the export files, but it is included in one or more of the migrated message flows). If this problem occurs, find the missing subflow and import it into the appropriate project. If you cannot retrieve the missing subflow for any reason, re-create it with the original name. All affected flows can then link correctly to the new subflow.

      You do not need to repeat the whole export and import process.

    • An indication that a resource that was migrated as a message flow and stored in a .msgflow file might be a user-defined node. If this warning occurs, check if the specified resource is a user-defined node or a message flow. If it is a message flow, it has been migrated correctly. If it is a user-defined node, complete the actions outlined in step 11.
  6. Start the workbench and switch to the Broker Application Development perspective.
  7. Open the message flow project that was created or updated by the migrate command.

    If the project is already open, right-click it and click Refresh, then Rebuild Project to ensure that the Broker Development view reflects the new content. Rebuild also performs a validation of the message flow project contents.

    Because ESQL and mappings are handled in a different way in Version 6.0, the migration process replaces some of the Version 2.1 nodes with different Version 6.0 nodes. The following table lists the replaced nodes. The ESQL that is associated with each node is created as a module with a default name, and the node property is set to the name of that module.

    Version 2.1 node Version 6.0 node
    Compute Compute
    Filter Filter
    Database Database
    DataDelete Database
    DataInsert Database
    DataUpdate Database
    Extract Compute
    Warehouse Database
  8. If a message flow includes one or more Filter nodes, check the ESQL module for each node in the ESQL file to ensure that the RETURN statement correctly returns a valid expression that resolves to a Boolean value.
  9. If a message flow includes a node with ESQL, the ESQL references fields in a message derived from an imported C header, and you have re-created the message model by importing the C header into the workbench, check the ESQL statements that refer to this message. The import process into the Version 6.0 workbench might create a model with different naming conventions from those created by the Version 2.1 importer, and you might need to update one or more field references.
  10. If you had promoted the ESQL property of any of the Version 2.1 nodes that included ESQL customization to reuse ESQL in multiple nodes, the promotion is not maintained in the migrated Version 6.0 message flows because promotion of ESQL related properties is no longer supported. The Tasks view shows an error for each ESQL promoted property. To achieve the same effect, create an ESQL function and call that function from each node's ESQL module.
  11. If you have migrated a user-defined node, only the XML interface definition file is migrated into a node .msgnode file (this file defines only the terminals and properties of the node). Complete its migration and its definition manually in Version 6.0 of the product. The following steps provide an outline of the required process. For full details, see Creating the user interface representation of a user-defined node in the workbench.
    1. Create a user-defined node project and move the .msgnode file from the message flow project into the new user-defined node project. When you move this file, the associated properties files are created.
    2. Optional: Complete development of the user-defined node in the Eclipse environment to create the user-defined node Eclipse plug-in (the directory structure that contains the files that make up this node). This task includes creating node resources for help, icons, and property editors and compilers, if required.
    3. Check for errors in the task list. Errors might be generated, for example, if the node or its terminal names include the space character (not supported in Version 6.0), or if a flow embeds another migrated flow and the reference is not correct. Resolve these errors by correcting names, or by using the Locate subflow menu option.
    4. Install the runtime code for the node (the .lil file) on the appropriate broker systems. You do not need to recompile the code for your user-defined node when you migrate it.
    5. Stop and restart the broker to recognize the new or changed files.
When you have migrated your resources, see the Version 2.1 post-migration tasks for information about tasks that you might want to perform after migration.
Related concepts
Message flows overview
ESQL functions
Related tasks
Making a message flow namespace aware
Opening an existing message flow
Defining message flow content
Developing ESQL
Related reference
Broker Application Development perspective
ESQL editor
Built-in nodes
mqsimigratemsgflows command