2 Invoking a Synchronous Service

This chapter of the tutorial describes how to invoke a synchronous service.

This chapter contains the following topics:

• Introduction

• Invoking a Synchronous Service to Receive an Order and Obtain a Credit Rating

• Summary

2.1 Introduction

In the first phase of this tutorial, you learn how to build a simple asynchronous BPEL process for receiving an order from a client and obtaining a credit rating. You perform the following key tasks:

• Deploy (start) a synchronous Credit Rating service.

• Create a new BPEL process named OrderBooking.

• Create a partner link to interact with the Credit Rating service.

• Design the BPEL process to invoke the Credit Rating service.

• Deploy the BPEL process.

• Run the deployed BPEL process from Oracle BPEL Console and submit a social security card number to the Credit Rating service to check the client's credit history.

• Review the credit rating results returned from the Credit Rating service to the client.

2.2 Invoking a Synchronous Service to Receive an Order and Obtain a Credit Rating

This section contains the following topics:

• Starting Oracle BPEL Server and JDeveloper BPEL Designer

• Starting and Testing Your Services

• Creating a New Workspace and an Order Booking Project

• Importing the Order Booking Schema

• Creating a Credit Rating Service Partner Link

• Creating Scope and Invoke Activities

• Creating an Initial Assign Activity to Send Request Data to the Credit Rating Service

• Creating a Second Assign Activity to Receive Response Data from the Credit Rating Service

• Creating a Third Assign Activity

• Validating, Compiling, and Deploying the Order Booking Process

• Running the Order Booking Process

2.2.1 Starting Oracle BPEL Server and JDeveloper BPEL Designer

Ensure that Oracle BPEL Server and JDeveloper BPEL Designer are started. See "Starting Oracle BPEL Process Manager Components" for instructions.

2.2.2 Starting and Testing Your Services

During this tutorial, the BPEL process that you design communicates with the Credit Rating service. You must first deploy this service and test that it is running.

1. Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager 10.1.2 > Developer Prompt to open up an operating system command prompt at the Oracle_Home\integration\orabpel\samples directory.

   
   

   Note: Always use the Developer Prompt to open an operating system command prompt in all phases of the Order Booking tutorial. Opening an operating system command prompt in any other way to run tutorial commands is not supported.

   
   

2. Change directories to the utils\CreditRatingService subdirectory:

   cd utils\CreditRatingService
   
   

3. Enter the following command:

   obant
   
   

   This deploys and starts the required services for using this tutorial. If successful, a message similar to the following appears at the end:

   BUILD SUCCESSFULTotal time: 3 secondsoraBPELPM\integration\orabpel\samples\utils\CreditRatingService>ENDLOCAL
   
   

   If you receive an error saying the path was not found, ensure that your environment path is set to the Oracle_Home\integration\orabpel\bin directory.

4. Access Oracle BPEL Console using Internet Explorer to see if all required services are running. Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager 10.1.2 > BPEL Console.

5. Click Login with default selected from the Domain list. The password is bpel.

   The services for this tutorial are running if CreditRatingService, TaskActionHandler, and TaskManager display in the Dashboard tab.

   
   

   See Also: "Connecting to Oracle BPEL Server" for instructions on creating a connection to Oracle BPEL Console

   
   

2.2.3 Creating a New Workspace and an Order Booking Project

Follow these instructions to create a new workspace and Order Booking project.

Caution: Do not include any special characters in the project name (such as periods) or in any activity or element names. If you do include special characters, errors appear when you attempt to compile your project.

1. Return to JDeveloper BPEL Designer.

2. Select File > New from the main menu.

3. Double-click Workspace in the Items window to display the Create Workspace window.

4. Enter OrderBookworkspace in the Workspace Name field and accept the default path in the Directory Name field.

5. Deselect the Add a New Empty Project check box.

6. Click OK.

7. Right-click OrderBookworkspace in the Applications Navigator section of the designer window. If the Applications Navigator section does not currently appear, select Application Navigator from the View main menu.

8. Select New Project.

9. Double-click BPEL Process Project in the Items window to display the BPEL Process Project window.

10. Enter OrderBooking in the BPEL Process Name field. All other fields default to the correct values for creating an asynchronous BPEL process.

11. Click OK.

    The bpel.xml, OrderBooking.bpel, and OrderBooking.wsdl files are created.

2.2.4 Importing the Order Booking Schema

Summary: You now import the GlobalCompany schema into your project. This schema defines the structure of the purchase order to submit.

