tibco activematrix businessworks plug-in for websphere mq ... · pdf filethe plug-in supports...

TIBCO ActiveMatrix BusinessWorks™ Plug-infor WebSphere MQ User's GuideSoftware Release 8.2November 2014

Two-Second Advantage®

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

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

WebSphere MQ Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

WebSphere MQ Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

WebSphere MQ Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

WebSphere MQ Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

WebSphere MQ RequestReply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

WebSphere MQ Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

WebSphere MQ Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79

Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Transactions with WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

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

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

Setting Up WebSphere MQ Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

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

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

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

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

Setting Up TIBCO ActiveMatrix BusinessWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Plug-in with Large Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Sending and Receiving Long Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Message Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Managing Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

3


Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Setting Up Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Exporting Logs to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

4


TIBCO Documentation and Support Services

All TIBCO documentation is available on the TIBCO Documentation site, which can be found here:

https://docs.tibco.com

Product-Specific Documentation

Documentation for TIBCO products is not bundled with the software. Instead, it is available on theTIBCO Documentation site. To directly access documentation for this product, double-click thefollowing file:

TIBCO_HOME/release_notes/TIB_bwmq_version_docinfo.html

The following documents for this product can be found on the TIBCO Documentation site:

● 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 on the TIBCODocumentation site:

● 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


https://docs.tibco.com

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

https://support.tibco.com

http://www.tibcommunity.com

Plug-in Overview

TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows you 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 TIBCO ActiveMatrixBusinessWorks Plug-in for Data Conversion, which allows TIBCO ActiveMatrix BusinessWorksapplications to use IBM standard copybooks to interface with legacy applications using severaltransport 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 software installed to determine if the features youwant 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 RequestReply activity that sends a request type message to a queue, and then

waits for a response in the configured reply queue. Multi-message formats are not supported forthis activity. With the Put and Get activities, you can manually construct a request/reply processusing logical or segmented messages.

● A WebSphere MQ Listener activity that gets a message from a queue as a process starter. Eachprocess 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


About WebSphere MQ Messages

TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphere MQ allows you 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 the 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 be used to parse and render suchcomplex message bodies.

7


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. At run time,you can run and deploy EAR files. Therefore, you can manage Businessworks applications in TIBCOEnterprise Administrator (TEA).

A typical workflow using the Plug-in includes:

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. Open TIBCO Business Studio using one of the following ways:

● Microsoft Windows: click Start > All Programs > TIBCO > TIBCO Business Studioversion_number > Studio for Designers.

● Linux or Mac OS: run the TIBCO Business Studio executable file located in the TIBCO_HOME\studio\version_number\eclipse directory.

2. From the menu, 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 editoris displayed automatically.

8


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 then click 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. After you create a project, configure a process by adding 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 the added activities, as described in WebSphere MQ Palette.

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

4. Click File > Save to save the project.

9


Debugging and Running a ProcessYou can debug your BusinessWorks applications to check if the configurations are 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 that only the application you want to debug and run is selected in the Applications tab inthe right panel.

5. Click the Advanced tab and click Browse to locate the logback file.By default, the log file is located in the TIBCO_HOME/bw/version_number/config/design/logbackdirectory and error 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 fails with anMQRC_MODULE_NOT_FOUND error.

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 the 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 is 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


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

Deploying ApplicationsAfter deploying BusinessWorks applications, you can manage the applications by using TIBCOEnterprise Administrator.

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 by using the command-line mode with the bwadmin utility.See TIBCO ActiveMatrix BusinessWorks Administration for more details about how to deploy anapplication.

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. See TIBCO ActiveMatrix BusinessWorks Administration formore 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.A 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


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

Package N This read only field documents the package name to which thisresource belongs.

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.

12


Queue Manager Connection Configuration

The Queue Manager Connection Configuration panel contains the following fields:

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 is exported by the server to which you are trying to connect.

This file is located in the queue manager home directory in the@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 is used tocreate the connection. If a user name is not provided, the credentialsof the current security context are 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.

13


Field


HeaderCompression

N If RLE is selected, Run Length Encoding compression is applied tothe header portion of messages sent or received over thisconnection.

MessageCompression

N If RLE is selected, Run Length Encoding applies to the body ofmessages sent over this connection.

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

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

Test Connection N Click to test the queue manager connection. Whether successful ornot, a report is placed in the text area to the right. If the test fails, thereport helps you determine what the problem is. In the event thatthe connection is TLS enabled and you are unsure what cipher touse, Test Connection searches for an acceptable cipher and includeit 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 adda line like this to the TIBCOBusinessStudio.ini file:

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

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

Pooling Configuration

The Pooling Configuration panel contains the following fields:


PoolingEnabled

N When selected, pooling is active for this connection. The primaryconsideration for choosing pooling parameters is the number ofavailable connections to the queue manager. Choose values whichdo not create unnecessary resource consumption in the queuemanager, and leave available connections for other applications(including other pooled connections, depending on whether or notthis application will be deployed on multiple servers).

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

14



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.

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

The TLS Configuration panel contains the following fields:


TransportLayer Security

Y This flag enables or disables transport layer security for theconnection. It can be mapped to a module property which you canuse to control this configuration option during deployment.

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 inthe connection field. Normally ciphers are negotiated during thehandshake, but this is not true of WebSphere MQ connections. Thecipher must match the one selected in the queue managers securechannel configuration. However, note that the names do not matchbecause the queue manager refers to the cipher suite, and the Plug-in refers to a cipher spec. To find out the correct cipher, simply leavethe field blank, and press Test Connection to see if any cipheravailable in Java is acceptable by the queue manager. If not, youmight have to adjust the queue managers cipher specification. Manyof the cipher specifications supported by WebSphere MQ are notavailable in the stock JRE from Oracle. To gain access to a largerarray of ciphers, it is necessary to run the Plug-in on a platformwhere the IBM JRE is available. Alternatively, a third party JSSEimplementation can be added to the JRE on your platform of choiceas long as it supports the ciphers you require.

15


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

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 SSL Client.● That the SSL Client protocol is TLSv1 and that the cipher is explicitly specified and matches the

cipher used by the server channel.

See the TIBCO ActiveMatrix BusinessWorks documentation for more details about the TLSConfiguration panel.

WebSphere MQ Message Body SchemaIf the message content type for a message is set to Schema, then the message is 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.

General

The General panel contains the following fields:


Package N This read only field documents the package to which the resourcebelongs.

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

Description N Description of the resource.

Message Body Configuration

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

16


● 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 are 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 syncpoint 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, force a syncpoint.

The Message Body Configuration panel contains the following columns:

Column Name Description

FieldName Assign a unique name to this field. The name is for reference and XMLconsistency only, and is not stored in the message.

