Skip navigation.

eDocs Home > BEA AquaLogic Service Bus 2.0 Documentation > Tutorials > Tutorial 2. Transforming a Loan Application

Tutorials

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Tutorial 2. Transforming a Loan Application

Data transformation is the mapping of data from one format to another. This section describes how BEA AquaLogic Service Bus routes messages and transforms messages, when necessary, according to specific criteria that you configure for a proxy service.

This section includes the following topics:

 

Prerequisites

Complete Tutorial 1. Routing a Loan Application.

 

Tutorial Goals

The goal of the tutorial is to provide the steps to create and test a routing and transformation scenario developed using the graphical environment provided in AquaLogic Service Bus Console.

Using the AquaLogic Service Bus Console you will build on what you learned in Tutorial 1. Routing a Loan Application, to:

 

Definition of the Scenario

A primary mortgage company uses BEA AquaLogic Service Bus to identify and re-route loan applications that can be sold to secondary loan companies. Loan applications with a principal request of greater than 25,000,000.00 are candidates for sale to a secondary loan company. When AquaLogic Service Bus receives a loan application meeting these criteria, the customer's credit rating information is retrieved (by making a callout to a Web service) and added to the loan application, then the application is forwarded to the secondary mortgage company's Web service to be processed.

Loan applications with a principal request of equal to or less than 25,000,000.00 are routed to a different business service for processing.

The target business services respond indicating whether the loan application is approved or rejected.

The following figure illustrates where BEA AquaLogic Service Bus fits in your enterprise to mediate the messaging between the enterprise services and the business services.

Figure 5-1 Expose a Loan Application Processing Web Service via AquaLogic Service Bus

Expose a Loan Application Processing Web Service via AquaLogic Service Bus


 

Overview of the Run-Time Process in AquaLogic Service Bus

A primary mortgage company receives a loan application. It is routed through the AquaLogic Service Bus proxy service, LoanGateway2, to determine the target business service to process the application. The default request pipeline simulates a credit rating lookup by assigning a custom context variable ($rating) the value AA (of type string). In addition, a customer ID (an integer) is returned from the lookup and assigned to another custom context variable: $custID.

Subsequently, to satisfy the interface requirements of the secondary loan company service, the message body is transformed by removing the customer name and social security number elements and replacing them with <rating>$rating</rating> and <custID>$custID</custID>. The transformed message ($body) is routed to a business service that handles applications for large loan amounts. The service returns a response of:

"Congratulations, your loan is approved and your loan ID is nnnnn. In future communications about your loan please reference this Loan ID for faster service".

Required Resources

You will use the Project folder, MortgageBroker, and the directory structure you created in the previous tutorial to hold the project artifacts. The resources required for this scenario are described in the following table.

Table 5-1 Routing a Loan Application Tutorial Resources

CreditRatingService, LoanSale

These are the WSDL resources

NormalLoan, LoanSaleProcessor, CreditRatingService

These are the external business services used by AquaLogic Service Bus

LoanGateway2

This is the AquaLogic Service Bus proxy service


 

 

Steps in This Tutorial

In this tutorial, you will build on what you learned in Tutorial 1. Routing a Loan Application—you will import additional WSDL resource, register new business and proxy services, and configure the routing behavior for the proxy service. Configuring the routing behavior includes:

Complete the following steps to design and configure the proxy service and the associated resources in AquaLogic Service Bus to resolve this user case scenario:

Step 1: Prepare Your Environment

Ensure that AquaLogic Service Bus is running in the domain you created for the tutorial and that you have completed the steps described in Tutorial 1. Routing a Loan Application.

Step 2: Create a Session and Set up a Project

For this tutorial, you use the project folder, MortgageBroker, and the directory structure you created in Tutorial 1. Routing a Loan Application to hold the project artifacts.

  1. Click Create in the Change Center to create a new session.
  2. In the AquaLogic Service Bus Console navigation panel, select Project Explorer.

    3. The Project Explorer pane is opened in the navigation panel and a project page is displayed in the console.

  3. In Project Explorer expand the MortgageBroker project tree to expose the sub folders containing the project artifacts.:

Step 3: Create the Resources

In this step, you will import the WSDL resource, and create the proxy service and the business service required for the tutorial:

