IBM MQSeries Workflow SupportPac WA05
XML Development Toolkit and
Sample Scenario
Version 1 Release 1
Contents
Introduction
MQSeries Workflow provides an XML message-based interface that allows you
to:
-
Deal with process instances in MQSeries Workflow
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.
-
Invoke an activity implementation
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:
-
Utility for FDL-to-DTD transformation
A tool that uses FDL to create the corresponding XML DTD. You can use
the DTD, for example, to validate your MQSeries Workflow XML documents.
-
Utility for FDL to XML Schema (XSD) transformation
A tool that uses FDL to create the corresponding XML schema. You can
use the XSD, for example, to validate your MQSeries Workflow XML documents.
-
User-defined Program Execution Server (UPES) framework
The UPES Framework is a UPES implementation that helps you integrate
your applications. It encapsulates the access to the MQSeries queue as
well as to an incoming MQSeries Workflow XML message.
-
Test tools
The package consists of tools to validate that your MQSeries Workflow
XML messages are correct, to send XML messages to the MQSeries Workflow
Server, and to simulate a UPES.
-
XML sample scenario
The sample scenario illustrates how to start a process and invoke an
activity implementation using the XML interface of MQSeries Workflow. It
also uses the UPES framework.
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:
-
An FDL file to describe the container structures. The name of the FDL file
is to be passed on program invocation as the first parameter.
-
A configuration file to customize the translator. If no configuration file is specified, the
translator uses the configuration file fdl2dtd.cfg.
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:
-
The messages to be included in the DTD.
There is a template file fdl2dtd.tpl which contains the static
part of the DTD. This contents of this file is entirely copied to the output file with the
exception of the line containing the tag <!-- _GENERATED_DATA_STRUCTURE_DTD_
-->. This tag line is replaced with the ENTITY and ELEMENT
definitions which are derived from the FDL STRUCTURE definitions.
You can create your own template file which only contains the definitions
for the messages that you use. Specify your template file name in the [TEMPLATE]
section of fdl2dtd.cfg so that the generator uses your template
file.
This feature can be useful if you only want to use a subset of the
MQSeries Workflow messages, for example, the call-out messages, and you
want to generate the DTD as compact as possible.
-
The container structures to be included in the DTD.
You can specify a list of FDL STRUCTURE names to be skipped
during generation. You specify the names in the [SKIP] section
of
fdl2dtd.cfg.
This feature can be useful if container structures are not used in
messages and you do not want to modify the FDL where they are defined.
Note that the container structure names must be specified exactly as they
are mapped in the DTD, that is, without any embedded spaces. For example,
the FDL 'Default Data Structure' must be specified as 'DefaultDataStructure'.
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:
-
An FDL file to describe the container structures. The name of the FDL file
is to be passed on program invocation as the first parameter.
-
A configuration file to customize the translator. If no configuration file is specified, the
translator uses the configuration file fdl2xsd.cfg.
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:
-
The messages to be included in the XSD.
There is a template file fdl2xsd.tpl which contains the static
part of the XSD. This contents of this file is entirely copied to the output file with the
exception of the line containing the tag <!-- _GENERATED_DATA_STRUCTURE_XSD_ -->.
This tag line is replaced with the <conmplexType/>
definitions which are derived from the FDL STRUCTURE definitions.
You can create your own template file which only contains the definitions
for the messages that you use. Specify your template file name in the [TEMPLATE]
section of fdl2xsd.cfg so that the generator uses your template
file.
This feature can be useful if you only want to use a subset of the
MQSeries Workflow messages, for example, the call-out messages, and you
want to generate the XSD as compact as possible.
-
The container structures to be included in the XSD.
You can specify a list of FDL STRUCTURE names to be skipped
during generation. You specify the names in the [SKIP] section
of
fdl2xsd.cfg.
This feature can be useful if container structures are not used in
messages and you do not want to modify the FDL where they are defined.
Note that the container structure names must be specified exactly as they
are mapped in the XSD, that is, without any embedded spaces. For example,
the FDL 'Default Data Structure' must be specified as 'DefaultDataStructure'.
- The XML namespaces and their prefixes used for generation.
You can modify the XML namespaces used by the translator by editing the values contained in the
[SUBST] section of
fdl2xsd.cfg.
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:
-
MQSeries API skills to know how to read from and write to the MQSeries
UPES queue
-
XML skills to process an XML message
-
MQSeries Workflow skills to process an MQSeries Workflow XML message
-
UPES skills to know about the operational semantics of a UPES
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:
-
Xerces-J 1.0.3 or later ( available from http://xml.apache.org)
. The jar file of this product is delivered with MQSeries Workflow. You
find it in your Workflow installation path \smp\dpxml.
-
fmcupes.jar from the UPES directory.
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
-
A client application collects the input data of the process and creates
an XML message (ProcessTemplateExecute) to start an MQSeries Workflow process.
-
The client application sends the XML message to the XML input queue of
MQSeries Workflow.
-
MQSeries Workflow reads the XML message, parses it, and starts the process
identified by the template name provided in the XML message.
-
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.
-
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.
-
The UPES sends the response data as an XML message (ActivityImplInvokeResponse)
back to MQSeries Workflow.
-
MQSeries Workflow reads the XML response message, finishes the activity,
and process navigation continues.
-
Because the RiskFactor is high in this example, activity RequestApproval
is started.
-
Another XML message (ActivityImplInvoke) is sent to the UPES.
-
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.
-
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:
-
MQSeries Workflow server; Version 3.3 or higher
-
MQSeries Workflow client; Version 3.3 or higher to run the process
-
MQSeries Java bindings in the class path (MA88 support pack)
-
JDK 1.2.2 or later (from http://java.sun.com/products/jdk/1.2)
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:
-
Change user 'User' to your user ID. On Windows NT, this is the user ID
with which you are logged on.
Note that the user ID must be a valid MQSeries Workflow user ID and
conform to the MQSeries naming rules of the MQMD UserIdentifier field,
for example, no longer than 12 bytes. For more information, refer to the
IBM
MQSeries Programming Guide.
If you changed the installation defaults, change your network settings
in the xmlsample.fdl file as follows:
-
Change the system qualifier 'FMC' to the one that you are use for your
installation.
-
Change the system 'FMCSYS' to the one you use for your installation.
-
Change the system group 'FMCGRP' to the one you use for your installation.
-
Change the queue manager name 'FMCQM' to the one you use for your installation.
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:
-
UPES001
This is the queue where the UPES is listening for ActivityImplInvoke
XML messages.
-
CREDITREQUESTQ
This is the queue where the client application is listening for ProcessTemplateExecuteResponse
XML messages from MQSeries Workflow.
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:
-
In the 'UPES View' window, as shown below, click 'Start UPES' to start
the UPES application.
-
Change to the CreditRequestView window.
-
Click 'New Request...' to display a dialog asking for the customer information
as shown below.
-
The following scenario navigates through the process where activity 'AcceptCredit'
is not processed.
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.
-
The window that is displayed next informs you that the request was approved.
-
Click 'OK' to view the response message on the log entry of the CreditRequestView
window.
-
The 'UPES View' window displays all XML messages received or sent by the
UPES as well as logging information.
-
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.
-
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.
-
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.
-
If you click 'OK' in this window, you see the response XML message in the
log entry of the CreditRequestView window.
-
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:
-
UPES.java
Contains the code for accessing the input queue and listening for incoming
messages.
-
SchufaSampleListener.java
Implementation of the class which implements the risk assessment. The
implementation immediately creates a response to a given request.
-
CreditApprovalSampleListener.java
Implementation of a more complex UPES listener which displays a manual
approval window as soon as a request arrives.
-
CreditRequest.java
An application which puts a request into the MQSeries Workflow execution
server XML input queue.
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]