+ All Categories
Home > Documents > TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in...

TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in...

Date post: 16-Mar-2018
Category:
Upload: dinhmien
View: 262 times
Download: 8 times
Share this document with a friend
89
TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User's Guide Software Release 8.1 May 2014 Two-Second Advantage ®
Transcript
Page 1: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

TIBCO ActiveMatrix BusinessWorks™ Plug-infor WebSphere MQ User's GuideSoftware Release 8.1May 2014

Two-Second Advantage®

Page 2: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCHEMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY(OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THEEMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANYOTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright lawsand treaties. No part of this document may be reproduced in any form without the writtenauthorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO ActiveMatrixBusinessWorks Plug-in for Data Conversion, TIBCO Business Studio, and TIBCO EnterpriseAdministrator are either registered trademarks or trademarks of TIBCO Software Inc. in the UnitedStates and/or other countries.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform EnterpriseEdition (J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks ofOracle Corporation in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOTALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASEDAT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWAREVERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2012-2014 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

2

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 3: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Contents

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Plug-in Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

About WebSphere MQ Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Creating a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Creating a WebSphere MQ Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Configuring a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Debugging and Running a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Configuring the Local Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Checking the Output of an Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

Deploying Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Generating an EAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Shared Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

WebSphere MQ Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

WebSphere MQ Message Body Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

WebSphere MQ Application Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

WebSphere MQ Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

WebSphere MQ Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

WebSphere MQ Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

WebSphere MQ Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

WebSphere MQ Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

WebSphere MQ Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66

Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Transactions with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Data Conversion Plug-in with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Creating Secure Connections to the Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Setting Up WebSphere MQ Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Creating IBM Keystores for the Queue Manager and Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Configuring the Queue Manager to Use Generated Keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Using the IBM Key Management Tool to Review the Personal Certificate Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79

Creating a TLS Connection for the Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Setting Up TIBCO ActiveMatrix BusinessWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Plug-in with Large Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Sending and Receiving Long Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Managing Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

3

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 4: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Setting Up Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Exporting Logs to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

4

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 5: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

TIBCO Documentation and Support Services

All TIBCO documentation is available in the TIBCO Documentation Library, which can be found here:

https://docs.tibco.com

Product-Specific Documentation

The following documents for this product can be found in the TIBCO Documentation Library:

● TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ Installation● TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ User's Guide● TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ Release Notes

The following documents provide additional information and can be found in the TIBCODocumentation Library:

● TIBCO ActiveMatrix BusinessWorks Documentation● TIBCO Enterprise Administrator User's Guide

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support asfollows:

● For an overview of TIBCO Support, and information about getting started with TIBCO Support,visit this site:

http://www.tibco.com/services/support

● If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you canrequest one.

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is aplace to share and access the collective experience of the TIBCO community. TIBCOmmunity offersforums, blogs, and access to a variety of resources. To register, go to:

http://www.tibcommunity.com

5

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 6: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Plug-in Overview

TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implementActiveMatrix BusinessWorks applications that exchange messages with other WebSphere MQ-capableapplications across a wide range of hardware and operating systems.

The Plug-in is specifically used to exchange free form binary and text data with the TIBCOActiveMatrix BusinessWorks Plug-in for Data Conversion, which allows TIBCO ActiveMatrixBusinessWorks applications to use IBM standard copybooks to interface with legacy applications usingseveral transport mechanisms such as this Plug-in.

The Plug-in supports the following features:

● WebSphere MQ 7.x and upward releases. The Plug-in supports the connection to WebSphere MQ6.x to the same extent that IBM supports connections between WebSphere MQ Server 6.x and Client7.x. See the IBM documentation for the version of softwares installed to determine if the featuresyou want to use are supported. The unsupported items are listed as follows:

— Pub/Sub Applications— Application Properties— Locally bound connections to WebSphere MQ Server 6.x

● A Connection resource that contains all parameters relevant to establishing a connection, includingautomatic re-connectivity.

● Connections can be pooled and secured with Transport Layer Security (TLS).● A WebSphere MQ Get activity that gets a message from a queue and returns the contents of the

message as fields in the output schema.● A WebSphere MQ Put activity that puts message to a queue.● A WebSphere MQ Listener activity that gets a message from a queue as a process starter. Each

process started may access the message read as fields in the activity output. Optionally, the messagecan be explicitly acknowledged from within the new process. If the message is not acknowledged, itis placed back on the queue.

● The WebSphere MQ Publisher/Subscriber activities perform topic publish and subscribe functionsusing messages, as described above.

● Handles the following message types:

— Datagram— Request— Reply— Report (COA, COD, Expiration, Exception, PAN, and NAN types are supported)

● Filters on correlation and message identifiers.● Local MQ transactions for Get and Put activities.● Grouped and segmented messages.● Dynamic queues.● WebSphere MQ message properties.

6

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 7: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

About WebSphere MQ Messages

TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to access WebSphere MQqueues and messages with WebSphere MQ applications.

WebSphere MQ messages consist of three basic sections:

● A header containing fields.● Message properties that are collection of property names and property values.● The message body.

The Plug-in uses different mechanisms to provide access to these sections.

Message Headers

Get, Put, and Listener activities provide access to WebSphere MQ message headers using the input andoutput schemas for an activity. The root name mqproperties contains the fields of message headers.Field names used in the mqproperties node generally map to message header field names used in theWebSphere MQ interface for Java. Only applicable fields are exposed in the input and output schema.For example, the accountingToken element is not an input schema field but is an output schema fieldfor the Get activity.

Message Properties

Message properties are a collection of name value pairs that can be sent with a Put activity to adestination, or can be received from a destination for Get and Listener activities. Values for a propertyare interpreted according to the schema that defines the properties node, and honor the encoding of themessage.

Message Body

The message body is exchanged as text strings or byte arrays for Get, Put, and Listener activities.

WebSphere MQ message payloads are often complex combinations of string, integer, and other fieldstypes. It is recommended that the Plug-in for Data Conversion should be used to parse and render suchcomplex message bodies.

7

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 8: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Getting Started

A typical workflow using the plug-in to achieve different goals includes creating a process, testing it inthe debugger, and deploying the application.

TIBCO ActiveMatrix BusinessWorks uses the Eclipse graphical user interface (GUI) provided by TIBCOBusiness Studio to define business processes and generate Enterprise Archives (EAR files). The EARfiles is deployed and run in the ActiveMatrix BusinessWorks runtime, and also is managed by usingTIBCO Enterprise Administrator (TEA).

The following is a typical workflow using the plug-in:

1. Creating a Project

2. Creating a WebSphere MQ Connection

3. Configuring a Process

4. Debugging and Running a Process

5. Deploying Applications

Creating a ProjectProjects are BusinessWorks application modules that are created in TIBCO Business Studio. A projectcontains various resources.

Procedure

1. Start TIBCO Business Studio.

2. Click File > New > BusinessWorks Resources.

3. Click BusinessWorks Application Module in the BusinessWorks Resource dialog. Click Next.

There are several ways to open the New BusinessWorks Application Module dialog andcreate a new project in TIBCO Business Studio. See the TIBCO ActiveMatrixBusinessWorks documentation for more information.

4. Type a name for the project that you are creating in the Project name field.

5. Keep the Use default location, Create empty process, and Create Application check boxes selected.Click Finish.

Result

A project and an application are created and displayed in the Project Explorer view. The Process editoropens automatically.

8

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 9: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Creating a WebSphere MQ ConnectionTo use the plug-in activities, you need to create a WebSphere MQ Connection shared resource whichcontains all the parameters necessary to connect to a queue manager.

Procedure

1. Expand the created project in the Project Explorer view.

2. Right-click the Resources folder and select New > WebSphere MQ Connection.

3. Type a name in the Resource Name field in the WebSphere MQ Connection Resource dialog. ClickFinish.

4. Configure the WebSphere MQ Connection shared resource in the displayed editor, as described in WebSphere MQ Connection.

Configuring a ProcessProcesses define the business logic. Once a project is created, you need to configure the process byadding activities, conditions, and services.

Procedure

1. Select an activity from the Palette view and drop it in the Process editor.For example, select and drop the Timer activity from the General Activities palette and the Putactivity from the MQ palette.

2. Click to create links between the activities and configure the condition types.

3. Configure added activities, as described in WebSphere MQ Palette.

An WebSphere MQ Connection shared resource is required when configuring activities.See Creating a WebSphere MQ Connection for more details on how to create a WebShpereMQ Connection shared resource.

4. Click File > Save to save the project.

9

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 10: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Debugging and Running a ProcessDebug the application you have configured to ensure that the application configuration is correct.

Procedure

1. Open the process you have configured in TIBCO Business Studio.

2. On the toolbar, click Run > Debug Configurations.

3. Click BusinessWorks Application > BWApplication in the left panel.

4. Ensure only the application you want to debug and run is selected in the Applications tab in theright panel.

5. Click the Advanced tab and click Browse to locate the logback file.By default, the log file resides in the TIBCO_HOME/bw/6.0/config/design/logback directory anderror logs are captured. See Managing Logs for more details.

6. Click Debug.TIBCO Business Studio changes to the Debug perspective. Logs are displayed in the Console view.

Configuring the Local ConnectionIf the connection binding type is Local, then the JVM running your application expects to find the MQnative libraries on the java.library.path. If it does not, your process will fail with an indicationMQRC_MODULE_NOT_FOUND.

To add the MQ native libraries to the application debug configuration:

Procedure

1. In TIBCO Business Studio, click Run > Debug Configurations.

2. Click BusinessWorks Application > BWApplication in the left panel.

3. Click Environment tab in the right panel.

4. In the Edit Environment Variable wizard, add or modify the library search path variable for yoursystem:

● For Linux (The entry will be similar to):

Type LD_LIBRARY_PATH in the Name field and ${env_var:RV_HOME}/lib/64:${env_var:RV_HOME}/lib:/opt/mqm/java/lib/OSGi:/opt/mqm/java/lib64:$

{env_var:LD_LIBRARY_PATH} in the Value field.

● For Windows:

Type PATH in the Name field and ${env_var:RV_HOME}/bin${system_property:path.separator}C:\Program Files (x86)\IBM\WebSphere MQ\java

\lib${system_property:path.separator}${env_var:PATH} in the Value field.

Checking the Output of an ActivityAfter debugging the application, you can check the output of activities.

Procedure

1. In the Debug perspective, expand BWApplication and click the activity in the upper left panel.

2. In the upper right panel, click the Job Data view and click Output.

10

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 11: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

You can also check the activity output in the plug-in logs. See Managing Logs for moreinformation.

Deploying ApplicationsAfter deploying applications, you can manage BusinessWorks applications by using TIBCO EnterpriseAdministrator.

Prerequisites

The following tasks are required before deploying applications:

● Creating a Project.● Generating an EAR File.

A typical workflow of deployment includes:

1. Uploading an EAR file.

2. Deploying an application.

3. Configuring an application.

4. Starting an application.

You can deploy an application EAR file using the command-line mode with the bwadmin utility. SeeTIBCO ActiveMatrix BusinessWorks Administration for more details about how to deploy an application.

Generating an EAR FileApplication archives are enterprise archive (EAR) files that are created in TIBCO Business Studio. AnEAR file is required when deploying an application.

Prerequisites

An application project has already been created, as described in Creating a Project.

There are many ways to generate an EAR file, the following is one method. See TIBCO ActiveMatrixBusinessWorks Administration for more information.

Procedure

1. Go to the File Explorer view and click the Open Directory to Browse icon.

2. Select the folder where you want to generate the EAR file and click OK.The new folder is displayed in the File Explorer view.

3. Drag the application from the Project Explorer view to the new folder in the File Explorer view.

The EAR file is generated with the name <name>.<application>_<version>.ear.

11

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 12: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Shared Resource

Shared resources are specifications that are shared among activities. This plug-in contains theWebSphere MQ Connection, WebSphere MQ Message Body Schema and WebSphere MQ ApplicationProperties Schema shared resources.

WebSphere MQ ConnectionThe WebSphere MQ Connection shared resource contains all the parameters necessary to connect to aqueue manager.

The connection resource supports these modes:

● Local: A local connection uses the C language libraries and JNI to locate and connect to queuemanagers on the local machine.

— Local connections support local transactions.— Local connections require a WebSphere MQ server installation on the local machine.— Local connections use the credentials for the logged on user.

● Remote: A remote connection uses TCP/IP to connect to the listening port on any queue manager onthe network or the local machine.

— Remote connections support local transactions.— Remote connections support the use of specific user credentials.— Remote connections support secure transports (TLS/SSL).

● Client Connection Table: This type of connection uses a Client Channel Definition Table (CCDT)exported by the queue manager upon saving a client channel definition. This is the only supportedmethod to connect to a multi-instance queue manager.

— Client connection table connections support local transactions. However, note that transactionsare not guaranteed to survive reconnections to the backup server in a failover situation.

— Client connection table connections support the use of specific user credentials.— Client connection table connections support secure transports (TLS/SSL).

See the IBM documentation for a description of CCDTs and how they are to be used.

General

The General panel contains the following fields.

FieldModuleProperty? Description

Name N The name to be displayed as the label for the WebSphere MQConnection shared resource in the process.

Description N Description of the resource.

Queue Manager Connection Configuration

The Queue Manager Connection Configuration panel contains the following fields.

12

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 13: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Binding N The connection resource supports three modes:

● Local● Remote● Client Connection Table

ClientConnectionTable

Y When using a Client Connection Table, enter the URL of the CCDTfile that was exported by the server to which you are trying toconnect.

This file should be located in the queue manager home directory inthe @ipcc/AMQCLCHL.TAB file. You can either reference this file fromthis location, or copy it to a location where it is accessible to therunning BusinessWorks instance.

This URL supports the HTTP, FTP and FILE protocols.

Host Name Y For remote connections, provide the name of the machine hostingthe queue manager.

Default: localhost

This field is only available for remote bindings.

Port Y For remote connections, provide the TCP port number on which thequeue manager is listening.

Default: 1414

Range: 1 - 65535

This field is only available for remote bindings.

User Name Y For secure remote connections, the user name which will be used tocreate the connection. If a user name is not provided, the credentialsof the current security context is used.

Password Y For remote connections, the password associated with the specifieduser name.

Queue ManagerName

Y For Local and CCT connections, the name of the queue manager toconnect to. If not specified, the default queue manager is selected.

Server ChannelName

Y For remote connections, the server channel to connect to.

Queue managers can use multiple server channels if needed, forexample to support TLS and plain connections.

HeaderCompression

N If RLE is selected, Run Length Encoding compression will beapplied to the header portion of messages sent or received over thisconnection.

13

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 14: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

MessageCompression

N If RLE is selected, Run Length Encoding will be applied to the bodyof messages sent over this connection.

If ZlibFast is selected, the connection will apply to both RLE andZlibFast compression.

If ZlibHigh is selected, the connection will apply to all threecompression techniques.

Test Connection N Click to test the queue manager connection. Whether successful ornot, a report will be placed in the text area to the right. If the testfails, the report will help you determine what the problem is. In theevent that the connection is TLS enabled and you are unsure whatcipher to use, Test Connection will search for an acceptable cipherand include it in the report.

If this is a local connection, Test Connection may fail because itcannot load the native JNI libraries it needs. If this happens youmust add the WebSphere MQ jative libraries (dll's) to the libraryloading path for your platform. The easiest way to do this is to add aline like this to the TIBCOBusinessStudio.ini file:

● For Microsoft Windows, -Djava.library.path=C:\ProgramFiles (x86)\IBM\WebSphere MQ\java\lib64

● For Unix/Linux, -Djava.library.path=/opt/mqm/java/lib64

Pooling Configuration

The Pooling Configuration panel contains the following fields.

FieldModuleProperty? Description

PoolingEnabled

N When checked, pooling is active for this connection. The primaryconsideration for choosing pooling parameters is the number ofavailable connections to the queue manager. Choose values whichwill not create unnecessary resource consumption in the queuemanager and leave available connections for other applications(including other pooled connections, should this application bedeployed on multiple servers).

If pooling is not active, a new non pooled connection is acquired andreleased for each activity.

Max Y Determines the maximum number of connections allowed in thepool. When this limit is reached, subsequent activities wait for aconnection to become available before starting.

14

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 15: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

Max Unused Y Determines the maximum number of idle connections allowed in thepool. When the number of unused connections reaches this number,the idle connections are disconnected and closed, freeing resourceson the server. Amounts over the Max Connections value areignored.

Timeout Y The length of time an inactive connection is kept in the pool. Aconnection that has remained unused for this number ofmilliseconds is closed and removed from the pool, freeing resourceson the server.

TLS Configuration

The TLS Configuration panel contains the parameters required to make a secure connection to thequeue manager using the Transport Layer Security protocol. Before TLS can be used, the queuemanager and server channel used by clients must be configured. For more information, see CreatingSecure Connections to the Queue Manager.

In order to ensure TLS can now be switched on or off at runtime depending on a deployment parm.Thus the SSL Configuration fields are always enabled. The TLS Configuration panel contains thefollowing fields.

FieldModuleProperty? Description

TLSConfiguration

N Create an SSL Client Configuration resource.

See Creating Secure Connections to the Queue Manager for moreinformation about this field.

TLS CipherSpec

Y The queue manager requires that a particular cipher is specified onthe connection. Normally ciphers are negotiated during thehandshake, but this is not true of WebSphere MQ connections. Thecipher must match the one selected on the queue managers securechannel configuration. However, please note the names do notmatch because the queue manager refers to the cipher suite and theplug-in refers to a cipher spec. To find out the correct cipher, simplyleave the field blank and press Test Connection to see if any cipheravailable in Java is acceptable to the queue manager. If not you mayhave to adjust the queue manager's cipher specification.

The following table shows the values in the TLS Cipher Spec field which are known to work:

BW Configuration Channel Configuration

SSL_RSA_WITH_DES_CBC_SHA DES_SHA_EXPORT

SSL_RSA_WITH_NULL_MD5 NULL_MD5

SSL_RSA_WITH_NULL_SHA NULL_SHA

15

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 16: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

BW Configuration Channel Configuration

SSL_RSA_EXPORT_WITH_RC4_40_MD5 RC4_MD5_EXPORT

SSL_RSA_WITH_RC4_128_MD5 RC4_MD5_US

SSL_RSA_WITH_RC4_128_SHA RC4_SHA_US

SSL_RSA_WITH_3DES_EDE_CBC_SHA TRIPLE_DES_SHA_US

Configure TLS using these fields and ensure:● That a Java Key Store is configured for the SSLClient.● That the SSLClient protocol is TLSv1 and that the cipher is explicitly specified and matches the

cipher used by the server channel.

See TIBCO ActiveMatrix BusinessWorks for more details about the TLS Configuration panel.

WebSphere MQ Message Body SchemaIf the message content type for a message is set to Schema, then the message will be parsed or rendered(depending on the operation) based on the schema derived from this resource. Therefore, to interactwith an application all that has to be known is the schema to which its messages conform.

To create a schema, instantiate a Message Body Schema resource and add fields in the sequence thatthey are to appear in the message.

● The string type fields require the length to be provided. The length is ignored for other types. Datais space padded or truncated as necessary to conform to the length provided.

● The fields will be inserted or removed from the message in the order in which they are added to thetable in this resource.

● Field names need only be unique.● If there is no sync-point in place for the activity and an error occurs while extracting message body

fields which causes the activity to fail, then the message is effectively lost. If there is any chance ofthis happening in your application, you should force a sync-point.

WebSphere MQ Application PropertiesThere is no shared resource representing the application properties for a message in BusinessWorks 6.Instead, a generic schema is used and mapped onto the operation.

Only the field types listed below are supported:

● boolean● byte● bytes● short● int● long● float● double● stringThe node represented by this schema will be present on the input schema of the Put activity and in theoutput schema of Get and Listener activities. Fields which contain values are mapped onto sent

16

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 17: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

messages. When processing a received message, all fields in the schema which have correspondingnamed counterparts in the message are mapped onto the output schema. If a type mismatch occurswhen mapping fields onto the output schema, the field is skipped. If fields that are required by theschema are missing from the message, it will cause the activity to fail. If there is no sync-point in placefor the activity and an error occurs while extracting the properties which causes the activity to fail, thenthe message is effectively lost. If there is any chance of this happening in your application you shouldforce a sync-point.

To create an WebSphere MQ Application Properties Schema, right-click the Schemas folder in theProject Explorer view, select New > XMS Schema File, and configure the schema and then select itfrom all the activities that use it.

If the application properties are used on a message, the properties are included in an MQRFH2 header.This header is visible to and must be handled by non-Java applications in order for those applicationsto access the properties.

17

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 18: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

WebSphere MQ Palette

The WebSphere MQ palette contains activities that can be added to your business processes.

WebSphere MQ PutThe Put activity can place messages into a configured queue.

There are four types of messages:

● Datagram: Basic message.● Request: A message for which the sending application expects a response and for which a Reply to

Queue is required.● Reply: A message sent in response to a received Request type message. Usually the destination for

this message has been mapped from the Reply To Queue field of the request message.● Report: A message containing monitoring data. In most cases, report messages are generated by

queue managers. However, it is possible for applications to do so using this message type.

The activity is capable of sending any of the four message types to permanent or dynamic queues. Thecapabilities of the activity are determined by the configuration, with some runtime behaviors controlledby the input schema. The type of message being sent may determine what fields are applicable for theput operation.

Messages can be sent to predefined queues or dynamic queues. If the destination or the reply to queueis dynamic, you must specify a properly configured model queue. The queue manager constructs adynamic queue based on that template. The name of a unique dynamic queue can be generated if thequeue name provided ends with an asterisk (*). It makes sense to use such names only if it is possible toconfigure a receiving application with the name of the newly created queue. The name can be takenfrom the destination element in the Output tab.

General

The General tab contains the following fields.

Field

ModuleProperty? Description

Name N The name to be displayed as the label for the activity in the process.

Connection Y The connection resource which associates this activity with thequeue manager that has access to the desired queue.

Destination Y The name of the queue onto which the message will be placed. If thequeue is to be created dynamically, enter the name of the dynamicqueue. The name must follow the MQSeries rules for dynamic queuenames.

If the queue name has been dynamically mapped using the inputschema's destination field, this field is not required.

DynamicDestination

N A flag that enables the creation of a dynamic queue. When selected,the Dynamic Destination Model field is enabled. Dynamic queuesare ones which are created as needed and display when the lifespandictated by the model is reached.

18

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 19: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

DynamicDestinationModel

Y Select the Dynamic Destination check box to enable this field.

Enter the name of a queue model for the queue manager to use as atemplate for creating this dynamic queue.

Message ContentType

N Select the type of message content:

● Binary: If Binary is selected, string content can still be sent, but itmust be translated to binary via an xpath expression.

● Text: String data can be directly mapped onto the message. Itwill be converted using the default Java encoding.

● Schema: The message will be formatted according to the schemaprovided in the Message Body Fields field. Input values for thisschema will appear in the input editor.

Message BodyFields

Y Provide the schema to be used in the Input tab, and at runtime toencode the contents of this message.

Message Type N Select the type of message that is to be sent:

● Datagram● Request● Reply● Report

If a Request message is chosen, the Reply To Destination andDynamic Reply To Destination fields are enabled.

Reply ToDestination

Y This field is enabled for the Request message type only.

The queue name which will be placed into the message header'sReply To Destination field. This queue need not exist and is notchecked at design or runtime.

DynamicReplyToDestination

N This field is enabled only when the Dynamic Reply To Destinationcheck box is selected.

A flag that enables the creation of a dynamic queue. When selected,the Dynamic Reply To Dest Model field is enabled, and the replyqueue will be dynamically created based on the model in theDynamic Reply To Dest Model field. If a dynamic reply queue isspecified, it will be created during the put operation so that it isavailable to the responding application.

This field is available only for the Request message type.

DynamicReplyToDestModel

Y Specify the model after which the reply queue is to be patterned.

This field is enabled only when the Dynamic Reply To Destinationcheck box is selected.

19

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 20: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Fail If Quiesing Y Select this check box to cause the activity to fail if the queue managerattempts to quiesce during the operation. This will prevent thequeue manager quiesce from being delayed by this activity.

ApplicationProperties

Y Select the Application Properties resource to be included as part ofthis message. Application properties are similar to regular messageheader fields except that the name and type of these fields can bedetermined by a predefined schema.

To use application properties create a generic XML schemacomposed of a node with simple elements inside it and map it to thisfield. See the IBM WebSphere documentation for property typessupported by the level of client you have installed.

A failure to observe cardinality will result in errorsprocessing the input or output schema.

Logger Name Y Loggers are configured in an XML file used by the runtime. Theruntime logger configuration is specified by the -Dlogback.configurationFile parameter of either the deployedapplication instance or of the debugger instance. Once the logger isconfigured, it can be named here to cause informational messages tobe written there. See TIBCO ActiveMatrix BusinessWorks for moredetails about how to configure loggers.

Description

Provide a short description for the activity.

Multi-Message

The Multi-Message tab contains the following fields.

20

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 21: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Multi-MessageSupport

N Select the level of support this activity is to have for batch groupsand logical messages.

Select one of the following:

● None: The input schema will provide only for a single messageand it will be put without a sync-point. This is the fastestoperation configurable.

● Batch: The input schema will be configured for batch messages.Multiple nodes will be sent as separate messages and committedas a single unit of work.

● BatchGroup: The input schema will be configured for batch butall the messages provided will be sent as a single logical messagegroup.

● CustomGroup: In this mode, the input schema will beconfigured for a single message and the lastMessage field willbe provided. The application designer can loop a number of putoperations to create a logical message group and it is theirresponsibility to terminate the group by setting the lastMessagefield of the last message to true.

Unless the activity is in an MQ Local Transaction, each memberof the logical message will be committed as the activity ends. Ifan error occurs, an incomplete logical message could be left onthe queue. It is therefore good practice to use a local transactionto commit an entire logical message at once.

This only works in a loop because the activity storesthe message object for use as context when sending thenext message.

Segmentation N Select the segmentation behavior for this put operation.

Select one of the following:

● None: The message will not be segmented, nor will it allow thequeue manager to segment it.

● Explicit: This will enable the Max Segment Size field and willsegment the message configured on the input schema into asmany segments as necessary to send the whole message.

● QueueManager: The message will be sent with flags set so thatthe queue manager can segment it to suit the buffer sizes of anychannels encountered on the way to the destination.

● Both: The message will be explicitly segmented by Max SegmentSize and flags will be set allowing the queue manager to furthersegment the message if necessary.

21

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 22: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Max SegmentSize

Y If segmentation is enabled, this field is enabled. Enter the maximumsize in bytes that any segment of this message should consume (notincluding the size of the header on each segment).

Default: 0

ExplicitCommit

N Every attempt is made within the plug-in to avoid unnecessarycommits due to the overhead involved. However you might selectthe check box to force the creation of a unit of work and subsequentcommit. The commit happens after any application properties andmessage body fields have been processed, so selecting the check boxprotects you from removing a message from the queue only to failwhile processing the contents. Message contents can cause failuresif, for instance, the encoding or character set is in appropriate for thedata, or the schema used to process the message is in error.

Synpoint Used N This field is not a configuration field, rather it is an indication ofwhether a syncpoint will be required for the operation. Nonsyncpoint operations are significantly faster than syncpoint ones,however the overhead of a syncpoint is much less significant forlarge batches.

If an activity is inside a local transaction, this field will beunaware of that fact. In that case a sync-point is always ineffect for the local transaction.

Advanced

The Advanced tab contains the following fields.

Field

ModuleProperty? Description

MessagePriority

Y Set the priority of the message as it is to be retrieved by the queuemanager. The values range from 0 to 9.

MessageExpiration

Y The time, in tenths of a second, that the message will persist on thequeue before being deleted by the queue manager. The default, 0, isto persist forever.

Values range from 0 to 2147483647.

The default is 0, which means the message never expires.

GenerateCorrelation Id

N Select this check box to cause the queue manager to generate aunique correlation identifier for the message when it is sent. Thismeans that the message identifier, which is always generated, iscopied to the correlation identifier field.

If this option is enabled, the queue manager overlays anycorrelation identifier that is mapped on the input schema.

22

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 23: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Persistence N Determines whether messages on the queue manager persist acrossrestarts.

Select one of the following settings:

● AS_QUEUE_DEF: It uses the persistence level defined in thequeue definition.

● PERSISTENT: It ensures that the message persists if the queuemanager fails or restarts.

● NOT_PERSISTENT: Not Persistent.

Context Support N The input fields of a put operation fall into categories based on theircontext. Many fields are always present, but others are only presentif the context relevant to that field is chosen. This is because thequeue manager must grant the user the authorization to updatethese fields.

Select one of the following settings:

● Default: The input schema will conform to the fields accessible toa user with the default authority.

● Identity: The input schema will conform to the fields accessibleto a user with the Set Identity Context authority.

The new fields are:

● accountingToken

● applicationIdData

● userId

● All: The input schema will conform to the fields accessible to auser with the Set Identity Context and Set All Contextauthorities.

The new fields (in addition to those provided by Identity) are:

● applicationOridinData

● putApplicationType

● putApplicationName

23

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 24: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Confirm onArrival

N Trigger a report message using the Confirm on Arrival type. Thereport is not enabled by default.

Report types are:

● NONE: The report is not enabled.● NO_DATA: The body of the message does not accompany the

report.● WITH_DATA: The first 100 bytes of the message body

accompanies the report.● FULL_DATA: The entire body of the message accompanies the

report.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive withRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

Confirm onDelivery

N Trigger a report message using the Confirm on Delivery type. Thereport is not enabled by default.

Report types are:

● NONE: The report is not enabled.● NO_DATA: The body of the message does not accompany the

report.● WITH_DATA: The first 100 bytes of the message body

accompanies the report.● FULL_DATA: The entire body of the message accompanies the

report.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive with theRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

24

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 25: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Confirm onException

N Trigger a report message using the Confirm on Exception type. Thereport is not enabled by default.

Report types are:

● NONE: The report is not enabled.● NO_DATA: The body of the message does not accompany the

report.● WITH_DATA: The first 100 bytes of the message body

accompanies the report.● FULL_DATA: The entire body of the message accompanies the

report.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive with theRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

Confirm onExpiry

N Trigger a report message using the Confirm on Expiry type. Thereport is not enabled by default.

Report types are:

● NONE: The report is not enabled.● NO_DATA: The body of the message does not accompany the

report.● WITH_DATA: The first 100 bytes of the message body

accompanies the report.● FULL_DATA: The entire body of the message accompanies the

report.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive with theRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

Report ReplyQueue

Y Enter the name of the queue to which Report messages should besent. This queue need not exist and is not checked, but can beselected using Choose a field value type on the right side of thefield. The value entered here maps onto a message'sreplyToQueueName field.

25

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 26: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Pass CorrelationId

N Determines the setting for a report message’s correlation ID.

● When checked, the correlation ID of the sent message is copied tothe correlation ID field of the report message.

● When not checked, the message ID of the sent message is copiedinto correlation ID field of the report message.

AsynchronousPut*

N Select this check box to achieve a modest improvement in thelatency of the Put activity if your application can tolerate thepotential for an unreported failure writing to the queue.

See the IBM WebSphere documentation for the put message optionMQPMO_ASYNC_RESPONSE for more information regarding the risks ofusing this option.

Input

The Input tab contains the following fields.

Field

ModuleProperty? Description

Batch N This node will be present when any of the multi-message modes areactive based on the activity configuration. It will allow theInteractionInput node to be duplicated any number of times tomake up a composite batch for the put operation.

InteractionInput N This input schema field is the root node for all the input provided tothe activity.

26

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 27: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

mqproperties N The node containing all the message header fields (plus thedestination override) that are relevant on input.

● destination: Specify a destination here in order to override thequeue name from the configuration panels. This allows thequeue to be dynamically specified.

● destqmgr: Destination queue manager name. The name of thequeue manager on which this queue resides.

A transmission queue and a sender channel must beconfigured for this queue manager in order for it towork.

● correlationId: Provide a correlation identifier for this messageby mapping a byte array to this field. The XPath expressiontib:string-to-base64 ("correlationid") is sufficient topopulate this field.

● messageId: Specify a message ID. This value overrides thedefault value generated by the queue manager. The rules are thesame as for correlationId.

● characterSet: Sets the IBM Coded Characterset ID of thismessage. Valid values are:

— 850: The commonly used ASCII codeset.

— 819: The ISO standard ASCII codeset.

— 37: The American EBCDIC codeset.

— 1200: Unicode.

— 1208: UTF-8.

The queue manager may apply this codeset when doingconversions for the purpose of creating report messages.

● alternateUserId: Specify a userid to be used as an alternateuser for this operation only. The user used in the connectionresource must have an Alternate Userid Authority in order touse this field.

● accountingToken: Provide a binary (base 64 encoded)accounting token to be used on host systems to assist inaccounting for resources used by the application.

● applicationIdData: Provide a string that can be used on allend points to identify this application.

● applicationOriginData: Provide information related to theoriginating application node for this message.

27

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 28: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● putApplicationType: Provide either one of the IBMdocumented application type enumerators for this application orone of your choosing. See the IBM WebSphere MQdocumentation for the meaning of the documented applicationtypes. These are the documented enumerations:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMS 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14MQAT_NO_CONTEXT

● putApplicationName: Provide information about theoriginating application in this field.

● userId: Provide the userid to be used when authorizing thismessage as it traverses the messaging system. For operationswith report options, this field is mandatory. If a value is notprovided here, it is taken from the connection resource if one isavailable there, and from the environment if it is not.

● replyToQueueName: Specify the name of an existing queue thatthe target application can use as a destination for its response.This enables the common "request response" pattern.

● replyToQmgrName: Destination queue manager name. The nameof the queue manager on which this queue resides.

A transmission queue and a sender channel must beconfigured for this to work.

● format: Describes the nature of the data in the message. Itdefaults to " ", or MQFMT_NONE. A user defined format can be usedto assist the receiving application in decoding the message, forinstance in the selection of a Data Conversion parse activity forthis message type.

28

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 29: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● expiry: Indicates the length of time (in tenths of a second) thatthe message is kept on the queue before being deleted. Defaultsto -1, which means there is no expiration. This field overridesthe configuration value for expiry if it is mapped. Permissiblevalues are a positive integer or -1.

● priority: The priority (from 1 to 9) of the message. This fieldoverrides a configuration value for priority if it is mapped.

● reportOptionPan: Set this boolean field to add the valuePositive Acknowledgment to the report field of the message.This field is an application only field and is not acted upon bythe queue manager.

● reportOptionNan: Set this boolean field to add the valueNegative Acknowledgment to the report field of the message.This field is an application only field and is not acted upon bythe queue manager.

● report: This is the report options field for the message. Ifnothing is entered then the report options as configured in theAdvanced tab will be used to populate it at runtime, however ifa number is mapped here it will be logically OR'ed with theresults of processing the report options. It is provided to enablethe use of report options not configurable in the Advanced tab.

● encoding: This is the encoding field for the message and itspecifies the representation used for numeric values in theapplication message data. This applies to binary, packed decimaland floating point data. This encoding is used when processingof fields mapped by a message body schema. For specific valuessee the MQMessage encoding field in the WebShere MQdocumentation.

appProperties N Contains fields that correspond to the schema as it is defined in theapplication properties resource that is mapped to this activity.Application properties are included in an MQRFH2 header which isdynamically added to the message.

This node only appears if a properties resource isspecified for the activity.

messageFields N This element will be present when Schema is selected from theMessage Content Type list of the General tab. The contents of themapped schema will be present in this node for mapping purposes.

bytes N Map the main content of the message body here. In general, this isthe output of a Plug-in for Data Conversion render activity, but itcould be any array of bytes. If string data is to be mapped to thisfield, use the XPath function tib:string-to-base64 to convert itto bytes.

29

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 30: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

text N Present if Text is selected in the Message Content Type area. Astring mapped to this field will be converted to bytes using thecharacter set specified for the message.

lastMessageInGroup

N If CustomGroup in the Multi-Message Support area is selected,this field will appear on the input schema. In a custom group it is upto the application to terminate the logical message by setting thisfield to TRUE on the last message.

Output

The Output tab contains the following fields.

Note that some of these fields will be missing or inaccurate if Asynchronous Mode is used.

Field

ModuleProperty? Description

Batch N This node will be present when Batch or BatchGroup in the Muti-Message tab is selected. For each InteractionInput node presentin the input schema, an InteractionOutput node will be presenthere under the Batch node.

InteractionOutput

N The root node for all the output provided by the activity.

30

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 31: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant on input.

● destination: To document the destination for this message. Ifthe queue was a dynamic queue, the generated name is reportedhere.

● destqmgr: To document the remote queue manager specified forthe put operation.

● correlationId: To document the correlation ID, if any.

● messageId: To document the message ID.

● characterSet: To document the character set used by the queuemanager to process this message.

● alternateUserId: As provided in the input schema.

● accountingToken: As provided in the input schema.

● applicationIdData: As provided in the input schema.

● applicationOriginData: As provided in the input schema.

● putApplicationType: As provided in the input schema.

● putApplicationName: As provided in the input schema.

● userId: The effective user ID used to connect to the queuemanager.

● replyToQueueName: Same as input.

● replyToQmgrName: Destination queue manager name. The nameof the queue manager on which this queue resides.

A transmission queue and a sender channel must beconfigured for this to work.

● format: The character string placed into the format element bythe sending application. Plug-in applications do not supportmodification of this field and for those applications it will beempty. However, if a custom application sends the message, itscontents would be visible here.

● expiry: To indicate the number of tenths of a second that themessage is kept on the queue before being deleted. Defaults to-1, which means there is no expiration.

● priority: The priority (from 1 to 9) with which the message wassent.

● reportOptionPan: Set this boolean field to add the valuePositive Acknowledgment to the report field of the message.This field is an application only field and is not acted upon by thequeue manager.

31

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 32: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● reportOptionNan: Set this boolean field to add the valueNegative Acknowledgment to the report field of the message.This field is an application only field and is not acted upon by thequeue manager.

● groupId: To document the group ID, if any.

● messageType: Enumerated value of the chosen message type:

— 8 is Datagram.

— 2 is Reply.

— 4 is Report.

— 1 is Request.

● backoutCount: The number of times this message was backedout before being committed.

● feedback: For a Report message received by a WMQ Get orListener activity, this field defines the nature of the report. Thefield is unused with a value of 0 in Put activities.

● version: To document the version of the message. This Plug-insupports type 2 messages only.

● putDateTime: The time that the message was placed onto thequeue.

● groupStatus: To indicate whether the message is part of alogical message. It can contain any one of the following:

— MSG_IN_GROUP— MSG_NOT_IN_GROUP— MSG_LAST_IN_GROUP

responsetimemillisec

N To indicate, in milliseconds, how long it takes to send the message.

Fault

The Fault tab lists exceptions that are thrown by this activity.

Error SchemaElement Datatype Description

msg string The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ error message.

msgCode string The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ error code.

32

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 33: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Error SchemaElement Datatype Description

mqCompCode string This is the original MQException's completion code, if it was anMQException that triggered the fault.

mqReasonCode string This is the original MQException's reason code, if it was anMQException that triggered the fault.

mqErrorCode string This is the original MQException's error code, if it was anMQException that triggered the fault.

WebSphere MQ GetThe Get activity is used to retrieve a message from a configured queue. Messages can be retrievedbased on filter criteria specified in the input document.

The Get activity can be used to:

● Check the queue with a wait interval. The activity waits on the queue for the specified interval, thenreturns whether or not a message was received.

● Check the queue without a wait interval. The activity checks the queue and returns immediately,regardless of whether a message was read.

● Listen indefinitely on the queue. The activity returns a message if one is available, or waits foreverfor a message to arrive.

General

The General tab contains the following fields.

Field

ModuleProperty? Description

Name N The name to be displayed as the label for the activity in the process.

Connection Y The connection resource which connects this activity with thequeue manager that has access to the desired queue.

Click the icon to select a usable connection for the activity.

Destination Y Enter the name of the queue on which this get should beperformed. This field can be dynamically provided on the inputschema and is not required here.

DynamicDestination

N Select the Dynamic Destination check box to enable dynamicdestinations for this operation. This will enable the DynamicDestination Model field.

DynamicDestinationModel

Y Enter the name of the model queue which the queue manager willuse as a template when constructing this dynamic destination.

33

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 34: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Message ContentType

N Choose the way that the message body will be represented in theoutput schema.

● Binary: The message is an array of bytes suitable for use by theData Conversion Palette activities.

● Text: The message is a string. The message will be decodedusing characterSet for the message, or 819 if none is provided.Characterset 819 is the Java API default.

● Schema: The message will be formatted according to theschema provided in the Message Body Fields field. Values forthis schema will appear in the Output tab.

Message BodyFields

Y Provide the schema to be used in the Output tab, and at runtime toencode the contents of this message.

Close Option N Select the close option for this Get activity. These options are foruse on permanent dynamic queues only.

● NONE: No action is taken.● DELETE: Deletes the queue, if it is empty. If the queue is not

empty, no action is taken.● PURGE: Deletes the queue and any messages on it.

If the Get activity is being performed on a permanent dynamicqueue and the intention is for the queue to be deleted, you shouldchoose either DELETE or PURGE. DELETE will delete the queue ifit is empty, and PURGE will delete the queue and any messagesthat are on it.

Do not select DELETE or PURGE for permanently defined queues.Depending on your security access, this might delete them.

Access Mode N Select the access mode for the queue:

● QDEFAULT: It accepts the access mode established when thequeue is created.

● SHARED: It allows other listeners to access the queue.● EXCLUSIVE: It does not allow other listeners to access the

queue. If another WebSphere MQ application has the queueopen, this activity fails.

Fail If Quiescing N Select this check box to cause the activity to fail and exit if thequeue manager attempts to quiesce. Failure to do so will causequiesce operations to take much longer.

34

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 35: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

GMO Convert N Causes the get message option MQGMO_CONVERT to be used for thisget operation. It will cause the queue manager to convert string andnumeric fields using the characterSet and encoding elementsbefore the data is copied to the message buffer.

Wait Forever N If the Wait Forever check box is selected, the Get activity will waitforever for a message on the queue. When cleared, the WaitTimeout field is enabled.

The Wait Forever check box is selected by default.

Wait Timeout Y The number of milliseconds this activity waits for a message beforefailing. If significant wait intervals are allowed, a separate threadpool should be used.

This field is not available if the Wait Forever check box is selected.

ApplicationProperties

Y Select the application properties resource to be used to map theoutput of this Get activity. Application properties are similar toregular message header fields except that the name and type of thefields can be determined by a predefined schema. If the receivedmessage contains properties, they are mapped according to thisschema.

To use application properties create a generic XML schemacomposed of a node with simple elements inside it and map thatschema to this field. See the IBM WebSphere documentation forproperty types supported by the level of client you have installed.

A failure to observe cardinality will result in errorsprocessing the input or output schema.

Logger Name Y Enter the name of any logger which has been configured for theruntime to write to. If no logger name is provided then the defaultone is used. The activity writes informational messages to the logdepending on how the logger is configured.

Description

Provide a short description for the activity.

Multi-Message

The Multi-Message tab contains the following field.

35

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 36: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

Multi-MessageSupport

N This value can be None, BatchGroup or CustomGroup.

● None: In this mode, the Get activity operates as though it isexpecting a non logical ordinary message from the queue.However, there is no way to prevent it from getting the firstmember of a logical message if it exist. The Complete Message,and Get Ordered fields apply. If the activity is not in a localtransaction, it will operate without a sync-point for efficiency.

The Syncopist Used indicator will be off.

● BatchGroup: In this mode the get is expecting to get either agroup of individual messages (in which case the Batch Size fieldwill control how many messages are retrieved) or a LogicalMessage. If the activity is not in a local transaction the entiremulti message operation will occur within a single unit of work,otherwise it will occur in the unit of work represented by thelocal transaction. Because it is not possible to filter out logicalmessages, if a normal message is fetched, and then a logicalmessage is encountered the entire logical message will beincluded with the normal message in one operation regardless ofthe Batch Size value. If the intention is to process LogicalMessages only, the batch size should be set to 1. The CompleteMessage and Get Ordered fields are in effect.

● CustomGroup: In this mode the activity will get a singlemessage from the queue and store the context of this message forsubsequent use. This mode is intended to be used in a loop toiteratively process the contents of a Logical Message. The outputschema field groupStatus will indicate whether the message isin a group and whether or not is is the last message with thecontents: MSG_IN_GROUP, MSG_NOT_IN_GROUP,MSG_LAST_IN_GROUP. This field should be used to determinewhen to terminate the loop. Unless the activity is a localtransaction it will commit the contents of each get as they areperformed.

Batch Size N If BatchGroup mode is in effect, this field becomes enabled. Enterthe number of discrete messages which are to make up this batchget. The output schema will contain a node for each messageretrieved. If a timeout occurs while the batch is incomplete then theincomplete batch will be processed and no exception will be thrown.

CompleteMessage

N Selecting the Complete Message check box causes the get to wait fora logical message to be complete before returning any of themessages. When clearing the Complete Message check box, alogical message need not be complete for the get to work, which ishandy for processing damaged messages, or messages which areintended to be processed as they are written to the queue. It has noeffect on non logical messages.

36

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 37: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

Get Ordered N When the Get Ordered check box is selected, it requires that alogical message be processed in the order it was written to thequeue. Therefore the first get on a message will require that messagenumber 1 be present, so it must be disabled to process partial(damaged) logical messages. The queue must be indexed for this towork. If the queue is not indexed, this option will be dynamicallyswitched off.

ExplicitCommit

N Every attempt is made within the plug-in to avoid unnecessarycommits due to the overhead involved. However you might selectthe check box to force the creation of a unit of work and subsequentcommit. The commit happens after any application properties andmessage body fields have been processed, so selecting this check boxprotects you from removing a message from the queue only to failwhile processing the contents. Message contents can cause failuresif, for instance, the encoding or character set is in appropriate for thedata, or the schema used to process the message is in error.

SyncpointUsed

N This is a status indicator only and does not represent anyconfiguration information. It indicates whether the activity will runwith a sync-point in effect and therefore require a subsequentcommit operation. Every effort has been made to avoid unnecessarycommits. The flag may be off if the activity is in a local transaction,but there will still be a sync-point in place on behalf of thetransaction, so it is irrelevant in that case.

Input

The Input tab contains the following fields.

FieldModuleProperty? Description

InteractionInput

N The root node for all the input provided to the activity.

37

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 38: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant on input.

● destination: Override the destination queue name with thestring specified in this field.

● destqmgr: The name of the remote queue manager from whichto fetch the message.

The queue managers involved must be configuredwith the necessary sender and receiver channels inplace and started.

● correlationId: Provide a correlation identifier for this messageby mapping a byte array to this field. The XPath statement tib:string-to-base64 ("correlationid") is sufficient topopulate this field. The provided correlation ID is used to filtermessages from the queue.

● messageId: Specify a message ID. This value overrides thedefault value generated by the queue manager. The rules are thesame as for correlationId. If a message ID is provided, it isused to filter the get results.

● characterSet: Sets the IBM Coded Characterset ID of thismessage. Valid values are:

— 850: The commonly used ASCII codeset.

— 819: The ISO standard ASCII codeset.

— 37: The American EBCDIC codeset.

— 1200: Unicode

— 1208: UTF-8

The queue manager may apply this codeset when doingconversions for the purpose of creating report messages.

● alternateUserId: Specify a userid to be used as an alternateuser for this operation only. The user used in the connectionresource must have the Alternate Userid Authority in order touse this field.

● waitInterval: Specify a new get timeout value for thisoperation only. It is the number of milliseconds that theoperation will wait before timing out. If the Wait Forever checkbox in the General tab is selected , this field will be ignored.

Output

The Output tab contains the following field.

38

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 39: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

Batch N If BatchGroup is selected for this activity, this Batch node will bethe high level item for the activity and will contain a number ofInteractionOutput nodes equal to or less than the Batch Sizeparameter depending on how many messages are availablewithin the timeout period. If a logical message is fetched from thequeue there will be a node in the output for each member of thelogical message.

InteractionOutput

N The root node for all the output provided by the activity.

39

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 40: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant on output.

● destination: To document the destination for this message. Ifthe queue was a dynamic queue, the generated name isreported here.

● destqmgr: The name of the remote queue manager supplied inthe input schema.

● correlationId: To document the message correlation ID, ifany

● messageId: To document the message ID.

● characterSet: To document the character set the queuemanager used to process this message.

● alternateUserld: If the get operation is intended to beconducted using the authentication capabilities of a differentuserid than the one on the connection resource enter thatuserid here.

You must have authorization to use this capability.The provided userid is in effect for only thisoperation.

● accountingToken: The accounting token provided by thesending application.

● applicationIdData: Application ID data. This is theapplication data provided by sender of the message.

● applicationOriginData: Origin data as provided by eitherthe sender of the message or the queue manager.

40

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 41: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

● putApplicationType: The type of application that put themessage.

Documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMS 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14MQAT_NO_CONTEXT

● putApplicationName: Application name data as provided byeither the sender of the message or the queue manager.

● userId: The effective user ID used to connect to the queuemanager.

● replyToQueueName: The name of the queue to which a replyshould be sent. If the type of the message is Request, then thisis the name of the queue that the application should send thereply message to.

● replyToQmgrName: The name of the remote queue manager forthis message's reply-to destination, if one was provided.

● format: TO describe the nature of the data in the message. Thesender of the application can use standard names (thesenames are prefixed by the MQ text) or application-generatednames. If the message originated from a TIBCO ActiveMatrixBusinessWorks Plug-in for WebSphere MQ application, this isan empty string.

● expiry: The expiration time (in tenths of a second), afterwhich the message is eligible to be discarded by the queuemanager.

The default value of -1 means there is no expiration.

● priority: The priority (from 1 to 9) with which the messagewas sent.

41

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 42: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

● reportOptionPan: This is the Positive Acknowledgmentreport field and is provided by the sending application. Thisreport field is not acted upon by the queue manager.

● reportOptionNan: This is the Negative Acknowledgmentreport field and is provided by the sending application. Thisreport field is not acted upon by the queue manager.

● groupId: To document the group ID used for this message, ifany.

● messageType: Enumerated value indicating the message type:

— 8 is Datagram.

— 2 is Reply.

— 4 is Report.

— 1 is Request.

● backoutCount: The number of times this message was backedout before being committed.

● feedback: If the message was a Report message, this fielddefines the nature of the report. Defaults to 0 for non reportmessages.

● version: To document the version of the message. This Plug-in supports type 2 messages only.

● putDateTime: The time that the message was placed onto thequeue.

● groupStatus: To indicate whether the message is part of alogical message. It can contain any of the following:

— MSG_IN_GROUP— MSG_NOT_IN_GROUP— MSG_LAST_IN_GROUP

appProperties N This field maps the application properties present in the receivedmessage to the schema attached to the activity. Properties whichare missing or not present in the schema are not shown here.

messageFields N Contain the message body formatted using Schema in theMessage Content Type list of the General tab.

Appear for schema based messages only.

bytes N If the activity is configured to use binary messages then this fieldcontains the output body of the message. Typically, this bytearray is to be mapped as input to a TIBCO ActiveMatrixBusinessWorks Plug-in for Data Conversion parse activity.

This field is only displayed if the activity is configured to in theBinary mode.

42

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 43: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

text N If the activity is configured to use text for the payload, this fieldwill be present and contain the contents of the message decodedas a string.

This field is only displayed if the activity is configured to in theText mode.

responsetimemillisec

N To indicate how long it took to receive the message. This valueincludes any time spent waiting on an empty queue.

Fault

The Fault tab lists the possible exceptions thrown by this activity.

Fault Thrown when..

msg The descriptive text provided by this exception object.

msgCode If the message has a BW message code it will be mapped to this field.

mqCompCode If the message originated as a WebSphere MQ API exception, then thatexception's completion code will be here.

mqReasonCode If the message originated as a WebSphere MQ API exception, then thatexception's reason code will be here.

mqErrorCode If the message originated as a WebSphere MQ API exception, then thatexception's error code will be here.

WebSphere MQ ListenerThe WebSphere MQ Listener activity listens on a queue and when a message arrives that satisfies theconfigured filters it retrieves and it starts a process including the contents of the message.

The listener can poll a queue based on interval and a timeout values, or it can wait indefinitely on aqueue. Regardless of which mode it is in, when messages arrive on the queue they are each processedimmediately with no intervening interval time.

General

The General tab contains the following fields.

FieldModuleProperty ? Description

Name N The name to be displayed as the label for the activity in the process.

Connection Y The connection resource which connects this activity with the queuemanager that has access to the desired queue.

43

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 44: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty ? Description

Instances Y Enter the number of instances of the queue listener you wish thisactivity to run. This translates exactly the number of threads andconnections to the Queue Manager created by this activity.

The default is 1 and the maximum is 64.

If the Require Client Confirmation check box is selected below,each thread this activity runs will wait for the confirmation beforegetting another message from the queue. Therefore, to processmessages in an absolute serial fashion, only one instance of thelistener should be started. In this case, the number of messagesprocessed becomes a function of how much latency exists in theactivity prior to the confirmation.

Destination Y The name of the queue from which the message will be retrieved.

DynamicDestination

N A flag that enables the creation of a dynamic queue. When selected,the Dynamic Destination Model field is enabled.

DynamicDestinationModel

Y Provide the name of the model queue after which this dynamicqueue will be patterned. This field is only available if the aboveDynamic Destination check box is selected.

It is recommended that static queue names (queue namesthat do not contain a pattern) be used for listeneractivities. Should a pattern be used for a Listener activityqueue name, then the name generated by the queuemanager is not available until the listener creates aprocess which makes it impossible for a sender to knowthe name.

MessageContent Type

N Select the type of message content:

● Binary: The body of the message will be represented as a bytearray to subsequent activities in the process and will becontained in the bytes element.

● Text: The body of the message will be represented as a string tosubsequent activities in the process and will be contained in thetext element. This string will be converted from the bytes in themessage using the characterSetelement in effect for thismessage.

● Schema: If the message has been written using the MQMessageread/write API calls, it can be rendered here by providing aschema resource that conforms to the schema of the message.

Message BodyFields

Y If the message has been written using the MQMessage read/writeAPI calls, use this field to map a schema conforming to the messagebody.

44

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 45: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty ? Description

Fail IfQuiescing

N Select the Fail If Quiescing check box to prevent this listener fromholding up a queue manager quiesce operation. If the queuemanager does terminate, the activity attempts to reconnectindefinitely.

Access Mode N Select the access mode for the queue:

● QDEFAULT: It accepts the access mode established when thequeue was created.

● SHARED: It allows other listeners to access the queue.● EXCLUSIVE It does not allow other listeners to access the queue.

During execution, if the queue is open by another applicationthen the activity fails.

GMO Convert N Causes the get message option MQGMO_CONVERT to be used for thisget operation. It will cause the queue manager to convert string andnumeric fields using the characterSet and encoding elementsbefore the data is copied to the message buffer.

Require ClientConfirmation

N Select the Require Client Confirmation check box to request explicitconfirmation of a received message.

The confirm activity can be used to confirm the message’s arrivaland remove it from the queue. The Plug-in uses the queuemanager's Syncpoint capability to ensure that the message is onlyremoved from the queue if it is confirmed.

The activity will wait for the confirmation beforeobtaining another message which imposes an absolutelimit on the throughput. If serial processing of themessages is not essential, raise the Instances parameteruntil either the worker threads are 100% busy or thedesired throughput is achieved.

If the activity fails to confirm the message, it will loop andrepeatedly process the same message.

Logger Name Y Enter the name of any pre-configured logger available to theruntime. Loggers are configured in an XML document referenced bythe Dlogback.configurationFile runtime parameter.

Description

Provide a short description for the activity.

Multi-Message

The Multi-Message tab contains the following fields.

45

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 46: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty ? Description

Multi-MessageSupport

N Two options are supported:

● None● BatchGroup

If BatchGroup is selected, an activity started by a listener to operatein batch mode that contains multiple InteractionOutput nodes,each representing one message in the batch. The Batch Size fieldwill be enabled allowing you to determine the number of discretemessages to be included in the batch. When None is selected, theListener activity processes a single message at one time from thequeue.

The main improvement that Batch Mode offers is all messages in thebatch are committed by a single call thus eliminating continualround trips which reduces network traffic and latency involved withcommitting each message individually. The size of the batch for aPut activity is determined by the number of nodes in the inputschema.

If explicit client confirmation is selected for a batch, theentire batch will be confirmed when the confirmationactivity runs. Enabling Batch Mode eliminates theconfirmation of individual messages, so if an error isdetected while processing a message, the entire batchmust be reprocessed.

Batch Size Y If BatchGroup is selected, this field becomes enabled. Enter validinputs range from 2 to 100 to control the size of the batchesretrieved by this listener.

CompleteMessage

N Enable this field to cause the listener to only process the firstmember of a logical message when all the members of the logicalmessage have been written to the queue. This must be deselectedwhen processing incomplete logical messages and when processinghuge logical messages one message at a time.

Get Ordered N Select this field to cause logical messages to be processed in theorder in which they were created. To process incomplete logicalmessages, you should not select this field. This option requires thatthe queue be indexed, otherwise it will be disabled dynamically atruntime.

ExplicitCommit

N Every attempt is made within the plug-in to avoid unnecessarycommits due to the overhead involved. However you might selectthe check box to force the creation of a unit of work and subsequentcommit. The commit happens after any application properties andmessage body fields have been processed, so selecting this check boxprotects you from removing a message from the queue only to failwhile processing the contents. Message contents can cause failuresif, for instance, the encoding or character set is in appropriate for thedata, or the schema used to process the message is in error.

46

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 47: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty ? Description

SyncpointUsed

N This field is not a configuration parameter, but is a status indicationof whether the activity is configured to require a sync-point or not.Because of the cost of sync-point operations every effort has beenmade to avoid them. If the activity requires a confirmation or usesmultiple messages a sync will be required.

Advanced

The Advanced tab contains the following fields.

FieldModuleProperty? Description

Sequence Key N This field can contain an XPath expression that specifies whichprocesses should run, and in which in order. Process instances withsequencing keys that evaluate to the same value are executedsequentially in the order the process instance was created.

See TIBCO ActiveMatrix BusinessWorks Process Design Guide for moreinformation about controlling the execution order of processinstances and about XPath expressions.

Custom Job Id N This field can contain an XPath expression that specifies a custom IDfor the process instance. This ID is displayed in the View Servicedialog of TIBCO Administrator, and it is also available in the$_processContext process variable.

Enable Polling N When selected, the activity instantiates a connection to the queuemanager and opens the queue. It then periodically issues timed getson the queue where the timeout value is equal to the polling timeoutand the period between gets is equal to the polling interval.

However, if there are multiple messages on the queue they areprocessed without an intervening polling interval, thus diminishingapplication latency.

When cleared, the activity waits forever on the queue, processingmessages as they arrive. If the queue manager connection fails theactivity attempts to reconnect based on the reconnection interval.

A poor choice of polling interval and polling timeoutvalues could impose a high overhead on the engine aswell as the queue manager to which the activity isconnected. Use values here which take into account thelatency in the network between this activity and the queuemanager, as well as the processing demands you arewilling to place on that queue manager.

47

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 48: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

PollingInterval

Y If the Enable Polling check box is selected, this is the interval atwhich a new polling cycle is initiated.

Specify time in milliseconds.

Valid range: 100 to 1000000

Default: 1000

PollingTimeout

Y If the Enable Polling check box is selected, this is the timeout valuefor each individual listen. The value specified here should besignificantly smaller than the Polling Interval. This minimizes thenumber of concurrent connections to the queue and reduces theprocessing resources needed.

Specify time in milliseconds.

Valid range: 10 to 1000000

Default: 1000

ReconnectionInterval

Y The length of time, in milliseconds, that the listener waits betweenattempts to reconnect to the queue.

This setting is used only when the Enable Polling check box iscleared. If the Enable Polling check box is cleared, the Listeneractivity listens indefinitely on the queue. However, if an error occursand the queue manager is subsequently unavailable (shut down forinstance), this value is the number of milliseconds betweenreconnection attempts.

Valid range: 2000 to 1000000

Default: 10000

Correlation Id Y The Listener activity instructs the queue manager to filter therequest based on this correlation ID. Only messages with exactly thesame ID are accepted.

WebSphere MQ uses byte arrays for correlation IDs.However, it is not possible to provide a byte array as aconfiguration parameter. When filtering a queue this way,be sure to use a clear text correlation ID on the applicationthat did the put.

Message Id Y The Listener activity instructs the queue manager to filter therequest based on the specified message ID.

In contrast to correlation IDs, message IDs are alwaysprovided. If the listener does not explicitly state a messageID, it accepts any message. If an ID is provided, the listenis filtered for that message ID.

48

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 49: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

ApplicationProperties

Y Select the Application Properties resource to be used to map theoutput of this get. Application properties are similar to regularmessage header fields except that the name and type of the fieldscan be determined by a predefined schema. If the received messagecontains properties, they are mapped according to this schema.

To use application properties create a generic XML schemacomposed of a node with simple elements inside it and map thatschema to this field. See the IBM WebSphere documentation forproperty types supported by the level of client you have installed.

A failure to observe cardinality will result in errorsprocessing the input or output schema.

Output

The Output tab contains the following fields.

Field

ModuleProperty? Description

Batch N If BatchGroup in the Multi-Message Support area is selected, thisnode will be present and will contain an InteractionOutput nodefor each message retrieved as part of this batch.

InteractionOutput

N The root node for all the output provided by the activity.

49

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 50: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant on output.

● destination: To document the destination for this message. Ifthe queue was a dynamic queue, the generated name is reportedhere.

● destqmgr: If the message was routed through a remote queuemanager, documents the name of the destination queuemanager.

● correlationId: To document the message correlation ID, ifany.

● messageId: To document the message ID.

● characterSet: To document the character set the queuemanager used to process this message.

● alternateUserId: Specify a userid to be used as an alternateuser for this operation only. The user used in the connectionresource must have the Alternate Userid Authority in order touse this field.

● accountingToken: The accounting token provided by thesending application.

● applicationIdData: Application ID data as provided by thesending application.

● applicationOriginData: Additional information about theorigin of the message provided by the sender of the message.

50

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 51: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● putApplicationType: The type of application that put themessage.

Documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMSQ 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14MQAT_NO_CONTEXT

● putApplicationName: The name of the application that put themessage.

● userId: The effective user ID used to connect to the queuemanager.

● replyToQueueName: The name of the queue to which a replyshould be sent. If the type of the message is Request, then this isthe name of the queue that the application should sent the replymessage to.

● replyToQueueMgrName: The name of the remote queue managerto be used when processing any reply or report message.

● format: A name that describes the nature of the data in themessage. The sender of the application can used standard names(these names are prefixed by the text MQ) or applicationgenerated names. If this message originated from a TIBCOActiveMatrix BusinessWorks Plug-in for WebSphere MQ, thenthis field contains an empty string.

● expiry: The expiration time (in tenths of a second), after whichthe message is eligible to be discarded by the queue manager.This contains whatever value was used when the message wassent.

● priority: The priority (from 1 to 9) with which the messagewas sent.

51

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 52: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● reportOptionPan: This is the Positive Acknowledgment reportfield and is provided by the sending application. This reportfield is not acted upon by the queue manager.

● reportOptionNan: This is the Negative Acknowledgmentreport field and is provided by the sending application. Thisreport field is not acted upon by the queue manager.

● report: This is the report options field for the message. Ifreports were requested for the message, the relevant bits will bepresent here.

● encoding: This is the encoding element for the message and itspecifies the representation used for numeric values in theapplication message data. This applies to binary, packeddecimal and floating point data. This encoding element is usedwhen processing of fields mapped by a message body schema.For specific values see the MQMessage encoding field in theWebShere MQ documentation.

● groupId: To document the group ID used for this message, ifany.

● messageType: Enumerated value indicating the message type.

Where:

● 8 is Datagram.

● 2 is Reply.

● 4 is Report.

● 1 is Request.

● backoutCount: The number of times this message was backedout before being committed.

● feedback: If the message was a Report message, this fielddefines the nature of the report. Defaults to 0 for non reportmessages.

● version: To document the version of the message. This Plug-insupports type 2 messages only.

● putDateTime: The time that the message was placed onto thequeue.

● groupStatus: To indicate whether the message is part of alogical message. It can contain:

— MSG_IN_GROUP— MSG_NOT_IN_GROUP— MSG_LAST_IN_GROUP

52

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 53: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

bytes N The output body of the message. Typically, this byte array is to bemapped as input to a Data Conversion Plug-in parse activity.

This field is only displayed if the activity is configured to use theBinary mode.

text N If the activity is configured to use text messages then this node willbe present in the bytes field. The contents of the message will bedecoded into a string using the Java default encoding andpresented here.

This field is only displayed if the activity is configured to in theText mode.

responsetimemillisec

The time, in milliseconds, that the listener took to receive thismessage. It is measured from when the listener started listening towhen it has finished creating the event context passed to theremaining activities in this process.

appProperties N This field maps the application properties present in the receivedmessage to the schema attached to the activity and only displays ifapplication properties are mapped on the Advanced tab. Propertieswhich are missing or not present in the schema are not shown here.

messageFields N Contain the message body formatted using Schema in the MessageContent Type list of the General tab.

Appear for schema based messages only.

Fault

The Fault tab lists exceptions that are thrown by this activity.

Error SchemaElement Data type Description

msg string The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ error message.

msgCode string The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ error code.

mqCompCode string If the message is originated as a WebSphere MQ API exception, thenthat exception's completion code will be here.

mqReasonCode string If the message is originated as a WebSphere MQ API exception, thenthat exception's reason code will be here.

53

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 54: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

WebSphere MQ PublishThe WebSphere MQ Publish activity publishes a message to a dynamic or a predefined topic.

The activity is capable of sending any of the four message types described in the WebSphere MQ Putactivity. The capabilities of the activity are determined by the configuration, with some runtimebehaviors controlled by the input schema. The type of message being sent might determine what fieldsare applicable for the publish operation, for instance request messages are incompatible with reportoptions. Even though this is a pub/sub type of activity, the report and reply-to queues are real queuesnot topics.

In WebSphere MQ, a topic is defined as a string of characters starting with a forward slash key (/) andcan contain many topic nodes to the right. WebSphere MQ supports a mechanism for separatingadministratively-defined topic strings from application-defined ones. This is exposed on the publishactivity by the Destination field and the Topic Dynamic field. The intent is that administrativelydefined portions of the topic string are represented by selecting a permanently defined topic for thefirst part of the topic string and concatenating the dynamic portion to the right. This way an applicationcan be deployed in several environments without naming conflicts.

There is no difference between the message object published by this activity from the one sent by thePut activity.

General

The General tab contains the following fields.

FieldModuleProperty? Description

Name N The name to be displayed as the label for the activity in theprocess.

Connection Y The connection resource which associates this activity with thequeue manager that has access to the desired topic.

Click to select a usable connection for the activity.

Destination Y The name of the administratively defined topic to which themessage will be published. This field is optional in the eventthat the topic string is to be entirely specified in the TopicDynamic field or the input schema.

Topic Dynamic Y The contents of this field are concatenated to the topic namereferenced by the administratively defined topic above. If noadministratively defined topic is provided this string forms theentire topic string.

54

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 55: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

Message ContentType

N Two types message content are supported:

● Binary: The bytes field in the input schema to map bytearray data onto the outgoing message.

● Text: The text field in the output schema onto whichregular string data can be mapped. At runtime this stringwill be converted to bytes using the default Java encoding.

● Schema: Select Schema to write the message body such thatit conforms to a schema. The schema to be used is designedas a sharable resource and mapped to the field below.

Message BodyFields

Y Provide the schema to be used in the Input tab, and at runtimeto encode the contents of this message.

Message Type N Select the type of message that is to be sent:

● Datagram● Request● Reply● Report

If a Request message is selected, the Reply To Destination fieldis enabled and the report options are disabled. All othermessage types allow report options.

Reply ToDestination

Y This Reply To Destination field is enabled only when theRequest message type is selected from the Message Type list.This field contains the queue name which will be placed into thereplyToQueueName field in the Input tab. Click Choose a field

value type besides the Reply To Destination field to selectthe queue.

Retain Message N Select the Retain Message check box to indicate that themessage is to be retained in the queue manager even if nosubscribers exist. This allows future subscribers to receive themessage when they are created. This is useful for conveyingapplication state information.

Fail If Quiescing N Select the Fail If Quiescing check box to prevent this activityfrom holding up a queue manager quiesce operation.

55

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 56: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

ApplicationProperties

Y Select a schema which represents the application properties tobe placed in this message. To use application properties create ageneric XML schema composed of a node with simple elementsinside it and map that schema to this field.

See the IBM WebSphere documentation for property typessupported by the level of client you have installed.

A failure to observe cardinality will result in errorsprocessing the input or output schema.

Logger Name Y Enter the name of any pre-configured logger available to theruntime. Loggers are configured in an XML documentreferenced by the Dlogback.configurationFile runtimeparameter.

Description

Provide a short description for the activity.

Advanced

The Advanced tab contains the following fields.

Field

ModuleProperty? Description

Message Priority Y Set the priority of the message as it is to be retrieved by the queuemanager. The values range from 0 to 9. If not specified, the defaultis the destination queue's default priority.

56

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 57: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Context Support N The input fields of a put operation fall into categories based ontheir context. Many fields are always present, but others are onlypresent if the context relevant to that field is chosen. This is becausethe queue manager must grant the user the authorization to updatethese fields.

Select one of the following settings:

● Default: The input schema will conform to the fields accessibleto a user with the default authority.

● Identity: The input schema will conform to the fields accessibleto a user with the Set Identity Context authority.

The new fields are:

● accountingToken

● applicationIdData

● userId

● All: The input schema will conform to the fields accessible to auser with the Set Identity Context and Set All Contextauthorities.

The new fields (in addition to those provided by Identity) are:

● applicationOridinData

● putApplicationType

● putApplicationName

Confirm OnArrival

N Trigger a report message by using the Confirm on arrival type. Thereport is not enabled by default.

Report types are:

● NONE: The report is not enabled.● NO_DATA: The body of the message does not accompany the

report.● WITH_DATA: The first 100 bytes of the message body

accompanies the report.● FULL_DATA: The entire body of the message accompanies the

report.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive with theRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

57

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 58: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Confirm OnDelivery

N Trigger a report message by using the Confirm on delivery type.The report is not enabled by default.

Report types are:

● NONE: The report is not enabled.● NO_DATA: The body of the message does not accompany the

report.● WITH_DATA: The first 100 bytes of the message body

accompanies the report.● FULL_DATA: The entire body of the message accompanies the

report.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive with theRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

Confirm OnException

N Trigger a report message by using the Confirm on exception type.The report is not enabled by default.

Report types are:

● NONE: The report is not enabled.● NO_DATA: The body of the message does not accompany the

report.● WITH_DATA: The first 100 bytes of the message body

accompanies the report.● FULL_DATA: The entire body of the message accompanies the

report.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive with theRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

58

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 59: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Confirm OnExpiry

N Trigger a report message by using the Confirm on expiry type. Thereport is not enabled by default.

Report types are:

● NONE: The report is not enabled.● NO_DATA: The body of the message does not accompany the

report.● WITH_DATA: The first 100 bytes of the message body

accompanies the report.● FULL_DATA: The entire body of the message accompanies the

report.

Reports are delivered to the reply to queue specified in the ReportReply Queue field. Because this field maps to the message'sreplyToQueueName field, reports are mutually exclusive with theRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

Report ReplyQueue

Y Enter the name of the queue to which Report messages should besent. The value entered here maps onto the replyToQueueNamefield.

AsynchronousPut*

N Select the check box to achieve a modest improvement in thelatency of the Put activity if your application can tolerate thepotential for an unreported failure writing to the queue. See theIBM WebSphere documentation for the put message optionMQPMO_ASYNC_RESPONSE for more information regarding the risksof this option.

Input

The Input tab contains the following fields.

Field

ModuleProperty? Description

InteractionInput

N This input schema field is the root node for all the input provided tothe activity.

59

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 60: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

mqproperties N The node containing all the message header fields (plus thedestination override) that are relevant on input.

● destination: Specify a destination here in order to override thetopic name from the configuration panels.

● destqmgr: Destination queue manager name. The name of thequeue manager on which this topic resides.

A transmission queue and a sender channel must beconfigured for this queue manager for it to work.

● topicdynamic: The dynamic portion of the topic string. This canbe the entire topic string and will override any dynamic topicspecified on the configuration panel.

● correlationId: To provide a correlation identifier for thismessage by mapping a byte array to this field. The XPathexpression tib:string-to-base64 ("correlationid") issufficient to populate this field. This field is only valid if the topicreferenced is an administratively defined unmanaged topic. Inall other cases it will be ignored by the queue manager.

Consult the IBM WebSphere MQ documentation for descriptionsof managed and unmanaged subscriptions.

● messageId: To provide a message identifier for this message bymapping a byte array to this field. The XPath expressiontib:string-to-base64 ("messageId") is sufficient topopulate this field. This field is only valid if the topic referencedis an administratively defined unmanaged topic. In all othercases it will be ignored by the queue manager.

● characterSet: To set the IBM Coded Characterset ID of thismessage.

Valid values are:

● 850: The commonly used ASCII codeset.

● 819: The ISO standard ASCII codeset.

● 37: The American EBCDIC codeset.

● 1200: Unicode.

● 1208: UTF-8.

The queue manager might apply this codeset when doingconversions for the purpose of creating report messages.

● alternateUserId: To specify a userid to be used as an alternateuser for this operation only. The user used in the connectionresource must have the Alternate Userid Authority in order touse this field.

● accountingToken: To provide a binary (base 64 encoded)accounting token to be used on host systems to assist inaccounting for resources used by the application.

60

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 61: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● applicationIdData: To provide a string that can be used on allend points to identify this application.

● applicationOriginData: To provide information related to theoriginating application node for this message.

● putApplicationType: To provide either one of the IBMdocumented application type enumerators for this application orone of your choosing.

See the IBM WebSphere MQ documentation for the meaning ofthe documented application types.

The documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMSQ 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14MQAT_NO_CONTEXT

● putApplicationName: The name of the application that put themessage. Provide information about the originating applicationin this field.

● userId: To provide the userid to be used when authorizing thismessage as it traverses the messaging system. For operationswith report options, this field is mandatory. If a value is notprovided here, it is taken from the connection resource if one isavailable there, and from the environment if it is not.

● replyToQueueName: To specify the name of an existing queuethat the target application can use as a destination for itsresponse. This enables the common "request response" pattern.

● replyToQmgrName: Destination queue manager name. The nameof the queue manager on which this queue resides.

A transmission queue and a sender channel must beconfigured for this to work.

61

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 62: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● format: To describe the nature of the data in the message. Itdefaults to a space character or MQFMT_NONE. A user definedformat can be used to assist the receiving application in decodingthe message, for instance in the selection of a Data Conversionparse activity for this message type.

● expiry: To indicate the length of time (in tenths of a second) thatthe message is kept on the queue before being deleted. Defaultsto -1, which means there is no expiration. This field overridesthe configuration value for expiry if it is mapped.

Permissible values are positive integers or -1.

● priority: The priority (from 1 to 9) of the message. This fieldoverrides a configuration value for priority if it is mapped.

● reportOptionPan: This is the Positive Acknowledgment reportfield and is provided by the sending application. This reportfield is not acted upon by the queue manager.

● reportOptionNan: This is the Negative Acknowledgment reportfield and is provided by the sending application. This reportfield is not acted upon by the queue manager.

● report: This is the report options field for the message. Ifnothing is entered then the report options as configured in theAdvanced tab will be used to populate it at runtime, however ifa number is mapped here, it will be logically OR'ed with theresults of processing the report options. It is provided to enablethe use of report options not configurable in the Advanced tab.

● encoding: This is the encoding field for the message and itspecifies the representation used for numeric values in theapplication message data. This applies to binary, packed decimaland floating point data. This encoding is used when processingof fields mapped by a message body schema.

For specific values see the MQMessage encoding field in theWebShere MQ documentation.

bytes N Map the main content of the message body here. In general, this isthe output of a Plug-in for Data Conversion render activity, butcould be any array of bytes. If string data is to be mapped to thisfield, use the XPath function tib:string-to-base64 to convert it tobytes.

This field is only displayed if the activity is configured to in theBinary mode.

text N This field contains a text representation of the bytes in the messagebody as converted using the default Java encoding.

This field is only displayed if the activity is configured to in the Textmode.

62

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 63: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

appProperties N Contains fields that correspond to the schema as it is defined in theapplication properties resource that is mapped to this activity.

The appProperties node is only present if a WMQProperties Resource has been configured for the activity.

messageFields N This element will be present when Schema is selected from theMessage Content Type list of the General tab. The contents of themapped schema will be present in this node for mapping purposes.

Output

The Output tab contain the following fields.

Field

ModuleProperty? Description

InteractionOutput N The root node for all the output provided by the activity

63

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 64: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant on input.

● destination: To document the destination for this message.If the topic was a dynamic topic, the generated name isreported here.

● destqmgr: To document the remote queue manager specifiedin the input schema.

● topicdynamic: To document the effective topic string for thispublication. This includes the root portion from anyadministratively defined topic provided, as well as the anydynamic portion.

● correlationId: To document the message correlation ID, ifany.

● messageId: To document the message ID.

● characterSet: To document the character set the queuemanager used to process this message.

● alternateUserId: To specify a userid to be used as analternate user for this operation only. The user used in theconnection resource must have the Alternate UseridAuthority in order to use this field.

● accountingToken: As provided in the input schema.

● applicationIdData: As provided in the input schema.

● applicationOriginData: As provided in the input schema.

● putApplicationType: As provided in the input schema.

● putApplicationName: As provided in the input schema.

● userId: The effective user ID used to connect to the queuemanager.

● replyToQueueName: Same as input.

● replyToQmgrName: Same as input.

● format: The character string placed into the format field bythe sending application.

● expiry: Indicates the number in tenths of a second that themessage is to be kept on the queue before being deleted.Defaults to -1, which means there is no expiration.

● priority: The priority (from 1 to 9) with which the messagewas sent.

● reportOptionPan: This is the Positive Acknowledgmentreport field and is provided by the sending application. Thisreport field is not acted upon by the queue manager.

64

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 65: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● reportOptionNan: This is the Negative Acknowledgmentreport field and is provided by the sending application. Thisreport field is not acted upon by the queue manager.

● report: This is the report options field for the message. Ifnothing is entered then the report options as configured in theAdvanced tab will be used to populate it at runtime, howeverif a number is mapped here, it will be logically OR'ed with theresults of processing the report options. It is provided toenable the use of report options not configurable in theAdvanced tab.

● encoding: This is the encoding field for the message and itspecifies the representation used for numeric values in theapplication message data. This applies to binary, packeddecimal and floating point data. This encoding element isused when processing of fields mapped by a message bodyschema. For specific values see the MQMessage encodingfield in the WebShere MQ documentation.

● groupId: To document the group ID assigned to the messageby the queue manager.

● messageType: Enumerated value indicating the message type.

Where:

● 8 is Datagram.

● 2 is Reply.

● 4 is Report.

● 1 is Request.

● backoutCount: The number of times this message was backedout before being committed.

● feedback: If the message was a Report message, this fielddefines the nature of the report. Defaults to 0 for non reportmessages.

● version: To document the version of the message. This Plug-in supports type 2 messages only.

● putDateTime: The time that the message was placed onto thequeue.

● groupStatus: To indicate the logical message status of amessage. Pub/Sub does not support logical messages so thisfield will be empty.

responsetimemillisec

N To indicate, in milliseconds, how long it took to publish themessage.

65

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 66: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Fault

The Fault tab lists exceptions that are thrown by this activity.

Error SchemaElement Data type Description

msg string The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ error message.

msgCode string The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ error code.

mqCompCode string If the message is originated as a WebSphere MQ API exception, thenthat exception's completion code will be here.

mqReasonCode string If the message is originated as a WebSphere MQ API exception, thenthat exception's reason code will be here.

mqErrorCode string If the message is originated as a WebSphere MQ API exception, thenthat exception's error code will be here.

WebSphere MQ SubscriberThe subscriber activity listens on a topic or administratively defined subscription and starts a processthat provides the contents of the message.

The subscriber can poll a topic based on interval and a timeout values, or it can wait indefinitely.Regardless of which mode it is in, when messages arrive they are each processed immediately with nointervening interval time. When polling is enabled, messages published to the subscribed topic are notlost during the interval when the subscriber is not actively listening because the subscriber exists for theduration and is not created and destroyed across intervals. However, this does not necessarily applyduring error recovery or lost connection scenarios.

The topic string is composed of two optional parts:

● An administratively defined topic. This option implies a root topic string defined on the server.● A dynamic topic string which is concatenated to the topic string for the defined topic, if one is

specified.

If neither of these fields is provided but an existing durable subscription is specified, the activitysubscribes to the durable subscription.

The queue manager inserts the forward slash (/) as necessary to compose a well formed topic string.

While the listener is active, a temporary dynamic subscription is created (in the queue manager) so thatall messages appropriate for the topic are routed there. This subscription will cease to exist when thelistener is stopped, or in error recovery. In order to avoid missing messages destined for the topic, youcan enable the Durable Subscription option to have the subscription persisted indefinitely in the queuemanager using the name provided. Durable subscriptions accumulate messages even when there are nolisteners, much like a queue would.

General

The General tab contains the following fields.

66

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 67: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

Name N The name to be displayed as the label for the activity in the process.

Connection Y Choose the connection resource which associates this activity withthe queue manager that has access to the desired topic.

Click to select a usable connection for the activity.

Destination Y The name of the administratively defined portion of the topic string.If a topic name is specified, the topic string associated with thatname in the queue manager forms the root or left-most portion ofthe topic string.

WildcardScheme

N WebSphere MQ supports two wild card schemes:

● Topic: Associated with current queue managers.● Char: Associated with version 6 and earlier of WebSphere MQ.

Either scheme can be used. Consult the WebSphere MQdocumentation for information about these schemes.

Topic Dynamic Y Enter the dynamic portion of the topic string here. This field cancontain the entire topic string or only the right-most portion of it,depending on whether it is to be used in conjunction with anadministratively defined topic.

DurableSubscription

N When selected, the subscription created by this subscriber isdurable. Durable subscriptions survive subscriber and queuemanager restarts, and accumulate messages until they are explicitlydeleted.

SubscriptionName

Y Enabled if the Durable Subscription check box is selected. This isthe name of the permanent subscription.

A subscriber can be started using only the durable subscriptionname. If the subscription exists, no topic string or dynamic topic arenecessary.

MessageContent Type

N Two types message content are supported:

● Binary: The bytes field in the output schema is provided andcontains a byte array representing the messages contents.

● Text: The text field in the output schema is provided andcontains a string composed by decoding the message's bytearray using the default Java encoding.

● Schema: If the message has been written using the MQMessageread/write API calls it can be rendered here by providing aschema resource that conforms to the schema of the message.

Message BodyFields

Y Provide the schema to be used in the Output tab, and at runtime todecode the contents of this message.

67

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 68: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

NewPublicationsOnly

N Select the New Publications Only check box for non-durablesubscriptions where you do not want to receive the last messagepublished with the Retain Message option. In essence, this is a wayof opting out of the application state message.

Fail If Quiescing N Select the Fail If Quiescing check box to prevent this subscriberfrom holding up a queue manager quiesce operation. If the queuemanager does terminate, the activity attempts to reconnectindefinitely.

GMO Convert N Causes the get message option MQGMO_CONVERT to be used for thisGet operation. It will cause the queue manager to convert string andnumeric fields using the characterSet and encoding elementsbefore the data is copied to the message buffer.

Require ClientConfirmation

N Select the Require Client Confirmation check box to requestexplicit confirmation of a received message.

The confirm activity can be used to confirm the message’s arrivaland remove it from the queue. The Plug-in uses the queuemanager's Syncpoint capability to ensure that the message is onlyremoved from the queue if it is confirmed.

The activity will wait for the confirmation beforeobtaining another message which imposes an absolutelimit on the throughput. If serial processing of themessages is not essential, raise the Instances parameteruntil either the worker threads are 100% busy or thedesired throughput is achieved.

If the activity fails to confirm the message, it will loop andrepeatedly process the same message.

Logger Name Y Enter the name of any pre-configured logger available to theruntime. Loggers are configured in an XML document referencedby the Dlogback.configurationFile runtime parameter.

Description

Provide a short description for the activity.

Advanced

The Advanced tab contains the following fields.

68

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 69: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

Sequence Key N This field can contain an XPath expression that specifies whichprocesses should run, and in which in order. Process instances withsequencing keys that evaluate to the same value are executedsequentially in the order the process instance was created.

See TIBCO ActiveMatrix BusinessWorks Documentation for moreinformation about controlling the execution order of processinstances and about XPath expressions.

Custom Job Id N This field can contain an XPath expression that specifies a custom IDfor the process instance. This ID is displayed in the View Servicewizard of TIBCO Administrator, and it is also available in the$_processContext process variable.

Enable Polling N When selecting the Enable Polling check box, the activityinstantiates a connection to the queue manager and opens the topic.It then periodically issues timed gets on the topic where the timeoutvalue is equal to the polling timeout and the period between gets isequal to the polling interval. However, if there are multiplemessages available, they are processed without an interveningpolling interval, thus diminishing application latency.

When clearing the Enable Polling check box, the activity waitsindefinitely on the topic, processing messages as they arrive. If thequeue manager connection fails, the activity attempts to reconnectbased on the reconnection interval.

A poor choice of polling interval and polling timeoutvalues could impose a high overhead on the engine aswell as the queue manager to which the activity isconnected. Use values here which take into account thelatency in the network between this activity and the queuemanager, as well as the processing demands you arewilling to place on that queue manager.

PollingInterval

Y If the Polling Interval check box is selected, this is the interval atwhich a new polling cycle is initiated. Specify time in milliseconds.

Valid range: 100 to 1000000

Default: 1000

PollingTimeout

Y If the Polling Interval check box is selected, this is the timeout valuefor each individual listen. The value specified here should besignificantly smaller than the value in the Polling Interval field.This minimizes the number of concurrent connections to the queueand reduces the processing resources needed.

Specify time in milliseconds.

Valid range: 10 to 1000000

Default: 1000

69

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 70: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

FieldModuleProperty? Description

ReconnectionInterval

Y The length of time, in milliseconds, that the listener waits betweenattempts to reconnect to the topic.

This setting is used only when polling is disabled. If polling is notenabled, the listener listens indefinitely on the queue. However, if anerror occurs and the queue manager is subsequently unavailable(shut down for instance), this value is the number of millisecondsbetween reconnection attempts.

Valid range: 2000 to 1000000

Default: 10000

ApplicationProperties

Y If the messages expected on this topic contain application specifictopics, a shared schema resource should be created to representthose properties and it should be mapped here. Messages whichcontain any or all of these properties will have them provided asinput to the process created by this starter. To use applicationproperties create a generic XML schema composed of a node withsimple elements inside it and map that schema to this field.

See the IBM WebSphere documentation for property typessupported by the level of client you have installed.

A failure to observe cardinality will result in errorsprocessing the input or output schema.

Output

The Output tab contains the following fields.

Field

ModuleProperty? Description

InteractionOutput N The root node for all the output provided by the activity.

70

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 71: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant on input.

● destination: To document the destination for this message.This field contains the complete topic string for the message.

● destqmgr: To document the remote queue manager specifiedon the input schema.

● topicdynamic: To override the Topic Dynamic field from theGeneral tab. This string forms the dynamic portion of the fullyresolved topic name.

● correlationId: To document the message correlation ID. Inmost cases this is an internal queue manager value and is notavailable for filtering purposes.

● messageId: To document the message ID.

● characterSet: To document the character set the queuemanager used to process this message.

● alternateUserId: To specify a userid to be used as analternate user for this operation only. The user used in theconnection resource must have the Alternate Userid Authorityin order to use this field.

● accountingToken: The accounting token that allows workdone as a result of the message to be appropriately billed.

● applicationIdData: Application ID data. This is applicationdata was provided by sender of the message.

● applicationOriginData: Additional information about theorigin of the message provided by the sender of the message.

71

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 72: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● putApplicationType: The type of application that put themessage.

Documented enumerations are:MQAT_AIX MQC.MQAT_AIX 0x06 MQAT_CICS MQC.MQAT_CICS 0x01MQAT_DOS MQC.MQAT_DOS 0X05 MQAT_IMS MQC.MQAT_IMS 0X03MQAT_MVS MQC.MQAT_MVS 0X02MQAT_OS2 MQC.MQAT_OS2 0X04MQAT_OS400 MQC.MQAT_OS400 0X08 MQAT_QMGR MQC.MQAT_QMGR 0X07 MQAT_UNIX MQC.MQAT_UNIX 0X06MQAT_WINDOWS MQC.MQAT_WINDOWS 0X09 MQAT_JAVA MQC.MQAT_JAVA 0X1C MQAT_UNKNOWN MQC.MQAT_UNKNOWN -1 or 0XFFFFFFFF MQAT_NO_CONTEXT MQC.MQAT_NO_CONTEXT 0X00 MQAT_CICS_VSE MQC.MQAT_CICS_VSE 0X0AMQAT_VMS MQC.MQAT_VMSQ 0X0C MQAT_GUARDIAN MQC.MQAT_GUARDIAN 0X0D MQAT_VOS MQC.MQAT_VOS 0X0E MQAT_DEFAULT MQC.MQAT_DEFAULT 0X1C MQAT_NSK MQC.MQAT_NSK 0X0D MQAT_CICS_BRIDGE MQC.MQAT_CICS_BRIDGE 0X15 MQAT_NOTES_AGENT MQC.MQAT_NOTES_AGENT 0X16 MQAT_WINDOWS_NT MQC.MQAT_WINDOWS_NT 0X0B MQAT_IMS_BRIDGE MQC.MQAT_IMS_BRIDGE 0X13 MQAT_XCF MQC.MQAT_XCF 0X14MQAT_NO_CONTEXT

● putApplicationName: The name of the application that put themessage, if one was provided.

● userId: The effective user ID used to connect to the queuemanager.

● replyToQueueName: The name of the queue to which a replyshould be send if the message is a request.

● replyToQmgrName: If this message arrived by way of a remotequeue manager specification, this field documents the queuemanager to which this subscriber is connected.

● format: A name that describes the nature of the data in themessage.

● expiry: The expiration time (in tenths of a second), after whichthe message is eligible to be discarded by the queue manager.This contains whatever value was used when the message wassent.

● priority: The priority (from 1 to 9) with which the messagewas sent.

● reportOptionPan: This is the Positive Acknowledgment reportfield and is provided by the sending application. This reportfield is not acted upon by the queue manager.

72

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 73: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

● reportOptionNan: This is the Negative Acknowledgmentreport field and is provided by the sending application. Thisreport field is not acted upon by the queue manager.

● report: This is the report options field for the message.Reflects the report options in effect for this message.

● encoding: This is the encoding element for the message and itspecifies the representation used for numeric values in theapplication message data. This applies to binary, packeddecimal and floating point data. This encoding is used whenprocessing of fields mapped by a message body schema. Forspecific values see the MQMessage encoding field in theWebShere MQ documentation.

● groupId: The group ID of the message, if it was part of agroup.

● messageType: Enumerated value indicating the message type:

— 8 is Datagram.

— 2 is Reply.

— 4 is Report.

— 1 is Request.

● backoutCount: The number of times this message was backedout before being committed.

● feedback: If the message was a Report message, this fielddefines the nature of the report. Defaults to 0 for non reportmessages.

● version: To document the version of the message.

● putDateTime: The time that the message was placed onto thetopic.

● groupStatus: To indicate whether the message is part of alogical message. It can contain any of the following:

— MSG_IN_GROUP— MSG_NOT_IN_GROUP— MSG_LAST_IN_GROUP

bytes N The output body of the message. Typically, this byte array is to bemapped as input to a Data Conversion Plug-in parse activity.

This field is only displayed if the activity is configured to in theBinary mode.

73

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 74: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Field

ModuleProperty? Description

text N This field contains a text representation of the bytes in the messagebody as converted using the default Java encoding.

This field is only displayed if the activity is configured to in theText mode.

responsetimemillisec

N This field records the time, in milliseconds, that it takes to start theWebSphere MQ get API call until the event context for the newactivity is created.

appProperties N This field maps the application properties present in the receivedmessage to the schema attached to the activity. Properties whichare missing or not present in the schema are not shown here.

The field is only displayed if an application properties schema isconfigured for the activity.

messageFields Contain the message body formatted using Schema in theMessage Content Type list of the General tab.

Appear for schema based messages only.

Fault

The Fault tab lists exceptions that are thrown by this activity.

Error SchemaElement Data type Description

msg string The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ error message.

msgCode string The TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ error code.

mqCompCode string If the message is originated as a WebSphere MQ API exception, thenthat exception's completion code will be here.

mqReasonCode string If the message is originated as a WebSphere MQ API exception, thenthat exception's reason code will be here.

74

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 75: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Miscellaneous

Miscellaneous describes how TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ is usedwith TIBCO Active matrix BusinessWorks Plug-in for Data Conversion and WebSphere MQ.

Transactions with WebSphere MQThe plug-in for WebSphere MQ has its own type of local transaction called MQ. The Get and Putactivities enclosed in such a transaction group have their queue manager resources enlisted with thislocal transaction and when it ends, all the queue actions will be committed.

TIBCO ActiveMatrix BusinessWorks 6.0 has enhanced supports for local transactions.

If activities within a single MQ local transaction use different queue managers, the resources will becommitted at the end of the transaction one queue manager at a time. Therefore if the second or thirdqueue manager fails to commit, the queues can be left in an inconsistent state. For this reason it isadvisable to confine local MQ transactions to queues involving a single queue manager.

Data Conversion Plug-in with WebSphere MQThe plug-in, together with TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion, providesActiveMatrix BusinessWorks with the ability to encode XML-structured data into byte sequences to besent to a WebSphere MQ-capable application.

The plug-in does not attempt to provide tools for the manipulation of the message body itself. Thisrequirement is fulfilled by TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion. Messagescan be free form text (like XML documents) or they can have internal structure. In the case of mostlegacy applications, that structure is usually expressed in the form of a copybook document like thisone: * *===========================================================*

75

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 76: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

* * TIBCO Mainframe sample COBOL Copybook * * *===========================================================*

01 WS-IVP-FIELDS. 05 IVP-ID PIC X(8) USAGE DISPLAY. 05 IVP-DESCR PIC X(56) USAGE DISPLAY. 05 IVP-RESULT PIC X(80) USAGE DISPLAY. 05 IVP-BES-NAME PIC X(8) USAGE DISPLAY. 05 IVP-BES-TRAN-ID PIC X(8) USAGE DISPLAY. 05 IVP-BES-PGM-NAME PIC X(8) USAGE DISPLAY. 05 IVP-USERID PIC X(8) USAGE DISPLAY. 05 IVP-START-TIME PIC X(8) USAGE DISPLAY. 05 IVP-REPLY-TIME PIC X(8) USAGE DISPLAY. 05 IVP-SUBJ-SFX PIC X(30) USAGE DISPLAY. 05 IVP-TYPE PIC X(1) USAGE DISPLAY. 05 IVP-BES PIC X(1) USAGE DISPLAY. 05 IVP-WRITES PIC S9(8) USAGE COMP. 05 IVP-BES-TASKNO PIC S9(8) USAGE COMP. 05 IVP-BES-DELAY PIC S9(8) USAGE COMP. 05 IVP-BTCH-SEQ-NO PIC S9(8) USAGE COMP. 05 IVP-START-DATE-CHAR PIC X(16) USAGE DISPLAY. 05 IVP-START-TIME-CHAR PIC X(16) USAGE DISPLAY. 05 IVP-REPLY-DATE-CHAR PIC X(16) USAGE DISPLAY. 05 IVP-REPLY-TIME-CHAR PIC X(16) USAGE DISPLAY.

TIBCO ActiveMatrix BusinessWorks Plug-in for Data Conversion converts copybooks to XML schemasfor use in other activities. The Data Conversion Plug-in render and parse activities convert canonicaldata to memory based formats and vice-versa. If your WebSphere MQ project converses with anapplication that uses these formats, simply create Data Conversion Plug-in activities that represent themessage structure for those applications and pipe the values in and out of message activities tocommunicate with them, the following figure shows how canonical data is converted using the DataConversion Plug-in:

Creating Secure Connections to the Queue ManagerYou can create a secure connection between the plug-in and the WebSphere MQ queue manager byusing Transport Layer Security (TLS).

There are many variables that control secure connections, and all must be correctly enabled for TLS tofunction. If problems occur, it may be difficult to identify the source. The Troubleshooting section offersa few suggestions to aid in identifying the source of any problems.

Procedure

1. Configure the WebSphere MQ queue manager to accept TLS connections.

2. Create a keystore for the certificates and trusts used by the queue manager.See Setting Up WebSphere MQ Queue Manager for more details. The WebSphere MQ queuemanager configuration is covered extensively in the IBM documentation. If any of the terms used inthis section are unfamiliar, review the IBM documentation for clarification.

3. Configure TIBCO ActiveMatrix BusinessWorks to connect using TLS.See Setting Up TIBCO ActiveMatrix BusinessWorks for more details.

76

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 77: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Setting Up WebSphere MQ Queue ManagerTo create a secure connection to WebSphere MQ queue manager, you need to set up WebSphere MQqueue manager.

This section introduces how to enable the WebSphere MQ queue manager to accept TLS connections byusing the sample that is provided by the plug-in. You must create a keystore for the certificates andtrusts used by the queue manager.

These examples use self-signed certificates. Although self-signed certificates are acceptable in a designenvironment, they should never be used in production.

Procedure

1. Create IBM keystores for the queue manager and client by using a given script in the plug-insamples directory.The following steps describes the configuration of the queue manager to use certificates generatedby the script using the command: createQueueManagerKeystore.sh/var/mqm/qmgrs/qmwn/sslqmwn password.

2. Configure the queue manager to use generated keystore.

3. Use the IBM Key Management Tool to Review the Personal Certificate Name.

4. Creating a TLS Connection for the Queue Manager.

5. Verify that all SSL files can be read by the mqm group.

Verify the security of all the files in the directory which you configured as the SSL Key Repositoryproperty of the queue manager are readable by the mqm group. This is the security group mqm thatwas created during the installation of WebSphere MQ on the platform. If they are not, adjust theiraccess properties or the queue manager will not be able to read them.The queue manager is now capable of making a secure connection with a client. Using the Plug-in,you can now create a TLS-secured connection to the queue manager.

Creating IBM Keystores for the Queue Manager and Client

Each end of the TLS connection must have a keystore. A sample script is included in the plug-in'ssamples directory to create keystores for the queue manager and client.

Setting up WebSphere MQ queue manager relies on certificates generated using this script. The script isannotated, and is intended to be used as a template to aid you in the creation of your own scripts. Usethis script to assist in the creation of TLS connections in an evaluation or development environmentonly. Because all the certificates created by the script are self-signed, they are inappropriate forproduction use.

Location of the Script

Versions of the script are available for UNIX and Windows. The scripts are:

● UNIX

TIBCO_HOME/bw/palettes/bwmq/8.1/samples/createQueueManagerKeystore.sh

● Microsoft Windows

TIBCO_HOME\bw\palettes\bwmq\8.1\samples\sslcert.bat

Script Syntax

Run the script on the platform based on your requirements. For example, on the UNIX system runningthe command: createQueueManagerKeystore.sh keystordir qm-name keystore-password

77

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 78: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

where:

● keystoredir is the directory in which to create the keystores. This can be a working directory or theSSL directory in the queue managers data directory, so long as the queue manager's keystore iseventually placed in the location configured in its SSL parameters.

● qm-name is the name of the queue manager for which the keystore is being created. This name mustuse lower case characters only.

● keystore-password is the password used to secure the keystore.

You may either customize the scripts to produce keystores that suit your environment's standards, orenter the commands discretely to accomplish the same thing.

Output of the Script

The objective of each script is to produce two IBM CMS type keystores, each containing an identity andthe other's signing CA certificate. That way, a TLS connection can be instantiated using one keystore ateach end.

Running this script generates a number of files, most importantly:

● qm-name.sth is the stash file for the queue managers key store.

● qm-name.kdb is the IBM CMS format keystore for the queue manager.

● client.kdb is the IBM CMS format keystore to be used to make a Java keystore for the client.

Configuring the Queue Manager to Use Generated Keystore

After the script has created the keystores, you must configure the queue manager to use the generatedkeystore.

In the Plug-in's example, the keystore is named qmwn.kdb and the queue manger name is qmwn. Toconfigure the queue manager, set its SSL Key Repository parameter to this file without the suffix. Thekeystore created with the example in Step 1 is /var/mqm/qmgrs/qmwn/ssl/qmwn.kdb. The value for thecorresponding key database for the queue manager would be /var/mqm/qmgrs/qmwn/ssl/qmwn.

The following figure WebSphere MQ shows an example of the IBM WebSphere MQ Explorer queuemanager properties for SSL.

78

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 79: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Using the IBM Key Management Tool to Review the Personal Certificate Name

The IBM Key Management tool is used to open the keystore, and it is normally started by the script inthe mqm/bin/strmqikm directory, and the executable is called iKeyMan.

The Personal Certificate name must use all lower case characters. If your queue manager name containsupper case characters, rename this alias so that all characters are in lower case. If this alias is not correct,the queue manager will not be able to open the keystore.

IBM Key Management tool (iKeyMan) does not allow you simply change an uppercase character to alowercase character. To retain the same name, you will have to use an intermediate name for therename function to work.

You can also review the CA certificate that was copied using the script to instruct the queue manager to"trust" the client’s certificate. To see this information, select Signer Certificates from the list below theKey database content heading.

The following figure shows the keystore created in Step 1. Note the name of the personal certificate isibmwebspheremqqmwn. This special alias is composed of the tag ibmwebspheremq with the name of thequeue manager concatenated onto it. In this example, the queue manger name is qmwn.

79

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 80: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Creating a TLS Connection for the Queue Manager

Using the IBM WebSphere MQ Explorer, create a server connection channel for the new queue managerand set its SSL properties so that client authorization is enabled (if desired) and a cipher suite isselected.

For example, TRIPLE_DES_SHA_US is a specification which should have a matching cipher inBusinessWorks.

The terms SSL and TLS are used interchangeably in the IBM documentation, and most of the parametersettings for TLS are labeled SSL. Insofar as this document is concerned, TLS is functionally equivalentto SSL V3.

The following figure (SSL Cipher Suite Selection) shows the SSL setting configured using the IBMWebSphere MQ Explorer tool.

80

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 81: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Setting Up TIBCO ActiveMatrix BusinessWorksAfter setting up WebSphere MQ queue manager, you can configure TIBCO ActiveMatrixBusinessWorks to use the secure channel.

Procedure

1. In TIBCO Business Studio, open an existing project or create a new one.

2. Create a WebSphere MQ Connection.

3. Configure the shared resource.a) In the General panel, type a name in the Name field.b) In the Queue Manager Connection Configuration panel, click Remote in the Binding area.c) Enter remote connection values in the Host Name, Port, User Name, Password, and Server

