WASKB-022 INVOKING A WEB SERVICE FROM A BUSINESS PROCESS TUTORIAL

INVOKING A WEB SERVICE FROM A BUSINESS PROCESS TUTORIAL

INTRODUCTION

A business process executes a series of activities in a sequence. This simple concept is the foundation of application integration. For example, after an order is placed in the web site, the order information needs to be sent to the accounting system for credit checking. The order also needs to be sent to the back end order processing system for fulfillment. The order processing system needs to send the order information to the warehouse where the items will be picked and packaged. After the order is shipped, a notification needs to be sent to the accounting system for invoicing. A notification also needs to be sent to the web site so that purchaser can view the waybill number of the shipped package.

According to the Service Oriented Architecture, each such system (accounting, order processing and warehouse) is seen as a service. A BPEL business process can be designed that shows the sequence of service invocation. A service is a generic concept and does not have to be a Web Service. A Web Service limits the protocol and data format to SOAP. A Web Service is one of many types of services that a process can invoke.

In this tutorial, we will learn how to invoke a Web Service from a process.

THE SERVICE ORIENTED ANALYSIS AND DESIGN (SOAD) METHODOLOGY

You may be already familiar with Object Oriented Analysis and Design (OOAD). OOAD deals with design of objects as building blocks of applications. SOAD can be seen as an extension of OOAD. SOAD deals with design of services as building blocks of applications. In our example above, each system can be seen as a service provider. For example, the accounting system is a service provider that provides the following operations.

  1. Check credit
  2. Prepare invoice

In SOAD the starting point of the design process is the business use case. A business use case documents the interaction between various systems or service providers much like the way we have described the example in the previous section. From the business use case comes the BPEL process diagram. In the BPEL process diagram each interaction with a service is modeled using the Invoke activity. The invoke activity represents invocation of an operation supported by a service. At this point the precise nature of the service, operation names, input and output data format may not be known.

After the BPEL diagram has been designed, services need to be identified. As we have already discussed, each invoke activity represents invocation of an operation of a service. Just go through each invoke activity and list the operation names. Next, group related operations in a single service. For example, the checkCredit and prepareInvoice operations can be grouped in the Accounting service. This completes the service identification process.

Next, we need to refine the service specification. This involves formally documenting the service and operation names and the input and output data format. Web Services Description Language (WSDL) was designed for this purpose (in spite of the unfortunate use of the phrase “Web Services” which as we have already discussed represents one of many types of services). The data format is specified as XML schema. The schema may be built inside the WSDL file. Or the WSDL file may refer to an external XML schema document.

Some of the identified services may already have an implementation. In our example, the accounting system is already in operation. In this case, we will need to configure the existing system as the provider of a service. This is usually done using one of these ways:

  1. The existing system may already have a web service interface. This interface may not be exactly same as the specification you have come up with in the previous step. In that case, develop interface and data map. WebSphere Process Server can apply these maps when an invoke activity is executed.
  2. The existing system provides a Java or EJB API that closely matches the service specification you have come up with. WebSphere Process Server allows you to use a Java class or EJB as a service provider. Optionally, data or interface map can be applied. If there is significant difference in the API and the service specification, it may be easier to develop a wrapper API that follows the service specification rather than design interface and data map.
  3. The existing system has a proprietary API (such as a C++ API). In that case, the following choices exist:
    1. Wrap the system in a new web service. This will require small amounts of programming. You will need to take the service specification developed in a previous step and create a new web service. The web service simply calls the system specific API to get any work done.
    2. The system may provide other ways of accessing the service. For example, the accounting system may monitor a a messaging queue containing shipped order information. WebSphere Process Server allows you to interact with a service using such traditional ways.

If no implementation exists for a service, one needs to be developed following the service specification identified in a previous step.

Development of a new service from a specification is called top down web service development. In this tutorial, we will develop such a service. The following steps will be taken:

  1. Design the process
  2. Identify the service
  3. Develop the service specification
  4. Develop a new web service following that specification

