Perform these tasks to complete a Parallel Migration from WebSphere® Message Broker Version 6.1 to IBM® Integration Bus Version 10.0 on Linux and UNIX systems.
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.
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 |
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.
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.
Remember
to check the hardware requirements before you begin the migration
process: http://www.ibm.com/software/integration/wbimessagebroker/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.
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.
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.
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:
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.
In the XAResourceManager stanza for each Oracle and Sybase database that participates in a global unit of work that is coordinated by the integration node queue manager, change the entry for the switch file. For changes to the switch file configuration to take effect, you must restart the integration node queue manager.
The following table specifies the entries that you must change for each operating system and database management system (DBMS).
DBMS | Original entry | New entry |
---|---|---|
Oracle | SwitchFile=UKor8dtc22.so or SwitchFile=UKoradtc22.soor SwitchFile=UKor8dtc23.soor SwitchFile=UKoradtc23.soor SwitchFile=UKoradtc24.soor SwitchFile=UKoradtc26.so |
SwitchFile=UKoradtc95.so |
Sybase (not supported on Linux on IBM z Systems) | SwitchFile=UKasedtc22.so or SwitchFile=UKasedtc23.soor SwitchFile=UKasedtc24.soor SwitchFile=UKoradtc26.so |
SwitchFile=UKasedtc95.so |
To check that your ODBC environment is set up correctly on Linux and UNIX systems, run the mqsicvp command. This command also validates the connection to all data sources that are 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..
Return to the Migration steps by clicking here: Migrate 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
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:
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.
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.
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..
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.
When you have completed the migration, these following tasks are optional steps that you might want to complete.
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
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.
. /opt/mqm/setmqenv -s -x 64
Because
the setmqenv is not persistent, you can create
an IBM Integration Bus common profile to run
this command in either of the following ways:work_path/config/integrationNodeName/profiles
work_path/config/integrationNodeName/server_name/profiles
echo %MQSI_WORKPATH%
. install_dir/server/bin/mqsiprofile
You must include the period and space characters for this command to work correctly. Add this command to your login profile if you want it to be run at the start of every session.
If you use the zsh shell, then running the mqsiprofile might cause the terminal session to exit. To resolve this issue, run the unsetopt function_argzero command before you run the mqsiprofile command.
This command also runs any additional scripts that you copied to the common/profiles directory on Linux or UNIX systems, 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.
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 or queue-based authorization in the main product documentation.
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.
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.
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. |
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..
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.
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..
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.
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..
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).
mqsichangeproperties Int_Node -o BrokerRegistry -n allowSSLv3 -v true
mqsichangeproperties Int_Node -e Int_Server -o ComIbmJVMManager -n
allowSSLv3 -v true
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.
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.
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.
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.
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.
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.
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.
You can configure your SAP adapter connection project to use the 64-bit libraries by using one of the following methods:
Replacing the 32-bit libraries with the 64-bit libraries |
---|
To replace the 32-bit libraries with 64-bit libraries, complete
the following steps:
|
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:
|
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 UNIX and Linux", although that title might change after
this document is updated.
Use the advice given here to help you to resolve common problems that can occur when you import or migrate message flows.
Message flows that refer to a migrated user-defined node have connection errors |
---|
|
After migration, message flows cannot locate a user-defined node |
---|
|
Use the advice here to help you to resolve common problems that can occur when you import or migrate message models.
New instances of error message CTDV1534E |
---|
|
New instances of error messages CTDV1561E, CTDV1560E, CTDV1431E |
---|
|
New instances of error messages CTDV1150E, CTDV1118E, CTDV1432E, CTDV1446E, CTDV1466E, CTDV1467E |
---|
|
New instances of error message CTDV1625E |
---|
|
New instances of error message CTDV1458E |
---|
|
COBOL compiler errors when importing a copybook |
---|
|
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.
You see an error message when you recompile a BAR file from a previous version |
---|
|
The | menu provides only the option to import a compressed file inside an existing project
---|
|
Use these links for more migration information and troubleshooting.