Message Image  

Migration to Integration Bus v10

 View Only
Tue July 14, 2020 09:46 AM

IBM Integration Bus (IIB) v10 was launched in March 2015 and continues to provide a universal, independent platform to integrate disparate systems. We’ve already written articles about what is new in this version, but we also want existing integration solutions to work seamlessly on the new version. This article explains the options you have when adopting IIB v10, and some additional capabilities you might choose to exploit to simplify your system while migrating.

Migration basics

There are 3 things to consider when migrating existing solutions to the new version: your source code, your existing servers, and your people (developers and operations staff) and their operating procedures. In v10, there are some changes worth reviewing before starting:

  • Changes for operator procedures
  • Changes to administration security

IIB v10 supports direct migration from Message Broker v7, v8 or Integration Bus v9 for both source code and servers (brokers, or integration nodes). Any existing applications can be imported into the development Toolkit and continue to be used, and existing compiled code (BAR files) can be deployed to new integration nodes without change. You can also convert existing integration nodes to the new version with a simple command.

IIB v10 also supports coexistence with all previous versions – it can be installed alongside them, and you can run a mixture of development toolkits and integration nodes at different versions.

It also supports migration of source code from WebSphere Enterprise Service Bus v8.5, continuing the work started in IIB v9; this is a larger technology change and the source code is converted into a new form during that process. In IIB v10 the conversion tool has been extended to support additional imports and exports, and the converter is updated frequently as new capabilities are added, without the need to wait for a fixpack to get the latest version.

The key point with any migration is to have a clear picture of what you want your system to look like eventually, and define steps to get you to that end state with appropriate steps to minimise risk.

Migrating your application code and developer environments

The simplest way to look at your application code is as a set of projects: applications, libraries, and independent projects such as message flows or message sets. However you may also include any scripts which build and package your code (if you have them), such as Ant files which run the mqsicreatebar or mqsipackagebar commands.

Importing those projects into the v10 Toolkit migrates the projects into v10 format. The amount of change this causes varies depending on your starting version, but it is generally true that once you start editing in v10, you cannot share that project with earlier versions. If you use the v10 Toolkit or a v10 mqsipackagebar/mqsicreatebar command to create a BAR file, that can only be deployed to v10 integration nodes.

One new feature in v10 is that every Toolkit gets a local integration node for testing. You can opt out of this, but you might find it helpful as it enables developers to be self-sufficient without needing additional systems to support unit testing.

So when you are looking to start developing using v10 capability, make sure that:

  • developers who work together on the same projects upgrade their environments at the same time
  • test integration nodes supporting those developers are upgraded before toolkits are upgraded
  • if you store source code in version control, take a new fork of the stream to use with v10

Read the knowledge centre for more details.

Migrating your servers (integration nodes)

When you want to upgrade existing integration nodes, you have two basic options:

  1. In-place migration: Take the existing server definition and convert its data to v10 format, and restart using v10 code
  2. Side-by-side migration: Build a new integration node with v10 code, and redeploy existing apps to the new node

In case (1) you have a simpler job for connecting applications, as the set of endpoints provided by the new system is exactly the same as before, but you have a larger set of changes to make at once. Note also that v10 integration nodes have a different administration interface (see below), so you’ll need to do some planning of how to manage the migrated node before changing it in production.

In case (2) you take smaller steps towards your end goal, but you may need some work to redirect application traffic to the new node, using an HTTP load balancer or whatever other technology is appropriate. See migration in the Knowledge Centre for more information on these options.

Before v10, there was a restriction that every new integration node needed its own queue manager, specified when the node was created with -q. In v10 this restriction has been lifted; you can share a queue manager between multiple v10 nodes, or share a queue manager between a v10 node and a previous version node. This can help reduce the amount of application redirecting required during side-by-side migration.

In v10, there is also a new option of building a node without an associated queue manager, for all platforms apart from z/OS. This can also simplify your new configuration, but there are some restrictions about what type of integration solutions can run on a node configured this way. Check product documentation for details, but the summary is:

  1. If you want globally coordinated transactions, you require a default queue manager
  2. If you want to use certain nodes which store state (e.g. Aggregation, Collector) then you require a default queue manager
  3. If you want to use HTTP or SOAP nodes with a node-wide HTTP listener, you require a default queue manager
  4. If you want to use Publication nodes or use IIB as an MQ content-filtering provider, you require a default queue manager

The Knowledge Centre contains details of the capabilities that require WebSphere MQ.

You can choose to change or remove the default queue manager after migration, so you don’t have to decide up front what you want. Again, this flexibility is new in v10.

If you have highly-available integration nodes from v9 or earlier, these are typically built using either:

  1. WebSphere MQ active-passive queue managers, or
  2. External HA managers such as Microsoft Cluster Server

When migrating these, you have similar options, but note that you need to take a short period of downtime to upgrade an existing pair to a new version while its state is changed.

Changes for operators

A significant change in v10 for operators and administrators is that v10 nodes are no longer administered via MQ – remote administration is now done over an http (or https) port, and local administration is also via on-box system inter-process communication.

For operators wanting an administration console, this is now provided exclusively via a web application, rather than the previous Eclipse-based extension to WebSphere MQ Explorer. The Web interface, introduced in MBv8, has been significantly extended to allow deployment and resource definition.

If you have command-line scripts, the existing command interfaces are all still present, but have changed their parameters slightly if you are administering remote integration nodes – you now need to specify a host/port for the remote integration node’s http admin listener, not the MQ port.

Java administrative APIs have changed their behaviour slightly – the classes used to make a remote connection have changed (existing class deprecated, and a new class added to permit the new-style connection parameters to be provided).

Changes to administration security

If you have administration security enabled in previous versions, you may need to do some additional work on migration – and you should certainly read about the new concepts before migrating. The main effect is on administration requests sent to remote integration nodes.

If administration security was enabled in previous versions, the identity for an incoming request was obtained from:

  1. The on-box user ID, for a Java or command-line application on the same machine as the node
  2. The remote-box user ID, for a Java or command-line admin app connecting from a remote machine
  3. A user/password combination provided via http basic-auth, for REST and Web requests

In v10, option (2) is no longer used. So to enable any remote administration with security enabled, users must be defined to the integration node with the mqsiwebuseradmin command, and that user/password needs to be provided when the administrative command is issued. For on-box administration, mqsiwebuseradmin is not required.

If you are migrating an existing integration node, you will have to define additional user IDs to enable remote administration to continue after migration. The mqsimigratecomponents command will not do this for you.

If you have a queue manager associated with your integration node, authorisation for administrative tasks is done in the same way as previous versions. So when migrating in-place, any existing queue permissions are still used. If you build a new node without an associated queue manager, there is a new command to define authorisations, mqsichangefileauth – this is used instead of the MQ command setmqaut.

You can further protect remote administrative communication with https using TLS – this supercedes previous guidance about encrypting your MQ administrative channels. Given that http basic-auth is used to send users and passwords, use of TLS is strongly recommended unless you are on trusted network.


If you have an existing Integration Bus configuration, you can quickly and easily migrate what you have to v10 – either by upgrading your existing system in-place, or by building another parallel system alongside. You then have some options on how much new capability you want to exploit.