THE BUSINESS LOGIC

In this tutorial, we will build a simplified version of the order processing example. It will have these sequence of activities.

  1. Check for line of credit. This will be later implemented as a web service.
  2. Place the order in the backend order processing system. This will be a simple snippet activity in this tutorial.
  3. The order processing system will notify the warehouse. This will be a simple snippet activity in this tutorial.

PREREQUISITES

This is an advanced tutorial. It does not provide the detail steps to carry out the basic tasks. If you are new to WebSphere Integration Developer, you should complete the previous tutorials first.

CREATE THE MODULE

To avoid running into existing defects in WID, disable automatic publishing. The details can be found in previous tutorials.

Start the process server. Create a new business integration module called OrderProcessing. Deploy the OrderProcessingApp to the server.

CREATE THE BUSINESS OBJECTS

Expand OrderProcessing. Right click on Data Types and select New->Business Object. Enter types in the folder name. Enter LineItem as the name of the business object. Click on Finish. Add various attributes to the LineItem business object as shown below.

Save changes.

Create another business object called Order in the types folder. An order has a list of line items. To model this, drag the LineItem business object and drop it on the editor for the Order business object.

System automatically adds an attribute called LineItem1 of type LineItem. Select the newly added attribute. Activate the Properties view. Change the name of the attribute to Items. Select the Array check box.

Making the attribute an array is important. This allows an Order object to contain unlimited number of LineItem objects.

Add a few other attributes to the Order business object as shown below.

Save changes. Close the editors.

CREATE THE INTERFACE FOR THE BUSINESS PROCESS

Create a new interface in the interfaces folder called IAcceptOrder. This interface will have a single operation called start. This operation will take an Order business object as input. The operation will have no output making it an one way operation.

Right click anywhere on the interface editor and select Add One Way Operation. Change the name of the operation to start.

Right click on the operation name and select Add Input. Change the name of the input to order and data type to Order.

Save changes.

CREATE THE BUSINESS PROCESS

Create a new business process in the procs folder called AcceptOrder. Make the process implement the IAcceptOrder interface created in the previous step.

After the process is created, system will automatically add a variable called Order of type Order. To avoid confusion, change the name of the variable to newOrder. This variable is also set up with the Receive activity so that the input data to the process is saved in the variable. After you change the name of the variable, system automatically reconfigures the receive activity to use the newOrder variable.

In the business process editor, expand the activities drawer. Click on the Invoke button. Then click below the Receivenode. Change the name of the invoke activity to Check Credit.

We should accept the order, only if sufficient credit is available.

Expand the flow control drawer. Select the Choice button. Then click below the Check Credit activity. Change the name of the choice activity to “Credit Available?”. A choice activity is essentially an “if-then-else” decision node. System adds a Case node to the choice by default. A case node is a condition. If the condition evaluates to true, the sequence of activities in that case is executed. Select the case. From the Properties view, change the name to Yes.

Select the “Credit Available?” activity and click on the Add Otherwise button.

Now, we will add the remaining activities. For this tutorial, we know that they will be snippet activities. In real life, they will be all invoke activities.

From the activity drawer, select Snippet. Click below the Yes case. Change the name of the snippet to “Send Order to Backend”. Create another snippet below it and change the name to “Notify Warehouse”.

Expand the third drawer on the left hand side of the process diagram. Select the Terminate activity and add it below the Otherwise choice.

The process should look like above at this point. Save changes. There will be a few compilation problems. Ignore them for now.

SERVICE IDENTIFICATION

In this step, we will identify the services. In this tutorial, the identification process is rather simple. We have only one invoke activity. Each invoke activity corresponds to a service operation. We list all the operations identified:

  1. checkCredit

We group related operations and define services. The following services are identified:

  1. AccountingService. Supported operations:
    • checkCredit

SERVICE SPECIFICATION

