Usage

Step palette

To access this plugin in the palette, click Middleware > Enterprise Service Bus > WebSphere Message Broker.

IBM Integration API JAR files

The IBM Integration Bus plugin requires access to several JAR files to utilize the IBM Integration API. The specific files needed and their location depends on IBM Integration Bus version that is being used.

• Version 9: the default location of is the java/lib directory in your WebSphere MQ installation directory.
• Version 10: the default location is the classes directory of your IIB server installation directory.

The location of the JAR files is specified on the Jar Path property on the following steps.

• Create Execution Group
• Create Or Update Configurable Service
• Delete Applications
• Delete BAR File Contents
• Delete Execution Group
• Deploy
• Override Bar Properties
• Restart Execution Groups
• Set Execution Group Properties
• Set Integration Node Properties
• Set Message Flows Properties
• Start Message Flows
• Stop Message Flows

On the Jar Path property specify either a directory to recursively search from which contains all required JAR files, or specify each individual JAR path split by your file systems path separator.

The following table list the JAR files required. Additional JAR files are required when connecting to an Integration Node remotely. A remote connection is made when you specify an IP and Port to connect to the broker.

Steps

The following process steps are available in the WebSphere Message Broker CMP plugin.

• Create Execution Group
• Create Integration Node
• Create Or Update Configurable Service
• Delete Applications
• Delete BAR File Contents
• Delete Configurable Service
• Delete Execution Group
• Delete Integration Node
• Deploy
• Does Execution Group Exist
• Override Bar Properties
• Restart Execution Groups
• Set Execution Group Properties
• Set Integration Node Properties
• Set Message Flows Properties
• Start Integration Node
• Start Message Flows
• Stop Integration Node
• Stop Message Flows

Create Execution Group

Create execution groups, but only if they do not exist.

Create Integration Node

Create an Integration Node (Broker). This command will create the WebSphere MQ queues required by the broker if they do not exist.

Create Or Update Configurable Service

Create a configurable service if it doesnt exist. If it does, update its properties.

Delete Applications

Delete an application or multiple applications deployed to an execution group
by name.

Delete BAR File Contents

Delete all contents that have been deployed using a BAR file name that matches the given regular expression. Useful for deploying into shared execution groups.

Delete Configurable Service

Delete a configurable service.

Delete Execution Group

Delete the specified execution group from the broker. This will also remove any resources used by the execution group.

Delete Integration Node

Delete an Integration Node (Broker).

Deploy

Deploy a Broker Archive. This step will set the output property completionCode, representing the last completion code returned from the broker during deployment.

Does Execution Group Exist

Sets an output property named exists with true or false based on the existence of the specified Execution Group.

Override Bar Properties

Overrides configuration properties inside a Broker Archive file. This step is not compatible with WebSphere Message Broker version 7.

Restart Execution Groups

Restart execution groups if they exist on the broker.

Set Execution Group Properties

Set runtime properties for an execution group.

Set Integration Node Properties

Set Runtime Properties for the Integration Node (broker).

Set Message Flows Properties

Sets runtime properties on a list of message flows.

Start Integration Node

Start an Integration Node (Broker).

Start Message Flows

Start Message Flows that are stopped.

Stop Integration Node

Stop an Integration Node (Broker).

Stop Message Flows

Stop Message Flows that are running.

Troubleshooting

You can use the IBM Integration API trace to troubleshoot issues with IBM Integration Bus. For additional information about the trace, see IBM Integration API trace.

Concepts Explained

Queue Managers

Queue managers handle queues that store messages until an application is ready to process them. IIB version 9 requires that an Integration Node is always associated with a Queue Manager, while IIB version 10 does not. The reason for this is that WebSphere MQ is no longer a prerequisite to run IBM Integration Bus beginning with version 10. This allows you to develop and deploy applications without WebSphere MQ, and instead directly in IIB. This distinction is evident in the plugin, where when connecting to a version 9 integration node you must first specify a queue manager, while with version 10 you may connect directly to the integration node.

A distinction must be made here relating to MQ Nodes. Multiple types of MQ Nodes exist, including MQInput and MQOutput nodes. An MQInput node can be used to receive messages stored on a queue of an MQ Queue Manager, while MQOutput nodes are used to send messages to a queue. So, when deploying message queues that are defined using MQ Nodes a Queue Manager is required.

