IBM MQSeries Workflow - MQSeries Integrator interoperability sample, Version 1.2

In this documentation it is assumed that you are familiar with the MQSeries family of products. It describes how to install and run the delivered sample scenario.

Contents

Introduction
Overview of sample scenario
Installation
Running the sample
Handling problems and errors
Change log

More information

Introduction

Using the MQSeries Workflow XML interface, you can integrate applications based on MQSeries to start or execute a workflow process via XML messages. This is also referred to as call-in scenario. In addition, MQSeries Workflow can generate an XML message to integrate an MQSeries-based application into any workflow process. This is also called call-out scenario.

This SupportPac contains a scenario using MQSeries Integrator, Version 2.01 to transform a C-structure message format to or from MQSeries Workflow XML. It offers predefined message sets for MQSeries Integrator to be used in connection with MQSeries Workflow XML messages. It also includes sample message flows to run the sample scenario. The sample scenario shows how existing MQSeries-based applications can be used to execute MQSeries Workflow processes and how you can integrate existing MQSeries-based applications into an MQSeries Workflow process without having to change the MQSeries-based applications for MQSeries Workflow.

The sample contains two easy-to-use MQSeries-based applications, which are:

• ExecOrder.exe to execute an MQSeries Workflow process via the call-in scenario using MQSeries Integrator

This can also be any existing application, for example, any other workflow system in another enterprise that supports MQSeries.

• Lookup.exe, which is an MQSeries-based application integrated into an MQSeries Workflow process

This application shows a running backend application that is waiting for requests. This backend application is integrated into an MQSeries Workflow process via MQSeries Integrator.

Overview of sample scenario

The following section describes in detail the Sample Scenario.
Following this section, you find a more detailed description of the deliverables that are part of this SupportPac:

• MQSeries Workflow sample order process
• MQSeries-based sample applications
• MQSeries Integrator sample message sets and flows

Sample scenario

This sample scenario includes two sample applications based on MQSeries. They are also based on the samples amqsput and amqsget, which are part of MQSeries. These applications need no XML parser or any special coding nor any definitions for MQSeries Workflow. The section in the centre of the above figure shows the MQSeries Integrator message flows as they are defined for this sample. On the right, the MQSeries Workflow model is shown, which is used to control a simple order process used for this scenario. The following illustrates the flow of these sample applications:

1. The sample application, called ExecOrder, puts a simple C structure into the MQSeries queue, which is called ExecOrderOut. The application must wait for a reply, which is also a C structure to be finally put into the ExecOrderIn queue, as shown in (8).
2. An MQSeries Integrator message flow OrderProcessExecute is defined to transform the C structure into an MQSeries Workflow XML message with the result being written into the MQSeries Workflow FMC.FMCGRP.EXE.XML queue to execute an MQSeries Workflow process. If the MQSeries Integrator message broker and the MQSeries Workflow services are running, these steps are carried out automatically as soon as an MQSeries message arrives in the queue.
3. As soon as these steps are finished, an MQSeries Workflow process, called Order, is initiated and started. The Order process activity 'Lookup Inventory' is defined to put an MQSeries Workflow XML message in the defined queue LookupRequestIn and waits for the reply. The MQSeries Workflow process continues as soon as the reply message returns.
4. The MQSeries Integrator message flow LookupRequest is defined to transform the MQSeries Workflow XML message into a simple C structure. The reply message to MQSeries Workflow must contain the Activity Implementation Correlation Identifier which is provided by MQSeries Workflow in the XML message. In this sample, the message is stored together with the MQ message ID in a DB2 database. In the reply processing, the DB2 table entry is read from the DB2 database and then deleted. Consequently, the application need not be changed for MQSeries Workflow integration.
5. The sample application, called Lookup, shown in the figure on the left then simulates an inventory lookup and returns a simple reply as a C structure.
6. The MQSeries Integrator message flow LookupReply is defined to transform the simple C structure reply into an MQSeries Workflow XML message. To create the Workflow XML message, MQSeries Integrator uses the Activity Implementation Correlation Identifier (ActImplCorrelID) from the DB2 database. The MQMD for the sample application Lookup is set to the MQ Series default value, which means that the message ID to Lookup is used to set the MQMD Correlation Identifier in the Lookup reply. So, the Correlation Identifier that is returned by the MQMD from the message generated by the sample application is taken to get the correlated ActImplCorrelID from the DB2 database.
7. The MQSeries Workflow process continues as soon as it receives the ActivityImplInvokeResponse in the FMC.FMCGRP.EXE.XML queue. Note that this is the same queue as used in Step (2). MQSeries Workflow needs only one XML input queue. It differentiates between the messages by XML content.
8. The MQSeries Integrator message flow OrderProcessReply is defined to transform the MQSeries Workflow XML message into a simple C structure to send it to the process starting the sample application ExecOrder back as a reply.

MQSeries Workflow sample order process

The order process is modeled with three major activities. In the sample scenario the process will be started via an order request which results from the MQSeries sample application ExecOrder. The first activity in the process checks for completeness of the order information. The second activity Lookup Inventory integrates an existing MQSeries-based application Lookup, which checks the availability of the ordered parts. The final activity is the reject or accept order activity, depending on the return code of the activity, called Lookup Inventory. The first and final activities are both implemented as MQSeries Workflow applications in a dynamic link library fmct3act.dll, containing simple C functions with the invocations to be logged into fmct3act.log and fmct3act.err.