Now, we will specify the service accurately and exactly using a WSDL file. In WID, a service specification is called an interface. This terminology is appropriate given that a service specification is an abstract document and does not describe a specific implementation.

Create a new interface called AccountingService in the interfaces folder. System will open the new interface in the editor. Right click anywhere on the editor and choose Add Request Response Operation. Change the name of the operation to checkCredit. Add three inputs to the operation as shown below.

  1. BusinessID – string
  2. Amount – double
  3. Currency – string

Add an output field called creditOK of type boolean. The interface should look as follows.

This completes the interface (service) specification. In real life, there may be several more operations to define.

Save changes and close all open editors.

COMPLETE THE BUSINESS PROCESS

Now that the service specifications are available, we can complete the business process by supplying necessary information for the invoke activities.

First, create a few process variables as follows.

  1. orderTotal – double
  2. currency – string
  3. businessID – string
  4. creditOK – boolean

Next, we will add a new reference partner. A partner essentially represents a service provider. The wonderful thing about a partner reference is that we do not directly specify how the service is implemented (Web Services, EJB, Java class etc.) or where the service is available (host name, port number etc.). Everything remains at an abstract level. Think of a partner as a hook where implementation level details are plugged in at deployment time. This opens up many possibilities. For example, if you have a reference partner for a “Technical Support System”, WebSphere Process Server can route operation invocations made using the partner to different systems at different times of day.

Open the AcceptOrder business process in the editor. On the right hand side palette, click on the + icon below the Reference Partner section. Change the name of the partner to AccountingSystem. While the newly added partner is selected, activate the Properties view. Click on the Details tab. Click on the Browse button and select the AccountingService interface created in the previous step. Save changes.

Now, select the “Check Credit” invoke activity. In the Properties view select the Details tab. Next to the Partner field, click on the Browse button and select the AccountingSystem partner created above. System automatically selects the checkCredit operations since there is only one operation in the interface.

Next, associate various process variables as the input and output data for the operation as shown below.

Now, we will provide the condition for the case node. Select the Yes case below the “Credit Available?” choice activity. In the details tab of the properties page, select Same as Process (Java) as the Expression language. In the left hand node enter

creditOK == true

Save changes. Check the Problems view for any compilation problem. There should be none.

One last thing needs to be done to complete the process. We had used various process variables such as businessID and orderTotal as input data to the checkCredit operation invocation. These variables had never been initialized. Add a snippet activity above the “Check Credit” invoke activity. Set the following Java code.

businessID = newOrder.getString("BusinessID"); 
currency = newOrder.getString("Currency"); 
orderTotal = new Double(newOrder.getDouble("GrandTotal"));

Select the “Send Order to Backend” snippet. Set the Java code to:

System.out.println("Sending order to backend");

Select the “Notify the Warehouse” snippet. Set the Java code to:

System.out.println("Notify the warehouse");

Save changes. Close the process editor.

UNIT TEST THE PROCESS

A powerful feature of WID is the capability to test a BPEL process without completing all the invoked services. This allows separate teams of developers to work on the process and the services.

Double click on OrderProcessing->OrderProcessing to open the assembly editor. Drag and drop the AcceptOrder process on the editor. Save changes.

You will notice a warning icon (yellow triangle) in the AcceptOrder process. This is because we have not wired the AccountingSystem reference partner to any specific service implementation. This indicates that the service implementation is not complete. We can still test the process. System will let us manually emulate the missing services.

Right click on the server in the Servers view and select Publish. This is needed since we have disable automatic publishing. Wait for publishing to be over.

Right click anywhere in the assembly editor and choose Test Module.

In the test client, right click on Items and select Add Element. Set these values.

  • ProductSKU – 1234
  • Quantity – 2
  • BusinessID – WEB AGE
  • GrandTotal – 100.00

Other values are optional for now. Click on Continue. System will ask you choose the server to which the test request will be sent. Choose the process server instance and enable the Use this as the default and do not ask again check box. Click on Finish.