FieldType Select a type from the FieldType list.

For detailed field types, see the following table.

String Length Specify the length for a string.

The following table lists the field types and the methods used to access the field types:

Field Type Put API Get API

string writeString readStringOfCharLength(name encodes length)

boolean writeBoolean readBoolean

byte writeByte readByte

bytes write readFully

short writeShort readShort

int writeInt readInt

long writeLong readLong

float writeFloat readFloat

double writeDouble readDouble

decimal2 writeDecimal2 readDecimal2



unsignedbyte write readUnsignedByte

17


Field Type Put API Get API

unsignedshort writeShort readUnsignedShort

utf writeUTF readUTF

char writeChar readChar

line writeString readLine

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 following field types are supported:

● boolean● byte● bytes● short● int● long● float● double● string

The node represented by this schema is present on the input schema of the Put activity and in theoutput schema of the Get and Listener activities. Fields which contain values are mapped onto sentmessages. 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 causes the activity to fail. If there is no sync-point in place forthe activity and an error occurs while extracting the properties which causes the activity to fail, then themessage is effectively lost. If there is any chance of this happening in your application, you need toforce a sync-point.

To create a WebSphere MQ Application Properties Schema, right-click the Schemas folder in the ProjectExplorer view, click New > XML Schema File, and configure the schema and then select it from all theactivities 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.

18


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 of the Put activity contains the following fields:

Field


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

Destination Y The name of the queue onto which the message is placed. If thequeue is to be created dynamically, enter the name of thedynamic queue. The name must follow the MQSeries rules fordynamic queue names.

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

19


Field


DynamicDestination

N A flag that enables the creation of a dynamic queue. Whenselected, the Dynamic Destination Model field is enabled.Dynamic queues are ones which are created as needed anddestroyed when the lifespan dictated by the model is reached.

DynamicDestination Model

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

Enter the name of a queue model for the queue manager to use asa template 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 it must be translated to binary via an XPath expression.

● Text: String data can be directly mapped onto the message.The message is decoded using characterSet for the message,or 819 if none is provided. Characterset 819 is the Java APIdefault.

● Schema: The message is formatted according to the schemaprovided in the Message Body Fields field. Input values forthis schema appear in the input editor.

Message BodyFields

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

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

● Datagram● Request● Reply● Report

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

Reply ToDestination

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

The queue name which is placed into the message header's ReplyTo Destination field. If the reply to destination is dynamic, aqueue is created and kept open until the end of the process. If anasterisk is the last character of the name, or no name is provided,the queue manager generates a name. The destination elementin the Put activity's output schema documents this dynamicallygenerated name, and the sent message also contains the name sothat the receiving application knows where to send the response.

20


Field


DynamicReplyToDestination

N This check box is enabled if Request is selected in the MessageType field.

When this check box is selected, the Dynamic ReplyToDestModel field is enabled, and the reply queue is dynamicallycreated based on the model in the Dynamic ReplyToDest Modelfield. If a dynamic reply queue is specified, the dynamic replyqueue is created during the put operation so that it is available tothe responding application. The created destination exists untilthe end of the process, so any activity which replies to thisrequest must do so before the process ends or the destination isdeleted.

DynamicReplyToDest Model

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

This field is enabled only when the DynamicReplyToDestination check box is selected.

Fail If Quiescing N Select this check box to cause the activity to fail if the queuemanager attempts to quiesce during the operation. This preventsthe queue manager quiesce from being delayed by this activity.This check box is selected by default.

ApplicationProperties

N Select the Application Properties resource to be included as partof this message. Application properties are similar to regularmessage header fields except that the name and type of thesefields can be determined by a predefined schema.

To use application properties, create a generic XML schemacomposed of a node with simple elements inside it and map it tothis field. See the IBM WebSphere documentation for propertytypes supported by the level of client you have installed.

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

Logger Name Y Loggers are configured in an XML file used at run time. Theruntime logger configuration is specified by the -Dlogback.configurationFile parameter of either the deployedapplication instance or of the debugger instance. Once the loggeris configured, it can be named here to cause informationalmessages to be written there. See the TIBCO ActiveMatrixBusinessWorks documentation for more details about how toconfigure loggers.

Description

A short description for the Put activity.

Multi-Message

The Multi-Message tab of the Put activity contains the following fields:

21


Field


Multi-MessageSupport

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

Select one of the following settings:

● None: The input schema provides only for a single message andit is put without a sync-point. This is the fastest operationconfigurable.

● Batch: The input schema is configured for batch messages.Multiple nodes are sent as separate messages and committed as asingle unit of work.

● BatchGroup: The input schema is configured for batch but all themessages provided are sent as a single logical message group.

● CustomGroup: In this mode, the input schema is configured fora single message, and the lastMessage field is provided. Theapplication designer can loop a number of put operations tocreate a logical message group and it is their responsibility toterminate the group by setting the lastMessage field of the lastmessage to true.

Unless the activity is in an MQ Local Transaction, each memberof the logical message is committed as the activity ends. If anerror occurs, an incomplete logical message can be left in thequeue. It is therefore good practice to use a local transaction tocommit 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.


● None: The message is not segmented, nor does it allow the queuemanager to segment it.

● Explicit: This enables the Max Segment Size field and segmentsthe message configured in the input schema into as manysegments as necessary to send the whole message.

● QueueManager: The message is sent with flags set so that thequeue manager can segment it to suit the buffer sizes of anychannels encountered on the way to the destination.

● Both: The message is explicitly segmented by Max Segment Sizeand flags are set allowing the queue manager to further segmentthe message if necessary.

22


Field


Max SegmentSize

Y If segmentation is enabled, this field is enabled. Enter the maximumsize in bytes that any segment of this message can 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 example, the encoding or character set is inappropriate for thedata, or the schema used to process the message is in error.

Syncpoint Used N This field is not a configuration field, rather it is an indication ofwhether a syncpoint is required for the operation. Non-syncpointoperations are significantly faster than syncpoint ones, however theoverhead of a syncpoint is much less significant for large batches.

If an activity is inside a local transaction, this field isunaware of that fact. In that case, a syncpoint is always ineffect for the local transaction.

Advanced

The Advanced tab of the Put activity contains the following fields:

Field


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 persists in 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 in the input schema.

23


Field


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


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


● Default: The input schema conforms to the fields accessible to auser with the default authority.

● Identity: The input schema conforms to the fields accessible to auser with the Set Identity Context authority.

The new fields are:

● accountingToken

● applicationIdData

● userId

● All: The input schema conforms to the fields accessible to a userwith the Set Identity Context and Set All Context authorities.

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

● applicationOridinData

● putApplicationType

● putApplicationName

24