The sample process was chosen to illustrate that you can specify to execute activities as manual or automatic start activities in MQSeries Workflow Buildtime. Manual activities are placed as work items on users' worklists and they must start such an activity manually. Because the first and the last activity in the process are modeled to be started manually, the MQSeries Workflow order process can be monitored while running the sample. This helps to demonstrate all activity invocations, for example, how the second activity changes to a running state while the MQSeries-based sample application is executed and how the process flow continues.

The following figure illustrates the sample MQSeries Workflow process, called Order.

MQSeries-based sample application

• ExecOrder to start the MQSeries Workflow process and to receive its results.
• Lookup to represent an existing MQSeries-based application, which can be integrated into an MQSeries Workflow process.

These sample applications do not need any specific coding for XML and MQSeries Workflow. They are implemented as C applications, which are based on MQSeries. You should be able to compile them also on other platforms, but this has not been tested until now. These applications can be newly written MQSeries applications with an XML parser or they can be written to generate and interpret MQSeries Workflow XML messages directly without using MQSeries Integrator. However, this SupportPac demonstrates how to integrate existing MQSeries applications without changing these applications. It also helps to show how the MQSeries Family products complement each another.

The following sample applications are used:

1. MQSeries-based sample application, called 'ExecOrder'
2. MQSeries-based sample application, called 'Lookup'

MQSeries-based sample application, called 'ExecOrder'

Any other scenario is also feasible, but you must consider the MQSeries Workflow features and how to handle several different applications that are used to start an MQSeries Workflow process by putting a message in the ExecOrderOut queue. However, if you want to use an existing application, which requests a different reply behavior, you must adapt the MQSeries Integrator OrderProcessExecure message flow. For details, refer to MQSeries Integrator message sets and flows. Check the source code of this MQSeries sample application, called ExecOrder.c, after having installed this SupportPac.

MQSeries-based sample application, called 'Lookup'

MQSeries Integrator sample message sets and flows

This SupportPac contains the following MQSeries Integrator message sets:

1. MQSWFXML (MQSeries Workflow Message Set)
2. MQSWFXML_Order2
3. OrderC

1. OrderProcessExecute
2. OrderProcessReply
3. LookupRequest
4. LookupReply

MQSWFXML (MQSeries Workflow Message Set)

Note: Refer to the MQSeries DTD when defining your own message flows. Not all syntactical specifications of the MQSeries Workflow XML message are defined in the MQSeries Integrator message set. For example, the WfMessage must contain at least one element from the list of possible values. MQSeries Integrator does not support these definitions so that all of these elements are defined as optional. Make sure that you have at least one of these elements assigned.

Note: This message set 'MQSWFXML (MQSeries Workflow XML Message Set)' is a new message set, which is based on the one in the previous version. It is now a level 2 message set, compared to level 1 of the previous version. The new message set contains enhancements, such as the new MQSeries Workflow XML constructs, for example, ActivityExpire. It also contains the MQSeries Workflow container elements, which were not supported by MQSeries Integrator Version 2.0, because container elements start with an underscore (_). Therefore, this SupportPac requires MQSeries Integrator, Version 2.0.1. The new message set is the same as the message set that is used in the MQSeries Workflow Event Sample SupportPac - WA06, Version 1.0.

MQSeries Integrator message set MQSWFXML_Order2

Note: The previous version of this SupportPac contains a message set 'MQSWFXML_Order', based on the message set 'MQSWFXML (MQSeries Workflow XML Message Set)' level 1. The message set MQSWFXML_Order2 message set is based on the new version 'MQSWFXML (MQSeries Workflow XML Message Set)' level 2. This means that it now contains additional elements to the new base message set.

For the sample, this message set is used within the MQSeries Integrator Control Center to map the elements - by dragging and dropping - from this message to the elements of the C structure and vice-versa. This message set is not used by the MQSeries Integrator Broker during run time. Therefore, the MQSeries Integrator internal XML parser is used.

Note: When you change the data structures or elements of the MQSeries Workflow process or if you want to create a new message for other MQSeries Workflow processes, you have to change or create the MQSeries Integrator MQSWFXML message type CONTAINER_TYPE. To do this, create or change an MQSeries Integrator compound type for an MQSeries Workflow data structure and add or change the elements in the MQSeries Integrator according to the MQSeries Workflow data elements. The MQSeries Integrator compound type identifier and Element identifier must be equal to the MQSeries Workflow data structure and data element name. Then, add the created MQSeries Integrator compound type to the checked out MQSeries Integrator compound type CONTAINER_TYPE. Save the MQSeries Integrator workspace and check in the modified CONTAINER_TYPE.

MQSeries Integrator message set OrderC

Message Flow OrderProcessExecute

Open the properties for the compute node to see the details of the mapping of the C structure into MQSeries Workflow XML. The following MQSeries Integrator window appears as shown in the next figure. The section Inputs on the left shows that the message Order_StartOrder of the OrderC message is set. The section Output Messages on the right shows the message MQSWFXML of the MQSWFXML_Order2 message set. In the lower half of the window, the generated assignment of the drag-and-drop operation is displayed, showing the incoming message elements from the left to the outgoing message elements to the right.

