Web Services Process Management Toolkit

IBM MQSeries Workflow SupportPac WA07 README

Web Services Process Management Toolkit
Version 1 Release 2

IBM

Contents

Introduction

The Web Services Process Management Toolkit allows you to compose any Web Services, add control logic, and include them into a business process to achieve the defined business goal. A Web Service can also be implemented as a business process, which can then be executed unter the control of a process management system. To model and run such a business process, the Web Services Process Management Toolkit uses IBM MQSeries® Workflow to manage business processes.
The following sections provide information about Web Services and MQSeries Workflow. You find details on what the Web Services Process Management Toolkit has to offer.

What are Web Services?

Web Services are self-describing, self-contained, modular applications running on the Web for the benefit of enterprises who want to create innovative processes and value chains. Web Services are Internet applications that fulfill a specific task or set of tasks that work with many other Web Services to carry out part of a complex workflow or business transaction. Web Services are deployed on the Web as platform-neutral applications using the Web Services Description language (WSDL). The service description contains the interface of the service, its data types, binding information, and network locations. The service description is published to a registry. The Web Services architecture comprises the following components:

For more information about Web Services, read the articles and columns offered in developerWorks' Web Services Corner at http://www.ibm.com/developerworks/webservices.

What is Business Process Management?

Business process management (BPM) puts the business process in the center of the execution of any business offering, such as a business service. To carry out a business process efficiently is mission critical and vital for an enterprise. Business process management has to satisfy these issues:

What is MQSeries Workflow?

MQSeries Workflow (MQWF) supports the specification and execution of long-running, interruptible, and potentially interactive business processes. A workflow process contains a set of activities. In a Web Services context, each activity represents a business service that contributes to the overall business goal of the process. An activity can either be implemented by a single operation provided by a software or a sub-flow. You can also define an activity to interact with people, for example to handle exceptions. Connectors between activities determine control and data flow within a process; business rules can be associated with connectors to control the paths through a process, as well as to data mapping to specify how data passes between activities.

The MQWF process modeling component supports the definition of workflow models and related meta data (for example, data structures for activity signatures and program definitions needed for activity implementations). Workflow models are translated into a Flow Definition Language (FDL) that is deployed within the MQWF process execution environment. The MQWF Process Execution Server interprets these models and invokes the software components that implement the activities in the workflow model.

For more information about MQSeries Workflow, refer to the MQSeries Workflow home page http://www.software.ibm.com/ts/mqseries/workflow.

About the Web Services Process Management Toolkit

The Web Services Process Management Toolkit (WSPMTK) allows you to compose any Web Services and include them into a business process to achieve the defined business goals. A Web service can be implemented as a business process, which can then be executed unter the control of a process management system. To model and run such a business process, the WSPMTK uses IBM MQSeries Workflow to manage business processes.

The WSPMTK combines business process management technology with Web Services and offers the tools and samples needed. The WSPMTK tools and samples complement MQWF, Web Services Toolkit (WSTK), and Web Services Development Environment (WSDE) and allow you to create complex Web Services. You can:

Note that the relationship between Web Services and Business Process Management is not only restricted to MQSeries Workflow. You might want to use message brokering facilities to exchange information between Web Services as well as information routing and transformation services. IBM MQSeries Integrator supports the implementation of message flows that define processing of in-flight information by a set of message processing services. Another technology are micro-flows that support the realization of complex operations of Web Services; a WebSphere micro-flow can choreograph the interaction of a set of Web Services to process the business function offered by an operation. For more information about the relationship of Web Services and Business Process Management, refer to the Web Services and Business Process Management  White Paper at the dynamic e-business page http://www-4.ibm.com/software/solutions/webservices/resources.html.

You find more details about the Web Services Process Management Toolkit in the following sections. The section Using the Web Services Process Management Toolkit describes the programs and steps that need to be taken to use the toolkit.

Components of the Web Services Process Management Toolkit

The Web Services Process Management Toolkit consists of the following components:

Implementing Web Services as a Process

If a Web Service is implemented as a process, at run time a service requester submits a Web Service request to the Web Service provider, in this case the SOAP Apache server running embedded in the Web application server. The Web Service provider is a generic implementation delivered with the WSPMTK, which in turn intercepts and transforms the request into an XML format, which can be interpreted by MQWF based on the request and on the deployment descriptor that describes the service. Consequently, the implementation of the Web Service provider acts as a generic service adapter; it handles the transformation from the service request to the XML message, which is interpreted by MQWF Runtime to execute a process instance, and from the MQWF XML response message to the service result. This is shown in the following figure:


