Deploying a BPEL Process

Introduction

Process deployment are integral functions of the ActiveBPEL Enterprise products. You can find detailed information on this topic in your product documentation: ActiveBPEL Server User's Guide.

ActiveBPEL Designer also provides the functionality required to build and deploy BPEL processes to the ActiveBPEL server. See: ActiveBPEL Designer User's Guide.

Deploying a BPEL process to a standalone ActiveBPEL engine requires construction and coordination of several files. This example takes you step-by-step through creation of a simple BPEL process including its WSDL definition), construction of the Process Deployment Descriptor (PDD) and Business Process Archive (BPR) files and, finally, deployment of the process into a Tomcat server environment where it will be available as a Web Service.

The BPEL process we'll create and deploy will be a variation on the standard "Hello, World!" application typically used as an introduction to other languages. To add just a little twist, we'll design our process to accept a message with two strings and return a concatenated result string. We'll call our process "echo".

Objectives

• Construct a WSDL Definition
• Implement a BPEL process
• Construct a Process Deployment Descriptor (PDD)
• Deploy a BPEL Process as a Web Service

WSDL File

The WSDL file for our echo process, echoDefs.wsdl, defines its available functions and the mechanism by which they are accessed.  The Web Service's interface to the outside world is defined in terms of portType, operations and messages and the access mechanism is defined in terms of partnerLinkType and binding.  Each of these has a section (or sections) defined by XML elements in a WSDL file.

wsdl:definitions

Our WSDL file starts out with the following text:

This first section defines a target namespace and the prefixes for the various external namespaces we'll use to define the Web Service details for the echo process.

Following the XML version specification, the outermost XML element is wsdl:definitions.  Note that this element name, as with all subsequent QName references that consist of a prefix, a colon and a name, is specified in a schema.  In this case, definitions is an element that is defined in the schema at http://schemas.xmlsoap.org/wsdl/, which you can actually view in a browser if you want.  The "wsdl" portion preceding the colon is a prefix, a shorthand abbreviation that references a namespace. The prefix is defined on the line that reads

      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

Each prefix used elsewhere in the file is defined in this manner.

By convention, the "tns" prefix usually has a special meaning, and is typically used to refer to the "this document's namespace". For our purposes this prefix, as well as the targetNamespace attribute of the wsdl:definitions element, points to this WSDL definition, i.e., http://docs.active-endpoints.com/activebpel/sample/wsdl/echoDefs/2006/09/echoDefs.wsdl.

wsdl:message

The Web Service supported by the echo process interacts with clients by receiving and sending messages. WSDL message definitions are specified using the wsdl:message element, and we'll need two: one to define an incoming request message and one to define an outgoing response message.

Note that echoRequest message has two parts, both defined as strings.  The echoResponse message has a single part, also a string, which will be the result after our process concatenates the two parts from the echoRequest message.

These are the only message definitions we'll need for our echo process.

wsdl:portType and wsdl:operation

The WSDL portType and operation are defined next.

We've named the portType for our WSDL Service EchoService and it has one operation: echo. That operation has an input message and an output message called echoRequest and echoResponse, respectively. These are the abstract definitions for the portType, operation and input/output parameters of the service. Concrete definitions will be created later in the wsdl:binding element.

Note that a wsdl:portType element may have multiple child wsdl:operation elements. Our process only supports one (echo).

wsdl:service

The wsdl:service element defines the address normally used to access the service and a reference to the binding information, which is found later in the file.

plnk:partnerLinkType

The partnerLinkType element is used to define a type of link between partners. Each partnerLinkType defines a role and each role references a portType. In our WSDL, there is only one partnerLinkType: echoPLT. echoPLT has a single role defined (echo) and that role references the EchoService portType, which was defined earlier.

As we'll see, this partnerLinkType definition is referenced in our BPEL process, as well as in our Process Deployment Descriptor.

wsdl:binding

The concrete nuts-and-bolts of accessing our echo process as a Web Service is defined in the wsdl:binding element.

This section specifies that the binding style for this Web Service will be SOAP / RPC. It defines a single operation, echo, with input and output elements whose name attributes match the message names defined earlier. The namespace attribute for the body of the input and output elements defined here as the target namespace for this WSDL, i.e., http://docs.active-endpoints.com/activebpel/sample/wsdl/echoDefs/2006/09/echoDefs.wsdl, though this is not a requirement. The rest of the parameters are determined by the schema that defines the SOAP protocol.

BPEL Process File

BPEL not only provides a mechanism to orchestrate Web Services, but when deployed, BPEL processes are Web Services in their own right.  Compared to the WSDL file, our BPEL process definition is simpler and shorter.  This is because most of the implementation details of a process regarding how to get at it, what messages it uses, what operations it performs, and how the incoming and outgoing data are formatted and marshaled are defined in the WSDL.