Integration Nodes (Brokers)

Message flows define a series of steps to be run when an integration node receives a message. Integration nodes host message flows and route messages as defined in the message flow.

Integration Servers (Execution Groups)

Integration servers are groups of message flows managed by an integration node. The integration node makes sure that the message flows operate in separate address spaces when they are on separate integration servers.

Broker Archive Files

As the focus of this post pertains to integrating IIB with HCL Launch, the details behind BAR file creation will not be covered. However, the IBM knowledge center fully explains this concept in the Creating a BAR File page.

Note that the terms ‘integration node’ and ‘broker’ are used interchangeably, just as the terms ‘integration server’ and ‘execution group’ are interchangeable.

Use Case: Integrating IIB

After understanding the IIB concepts, some common use cases and plug-in steps for IIB integration with HCL Launch are demonstrated in this article.

1. Provisioning your environment

Sometimes, the most difficult part of automating deployment is determining the structure of your resource tree within HCL Launch. Determining an efficient scheme for what to treat as a resource or a component can save time and complexity.

A good recommendation is to follow the structure outlined within IIB. Note that if you aren’t using WebSphere MQ, it is not necessary to treat a Queue Manager as a resource. However, if you are, the IBM WebSphere MQ Explorer may be a good guide as to what resources need to be created.

As an alternative, you may employ the mqsilist command-line script located in your IIB’s installation directory to outline your resource tree. Running the mqsilist command by itself will list all integration nodes and the queue manager that they are associated with. You may list execution groups managed by a given broker by supplying the broker name as a command-line argument to the script (i.e. mqsilist brokerName). It may be necessary to run the mqsiprofile script first, which will export some necessary environment variables. See mqsilist command in the IBM Knowledge Center for more information on this command.

Generally, an IIB resource tree involves the queue manager at the top level (if one is being used), the integration nodes associated with the queue manager, the execution groups belonging to each broker, and then the BAR files that are to be deployed to each corresponding integration server.

As a disclaimer, when you decide to provision your resource tree, it is strongly recommended to have integration servers (execution groups) as their components. As an example, consider the following use case: A user has three execution groups in their IIB environment (EG1, EG2, and EG3). Each execution group belongs to the integration node (broker) named BRK1. They also have ten BAR files to deploy amongst these execution groups (BAR1 to EG1, BAR2 to EG2, BAR3 to EG3, BAR4 to EG1, BAR5 to EG2, BAR6 to EG3, etc…). However, before each deployment, the user must make some configuration changes to the execution group that is going to be deployed to, and then restart that execution group.

With each execution group as their separate component, we have three components within HCL Launch. Each of the execution group components has its component process to set the properties on the execution group and then restart that execution group. Also, we have ten components for each of our BAR files. These components exist under the execution group component to be deployed within the resource tree, so that they may access its properties. Each BAR file components have a component process to handle the deployment logic.

Now within the HCL Launch application, we can create an application process to run all of the execution groups component processes to set properties and restart. This logic may run in parallel using the Install Multiple Components step. After the execution groups are properly restarted, we can have a second application process to run all of the deployments in parallel.

Imagine if this user didn’t have components for their execution groups, and instead used properties on their BAR file components to determine which execution group that BAR file would be deployed to. There would be no way to execute any logic that is specific to the execution group itself. The user could add a component process to restart the execution group referenced by the property on their BAR file component and run all of those in parallel. However, this would mean that ten different components would run at the same time to restart potentially overlapping execution groups. The BAR1 component would begin execution to restart EG1, while at the same time the BAR4 component would begin restarting the very same execution group. Whichever process finishes first would succeed, and the subsequent process would fail during the middle of execution. These race conditions can be avoided easily by justifiably allocating a component for each execution group within your environment.

The idea behind provisioning your resources in such a way is so that properties from each of the resources can propagate downwards. So, when running a deployment using one of your BAR file components it has access to properties on the parent execution group, broker, and queue manager.

To save time you may choose to create some general components to represent each type of resource (queue manager, broker, and execution group) and configure each with properties that correspond to that resource in IIB.

We will specify the following resource properties on our resources. Note that you may specify any property names that you want. These are just the default values for the fields in the IIB plug-in. These properties will be referenced directly in the plug-in step fields of your component processes.