Create the WSDL Resources

Because the WSDLs are the basis on which you create the business services and the proxy service, you must create the WSDL resources (LoanSale and CreditRatingService) before creating the other resources required for this scenario. Use the configuration wizard to configure the WSDL properties.

To import the appropriate WSDLs and create the WSDL resources, follow the steps described in To Import a WSDL, but for this instance name your resources and base them on the WSDLs as described in the following table.

Table 5-2 WSDL Configuration Settings

Resource Name

Location of the WSDL

LoanSale

BEA_HOME\weblogic90\servicebus\examples\src\examples\webservices\jws_basic\large\LargeLoanPurchasingService.wsdl

CreditRatingService

BEA_HOME\weblogic90\servicebus\examples\src\examples\webservices\jws_basic\credit\CreditLoanApprovalService.wsdl


 

When you complete this step, the MortgageBroker/WSDL folder contains the WSDL resources created in this tutorial and in Tutorial 1. Routing a Loan Application:

Creating a Proxy Service

In this step, you create a proxy service. The proxy service is used to route the loan application to the appropriate business service. It also calls a look up service to get the credit rating of the requestor if the loan amount requested is greater than 25 000 000.00. (Note that no units are assigned to the loan amount; it can be dollars or any other unit of currency.)

To create a new proxy service, follow the steps described in To Create the Proxy Service, but for this instance use the proxy service name and the Endpoint URI described in the following table.

Table 5-3 Proxy Service Configuration Settings

Proxy Service Name

LoanGateway2

Endpoint URI

/loan/gateway2


 

Review the configuration settings prior to registering the proxy service.

When you complete this step, the MortgageBroker/ProxyService folder contains the proxy services you created in this tutorial and in Tutorial 1. Routing a Loan Application:

Creating a Business Service

In this scenario, the proxy service is configured to route to one of several different business services, depending on the business requirements:

You created the Normal Loan service in Tutorial 1. Routing a Loan Application. To create the LoanSaleProcessor and CreditRatingService business services for this scenario, follow the steps described in To Create the Normal Loan Business Service. However, in this case, configure your services using the names, service types, and endpoint URIs described in the following tables.

Table 5-4 Configuration Settings for the LoanSaleProcessor Business Service

Business Service Name

LoanSaleProcessor

Service Type

WSDL port.

Use the WSDL Browser to select the LoanSale WSDL.

Select the helloPort port.

Endpoint URI

Accept the default value.


 

Table 5-5 Configuration Settings for the CreditRatingService Business Service

Business Service Name

CreditRatingService

Service Type

WSDL port.

Use the WSDL Browser to select the creditRatingService WSDL.

Select the helloPort port.

Endpoint URI

Accept the default value.


 

When you complete this step, the MortgageBroker/BusinessService folder contains the business services you created in this tutorial and in Tutorial 1. Routing a Loan Application:

Summary

By completing Step 1: Prepare Your Environment to Step 3: Create the Resources, you created the resources required for this scenario. You configured the proxy service with a base configuration. Subsequent steps (Step 4: Configure the Routing for the LoanGateway2 Proxy Service to Step 6: Configure the Routing Table Response Actions for the LoanGateway2 Proxy Service) describes how to complete the configuration of the proxy service to add the routing, transformation, and WS Callout behavior for the loan application messages.

Step 4: Configure the Routing for the LoanGateway2 Proxy Service

The proxy service is implemented in Service Bus as a Message Flow, which includes request and response pipelines. This step includes the following tasks:

Create a Routing Table

  1. In the AquaLogic Service Bus Console navigation panel, select Resource Browser.

    2. The Resource Browser pane is opened in the navigation panel and the Summary of proxy Services project page is displayed in the console.

    Note: You must be in a session to edit resources. If you have not already done so, begin a session (click Create in the Change Center) so that you can configure the proxy service and edit the message flow.

  2. In the Options column associated with the LoanGateway2 proxy service, click the Edit Message Flow icon Expose a Loan Application Processing Web Service via AquaLogic Service Bus .

    3. The Edit Message Flow page for the proxy service LoanGateway2 is displayed. This page displays the default message flow configuration. The default configuration consists of a start node and an echo node. This is the minimum configuration of a message flow.

  3. Left-click the Echo Node. Select Convert to Route Node.
  4. In the configuration dialog, note the default name for the node is RouteNode1; click Save.

    5. The route node is saved and named RouteNode1.

  5. Left-click RouteNode1 and from the pop up menu select Edit—>Route Node.

    6. The Edit Stage Configuration page is displayed. The page contains a single link, Add an Action.

  6. Left-click Add an Action, then select Routing Table.

    7. The Edit Stage Configuration page changes to display routing table configuration page.

    You will configure the routing table to route messages to business services based on evaluating the amount element of the incoming message. You must create an XQuery expression to do this. You can do so using the XQuery Expression Editor.

