Description

IBM Integration Bus, from the WebSphere product family, enables business information to flow between disparate applications across multiple hardware and software platforms. The plugin includes steps that can be used when designing a component process to deploy broker archives and to start, stop or delete message flows by using the IBM Integration API. For information on usage, including a sample of how to install IBM Integration Bus using HCL Launch, see How to automate IBM Integration Bus installation and deployments using HCL Launch and Chef. This plugin supports versions 9 & 10 of IBM Integration Bus (IIB). WebSphere Message Broker versions 7 and 8 are not supported.

Quick Info

Product
HCL Launch
Type
plugin
Compatibility
HCL Launch version 7.0 or later
Created by
HCL Software
Version Name Action

47.1100834

launch-webspheremessagebroker-cmp-47.1100834.zip

launch-webspheremessagebroker-cmp-47.1100834.zip

47.1100834


Summary

The IBM Integration Bus plugin provides steps for working with IBM Integration Bus (IIB), formerly known as WebSphere Message Broker. IBM Integration Bus connects business information among disparate applications on multiple hardware and software platforms.

The plugin uses the IBM Integration API, formerly known as the Configuration Manager Proxy (CMP) API, to communicate with the IBM Integration Bus. For additional information about the API, see IBM Integration API.

This plugin includes one or more steps, click Steps for step details and properties.

Compatibility

This plugin can be used with IBM Integration Bus versions 9 and 10.

This plugin requires HCL Launch version 7.0 or later.

The HCL Launch agent must run on an IBM Java Runtime Environment (JRE) or Java Development Kit (JDK). Other JREs and JDKs are not supported. This is a requirement of the IBM Integration API.

This plugin runs on all operating systems that are supported by the HCL Launch agent.

Installation

See Installing plugins in HCL Launch for installing and removing plugins.

History

The following table describes the changes made in each plugin version.

Plugin history details
Version Description
47 Update to the Override Bar Properties step processing to warn instead of fail on a line that is not valid in a property file.

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.

Version 9 Version 10 and later
ConfigManagerProxy.jar
com.ibm.mq.jar
ibmjsseprovider2.jar
IntegrationAPI.jar

Additional JAR files for remote connectionsjetty-io.jar
jetty-util.jar
websocket-api.jar
websocket-client.jar
websocket-common.jar

Steps

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

Create Execution Group

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

Input properties for the Create Execution Group step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this
value if you are using below version 10 of IIB.
No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines.
Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:
/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE.
No
Execution Groups String Comma or new line separated list of Execution Groups defined on the broker to create
if they do not exist.
Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API
will be required. For example: 10.0.0.1
Yes
IP String The ip address of the target server for a remote connection. You must specify
either an IP and Port to connect to a remote broker or an Integration Node Name
to connect to a local broker.
No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to
a remote broker or an Integration Node Name to
connect to a local broker.
No
Jar Path String Specify either directories to recursively search from,
or each individual jar path split by your file
systems path separator. (e.g. /opt/ibm/server/classes:/opt/ibm/common/jetty/lib)
You must specify your required JAR files in either the
Jar Path field or the CLASSPATH environment variable.
No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server.
Specifying this value will initialize your command environment. This
value is required if your command environment is not initialized on
startup through a script such as `.bashrc`.
No
Password Password Password for secure authentication. Explicit user authentication only available with
IIB 10.
No
Port String The port of the target server for a remote connection.You must specify either an IP
and Port to connect to a remote broker or an Integration Node Name to connect
to a local broker.
No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

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.

Input properties for the Create Integration Node step
Name Type Description Required
Additional Arguments String Any additional arguments to pass to the mqsicreatebroker script when running this step. Multiple arguments are split by new line. For example: i generalDefaultUserId. No
IIB Installation Directory String The installation directory of the IIB server. (e.g. /opt/ibm/server) Yes
Integration Node (Broker) String The name of the integration node to create. Yes
Queue Manager String The name of your WebSphere MQ Queue Manager. If this is not specified a queue manager is created unless running z/OS, in which case this step will fail. No
Service Password String The password for the service user ID. This is only required for IIB version 9. No
Service User ID String The user ID under which the broker runs. This is only required for IIB version 9. No