However, these mappings only fulfill part of the required information to generate a valid MQSeries Workflow XML message to execute a process (XML tag: ProcessTemplateExecute). Next, click the ESQL tab to see the extended information for the field mapping.

Note: MQSeries Integrator generates the corresponding ESQL statement for all mapped elements. You can extend the ESQL statements with additional statements on the ESQL page. However, as soon as you go back to the mapping tab and use drag and drop for other elements, any previous changes made on the ESQL page are lost. Therefore, it can be useful to store changes on the ESQL page separately, using cut and paste and avoid that your input gets lost when changing certain mappings.

For a valid MQSeries Workflow ProcessTemplateExecute XML message to be used in this sample, you need at least a process name, which is specified via the XML tag ProcTemplName. In addition, there are optional fields, such as ResponseRequired and UserContext. In this sample, an MQSeries-based sample application ExecOrder is used, with the message type MQMT_REQUEST, which means that a response is expected and reply-to-queue and reply-to-queue-manager for the response to the MQSeries-based sample application. The MQSeries Workflow XML tag ResponseRequired is set when an MQSeries Workflow XML response is required. Therefore, the ESQL statements must be added to map the MQMT_REQUEST into ResponseRequired. Because the MQSeries Workflow XML response must be mapped to a C structure before sending it back to the MQSeries-based sample application ExecOrder, the reply-to-queue of ExecOrder must be replaced with the input queue and of the response message flow OrderProcessReply. The reply-to-queue and the reply-to-queue-manager of ExecOrder will be stored in the UserContext field of the MQSeries Workflow XML message. MQSeries Workflow will return this field in the ProcessTemplateResponse XML message. It is used in the response flow OrderProcessReply to restore these values and to determinate dynamically the original reply-to-queue and reply-to-queue-manager of ExecOrder.

Following is the sample ESQL code of the OrderProcessExecute Compute node:

SET "OutputRoot"."MQMD" = "InputRoot"."MQMD";
SET "OutputRoot"."MQMD"."CorrelId" = "InputRoot"."MQMD"."MsgId";
SET OutputRoot.Properties.MessageSet = 'DL7UUDS088001';
SET OutputRoot.Properties.MessageType = 'MQSWFXML';
-- Enter SQL below this line.  SQL above this line might be regenerated, causing any modifications to be lost.

-- the following three lines are optional
SET OutputRoot.XML.(XML.XmlDecl)='';
SET OutputRoot.XML.(XML.XmlDecl).(XML.Version)='1.0';
SET OutputRoot.XML.(XML.XmlDecl).(XML.Standalone)='yes';


IF ( "InputRoot"."MQMD"."MsgType" = MQMT_REQUEST ) THEN
  SET "OutputRoot"."XML"."WfMessage"."WfMessageHeader"."ResponseRequired"='Yes';
  SET "OutputRoot"."XML"."WfMessage"."WfMessageHeader"."UserContext"=TRIM(InputRoot.MQMD.ReplyToQ) || ' ' || TRIM(InputRoot.MQMD.ReplyToQMgr);
  SET "OutputRoot"."MQMD"."ReplyToQ" = 'OrderProcessReplyIn';
ELSE
  SET "OutputRoot"."XML"."WfMessage"."WfMessageHeader"."ResponseRequired"='No';
END IF;

SET "OutputRoot"."XML"."WfMessage"."ProcessTemplateExecute"."ProcTemplName"='Order';

-- Now assign the container elements
SET "OutputRoot"."XML"."WfMessage"."ProcessTemplateExecute"."ProcInstInputData"."Order_StartOrder"."PersonInfo" = "InputBody"."PersonInfo";
SET "OutputRoot"."XML"."WfMessage"."ProcessTemplateExecute"."ProcInstInputData"."Order_StartOrder"."PartsInfo" = "InputBody"."PartsInfo";

Message Flow OrderProcessReply

The sample ESQL code of the OrderProcessReply compute node is called XML Reply to C. The internal MQSeries Integrator XML parser is used to get the values from the input queue. Because a C structure must be generated using the OrderC message set, the last four lines must be added for the broker to define which MQSeries Integrator message is to be set and which message is to be used. As already mentioned in the message flow OrderProcessExecute, the reply-to-queue-manager and the reply-to-queue are contained in the UserContext field. They are used to put the transformed message back to the original reply-to-queue. Any reply message from MQSeries Workflow that is not considered in this scenario, for example, process terminated or invalid XML message, is transformed in the compute node 'negative Reply to C' to a return code 999.

