Migrating from WebSphere Message Broker Version 6.1 to IBM Integration Bus Version 10.0 on Windows systems

Perform these tasks to complete a Parallel Migration from WebSphere® Message Broker Version 6.1 to IBM® Integration Bus Version 10.0 on Windows systems.

Name changes in IBM Integration Bus Version 10.0

IBM Integration Bus is a compatible evolution of WebSphere Message Broker that has also been designed to incorporate the features that are in WebSphere Enterprise Service Bus.

An integration bus is a collection of integration nodes. An integration node can be an IBM Integration Bus integration node, for example, or a WebSphere Application Server node. This concept is reflected in the names of various resources; for example, the name of the default integration node in IBM Integration Bus Version 10.0 is IBNODE.

The following diagram illustrates the architecture of IBM Integration Bus Version 10.0.
This diagram shows the main components of IBM Integration Bus and how they interact.
The following table lists the resource names that have changed in IBM Integration Bus Version 9.0 and IBM Integration Bus Version 10.0
IBM Integration Bus terms WebSphere Message Broker terms
IBM Integration Toolkit WebSphere Message Broker Toolkit
IBM Integration Administration for WebSphere Application Server WebSphere Message Broker Administration for WebSphere Application Server
IBM Integration web user interface WebSphere Message Broker web user interface
Integration node Broker
Integration server Execution group
Integration service Service
Integration Bus component Broker component
IBM Integration API Message Broker API, or Message Broker Java™ API
Custom integration application CMP application

IBNODE (default integration node name in Version 10)

 MB8BROKER (default broker name)
Integration Development perspective Broker Application Development perspective
Application Development view Broker Development view
Integration Nodes view Brokers view
Integration project Message Broker project

What is Parallel Migration?

Completing a Parallel Migration means that you must run both the old brokers and the new integration nodes side by side until the migration is complete. The different installations do not even have to be on the same system or computer.

It is recommended that you migrate incrementally, for example, migrate a set of related flows in groups and then test them. Then repeat the process until all flows are migrated. Although there is no set way to group the flows that you migrate, they would typically be grouped because the flows have some relationship. For example, you might group the flows based on the nodes that are used per application.

When you use parallel migration, you have full control over which flows are migrated, and you can migrate without stopping your original brokers. You can also configure your clients to use the new integration nodes for connectivity to MQ, HTTP, and SOAP for example, while your original brokers are still running.

As each group of flows is migrated to the new integration node, we recommend that you stop the flow on the old broker node, and monitor it to ensure that no clients are still attempting to send messages to the old queue manager.

After all the flows are migrated to the new integration nodes, stop the old broker nodes. Although these old broker nodes can be deleted, we recommend that you keep this broker node until you are confident that the new integration node and flows have been running long enough to be sure that no new issues are encountered.

We also recommend that the old runtime is left in place even after the brokers are delete so that you can revert quickly if you need to.

Prerequisites

Review this important information. With each fixpack release, the requirements might change, so it would be confusing to put an outdated set of requirements in this document.

Before you begin

Remember to check the hardware requirements before you begin the migration process: IBM Integration Bus system requirements.

You must also read Preparing the system in the main product documentation, and complete the prerequisite tasks for your operating system before you install IBM Integration Bus Version 10.0.

IBM Integration Bus Version 10.0 does not include IBM Integration Explorer and so there is no migration process for WebSphere Message Broker Explorer. In IBM Integration Bus Version 10.0, all integration node administration is performed by using the web user interface, the IBM Integration API, or commands. For information about these administration options, see the following topics:

Check the new features from later versions

The new features of later versions of the product must be checked for compatibility. As you are migrating across several versions of the product, and multiple fixpacks, there are many changes that must be reviewed in case they affect your message flows.

Links to the What's New section of each version of the product documentation are in the following section, and they provide a brief overview of the changes. You must also check the fixpacks for each version:

Check the technical and behavioral changes from later versions

Although you are ultimately migrating to Version 10, there are technical and behavioral changes from one version of the product to the next, and because your migration path is spanning several versions of the product you need to ensure that you take any changes into consideration:

What about WebSphere MQ?

If your deployment uses functions that integrate with WebSphere MQ, or requires that the integration node has a specified queue manager, make sure that you have a supported version of WebSphere MQ. For information about IBM Integration Bus functions that require WebSphere MQ, see Installing WebSphere MQ in the main product documentation..
  • If you are reusing an existing WebSphere MQ deployment, migrate your queue managers and other resources to a supported version of WebSphere MQ by following the instructions that are provided in the WebSphere MQ product documentation.
    Note: If you are reusing an existing WebSphere MQ deployment, you can configure the new IBM Integration Bus Version 10.0 integration nodes to use the same queue managers as the existing integration nodes. You do not have to create new queue managers for the new integration nodes.
  • If you are installing a new WebSphere MQ deployment, create one or more queue managers to support the required configuration for your IBM Integration Bus Version 10.0 integration nodes.

Detailed System Requirements: Databases, compilers, drivers, and more

Review this important information. With each fixpack release, the requirements might change, so it would be confusing to put an outdated set of requirements in this document.

The latest requirements are always to be found in the fixpack documentation: http://www.ibm.com/support/docview.wss?rs=849&uid=swg27045108 The following sections contain specific links to the information for your platform.