Channel Name fields.d) In the Pooling Configuration panel, select Pooling Enabled check box.See WebSphere MQ Connection for more information about the configuration.

4. Start the IBM Key Manger tool using the strmqikm program.This program is located in the mqm/bin directory in the WebSphere MQ server installation.

81

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 82: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

5. Using the IBM Key Manager, open the client keystore created by the script during the Setting UpWebSphere MQ Queue Manager.

6. Create a Java keystore from the contents of the IBM keystore.a) Select the client identity alias, and click Save As on the File menu.b) Change the keystore type to JKS and enter a new name for the client keystore in the Save As

dialog.This is the file that you reference from the connection resource, as pictured above.

c) Set the Key file type to JKS.d) Click Save.e) At the prompt, enter a password to be used with the keystore.

7. Specify the WebSphere MQ connection shared resource created in Step 2.a) Select the Transport Layer Security check box in the TLS Configuration panel.

b) click beside the TLS Configuration field.This allows you to create an SSL Client Configuration resource.

8. Configure the SSL Client Configuration resource.a) In the General panel, type a name in the Name field.

b) In the Basic SSL Client Configuration panel, click beside the Keystore Provider as TrustStore field.This allows you to create a Keystore Provider resource.

82

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 83: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

9. Configure the Keystore Provider resource.a) In the General panel, type a name in the Name field.b) Select SUN from the Provider list.c) In the URL field, specify the java keystore used for the credentials of this connection.d) Specify the value in the Password field.e) Select JKS from the Type list.