For simplicity our BPEL process is only slightly more complex than the standard "Hello, World!" application.  Here's the specification:

Receive a message containing two parts and respond with a message containing a single part whose value is the concatenation of the received parts' values.

Simple, no? We only need four BPEL activities to perform this task. Also, we won't need to invoke any external services, since an assign activity may contain copy operations that use expressions that support language constructs like concat(), which is exactly what we'll use. Here's the BPEL:

This process comprises a sequence activity that contains a receive, and assign and a reply.  Note the lines that are highlighted in blue italics.  These are the attributes whose definitions depend upon the information in echoDefs.wsdl, whose namespace is listed near the beginning of this file as http://docs.active-endpoints.com/activebpel/sample/wsdl/echoDefs/2006/09/echoDefs.wsdl and whose namespace prefix in this BPEL file is ns1.

Name this file echo.bpel.

Process Deployment Descriptor

A Process Deployment Descriptor (.pdd) file describes service binding and, optionally, the process version details for a BPEL process.

The service binding details describe the relationship between the partners defined in a BPEL file and the  implementation required to interact with actual partner endpoints (Web services). The descriptions include the binding information for each partner role and/or my role defined in a partner link.

For partner role endpoint references, the binding is described in the WS-Addressing standard format.

Endpoint References and WS-Addressing

The protocol to specify location information for an endpoint reference is based on the Web Services Addressing (WS-Addressing) specification.

The WS-Addressing specification standardizes the format for referencing a Web service allowing you to create uniquely identified Web services and Web service instances that are not bound to a specific transport mechanism, such as HTTP. Using WS-Addressing, the endpoint information is added to the header of a SOAP
request and not to the URL specified in the SOAP body.

Having endpoint reference information in a SOAP header means that you can do the following:

• Specify Web service instance IDs
• Select Reply To and Fault To addressees
• Select From endpoint references in the case where an acknowledgement needs to be sent back to the sender

The basic WS-Addressing syntax is as follows:

where:

Address is a mandatory element that identifies an endpoint. It may be a network address or a logical address.

ServiceName is the qualified name, or QName, for the service being invoked.

This service must be defined in a WSDL file that is deployed with the process or one that is available in the ActiveBPEL engine's WSDL catalog.

PortName identifies the service port being invoked.

You can review the WS-Addressing specification at the Web site of any of the specification's contributors, including IBM, BEA Systems, and Microsoft.

Endpoint References Requiring Credentials for Access

At deployment time, you must specify the location information for each partner link endpoint reference. If a partner's service requires authentication for access, you can add credential details to the partner link definition in the process deployment descriptor file.

The following example shows how to include credentials for a partner service in the process deployment descriptor file.

The tags and values in bold are required. A password is not required, but you must use the prefixed password tag if you are including a password.

Note the following details about the credentials definition:

• A WS-Addressing reference property points to the required namespace
• Add a prefix, such as aecred, to the namespace
• Use the prefix in the username and password tags

Partner Role Details

A Process Deployment Descriptor file contains an endpoint type for each partner role defined in a partner link. An endpoint type is a binding property that indicates how to communicate with the Web service the process interacts with. The different types give control over specifying services to work with now and in the future. For 
example, you can "hard-code" a service binding by making it static, or you can select more versatile options for changing and adding new service partners dynamically without redeploying the process.

The endpoint types are defined in the following table.

An example showing the syntax for specifying the endpoint type in the .pdd file is:

<partnerRole endpointReference="static">

My Role Details

The Process Deployment Descriptor file includes a binding style and service name for each partner link of my role type. The binding styles are the standard SOAP styles of RPC (remote procedure call), Message, and External. The style of RPC or Message should be appropriate for the simple, schema, or complex message variable manipulated by the service's operation.

An RPC invocation means that the body of a SOAP request has an outer element which matches the operation name and contains inner elements each of which maps to a parameter of the operation.

A Message invocation means the entire SOAP message consists simply of a single entity which is an XML document.

The Service Name is the name of the endpoint that ActiveBPEL creates for the BPEL process. This name must match the address in the binding section of the referenced WSDL file.

Allowed Roles is optional and specifies one or more security roles that an authenticated user must have in order to communicate with the BPEL process. If the application server is not configured with security then the allowed roles field is ignored.

Partner Definition Files

A partner definition file contains the endpoint information for a single service partner. The file contains one endpoint reference for each partner link type that the partner implements. The endpoint information applies to all partner links in BPEL processes that are deployed with the principal endpoint source. The authenticated principal must match the principal in the partner definition file.

For example, a service partner named National Bank can send an authenticated request to a BPEL process to assess the risk of loaning funds to a customer. The server looks up the authenticated principal to determine the correct endpoint to use to call back National Bank after the risk is assessed. This is useful because National Bank might have partner link types for additional services such as refinancing rates and insurance quotes. The partner definition file can contain one endpoint reference for each partner link type.

