As Published In September/October 2004

Your First BPEL Project
By Mike Lehmann

Learn how to wire a Web service to BPEL.

In my previous column, I provided a quick tour of the Business Process Execution Language (BPEL), using a complex sample business process. Now, let's look under the covers of BPEL and get a sense of what it takes to wire an existing Web service into a BPEL process.

Rather than focusing on the subtleties of the BPEL language itself, let's concentrate on the key language concepts you need to build your first BPEL process. To do this, I start by using the Employee Web service I used a couple of columns ago to illustrate JAX-RPC programming, handlers, and management issues with Web services, in a simple BPEL process.

The goal is to show you how to write BPEL processes by using your own Web services while gaining an understanding of why BPEL has certain constructs. This article is complemented by an online tutorial on using Oracle BPEL Designer, at oracle.com/technology/products/ias/bpel/htdocs/dev_support.html#tutorials.

Setting Up the PartnerLink for a Web Service

The first issue BPEL authors encounter is how to logically tie a BPEL process to an existing Web service. The construct in BPEL used to create this link is called a <partnerLink>. Every Web service used in a BPEL process requires a <partnerLink> describing which set of Web service operations—defined by the WSDL <portType> construct—is used in the BPEL process.

To enable a BPEL process to bind to a specific <portType> via a <partnerLink>, you build a <partnerLinkType> construct into the originating Web service WSDL or generate a new WSDL containing an import of the Web service WSDL and the additional <partnerLinkType> reference.

You need two things when adding a <partnerLinkType> to an existing WSDL. First, in the definitions section of the Employee Web service WSDL, a partner link namespace should be defined. Second, in the <portType> subelement of the <partnerLinkType>, a link to the Employee Web service <portType>, EmpInterface, needs to be defined. Listing 1 shows the key sections of the updated Employee Web service WSDL.

Because the Employee Web service is local, I added the <partnerLinkType> information manually. These steps are automated in a BPEL authoring tool.

Creating the Empty BPEL Process

Now we are ready to build a shell of a BPEL process. We will call our process the HRProcess. Listing 2 provides a basic BPEL shell that can be used to jump-start the process—such a shell is generated by default by Oracle BPEL Designer when you are building a new BPEL process.

The shell consists of a <process> element, the list of <partnerLink>s (Web services) used by the BPEL process, and <variable>s used in the business process. To this shell, a BPEL author typically adds a list of steps to be executed by the business process and the <partnerLink> referring to the Employee Web service. You may have noticed that the shell has a <partnerLink> called client, there by default, because the BPEL process is a Web service and has a <partnerLinkType> called HRProcess in its WSDL.

Following that pattern, Listing 2 also shows the EmpService <partnerLink>. Oracle BPEL Designer makes adding the EmpService <partnerLink> a simple operation, once you've pointed the <partnerLink> at the WSDL of the Employee Web service containing the <partnerLinkType> definition.

Setting Variables to Call the Service

BPEL authors often want to design the input and output message of their processes to correspond to a well-defined business document. Because a BPEL process itself is a Web service, this typically involves editing the BPEL WSDL or using a WSDL editor, depending on which tools your BPEL editing environment provides.

In this example, the target Employee Web service is simple, with a string input and a string output, so the default types used by HRProcess BPEL process WSDL generated by the Oracle BPEL Designer, shown in Listing 3, are usable as is.

To make this example clear, I've edited the default element name for the HRProcessRequest inbound data, input, to be inputEmpNumber and I've edited the default element name for the HRProcessResponse outbound data, result, to be resultEmpSalary.

To call the Employee Web service, a BPEL author has to take the input variable, inputEmpNumber, and transform it into a variable type the Employee Web service can understand. Correspondingly, the output of the Web service, employee salary, has to be transformed back into the variable type the BPEL service will return, resultEmpSalary.

To accomplish this, variables of the type the Employee Web service is expecting as input and as output must first be created in the BPEL process. Looking back at Listing 1 at the <portType> for the Employee Web service, you can see that the types the getEmpSalary operation uses are EmpInterface_getEmpSalary and EmpInterface_getEmpSalaryResponse. Listing 4, provides a sample BPEL declaration of the variables of these types—employeeNumber and employeeSalary.

Next Steps DOWNLOAD the Oracle BPEL Process Manager TRY the online tutorial of this article

With the variables created, the next step is to use the BPEL <assign> construct to transform the input variable inputEmpSalary into the employeeNumber variable. Listing 5, in the online version of this article, shows why this is important: Using an XPath statement inside the <assign> statement, you can see that the message structure the Employee Web service requires (/getEmpSalaryelement/String_1) is quite different from that provided from the invocation of the BPEL service itself (/HRProcessRequest/empNumber).

Invoking the Service

The last step to bring this BPEL wiring project to a close is to invoke the Web service itself. All the hard work has already been done by now with the <partnerLink> and <variable> declarations—the <invoke> is a simple step:

<invoke name="InvokeEmpService" 
       partnerLink="EmpService" 
       portType="ns0:EmpInterface" 
       operation="getEmpSalary" 
       inputVariable="employeeNumber" 
       outputVariable="employeeSalary"/>

First the <invoke> itself gets a logical name. Then it is connected to the partnerLink declared earlier in the BPEL process, EmpService. Next, within the <partnerLink>, a specific Employee Web service WSDL <portType>, EmpInterface, is called out, along with the actual operation that will be invoked, getEmpSalary. Last, the two variables—employeeNumber and employeeSalary—created to handle the Employee Web service input and output are passed to the <invoke> statement.

Can You Write This Yourself?

With these steps, you have done all the necessary work to connect an existing Web service into a fully functional BPEL process. Despite all the XML listed in this column, the average BPEL author seldom writes raw BPEL. Rather, highly graphical tools such as Oracle BPEL Designer automate the major tasks discussed here and generate much of the code.

However, as with any new language, it is worthwhile to have a basic understanding of how the pieces are wired together, especially if you are just starting out.