Figure 1. Invoke a process by means of a Web Service

The process, which is the implementation of a Web Service, can be modeled in MQSeries Workflow Buildtime and exported into Flow Definition Language (FDL) defining the MQWF process in a textual format. From this process definition, you can derive the definition of a Web Service, which is implemented by this process, including the SOAP binding for this Web Service. The following figures show an excerpt of an FDL item describing the interface of a simple workflow process and the WSDL rendering of this interface.
 

STRUCTURE 'CreditInfo'
  'CreditRequestor': STRING;
  'CreditAmount': LONG;
?
END 'CreditInfo'

PROCESS 'CreditRequest' ( 'CreditInfo', 'CreditInfo' )
?
END 'CreditRequest'

Figure 2. Sample process definition (FDL)


<?xml version='1.0'?>
<definitions name="MQWFService" ? >
<message name="CreditInfoInput"> <part name="CreditInfo" type="xsd1:CreditInfo"/> </message>
<message name="CreditInfoOutput"> <part name="CreditInfo" type="xsd1:CreditInfo"/> </message>
<portType name="CreditRequest">
  <operation name="CreditRequest">
    <input message="CreditInfoInput"/>
    <output message="CreditInfoOutput"/>
  </operation>
</portType>
<binding name="CreditRequestSOAPBinding" type="CreditRequest"> ? </binding>
<service name=?CreditAgencyService?>
  <port name="CreditRequestPort" binding="CreditRequestSOAPBinding">
    <soap:address location=?http://??/>
  </port>
</service>
<types>
  <xsd:schema ? > 
    <xsd:complexType name='CreditInfo'>
      <xsd:element name='CreditRequestor' type='xsd:string' minOccurs='0' maxOccurs='1'/>
      <xsd:element name='CreditAmount' type='xsd:integer' minOccurs='0' maxOccurs='1'/>
    </xsd:complexType>
  </xsd:schema> 
</types>
</definitions>
Figure 3. Corresponding WSDL






The following figure shows the steps that must be taken to promote a process as a Web Service.
 

Figure 4:Processes as Web services


  1. The service provider models a process using the MQWF process modeling component and generates the FDL representation of this process.
  2. The service provider then generates a WSDL file from this FDL file using a converter that extracts the process interface definitions from FDL. This WSDL serves as the Web Service interface description for any service requesters.
  3. The WSDL file might be used to publish the Web Service into UDDI, for example, by using the Web Services Toolkit (WSTK).
  4. Based on the WSDL file, a deployment descriptor and the client proxy code are generated by the Web Services Process Management Toolkit (WSPMTK).
  5. The client proxy code is used by the service requester to build a client application.
  6. The deployment descriptor is deployed to the SOAP server to make the service known to the generic SOAP service provider.
  7. The client proxy code is used by the service requester to invoke the service at run time.
When promoting a process as a Web Service, process life-cycle operations can be generated, for example, an operation to spawn across a process, or to call a process. The operation name itself can be a user-specified name. The mapping between the user-specified operation and the life-cycle operation of the process is done by the generic Web Service provider based on the information in the deployment descriptor. See the section The Deployment Descriptor  for a description of the deployment descriptor.

Composing Web Services

A Web Service can provide the implementation for an activity within the context of an MQWF process; a process then acts as a service requester. A user-defined program execution server (UPES) is the component to handle the invocation of a Web Service as the implementation of an activity. Once the activity implementation is due to be invoked as part of the process navigation, MQWF sends an XML message to the UPES. This message carries all the data needed for the service invocation; the content of the message identifies the Web Service and specifies its parameters. Acting as a client to the Web Service, the UPES calls the specified Web Service via a proxy. Optionally, the UPES can return the result of the Web Service as an XML response message to MQWF. This message signals the completion of the activity implementation.

Figure 5. Invoke a Web Service as activity implementation






The following figure shows the steps needed to use a given WSDL-defined Web service as implementation of an activity in an MQWF-driven process:

Figure 6. Invoke Web service as activity implementation (sample scenario)

  1. The service requester searches for the service in UDDI, selects a service, and extracts the WSDL document from UDDI, for example, by using WSTK.
  2. The service requester then generates an FDL stub based on the WSDL definitions. The FDL stub contains the program definitions to call the Web Service as well as an activity stub representing an activity that is implemented by a Web Service.

  3. Note: This functionality is currently not part of the WSPMTK. It is planned for the future.
  4. The WSDL document might also be used to generate client proxy code used by the Web Services UPES.
  5. The service requester models the process in the MQSeries Workflow modeling component, exports it into FDL and imports the process into MQWF Runtime.
  6. When the process is executed and the activity, which is implemented by a Web Service is started, control is given to the Web Services UPES.
  7. The Web Services UPES collects the necessary information to invoke the Web Service based on the client proxy code or based on the WSDL document.
  8. The Web Services UPES then calls the Web Service. When the Web Service returns, the Web Services UPES returns the result to MQWF and process navigation continues.
 
