IBM MQSeries Workflow SupportPac WA05

XML Development Toolkit and Sample Scenario
Version 1 Release 1

IBM

Contents

Introduction

MQSeries Workflow provides an XML message-based interface that allows you to:
  1. Deal with process instances in MQSeries Workflow

  2. A process instance can be created, started, executed, terminated, suspended, resumed, or deleted by sending an XML message to the MQSeries Workflow XML input queue. Any application that supports the MQSeries Workflow XML message format can request an action on a process instance in MQSeries Workflow.
     
  3. Invoke an activity implementation

  4. An activity implementation is invoked from MQSeries Workflow by sending an XML message to a user-defined MQSeries queue. The queue can be defined for handling input to any MQSeries application that supports XML messages. This can be your own in-house application, or a standard product, such as MQSeries Integrator V2. This allows you to start any application listening to an MQSeries queue that supports the MQSeries Workflow XML message format. An application listening to the queue is called a User-defined Program Execution Agent (UPES).
For a description of the MQSeries Workflow XML message interface, see the IBM MQSeries Workflow Programming Guide.

This package contains tools as well as a sample scenario that can help you implement your own application, using the XML message interface of MQSeries Workflow. It provides:

MQSeries Workflow XML development toolkit

The MQSeries Workflow XML development toolkit consists of the fdl2dtd translator, the fdl2xsd translator, the UPES framework, and the test tools.

The message-based interface

MQSeries Workflow supports a message-based interface using the standard Extensible Markup Language (XML). The message-based interface supports handling of process instances and receiving messages that are sent by a User-defined Program Execution Server (UPES, call-in interface) as well as sending messages to a User-defined Program Execution Server (call-out interface).

The structure of the XML messages is documented in the MQSeries Workflow Programming Guide in the form of a Document Type Definition (DTD, part of the XML standard). The DTD provides a formal specification of the messages that can be sent or received by MQSeries Workflow and it supports an XML parser to validate the message formats. There are tools, such as the IBM MQSeries Integrator or CrossWorld's Message Adapters, that can leverage a DTD to automate message transformations or to generate code for enterprise application integration.

The DTD as described in the MQSeries Workflow Programming Guide shows only the static portion of the DTD because a message can contain container data, for example, the data that is passed in a process input container when the process instance is created or activity container data that is exchanged with a UPES. Because the structure of container data is not known in advance (as it can be freely modeled using MQSeries Workflow Buildtime), it is not possible to statically define DTDs for all possible parts of a message.

However, once the structure of the container data is modeled, it can be exported from Buildtime as any other process model data in plain text format, that is, in Flow Definition Language (FDL). This allows a tool to extract the structural container information from the FDL, build the corresponding DTD, and combine that DTD with the static part of the message DTD to form a complete DTD for all messages that can be created and received by MQSeries Workflow hosting a defined set of process models and container structures.

The following sections describe such tools in details, namely the fdl2dtd translator and the fdl2xsd translator. The former will generate DTD's while the latter will generate XML Schema.

The fdl2dtd Translator

The fdl2dtd translator is a Java program that uses two input files:

The fdl2dtd translator produces one output file which contains the generated DTD. The name of the output file can be provided as second and optional parameter when invoking the translator. If no output file name is provided, the name of the output file is generated by concatenating the stem of the input file name and adding the suffix '.dtd'. For example:

fdl2dtd sample.fdl produces the output file sample.dtd

fdl2dtd sample.fdl mydtd.out produces the output file mydtd.out

fdl2dtd sample.fdl mydtd.out mycfg.dat produces the output file mydtd.out using the configuration file mycfg.dat

fdl2dtd accepts as input any valid FDL file of MQSeries Workflow Version 3.3 and higher. All FDL definitions other than the FDL STRUCTURE definitions are ignored. Typically, an FDL file is generated by using the Export to FDL function of the MQSeries Workflow Buildtime or by using the MQSeries Workflow Runtime import/export utility fmcibie. When using the export feature of fmcibie, fmcibie ensures that the FDL contains the definitions currently used by the MQSeries Workflow Runtime Server. The syntax for fmcibie can be found in the IBM MQSeries Workflow Getting Started with Buildtime book. A typical invocation to extract all FDL STRUCTURE definitions stored in the Runtime database to a sample.fdl file is as follows:

fmcibie /e=sample.fdl /u=admin /p=password /c"EXPORT STRUCTURE *"

By default, the output generated by the fdl2dtd translator complies to the MQSeries Workflow message format, encompasses the complete DTD for all XML messages supported by MQSeries Workflow and includes the ENTITY and ELEMENT definitions for all FDL STRUCTURE definitions present in the FDL input file. The Configuration section describes how to modify the default behavior.