System will start the process. Eventually, when the Check Credit invoke activity is reached, the test client will halt at an emulation point. Here you can look at the request that the invoke activity would send to the web service and manually enter reply data. Change the creditOK output parameter to true as shown above. Click on Continue. You should see the following messages in the Console view.

[12/13/05 15:51:40:030 EST] 0000009e System Out     O Sending order to backend 
[12/13/05 15:51:40:040 EST] 0000009e SystemOut     O Notify the warehouse

Re-run the test by right clicking on the Invoke node in the test client and selecting Rerun. This time set the value of the creditOK parameter to false. The process will end but you will not see the two messages shown above.

Save the test client settings in the root of the OrderProcessing project. Close the test client.

UNDERSTANDING INTERFACE EXPORTS AND IMPORTS

Not all services invoked by a process will be implemented within the same BI module. In real life, chances are high, the services are already offered by existing applications or will be developed by a different team. In many cases, a service will be offered by a different organization than where the process executes. In this case, the team developing the service will belong to a different organization. You will have little control over their technology of choice in developing the service. Thankfully, we can assume that many services will be implemented as Web Services. Web Service has a good track record for vendor and programming language neutrality.

Once a service interface definition has been created in a BI module, it can be exported as a WSDL file. The interface WSDL file contains the abstract specification or the <portType> element only. The exported WSDL file will have SOAP protocol specific binding and the endpoint (URL) information. This information goes inside the <binding> and <service> elements. The exported WSDL file needs to be sent to the team that will develop an implementation. Most modern development IDE provides a way to generate a skeletal Web Service implementation from this WSDL file. The developers will need to simply enter the business logic in the generated Java, VB or C# class.

Until a service implementation is complete, the process developers can simulate it when unit testing the process. We will shortly see how that can be done.

Finally, when the service implementation is complete, it needs to be plugged into the process. Remember, an invoke activity simply refers to a reference partner variable that conforms to a certain interface. The reference partner does not contain any protocol or endpoint specific details. Eventually, such information must be specified, if the process is to actually invoke the service implementation. A service implementation is described in a WSDL file. This file contains the abstract definition of the service (<portType>) as well as protocol details (<binding>) and endpoint (<service>) information. The service implementor will send you this WSDL file. The file needs to be imported in the BI module. This creates an interface import component. Finally, a reference partner of process needs to be wired (connected) to this import. When the process invokes and operation using the reference partner, system uses the wired import to find out what protocol and endpoint needs to be used to invoke the operation.

EXPORT WEB SERVICE SPECIFICATION

At this point, our service specification is in an abstract form in the AccountingService.wsdl file. Before we can generate a new web service based on that, we must add SOAP over HTTP protocol specific details. These details are provided in a WSDL file using the <service> and <port> elements.

Open the assembly editor for the business module. Drag and drop the AccountingService interface on the editor. Choose Export With Web Service Binding. System asks you to confirm the export process. Click on OK. Then as the transport type, select soap/http. This will produce a WSDL file called Export1_AccountingServiceHttp_Service.wsdl in the root folder of OrderProcessing project. You can also see it in the Web Service Ports node in the Business Integration view.

After the WSDL file has been generated, we don’t really need to keep the export component in the assembly editor. Delete Export1. Save the assembly editor.

DEVELOP THE WEB SERVICE

We will develop the web service in a separate web application. Switch to the J2EE perspective. Right click on Dynamic Web Projects and select New->Dynamic Web Project. Set the name of the web module to AccountingWeb. Click on the Show Advanced button. Change the EAR project name to AccountingApp. Click on Finish. System will offer to switch the perspective to Web. Decline it.

Right click on the AccountingWeb project and select New->Other. Select the Enable all Wizards check box.

Expand Web Services and select Web Service. Click on Next.

Choose Skeleton Java bean Web Service as the Web service type. Uncheck the Start Web service in Web project. Click on Next.