1. Copy OrderBookingPO.xsd and OrderBookingPO_1.xml from the Oracle_Home\integration\orabpel\samples\tutorials\127.OrderBookingTutorial\PracticeFiles directory to the Oracle_Home\integration\jdev\jdev\mywork\OrderBookworkspace\OrderBooking directory.

2. Double-click OrderBooking.bpel in the Applications Navigator section of the designer window to display the Structure section in the lower left of the window.

   
   

   Note: The Diagram View tab must be enabled to see the Structure section.

   
   
   
   Description of the illustration obph1str.gif
   
   

3. Select and right-click Project Schemas in the Structure section.

4. Select Import Schema.

   The Import Schema window appears.

5. Click the flashlight icon to access the Open window.

6. Select OrderBookingPO.xsd from the OrderBooking directory in which you placed it in Step 1 and click Open.

   The file is added to the URL field of the Import Schema window.

7. Click OK.

8. Verify that OrderBookingPO.xsd appears under OrderBooking > Web Content > Miscellaneous Files in the Applications Navigator section of the designer window. OrderBookingPO.xsd also appears under Project Schemas in the Structure section. If you want, you can double-click OrderBookingPO.xsd under Miscellaneous Files to view the design and source modes of this file.

9. If you view OrderBookingPO.xsd, close the window when done by clicking the x button on the Title tab.

   
   Description of the illustration obph1xsd.gif
   
   

10. Double-click OrderBooking.bpel in the Applications Navigator section of the designer window to display the Structure section in the lower left section of the designer window.

11. Expand Message Types > Process WSDL - OrderBooking.wsdl > OrderBookingRequestMessage > payload in the Structure section.

12. Right-click payload and select Edit Message Part to display the Edit Message Part window.

13. Select Element and click the flashlight icon to the right of the Element field.

14. Expand Project Schema Files > OrderBookingPO.xsd.

15. Select PurchaseOrder.

16. Click OK to close the Type Chooser window and the Edit Message Part window.

    This defines the input parameter (payload) of the PurchaseOrder type.

17. Expand Message Types > Process WSDL - OrderBooking.wsdl > OrderBookingResponseMessage > payload in the Structure section.

18. Right-click payload and select Edit Message Part to display the Edit Message Part window.

19. Select Element and click the flashlight icon to the right of the Element field.

20. Expand Project Schema Files > OrderBookingPO.xsd.

21. Select PurchaseOrder.

22. Click OK to close the Type Chooser window and the Edit Message Part window.

    This defines the output parameter (payload) of the PurchaseOrder type.

23. Select Save from the File main menu.

2.2.5 Creating a Credit Rating Service Partner Link

Summary: You now create a partner link for the Credit Rating service. This is the service you started when you ran obant in "Starting and Testing Your Services". A partner link enables you to define the external services with which the OrderBooking BPEL process is to interact. A partner link type characterizes the conversational relationship between two services by defining the roles played by each service in the conversation and specifying the port type provided by each service to receive messages within the context of the conversation.

1. Ensure that Process Activities is selected in the drop-down list of the Component Palette section in the upper right section of JDeveloper BPEL Designer.

2. Drag and drop a PartnerLink activity onto the right side of the designer window anywhere beneath the header Partner Links. Note that both sides of the designer window have sections in which partner links can be placed.

   
   Description of the illustration obph1pl.gif
   
   

3. Enter the following values to create a partner link for the Credit Rating service. For the WSDL File field below, click the flashlight (the second icon from the left named WSIL Browser) to access the WSDL Chooser window for automatically selecting the Credit Rating service deployed in "Starting and Testing Your Services":

   
   Description of the illustration wsdlfile.gif
   
   
   Description of the illustration obph1wsdl.gif
   
   

   Field	Value
   Name	CreditRatingService
   WSDL File	Access this URL by clicking the WSIL Browser flashlight icon and expanding and selecting LocalBPELServer > processes > default > CreditRatingService. http://localhost:9700/orabpel/default/CreditRatingService/CreditRatingService?wsdl See Also: "Setting the Hostname in Your JDeveloper BPEL Designer Web Browser Preferences" if you receive a parsing error when attempting to add a WSDL file in the WSDL Chooser window.
   Partner Link Type	CreditRatingService
   My Role	Leave unspecified since this is a synchronous service.
   Partner Role	CreditRatingServiceProvider

   
   

4. Click OK.

5. Select Save from the File main menu.

2.2.6 Creating Scope and Invoke Activities