Calling the fdl2dtd translator from a Java program

fdl2dtd is a shell script for command-line invocation of the translator tool. To invoke the translator from a Java program, the translator class can be used as follows:

com.ibm.workflow.util.fdl.make.DTD.main(new String[] { "sample.fdl", "mydtd.out" });

Installation

You find the fdl2dtd translator package in subdirectory smp\xml\fdl2dtd with the following directory structure:

\bin      Shell script and configuration file, sample FDL
\lib     jar archive file
\docs    JavaDoc
\src       Source code for the fdl2dtd translator
\src\tpl   Default template

To run the translator (for example, using the supplied sample.fdl), you need a java.exe available in your PATH. The translator has been tested with IBM JDK 1.2.2 and Sun JDK 1.3.

Note that the fdl2dtd shell script can only be invoked from the \smp\xml\fdl2dtd directory. To change this behaviour you need to adjust the temporary CLASSPATH set up by the shell script. To use the translator class from within a Java program, you must add fmcowstk.jar to your CLASSPATH.

Configuration

Use the fdl2dtd.cfg configuration file to customize the generation of the DTD. You can customize:

Customization

The fdl2dtd translator can be used in batch mode and accepts file names as arguments. The DTD generated for the FDL STRUCTURE definitions cannot be changed. You can implement enhancements to allow other input sources or output sinks, for example, StringBuffers, to transport the STRUCTURE description or documentation from the FDL to the DTD or to make the translator invoke fmcibie periodically to refresh the DTD.

The full source code of the translator is included in this support pack. There are three classes in the \fdl2dtd\src directory:
 
com.ibm.workflow.util.fdl.make.Make A generic driver that deals with file handling and configuration
com.ibm.workflow.util.fdl.make.DTD To set parameters for the Make for DTD generation
com.ibm.workflow.util.fdl.make.StructureVisitor To implement a visitor pattern on the FDL parse tree, responsible for the bulk of the code generation

In addition, you find the Javadoc for all classes in the com.ibm.workflow.util.fdl.make package.

The source code allows you to enhance the functionality of the translator. If you add a function and want to share it with others, please send us your comments.

The fdl2xsd Translator

The fdl2xsd translator is a Java program that uses two input sources:

The fdl2xsd translator produces one output file which contains the generated XML Schema. The name of the output file can be provided as second and optional parameter when invoking the translator. If no output file name is provided, the name of the output file is generated by concatenating the stem of the input file name and adding the suffix '.xsd'. For example:

fdl2xsd sample.fdl produces the output file sample.xsd

fdl2xsd sample.fdl myxsd.out produces the output file myxsd.out

fdl2xsd sample.fdl myxsd.out mycfg.dat produces the output file myxsd.out using the configuration file mycfg.dat

fdl2xsd accepts as input any valid FDL file of MQSeries Workflow Version 3.3 and higher. All FDL definitions other than the FDL STRUCTURE definitions are ignored. Typically, an FDL file is generated by using the Export to FDL function of the MQSeries Workflow Buildtime or by using the MQSeries Workflow Runtime import/export utility fmcibie. When using the export feature of fmcibie, fmcibie ensures that the FDL contains the definitions currently used by the MQSeries Workflow Runtime Server. The syntax for fmcibie can be found in the IBM MQSeries Workflow Getting Started with Buildtime book. A typical invocation to extract all FDL STRUCTURE definitions stored in the Runtime database to a sample.fdl file is as follows:

fmcibie /e=sample.fdl /u=admin /p=password /c"EXPORT STRUCTURE *"

By default, the output generated by the fdl2xsd translator complies to the MQSeries Workflow message format, encompasses the complete XML Schema for all XML messages supported by MQSeries Workflow and includes the <complexType/> definitions for all FDL STRUCTURE definitions present in the FDL input file. The Configuration section describes how to modify the default behavior.

Calling the fdl2xsd translator from a Java program

fdl2xsd is a shell script for command-line invocation of the translator tool. To invoke the translator from a Java program, the translator class can be used as follows:

com.ibm.workflow.util.fdl.make.XSD.main(new String[] { "sample.fdl", "myxsd.out" });

Installation

You find the fdl2xsd translator package in subdirectory smp\xml\fdl2dtd with the following directory structure:

\bin      Shell script and configuration file, sample FDL
\lib     jar archive file
\docs    JavaDoc
\src       Source code for the fdl2xsd translator
\src\tpl   Default template

To run the translator (for example, using the supplied sample.fdl), you need a java.exe available in your PATH. The translator has been tested with IBM JDK 1.2.2 and Sun JDK 1.3.