Configure the Routing Expression

  1. In the Routing table, select the <Expression> link. The Edit an XQuery Expression page is displayed.
  2. Accept the default selection of Text for XQuery expression.
  3. In the Message Context Variables pane, from the drop-down list of system context variables, select body.

    4. A graphical representation of the body element in the incoming message is displayed in the Message Context Variables pane.

    1. Click + beside the processLoanApp element to expand the element.
    2. Click + to expand the Loanrequest element. The structure of the loan request document is displayed. At run time, the proxy service makes its routing decision based on the value in the amount element of the message—therefore you select this element to use in the expression.
    3. Select the circle icon Expose a Loan Application Processing Web Service via AquaLogic Service Bus associated with the Amount element to use in the expression, and drag the amount element to the XQuery Edit Expression text box.

      4. Note: The drag and drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, follow step a and step b. The expression is displayed in the XPath text box in the Message Context Variables palette. Instead of dragging and dropping the Amount node onto the Edit Expression text box, simply copy the expression from the XPath text box and paste it into the Edit Expression text box.

  4. Click Validate to validate the XQuery.

    5. It is good practise to do this before you submit the expression. The expression is validated for syntax. If there are errors in the expression, they are displayed directly above the Validate button. In this case the expression is valid.

  5. Click Submit.

    6. You are returned to the routing table on the Edit a Stage Configuration page. <Expression> is now replaced by the expression that returns the value of the amount element in the message.

  6. In the Condition operators field, select > from the drop down list of operators.
  7. In the associated text field enter the number 25000000 (without commas).

    8. The routing table now contains an expression that determines the routing behavior. If the value in the Amount field is greater than 25000000, then messages are routed according to the routing table configuration.

  8. Select the Service link to define the service to which you want to route when the amount is greater than 25000000. The Service Browser is displayed.
    1. Select the LoanSaleProcessor business service
    2. Click Submit.
  9. In the Routing Table Operation menu, select the processLoanApp operation. This is the operation on the LoanSaleProcessor service business service that is invoked at run time if the amount of the loan requested in the loan application is greater than 25000000.

You have now defined the case for routing the loan application to the LoanSaleProcessor business service.

When a loan application with the amount of the loan greater than 25000000 is identified, a Web service callout (WS Callout) is performed to retrieve the customer's credit rating. The credit rating information is added to the loan application and the application is then forwarded to the secondary mortgage company's business service to be processed. The next section (Step 5: Configure the Routing Table Request Actions for the LoanGateway2 Proxy Service) describes how to configure the proxy service to do the WS Callout and transform the message appropriately for the target service.

Step 5: Configure the Routing Table Request Actions for the LoanGateway2 Proxy Service

To configure the Routing Table Request actions, execute the following steps:

Configure the WS-Callout Input Parameter

A WS-Callout is used to send the loan application to the CreditRatingService business service, which returns the credit rating of an applicant. Before configuring the WS-Callout action, you must assign an input parameter for the WS-Callout action as follows:

  1. Ensure that the Edit Stage Configuration page for the routing table you created in Step 4: Configure the Routing for the LoanGateway2 Proxy Service is open in the AquaLogic Service Bus Console.
  2. In the Routing Table Request Actions section, click Add an Action, then select Assign.

    3. The Assign action is added to the Request Action pipeline in the Routing Table.

  3. Select the <Expression> link. The Edit XQuery Expression page is displayed.
    1. Accept the default selection of Text.
    2. Select body from the Message Context Variables list, then expand the element list and drag the loanRequest element and drop it into the expression text box. The expression is:
      3. $body/exam:processLoanApp/loanRequest
    3. Click Validate to validate the XQuery, then Submit. You are returned to the routing table on the Edit a Stage Configuration page. <Expression> is now replaced by the expression that returns the content of the message to be sent to the WS Callout service.
  4. Enter inputparam in the variable text box.

    5. This step completes the assignment of the value returned by the XQuery expression ($body/exam:processLoanApp/loanRequest) to the inputparam variable.

