> Tutorial: Building Your First Business Process > Step 4: Invoke a Web Service

Tutorial: Building Your First Business Process

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Step 4: Invoke a Web Service

By default, a Decision node consists of one condition; a path below the condition node, which represents the path of execution followed when the condition, or set of conditions that evaluate to true; and a path to the right of the condition, which represents the path of execution followed when the condition evaluates to false (the default path).

Note: You can add additional condition nodes and paths to a Decision node, but in this scenario, we need only one set of conditions, and two paths.

In this step, you learn how to add logic to one path of execution for your Decision node (Sales Tax Calculation Needed?). Specifically, you learn how to design your business process to interact with resources via controls. Your business process invokes a Web service and handles the data returned from the Web service. This step describes the following topics:

 

What is the Tax Calculation Control?

Java Controls are server-side components managed by the Workshop framework. They encapsulate external resources and business logic for use in Workshop applications. In other words, controls represent the interfaces between your business process and other resources. The underlying control implementation takes care of most of the details of the interaction for you. Controls expose Java interfaces that may be invoked directly from your business process. You add an instance of a control to your project and then invoke its methods.

In this scenario, the business process calls a Web service, which calculates and returns a sales tax rate. Business Processes invoke Web services via Web Service controls. The Web service control (TaxCalcControl.java) is created for you and included in your application's project (specifically in the Tutorial_Process_Application_WEB\requestquote\services folder, where myapplications represents the location in which you created your tutorial application).

A complete description of how to create the TaxCalc.java Web service and its associated control (TaxCalcControl.java) is beyond the scope of this tutorial. The goal of Step 4 in this tutorial is to describe how to create the appropriate nodes in your business process, and design their communication with this Web Service control.

To learn about creating Web services, and creating a control from your Web service, see Tutorial: Web Services and Controls and Transactions.

Related Topics

Tutorial: Web Services

Transaction Boundaries

Design the Interaction Between Your Business Process and a Web Service

This section describes how to create the activities that are performed when the condition defined in your Decision node evaluates to true. The condition evaluates to true if the value of shipAddress/state in the XML document received from a client, equals any one of the following: CA, California, NJ, or New Jersey.

In this section, you learn how to invoke a Web service from your business process, and create a callback handler to receive the data returned by the Web service. It includes the following tasks:

To Create an Instance of the Web Service Control in Your Project
  1. If Design view is not visible, click the Design tab.
  2. From the BEA Workshop menu choose WindowArrow symbolShow ViewArrow symbolData Palette.
  3. Click on the Data Palette tab. A drop-down list of controls that represent the resources with which your business process can interact is displayed.
  4. Select Local control, select TaxCalcControl - requestQuote.services.
  5. Accept the default Field Name in the Insert Control:TaxCalcControl - requestQuote.services dialog box.
    6. Note: You can also drag and drop the TaxCalcControl.java from the Package Explorer pane to the Data Palette. The file is available at Tutorial_Process_application_WEB/src/requestquote.services/TaxCalcControl.java.
  6. Click Finish.
To Call the Tax Calculation Web Service From Your Business Process

In this step, you create the logic to call the tax calculation control from your business process.

  1. In the Data Palette, click the + beside the taxCalcControl. The list of methods available on the taxCalcControl is displayed.
  2. From the list of taxCalcControl methods, click the following method:
    3. void requestTaxRate(String stateID_arg)
  3. Drag and drop the method onto the business process, placing it on the Sales Tax Calculation Needed? node immediately below the condition (Yes) node



    4. A Control Send node is created representing the asynchronous call to your taxCalculation Web Service control. The node is named according to the name of the method you dragged onto the business process—in this case: requestTaxRate.

    Note: This interaction is designed to be asynchronous, meaning that the business process can send a request to the taxCalcControl from this node, and does not block waiting for a response from the control. In other words, the business process can continue processing and receive a response from the taxCalcControl service when that service completes the request.
  4. Double-click the requestTaxRate node. The node builder opens on the General Settings tab. The Control instance and target methods are already selected: taxCalcControl and void request TaxRate(String stateID_arg), respectively.
  5. Click the Send Data.

    6. By default, the Send Data opens on the Variable Assignment pane. The Control Expects field is populated with the data type expected by the requestTaxRate() method exposed by the taxCalcControl Web services: String stateID_arg.

    Note: As you learned in a previous step, Send Data tabs have two modes:
    • Variable Assignment—Use this mode when you want to assign the data received from the client to a variable of the same data type.
    • Transformation—Use this mode when you want to create a transformation between the data assigned to a variable and that expected by the method parameter.

      • In this case, you must switch to the Transformation mode because the data type required as input to the taxCalcControl control is a Java String type, and the variable in which the Request for Quote message (which includes the value of shipAddress/state) is stored, is of type XML (that is, QuoteRequestDocument, which is valid against an XML Schema).

      BEA Products provides a data mapping tool to map between heterogeneous data types. The data transformations you create using the tool are stored in Data Transformation files. You can think of transformation files as another resource with which your business process interacts via controls. That is, when transformation files containing your data transformations are built, they are built as controls. The controls expose transformation methods, which business processes invoke to map disparate data types.

  6. Click Transformation. A pane that allows you to define a transformation between your variable and the expected data type of the parameter on the control method.
  7. Click Select Variable to display the variables in your project, then choose requestXML (QuoteRequestDocument)—that is, the variable you created for the Client Request node at the start of your business process.

  8. In the next dialog box, click Create Transformation. The Transformation tool opens, which displays a representation of the QuoteRequest XML document in the Source pane, and a String in the Target pane.
  9. Click state in the Source pane and drag your mouse pointer over to String in the Target pane. A line is drawn between the state and String elements in the XML Map pane. It represents the transformation between the two data types.



  10. Save the .xq file before switching to the process, and click the RequestQuote.java tab.
    11. Note: Creating the transformation in the preceding steps creates a Transformation control in your project: A Java file, named RequestQuoteTransformation.java is created. An XQ file, which contains the query (written in the XQuery language) for the transformation method is also created. Both the Java and XQ files are displayed in the Package Explorer tab. Also, an instance of the Transformation control was created and is represented as transformations in the Data Palette (Controls folder).
  11. Click Close to close the Request Tax Rate node builder.

    12. This step completes the design of the Request Tax Rate node.