Note that the fdl2xsd shell script can only be invoked from the \smp\xml\fdl2dtd directory. To change this behaviour you need to adjust the temporary CLASSPATH set up by the shell script. To use the translator class from within a Java program, you must add fmcowstk.jar to your CLASSPATH.

Configuration

Use the fdl2xsd.cfg configuration file to customize the generation of the DTD. You can customize:

Customization

The fdl2xsd translator can be used in batch mode and accepts file names as arguments. The XSD generated for the FDL STRUCTURE definitions cannot be changed. You can implement enhancements to allow other input sources or output sinks, for example, StringBuffers, to transport the STRUCTURE description or documentation from the FDL to the XSD or to make the translator invoke fmcibie periodically to refresh the XSD.

The full source code of the translator is included in this support pack. There are three classes in the \fdl2dtd\src directory:
 
com.ibm.workflow.util.fdl.make.Make A generic driver that deals with file handling and configuration
com.ibm.workflow.util.fdl.make.XSD To set parameters for the Make for XSD generation
com.ibm.workflow.util.fdl.make.StructureVisitor To implement a visitor pattern on the FDL parse tree, responsible for the bulk of the code generation

In addition, you find the Javadoc for all classes in the com.ibm.workflow.util.fdl.make package.

The source code allows you to enhance the functionality of the translator. If you add a function and want to share it with others, please send us your comments.

User-defined Program Execution Server (UPES) framework

Introduction

Implementing a UPES solution requires expert skills and knowledge in the following areas: This support pack provides a UPES framework that encapsulates MQSeries and XML APIs to simplify the implementation of a UPES. Using this framework allows to focus on the application implementation instead of concentrating on the UPES implementation. The UPES framework is written in pure JAVA. The source code is delivered with this support pack so that you can adapt the UPES framework according to your needs.

The UPES framework

The UPES framework is Java code that implements a User-defined Program Execution Server. As shown in figure 1, it reads MQSeries Workflow messages from a specified input queue, translates the messages into Java classes/objects, and passes the Java objects to so-called registered UPES listener programs. UPES listeners can register or stop registering to the UPES by implementing the UPESListener interface. The UPES framework checks each listener whether it is responsible to handle an incoming message. Data is passed to the first listener which claims the responsibility for the message. The listener processes the message and returns a result to the UPES framework which in turn returns a response message to the MQSeries Workflow server. All processing is done in a transactional context using MQSeries as the transaction manager.

If you implement an application that is invoked by a UPES, write a UPES listener for your application and register it with the UPES framework. There is no need for any XML or MQSeries-specific code.

The UPES is multi-thread enabled, that is you can start multiple UPES threads when launching the UPES.
 


Figure 1 - UPES framework
 

Note: The UPES framework is a sample implementation of Java UPES. This listener concept is one possible kind of implementation.

The UPES is implemented by the UPES class, the UPES listener interface by the UPESListener class. The XML sample scenario described below implements two sample listeners:

See UPESView.java sample code for an example that shows how to invoke the UPES from a java program.

Installation

You find the UPES framework package in the subdirectory UPES with the following directory structure:

\UPES          class archives

\UPES\doc   JavaDoc

\UPES\src    Source code

To run the UPES, you need the following packages in your CLASSPATH:

Note: The sample scenario setup consists of startup files that set your CLASSPATH.

Test tools

The purpose of the test tools is to assist you in testing your XML applications, for example, there is a tool that simulates a UPES. The tools are written in C++. The source code is not part of this support pack.

fmctqsxp

This tool can be used to check if your XML document is well-structured and a valid XML document.

To start the tool, enter the name of the tool and specify the XML file to be checked as parameter:
fmctqsxp my-first-xml.xml

The generated output of the tool is the XML document itself.

fmctqmsg

In addition to the checks performed by fmctqsxp, this tool checks if the XML document is a valid MQSeries Workflow XML message, for example, if the XML document starts with the WfMessage element.

To start the tool, enter the name of the tool and then specify the XML file to be checked as parameter:
fmctqmsg my-first-xml.xml

The generated output of the tool is a success message or an exception message explaining the error. The exception message corresponds to the type of message that an MQSeries Workflow Server sends.

fmctqreq

This tool simulates a client application sending an XML request message to MQSeries Workflow, receiving an answer, and saving it to a file. The XML request message is read from an external file.
The tool uses a parameter file as input parameter. A sample fmctqreq.ini parameter file is delivered with this support pack. Study this file for a description of the parameters.

To start the tool, enter the name of the tool and specify the name of the parameter file:
fmctqreq -l fmctqreq.ini