The following figures show an excerpt of an WSDL document describing a Web Service and the FDL definition to invoke this Web Service.

 
<wsdl:portType name='WebServiceGetStockQuote'>
 <wsdl:operation name='WebServiceGetStockQuote'>
  <wsdl:input message='StockSymbol_InMsg'/>
  <wsdl:output message='StockPrice_OutMsg'/>
 </wsdl:operation>
</wsdl:portType>

....

<wsdl:service name='SampleService'>
 <wsdl:port name='WebServiceGetStockQuote_Port' binding='WebServiceGetStockQuote_Binding'>
  <soap:address location='http://localhost:8080/soap/servlet/rpcrouter'/>
 </wsdl:port>
</wsdl:service>
 

Figure 7. Sample WSDL document


...
PROGRAM 'getQuote' ( 'StockSymbol', 'StockPrice' )
    PARAMETER "SOURCE=WSDL;DOCUMENT=http://www.wspmtk.com/sample/wsdl/SampleService.wsdl;
    SERVICE=SampleService;PORT=WebServiceGetStockQuote_Port;OPERATION=WebServiceGetStockQuote;"
END 'getQuote'

SERVER 'WSUPES'
  TYPE USER_DEFINED_PROGRAM_EXECUTION_SERVER
    MQSYSTEM MQSERIES
    MESSAGE_FORMAT XML
    PHYSICAL_QUEUE_NAME "WSUPESRequestQ"
    QUEUE_MANAGER_NAME "FMCQM"
END 'WSUPES'

PROCESS 'WSGetStockQuote' ( 'StockSymbol', 'StockPrice' )
   PROGRAM_ACTIVITY 'GetStockQuote' ( 'StockSymbol', 'StockPrice' )
    ...
    PROGRAM 'getQuote'
    PROGRAM_EXECUTION_UNIT 'WSUPES.FMCSYS.FMCGRP'
    SYNCHRONIZATION NESTED
  END 'GetStockQuote'
END 'WSGetStockQuote'
 

Figure 8. Corresponding FDL

In this version of the toolkit, the Web Services UPES only offers static specification of a Web Service as an implementation for an activity during design time. Dynamic lookup and binding of a Web Service just-in-time during the execution of a process is an option for the future. This requires interaction with a service registry during run time to find and bind a Web Service, based on criteria that are specified during design time. For more information about the Web Services UPES refer to chapter Generic Web Service UPES.

Modeling the invocation of a Web Service

To model the invocation of a Web Service, you must carry out the following steps in MQWF Buildtime:
  1. Create a User-defined Program Execution Server (UPES) for the Web Services UPES. The default name for the UPES input queue is WSUPES.
  2. Create a data structure that contains the parameters of the Web Service. The data structure members must have the same name, order, and type as the Web Service parameters.

  3. If you are using the client proxy code, the following contraints apply:
  4. Create a program for the Web Service with the following program parameters:
  5. Within the process, create a program activity that represents the Web Service to be executed. Select the UPES that you defined in step 1 as execution unit.

Using the Web Services Process Management Toolkit

As outlined in Figure 4, several steps are necessary to make a process available as a Web service:

Generating a Web Service definition from an FDL file and deploying it

  1. Create an FDL file containing the description of one or more processes. The FDL file can be generated by using the Export to FDL function of the MQWF Buildtime or by using the fmcibie Runtime import/export utility. Using fmcibie extracts modeling data from Runtime instead of Buildtime and ensures that the FDL definitions are equivalent to the definitions that are used by MQWF Runtime. The syntax for fmcibie is described in the MQSeries Workflow - Getting Started with Buildtime book. Following is an example of a typical invocation which exports all FDL definitions of a process, called 'WebCreditRequest' to a file called sample.fdl:

  2. fmcibie /e=sample.fdl /u=admin /p=password /c"EXPORT PROCESS WebCreditRequest DEEP"
  3. For each complex type that is present in the input and output signature of the process, Java wrapper and optionally (de-)serializer classes have to be provided. If a STRUCTURE includes other nested STRUCTUREs, wrappers and optionally (de-)serializers need to be provided as well. You can generate (de-)serializers by using the toolkit or you can use existing Java classes that represents the data structures, for example, Address.
  4. A deplyoment descriptor that describes the characteristics of the SOAP service through which the process will be accessible needs to be provided.
  5. Optionally, if you want to allow a client program to access the Web Service, a convenience class (a Java client proxy) is provided.
  6. The Java classes mentioned above need to be compiled and deployed. To deploy them, the deployment descriptor needs to be passed to the SOAP Service Manager.