10. In the created SSL Client Configuration resource, select TLSv1 from the SSL Protocol list.

See TIBCO ActiveMatrix BusinessWorks Bindings and Palettes Reference for more information about theconfiguration.

83

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 84: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

TroubleshootingYour may encounter some errors while creating secure connections to the Queue Manager. By verifyingsimple details these errors can be resolved.

Following are some of the possible errors you may encounter and their resolutions.

● If you don't know the correct cipher, leave the field blank and press Test Connection. It will cyclethrough all the available ciphers until it finds one that works and report it in the status dialog to theright. If no cipher is accepted you may have to change the configuration of the server channel.

● Disable client authentication. This means that the queue manager will not check that it trusts thesigner of the plug-in's certificate. If it works with client authentication disabled but not with itenabled, then the two parties do not have all the signing CA certificates in place.

● Check the queue manager's log files. These files are in the queue manager's work directory under"errors". For the queue manager above, this file is:

/var/mqm/qmgrs/qmwn/errors/AMQERR01.LOG

A typical error from that file looks like:

----- amqrmrsa.c : 889 --------------------------------------------------------12/07/2012 02:46:09 PM - Process(15433.5) User(jsmith) Program(amqrmppa) Host(bilbo.jrr.org) Installation(Installation1) VRMF(7.5.0.0) QMgr(qmwn) AMQ9660: SSL key repository: password stash file absent or unusable.