To Receive the Tax Rate Calculation From the Web Service

The interaction between the business process and the tax calculation control is asynchronous, which means that the business process can continue performing other work while the tax calculation service prepares its response. The tax calculation service notifies the business process when the response is ready.

In the preceding section you designed a call to the tax calculation Web service (via a control). To add the logic in your business process that receives the tax rate returned by the tax calculation control, complete the following steps:

  1. In the Data Palette, click the + beside the taxCalcControl to expand the list of methods available on the taxCalcControl.
  2. From the list of taxCalcControl methods, click the following method:
    3. void returnTaxRate(float taxRate_arg)
  3. Drag and drop the method onto the business process placing it on the Sales Tax Calculation Needed? node immediately below the requestTaxRate node:

    4. A Control Receive node is created representing the asynchronous response from your Web Service control.



    The node is named according to the name of the method you dragged onto the business process—in this case: returnTaxRate.

  4. Double-click the returnTaxRate node. The node builder opens on the General Settings tab. The Control instance and target methods are already selected: taxCalculation and returnTaxRate(float taxRate-arg), respectively.
  5. Click the Receive Data tab. The tab opens with the Variable Assignment pane selected.

    6. The Control Expects field is populated with the data type and name of the parameter returned by the returnTaxRate() method on the taxCalculation control: float taxRate.

  6. In the Variable Assignment pane, click the arrow in the field under Select variables to assign, then select Create new variable.... The Create Variable dialog box is displayed.
  7. In the Variable Name field, enter taxRate.
  8. From the Simple tab, expand Primitive, and then select float.
  9. In the Default value field, enter 0. This initializes the value of taxRate to zero.



  10. Click OK. Your new variable, to which the sales tax rate is assigned at run time, is created and is listed as a Java variable in the Variables tab.
  11. Click Close in the node builder. The Control Receive node builder closes.

    12. This step completes the design of your returnTaxRate node and the design of the activities performed by your business process when the condition on the Decision node evaluates to true. In the Design view, your business process resembles that shown in the following figure:



    Note that the Start node icon changed from to after you added the asynchronous call to the Web Service control. The former icon indicates that your business process is stateless, and the latter indicates that it is under state.

    The icons reflect the specification for the stateless property for your business process. To see whether the stateless property is defined as true or false, click the Start node icon and view the Property Editor. To learn about stateful and stateless business processes, see Building Stateless and Stateful Business Processes. To understand why the property changed from stateless to stateful, see Transaction Boundaries.

    Note: If the Properties pane is not displayed in BEA Workshop, choose WindowArrow symbolShowViewArrow symbolProperty Editor from menu bar.
  12. From the Workshop menu, select FileArrow symbolSave All.
    13. Note: No further design is required for this Decision node. If the condition evaluates to true, the path of execution proceeds via the Yes path and the tax rate for the order is calculated. If the condition evaluates to false—no sales tax is required—the path of execution proceeds via the No path and a value of zero is assigned to the variable taxRate. Remember, you specified that taxRate is initialized to zero when you designed the taxRate variable in the preceding section.

Related Topics

Interacting With Resources Using Controls

Guide to Data Transformation

Building Stateless and Stateful Business Processes


  Back to Top       Previous  Next