In this page, we need to enter the location of the WSDL file that contains the specification of the service. Click on the Browse button. Choose the exported WSDL file from the root of the OrderProcessing project. Click on OK. Click on Next. This page allows us to configure a service project. Click on the Edit button. Expand Existing Servers and select WebSphere Process Server v6.0. As Web service runtime select IBM WebSphere. Click on OK. As Service project select AccountingWeb. As the EAR project select AccountingApp. Click on Next.

Click on Finish. System will generate the web service and open the implementation Java class Export1_AccountingServiceHttpBindingImpl. Fill in the implementation of the checkCredit method as follows.

public java.lang.Boolean checkCredit(java.lang.String businessID, 
    java.lang.Double amount, 
    java.lang.String currency) throws java.rmi.RemoteException { 	

    System.out.println("Checking credit limit for business: " +			
        businessID +
        " for amount: " + 			
        amount + currency);
    if (amount.doubleValue() > 1000.00) {
        System.out.println("Amounts over 1000.00 are automatically rejected");
        return new Boolean(false); 	
    }
    return new Boolean(true);
}

Save changes.

Add the AccountingApp application to the server.

WIRE THE REFERENCE PARTNER

Currently, the business process has a reference partner called AccountingSystem. This has not been mapped to a specific service implementation. Wiring is the act of specifying an actual service endpoint for a reference partner. This is done in the assembly editor.

An actual web service implementation is represented by a WSDL file that contains the <service> and <port> elements. Together they specify the communication protocol (SOAP over HTTP for example) and the end point (URL).

The WSDL file exported in a previous step can act as the WSDL file that we need. Except, the endpoint URL in that file is fictitious. Right click on Web Service ports->Export1_AccountingServiceHttp_Service and select Open With->Text Editor. Set the endpoint URL as shown in bold face below.

<wsdl:port name="Export1_AccountingServiceHttpPort" 
    binding="this:Export1_AccountingServiceHttpBinding">
    <soap:address 
location="http://localhost:9080/AccountingWeb/services/Export1_AccountingServiceHttpPort"/>
</wsdl:port>

Save changes and close the editor. Where did the URL come from? When the Web Service was generated in the AccountingWeb project, a WSDL file was also generated in the WebContent/wsdl/OrderProcessing folder. This WSDL file has the correct URL endpoint.

Open the assembly editor. Drag Export1_AccountingServiceHttp_Service on the assembly editor. Select Import With Web Service Binding.

Every reference partner in a process is rep[resented by a small rectangle as shown within the red circle above. You can select the small rectangle and use the Properties view to tell which reference partner it represents.

Click on the Wire tool in the left hand side tool bar. Click on the small rectangle for the reference partner and then click on the imported WSDL file Import1. This will “wire” the abstract reference partner variable to a specific implementation and endpoint of a Web Service.

Delete the Export1 exported reference to the WSDL file from the assembly if it is still there. Important: You must remove this exported reference. Otherwise there will be many build errors.

Save changes. Wait for the workspace to be rebuilt. Make sure that there are no warnings or errors shown in the Problems view.

TEST THE PROCESS

Right click on the server and select Restart Project->OrderProcessingApp. This will publish the module and restart the application. In the assembly editor, right click and select Test Module. Enter sample input values as shown in the previous testing step. Click on Continue. Make sure that the Console shows the output from the Web Service implementation. For example:

SystemOut     O Checking credit limit for business: WEB AGE for amount: 100.12

SUMMARY

We learned several new concepts in this advanced lab. In summary, we learned how to:

  1. Define a complex data type that contains a list of another complex data type.
  2. Create a business process that invokes external services.
  3. Identify services.
  4. Specify the service as an abstract interface in a WSDL file.
  5. Unit test a business process without actually implementing the invoked services.
  6. Export the service specification in a WSDL file with SOAP binding.
  7. Develop an implementation of the service as a Web Service.
  8. Import protocol binding and endpoint information about the service implementation.
  9. Wire the reference partner used by the process to invoke a service operation to the imported service information.