EXPLANATION:The SSL key repository cannot be used because MQ cannot obtain a password toaccess it. Reasons giving rise to this error include: (a) the key database file and password stash file are not present in the location configured for the key repository, (b) the key database file exists in the correct place but that no password stash file has been created for it, (c) the files are present in the correct place but the userid under which MQ is running does not have permission to read them, (d) one or both of the files are corrupt.

The channel is '????'; in some cases its name cannot be determined and so isshown as '????'. The channel did not start.ACTION:Ensure that the key repository variable is set to where the key database fileis. Ensure that a password stash file has been associated with the key databasefile in the same directory, and that the userid under which MQ is running hasread access to both files. If both are already present and readable in thecorrect place, delete and recreate them. Restart the channel.----- amqccisa.c : 5540 -------------------------------------------------------12/07/2012 02:46:09 PM - Process(15433.5) User(jsmith) Program(amqrmppa) Host(bilbo.jrr.org) Installation(Installation1) VRMF(7.5.0.0) QMgr(qmwn)

This error occurred because the queue manager does not have read permission to the files in the SSLdirectory. This happened because the default file creation mask does not allow group read.

Plug-in with Large MessagesWebSphere MQ cannot accept an arbitrarily large message. It has restrictions based on the size of thebuffers in the queue manager and its various channels. The preferred method for dealing withmessages too large for the queue manager or an intermediate channel to accept is to segment themessage.