SET "OutputRoot"."MQMD" = "InputRoot"."MQMD";
SET OutputRoot.Properties.MessageSet = 'DI8UM7K076001';
SET OutputRoot.Properties.MessageType = 'Order_Message';
-- Enter SQL below this line.  SQL above this line might be regenerated, causing any modifications to be lost.
SET OutputRoot.Properties.MessageFormat ='CWF';
DECLARE I INTEGER;
DECLARE J INTEGER;
SET I = POSITION(' ' IN CAST(InputRoot.XML.WfMessage.WfMessageHeader.UserContext AS CHAR) ) - 1 ;
SET J = I + 2 ;
SET "OutputRoot"."MQMD"."ReplyToQ" = SUBSTRING(InputRoot.XML.WfMessage.WfMessageHeader.UserContext FROM 1 FOR I);
SET "OutputRoot"."MQMD"."ReplyToQMgr" = SUBSTRING(InputRoot.XML.WfMessage.WfMessageHeader.UserContext FROM J);

SET "OutputRoot"."MRM"."ReturnCode" = "InputBody"."WfMessage"."ProcessTemplateExecuteResponse"."ProcInstOutputData"."Order_Message"."ReturnCode";

Message Flow LookupRequest

The MQSeries Workflow ActivityImplInvoke XML message contains an Activity Implementation Correlation Identifier which is used by MQSeries Workflow to relate the ActivityImplInvokeResponse to the generated ActivityImplInvoke message. This field is required in the response. An option could be to route the 80-bytes field through the integrated application, receive it from the application response, and then use it for the MQSeries ActivityImplInvokeResponse message. But as a result, an already existing application would have to be changed. To avoid changing an existing application, the MQSeries Integrator DataInsert node is used to store this value in a database to have it available for the response message flow. To do this, two additional nodes in this message flow are needed. MQSeries Workflow requests only a response when the activity is modeled to be executed in a synchronous mode. In this case, the MQSeries Workflow ActivityImplInvoke XML message contains the field ResponseRequired with the value 'Yes'. ResponseRequired set to 'Yes' is the default, that means when this field is not contained in the message, the setting is also assumed. These cases are filtered with an MQSeries Integrator Filter node. If these is the case, the Activity Implementation Correlation Identifier is then stored in the database. In addition, there must be an key in the database to get the correct value for the response. This is done using the default MQSeries behavior. A default MQSeries-based application should get the request message identifier from the MQMD and returns it as correlation identifier in the response. So the following compute node ESQL code sets the MQMD message type to MQMT_REQUEST to get a response if ResponseRequired was set to Yes. In addition, the message identifier is then also stored in the database.

SET "OutputRoot"."MQMD" = "InputRoot"."MQMD";
SET OutputRoot.Properties.MessageSet = 'DI8UM7K076001';
SET OutputRoot.Properties.MessageType = 'Order_PartsInfo';
-- Enter SQL below this line.  SQL above this line might be regenerated, causing any modifications to be lost.
SET "OutputRoot"."Properties"."MessageFormat"='CWF';

SET "OutputRoot"."MQMD"."ReplyToQ"='LookupOut';
SET "OutputRoot"."MQMD"."ReplyToQMgr"=' ';
IF( "InputRoot"."WfMessage"."WfMessageHeader"."ResponseRequired"='Yes')
 THEN
  SET "OutputRoot"."MQMD"."MsgType" = MQMT_REQUEST;
End IF;

SET "OutputRoot"."MRM"."PartNumber" = "InputBody"."WfMessage"."ActivityImplInvoke"."ProgramInputData"."Order_PartsInfo"."PartNumber";
SET "OutputRoot"."MRM"."PartOrderQty" = "InputBody"."WfMessage"."ActivityImplInvoke"."ProgramInputData"."Order_PartsInfo"."PartOrderQty";
SET "OutputRoot"."MRM"."PartName" = "InputBody"."WfMessage"."ActivityImplInvoke"."ProgramInputData"."Order_PartsInfo"."PartName";

-- Add the following lines for character conversion. Needed for MQSWF V3.2.1.
SET OutputRoot.Properties.CodedCharSetId= 1252;
SET OutputRoot.Properties.Encoding= MQENC_NATIVE;

Message Flow LookupReply

As for the OrderProcessRequest, there is an MQInput node, a Compute node, and an MQOutput node defined. The following ESQL code shows how the Activity Implementation Correlation Identifier is read from the database and used for the MQSeries Workflow ActivityImplInvokeResponse message. To get the correct entry from the database, the MQMD correlation identifier from the incoming Lookup response message is used. In addition, the message flow contains a DataDelete node to remove the entry from the database, because it is no longer needed.

SET "OutputRoot"."MQMD" = "InputRoot"."MQMD";
-- Enter SQL below this line.  SQL above this line might be regenerated, causing any modifications to be lost.

SET "OutputRoot"."XML"."WfMessage"."ActivityImplInvokeResponse"."ActImplCorrelID"= THE(SELECT ITEM T.FMC_ACTIMPLCORRELID FROM Database.ACTIVITY AS T  WHERE T.MQ_MSG_ID = "InputRoot"."MQMD"."CorrelId" );
SET "OutputRoot"."XML"."WfMessage"."ActivityImplInvokeResponse"."ProgramRC" = "InputBody"."ReturnCode";
SET "OutputRoot"."XML"."WfMessage"."ActivityImplInvokeResponse"."ProgramOutputData"."Order_Message"."ReturnCode" = "InputBody"."ReturnCode";

Installation

Prerequisites