Summary: You now create the Invoke activity that sends request data from the OrderBooking process to the synchronous Credit Rating service and receives a response. The customer custID variable from the Order Booking schema is used to obtain the credit rating. When you run the OrderBooking process, you specify a value for CustID in Step 3 of "Running the Order Booking Process".

Note: As you create and open activities such as Scope, Invoke, and Assign for the first time, the message Invalid Settings can appear at the top. This is because you have not yet entered details. You can ignore this message. After you enter and apply your details, the message disappears.

1. Drag and drop a Scope activity from the Component Palette section to below the receiveInput Receive activity. Always pay careful attention to where you place the Scope activity; throughout all phases of this tutorial, you drag and drop activities many times.

   
   Description of the illustration obph1dnd1.gif
   
   

   Note that the first time your drag and drop an activity, it has a generic name such as Scope_1.

2. Double-click the scope icon to display the Scope window.

3. Enter GetCreditRating in the Name field of the General tab.

4. Click OK.

5. Click the + sign to expand the Scope activity. You now add an Invoke activity and two Assign activities to this Scope activity.

6. Drag and drop an Invoke activity from the Component Palette section to inside the GetCreditRating Scope activity.

   
   Description of the illustration obph1dnd2.gif
   
   

7. Double-click the Invoke icon to display the Invoke window.

8. Enter the following details:

   Field	Value
   Name	invokeCR
   Partner Link	CreditRatingService

   
   

   The Operation (process) field is automatically filled in.

9. Click the first icon to the right of the Input Variable field. This is the automatic variable creation icon.

   
   Description of the illustration autocreate.gif
   
   

10. Click OK on the Create Variable window that appears.

    A variable named invokeCR_process_InputVariable is automatically created in the Input Variable field. This variable is automatically assigned a message type of CreditRatingServiceRequestMessage.

11. Click the first icon to the right of the Output Variable field.

12. Click OK on the Create Variable window that appears.

    A variable named invokeCR_process_OutputVariable is automatically created in the Output Variable field. This variable is automatically assigned a message type of CreditRatingServiceResponseMessage.

13. Click OK.

14. Select Save from the File main menu.

2.2.7 Creating an Initial Assign Activity to Send Request Data to the Credit Rating Service

Summary: You now create the first of two Assign activities in this phase. This Assign activity takes the customer custID element from the Order Booking schema and assigns it to invokeCR_process_InputVariable. This is the variable used for sending a request to the Credit Rating service.

1. Drag and drop an Assign activity from the Component Palette section to above the invokeCR Invoke activity and inside the GetCreditRating Scope activity.

   
   Description of the illustration obph1dnd3.gif
   
   

2. Double-click the assign icon to display the Assign window.

3. Click the General tab.

4. Enter assignCR in the Name field.

5. Click Apply.

6. Click the Copy Rules tab.

7. Click Create to display the Create Copy Rule window.

   
   Description of the illustration obph1create.gif
   
   

8. Enter the following details:

   Field	Value
   From
   Type	Variable
   Variables	Expand and select Variables > inputVariable > payload > ns1:PurchaseOrder > ns1:CustID Note: The namespace number values (for example, ns1, ns2) can vary.
   To
   Type	Variable
   Variables	Expand and select Variables > invokeCR_process_InputVariable > payload > ns2:ssn

   
   

   The Create Copy Rule window appears as follows:

   
   Description of the illustration obph1as.gif
   
   

9. Click OK to close the Create Copy Rule window and the Assign window.

10. Select Save from the File main menu.

2.2.8 Creating a Second Assign Activity to Receive Response Data from the Credit Rating Service

Summary: This Assign activity takes the response received from the Credit Rating service and places it in the comment field.

1. Drag and drop an Assign activity from the Component Palette section to below the invokeCR Invoke activity and inside the GetCreditRating Scope activity.

   
   Description of the illustration obph1dnd4.gif
   
   

2. Double-click the assign icon to display the Assign window.

3. Click the General tab.

4. Enter assignRating in the Name field.

5. Click Apply.

6. Click the Copy Rules tab.

7. Click Create to display the Create Copy Rule window.