Migrate to IBM Integration Bus Version 10.0

To migrate application logic from a broker on a distributed operating system to a different Version 10.0 integration node on the same computer, or on a different computer, complete the following steps:

Migrate steps

  1. Install IBM Integration Bus Version 10.0 on the same computer as your existing version, or on a different computer. If you are installing on the same computer, you must specify a different location.
  2. Before you migrate an integration node, create ODBC definitions for databases and specify appropriate database drivers for IBM Integration Bus Version 10.0: See Updating ODBC definitions when you migrate to IBM Integration Bus Version 10.0 in the next section of this document, and then return to these steps.
  3. Migrate your development resources to the IBM Integration Toolkit Version 10.0: See Migrating development resources to IBM Integration Bus Version 10.0 in a following section of this document, and then return to these steps.
  4. Set up the correct Version 10.0 command environment for Windows systems: See the Setting up a command environment section in a following section of this document, and then return to these steps.
  5. Create a Version 10.0 integration node by using the mqsicreatebroker command or the IBM Integration Toolkit. Give the integration node a name that is different from the name of the existing broker.
  6. If any of the resources on the existing broker require WebSphere MQ, specify an appropriately configured queue manager for the new integration node; see the previous section What about WebSphere MQ? or Installing WebSphere MQ in the main product documentation..
  7. Start the Version 10.0 integration node by using the mqsistart command. You can also start a local integration node by using the IBM Integration Toolkit.
  8. Create a list of the execution groups that you have on the existing broker, and recreate them as integration servers on the Version 10.0 integration node. Use the web user interface, the IBM Integration Toolkit Version 10.0, or the mqsicreateexecutiongroup command to complete this step.
  9. Deploy the message flows, applications, and libraries that are in use by the existing broker to the Version 10.0 integration node from the Version 10.0 IBM Integration Toolkit.
  10. Configure all other relevant properties from the existing broker on the Version 10.0 integration node.
  11. Test the new message flows, and migrate the next group of message flows. Repeat this process until you have migrated all your message flows.
  12. If you want to delete your existing broker, complete the following steps:
    1. In a command environment for your WebSphere Message Broker Version 6.1 installation, stop the original broker by using the mqsistop command.
    2. Remove the original broker from the WebSphere Message Broker Toolkit.
    3. In a command environment for your WebSphere Message Broker Version 6.1 installation, delete the original broker by using the mqsideletebroker command.

Updating ODBC definitions when you migrate to IBM Integration Bus Version 10.0

Before you migrate an integration node, create ODBC definitions for databases and specify appropriate database drivers for IBM Integration Bus Version 10.0.

The database drivers that are supported by IBM Integration Bus Version 10.0 might be at a later version than the drivers used by previous versions.

Complete this update before you run the mqsimigratecomponents command for the integration node that uses these ODBC connections.

Windows platform
Windows systems
Change the ODBC connection definitions:
  1. Open the ODBC Data Source Administrator window.
  2. Open the System DSN page.
  3. For each Oracle and Sybase database that is accessed by the integration node, compare the ODBC driver against the entries that are listed in the following table. If the ODBC driver does not match, you need to associate the data source name with the new ODBC driver by using the following instructions:
    1. Delete the data source by clicking Remove.
    2. Re-create the data source with the new ODBC driver by clicking Add.

    The following table displays the name of the new ODBC driver for each database management system (DBMS).

    DBMS IBM Integration Bus Version 10.0 ODBC driver name
    Oracle IBM Integration Bus DataDirect Technologies 64-BIT Oracle Wire Protocol
    Sybase IBM Integration Bus DataDirect Technologies 64-BIT Sybase Wire Protocol

Return to the Migration steps by clicking here: Migrate to IBM Integration Bus Version 10.0.

Migrating development resources to IBM Integration Bus Version 10.0

You cannot migrate the IBM Integration Toolkit or WebSphere Message Broker Toolkit from previous versions, but you can install IBM Integration Bus Version 10.0 to coexist with a previous version, and migrate the development resources to the IBM Integration Toolkit Version 10.0

Before you begin

Be aware of the following restrictions that apply after you migrate resources to IBM Integration Toolkit Version 10.0.
  • You cannot share the development resources with previous versions of the WebSphere Message Broker Toolkit or IBM Integration Toolkit. When you create a new project in IBM Integration Toolkit Version 10.0, it is created in a format that cannot be used in previous versions of the WebSphere Message Broker Toolkit or IBM Integration Toolkit. You can take the following steps to manage development with different versions of the WebSphere Message Broker Toolkit or IBM Integration Toolkit.
    • If you are using a version control system, create a new stream for use with the new version of your project.
    • If you expect to continue development of a project for an integration node at a version before Version 10.0, you must retain a WebSphere Message Broker Toolkit or IBM Integration Toolkit at the previous version.
    • If you need to continue development of the same project for integration nodes on both Version 10.0 and a previous version, ensure you use the WebSphere Message Broker Toolkit or IBM Integration Toolkit from the previous version for all your development.
  • You cannot deploy resources from IBM Integration Toolkit Version 10.0 to integration nodes at a previous version to Version 10.0.
  • If any of the following actions cause an error in the project, the IBM Integration Toolkit flags the error, and you can use a Quick Fix to rectify the error.
    • Creating the metadata information for the user-defined node project
    • Correcting the plug-in identifier if it does not match the project name
    • Ensuring all the user-defined nodes are in the same category
    For more information, see Applying a Quick Fix to a task list error in the main product documentation.. However, if you have different user-defined nodes that depend on different resources that have identical names, the BAR file compiler produces an error that indicates a naming conflict in the dependent resources.