Although the above mentioned steps appear to be tedious, you get all the necessary information to carry out these steps by using the FDL file that you created in the first step. You can use a tool to automate all other steps. The tool, called fdl2wsdl Translator, is described in the next section.

The fdl2wsdl Translator

The fdl2wsdl translator is a program written in pure Java, which uses two source files as input -- an FDL file and a configuration file -- and produces several output files: The configuration file, which is used by the translator (fdl2wsdl.cfg by default) can be altered by defining the file name via a system property named FDL2_CFG. This allows you to have individual configuration files (and thus different translation instructions) for different projects. For example:

fdl2wsdl sample.fdl will use the configuration file fdl2wsdl.cfg

while

set FDL2_CFG=other.cfg
fdl2dtd sample.fdl service.wsdl

uses the configuration file other.cfg and the generated WSDL file is named service.wsdl.

How to use the fdl2wsdl program

fdl2wsdl is a (Windows) shell script for convenient command-line invocation of the translator. To invoke the translator from a Java program, the translator class can be used directly. An invocation can look like this:

java.util.Properties props = System.getProperties();
props.setProperty("FDL2_CFG", "other.cfg");
com.ibm.workflow.util.fdl.make.WSDL.main(new String[] { "sample.fdl", "output.wsdl" });

which would be the program equivalent to the second example shown above.

Configuration

Most aspects of the code generation process (for example, chosen namespace names, configuration options for the deployed service, which life cycle methods of a process are exposed as a Web Service or where is the generated code located) can be customized via appropriate settings in the configuration file, which is used by the fdl2wsdl translator. The settings are documented in the default configuration file fdl2wsdl.cfg.
 

Generic Web Service Provider

The generic Web Service provider is a SOAP provider implementation, which intercepts SOAP requests, transforms them into MQWF XML requests, transmits them to MQWF, transforms, and passes the MQWF response back to the SOAP requester. For more information about a SOAP provider, refer to the Apache SOAP package at http://xml.apache.org/soap/index.html
The Web Service provider uses the information in the deployment descriptor to execute these steps. See the section The Deployment Descriptor for a description of the outline of the deployment descriptor.
To serialize and de-serialize the SOAP message parameters into Java beans and MQWF XML parameters, the generic Web Service provider uses two transformers, a generic and a typed one:

To launch a Web Service that is implemented by a process, the Web Service provider has to be known by your Web application server that is hosting the SOAP server. The Web Service provider either uses the JMS or the MQSeries interface to communicate with MQWF, based on your definitions in the deployment descriptor of the Web Service. See the Installation instructions for more information.

Limitations:


Generic Web Service UPES

The generic user-defined program execution server (UPES) for Web Services allows you to call a Web Service as an activity implemetation of a process. The UPES can use client proxy code or a WSDL document to invoke the service. The UPES receives this information from the program parameters of the program definition, which is passed to the UPES when the activity is started.
If client proxy code invocation is used, the Web Services UPES introspects the client proxy code method that is to be used for the Web Service invocation. It creates the parameters of the method by introspecting their constructors. Then, the method is invoked and the return parameter is processed accordingly.
If WSDL document invocation is used, the Web Services UPES introspects the WSDL document and calls the Web Service based on this information. Note that the WSDL document is referenced as URL and might be available "life" on the Web.

Currently the UPES only supports static binding of a Web Service. In the future, dynamic binding during run time can also be supported, which involves a query in UDDI. For information about setting up the Web Services UPES, refer to the Installation instructions.
For a description of how to model the invocation of a Web Service as well as the parameters to be used refer to Modeling the invocation of a Web Service.

Limitations:

The Deployment Descriptor

In addition to the values that a standard deployment descriptor of the Apache SOAP package contains for publishing a Web Service to the SOAP server, the Web Service provider needs additional information to invoke the MQWF process. For a description of the standard SOAP deployment descriptor, refer to the Apache SOAP documentation. The additional information needed is specified in the deployment descriptor as isd:option element. They are generated by the fdl2wsdl generator, based on the values in the configuration file.
The following table describes additional option elements, which are used by the generic Web Service provider:
 