Add a WS-Callout Action

This section describes how to configure the WS-Callout action to send the loan application to the CreditRatingService business service, which returns the credit rating of an applicant.

  1. In the Routing Table Request Actions section, click Expose a Loan Application Processing Web Service via AquaLogic Service Bus , then select Add an Action—>Web Service Callout.

    2. The WS-Callout action is added to the Request Action pipeline in the Routing Table.

  2. Click the WS-Callout Service link. The Service Browser is displayed.
    1. In the Service Browser, select CreditRatingService.
    2. Click Submit.
  3. From the Operation menu, select processLoanApp. The fields that allow you to configure the request and response parameters for the WS Callout are displayed:
    1. In the WS-Callout Request Parameters section, set the Loan request parameter to inputparam (the message context variable you defined in the preceding section).
    2. In the WS-Callout Response Parameters section, set the return parameter name to creditRating.

    This step completes the configuration of the WS-Callout to the CreditRatingService Web Service. The credit rating returned by the Web service is assigned to the creditRating context variable.

Configure the Message Transformation

In this section, you will configure the transformation of the message to match the public contract (interface requirements) of the loanSaleProcessor Service. Specifically, this section describes how to:

To Rename the Namespace

  1. Left-click the WS-Callout icon Expose a Loan Application Processing Web Service via AquaLogic Service Bus , then select Add an Action—>Rename.

    2. The Rename action configuration fields are added to the Request Actions pane.

  2. In the Rename statement, select <XPath>. The Expression Editor is displayed.
    1. In the Edit the Expression text box, enter the following XPath expression:
      2. .//java:*

      This expression identifies every instance of a namespace with a prefix of java.

    2. Click Submit. You are returned to the Edit Stage Configuration page.
  3. In the variable text box, enter body.

    4. The body context variable holds the body of the message. By completing these steps, you created a condition in which the XPath expression finds all the namespaces with the java prefix in the body context variable. The next step specifies the namespace with which to replace the namespaces identified by the XPath expression.

  4. Select the namespace radio button and enter the fully qualified namespace to be substituted in the message. The new namespace is java:large.client.

    5. Note: The namespace that you are replacing in this case is java:normal.client.

To Insert a New Element into the Message

  1. Left-click the Rename icon Expose a Loan Application Processing Web Service via AquaLogic Service Bus , then select Add an Action—>Insert.

    2. The Insert action configuration fields are added to the Request Actions pane.

  2. In the Insert action, select <Expression>. The Edit an XQuery Expression page is displayed. You will add a new namespace on this page.
  3. In the Namespace Definitions palette, locate to the User Namespaces area. Click + associated with the User Namespaces. The New Namespace Declaration dialog is displayed.
    1. In the prefix field enter lg.
    2. In the Namespace text field, enter java:large.client
    3. Click OK.

      4. You are returned to the Edit an XQuery Expression page, and the new namespace is displayed in the User Namespaces area in the Namespace Definitions palette.

  4. In the Edit the Expression text box, enter the following expression to specify how the new element is constructed:
    5. <lg:CreditRating>{$creditRating}</lg:CreditRating>

    At run time, the $creditRating variable is assigned a credit rating value by the credit rating service (to which we configured a WS-Callout action in Add a WS-Callout Action).

  5. Click Validate, then Submit.

    6. Note: It is good practice is to validate your expressions before submitting them.

  6. In the Insert statement, select after from the drop down list.
  7. Select the <XPath> link. The Edit an XPath Expression page is displayed:
    1. In the Message Context Variables pane, select body.
    2. Expand the element list and drag the Notes element and drop it into the Edit the Expression text box.

      3. Note: The drag and drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, when you click the Notes node in the Message Context Variables palette, the expression is displayed in the XPath text box. Instead of dragging and dropping the Notes node, simply copy the expression from the XPath text box to the Edit an Expression text box.

    The following XPath expression is written to the text box

    ./exam:processLoanApp/loanRequest/java:Notes
  8. In this statement, replace the namespace java with the namespace lg:
    9. ./exam:processLoanApp/loanRequest/lg:Notes
  9. Click Validate, then Submit to return to the Edit a Stage Configuration page.
  10. Enter body in the Variable text field (the last field in the expression). This is the context variable into which the new <CreditRating> element is inserted at run time.

    11. This step completes the configuration of the outbound message. You added a credit rating element to the message and changed the namespace so that the message complies with the public contract (interface) of the target service.

    The next step describes how to configure the response actions for the LoanGateway2 proxy service.