• DB2 UDB Version 6.1
• MQSeries Integrator Version 2.01 or later or WebSphere MQ Integrator Version 2.1 or later
• MQSeries Workflow Version 3.2.2 or later

• IBM VisualAge for C++ Version 3.5

Note: The MQSeries Integrator version shipped in December 2001 is called "WebSphere MQ Integrator".

Note: The samples in this SupportPac currently have been tested on the Windows NT platform only.

For information on how to install these products, see the related documentation.

Installation of this SupportPac

\fmcwinnt\SMP\MQSI\readme.html            \\ this documentation
\fmcwinnt\SMP\MQSI\*.gif                  \\ this documentation graphics
\fmcwinnt\SMP\MQSI\Order.fdl              \\ MQSeries Workflow order process
\fmcwinnt\SMP\MQSI\MQWFXML2.mrp           \\ MQSI MQSWFXML message set L2 export
\fmcwinnt\SMP\MQSI\MQSWFXML_Order2.mrp    \\ MQSI MQSWFXML_Order2 message set export
\fmcwinnt\SMP\MQSI\MQSWFXML_Order21.mrp    \\ WMQI MQSWFXML_Order2 message set export
\fmcwinnt\SMP\MQSI\OrderC.mrp             \\ MQSI OrderC message set export
\fmcwinnt\SMP\MQSI\MsgFlow02.exp          \\ MQSI MQSWF message flows export
\fmcwinnt\SMP\MQSI\ExecOrder.c            \\ sample Application ExecOrder source code
\fmcwinnt\SMP\MQSI\ExecOrder.mak          \\ ExecOrder makefile
\fmcwinnt\SMP\MQSI\ExecOrder.exe          \\ sample Application ExecOrder executable
\fmcwinnt\SMP\MQSI\Lookup.c               \\ sample Application Lookup source code
\fmcwinnt\SMP\MQSI\Lookup.mak             \\ Lookup makefile
\fmcwinnt\SMP\MQSI\Lookup.exe             \\ sample Application Lookup executable
\fmcwinnt\SMP\MQSI\fmctiord.h             \\ common sample application header file
\fmcwinnt\SMP\MQSI\mqsiqmq.mqs            \\ script to generate sample queues in MQSI Broker qmgr
\fmcwinnt\SMP\MQSI\mqsiqmcl.mqs           \\ script to generate MQ channels for MQSI Broker qmgr
\fmcwinnt\SMP\MQSI\fmcqmcl.mqs            \\ script to generate MQ channels for MQSWF qmgr
\fmcwinnt\SMP\MQSI\fmct3act.c             \\ sample MQSWF activity implementations
\fmcwinnt\SMP\MQSI\fmct3act.mak           \\ fmct3act.dll makefile

\fmcwinnt\bin\fmct3act.dll                \\ sample MQSWF activity implementation dll

Setting up the sample

It is assumed that you are familiar with the required products.

Setting up MQSeries Workflow

When the MQSeries Workflow configuration has finished, start the MQSeries Workflow Buildtime and import the file Order.fdl, which contains the sample MQSeries Workflow Order process. (Refer to Installation to check where the file has been installed.)

Because you have to use your Windows NT user ID to run this sample, you must add an MQSeries Workflow user with your NT user ID and your NT password including the authorization for the category Order Processes. Click the Staff tab in the Buildtime tree view and select Persons. Right-click and select New Person. Enter your user ID and password. Select Authorizations and make sure that the authorization is valid for the category Order Process.

The sample process is modeled so that all activities run in the scope of the starter of the process. The starter of the process is identified by the MQMD user identifier field of the incoming XML MQSeries message in MQSeries Workflow. Running the sample, this field contains the user ID of the user who started the ExecOrder sample application. Make sure that this user ID has the necessary MQSeries authorization to issue PUT for the required message.

The sample is designed so that the MQSeries Workflow XML message is put into the queue, called LookupRequestIn, of the queue manager, called MQSIQM. The queue manager MQSIQM is taken as queue manager name for the MQSI Broker. Any changes for the queue manager name for the MQSI broker must also be considered here. To change the queue manager name open the properties page for Network (-> Domain -> Group -> System -> Order) and enter a different queue manager name.

Having adapted the MQSeries Workflow process in Buildtime, export the process into an FDL file, for example, MyOrder.fdl. In Buildtime, click -> Export. Then import this new FDL file, called MyOrder.fdl, into MQSeries Workflow Runtime as described in Getting Started with Buildtime. From a command prompt, use the following command:

fmcibie -uADMIN -ppassword -yFMC -iMyOrder.fdl -t -o

MQSeries Workflow is now ready to run. The program needed to invoke the activities CheckOrder, AcceptOrder, and RejectOrder is implemented in the fmct3act.dll, which is copied during the installation into the bin directory of the MQSeries Workflow installation path. However, make sure that the defined queue WfOrderLookupIn and the queue manager MQSIQM exist. For information on how to create them, refer to Setting up MQSeries.