• iib.queueManager
• iib.brokerName
• iib.executionGroup

For demonstration purpose, these three components are created; MQ Queue Manager, IIB Broker, and IIB Execution Group. This way we can define the iib.queueManager property on the MQ Queue Manager component, the iib.brokerName property on the IIB Broker component, and the iib.executionGroup property on the IIB Execution Group component.

Now that we have our IIB Execution Group component in place if you want to add a new execution group named “NewEG” to your resource tree you may navigate to the Resources tab in the HCL Launch and add a new execution group component. The name that you specify to the newly added resource should be used as your iib.executionGroup resource property definition to keep all of your resources nicely organized by name.

The same procedure may be used to create your queue manager and integration node resources, with careful consideration for the resource tree hierarchy. The BAR files that we want to deploy will require a different strategy to model within HCL Launch. The strategy that was used to add our queue manager, execution group, and broker resources to the resource tree won’t be sufficient. Each BAR file needs its separate component in HCL Launch as each deployable BAR file will require its own set of component versions to be deployed.

The easiest way to go about creating BAR file components would be to employ a component template. This article employs a simple component template using the ‘File System’ source configuration type, directly supplying the path to the individual BAR file on the agent system.

This template can now be used to model all BAR files that will be used for deployment. Adding a component property to the template to refer to the name of the BAR file will allow us to dynamically resolve this name during runtime. See  Override BAR Properties and Deploy for configuring these component properties.

After all BAR files have been accounted for, the components may be added to the resource tree under the desired execution group resources (follow the guidelines for the resource tree that we determined earlier.)

Three additional resource properties that you will want to set are iib.mqsiprofile, iib.version, and iib.jarPath. Mentioned earlier in this post is the mqsiprofile executable script that exists in your IIB installation directory. This script is used to set some necessary environment variables to run the IIB command executables. The mqsiprofile script must also be run before using the IBM Integration API. For this reason, you will notice a field on all IIB plugin steps that use the IBM Integration API called MQSIPROFILE Executable. You can provide the path to your mqsiprofile in this field so that your command environment is properly configured, which is located by default in your IIB installation directory. Setting this location as a resource property will make it so that you don’t have to continually specify it on each step. For this example, set the iib.mqsiprofile property on the agent resource, which can be referenced in plug-in step fields as ${p:resource/iib.mqsiprofile}. The iib.version property is also necessary to determine the version of the IBM Integration API to use when running plug-in steps. This property may also be defined at the agent resource level.

For this example, set the JAR path property at the agent resource level. Another possible place for this property would be on the environment as it references a path specific to your IIB environment, like the iib.mqsiprofile property. For specific details as to what JAR files must be specified for your version of IIB, see IBM Integration API JAR Files.

2. Running Plugin Steps

Now that we have a proper resource tree, we can begin configuring steps to run using our resources. This article focuses on some of the most common steps in the IIB plugin. See a complete list of all supported steps of the IIB plug-in here. The commonly used steps that we are going to cover include Create Integration Node, Create Execution Group, Set Execution Group Properties, Override Bar Properties, and Deploy.

Before we begin, determine the scope of each step. To do this, determine the properties required during each step. We will do this for each step as we continue with this post.

The plug-in itself contains two different classifications of steps that can be run. There are those plug-in steps that act as command-line wrappers for the IBM Integration Bus commands. These steps execute the command scripts that exist within your IIB installation location under the bin directory.

When running steps that rely on the IBM Integration Bus commands you must specify your IIB installation directory. The field in the plugin step is labeled “IIB Installation Directory. These steps include:

• Create Integration Node
• Delete Integration Node
• Start Integration Node
• Stop Integration Node

IBM Integration API JAR Files

The other classification of plug-in steps relies on the Java IBM Integration API and does not require the installation directory to function. However, some other additional properties are required for each of these steps. With these plug-in steps, you specify the location of the IBM Integration API JAR files from your IIB server. The default location for these files differs based on the version of IIB. With IIB version 9, the default location of these files is within the java/lib directory in your WebSphere MQ installation directory. With version 9 of IIB, the default location of these files will be in the classes directory of your IIB server installation directory.