Step 6: Configure the Routing Table Response Actions for the LoanGateway2 Proxy Service

This step describes how to configure the response actions in the Routing Table so that the message that is returned by the proxy service to the client complies with the client's public contract (WSDL). Specifically, this section describes how to:

To Delete an Element

  1. Ensure that the Edit Stage Configuration page for the routing table you created and configured in the preceding steps is open in the AquaLogic Service Bus Console.
  2. In the Routing Table Response Actions section, click Add an Action—>Delete.

    3. The Delete action configuration fields are added to the Response Actions in the Routing Table.

  3. Select the < XPath> in variable option, then click <XPath>. The Edit an XPath Expression page is displayed.
    1. In the Edit the Expression text box, enter the following expression:
      2. ./exam:processLoanAppResponse/return/lg:CreditRating

      where processLoanAppResponse represents the WSDL operation that was invoked with the string Response appended to it, and return is the WSDL part name.

    2. Click Validate, then Submit. You are returned to the Edit Stage Configuration page.
  4. Enter body in the variable text field in the Delete action.

    5. The configuration for the Delete action is therefore:

    Delete ./exam:processLoanAppResponse/return/lg:CreditRating in variable body

    By completing these steps, you have specified that AquaLogic Service Bus removes the credit rating element from the response message as the message is processed in the response pipeline.

To Add a Rename Action