You can verify your MQSeries Workflow setup by starting the MQSeries Workflow Client (Start -> Programs -> MQSeries Workflow -> MQSeries Workflow Client - FMC). If you start the MQSeries Workflow Client for the fist time using your Windows NT user ID and password, one window displays showing a Tree View. Then, create a Process Template List, an Instance List, and a Worklist. To do this, select any one of these in the Tree View and right-click to open the context menu. Click Create New ... . Enter a name for the List, for example, TemplateList and click OK. Repeat these steps for the two remaining lists. A separate window displays for every list. In the Template list, there is the process template Order which represents the translated process model from Buildtime, called Order. In the Instance List, you can see an entry for every running Order process as soon as this process is started.

Setting up MQSeries

In addition to the queue managers, the MQ channels must be defined for the queue managers as well as additional queues for MQSI and the MQSeries-based sample application. This SupportPac contains three script files for MQSeries to create the required resources. The file extension is: mqs. Before you run them, check the contents and change them, if necessary for your environment. For details on how to create channels and transmission queues, refer to the MQSeries System Administration. See the chapter on Remote Administration.

• fmcqmcl.mqs

This file is used to define the required queue for 'send' and 'receive' from the queue manager FMCQM to MQSIQM. If you use other queue manager names than the proposed ones, change the queue manager name in this file as well. In addition, you must adapt the host name. Change the localhost to your host name and replace 1414 with the port as defined in the MQSI configuration. (1414 is the default port used by MQSeries.)

After having adapted this file to your environment, create the channel using the following MQ command from a command prompt:

runmqsc FMCQM < fmcqmcl.mqs

• mqsiqmcl.mqs

This file is used to define the required queue for 'send' and 'receive' from the queue manager MQSIQM to FMCQM. If you use other queue manager names than the proposed ones, change the queue manager name in this file as well. In addition, you must adapt the host name. Change the localhost to your host name and replace 5010 with the port defined in the MQSeries Workflow configuration on the Queue Manager page. (5010 is the default port used by MQSeries Workflow.)

After having adapted this file to your environment, create the channel using the following MQ command from a command prompt:

runmqsc MQSIQM < mqsiqmcl.mqs

• mqsiqmq.mqs

Additional queues are needed, for example, WfOrderLookupIn, where MQSeries Workflow puts an XML message and additional queues are needed as 'in' and 'out' queues for the MQSeries Integrator message flow as well as the MQSeries-based sample application. They must be created in the MQSI queue manager, using this command:

runmqsc MQSIQM < mqsiqmq.mqs

Alternatively, you can create the queues manually. Use this file to get the queue names for the sample, which are shown in the overview picture in section Sample Scenario.

Setting up MQSeries Integrator

When the MQSI Configuration Manager has started successfully, open a command prompt to import the message sets into the MQSI message repository. To do this, use the MQSeries Integrator command 'mqsimrmimpexp' and import these files: MQWFXML2.mrp, MQSWFXML_Order2.mrp and OrderC.mrp.

Note: The MQWFXML2.mrp is the same MQSeries Workflow XML message set as the one that is part of the MQSeries Workflow Event Sample SupportPac - WA06, Version 1.0. This means that it can only be imported once into MQSeries Integrator. If you try to import it again, for example, after you have already installed one of these SupportPacs, you get the following error message, which can then be ignored: Importing message set from MQWFXML2.mrp... BIP1973W: Duplicate message set identifier. The message set to be imported already exists in this repository.

Note: When using WebSphere MQ Integrator, use MQSWFXML_Order21.mrp instead of MQSWFXML_Order2.mrp.

mqsimrmimpexp -i MQSIMRDB Userid password MQWFXML2.mrp


mqsimrmimpexp -i MQSIMRDB Userid password MQSWFXML_Order2.mrp


mqsimrmimpexp -i MQSIMRDB Userid password OrderC.mrp

Next, select the Control Center Import (File -> Import) to import the message flows. They are part of the distributed file MsgFlow02.exp (refer to Installation where this file was installed). Select the Message Flows page where you see the newly imported message flows, such as OrderProcessExecute, OrderProcessReply, LookupRequest, and LookupReply. A little blue square displays next to the new message flows. This means that the new message flows are new and available only in your local workspace. To deploy them, you must check them into MQSeries Integrator. To do this, select every message flow. Right-click the context menu, then click 'Check In' or alternatively, in the tool bar, select File -> Local -> Save to Share, which checks in all objects from your workspace to MQSeries Integrator.

Set up the MQSeries Integrator Broker and deploy the sample message set and flow to the MQSeries Integrator Broker. To do this, select the Control Center Topology page, check out Topology, and click Topology -> Create -> Broker. Note that the broker itself should have already been created during the MQSeries Integrator Installation and Configuration. The step described here only creates a reference to the existing broker. Add the name and the name of the queue manager of the broker that is already existing. If you want to run the sample requiring less changes, you can use a broker with the queue manager name MQSIQM. Then, check in the newly created broker link and Topology or use File -> Local -> Save to shared.