You can continue to use resources from a previous version of WebSphere Message Broker or IBM Integration Bus by importing them into an IBM Integration Toolkit Version 10.0 workspace. After you import resources, you can no longer use them in a previous version of the WebSphere Message Broker Toolkit or IBM Integration Toolkit.

Message flow projects are replaced by integration projects in IBM Integration Bus Version 9.0 and later. When you import message flow projects into the IBM Integration Toolkit, they are converted automatically to integration projects. You cannot create a message flow project in IBM Integration Toolkit.

To migrate your projects by using a project interchange file, or to convert your message flow projects to integration projects, complete the steps in the following sections:

Importing resources from previous versions

You might have resources from previous versions of WebSphere Message Broker, such as Message Flow projects, Java projects, and message set projects, that you want to use in IBM Integration Bus Version 10.0. You can import these resources by using a project interchange file.

Message flow projects in WebSphere Message Broker Version 7.0 and Message Broker projects from WebSphere Message Broker Version 8.0 are replaced by integration projects in IBM Integration Bus Version 10.0. When you import Message Flow projects or Message Broker projects into IBM Integration Toolkit Version 10.0, they are converted automatically to integration projects. You can then use an imported project as the basis for a new application or library.

To import resources into IBM Integration Bus Version 10.0 by using a project interchange file, complete the following steps:
  1. In the previous version of WebSphere Message Broker Toolkit, export the resources that you want to use in IBM Integration Toolkit Version 10.0:
    1. Click File > Export. The Export wizard opens.
    2. Expand Other, click Project Interchange, then click Next.
    3. Select the projects that you want to export, and specify the location for the compressed file that is created. You can save the file to a folder on your file system, or to a disk drive.
    4. Click Finish. The project interchange file is created in the specified location.
  2. Create an IBM Integration Toolkit Version 10.0 workspace, or open an existing one.
  3. Import the project interchange file into the Version 10.0 workspace:
    1. Click File > Import. The Import wizard opens.
    2. Expand IBM Integration, click Project Interchange, then click Next.
    3. Specify the location of the project interchange file that you created in step 1.
    4. Specify the location of the open Version 10.0 workspace.
    5. Select the projects that you want to import into your Version 10.0 workspace, then click Finish.
You can choose to convert the imported projects to applications or libraries. For detailed instructions for how to convert your resources, see Converting existing projects to applications and libraries in the main product documentation..

Migrating message flow projects

When you import resources into an IBM Integration Toolkit Version 10.0 workspace, any message flow projects are converted automatically to integration projects. Ensure that you imported resources from a previous version of WebSphere Message Broker, as described in the previous section.

You cannot create a message flow project in IBM Integration Bus Version 10.0. You might want to continue to use message flow projects if you are working in a team environment, for example.

After your message flow projects are converted to integration projects, the message flows behave in the same way as before. However, if your message flow project contains schema, adapter components, WSDL files, IDL files, or SCA definitions, you might see errors after you migrate your project to IBM Integration Bus Version 10.0.

Quick fixes are available for these errors. These resources have no effect in a message flow project; you can include them in a Message flow project for reference only. But when you include the resources in an application or library, the resources become visible to other applications and libraries. This visibility can affect the resolution of those resources in the workspace. For example, a Message flow project might contain an XSD file that defines an element that is named element1, and a message set also contains an XSD file that defines an element that is named element1. In previous versions of WebSphere Message Broker, this duplication does not cause a problem because the element in the Message flow project is not used for name resolution. However, after migration to IBM Integration Bus Version 10.0, the presence of two elements that are named element1 causes an error.

An error is also displayed if you import a BAR file with resources from a previous version, and you then choose to refactor those resources to applications and libraries. If you try to recompile a BAR file after the resources are migrated to applications and libraries, you see an error message similar to the following example:
TotalPurchaseOrderFlow.msgflow belongs in an application or library and should 
be deployed within that container and not independently.
Create a new BAR file and select the application or library in the Prepare tab 
of the BAR editor, then select Build and Save.
To deploy the resource separately from the application or library, it must be 
moved into a Message Broker project.
Therefore, you cannot rebuild the BAR file but you can view the contents to see, for example, your original resources and how they were refactored.

Decide how you want to organize your migrated resources. Applications are typically used to contain all the resources that are required for a particular solution. Libraries are typically used to contain resources that you might want to reuse. So you might decide to store your main message flow in an application, and store your reusable resources in a library. For detailed instructions to convert your resources, see Converting existing projects to applications and libraries in the main product documentation..

What to do next

You can now view and modify existing resources, and create new resources. You can deploy your workspace resources to IBM Integration Bus Version 10.0 integration nodes.

You might want to reorganize your resources by using the containers provided in IBM Integration Bus Version 10.0. Applications are typically used to contain all the resources that are required for a particular solution. Libraries are typically used to contain resources that you might want to reuse. So you might decide to store your main message flow in an application, and store your reusable resources in a library. For instructions about converting your migrated resources to applications and libraries, see Converting existing projects to applications and libraries in the main product documentation..