The plug-in supports explicit segmentation, whereby the message is split into segments by the plug-initself as well as automatic segmentation performed by the queue manager. See the Multiple-Messagestab of the Put activity for more information.

84

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 85: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Segmented messages are not supported on z/OS.

Sending and Receiving Long MessagesActivities that support logical messages have a Multi-Message tab on which the sending and receivingof logical messages can be configured.

When getting a message from a queue which has or may have logical messages, it is important toconfigure these options to prevent the inadvertent removal of a member of a group, the followingfigure shows the Multi-Message tab in the Put activity.

Message Groups

Both the put and get operations support operating message groups.

● The put operation, there are three ways to send a multiple message group through the plug-in:

— The Batch option does not create a group but it allows you to send all the messages configuredthrough the input schema in a single logical unit of work. Each node in the input schema iscomposed into a message and is sent within the bounds of a sync-point. When the nodes aresent successfully, a commit is performed. If this is done within the context of an MQ LocalTransaction, the commit is deferred until the transaction scope ends.

— The BatchGroup option sends all the messages represented by the input schema as members ofa single logical message. Commit boundaries are the same as for a Batch group.

— The CustomGroup option allows you to use a sequence of the put operations to create a logicalgroup. You can turn on the last message flag in the input schema for the last message or makethe group fail. You can also use a loop to create the logical message. TIBCO recommends youperform these operations within the context of an MQ Local Transaction to make the commitboundaries explicit.