Next, you must deploy the message sets and message flows to the broker. To do this, select the Assignment page of the MQSeries Integrator Control Center. Three windows are displayed. The window on the left displays the Domain Hierarchy, the window in the middle the Deployable Message Types, and on the right the Domain Topology is displayed. Check out the newly created broker. The broker should already contain an Execution Group with a name 'default', which you must check out. The window in the middle displays the Message Sets and Message Flows and on the right, the broker name is shown as well as the default Execution Group. Use the mouse to drag and drop the four sample message flows into the Execution Engine default area. Alternatively, use Add in the context menu for the default in the window on the left. Then, add the message set OrderC to the broker. Do not add all the other message sets to the broker. Check in all the changes.
Next, select the broker displayed in the window and right-click the context menu, click Deploy -> Complete Assignment Configuration. This starts to publish the information to the MQSeries Integrator Broker. A message box appears to inform you that the deployment has started. In the Control Center, select the toolbar, then File -> Log ... and click Refresh. When the deployment message tells you that the step was successful, the newly created information is available to the broker. The Control Center page Operation displays the broker and Execution Engine with the message set and message flows with a green traffic light next to them. This means that MQSeries Integrator is ready to wait for messages in the input queues to convert them as needed.

Setting up DB2

To use the sample, create a DB2 database, called MQSIFMC and a table, called ACTIVITY with the following settings:

CREATE TABLE ACTIVITY (MQ_MSG_ID CHARACTER (24)  NOT NULL ,
                              FMC_ACTIMPLCORRELID CHARACTER (80) )
                              DATA CAPTURE NONE  IN USERSPACE1
COMMENT ON COLUMN ACTIVITY.MQ_MSG_ID IS
'MQSeries Message ID for activity reply'
COMMENT ON COLUMN ACTIVITY.FMC_ACTIMPLCORRELID IS
'MQSWF Activity Implementation Correlation ID for activity response'

To create the database, you can also use the DB2 Control Panel, select Databases and right-click the context menu to create a new database using the SmartGuide. To use the sample, you only enter the new database name, for example, MQSIFMC, and click Done. Having successfully created the database, select refresh and select Tables under the newly created Database. Right-click the context menu to create a table using the SmartGuide. Enter the name of the table to use the sample ACTIVITY and click Next twice for the third Edit Columns page. Then, click Add to create the columns with column name MQ_MSG_ID, datatype CHARACTER and Length 24. Click OK. Create the second column with column name FMC_ACTIMPLCORRELID, data type CHARACTER, and Length 80. Click OK, then click Done. The DB2 database should then be created.

To use this database for MQSeries Integrator, you must create a new ODBC data source for this database in ODBC. To do this, select Start -> Setting -> Control Panel -> ODBC Data Sources. Switch to the System DSN page and click Add. Select the IBM DB2 ODBC DRIVER and click Finish. Select the newly created database MQSIFMC in the Database alias entry field and click OK.

For execution of the scenario one-phase commit protocol is enabled now to access the database. To enable two-phase commit protocol you need to add an XAResourceManager stanza for the database manager that your queue manager is going to coordinate. For more information how to do this refer to the MQSeries System Administration Guide.

Running the sample

1. Make sure that all NT services are running. To start the Windows NT services, start Windows NT, then select Start -> Settings -> Control Center. Double-click Services. Check that the following services are started:
• IBM MQSeries
• IBM MQSeries Broker ConfigMgr
• IBM MQSeries Broker MQSIBroker (this represents the broker you defined, for example, MQSIBroker)
• MQSeries Workflow 3.2 - FMC (or MQSeries Workflow 3.3 - FMC)
2. Make sure that the MQSeries Integrator services are running. To do this use the Microsoft NT Event Viewer.
3. Make sure that the MQSeries channels are running. To do this, start the MQSeries Explorer, then select (Start -> Programs -> MQSeries -> MQSeries Explorer). Select Queue Managers -> FMCQM -> Advanced -> Channels. Check that both channels (FMCQM.TO.MQSIQM and MQSIQM.TO.FMCQM) are running.

Otherwise start them. To do this, select the channel FMCQM.TO.MQSIQM and right-click the context menu to start the sender channel. Then, select Queue Managers -> MQSIQM -> Advanced -> Channels and select MQSIQM.TO.FMCQM. Finally, right-click to start this channel.

4. Starting the MQSeries Workflow Client. Select Start -> Programs -> MQSeries Workflow -> MQSeries Workflow Client - FMC. Log on with your user ID and password.
5. Open a command prompt to start the sample application Lookup. From this command prompt, invoke the Lookup sample MQSeries-based application using the following command:

Lookup LookupIn MQSIQM

where LookupIn is the input queue for the MQSeries-based sample application Lookup. MQSIQM is the queue manager of the MQSI Broker, called MQSIQM in the sample.
This application is implemented as a loop to handle several MQ messages. It should simulate a running backend application that must be started once. To stop this application, use Crtl-C in the command prompt where you started the application or close the command prompt window. This application sends the incoming C structure to the displayed window and puts a hardcoded return code in the reply queue.
6. Open a command prompt for ExecOrder. From this command prompt, start the MQSeries-based sample application ExecOrder, using the following command:

ExecOrder ExecOrderOut MQSIQM Smith