The JAR files required also differ based on the version of IIB. Here are the required JAR files that must be specified based on version:

Steps that require access to these JAR files to utilize the IBM Integration API include:

• Set Broker Properties
• Create Execution Group
• Restart Execution Groups
• Set Execution Group Properties
• Set Message Flow Properties
• Create Or Update Configurable Service
• Delete Configurable Service
• Deploy
• Start Message Flows
• Stop Message Flows
• Override Bar Properties

Create Integration Node

Note that this step makes use of the MQSI script files located in your IIB installation directory. For this case, create another resource property to specify the location of this directory. The location of this property is subject to your specific use case. The most likely location would be as a resource property on the agent resource, as we are specifying a directory on the agent itself within our IIB environment. There are a few other steps in the plug-in that use the MQSI scripts and rely on this property as well. These steps include Delete Integration Node, Start Integration Node, and Stop Integration Node as noted earlier.

If you are running IIB version 9, you must also specify the Service User ID and Service Password of the user that the new broker will run under. Earlier in this article, we’ve dramatically simplified things by creating a general component to represent our integration node. If you missed it, see the section Provisioning Your Environment.

Firstly, add a new operational component process to our general integration node component created earlier. The logic for this new process will handle the creation of the integration node.

After this component process is added to the generic IIB Broker component, the component can now be used to create all future integration nodes in your resource tree. Note that in the future, you may add new component processes to the generic component that will automatically be added to the broker components that you have created.

 

The remaining setup is simplified by the fact that we’ve set up all of the required properties to run the step on our resources. The final steps are to add your components to the application, create an application process, and add your resources to the environment within that application. Create an application and add the IIB Broker component to it.

Next, you will need an application process to execute the Create Integration Node component process. As the component process is created as an operational process, it does not require a version to be specified on the component when executing. Operational processes are located in the process designer under the folder of its component. Note that when this application process is executed it will run the step for each ‘IIB Broker’ component that has been added to your environment. If you only want to run specific execution groups in this environment you can tag those added components and specify the tag in the Limit to Resource Tag field. Another option is to only add the desired IIB Execution Group components to your environment.

Finally, create an environment within that application and add your resources to it. In this instance, the agent and all resources are added to the environment.

When your application is ready, you can run the application process in your environment from the Environments tab in the application.

Create Execution Group

The setup for the Create Execution Group step is similar to the above step. The difference is that you specify the path of your IBM Integration API JARs. For this example, set the JAR path at the top level of your resource tree, which in this case is the agent. Another place for this property would be on the environment as it is going to reference a path specific to your IIB environment.

After the jarPath property is configured, you can create a new operational component process on your ‘IIB Execution Group’ component to run the Create Execution Group step.

The remainder of the setup for this step involves adding the IIB Execution Group component to your application and environment and creating an application process to run the operational process. This part of the article is covered in the ‘Create Integration Node’ subsection of the Running Plugin Steps section of this article. Note that you will need to add a new ‘IIB Execution Group’ component to your specific ‘IIB Broker’ component.

Set Execution Group Properties

We won’t go into depth on the setup for this step as it is the same as the Create Execution Group step explained above. Instead, focus on how to determine which properties can be set on the execution group. The Integration Server HTTP Listener Properties page in the IBM Knowledge Center provides you with some insight and examples of what properties you may change on the execution group. However, your IIB installation provides a helpful executable that you can run in your IIB installation directory called mqsireportproperties that you can use to explore all properties on the execution group. Specify the broker the execution group exists under and the execution group name itself. See mqsireportproperties command in the IBM Knowledge Center for usage.

You can use the same executable to list all properties of a given object for that execution group.

In this case, all general properties are listed for the execution group. You may choose any of the objects to report the properties of, such as the HTTPConnector object. When you have discovered a property that you wish to change you may set its value in the Properties field of the step using the syntax ObjectName/PropertyName=Value. For instance, to change the maximum number of HTTP connections for the execution group at a given time to 128, specify HTTPConnector/maxThreads=128.

Note that not all properties are configurable, and the request to change a non-configurable property will result in a rejected response from the broker. See Changes to properties that are associated with integration servers that provide some examples as to what properties may be configured but it doesn’t cover all of them.

Override Bar Properties and Deploy