Field


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 withRequest type messages. That is, if the message type is Request, areport confirmation is not sent.

Confirm onDelivery

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

Report types are:




report.


25


Field


Confirm onException

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

Report types are:




report.


Confirm onExpiry

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

Report types are:




report.


Report ReplyQueue

Y Enter the name of the queue to which Report messages are sent. Thisqueue needs not exist and is not checked, but can be selected usingChoose a field value type on the right side of the field. The valueentered here maps onto a message's replyToQueueName field.

Pass CorrelationId

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

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

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

26


Field


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 following is the input for the Put activity:

Input Item


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

InteractionInput N This input schema field is the root node for all the inputprovided to the activity.

27


Input Item


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

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

● destqmgr: Destination queue manager name. The name ofthe queue manager on which this queue is located.

A transmission queue and a sender channel mustbe configured for this queue manager in order for itto work.

● correlationId: 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.

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

● groupId: Specify a group ID. The queue manager overridesthe group ID for any message composed of multiple physicalmessages. However, if the intention is to send a singlemessage and use the groupId element as an additional filterby the receiving application, then mapping a group ID heremeets that requirement.

● characterSet: 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 may apply this codeset when doingconversions for the purpose of creating report messages.

● alternateUserId: Specify a use ID to be used as an alternateuser for this operation only. The user ID used in theconnection resource must have an Alternate Userid Authorityto use 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.

28


Input Item


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

● putApplicationType: Provide either one of the IBMdocumented application type enumerators for thisapplication or one of your choosing. See the IBM WebSphereMQ documentation for the meaning of the documentedapplication types. 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 user ID 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 oneis available there, and from the environment if it is not.

● replyToQueueName: Specify the name of a queue that thetarget application can use as a destination for its response.This enables the common "request response" pattern. If thequeue is a dynamically created one, it is created by the Putactivity and is closed at the end of the process that creates it.Therefore, any get for the reply must be done in the sameprocess; otherwise, the queue will have been deleted by thequeue manager.

● replyToQmgrName: Destination queue manager name. Thename of the queue manager on which this queue is located.

A transmission queue and a sender channel mustbe configured for this to work.

29


Input Item


● format: Describes the nature of the data in the message. Itdefaults to " ", or MQFMT_NONE. A user defined format can beused to assist the receiving application in decoding themessage, for example, in the selection of a Data Conversionparse activity for this message type.

● expiry: Indicates the length of time (in tenths of a second)that the message is kept in the queue before being deleted.Defaults to -1, which means there is no expiration. This fieldoverrides the configuration value for expiry if it is mapped.Permissible values 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 themessage. This field is an application only field and is notacted upon by the queue manager.

● reportOptionNan: Set this boolean field to add the valueNegative Acknowledgment to the report field of themessage. This field is an application only field and is notacted upon by the queue manager.

● report: This is the report options field for the message. Ifnothing is entered, then the report options as configured inthe Advanced tab are used to populate it at run time.However, if a number is mapped here, it is logically OR'edwith the results of processing the report options. It isprovided to enable the use of report options not configurablein 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, 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 theWebSphere MQ documentation.

appProperties N Contains fields that correspond to the schema as it is defined inthe application properties resource that is mapped to thisactivity. Application properties are included in an MQRFH2header which is dynamically added to the message.

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

messageFields N This element is present when Schema is selected from theMessage Content Type list of the General tab. The contents ofthe mapped schema are present in this node for mappingpurposes.

30


Input Item


bytes N Map the main content of the message body here. In general, thisis the output of a Plug-in for Data Conversion render activity,but it can be any array of bytes. If string data is to be mapped tothis field, use the XPath function tib:string-to-base64 toconvert it to bytes.

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

lastMessageInGroup N If CustomGroup in the Multi-Message Support area is selected,this field appears in 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 following is the output for the Put activity:

Some of these fields are missing or inaccurate if the Asynchronous Mode is used.

Output Item


Batch N This node is present when Batch or BatchGroup in the Muti-Message tab is selected. For each InteractionInput nodepresent in the input schema, an InteractionOutput node ispresent here under the Batch node.

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

31


Output Item


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

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

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

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

● messageId: To document the message ID.

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

● characterSet: To document the character set used by thequeue manager 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.



● format: The character string placed into the format elementby the sending application. Plug-in applications do notsupport the modification of this field and for thoseapplications it is empty. However, if a custom applicationsends the message, its contents are visible here.

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

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


32


Output Item



● report: To document the contents of the report field in thereturned message.

● encoding: To document the numerical value of the encodingfield. This encoding is used for extracting numerical datafrom the message if those numbers are in properties or amessage body schema.

● 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 is backedout before being committed.

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

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

● putDateTime: The time that the message is placed into 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 themessage.

Fault

The Fault tab lists exceptions that occur in the Put activity:

33


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.

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

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

mqErrorCode string This is the original MQException's error code, if it is anMQException that triggers 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 is received.

● Check the queue without a wait interval. The activity checks the queue and returns immediately,regardless of whether a message is 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 of the Get activity contains the following fields:

Field


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 operation isperformed. This field can be dynamically provided in the inputschema and is not required here.

DynamicDestination

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

34


Field


DynamicDestinationModel

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

Message ContentType

N Choose the way that the message body is represented in the outputschema.

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

● Text: The message is a string. The message is decoded usingcharacterSet for the message, or 819 if none is provided.Characterset 819 is the Java API default.

● Schema: The message is formatted according to the schemaprovided in the Message Body Fields field. Values for thisschema appears in the Output tab.

Message BodyFields

Y Provide the schema to be used in the Output tab, and at run time toencode the contents of this message. This field is only available ifSchema is selected in the Message Content Type field.

Close Option N Select the close option for this Get activity. These options are foruse in 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 in it.

If the Get activity is being performed on a permanent dynamicqueue and the intention is for the queue to be deleted, you canchoose either DELETE or PURGE. DELETE deletes the queue if itis empty, and PURGE deletes the queue and any messages that arein 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.

35


Field


Fail If Quiescing N Select this check box to cause the activity to fail and exit if thequeue manager attempts to quiesce. A failure to do so causesquiesce operations to take much longer. This check box is selectedby default.

GMO Convert N Causes the get message option MQGMO_CONVERT to be used for thisget operation. It causes 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 waitsforever for a message in the queue. When cleared, the WaitTimeout field is enabled.

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

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

If a Get activity is configured to wait forever, it does soeven after the application is set to stop using theadministrator or shell command. To release theconnection and close the destination, it is necessary tostop the appNode on which this application is running.


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


36


Field


Property Control N Select one of the following settings:

● AS_Q_DEF● COMPATIBILITY● IN_HANDLE● FORCE_MQRFH2