where ExecOrderOut is the input queue for the message flow OrderProcessExecute. MQSIQM is the queue manager of the MQSI Broker. To enter the name Smith is optional, it is used as a customer name in the sample.
7. Switch to the MQSeries Runtime Client and refresh the Work Items window. You should have a new work item, called 'Check order for Smith' in the worklist. The process is defined to start this activity manually. Double-click on this work item to start it. Another work item, called 'Lookup for Part Thinkpad' appears in the worklist after refresh and the state is running. As a result, you get the values that are assigned by ExecOrder to a C structure and put into the queue. This application then waits for the requested reply. Depending on the work items refresh policy settings Pull or Push, it can be necessary to refresh the work items view manually to see the updates in the MQSeries Workflow Runtime Client.
8. Switch back to the MQSeries Workflow Runtime Client. You should now have a new work item 'Order for Smith accepted' on the worklist. This activity must be started manually just like the first activity. After this activity is executed, switch to the ExecOrder command prompt, where this applications receives the MQSeries Workflow Order process response, sends it to the displayed window, and terminates.

When you run the sample, the windows displayed are similar to the following figure:



Handling problems and errors

Following are hints and tips to help you in case of problems with the sample or your scenario.
• Check that the Windows NT Services are running. Click Start -> Settings -> Control Panel. Start Services. Check that all services are started. In addition, check the Windows NT Event Viewer for messages. In the event log viewer you should also check for messages in the application log.
• Next, check that the MQSeries channels are running.
• ExecOrder puts a message in the specified queue. If this is not the case, you get an MQ put error message, which must be corrected. As soon as the message arrives in the MQSeries Integrator queue, it should be converted by MQSeries Integrator and the result is written into the MQSeries Workflow XML message input queue and an MQSeries Workflow process will be initiated and started. If MQSeries Integrator cannot transform a message, the message stays in the input queue of the message flow OrderProcessExecute and MQSeries Integrator retries to transform it. During the creation of the MQSeries queue ExecOrderOut, a Backout Reply Queue Name (WfSmpError) was defined with a Backout Threshold and a value of 3. This value is used by the MQSeries Integrator. This means that after 3 unsuccessful tries of transforming the incoming message, MQSeries Integrator will put the original message in the queue WfSmpError message.

To check for MQSeries Integrator messages, use the Microsoft Event Viewer. To do this, click Start -> Administration Tools -> Event View. Check that all services are started. In addition, check the Windows NT event log and look for messages. In the event log viewer you should also check for messages in the application log.

If the sample does not run as expected, it can be useful to check the Current Depth of the queues using the MQSeries Explorer. The counter will be increased when a new message arrives in the queue. This helps to determine which of the components causes the problem. For example, if the WfSmpError queue contains the message from ExecOrder, the problem could be within the MQSI message flow. In this case, check the next item in this list. If a message arrives in the FMCQM transmission queue, the problem is caused because the channel is not running. Use the Sample Scenario description to follow the expected flow and see where the flow stops.

• Check the MQSeries Integrator trace. When a problem occurs that most likely could be an MQSeries Integrator message transformation problem, analyze the MQSeries Integrator trace. To do this add trace nodes into the message flows or use the MQSeries Integrator user trace. To do this, invoke the MQSeries Integrator trace on the Operation page in the Control Center. Select the flow and click the context menu to start the user trace on debug level. Then, restart your message flow. Invoke the following commands on the command line:

mqsireadlog MQSIBroker -e default -u -f -o trace.xml
mqsiformatlog -i trace.xml -o trace.txt

Then, check the trace.txt file for error messages.
• Check the MQSeries system log and error log.
Use the MQSeries Workflow administration utility to view these logs. To do this invoke the following command on the command line:

fmcautil -uADMIN -ppassword

Then select l, press enter. Select l again to list the MQSeries Workflow messages.
• If you use another MQSeries Integrator queue manager than MQSIQM, adapt your changes in the command-line parameters of ExecOrder and Lookup. In addition, modifiy the UPES definitions in MQSeries Workflow. You must also modify the queue manager name MQSIQM in the mqs files (fmcqmcl.mqs and mqsiqmcl.mqs) to the queue manager name of your MQSeries Integrator broker.
• If you use another MQSeries Workflow queue manager than FMCQM, adapt your changes in the MQSeries Integrator message flows StartOrderExecute and LookupReply.

Change log

Changes in Release 1.0.1 - 30 Oct 2000

• Renaming of SupportPac number from MA03 to WA02
• Change of software required from 'MQSeries Workflow Version 3.2.2' to 'MQSeries Workflow Version 3.2.2 or later'
• Change of software required from 'MQSeries Integrator Version 2.0' to 'MQSeries Integrator Version 2.0 or later'

Changes in Release 1.1 - 30 Mar 2001

• Replacing message set MQSWFXML level 1 (MQSWFXML.mrp) by MQSWFXML level 2 (MQWFXML2.mrp), which contains the MQSeries Workflow Version 3.3 XML message enhancements.
• Replacing message set MQSWFXML_Order (MQSWFXML_Order.mrp) by MQSWFXML_Order2 (MQSWFXML_Order2.mrp), which is based on the new MQSWFXML level 2 message set.
• Change of software required from 'MQSeries Integrator Version 2.0' to 'MQSeries Integrator Version 2.01 or later'.
• Updates in the documentation to reflect the above changes.

Changes in Release 1.2 - 30 Nov 2001

• Adding MQSWFXML_Order21.mrp for the message set MQSWFXML_Order2 to support 'WebSphere MQ Integrator Version 2.1'.