This section describes how to rename the namespace to the namespace required by the client, that is java:normal.client. (Recall that you configured the request message to the loanSaleProcessor business service to change the namespace to that required by that service. (See To Rename the Namespace.)

  1. Left-click the Delete icon Expose a Loan Application Processing Web Service via AquaLogic Service Bus , then Add an Action—>Rename.

    2. The Rename action configuration fields are added to the Response Actions pane.

  2. In the Rename statement, select <XPath>. The Expression Editor is displayed.
    1. In the Edit the Expression text box, enter the following XPath expression:
      2. .//lg:*

      This XPath expression finds every namespace with a prefix of lg:.

    2. Click Submit. You are returned to the Edit Stage Configuration page.
  3. In the Rename action's variable text field enter body.
  4. Select the namespace option, and in the text field associated with the namespace, enter java:normal.client.

    5. By completing these steps, you have specified that AquaLogic Service Bus replaces all namespaces with the prefix lg: in the response message with java:normal.client.

The last step in the configuration of the routing table for the LoanGateway2 proxy service is to add a default routing case (an else condition) to the Case expression.

Step 7: Add a Default Routing Case

This step describes how to configure a default routing case for the routing table for the LoanGateway2 proxy service. At run time, AquaLogic Service Bus routes messages according to the configuration of this default case if none of the conditions configured in the Routing Table is met.

  1. Left-click the routing table Case icon Expose a Loan Application Processing Web Service via AquaLogic Service Bus , then select Insert—>Default Case.

    2. The default case is added after the routing table on the Edit Stage Configuration page.

  2. Select the <Service> to display the Services Browser.
    1. Select the NormalLoan business service.
    2. Click Submit.
  3. In the Default case configuration fields, select the operation processLoanApp.
  4. Click Save to save the route node configuration and return to the Edit Message Flow page for the LoanGateway2 proxy service.
  5. Click Save on each configuration page until you return to the Summary of Proxy Services page
  6. Click Activate in the Change Center to save the session configuration information.

Step 8: Test Your Loan Application Routing Configuration

Now that you have configured AquaLogic Service Bus to work with the client and the target business services, you can test your configuration. The routing behavior of the proxy service in this scenario is based on the value of the loan amount in the loan application message. Changing the value of the loan amount changes the routing behavior.

This section describes how to test the proxy service for both cases. The message returned in the command window after running a test indicates the success or failure of the test and identifies the business service that processed the request.

This section includes the following test scenarios:

To Test the LoanSaleProcessor (the Large Loan Purchasing Service) Business Service

  1. Open a command window.
  2. If you have not run the setEnv.cmd to set up your environment, you must do so now.
    1. Change to the following directory:
      2. BEA_HOME\weblogic90\samples\servicebus\examples\src\
    2. In this directory, on the command line, run the following command: 
      3. setEnv.cmd

      Note: If you are testing the configuration on a UNIX system, run the setEnv.sh script at your command line prompt.

  3. Change to the following directory:
    4. BEA_HOME\weblogic90\samples\servicebus\examples\src\examples\webservices\jws_basic\normal
  4. To change the routing behavior of AquaLogic Service Bus, you must edit the build.xml file run target:
    1. Open build.xml.
    2. Scroll to the end of the build.xml file looking for the string:
      3. <arg line="http://$...
    3. Replace the string found at this location with:
      4. <arg line="http://${wls.hostname}:${wls.port}/loan/gateway2 steve 555 25000001 20 5.1 notes" />

    This changes the URI to that of the proxy service to that of the deployed Web service (gateway2) running in the tutorial domain, and specifies a value of 25000001 for the loan amount. (For more information about the input parameters for the test, see Table 4-5.)

  5. If you have not already done so, deploy the business services:
    1. In a command window, change directory to the following directory:
      2. BEA_HOME\weblogic90\samples\servicebus\examples\src\examples\webservices\jws_basic\normal
    2. Enter ant, then press Enter.
  6. To test the build, on the command line enter:
    7. ant run

    This tests the routing logic of the proxy service. The message from the Web service is output to the command line.

    [java] Loan Application Response: CREDIT RATING: AA: LOAN PURCHASED BY THE <i><b>LARGE</b></i> LOANS SERVICE
         [java] Rate: 5.1
    BUILD SUCCESSFUL

Note that the response message indicates that the Large Loan Service processed the request because the amount of the loan requested was 25000001 (greater than 25000000).

To Test the NormalLoan Business Service

  1. Follow the procedure To Test the LoanSaleProcessor (the Large Loan Purchasing Service) Business Service on page 5-18 to edit the build.xml file in the following directory:
    2. BEA_HOME\weblogic90\samples\servicebus\examples\src\examples\webservices\jws_basic\normal

    In this case (to test the normalLoan business service), in the build.xml file, enter a value of 25000000 for the loan amount (see Table 4-5), then save the changes.

  2. If you have not already done so, deploy the business services:
    1. In a command window, change directory to the following directory:
      2. BEA_HOME\weblogic90\samples\servicebus\examples\src\examples\webservices\jws_basic\normal
    2. Enter ant, then press Enter.
  3. To test the routing logic of the proxy service, on the command line enter:
    4. ant run

    A response message from the Web service is output to the command line.

    [java] Loan Application Response: APPROVED BY THE <i><b>NORMAL</b></i> LOAN APPLICATION PROCESSING SERVICE
         [java] Rate: 5.1
    BUILD SUCCESSFUL

Note that the response message indicates that the Normal Loan Application Processing Service processed the request because the amount of the loan requested was 25000000.

 

Best Practices

In this tutorial, you configure the transformation and replace the namespaces in the Route node. Alternatively, it is possible to configure the same logic in the request pipeline in a pipeline pair.

The work you must do to accomplish the transformation and namespace replacement is the same regardless of the model you choose.

In the case of the tutorial scenario, it is easier to add the actions to the request and response actions of the existing route node rather than create a separate pipeline pair, add a stage, and then add the transformation actions to that stage.

The following scenario describes a situation in which the choice of the implementation is important:

A route node routes messages to five different services. Each service requires the same transformation. In this scenario, it is better practice to add a single transformation to a request pipeline rather than configure five identical sets of transformations for each routing configuration in each route node. The run-time execution cost is the same, but the cost of maintaining, configuring, and understanding the latter implementation is higher and more work intensive.

 

Back to Top Previous Next