Note: If you want to send more than one XML request message to MQSeries Workflow, you must start the tool for every message to be sent.

fmctqups

This tool simulates a UPES implementation. It receives an MQSeries Workflow XML message from an input queue, extracts the ActivityImplCorrelId from the message, inserts it into a predefined XML skeleton response message, and sends the response message to MQSeries Workflow.
It uses a parameter file as input parameter. A sample fmctqups.ini parameter file is delivered with this support pack. Study this file for a description of the parameters.

To start the tool, enter the name of the tool and then specify the name of the parameter file:
fmctqups -l fmctqups.ini

Note: If you want to receive more than one XML message from MQSeries Workflow, you must start the tool for every message to be received.
 

Installation

You find the test tools package in subdirectory smp\xml\testtools with the following directory structure:

\fmctqsxp      fmctqsxp tool
\fmctqmsg     fmctqmsg tool
\fmctqreq      fmctqreq tool
\fmctqups      fmctqups tool

To run the test tools, you need a client connection to the queue manager where MQSeries Workflow is running.

XML Sample Scenario

XML sample scenario description

The sample scenario uses a simple workflow model, which encompasses the processing of a credit request by a bank. The credit request process comprises running a credit check, evaluating the credit check, deciding if the credit can be granted, and informing the customer accordingly.

Figure 2 illustrates the scenario.

Figure 2. Workflow model of XML scenario

A bank employee starts a client application (1) and is prompted to enter the customer information applying for credit as well as the credit amount. The client application then sends an XML request to MQSeries Workflow containing the customer information (2). MQSeries Workflow starts the CreditRequest process and passes the information to the first activity (3) where the risk of granting the credit is assessed. This activity is called 'AssesRisk' and is carried out by a UPES activity implementation. The activity implementation can be an in-house application or a third-party application, that is, an application written by a financial subcontractor. When the UPES receives the Invoke message from MQSeries Workflow, it starts (4) the 'AssessRisk' application. A credit report is created and, as a result, a credit report of the customer is created, which includes the risk factor: high, medium, or low. Control is given back to the CreditRequest process (a response is sent) where the next activity is started depending on the content of the credit report and the credit amount. If the risk is medium or high or if the credit amount is higher than 100000, control is passed to activity 'RequestApproval' (5). This activity is again carried out by the same UPES (6). The 'RequestApproval" activity implementation causes a bank employee to decide whether to grant the credit. While the 'AssessRisk' application is an automatic program without user intervention, the 'RequestApproval' application is a GUI application. If the credit is rejected, control passes to an activity that posts a notice for rejection of credit (7). If it is accepted, control passes for posting acceptance (8).

Everything gets done in good order by the right person in the right sequence. MQSeries Workflow ensures that the bank's defined and modeled process is followed. Every application gets processed properly and efficiently.

[top]
     

Message flow and system setup

Figure 3 illustrates the system setup and message flow of the XML sample scenario in detail.
 
 

Figure 3. Message flow and system setup
 
  1. A client application collects the input data of the process and creates an XML message (ProcessTemplateExecute) to start an MQSeries Workflow process.
  2. The client application sends the XML message to the XML input queue of MQSeries Workflow.
  3. MQSeries Workflow reads the XML message, parses it, and starts the process identified by the template name provided in the XML message.
  4. When the first activity AssessRisk is started, an XML message (ActivityImplInvoke) to invoke the activity implementation is sent to the UPES input queue by MQSeries Workflow.
  5. The UPES reads the message and checks the registered listeners, in this case the AssessRisk and RequestApproval listeners, whether they are responsible to execute this activity implementation. The AssessRisk listener claims responsibility and the UPES  passes the information to this listener. The AssessRisk listener processes the information and passes the response data back to the UPES.
  6. The UPES sends the response data as an XML message (ActivityImplInvokeResponse) back to MQSeries Workflow.
  7. MQSeries Workflow reads the XML response message, finishes the activity, and process navigation continues.
  8. Because the RiskFactor is high in this example, activity RequestApproval is started.
  9. Another XML message (ActivityImplInvoke) is sent to the UPES.
  10. The UPES reads the message and checks the registered listeners, in this case the AssessRisk and RequestApproval listeners, whether they are responsible to execute this activity implementation. The RequestApproval listener claims responsibility and the UPES passes the information to the RequestApproval listener. The approval request activity implementation is executed and the response is sent back by the UPES to MQSeries Workflow which navigates to the next activity AcceptCredit.
  11. When the AcceptCredit activity is finished, the process ends and the XML response message (ProcessTemplateExecuteResponse) is sent to the client application, which in turn displays the response.
[top]

Installation and setup

Installation files