● The get operation supports the Batch and BatchGroup operations. In the Batch mode, messages areretrieved until the specified size of the batch is reached and then returned to the activity asindividual nodes on the output Batch schema. This is done as a single unit of work and iscommitted when the activity completes unless it is inside an MQ Local Transaction. TheBatchGroup mode fetches the contents of an entire logical message and returns it as a batch. Thecommit semantics are the same as for Batch gets.

If the None option is selected, an a logical message is encountered and the first member ofthe logical message will be fetched and returned from the activity. This breaks the logicalmessage structure, so take note when accessing queues, which contain logical messages.The Complete Message and Get Ordered flags can be turned off to access the members ofbroken groups.

For get and put operations, the Multi-Message tab contains the Synpoint Used check box, which is nota configuration option, but an indication of whether the operation requires the use of a sync-point.Sync-points impose a significant overhead on queue operations so you should avoid using the gets andputs operations for a single message. However for groups of messages it is efficient to process thegroup within a single sync-point.

Segmented Messages

Both the Get and Put activities support segmented messages.

85

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 86: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

The Get activity creates segmented messages if messages are slices of a larger message. The segmentedmessages are always concatenated together to reconstitute the original message after the operation.Individual segments may not differ in terms of the message context or other fields on the input schema.The Get activity always returns a single reconstituted message when a segmented message isencountered.