The Override Bar Properties step is executed before deployment to change configurable properties on a broker archive file. If you are looking to create a new BAR file for deployment, see mqsicreatebar command.

Customizable BAR file properties exist in the deployment descriptor of the BAR file in its META_INF/broker.xml configuration file. For a list of properties on your BAR file, you may use the mqsireadbar executable script located in your IIB installation directory. For details about using this command executable, see mqsireadbar command. The following is an example of reading the pager.bar sample BAR file provided with a successful IIB version 10 installation.

In this example, to change the queueName of the TEXTMESSENGER queue to MYMESSENGER, specify TextMessenger#TEXTMESSENGER.queueName=MYMESSENGER. The Override BAR Properties step allows you to either specify individual property names and values (name=value) or to specify a properties file. The properties file must consist of a series of individual property overrides.

For the creation of the BAR file component, use the IIB BAR File template that we created in the Provisioning Your Environment. If you plan to override BAR file properties with each deployment, add a property to your template that allows you to easily specify overrides during component creation. To do this, add a new component property definition to your IIB BAR File component template.

Now, using the component template to create the BAR file component allows us to provide BAR property overrides if they are necessary. As stated earlier, you can either specify individual property overrides or you may choose to specify a file. A properties file is the best option if your property overrides change from version to version. For this example, set up a directory on your IIB server’s file system to hold any BAR files and properties files used for BAR overrides. If you wish to use a different type of source configuration to specify the location of your BAR files and properties files, you can change the Source Configuration Type field on your IIB BAR File template. This allows you to use any of the HCL Launch’s source configuration plugins to import your files. You may find the proper plug-in to suit your source configuration needs from the Source Config Plugins section of the HCL Information Center.

Once we have our BAR component created, we can add it to our resource tree under the desired execution group that it will be deployed to from the Resources tab of the HCL Launch web console. For this example, add the pager.bar to the newly created NewEG execution group.

The placement of the component in the resource tree gives the pager.bar component access to the resource properties on the execution group, broker, and queue manager, as well as the component properties defined on the pager.bar component itself. These resource properties were defined in the Provisioning Your Environment.

Now, we need to create the component process for the deployment. Note, that this should be created as a ‘Deployment’ type process and not an ‘Operational’ process as a component version must be specified when it is executed. We can create this new component process on our IIB BAR File component template so that we only have to define it once for each BAR file component. In this example deployment, we have steps for overriding the BAR file properties and deploying the BAR file in the same component process.

The logic for our deployment component process is as follows:

1. Copy the pager.bar and pager_overrides.txt file from our component version to the agent’s working directory. This is handled by the Download Artifacts step of the built-in HCL Launch Versioned File Storage plugin. See the Documentation Page for this plugin if you have any issues.

   

   Note that the properties in the ‘Includes’ field are specific to that BAR file component, and will include the BAR file and properties file.

2. Override the properties of your BAR file specified in our properties file. This will use the Deploy step of the IIB Plugin for HCL Launch. As the BAR file and the override properties files have been copied to the agent’s working directory, they may now be referenced directly in the plugin step fields.

   

3. The final step is to deploy the BAR file to the execution group.

   

After the BAR file component is created and properly configured, add it to the application, and create a new application process to execute the deployment component process. Assuming that we have multiple BAR files to deploy to multiple execution groups, it makes sense to use the Install Multiple Components application process step. For usage information on this step, see Install Multiple Components.

To utilize the Install Multiple Components step, tag each BAR file component that you’ve created. When creating the components using the IIB BAR File component template, tag the component template, all components created using the template are tagged as well. In this example, create a tag for BAR file components called BARFILE.

As the last setup for running our deployment, create a new application process on our application, such as Run Deployment. This new process will only consist of one application process step Install Multiple Components. To run all deployments on each of our BAR file components, specify our newly created component tag and the name of the component process to run.

Before running the process, make sure that you have a component version imported into your BAR file component. To do this, navigate to the Versions tab of your BAR file component, and click Import New Versions. This will use your configured source configuration to import artifacts into a new component version that may be used to run our new application process. See the Source Config Plugins section of the HCL Information Center for all available source configurations.

After importing the component version, we can use that version to run the deployment. Navigate to your application, and click the arrow to request a new process. When you click Choose Versions, select any available versions for your BAR file components.