Migrating a message flow

Before you start:

Read the concept topic about conditions for a Version 5.0 broker participating in a Version 6.0 broker domain.

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, it is better to upgrade them to become namespace aware by following the steps in Making a message flow 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.

For more information about changes in this release, see What's new in Version 6.0?.

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 any existing message flow with the next flow that it finds of the same name without warning. Therefore be careful to avoid conflicts, and to ensure that the most recent version of a multiply-defined message flow is the last one to be migrated.

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 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 you have a workbench session 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. It is better to allow the command to create 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.

      If you want to rename any of these message flows or nodes after import to conform to your local naming conventions, use the facilities provided by the workbench 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, this 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.

      Start of changeWhen 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.0 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.End of change

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

  5. Check the report file mqsimigratemsgflows.report.txt that 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 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 by right-clicking the project and clicking Open Project.

    If the project is already open, right-click and click Refresh, then Rebuild Project to ensure that the Navigator 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 into the Version 6.0 workbench might create a model with different naming conventions than that 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, this 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 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 do this, 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. These 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