Create Or Update Configurable Service

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

Input properties for the Create Or Update Configurable Service step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Delete Missing Properties Boolean This option will attempt to delete any properties that exist on the configurable service that arent referenced in the Properties field. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE For example: java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API will be required. For example: 10.0.0.1 Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib. You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP< and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Properties String A new line separated list of properties to set in the format name->value or name=value Yes
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Service Name String The name of the service to be created or updated Yes
Service Type String The type of the service. If there is a service matching Service Name that is not of this type, the step fails. Yes
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with
IIB 10.
No

Delete Applications

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

Input properties for the Delete Applications step
Name Type Description Required
Application Names String A list of IIB application names split by newlines or commas. Yes
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Group String Name of the Execution Group where the applications exist. Yes
Fail On Missing Application Boolean Select this checkbox to fail immediately if any specified applications do not exist on the execution group. Otherwise, the step fails if none of the applications exist on the execution group. No
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API will be required. For example: 10.0.0.1 Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

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.

Input properties for the Delete BAR File Contents step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Delete Libraries Boolean Check this box to delete any libraries that have been deployed to the execution group using the BAR file. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Group String Name of the Execution Group to Deploy to. Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API will be required. For example: 10.0.0.1 Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file
systems path separator. (e.g. /opt/ibm/server/classes:/opt/ibm/common/jetty/lib) You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable.
No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
RegEx String Java compliant regular expression for matching the BAR file name of deployed flows. Yes
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Delete Configurable Service

Delete a configurable service.

Input properties for the Delete Configurable Service step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API will be required. For example: 10.0.0.1. Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. (e.g. /opt/ibm/server/classes:/opt/ibm/common/jetty/lib) You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as `.bashrc`. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Service Name String The name of the service to be created or updated Yes
Service Type String The type of the service. If there is a service matching Service Name that is not of this type, the step will fail. Yes
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Delete Execution Group

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