After selecting one of these options, you can use the Get activity tointer-operate with various versions of WebSphere MQ applications.Which option to use depends on the sending application. See thesection entitled "MQGMO message property option setting" in theIBM WebSphere MQ documentation for detailed information.

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

A short description for the Get activity.

Multi-Message

The Multi-Message tab of the Get activity contains the following fields:

37




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 exists. The Complete Message,and Get Ordered fields apply. If the activity is not in a localtransaction, it operates without a syncpoint for efficiency.

The Syncpoint Used indicator is off.

● BatchGroup: In this mode, the get operation is expecting to geteither a group of individual messages (in which case the BatchSize field controls how many messages are retrieved) or aLogical Message. If the activity is not in a local transaction, theentire multi-message operation occurs within a single unit ofwork, otherwise it occurs 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 is includedwith the normal message in one operation regardless of theBatch Size value. If the intention is to process Logical Messagesonly, set the batch size to 1. The Complete Message and GetOrdered fields are in effect.

● CustomGroup: In this mode, the activity gets a single messagefrom 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 indicates whether the message is in agroup and whether or not is the last message with the contents:MSG_IN_GROUP, MSG_NOT_IN_GROUP, MSG_LAST_IN_GROUP.This field is used to determine when to terminate the loop.Unless the activity is a local transaction, it commits the contentsof each get as they are performed.

Batch Size Y 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 contains a node for each message retrieved.If a timeout occurs while the batch is incomplete, then theincomplete batch is processed and no exception is thrown.

CompleteMessage

N Selecting the Complete Message check box causes the Get activity towait for a logical message to be complete before returning any of themessages. When the Complete Message check box is cleared, alogical message needs 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.

38



Get Ordered N When the Get Ordered check box is selected, it requires that alogical message be processed in the order it is written to the queue.Therefore, the first get in a message requires that message number 1be present, so it must be disabled to process partial (damaged)logical messages. The queue must be indexed for this to work. If thequeue is not indexed, this option is dynamically switched 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 example, the encoding or character set is inappropriate 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 runswith a syncpoint 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 is still a syncpoint in place on behalf of the transaction, soit is irrelevant in that case.

Input

The following is the input for the Get activity:

Input Item


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

39


Input Item


mqproperties N The node containing all the message header fields (plus thedestination override) which are relevant to 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 thismessage by mapping a byte array to this field. The XPathstatement tib: string-to-base64 ("correlationid") issufficient to populate this field. The provided correlation ID isused to filter messages from the queue.

● messageId: Specify a message ID. This value overrides thedefault value generated by the queue manager. The rules arethe same as for correlationId. If a message ID is provided, itis used to filter the get results.

● groupId: Specify a group ID. If a single message is placed inthe queue using a specific group ID, then this message can befiltered and received by a Get activity after this activity mapsthe correct group ID there. This field is provided for use as anextra filter field only.





— 1200: Unicode.

— 1208: UTF-8.


● alternateUserId: Specify a user ID to be used as an alternateuser for this operation only. The user ID used in theconnection resource must have the Alternate Userid Authorityto use this field.

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

40


Output

The following is the output for the Get activity:

Output ItemModuleProperty? Description

Batch N If BatchGroup is selected for this activity, this Batch node isthe high level item for the activity and contains a number ofInteractionOutput nodes equal to or less than the BatchSize parameter depending on how many messages areavailable within the timeout period. If a logical message isfetched from the queue, there is a node in the output for eachmember of the logical message.


41



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

● destination: To document the destination for thismessage. If the queue is a dynamic queue, the generatedname is reported here.

● destqmgr: The name of the remote queue managersupplied in the input schema.

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


● groupId: To document the group ID.

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

● alternateUserld: If the get operation is intended to beconducted using the authentication capabilities of adifferent user ID than the one on the connection resource,enter that user ID here.

You must have authorization to use thiscapability. The provided user ID is in effect foronly this operation.

● accountingToken: The accounting token provided by thesending application.

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

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

42



● putApplicationType: The type of the application that putsthe message.

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 providedby either the sender of the message or the queue manager.


● replyToQueueName: The name of the queue to which areply is sent. If the type of the message is Request, thenthis is the name of the queue that the application sends thereply message to.

● replyToQmgrName: The name of the remote queue managerfor this message's reply-to destination, if one is provided.

● format: To describe the nature of the data in the message.The sender of the application can use standard names(these names are prefixed by the MQ text) or application-generated names. If the message originates from a TIBCOActiveMatrix BusinessWorks Plug-in for WebSphere MQapplication, this is an 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 themessage is sent.

43



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

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

● report: To document the numerical value of the reportfield.

● encoding: To document the numerical value of theencoding field. This encoding is used for extractingnumerical data from the message if the numbers are inproperties or a message body schema.

● messageType: Enumerated value indicating the messagetype:

— 8 is Datagram.

— 2 is Reply.

— 4 is Report.

— 1 is Request.

● backoutCount: The number of times this message isbacked out before being committed.

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

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


● 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 thereceived message to the schema attached to the activity.Properties which are missing or not present in the schema arenot shown here.

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

This field is displayed for schema-based messages only.

44



bytes N If the activity is configured to use binary messages, then thisfield contains the output body of the message. Typically, thisbyte array 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 inthe Binary mode.

text N If the activity is configured to use text for the payload, thisfield is present and contains the contents of the messagedecoded as a string.

This field is only displayed if the activity is configured to inthe Text mode.

responsetimemillisec N To indicate how long it takes to receive the message. Thisvalue includes any time spent waiting in an empty queue.

Fault

The Fault tab lists the possible exceptions that occur in the Get activity:

Error SchemaElement


msg string The descriptive text provided by this exception object.

msgCode string If the message has a BW message code, it is mapped to this field.

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

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

mqErrorCode string If the message originates as a WebSphere MQ API exception, thenthat exception's error code is 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 in 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 of the Listener activity contains the following fields:

45


FieldModuleProperty ? Description


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

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, eachthread this activity runs waits for the confirmation before gettinganother message from the queue. Therefore, to process messages inan absolute serial fashion, start only one instance of the listener. Inthis case, the number of messages processed becomes a function ofhow much latency exists in the activity prior to the confirmation.

Destination Y The name of the queue from which the message is 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 is patterned. This field is only available when the DynamicDestination check box is selected.

It is recommended that static queue names (queue namesthat do not contain a pattern) be used for listeneractivities. If a pattern is used for a Listener activity queuename, the name generated by the queue manager is notavailable until the listener creates a process which makesit impossible for a sender to know the name.

MessageContent Type

N Select the type of message contents:

● Binary: The body of the message is represented as a byte array tosubsequent activities in the process and is contained in the byteselement.