8. Enter the following details:

   
   

   Note: Instead of manually entering an expression, you can press Ctrl and then the space bar in the Expression field. Scroll through the list of values that appears and double-click the value you want. Edit the value as necessary. As you enter information, a trailing slash can appear. This means you are being prompted for additional information. Either enter additional information, or press the Esc key and delete the trailing slash to complete the input of information.

   
   

   Field	Value
   From
   Type	Expression
   Expression	concat('Good credit, Rating = ', bpws:getVariableData('invokeCR_process_OutputVariable','payload','/ns2:rating')) Note: Press Ctrl and then the space bar to display a list for selecting (double-clicking) this syntax. The namespace number values (for example, ns1, ns2) can vary. Use the namespace values that automatically appear.
   To
   Type	Variable
   Variables	Expand and select Variables > inputVariable > payload > ns1:PurchaseOrder > ns1:OrderInfo > ns1:OrderComments

   
   

9. Click OK to close the Create Copy Rule window and the Assign window.

10. Click the - sign to close the GetCreditRating Scope activity.

    
    Description of the illustration obph1collscope2.gif
    
    

    When closed, the GetCreditRating Scope activity looks as follows:

    
    Description of the illustration obph1collscope.gif
    
    

11. Select Save from the File main menu.

2.2.9 Creating a Third Assign Activity

1. Drag and drop an Assign activity from the Component Palette section to below the GetCreditRating Scope activity and above the callbackClient activity.

   
   Description of the illustration obph1dnd5.gif
   
   

2. Double-click the assign icon to display the Assign window.

3. Click the General tab.

4. Enter assignOutput in the Name field.

5. Click Apply.

6. Click the Copy Rules tab.

7. Click Create to display the Create Copy Rule window.

8. Enter the following details to create a statement:

   Field	Value
   From
   Type	Variable
   Variables	Expand and select Variables > inputVariable > payload
   To
   Type	Variable
   Variables	Expand and select Variables > outputVariable > payload

   
   

9. Click OK to close the Create Copy Rule window and the Assign window.

10. Select Save from the File main menu.

    When complete, the designer window looks as follows:

    
    Description of the illustration obph1.gif
    
    

2.2.10 Validating, Compiling, and Deploying the Order Booking Process

1. Go to the Applications Navigator section.

2. Right-click OrderBooking.

3. Select Deploy > LocalBPELServer > Deploy to default domain.

4. Enter the domain password of bpel when prompted.

   This compiles the BPEL process. Review the bottom of the window for any errors. If there are no errors, deployment was successful.

   
   Description of the illustration obph1deploy.gif
   
   

5. If there are errors, click BPEL Validation Errors to display details about the type and location of the error.

6. Make corrections and deploy again.

2.2.11 Running the Order Booking Process

You are now ready to begin the process of applying for a new order.

1. Log into Oracle BPEL Console using Internet Explorer or refresh the page if it is already open. Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager 10.1.2 > BPEL Console.

   The Dashboard tab of Oracle BPEL Console appears.

2. Click OrderBooking in the Deployed BPEL Processes list.

3. Enter a nine-digit integer value that does not begin with zero in the CustID field of the HTML Form and click Post XML Message. Ignore the other fields.

   The BPEL Processes tab displays a message similar to the following:

   Test Instance Initiated
   
   Instance '39e706a46ad531be:858bf1:fcc240f310:-7ffc' is being processed asynchronously.
   
   

4. Click the Instances tab at the top.

5. Verify that the OrderBooking and CreditRatingService instances were created. Both should appear in the Instance list. The Last Modified list displays the times at which they were created.

   
   Description of the illustration obph1run.gif
   
   

6. Click the OrderBooking instance.

   A message appears stating the following:

   The state of this instance is Completed
   
   

7. Click the Audit link to follow the instance execution process. The Audit link displays the following details:

   
   Description of the illustration obph1audit.gif
   
   

8. Click the Flow link.

9. Click callbackClient at the bottom of the flow to see the results.

   
   Description of the illustration obph1flow.gif
   
   

10. Verify the credit rating value. The comment field shows that the credit rating is returned as 560; this is also returned in the variable invokeCR_process_OutputVariable.

2.3 Summary

You have now built a simple asynchronous BPEL process that received an order from a client and obtained a credit rating from a Credit Rating service. You performed the following key tasks:

• Deployed a synchronous Credit Rating service.

• Created a new project named OrderBooking, which automatically created a BPEL process of the same name.

• Created a partner link that enabled you to define the external service (the deployed Credit Rating service) with which your BPEL process interacted.

• Designed the BPEL process and invoked the Credit Rating service by creating all necessary activities.

• Deployed the BPEL process to Oracle BPEL Console.

• Ran the BPEL process from Oracle BPEL Console and submitted a social security card number to the Credit Rating service, which checked the client's credit history.

• Reviewed the credit rating results returned from the Credit Rating service to the client.