Input properties for the Delete Execution Group step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Group String The name of the execution group to be deleted. Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API is required. For example: 10.0.0.1. Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. (e.g. /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Delete Integration Node

Delete an Integration Node (Broker).

Input properties for the Delete Integration Node step
Name Type Description Required
Delete Trace Files Boolean Check this box to delete the nodes trace files from its work directory. No
Delete WebSphere MQ Queues Boolean Check this box to delete any current integration server administration security WebSphere MQ queues along with the integration node. No
IIB Installation Directory String The installation directory of the IIB server. (e.g. /opt/ibm/server) Yes
Integration Node (Broker) String The name of the integration node to create. Yes

Deploy

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

Input properties for the Deploy step
Name Type Description Required
Bar File Names String Comma or new line separated list of Broker Archive files to deploy. Yes
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Deployment Type Enumeration Specify either an incremental or full deployment. You can also specify the ${p?:iib.deployType} option and set the iib.deployType property to either incremental or full at any level in the property hierarchy. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Groups String Comma or new line separated list of Execution Groups to Deploy to. Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API will be required. For example: 10.0.0.1 Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. (e.g. /opt/ibm/server/classes:/opt/ibm/common/jetty/lib) You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as `.bashrc`. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Start/Stop Message Flows Boolean Check to stop all Message Flows in the Execution Group before deployment and start all Message Flows after deployment. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Does Execution Group Exist

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

Input properties for the Does Execution Group Exist step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64: /opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Group String Execution Group name to identify its existence. Yes
Fail if Execution Group Not Found Boolean Select this checkbox to fail the step if the Execution Group is not found. The output property will still be set. No
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API is required. For example: 10.0.0.1. Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib. You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10.
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Override Bar Properties

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

Input properties for the Override Bar Properties step
Name Type Description Required
Bar File Excludes String New line separated list of Broker Archives to exclude *.bar includes all bar files in the working directory. No
Bar File Includes String New line separated list of broker archive files or patterns to include *.bar includes all bar files in the working directory. Yes
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE, for example: java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib. Implemented to support z/OS using an ENVFILE. No
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API is required. For example: 10.0.0.1. Yes
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
On Failure Enumeration Choice of action when overrides fail on a particular bar file. Values are: Fast Fail, bestEffort and warn. Fast Fail: Step fails right away. Best Effort: Step attempts to override properties on all bar files and fails at the end if any override failures occurred. Useful to pinpoint which bar files are not valid. Warn: Step continues on if an override failure occurs, and print a warning declaring the bar file that failed. No
Properties String A new line separated list of properties to set in the format name=value, or a Property file. (You must specify either Properties or a Properties File, not both). Yes

Restart Execution Groups

Restart execution groups if they exist on the broker.

Input properties for the Restart Execution Groups step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Groups String Comma or new line separated list of Execution Groups defined on the broker to restart. Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API is required. For example: 10.0.0.1. Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to< connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value initializes your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available
in IIB version 10.
No
Username String Username for secure authentication. Explicit user authentication only available with
IIB 10.
No

Set Execution Group Properties

Set runtime properties for an execution group.

Input properties for the Set Execution Group Properties step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Group String Name of the Execution Group defined on the broker. Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API will be required. For example: 10.0.0.1 Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value will initialize your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Properties String A new line separated list of properties to set in the format name=value Yes
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging is disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Set Integration Node Properties

Set Runtime Properties for the Integration Node (broker).

Input properties for the Set Integration Node Properties step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE (i.e. java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API is be required. For example: 10.0.0.1. Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node (broker). You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value initializes your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Properties String A new line separated list of properties to set in the format type:name=value. Possible component types to specify for type are configurableservice, httplistener, securitycache, cachemanager, or webadmin. The name is specified in the format objectName/propertyName. For configurable services the name must be in the format service/objectName/propertyName. Yes
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Set Message Flows Properties

Sets runtime properties on a list of message flows.

Input properties for the Set Message Flows Properties step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Directory Offset String Path under the current working directory where you want the step to execute. Absolute paths are not allowed. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE, for example: java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Group String Name of the Execution Group to Deploy to. Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API is required. For example: 10.0.0.1. Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value initializes your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Message Flows String A new line separated list of message flows. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Properties String A new line separated list of properties to set in the format name=value No
Property File String Specify the name and path to a property file to use as a source of the properties instead of explicitly listing the properties in the Properties field and the flows in the Message Flows field. The property file would be the same format as the one used by the mqsiapplybaroverride command. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you
are using below version 10 of IIB.
No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Start Integration Node

Start an Integration Node (Broker).

Input properties for the Start Integration Node step
Name Type Description Required
IIB Installation Directory String The installation directory of the IIB server. For example: /opt/ibm/server. Yes
Integration Node (Broker) String The name of the integration node to create. Yes

Start Message Flows

Start Message Flows that are stopped.

Input properties for the Start Message Flows step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE, for example: java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Group String Name of the Execution Group. Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API is required. For example: 10.0.0.1. Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value initializes your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Message Flows String Comma or new line separated list of Message Flow names to start. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

Stop Integration Node

Stop an Integration Node (Broker).

Input properties for the Stop Integration Node step
Name Type Description Required
IIB Installation Directory String The installation directory of the IIB server. (e.g. /opt/ibm/server) Yes
Integration Node (Broker) String The name of the integration node to create. Yes

Stop Message Flows

Stop Message Flows that are running.

Input properties for the Stop Message Flows step
Name Type Description Required
Channel String The name of the channel to use. Must be defined on the queue manager. Specify this value if you are using below version 10 of IIB. No
Environment Variables String A file or list containing property entries, with each entry delimited by newlines. Entries must be in the form VAR=VALUE, for example: java.library.path=/opt/mqm/java/lib64:/opt/mqm/java/lib). Implemented to support z/OS using an ENVFILE. No
Execution Group String Name of the Execution Group. Yes
IBM Integration Bus Version String Enter the version of the installed IBM Integration Bus. This determines which API is required. For example: 10.0.0.1. Yes
IP String The ip address of the target server for a remote connection. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Integration Node Name String Name of Integration Node. You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Jar Path String Specify either directories to recursively search from, or each individual jar path split by your file systems path separator. For example: /opt/ibm/server/classes:/opt/ibm/common/jetty/lib). You must specify your required JAR files in either the Jar Path field or the CLASSPATH environment variable. No
MQSIPROFILE Executable String The absolute path to the mqsiprofile executable on your IIB server. Specifying this value initializes your command environment. This value is required if your command environment is not initialized on startup through a script such as .bashrc. No
Message Flows String Comma or new line separated list of Message Flow names to start. No
Password Password Password for secure authentication. Explicit user authentication only available with IIB 10. No
Port String The port of the target server for a remote connection.You must specify either an IP and Port to connect to a remote broker or an Integration Node Name to connect to a local broker. No
Queue Manager String The WebSphere MQ Queue Manager which the broker is using. Specify this value if you are using below version 10 of IIB. No
Trace File String The file to use for trace logging. If not set trace logging will be disabled. No
Use SSL Boolean Administration security authentication/authorization. This option is only available in IIB version 10. No
Username String Username for secure authentication. Explicit user authentication only available with IIB 10. No

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.