● Text: The body of the message is represented as a string tosubsequent activities in the process and is contained in the textelement. This string is converted from the bytes in the messageusing the characterSet element in effect for this message.

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

46



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 is 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 opened by anotherapplication, then the activity fails.

GMO Convert N Causes the get message option MQGMO_CONVERT to be used for thisget operation. It causes 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 theexplicit 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 waits for the confirmation before obtaininganother message which imposes an absolute limit on thethroughput. If serial processing of the messages is notessential, raise the value of the Instances field until eitherthe worker threads are 100% busy or the desiredthroughput is achieved.

If the activity fails to confirm the message, it loops and repeatedlyprocesses the same message.

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

Description

A short description for the Listener activity.

Multi-Message

The Multi-Message tab of the Listener activity contains the following fields:

47




N Two options are supported:

● None● BatchGroup

If BatchGroup is selected, an activity is started by a listener tooperate in the batch mode that contains multipleInteractionOutput nodes, each representing one message in thebatch. The Batch Size field is enabled allowing you to determine thenumber of discrete messages to be included in the batch. WhenNone is selected, the Listener activity processes a single message atone time from the queue.

The main improvement that the batch mode offers is that allmessages in the batch are committed by a single call, thuseliminating continual round trips, which reduces network trafficand latency involved with committing each message individually.The size of the batch for a Put activity is determined by the numberof nodes in the input schema.

If explicit client confirmation is selected for a batch, theentire batch is confirmed when the confirmation activityruns. Enabling the 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 1 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 are created. To process incomplete logicalmessages, do not select this field. This option requires that the queuebe indexed, otherwise it is disabled dynamically at run time.

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 example, the encoding or character set is inappropriate for thedata, or the schema used to process the message is in error.

48



SyncpointUsed

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

Advanced

The Advanced tab of the Listener activity contains the following fields:


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

See the TIBCO ActiveMatrix BusinessWorks documentation formore information 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 Enterprise Administrator, and it is also available inthe $_processContext process variable.

49



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 in the queue they areprocessed without an intervening polling interval, thus diminishingapplication latency.

When cleared, the activity waits forever in the queue, processingmessages as they arrive. If the queue manager connection fails, theactivity attempts to reconnect based on the reconnection interval. Ifthe listener is not polling, it is doing an unbounded get on thequeue, and the listener does so even after the application is set tostop using the administrator or shell command. To release theconnection and close the destination, you must stop the appNode onwhich this application is running. This also means that if youredeploy the application without recycling the appNode, theconnections from the previous deployment persist until the node isrecycled. This is because there is no safe way to interrupt aWebSphere MQ native Java API get method.

A poor choice of polling interval and polling timeoutvalues might 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 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 must besignificantly smaller than the polling interval. This minimizes thenumber of concurrent connections to the queue and reduces theprocessing resources needed.



Default: 1000

50



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 forexample), this value is the number of milliseconds betweenreconnection attempts.


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

Group Id Y The Listener activity instructs the queue manager to filter therequest based on the specified group ID. Only messages with exactlythe same group ID are accepted.

When filtering a queue this way, be sure to use a clear textgroup ID on the application that does the put.


N 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 MQ documentation forproperty types supported by the level of client you have installed.


51



PropertyControl

N Select one of the following settings:


After selecting one of these options, you can use the Listener activityto inter-operate with various versions of WebSphere MQapplications. Which option to use varies depending on the sendingapplication. See the section entitled "MQGMO message propertyoption setting" in the IBM WebSphere MQ documentation fordetailed information.

Conversations

You can use the Conversations tab of the Listener activity to initiate or join a conversation.

Conversations receive messages after the creation of a process instance, which is initiated or joined byan activity. This activity can be used to initiate a conversation. Click the Add New Conversation icon to initiate a conversation. For more details regarding conversations, see TIBCO ActiveMatrixBusinessWorks Application Development.

Output

The following is the output for the Listener activity:

Output Item


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


52


Output Item


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


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

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


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


● alternateUserId: Specify a user ID to be used as analternate user for this operation only. The user ID used in theconnection resource must have the Alternate UseridAuthority to use 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.

53


Output Item


● putApplicationType: The type of the application that putsthe message.

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 putsthe message.


● replyToQueueName: The name of the queue to which a replyis sent. If the type of the message is Request, then this is thename of the queue that the application sends the replymessage to.

● replyToQmgrName: 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 use standardnames (these names are prefixed by the MQ text) orapplication generated names. If this message originates froma TIBCO ActiveMatrix BusinessWorks Plug-in for WebSphereMQ application, then this field contains an empty string.

● expiry: The expiration time (in tenths of a second), afterwhich the message is eligible to be discarded by the queuemanager. This contains whatever value is used when themessage is sent.


54


Output Item


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

● report: This is the report options field for the message. Ifreports are requested for the message, the relevant bits arepresent here.

● encoding: This is the encoding element for the message andit specifies 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 WebSphere MQ documentation.

● messageType: Enumerated value indicating the messagetype.

Where:

● 8 is Datagram.

● 2 is Reply.

● 4 is Report.

● 1 is Request.

● backoutCount: The number of times this message wasbacked out before being committed.

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





55


Output Item


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

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

text N If the activity is configured to use text messages then this node ispresent in the bytes field. The contents of the message aredecoded 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 N The time, in milliseconds, that the listener takes to receive thismessage. It is measured from when the listener starts listening towhen it finishes 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 displaysif application properties are mapped on the Advanced tab.Properties which are missing or not present in the schema arenot shown here.

messageFields N Contains the message body formatted using Schema in theMessage Content Type field of the General tab. Each field in theschema is mapped here.


Fault

The Fault tab lists exceptions that occur in the Listener activity:

Error SchemaElement






56


WebSphere MQ RequestReplyThe RequestReply activity performs the combined operations of putting a request message into aqueue, and then listening on an indicated response queue for the reply.

Because the RequestReply activity depends on the request being committed to the request queue, thisactivity does not participate in local transaction semantics. This also means that this activity does notshare a connection resource with activities in a local transaction because it can unexpectedly commitresources under the control of the local transaction.

General

The General tab of the RequestReply activity contains the following fields:

Field



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 into which the message is placed. If thequeue is to be created dynamically, enter the name of thedynamic queue. The name must follow the MQSeries rules fordynamic queue names.

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

Message ContentType

N Select the type of message content:

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

● Text: String data can be directly mapped onto the message.The message is decoded using characterSet for the message,or 819 if none is provided. Characterset 819 is the Java APIdefault.

● Schema: The message is formatted according to the schemaprovided in the Message Body Fields field. Input values forthis schema appear in the input editor.

Message BodyFields

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

57


Field