The Put activity creates a segmented message if Explicit is selected in the Segmentation field and themessage is larger than the size provided. The queue manager automatically creates segment messagesif Queue Manager is selected in the Segmentation field. If Both is selected in the Segmentation field, itmeans both the Explicit and Queue Manager options are selected.

The segmented message feature is not supported by WebSphere MQ on z/OS.

Message FiltersWhen reading messages from WebSphere MQ, you can limit which messages are read using messagefilters.

The Get and Listen activities allow you to read only messages that match a specified correlation ID ormessage ID.

● Assigning IDs

These values are assigned to the WebSphere MQ message when it is created. You can specify thedesired ID using the mqproperties element in the Input tab of the Put activity. However, mostapplications let the queue manager automatically generate an identifier.

● Specifying Filters

Filters can be set for Get and Listen activities.

● For Get activities, the filter can be set using the correlationId and messageId elements in theInput tab. These elements are grouped under the mqproperties element heading.

● For Listen activities, the filter is set using the Correlation Id and Message Id fields in theAdvanced tab.

Filter Scenario: Request-Reply

One common use for filters is in a request-reply interaction. In this scenario, a message publisher puts aRequest message on the queue that is handled by a service application. The Request message specifiesa Reply To Queue name, indicating the queue where the requestor will look for the reply message.