Parameter Value Comment
ServiceSchemaNamespace Name space The name space used by the service.
ProcessTemplateName Process template name The process template name of the process to be invoked.
MethodMap Alias=operation pairs A map of alias names that refer to process life cycle operations. The supported life cycle operations are:
  • call
  • spawn
  • terminate
  • suspend
  • resume
ProviderMsgPipeClass Name of message pipe class Specifies the message API to be used, either MQSeries or JMS. 
  • MQSeries: com.ibm.workflow.soap.provider.MQPipe
  • JMS: com.ibm.workflow.soap.provider.JMSPipe
ProviderXformerClass Name of transformer class Specifies the transformer to be used to serialize/de-serialize message parameters
  • Typed: com.ibm.workflow.soap.provider.TypedXformer
  • Generic: com.ibm.workflow.soap.provider.GenericXformer
AgentUserId Workflow user ID Workflow user ID to be used for life cycle operations terminate, suspend, and resume.
AgentPassword Workflow password Password of user ID
QueueManagerName Queue manager name Queue manager name of MQWF used by the generic service provider in case of MQSeries message API
QueueName Queue name Queue name of MQWF used by the generic service provider in case of MQSeries message API
ResponseQueueManagerName Queue manager name Queue manager name of the generic service provider in case of MQSeries message API
ResponseQueueName Queue name Queue name used by the generic service provider in case of MQSeries message API

The following figure shows a sample deployment descriptor:
<?xml version='1.0'?>

<!-- SOAP Deployment Descriptor for WSDL port 'WebServiceGetStockQuote', MQWF Process 'WebServiceGetStockQuote' -->
<!-- This file ("E:\wspmtk10\fdl2wsdl\.\output\WebServiceGetStockQuote_DD.xml") was generated -->
<!-- by MQWF WSDL Generator V1.2 on Sun May 13 17:13:41 GMT+02:00 2001 -->
<!-- from FDL file "E:\wspmtk10\fdl2wsdl\..\samples\getstockquote\getstockquote.fdl" -->

<isd:service xmlns:isd='http://xml.apache.org/xml-soap/deployment' id='urn:WebServiceGetStockQuote'>
 <isd:provider type   ='com.ibm.workflow.soap.provider.Provider'
               scope  ='Application'
               methods='WebServiceGetStockQuote'
               static ='false'>
  <isd:java class='com.ibm.workflow.soap.provider.Provider'/>
  <isd:option key='ServiceSchemaNamespace'   value='http://www.wspmtk.com/sample/schema'/>
  <isd:option key='ProcessTemplateName'      value='WebServiceGetStockQuote'/>
  <isd:option key='MethodMap'                value='WebServiceGetStockQuote=call'/>
  <isd:option key='ProviderMsgPipeClass'     value='com.ibm.workflow.soap.provider.MQPipe'/>
  <isd:option key='ProviderXformerClass'     value='com.ibm.workflow.soap.provider.TypedXformer'/>
  <isd:option key='AgentUserId'              value='ADMIN'/>
  <isd:option key='AgentPassword'            value='password'/>
  <isd:option key='QueueManagerName'         value='FMCQM'/>
  <isd:option key='QueueName'                value='EXEXMLINPUTQ'/>
  <isd:option key='ResponseQueueManagerName' value='FMCQM'/>
  <isd:option key='ResponseQueueName'        value='WEBSERVICE'/>
 </isd:provider>
 <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
 <isd:mappings defaultRegistryClass='com.ibm.workflow.soap.provider.MappingRegistry'>
  <isd:map encodingStyle     ='http://schemas.xmlsoap.org/soap/encoding/'
           xmlns:sns         ='http://www.wspmtk.com/sample/schema' qname='sns:StockSymbol'
           javaType          ='com.wspmtk.www.sample.schema.StockSymbol'
           xml2JavaClassName ='com.wspmtk.www.sample.schema.StockSymbolDeserializer'
           java2XMLClassName ='com.wspmtk.www.sample.schema.StockSymbolDeserializer'/>
  <isd:map encodingStyle     ='http://schemas.xmlsoap.org/soap/encoding/'
           xmlns:sns         ='http://www.wspmtk.com/sample/schema' qname='sns:StockPrice'
           javaType          ='com.wspmtk.www.sample.schema.StockPrice'
           xml2JavaClassName ='com.wspmtk.www.sample.schema.StockPriceDeserializer'
           java2XMLClassName ='com.wspmtk.www.sample.schema.StockPriceDeserializer'/>
 </isd:mappings>
</isd:service>
 

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.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and / or other countries.

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