Return to the Migration steps by clicking here: Migrate to IBM Integration Bus Version 10.0.

After you have migrated to IBM Integration Bus Version 10.0 on a Windows system

When you have completed the migration, these following tasks are optional steps that you might want to complete.

Setting up a command environment

Runtime components, and commands that administer runtime components, must be run from a command environment. This command environment is initialized by running the mqsiprofile command.

Before you begin

Check whether the following conditions apply to your environment:
  • If you have a previous version of IBM Integration Bus on this system, then ensure that you run the correct profile before you use Version 10.0. The mqsiprofile command places the Version 10.0 commands and libraries at the front of your search path, and can override any combination of PATH, CLASSPATH, or library PATH.
  • If you use the same user ID, and you run multiple profiles (from multiple different installations or versions), you might get unexpected results. Log off and log on again before you run the specific profile that you require.
  • You can check that your ODBC environment is configured correctly by running the mqsicvp command. This command also validates the connection to all data sources (listed in the odbc.ini file) that are associated with an integration node by using the mqsisetdbparms command. For more information, see mqsicvp command in the main product documentation..

Set up your command environment

The following steps explain how to initialize your command environment by running the mqsiprofile command.

If required, you can perform the following customizations before you run the mqsiprofile command:
  • Extend the initialization that is performed by this profile; for example, for databases, or for other products that you want to use within the integration node; see Running database setup scripts in the main product documentation..
  • Configure a different command environment for a specific integration node or integration server. If you want to run your own additional environment settings for an integration node or integration server, add command files to the following directories:
    • Windows platformOn Windows: Add one or more command files (with the file extension .cmd) to the following directories:
      • For an integration node:

        work_path\config\integrationNodeName\profiles

      • For an integration server:

        work_path\config\integrationNodeName\server_name\profiles

      where:
      work_path
      Specifies the machine-wide IBM Integration Bus working directory.
      integrationNodeName
      Specifies the name of your integration node.
      server_name
      Specifies the name of your integration server.
      Important: To verify the machine-wide IBM Integration Bus working directory, enter the following command in a command console:
      echo %MQSI_WORKPATH%
    • Ensure that the name of the integration nodes and integration servers contain only characters that are valid on your file system. You might also need to create the required directory structure.
    • To diagnose any problems, log files are written that list the profile scripts and the environment that is used by the integration node and the integration server. The log files are found in the following locations:
      • Windows platformOn Windows:
        • work_path\Common\log\integrationNodeName.profilelog (for the integration node)
        • work_path\Common\log\integrationNodeName\server_name.profilelog (for the integration server)
        Profile scripts are not removed automatically when an integration node or integration server is deleted. Therefore, if you created profile files for an integration node or integration server, you must delete these profile files manually if they are no longer required.
Ensure that you use the following environment each time you run an administrative command or start an integration node:
  • Windows platformOn Windows 7 and Windows 2008:
    • Open a command console by clicking Start > All Programs > IBM Integration Bus 10.0.0.n > IBM Integration Console 10.0.0.n.
  • Windows platformOn Windows 8 and Windows 2012:
    • Open a command console by searching for IBM Integration Console. If you have multiple installations of IBM Integration Bus, make sure that you are running the IBM Integration Console from the build of the IBM Integration Bus installation that you want to administer.

This command also runs any additional scripts that you copied to the common\profiles directory on Windows, so that the environment is initialized for runtime components and other resources such as databases.

What to do next

From the command line in the initialized environment, you can run commands to administer IBM Integration Bus.

You can return to the Migration steps by clicking here: Migrate to IBM Integration Bus Version 10.0.

Reconfiguring administration security after migration

After migration, you can reconfigure your administration security to use file-based permissions that are set on your integration nodes.

In previous versions of IBM Integration Bus and WebSphere Message Broker, you could only configure administration security by using queue-based permissions on WebSphere MQ queues. In IBM Integration Bus Version 10.0, you can also configure administration security by using file-based permissions on your integration nodes. If your IBM Integration Bus Version 10.0 environment does not include WebSphere MQ, and you want to configure administration security, then you must use file-based permissions. For more information, see Configuring administration security to use file-based, queue-based, or LDAP authorization in the main product documentation.

In previous versions of IBM Integration Bus and WebSphere Message Broker, you used IBM Integration Explorer, to administer IBM Integration Bus. In IBM Integration Bus Version 10.0, most of the administration tasks can be completed by using the web user interface. If administrators need to connect to remote integration nodes, you must define web users on the integration node and assign permissions. For more information, see the following topics:

Updating error processing routines

IBM Integration Bus Version 10.0 components generate diagnostic messages (BIP messages), and no longer generate others that were reported in previous versions. The text of some messages is updated to reflect change in behavior and function in later versions, although the meaning is retained. One message, BIP8663, is reused and has different content and meaning.

If you have applications that check for specific messages, you must update these routines. For example, you might have programs that automate error reporting, or identify the occurrence of specific error conditions. For the full list of messages, see Updating error processing routines in the main product documentation.

Migrating deployable resources

You can continue to use legacy resources in IBM Integration Bus. However, if you want to continue developing resources created in previous versions, you must migrate them.