Because the same Reply to Queue is often used by many message requestors, the message requester canuse the correlation ID generated by the Put activity to identify those reply messages that are sent inresponse to its own request.

To enable this functionality, map the correlationId element from the Output tab of the Put activity tothe correlationId element in the Input tab of the Get activity that will read the reply message.

It is the responsibility of the application replying to the request to set the correct correlation ID in thereply message. The correlation ID is present in the request message header.

Filter Scenario: Reports

Filters can also be used to identify the confirmation of delivery report associated with a put message.

When a put message activity requests a delivery report using the report element in the Input tab, thequeue manager puts a report message onto the specified Report Reply Queue queue.

Correlation IDs are used to relate the original put message to the report messages. Using the PassCorrelation ID check box, you choose whether the original message ID or correlation ID is used for thereport message correlation ID.

86

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 87: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

As in the previous scenario, the process can pass the correlationId element shown in the Output tabof the Put activity to the correlationId element in the Input tab of Get activity that will read thereport messages.

87

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 88: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

Managing Logs

Logs are used to trace and troubleshoot the plug-in exceptions.

A logback.xml file is located in the TIBCO_HOME\bw\6.0\config\design\logback directory. Updatethis file to set up log levels and export logs to a file.

Log LevelsThe plug-in captures logs at different levels.

Log Level Description

Info Indicates normal plug-in operations. No action is needed. A tracing messagetagged with Info indicates that a significant processing step is reached andlogged for tracking or auditing purposes. Only info messages preceding atracking identifier are considered as significant steps.

Warn Indicates that an abnormal condition is found. Processing continues, but specialattention from an administrator is recommended.

Error Indicates that an unrecoverable error has occurred. The activity will fail and anexception will be provided.

Debug Indicates a developer-defined debug message.

Setting Up Log LevelsBy default, the log level is Error . The plug-in allows you to change the log level to trace differentmessages.

If neither the plug-in log nor the BusinessWorks log is configured in the logback.xml file, the errorlogs of the plug-in will be displayed in the Console view by default.

If the plug-in log is not configured but the BusinessWorks log is configured in the logback.xml file, theconfiguration for the BusinessWorks log is implemented by the plug-in.

Procedure

1. Navigate to the TIBCO_HOME\bw\6.0\config\design\logback directory and open thelogback.xml file.

2. Add the following node in the Console Appender area to specify the log level for the plug-in.<logger name="com.tibco.bw.palette.bwmq.runtime"> <level value="DEBUG"/></logger>

The level tag defines the log level and the value is Error or Debug.

When the level is set to Debug, the input and output for the plug-in activities are alsodisplayed in the Console view. See Log Levels for more details regarding each log level.

88

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide

Page 89: TIBCO ActiveMatrix BusinessWorks Plug-in for … Overview TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows users to design and implement ActiveMatrix BusinessWorks

3. Optional: Add the following node in Console Appender area to specify the log level for an activity.<logger name="com.tibco.bw.palette.bwmq.runtime.ActivityNameActivity"> <level value="DEBUG"/></logger>

For example, if you want to set the log level of the Put activity to Debug, you need to add thefollowing node:<logger name="com.tibco.bw.palette.bwmq.runtime.PutActivity"> <level value="DEBUG"/></logger>

For the activities that do not configure with specific log levels, they still inherit log levelconfigured for the plug-in or BusinessWorks.

4. Save the file.

Exporting Logs to a FileModify the logback.xml file to export plug-in logs to a file.

Procedure

1. Navigate to the TIBCO_HOME\bw\6.1\config\design\logback directory and open thelogback.xml file.

When deploying an application in TIBCO Enterprise Administrator, you need tonavigated to the TIBCO_HOME\bw\domains\mydomain\appnodes\myspace\mynodedirectory to find the logback.xml file.

2. Add the following node to specify the file location.<appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>c:/bw6-mq.log</file> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36}-%msg%n</pattern> </encoder></appender>

The file tag defines the location to which the log is exported and the value is the absolute path ofthe file.

You also need to add the file name in the file path.

3. Add the following node to the root node at the bottom of the logback.xml file to enable exportingthe logs to a file. <appender-ref ref="FILE" />

<root level="DEBUG"> <appender-ref ref="STDOUT" /> <appender-ref ref="FILE" /></root>

4. Save the file.

89

TIBCO ActiveMatrix BusinessWorks™ Plug-in for WebSphere MQ User's Guide


Recommended