Reply ToDestination

Y Specify a reply queue on which the RequestReply activityperforms a get immediately after sending a request. The activitywaits for the number of milliseconds specified in thewaitinterval element of the input schema.

The queue name which is placed into the message header's ReplyTo Destination field. If this queue is dynamic, it is created beforethe put is performed, and the name of the temporary queue is setin the request message.

DynamicReplyToDestination

N A flag that enables the creation of a dynamic queue.

When selected, the Dynamic ReplyToDest Model field isenabled, and the reply queue is dynamically created based on themodel in the Dynamic ReplyToDest Model field. If a dynamicreply queue is specified, it is created during the put operation sothat it is available to the responding application.

DynamicReplyToDest Model

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

This field is enabled only when the DynamicReplyToDestination check box is selected.

Fail If Quiescing N Select this check box to cause the activity to fail if the queuemanager attempts to quiesce during the operation. This preventsthe queue manager quiesce from being delayed by this activity.


N Select the Application Properties resource to be included as partof this message. Application properties are similar to regularmessage header fields except that the name and type of thesefields can be determined by a predefined schema.

To use application properties, create a generic XML schemacomposed of a node with simple elements inside it and map it tothis field. See the IBM WebSphere documentation for propertytypes supported by the level of client you have installed.


Logger Name Y Loggers are configured in an XML file used at run time. Theruntime logger configuration is specified by the -Dlogback.configurationFile parameter of either the deployedapplication instance or of the debugger instance. Once the loggeris configured, it can be named here to cause informationalmessages to be written there. See the TIBCO ActiveMatrixBusinessWorks documentation for more details about how toconfigure loggers.

Description

A short description for the RequestReply activity.

58


Advanced

The Advanced tab of the RequestReply activity contains the following fields:

Field


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 persists in thequeue before being deleted by the queue manager.

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 in the input schema.

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


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

59


Field


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.




The new fields are:

● accountingToken


● userId






Input

The following is the input for the RequestReply activity:

Input Item


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

60


Input Item


mqproperties N The node containing all the message header fields (plus thedestination override) that are relevant to the put side of theoperation. Note that any values mapped to the filtering fields(messageId, correlationId, and groupId) are subsequentlyused to filter the get side of the operation.

● destination: Specify a destination here to override the queuename from the configuration panels. This allows the queue tobe dynamically specified.

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

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

● correlationId: 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. If a correlation ID is provided,then the activity filters the reply queue using the samecorrelation ID.

● messageId: Specify a message ID. This value overrides thedefault value generated by the queue manager. The rules arethe same as for correlationId. If a message ID is provided,then the activity filters the reply queue using the samemessage ID.

● groupId: Specify a group ID for a message if the message ispart of a group. If a group ID is provided, then the activityfilters the reply queue using the same group ID.





— 1200: Unicode.

— 1208: UTF-8.


● alternateUserId: Specify a use ID to be used as an alternateuser for this operation only. The user ID used in theconnection resource must have an Alternate Userid Authorityto use 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.

61


Input Item


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

● putApplicationType: Provide either one of the IBMdocumented application type enumerators for this applicationor one of your choosing. See the IBM WebSphere MQdocumentation for the meaning of the documentedapplication types. 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 user ID 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 oneis available there, and from the environment if it is not.

● replyToQueueName: This field overrides the Reply ToDestination field provided in the General tab. This is thedestination on which the Get side of the operation waits aftersending the request. If neither the configuration value nor thisfield is provided, then the activity fails with anMQRC_MISSING_REPLY_TO_Q error.

● replyToQmgrName: Destination queue manager name. BecauseWebSphere MQ does not support a get operation in a remotequeue, this field is ignored. The reply must come back fromthe same queue manager to which the activity is connected.

62


Input Item


● format: Describes the nature of the data in the message. Itdefaults to " ", or MQFMT_NONE. A user defined format can beused to assist the receiving application in decoding themessage, for example, in the selection of a Data Conversionparse activity for this message type.

● expiry: Indicates the length of time (in tenths of a second)that the message is kept in the queue before being deleted.Defaults to -1, which means there is no expiration. This fieldoverrides the configuration value for expiry if it is mapped.Permissible values are a positive integer or -1.


● reportOptionPan: Set this boolean field to add the valuePositive Acknowledgment to the report field of themessage. This field is an application only field and is not actedupon by the queue manager.

● reportOptionNan: Set this boolean field to add the valueNegative Acknowledgment to the report field of themessage. This field is an application only field and is not actedupon by the queue manager.

● report: Because this activity always sends a request typemessage, report options are not available. If any reportoptions are provided here, they are reset to zero by the queuemanager.

● 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 is used whenprocessing of fields mapped by a message body schema. Forspecific values, see the MQMessage encoding field in theWebSphere MQ documentation.

● waitinterval: Specify the number of milliseconds that theRequestReply activity waits for the response after sending therequest before throwing a timeout exception. To waitindefinitely, define a -1 in this field using the statementxsd:int(-1).

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

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

63


Input Item



bytes N Map the main content of the message body here. In general, thisis the output of a Plug-in for Data Conversion render activity, butit can 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.

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

Output

The following is the output for the RequestReply activity:

Some of these fields are missing or inaccurate if the Asynchronous Mode is used.

Output Item



64


Output Item


mqproperties N The node containing the message fields relevant to the get side ofthe request/reply operation. Any fields which relate to filteringmessages (messageId, correlationId, and groupId) which aremapped on the input schema are used to filter the responsepresented here.


● destqmgr: To document the destination queue manager as itis specified in the reply message. Because get operations mustoccur on the queue manager to which the activity isconnected, this destination queue manager is always thatsame queue manager.

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


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

● characterSet: To document the character set used by thequeue manager to process this message. This character set isalso the character set used to extract string data from themessage.

● alternateUserId: As provided in the input schema.







● replyToQueueName: Normally null for this activity typebecause the output of this activity represents a reply.


● format: The format of the message. This field is normallyused to help the receiving application parse the payload. Thevalue can be one of the IBM standard formats or an customapplication specific value.

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


65


Output Item




● report: To document the report field in the message as it isreceived.

● encoding: To document the encoding field in the message asit is received. This encoding is used to extract any numericaldata from the message.

● waitinterval: The number of milliseconds theRequestReply activity waits for the response to the requestsent by this activity.

● messageType: Enumerated value of the chosen message type:

— 8 is Datagram.

— 2 is Reply.

— 4 is Report.

— 1 is Request.


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


● putDateTime: The time that the request message is placedinto the queue.

● 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

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.

66


Output Item




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


text N If the activity is configured to use text for the payload, this fieldis present and contains the contents of the message decoded as astring.