Before you begin

  • Read the concept information about applications, libraries, and integration projects: Resource management overview in the main product documentation..
  • Read the concept information about subflows: Subflows in the main product documentation..
  • You can migrate message flow projects or integration projects by following the instructions in the Importing resources from previous versions section in this document.

Migrate your deployable resources

You can import message flow projects or integration projects into the Version 10.0 IBM Integration Toolkit to migrate your resources from earlier versions. These resources are converted automatically to integration projects. You can then use an imported project as the basis for a new application or library. Some of your migrated resources need further work before you can continue to develop them.
Note: Message flow projects were replaced by Message Broker projects in WebSphere Message Broker Version 8.0. Message Broker projects were renamed as integration projects in IBM Integration Bus Version 9.0.
The following list outlines the types of resource that require additional migration steps if you want to continue developing them in IBM Integration Bus. The links will open the relevant information in this section:
The following table summarizes the type of resource that you must migrate into IBM Integration Bus Version 10.0 if you want to continue developing them:
Table 1. Legacy resources that require additional migration tasks
To continue developing in IBM Integration Bus Version 10.0 Resource created in WebSphere Message Broker Version 6.1
Message sets You must enable the menus for message set development.
Message maps You must complete the migration of message maps to graphical data maps.
ESQL files You must complete the migration tasks.
Subflows You must complete the migration of subflows created as .msgflow files into .subflow files.

Migrating message sets

In WebSphere Message Broker Version 8.0 and later, message model schema files contained in applications, integration services, and libraries are the preferred way to model messages for most data formats. Message sets are required if you use the MRM or IDOC domains. For more information about message modeling, see Message modeling concepts.

You can import message flows containing message sets from previous versions into IBM Integration Bus Version 10.0. Your existing message sets can be viewed, modified, and deployed in the usual way. However, by default, the menu options for creating new message sets or message definition files are hidden. To perform these tasks, you must first enable message set development in the IBM Integration Toolkit Preferences.

For more information, see Enabling message set development in the main product documentation..

Migrating message maps

IBM Integration Bus Version 10.0 includes a graphical data mapping capability, which is used when you add a Mapping node to a message flow.

You can import message flows containing the following nodes, which use message mapping, from WebSphere Message Broker Version 6.1 into IBM Integration Bus Version 10.0:
  • DataDelete
  • DataInsert
  • DataUpdate
  • Extract
  • Mapping
  • Warehouse

The message mapping (.msgmap) on these Version 6.1 nodes can be viewed, compiled into a BAR file, and deployed to run the same transformation logic that was used in Version 6.1. However, the Version 6.1 message mapping operations are accessible only in read-only mode and cannot be modified. If you want to modify the transformation logic of an imported message flow that used Version 6.1 message mapping operations, you must replace the node with a new Mapping node and build a new graphical data map file (.map).

For information about converting Version 6.1 message maps (.msgmap) to Version 10.0 graphical data maps (.map), see Converting a message map from a .msgmap file to a .map file in the main product documentation..

Migrating ESQL files

The required character set encoding for ESQL files that are used in IBM Integration Bus Version 10.0 is UTF-8. When a message flow project is migrated to an integration project, any ESQL files that the message flow project contains are read by using the character set encoding that was used in the previous version of WebSphere Message Broker, and are rewritten in UTF-8. When importing your message flow projects, note that the file encoding of the workspace and host operating system must match the file encoding with which the message flow projects were created.

Migrating subflows

Since WebSphere Message Broker Version 8, you create subflows as .subflow files.

Subflows from WebSphere Message Broker Version 6.1 were created as .msgflow files. You must convert them into .subflow files if you want to continue developing them in IBM Integration Bus Version 10.0. You convert these subflows by using the function Convert to subflow.

For more information on how to convert a legacy subflow into a .subflow file, see Converting between message flows and subflows in the main product documentation..

Migrating a flow that uses SSLv3