You find the sample scenario package in the subdirectory smp\xml\XMLSampleScenario with the following directory structure:

/XMLSampleScenario          Shell script, class archives, FDL

/XMLSampleScenario/doc   JavaDoc

/XMLSampleScenario/src    Source code

In the following installation and setup descriptions all file names and directories are relative to the XMLSampleScenario directory.

Installation prerequisites

To run the sample, you need: In addition, the sample uses Xerces-J 1.0.3 ( available from http://xml.apache.org) . The jar file of this product is already delivered with MQSeries Workflow Version 3.3. You find it in your Workflow installation path \smp\b2b.

Setting up MQSeries Workflow

First, the sample FDL xmlsample.fdl must be adapted to your environment. In general, the sample fdl uses the installation defaults. If you use the installation defaults, then all you have to do is: If you changed the installation defaults, change your network settings in the xmlsample.fdl file as follows: Next, import the sample FDL into the appropriate system. For example, for FDL xmlsample.fdl, use the command:

fmcibie -ixmlsample.fdl -u<ADMIN_USERID> -p<ADMIN_PASSWORD> -o -t

Note: You can also import the fdl file into Buildtime and study the process model with the sample definitions.

Setting up MQSeries

To run the sample, there are two queues that are required. These queues must be created by you within the same queue manager which manages the queues of the MQSeries Workflow system group in which you want to run the sample.
The name of the queues are: To create the queues, you can use the MQSeries Explorer or the runmqsc utility. To create a queue with the runmqsc utility, enter the following commands:

Runmqsc FMCQM
DEFINE QLOCAL(UPES001) DESCR('Local UPES queue for requests')
 

Setting up your environment

To run the sample application, adapt file env.bat and set the environment variables according to your system.

Running the sample

To run the sample, you must have installed the MQSeries Workflow Runtime server and Client. The Client is needed because all the activities except for the UPES activities are implemented using the CreditRequest scenario executables delivered with the product.

To start the sample, you can run startup.cmd which adds fmcupes.jar and fmcxmlsm.jar to your classpath. Then it starts the UPES (UPESView) and the client application (CreditRequestView). In addition, a MQSeries Workflow Program Execution Agent (PEA) is started.
Note: Application UPESView automatically registers the delivered sample listeners.

Two windows 'UPES View' and 'CreditRequestView' are displayed, in which you can perform the following tasks:

  1. In the 'UPES View' window, as shown below, click 'Start UPES' to start the UPES application.


  2.  

  3. Change to the CreditRequestView window.

  4.  
  5. Click 'New Request...' to display a dialog asking for the customer information as shown below.


  6.  

  7. The following scenario navigates through the process where activity 'AcceptCredit' is not processed.

  8. Enter less than 100000 into the credit amount field, for example, 9999. Click 'OK' to check the XML message in the log window. This XML message is sent to the Workflow Server to be processed.


     

  9. The window that is displayed next informs you that the request was approved.


  10.  

  11. Click 'OK' to view the response message on the log entry of the CreditRequestView window.


  12.  

  13. The 'UPES View' window displays all XML messages received or sent by the UPES as well as logging information.

  14.  

     


     

  15. You can start a second process where the 'AcceptCredit' activity is processed. This is the case if the credit amount is greater than or equal to 100000. Click 'New Request...' in the CreditRequestView window to display a dialog that requests additional information.

  16.  
  17. Enter 100000 or a larger amount in the credit amount field. The process then runs the 'AcceptCredit' activity. Click 'OK' to view the XML message in the log panel. This XML message is sent to the Workflow engine to be processed.


  18.  

  19. The UPES displays a window requesting manual approval. Click 'Approve' or 'Reject' and the following window informs you that the request was approved or rejected depending on the decision you made.

  20.  

     


     

  21. If you click 'OK' in this window, you see the response XML message in the log entry of the CreditRequestView window.
  22. The UPESView window displays all XML messages received and sent by the UPES as well as additional logging information.

The sample source code

There are two kinds of java files: models and view. Models contain information to connect to MQSeries and to create the XML message. If there is a view for a given model, the file name is the same as the file name for the model with the additional suffix 'View'. For example, CreditRequest.java and CreditRequestView.java.

There are four major model files:

For more information, refer to the JavaDoc documentation.

[top]

How to send your comments

Your feedback is important in helping us to provide the most accurate and high-quality information. If you have any input, send us your comments by e-mail to: workflow@de.ibm.com

Trademarks:
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

IBM
MQSeries
Microsoft, Windows, Windows NT, and the Windows logo are registered trademarks of Microsoft Corporation in the United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Other company, product, and service names may be trademarks or service marks of others.

[top]