responsetimemillisec N To indicate, in milliseconds, how long it takes to send themessage.

Fault

The Fault tab lists exceptions that occur in the RequestReply activity:

Error SchemaElement




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

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

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

WebSphere MQ PublishThe WebSphere MQ Publish activity publishes a message to a dynamic or 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 the message being sent might determine what

67


fields are applicable for the publish operation, for example, request messages are incompatible withreport options. Even though this is a pub/sub type of activity, the report and reply-to queues are realqueues, not topics.

In WebSphere MQ, a topic is defined as a string of characters starting with a forward slash (/) and cancontain 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 of the Publish activity contains the following fields:



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 is published. This field is optional in the event that thetopic string is to be entirely specified in the Topic Dynamicfield or the input schema.

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

Message ContentType

N The following types of 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 run time, this string isconverted 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 is provided for mapping on theinput schema.

Message BodyFields

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

68



Message Type N Select the type of the 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 is placed into thereplyToQueueName field in the Input tab. Click Choose a field

value type next to 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.


N Select a schema which represents the application properties tobe placed in this message. To use application properties, createa generic XML schema composed of a node with simpleelements inside it and map that schema to this field.

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


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

Description

A short description for the Publish activity.

Advanced

The Advanced tab of the Publish activity contains the following fields:

69


Field


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.

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.




The new fields are:

● accountingToken


● userId






Confirm OnArrival

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

Report types are:




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.

70


Field


Confirm OnDelivery

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

Report types are:




report.


Confirm OnException

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

Report types are:




report.


71


Field


Confirm OnExpiry

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

Report types are:




report.


Report ReplyQueue

Y Enter the name of the queue where you want to send Reportmessages. The value entered here maps onto thereplyToQueueName field.

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 MQ documentation for the put message optionMQPMO_ASYNC_RESPONSE for more information regarding the risksof this option.

Input

The following is the input for the Publish activity:

Input Item


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

72


Input Item


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

● destination: Specify a destination here to override the topicname from the configuration panels.

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

A transmission queue and a sender channel mustbe configured for this queue manager for it to work.

● topicdynamic: The dynamic portion of the topic string. Thiscan be the entire topic string and 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 thetopic referenced is an administratively defined unmanagedtopic. In all other cases, it is ignored by the queue manager.

Consult the IBM WebSphere MQ documentation fordescriptions of managed and unmanaged subscriptions.

● messageId: To provide a message identifier for this messageby mapping 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 topicreferenced is an administratively defined unmanaged topic.In all other cases 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 user ID to be used as analternate user for this operation only. The user ID used in theconnection resource must have the Alternate UseridAuthority to use 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.

73


Input Item


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

● applicationOriginData: To provide information related tothe originating application node for this message.

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

See the IBM WebSphere MQ documentation for the meaningof the 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 putsthe message. Provide information about the originatingapplication in this field.

● userId: To provide the user ID to be used when authorizingthis message as it traverses the messaging system. Foroperations with report options, this field is mandatory. If avalue is not provided here, it is taken from the connectionresource if one is available there, and from the environment ifit 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.

74


Input Item




● format: To describe the nature of the data in the message. Itdefaults to a space character or MQFMT_NONE. A userdefined format can be used to assist the receiving applicationin decoding the message, for example, in the selection of aData Conversion parse activity for this message type.

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

Permissible values are positive integers or -1.




● report: This is the report options field for the message. Ifnothing is entered, then the report options as configured inthe Advanced tab are used to populate it at run time.However, if a number is mapped here, it is logically OR'edwith the results of processing the report options. It isprovided to enable the use of report options not configurablein 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, packeddecimal and floating point data. This encoding is used whenprocessing of fields mapped by a message body schema.

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

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


75


Input Item


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


appProperties N Contains fields that correspond to the schema as it is defined inthe application properties resource that is mapped to thisactivity.

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


Output

The following is the output for the Publish activity:

Output Item



76


Output Item


mqproperties N The node containing all the message header fields (plus thedestination override) as they are mapped from the messageafter it is sent.

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

● destqmgr: To document the remote queue managerspecified in the input schema.

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

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



● alternateUserId: To specify a user ID to be used as analternate user for this operation only. The user ID used inthe connection resource must have the Alternate UseridAuthority to use this field.







● replyToQueueName: Same as input.

● replyToQmgrName: Same as input.

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

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



77


Output Item



● report: This is the report options field for the message. Ifnothing is entered, then the report options as configured inthe Advanced tab are used to populate it at run time.However, if a number is mapped here, it is logically OR'edwith the results of processing the report options. It isprovided to enable the use of report options notconfigurable 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, 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 WebSphere MQ documentation.

● messageType: Enumerated value indicating the messagetype.

Where:

● 8 is Datagram.

● 2 is Reply.

● 4 is Report.

● 1 is Request.



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


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

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

Fault

The Fault tab lists exceptions that occur in the Publish activity:

78


Error SchemaElement Data type Description





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

WebSphere MQ SubscriberThe Subscriber activity listens on a topic or an administratively defined subscription and starts aprocess that provides the contents of the message.

The subscriber can poll a topic based on interval and 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. To avoid missing messages destined for the topic, you canenable 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 of the Subscriber activity contains the following fields:

Field



79


Field


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 with an administrativelydefined 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 The following types of 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 run time todecode the contents of this message.

80


Field


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 causes 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 waits for the confirmation before obtaininganother message which imposes an absolute limit on thethroughput. If serial processing of the messages is notessential, raise the value of the Instances field until eitherthe worker threads are 100% busy or the desiredthroughput 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 the runtime. Loggers are configured in an XML document referenced bythe Dlogback.configurationFile runtime parameter.

Description

A short description for the Subscriber activity.

Advanced

The Advanced tab of the Subscriber activity contains the following fields:

81



Sequence Key N This field can contain an XPath expression that specifies whichprocesses can 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 the TIBCO ActiveMatrix BusinessWorks documentation formore information 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 Enterprise Administrator, and it is also available inthe $_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 might 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.


Default: 1000

PollingTimeout

Y If the Polling Interval check box is selected, this is the timeout valuefor each individual listen. The value specified here must 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.



Default: 1000

82



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 example), this value is the number of millisecondsbetween reconnection attempts.


Default: 10000


N If the messages expected on this topic contain application specifictopics, a shared schema resource must be created to represent thoseproperties and it has to be mapped here. Messages which containany or all of these properties will have them provided as input to theprocess created by this starter. To use application properties, createa generic XML schema composed of a node with simple elementsinside it and map that schema to this field.

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


PropertyControl

N Select one of the following settings:


After selecting one of these options, you can use allow theSubscriber activity to inter-operate with various versions ofWebSphere MQ applications. Which option to use varies dependingon the sending application. See the section entitled "MQGMOmessage property option setting" in the IBM WebSphere MQdocumentation for detailed information.

Conversations

You can use the Conversations tab of the Subscriber activity to initiate or join a conversation.

Conversations receive messages after the creation of a process instance, which is initiated or joined byan activity. This activity can be used to initiate a conversation. Click the Add New Conversation icon to initiate a conversation. For more details regarding conversations, see TIBCO ActiveMatrixBusinessWorks Application Development.

Output

The following is the output for the Subscriber activity:

83


Output Item



84


Output Item


mqproperties N The node containing all the message header fields (plus thedestination override) which have been mapped from thereceived message.

● 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 specifiedin the input schema.

● topicdynamic: To override the Topic Dynamic field fromthe General tab. This string forms the dynamic portion ofthe fully resolved topic name.

● correlationId: To document the message correlation ID. Inmost cases, this is an internal queue manager value and isnot available for filtering purposes.



● alternateUserId: To specify a user ID to be used as analternate user for this operation only. The user ID used in theconnection resource must have the Alternate UseridAuthority 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 isapplication data was provided by sender of the message.

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

85


Output Item


● 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 putsthe message, if one is provided.


● replyToQueueName: The name of the queue to which a replyis sent if the message is a request.

● replyToQmgrName: If this message arrived by way of aremote queue manager specification, this field documentsthe queue manager 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), afterwhich the message is eligible to be discarded by the queuemanager. This contains whatever value is used when themessage is sent.



86


Output Item



● 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 andit specifies 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 theWebSphere MQ documentation.

● messageType: Enumerated value indicating the messagetype:

— 8 is Datagram.

— 2 is Reply.

— 4 is Report.

— 1 is Request.



● version: To document the version of the message.

● putDateTime: The time that the message is placed onto thetopic.



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


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


87


Output Item


responsetimemillisec N This field records the time, in milliseconds, that it takes to startthe WebSphere MQ get API call until the event context for thenew activity is created.

appProperties N This field maps the application properties present in thereceived message to the schema attached to the activity.Properties which are missing or not present in the schema arenot shown here.

The field is only displayed if an application properties schema isconfigured for the activity.



Fault

The Fault tab lists exceptions that occur in the Subscriber activity:

Error SchemaElement






88


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 are committed.

TIBCO ActiveMatrix BusinessWorks 6.0 and above have enhanced support for local transactions.

If activities within a single MQ local transaction use different queue managers, the resources arecommitted 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: * *===========================================================*

89


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

90


Setting Up WebSphere MQ Queue ManagerTo create a secure connection to the WebSphere MQ queue manager, you need to set up the WebSphereMQ queue 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 must 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 describe the configuration of the queue manager to use certificates generated bythe 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. Create 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 that iscreated during the installation of WebSphere MQ on the platform. If they are not, adjust their accessproperties or the queue manager is not 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 the WebSphere MQ queue manager relies on certificates generated using this script. Thescript is annotated, and is intended to be used as a template to aid you in the creation of your ownscripts. Use this script to assist in the creation of TLS connections in an evaluation or developmentenvironment only. Because all the certificates created by the script are self-signed, they areinappropriate for production 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.2/samples/createQueueManagerKeystore.sh

● Microsoft Windows

TIBCO_HOME\bw\palettes\bwmq\8.2\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

91


where:

● keystordir is the directory in which to create the keystores. This can be a working directory or the SSLdirectory in the queue manager's 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 manager's 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 shows an example of the IBM WebSphere MQ Explorer queue manager propertiesfor SSL.

92


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 lowercase characters. If your queue manager name containsuppercase characters, rename this alias so that all characters are in lower case. If this alias is not correct,the queue manager is not able to open the keystore.

IBM Key Management tool (iKeyMan) does not allow you to simply change an uppercase character to alowercase character. To retain the same name, you have to use an intermediate name for the renamefunction to work.

You can also review the CA certificate that is 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.

93


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

94


Setting Up TIBCO ActiveMatrix BusinessWorksAfter setting up the 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 Manager tool using the strmqikm program.This program is located in the mqm/bin directory in the WebSphere MQ server installation.

95


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 from 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 previously.

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 next to 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 next to the Keystore Provider as TrustStore field.This allows you to create a Keystore Provider resource.

96


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.

97


TroubleshootingYou might encounter some errors while creating secure connections to the queue manager. By verifyingsimple details these errors can be resolved.

The following are some of the possible errors you may encounter and their resolutions.

● If you do not know the correct cipher, leave the field blank and press Test Connection. It cyclesthrough 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 does 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 Multi-Message tabof the Put activity for more information.

98


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 syncpoint. When the nodes are sentsuccessfully, 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.

— You can use the CustomGroup option to use a sequence of 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. If the individual CustomGroup operations are not in a local transaction, they are committed at the end of the activitywhich means that any application listening for these message might begin to process themimmediately. If it is a requirement that no application accesses these messages until the group iscompleted, place the creating loop inside a local transaction.

● 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 Syncpoint Used check box, which isnot a configuration option, but an indication of whether the operation requires the use of a syncpoint.Syncpoints impose a significant overhead on queue operations, so avoid using them wherever possiblefor performance reasons. However, for groups of messages, it is efficient to process the group within asingle sync-point.

99


Segmented Messages

Both the Get and Put activities support segmented messages.

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 Listener 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 Listener 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 Listener 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 in the queue that is handled by a service application. The Request message specifies aReply To Queue name, indicating the queue where the requestor looks 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 reads the reply message. Startingfrom version 8.2.0 of the Plug-in, there is a specific RequestReply activity to automate this pattern.

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.

100


When a put message activity requests a delivery report using the report element in the Input tab, thequeue manager puts a report message into 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.

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 reads the reportmessages.

101


Managing Logs

Logs are used to trace and troubleshoot Plug-in exceptions.

A logback.xml file is located in the TIBCO_HOME\bw\version_number\config\design\logbackdirectory. Update this 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 occurred. Processing continues, butspecial attention from an administrator is recommended.

Error Indicates that an unrecoverable error occurred. Depending on the severity ofthe error, the Plug-in might continue with the next operation or might stop.

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\version_number\config\design\logback directory and openthe logback.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.

102


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 the loglevel configured 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\version_number\config\design\logback directory and openthe logback.xml file.

When deploying an application in TIBCO Enterprise Administrator, navigate to theTIBCO_HOME\bw\domains\mydomain\appnodes\myspace\mynode directory to find thelogback.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 to be exported and the value is the absolutepath of the file.

You also have 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.

103


tibco activematrix businessworks plug-in for websphere mq ... · pdf filethe plug-in supports...

Documents