You can deploy the partner definition file by adding it as the only file in a business process archive, if desired. If partner definition details change, you do not need to redeploy a BPEL process. You can redeploy the .pdef file. There is only one .pdef file for each principal so the most recently deployed file for a principal sets all of the endpoints for that principal.

Note: To take advantage of a partner definition, the endpoint type for the partner link must be principal.

Example File:

The .pdd file that describes how our process will be deployed is fairly simple in this case.

There are a few external references in this new file.  The first one of these is xmlns:bpelns="http://docs.active-endpoints.com/activebpel/sample/bpel/echo/2006/09/echo.bpel", which comes from the target namespace defined in the BPEL process (see above).  Another is the name of the partnerLink definition – echoPLT – which must match the name of the partnerLink definition in the BPEL file.  Note that BPELs and PDDs can have multiple partnerLink definitions, and when they do there should be matching instances in the two files.  A third external reference is to the echoDefs WSDL file and its associated target namespace.  The path wsdl/echoDefs.wsdl describes where in the archive this file is located.

Finally, note the service value in the one and only partnerLink definition: echoService.  This is the Web Service name under which our process will be deployed in the ActiveBPEL engine.

Name the file echo.pdd.

Remember going forward that a BPR may contain multiple BPEL process files, and should have one of these PDD files per deployed process.

WSDL Catalog

The last file in our archive is a catalog of the WSDL and XML schema definitions needed to resolve all of the references throughout.  This file is named wsdlCatalog.xml.

When you use ActiveBPEL Designer to create a .bpr file, the .bpr wizard automatically generates a WSDL catalog. Information from the catalog is displayed in the Administration Console.

The WSDL catalog provides a way for the ActiveBPEL engine to find WSDL files within a .bpr deployment archive.

The following example shows the syntax for an entry in wsdlCatalog.xml.

The location attribute maps to a WSDL file in one of two ways. Its value is either the location attribute of a <wsdl> element in the wsdlReferences section of a .pdd file or the location attribute of an <import> element in a WSDL file.

When loading a WSDL file at deployment time, the ActiveBPEL engine reads the WSDL references from the .pdd file and uses the location attribute of the <wsdl> element as a key into the WSDL catalog. If the WSDL catalog contains a matching location, the engine loads the WSDL from the corresponding classpath. If no mapping exists in the catalog, the engine assumes the location is an absolute URL and attempts to load the WSDL from that location.

The classpath attribute indicates where the WSDL file resides in the .bpr file, relative to the root of the .bpr file's contents.

The wsdlCatalog.xml for this sample:

The location and classpath are the same, and both point to the location in the BPR where a given WSDL reference file is found (the archive directory structure is described below).

Archive Directory Structure

With the files needed for our deployment archive out of the way, we need look at the standard directory structure used in the archive:

The directory name "echo" is arbitrary and can be placed pretty much anywhere in your file system – it won't appear in the archive since it's considered the root.  You'll want to place echoDefs.wsdl into the wsdl directory and echo.bpel into the bpel directory, but what may not be obvious is that echo.pdd should go into the root (echo) directory and wsdlCatalog.xml should go into META-INF.

Creating the BPR

Once you've created your various files and placed them into the appropriate archive directory locations, you can use Java's jar tool to create the Business Process Archive (BPR) that will be deployed to the ActiveBPEL engine.  A BPR is like any other Java archive except thatit has only XML files, not .class files.  The idea's the same though, and the structure is a single file that can be managed easily.  In a DOS command window or Unix shell, change to the archive root directory (echo, in this case) and execute the following command:

This command creates echo.bpr, which is your deployable Business Process Archive.  Note that this file is similar to a .jar or .zip file, and can be opened for examination using a tool like WinZIP.

Deploying as a Web Service

Deploy the BPR file into a Tomcat environment with one step: copy echo.bpr into the $CATALINA_HOME/bpr directory, e.g., C:\jakarta-tomcat-5.0.28\bpr (Note: if you don't see this directory, check the instructions for installing the ActiveBPEL engine into a Tomcat environment).

If all has gone well and there are no typos in any of the files, when the ActiveBPEL engine is running your newly deployed BPEL process should be available as a Web Service at the following URL:

    http://localhost:8080/active-bpel/services/echoService

and you can use the following URL to verify that the process was successfully deployed:

    http://localhost:8080/active-bpel/services/echoService?wsdl

which returns the ActiveBPEL engine's rendering of the echoDefs.wsdl WSDL Reference (note: it will be different from our version, above).

Note: if you've installed or configured your Tomcat server at a different location or on a different port, then you will need to modify this URL accordingly.

Remember going forward that a BPR may contain multiple BPEL process files, and should have one PDD file per deployed process.

Well, that's it. Your new BPEL process is deployed and ready to be invoked.

Copyright © 2004–2007 Active Endpoints, Inc.