All message flows that use SSLv3 should be updated to use TLS. SSLv3 is disabled by default in IBM Integration Bus Version 10.0, because SSLv3 is no longer considered secure due to the POODLE vulnerability (see http://www.ibm.com/support/docview.wss?uid=swg21687678).

Flows that attempt to use SSLv3 report connection failures. For example:
  • BIP3544E: Failed to create an SSL connection to the remote host. Reason 'java.security.NoSuchAlgorithmException: SSLv3 SSLContext not available'.
  • BIP3135S: An exception occurred while starting the servlet engine connector. Exception text is HTTP Listener org.apache.catalina.LifecycleException: Failed to start component.
For each integration server that hosts message flows that use SSLv3, complete one of the following steps:
  • Update the message flows to use TLS.
    Note: You must update both sides of any communication to use TLS:
    • For any inbound communication to IBM Integration Bus, the sending application must also be updated.
    • For any outbound communication from IBM Integration Bus, the receiving application must also be updated.
  • It is strongly recommended that these changes are made to avoid the known security vulnerability in SSLv3. However, if it is not possible to use TLS communication between IBM Integration Bus and external applications, SSLv3 can be re-enabled by using the following commands:
    • Re-enable SSLv3 support for an integration node (applies to all of its integration servers):
      mqsichangeproperties Int_Node -o BrokerRegistry -n allowSSLv3 -v true
    • Re-enable SSLv3 support for a specific integration server (enter on one line):
      mqsichangeproperties Int_Node -e Int_Server -o ComIbmJVMManager -n 
allowSSLv3 -v true
    where Int_Node is the name of the integration node and Int_Server is the name of the integration server.

Migrating a flow that contains JMS nodes

When you migrate a message flow from WebSphere Message Broker Version 6.1 that contains JMS nodes, you might have to update the value of the Transaction mode property.

In IBM Integration Bus Version 10.0, the valid values for Transaction mode on the JMS nodes are Yes and No. In versions before WebSphere Message Broker Version 8.0, the valid values were Local, Global and None.

When you migrate a message flow that contains JMS nodes with the value of Transaction mode set to None, the value is automatically migrated to No.

When you migrate a message flow that contains JMS nodes with the value of Transaction mode set to Local or Global, a migration warning is shown that prompts you to change the value to Yes. If you require XA coordinated transactions, you must also select the message flow Coordinated Transaction property.

The migration warning is displayed until you change the value appropriately. The warning does not prevent deployment of message flows.

Migrating a flow that contains File nodes

If you migrate message flows that contain File nodes to IBM Integration Bus Version 10.0, ensure that your NFS server appropriately supports file locking.

If you use an NFS server, and have File nodes in different integration servers in IBM Integration Bus Version 10.0 that access the same directory on the NFS server, ensure that you are using NFS version 4 to correctly support file locking.

Migrating a flow that supports ?wsdl queries

If you want WSDL and XML Schema information to be made available for existing SOAPInput-SOAPReply flows that implement web services, you must explicitly set the SOAPInput node property Enable support for ?wsdl and redeploy the flow.

In the unlikely event you have implemented an HTTPInput-HTTPReply flow to support ?wsdl queries related to a SOAPInput-SOAPReply flow, you should now deprecate the HTTP flow. By sending ?wsdl requests directly to the endpoint exposed by the SOAPInput node, this capability will continue to work even if the internal WSDL deployment details change in the future.

If your HTTP flow and your SOAP flow are using the same listener (either the integration node listener or the same embedded listener), the HTTPInput URL will clash with the SOAPInput URL, and a warning is written to the event log. In this case the ?wsdl request is always serviced correctly, but web service requests could be sent to either the SOAPInput or the HTTPInput node.

Migrating custom integration (CMP) applications

If you have applications that use the IBM Integration API, check that they access the correct resources.

Custom integration applications that you develop in Version 10.0 can connect to your existing WebSphere Message Broker Version 6.1 integration nodes, and your existing WebSphere Message Broker Version 6.1 custom integration applications can connect to Version 10.0 integration nodes.

  1. Update your custom integration applications to use the IntegrationAPI.jar file that is included in IBM Integration Bus Version 10.0. The IntegrationAPI.jar file replaces the ConfigManagerProxy.jar file that is used in versions before Version 10.0. Existing custom integration applications must be rebuilt to use the IntegrationAPI.jar file, and the IntegrationAPI.jar file must be included in the class path for the applications. For stand-alone applications, the IntegrationAPI.jar file must be supplied with the application.

    You do not have to change the methods that the application uses; the Version 10.0 IBM Integration API includes all deprecated classes and takes appropriate action.

  2. For custom integration applications that connect to an integration node, update the connection details that are used by your custom integration applications to connect to the appropriate integration node.

    In IBM Integration Bus Version 10.0, the IBM Integration API connections are no longer dependent on WebSphere MQ, and so connections are no longer made by using WebSphere MQ queues.

  3. If you are connecting to a remote integration node, update your connection details to use the web administration port; see Configuring the IBM Integration Bus web user interface in the main product documentation.. For information about using SSL on these connections, see Connecting to a remote integration node in the main product documentation..
  4. If administration security is enabled, in IBM Integration Bus Version 10.0, user credentials are required for integration applications that use a remote connection. If the connection is local, you must run the application under a user ID that is part of the mqbkrs group. For new integration applications, you can provide user details during application development by using the IBM Integration API IntegrationNodeConnectionParameters class. For existing compiled applications, you must supply the security credentials by using one of the methods that is described in Connecting to an integration node from a custom integration application in the main product documentation..

Migrating an application that contains an SAP adapter connection project

If you migrate an application or library that contains an SAP adapter connection project from WebSphere Message Broker Version 6.1 to IBM Integration Bus Version 10.0, you must replace the 32-bit version of the SAP libraries with the 64-bit version of the SAP libraries.

IBM Integration Bus Version 10.0 is only available on 64-bit platforms. If you migrate an application that contains an SAP adapter connection project, and the project uses 32-bit libraries, then you must reconfigure the project to use 64-bit libraries.
Note: The 32-bit libraries and the 64-bit libraries have the same file names. If you perform an iterative discovery on an SAP adapter connection project in IBM Integration Bus Version 10.0, and you get a com.ibm.adapter.framework.BaseException error, your project is using the 32-bit libraries.
The library file names are detailed in the following list:
  • sapjco3.jar
  • sapidoc3.jar
  • sapjco3.dll (Windows only)
  • libsapjco3.so (Linux® only)

You can configure your SAP adapter connection project to use the 64-bit libraries by using one of the following methods:

Table 2. Replacing the 32-bit libraries with the 64-bit libraries
Replacing the 32-bit libraries with the 64-bit libraries
To replace the 32-bit libraries with 64-bit libraries, complete the following steps:
  1. Stop the IBM Integration Toolkit.
  2. Navigate to the directory where the 32-bit SAP libraries are stored.
  3. Replace the 32-bit SAP libraries with the 64-bit SAP libraries.
  4. Restart the IBM Integration Toolkit.
Your SAP adapter connection project is using the 64-bit libraries.
Table 3. Updating the Java build path to use the 64-bit libraries
Updating the Java build path to use the 64-bit libraries
To update the Java build path for the SAP connection, complete the following steps:
  1. In the IBM Integration Toolkit, navigate to the application or library that contains the SAP adapter connection project.
  2. Expand Other Resources and right-click the SAP adapter connection project; for example, CWYAP_SAPAdapter_Tx.
  3. Click Properties > Java Build Path and click the Libraries tab.
  4. Select sapidoc3.jar, click Edit, navigate to the location of the 64-bit version of sapidoc3.jar, and click Open.
  5. Select sapjco3.jar, click Edit, navigate to the location of the 64-bit version of sapjco3.jar, and click Open.
  6. Click OK to close the Properties dialog.
Your SAP adapter connection project is using the 64-bit libraries.

Resolving problems that occur when migrating or importing resources

Use the advice given here to help you to resolve common problems that can occur when you import or migrate resources.

Migration information is regularly updated on the IBM Integration Bus support web page with the latest details available. Click Troubleshoot, then look for a document with a title like "Problems with Migration on Windows", although that title might change in future versions after this document is updated.

Resolving problems when migrating or importing message flows

Use the advice given here to help you to resolve common problems that can occur when you import or migrate message flows.

Table 4. Message flows that refer to a migrated user-defined node have connection errors
Message flows that refer to a migrated user-defined node have connection errors
  • Scenario: After migration, all message flows that refer to a migrated user-defined node have errors indicating that connections cannot be made.
  • Explanation: One possible cause is that the original user-defined node had space characters as part of one or more terminal names. The spaces are wrongly rendered as 'X20'.
  • Solution: Edit the user-defined node .msgnode file, which is available in the same project as the flows that you have migrated. Correct any terminal names that are at fault. Ensure that the names are exactly as the message flow node implementation expects.
Table 5. After migration, message flows cannot locate a user-defined node
After migration, message flows cannot locate a user-defined node
  • Scenario: After migration, message flows cannot locate a user-defined node.
  • Explanation: One possible cause is that the flows do not have the correct reference internally to a user-defined node.
  • Solution: Select the Locate subflow menu for the node that cannot be located. Using the Browse dialog box, locate the user-defined node (which is in the same project as migrated flows). The message flow now links to the user-defined node correctly and the task list entry is removed when you save the flow.

Resolving problems when migrating or importing message models

Use the advice here to help you to resolve common problems that can occur when you import or migrate message models.

Table 6. New instances of error message CTDV1534E
New instances of error message CTDV1534E
  • Scenario: A DFDL schema that was created by a version of IBM Integration Bus earlier than Version 10.0 is validated in the toolkit or during deployment. Extra instances of CTDV1534E are issued.
  • Explanation: The IBM implementation of DFDL added a validation check to comply with the DFDL 1.0 specification. The DFDL property 'length' of an element must not exceed the capacity of the element's simple type. This check was being made for DFDL 'lengthUnits' = 'bits', it is now also being made for 'lengthUnits' = 'bytes'. The addition of this check can cause extra instances of CTDV1534E.
  • Solution: Change the element's simple type so that it can cope with the length. For example, a two's complement binary number has DFDL 'length' = '8' and type is xs:int. Change the type to xs:long to clear the error.
Table 7. New instances of error messages CTDV1561E, CTDV1560E, CTDV1431E
New instances of error messages CTDV1561E, CTDV1560E, CTDV1431E
  • Scenario: A DFDL schema that was created by a version of IBM Integration Bus earlier than Version 10.0 is validated in the toolkit or during deployment. Extra instances of CTDV1561E, CTDV1560E, CTDV1431E are issued.
  • Explanation: The IBM implementation of DFDL added validation checks to comply with the DFDL 1.0 specification. Checks need to be made on elements and groups when DFDL property 'initiatedContent' = 'yes' on the parent sequence or choice. Some of these checks were missing, and have now been added. The addition of these checks can cause extra instances of CTDV1561E, CTDV1560E, or CTDV1431E.
  • Solution: Set 'initiatedContent' = 'no' on the parent sequence or choice. If a new error CTDV1559E then appears, contact your IBM Support Center for further advice.
Table 8. New instances of error messages CTDV1150E, CTDV1118E, CTDV1432E, CTDV1446E, CTDV1466E, CTDV1467E
New instances of error messages CTDV1150E, CTDV1118E, CTDV1432E, CTDV1446E, CTDV1466E, CTDV1467E
  • Scenario: A DFDL schema that was created by a version of IBM Integration Bus earlier than Version 10.0 is validated in the toolkit or during deployment. Extra instances of CTDV1150E, CTDV1118E, CTDV1432E, CTDV1446E, CTDV1466E, CTDV1467E are issued.
  • Explanation: The IBM implementation of DFDL added validation checks to comply with the DFDL 1.0 specification. Cross-checks need to be made between DFDL properties of elements and groups and DFDL properties on the parent sequence or choice. Some of these checks were missing when the parent sequence or choice was the content of a global group and DFDL properties were placed on group references to the group. These checks have now been added. The addition of these checks can cause extra instances of CTDV1150E, CTDV1118E, CTDV1432E, CTDV1446E, CTDV1466E, or CTDV1467E.
  • Solution: Correct the schema in accordance with the indicated error.
Table 9. New instances of error message CTDV1625E
New instances of error message CTDV1625E
  • Scenario: A DFDL schema,that was created by a version of IBM Integration Bus earlier than Version 10.0 is validated in the toolkit or during deployment. Extra instances of CTDV1625E are issued.
  • Explanation: The IBM implementation of DFDL added validation checks to comply with the DFDL 1.0 specification. When the DFDL property 'occursCountKind' of an element is 'parsed' and the parent sequence has a separator, the DFDL property 'separatorSuppressionPolicy' of the parent sequence must be 'anyEmpty'. This new check is the result of a specification erratum.
  • Solution: Correct the sequence so DFDL 'separatorSuppressionPolicy' is 'anyEmpty', or change the element so DFDL 'occursCountKind' is 'implicit'.
Table 10. New instances of error message CTDV1458E
New instances of error message CTDV1458E
  • Scenario: A DFDL schema,that was created by a version of IBM Integration Bus earlier than Version 10.0 is validated in the toolkit or during deployment. Extra instances of CTDV1458E are issued.
  • Explanation: The IBM implementation of DFDL has added validation checks to comply with the DFDL 1.0 specification. The DFDL property 'fillByte' must resolve to a single byte value. This check was not being made correctly when 'fillByte' contained DFDL entities such as %r00;. The corrected check can cause extra instances of CTDV1458E.
  • Solution: Correct the 'fillByte' to use a single DFDL entity that resolves to a single byte value.
Table 11. COBOL compiler errors when importing a copybook
COBOL compiler errors when importing a copybook
  • Scenario: The report file that is generated by the import contains COBOL compiler errors. For example, you try to import the following copybook:

    01 AIRLINE-REQUEST. ....05 CUSTOMER. ........10 NAME................PIC X(45). ....05 ADDRESS. ........10 STREET.............PIC X(30). ........10 CITY.................PIC X(25). ........10 STATE...............PIC X(20). ........10 ZIP-CODE.........PIC X(5). ....05 FLIGHT-NO............PIC X(6). ....05 TRAN-DATE...........PIC X(10). ....05 COST....................PIC X(7). ....05 CC-NO..................PIC X(20). ....05 RESPONSE. ........10 STATUS.............PIC X(100). ........10 DETAILS............PIC X(100).

    The report file contains errors:
    Line No : 4 IGYDS1089-S "ADDRESS" was invalid. Scanning was resumed at the 
next area "A" item, level-number, or the start of the next clause.
Line No : 14 IGYDS1089-S "STATUS" was invalid. Scanning was resumed at the 
next area "A" item, level-number, or the start of the next clause.
  • Explanation: The errors are caused by the copybook containing field names that are COBOL reserved keywords.
  • Solution: Change the name of the fields in question, so that they are not COBOL reserved keywords, and retry the import.

Resolving problems when migrating or importing other resources

Use the advice given here to help you to resolve common problems that can arise when you import or migrate resources other than message flows.

Table 12. You see an error message when you recompile a BAR file from a previous version
You see an error message when you recompile a BAR file from a previous version
  • Scenario: You have imported a BAR file with your resources from a previous version, and you then choose to refactor those resources to applications and libraries. You try to recompile a BAR file after the resources have been migrated to applications and libraries, but you see an error message similar to the following example:
    TotalPurchaseOrderFlow.msgflow belongs in an application or library and 
should be deployed within that container and not independently.
Create a new BAR file and select the application or library in the 
Prepare tab of the BAR editor, then select Build and Save.
To deploy the resource separately from the application or library, 
it must be moved into a Message Broker project.
  • Explanation: If you have reorganized your imported resources into applications and libraries, you cannot rebuild the original BAR file. If a message flow from your original BAR file has been moved into an application in IBM Integration Bus, you must deploy the flow with the new container, or move it to an integration project, from which you can deploy it separately.
  • Solution: Create a new BAR file and add the application or library that contains the resources that you want to deploy. To deploy a resource like a message flow on its own, move the flow to an integration project, then deploy the flow separately.
Table 13. The File > Import menu provides only the option to import a compressed file inside an existing project
The File > Import menu provides only the option to import a compressed file inside an existing project
  • Scenario: You have a compressed file that contains message set projects and message flow projects. When you click File > Import, you have only the option to import the compressed file inside an existing project, but you want to re-create the message set projects and message flow projects.
  • Solution: When you export and import files, do not export or import the root directory, which is created for you because of the project file. When you export your message flow and message set projects:
    1. Click Create only selected directories.
    2. Clear the project root folder.
    3. Select the files and subdirectories as required. The project root folder is selected, but is displayed as gray.
    Then, when you import the compressed file:
    1. Clear the root (/) folder.
    2. Select the files and subfolders as required. The project root folder is selected, but is displayed as gray.

More migration resources

Use these links for more migration information and troubleshooting.

Links to more migration resources