The Navigator pane of the IBM WebSphere MQ Explorer.

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.

A resource tree provisioned with queue managers, integration nodes, integration servers, and BAR files.

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.

Resource property definition 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.

Adding a new execution group to the resource tree.
Specify the name of your execution group as your ‘iib.executionGroup’ property.

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.

A simple component template for creating BAR file components.

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.

Creating a new BAR file component using the component template.

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.)

Completed resource tree with BAR files added to parent execution groups.

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.

Setting the ‘iib.jarPath’ property at the agent resource level.

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:

IIB Version 9 IIB Version 10
ConfigManagerProxy.jar IntegrationAPI.jar
com.ibm.mq.jar
ibmjsseprovider2.jar

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.

Adding the iib.installDir property to the agent resource.

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.

Add the component process step to create 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.

Add the new component to your resource tree under the Queue Manager that it belongs to if applicable.

 

Choose the generic “IIB Broker” component and specify the name of your new broker to create.

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.

Adding your IIB Broker and IIB Execution Group components to an application.

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.

Application process created to execute the ‘Create Integration Node’ component process.

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.

Adding resources to your 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.

Setting the ‘iib.jarPath’ property at the agent resource level.

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.

Configure the Create Execution Group step on your IIB Execution Group component.

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.

Add a new IIB Execution Group component resource to the broker component resource that you want to create the execution group under.

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.

List all objects of the execution group that you can configure properties for.

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

Run the mqsireportproperties executable to list all execution group properties.

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.

Broker rejecting a request to change a property that is not configurable.

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.

Executing the mqsireadbar command using the pager.bar file.

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.

Example properties file to override properties on the ‘pager.bar’ file.

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.

Add a component property to specify BAR file overrides during component creation.

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.

Creating a new BAR file component using the IIB BAR File component template.

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.

Adding the BAR file component to your resource tree.

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.
    Override BAR file properties.
  3. The final step is to deploy the BAR file to the execution group.
    The ‘Deploy’ step of the IIB Plugin.

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.

Added a new tag to the component template.

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.

Application process step to run all BAR file deployments.

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.

Importing a new component version into the pager.bar BAR file component.

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.