Skip navigation.

eDocs Home > BEA AquaLogic Service Bus 2.1 Documentation > Tutorials > Tutorial 3. Validating a Loan Application

Tutorials

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

Tutorial 3. Validating a Loan Application

This section describes how a BEA AquaLogic Service Bus proxy service can be configured to validate a message passing from a client to a business service. Validation can happen at any stage in the flow, though usually it happens as early as possible to prevent further unnecessary processing of the message should an invalid result occur.

Validation can happen in a number of ways:

BEA AquaLogic Service Bus does not automatically validate the message sent or received against the service interface definition, whether this is a WSDL definition or a messaging interface definition. However, you can configure a Validate action and use XQuery conditional expressions to perform explicit validate checks in the message flow. This reduces the possibility of run-time errors as a result of invalid configurations.

This section includes the following topics:

 

Prerequisites

Complete Tutorial 1. Routing a Loan Application and Tutorial 2. Transforming a Loan Application.

 

Tutorial Goals

The goal of the tutorial is to provide the steps to configure and test BEA AquaLogic Service Bus to demonstrate how message validation and error handling is managed using the graphical environment provided in the AquaLogic Service Bus Console. It includes the following:

Features Highlighted

Developing this tutorial exposes you to the following features of AquaLogic Service Bus

 

Definition of the Scenario

A primary mortgage company routes every loan application through a BEA AquaLogic Service Bus proxy service which validates the message. If the application is incomplete, it is written to an error directory and an error message is returned to the client. If complete, it is routed to a business service for review. If approved, the service returns a message indicating whether the loan is accepted or rejected.

The following figure summarizes the logical architecture to support this scenario. It illustrates where AquaLogic Service Bus fits in your enterprise to mediate the messaging between the client and the business services.

Figure 5-1 Validating a Loan Application using AquaLogic Service Bus

Validating a Loan Application using AquaLogic Service Bus


 


 


 

Overview of the Process in AquaLogic Service Bus

In this scenario, you will configure AquaLogic Service Bus to validate an incoming message in the message flow against a schema definition in a WSDL resource. Each field is checked for content. All elements must have content for the application to be valid. However, in this case, the validation action raises an error when the value of the loan duration field is not an integer. The context variable, $fault, is populated with the error. The error is trapped by a stage error handler which replaces the body context variable <Notes> field value with the text of the $fault <reason> element. A Report action then saves the error code and, for context, the message body for later viewing and searching in the console. The Reply action returns the body context variable to the client.

In this scenario, one of the following actions takes place:

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

Resource Name

Description

normalLoan

This is the WSDL resource

NormalLoan Web service

This is an external business service used by AquaLogic Service Bus

LoanGateway3

This is the AquaLogic Service Bus proxy service


 

 

Steps in This Tutorial

In this tutorial, BEA AquaLogic Service Bus is used to route a loan application within a Mortgage company to a target Web service. The loan application has to be completed correctly for the application to be processed. If there is an error in the application, then a validation exception is thrown, and an error message is returned to the client.

You will create a proxy service, LoanGateway3, and configure it to route a message to the normalLoan business service. You will configure the behavior of the proxy service, which 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 create the proxy service, LoanGateway3. You will use the existing normalLoan service WSDL resource as the basis on which to validate the content of the message. This WSDL resource was created in Tutorial 1. Routing a Loan Application in the section Create the normalLoan Service WSDL Resource. If the loan application is valid, that is, it meets the expected criteria, it is routed to the existing normalLoan business service. This business service was created in Tutorial 1. Routing a Loan Application in the section To Create the Normal Loan Business Service.

Create 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. Base this proxy service on the proxy service you previously created in Tutorial 1.

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-2 Proxy Service Configuration Settings

Proxy Service Name

LoanGateway3

Service Type

Select normalLoan WSDL

Endpoint URI

/loan/gateway3


 

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:

Step 4: Configure the LoanGateway3 Proxy Service

The proxy service is implemented in AquaLogic Service Bus as a message flow, which includes request and response pipelines. AquaLogic Service Bus Message Flows define the implementation of proxy services. Message flows can include zero or more pipeline pairs: request and response pipelines for the proxy service (or for the operations on the service) and error handler pipelines that can be defined for stages, pipelines, and proxy services. Pipelines can include one or more stages, which in turn include actions. To configure the behavior of the LoanGateway3 proxy service, you will complete the following for the message flow:

Create a Pipeline Pair

  1. In the AquaLogic Service Bus Console navigation panel, select Project Explorer.

    2. The Project Explorer pane is opened in the navigation panel.

    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 Actions column associated with the LoanGateway3 proxy service, click the Edit Message Flow icon Validating a Loan Application using AquaLogic Service Bus .

    3. The Edit Message Flow page for the proxy service LoanGateway3 is displayed.

  3. Click the LoanGateway3 node, then select Add Pipeline Pair.

The PipelinePairNode1 is created and placed in the message flow. Request and response pipelines are displayed for this node as shown in the following figure.

Figure 5-2 Add Pipeline Pair

Add Pipeline Pair


 

Configure the Request Actions for the LoanGateway3 Proxy Service

You must now configure the request actions for the proxy service.

  1. Click the request pipeline Add Pipeline Pair , then select Add Stage.
  2. Accept the default name, Stage 1.
  3. Click Stage1, then select Edit—>Name and Description.
  4. Enter validate loan application and click Save.

The screen should appear as shown in the following figure.

Figure 5-3 Add Stage to Request Pipeline

Add Stage to Request Pipeline


 

Configure an Action to do Message Validation

  1. To edit the stage, click validate loan application, then select Edit—>Stage. The Edit Stage Configuration page is displayed.
  2. Click the Add an Action link and select Validate from the drop-down list. The Validate action is added to the stage.
  3. In the Validate statement, click the XPath link to edit the XPath expression. The XPath Expression Editor page is displayed.
  4. Click Variable Structures. The Variable Structures pane is displayed.
  5. In the Variables Structure pane, from the Select Structure drop-down list, select body.

    6. A structural representation of the body element is displayed in the Variables Structure pane.

    1. Click + beside the processLoanApp element to expand the element.

      2. The processLoanApp element is within the $body - processLoanApp (request) element.

    2. Click + to expand the loanRequest element.

      3. A graphical representation of the structure of the loan request document is displayed.

    3. Select the circle icon Add Stage to Request Pipeline associated with the loanRequest element, drag and drop it in the XQuery Expression text box. The XQuery expression is written in the text box.

      4. ./exam:processLoanApp/loanRequest

      Note: The drag and drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, select the loanRequest element in the Variable Structures pane. The expression is displayed in the Property Inspector palette. Place the cursor in the XQuery expression text box and click Copy Property. The expression is copied to the text box. You can also copy the expression in the palette and paste it into the XQuery Expression text box.

  6. Click Validate to validate the XQuery.

    7. It is good practice 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.

  7. Click Save.

    8. You are returned to the Edit Stage Configuration page. <XPath> is replaced by the XQuery expression.

  8. In the Variable text field, enter body.
  9. Select resource, then select WSDL from the list. The Select a WSDL browser window is displayed.

    10. The proxy service is based on the WSDL resource you originally created, hence you must validate the message against this resource.

  10. In the Select a WSDL window, select the normalLoan WSDL.

    11. The Select WSDL Definitions panel is populated with the content categories of the WSDL.

    1. In the Select WSDL Definitions panel, from the Types category, select the WSDL type for this WSDL as loanStruct.
    2. Click Submit to complete your selection.
  11. Select the Raise Error on validation failure option.

The validate action should appear as shown in the following figure.

Figure 5-4 Configure Action for Message Validation

Configure Action for Message Validation


 
  1. Click Save.

Note: Validation of a message should happen as early as possible in a message flow. This prevents unnecessary processing of the message in a case where the content of the message may be invalid. If an exception is raised, further processing is stopped and a response is immediately returned to the client.

Messages can be validated at the route node or using a separate Validate action (as in this case). Creating a Validation stage make the processing of the message more modular and logically breaks out the actions in the message flow. In a case where multiple validations may be preformed on a message, it allows for logical expansion of the validate action.

The configuration is saved.

Add a Stage Error Handler using a Replace Action

Add a Replace action to the stage and configure this action to replace the Notes element value with the fault context variable reason text. This results in the fault description being returned to the client.

  1. Click validate loan application, then select Add—>Stage Error Handler. The Edit ErrorHandler page is displayed.
  2. Click Error handler, then select Add Stage. The stage1 node is displayed.
  3. Click stage1 and select Edit—>Name and Description
  4. Enter the name Reply for the stage, then click Save. The reply stage is displayed on the page.

    5. Figure 5-5 Edit Name and Description of Stage

    Edit Name and Description of Stage


     
  5. To edit the stage, click reply, then select Edit—>Stage. The Edit Stage Configuration page is displayed as shown in the following figure.

    6. Figure 5-6 Edit ErrorHandler page

    Edit ErrorHandler page


     
  6. Click the Add an Action link, then select Replace.
  7. In the Replace statement, click the XPath link to edit the XPath expression. The XPath Expression Editor page is displayed.
  8. From the Select Structure drop-down list in the Variable Structures pane, select body.

    9. A structural representation of the body element is displayed in the Variable Structures pane.

    1. Click + beside the processLoanApp element to expand the element.

      2. The processLoanApp element is within the $body - processLoanApp (request) element.

    2. Click + to expand the loanRequest element.
    3. Select the circle icon Edit ErrorHandler page associated with the Notes element of $body, drag and drop it on the XPath Expression text box. The following XPath expression is written in the text box.

      4. ./exam:processLoanApp/loanRequest/java:Notes

      Note: The drag and drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, select the Notes element in the Variable Structures pane. The expression is displayed in the Property Inspector palette. Place the cursor in the XPath expression text box and click Copy Property. The expression is copied to the text box. You can also copy the expression in the palette and paste it into the XPath Expression text box.

  9. Click Validate to validate the expression, then click Save.
  10. In the Variable text field, enter body.
  11. Click the <Expression> link to display the XQuery Expression Editor page and accept the default selection of XQuery Text in the page.
  12. In the XQuery expression text box, enter:
    $fault/ctx:reason/text()
  13. Click Validate, then Save.
  14. Select the Replace node contents option. You do not want to replace the entire node.

The replace action should appear as shown in the following figure.

Figure 5-7 Add Error Handler Using Replace Action

Add Error Handler Using Replace Action


 

Add a Report Action to Report the Error

Add a Report action and configure it to report the body context variable as detailed context, and set a key name of errorCode and the key value to the actual error code found in the fault context variable.

  1. Click the Replace action Add Error Handler Using Replace Action and select Add an Action—>Report. The Report action is added to the page.
  2. In the Report statement, click the <Expression> link. The XQuery Expression Editor page is displayed.
  3. Accept the default selection of XQuery Text in the page.
  4. In the Variables Structures pane, select body - processLoanApp from the Select Structure drop-down list.
    1. Select the icon Add Error Handler Using Replace Action associated with the $body element and drag and drop it on the XQuery Expression text box.

      2. The $body XQuery expression is written in the text box.

      Note: The drag and drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, select the body element in the Variable Structures pane. The expression is displayed in the Property Inspector palette. Place the cursor in the XQuery expression text box and click Copy Property. The expression is copied to the text box. You can also copy the expression in the palette and paste it into the XQuery Expression text box.

    2. Click Validate, then Save.

    You return to the Edit Stage Configuration page.

  5. In the key-value pair table, select the link Add a key.
    1. Enter a name for the key. In this case, enter errorCode.
    2. In the key value field, click XPath.
  6. In the Variable Structures pane, select fault from the Select Structure drop-down list.
    1. Select the icon Add Error Handler Using Replace Action associated with the errorCode and drag and drop it on the XPath Expression text box.

      2. The ./ctx:errorCode expression is written in the text box.

      Note: The drag and drop functionality works only in Internet Explorer (IE) browsers. If you are using a browser other than IE, select the errorCode element in the Variable Structures pane. The expression is displayed in the Property Inspector palette. Place the cursor in the XPath expression text box and click Copy Property. The expression is copied to the text box. You can also copy the expression in the palette and paste it into the XPath Expression text box.

      This step allows the reporting data to be indexed by errorcode. The keys are a convenient way to identify a message. You can use the errorcode to search for reporting entries in the reporting module.

  7. Click Validate to validate the XQuery, then click Save.
  8. In the Variable text field, enter fault.

Note: To Add an action on a page, click the Action preceding the placement of the new action and select the Action to add from there. Actions are added in sequence.

The report action should appear as shown in the following figure.

Figure 5-8 Add Report Action

Add Report Action


 

Add a Reply Action to Reply with a Failure Code.

  1. Click the Report action and select Add an Action->Reply. The Reply action is added to the page.
  2. Select the With Failure option as shown in the following figure.

    3. Figure 5-9 Reply Action to Reply with Failure Code

    Reply Action to Reply with Failure Code


     
  3. Click Save the stage configuration.
  4. Save the error handler configuration.

Now, the Edit Stage Configuration page should appear as shown in the following figure.

Figure 5-10 Request Actions for LoanGateway3 Proxy Service

Request Actions for LoanGateway3 Proxy Service


 

Step 5: Add a Default Routing Case

Configure the Route Node

Add a Route Node to the Pipeline pair, then configure the Route Node to route to the normalLoan business service.

  1. Click PipelinePairNode1, then select Add Route Node.
  2. Click RouteNode1 and select Edit—>Route Node. The Edit Stage Configuration page is displayed.
  3. Click Add an Action, then select Routing.

    4. The Route action is displayed in the page.

  4. In the Route statement, click the Service link to define the service to which you want to route the messages. The Select Service page is displayed.
    1. Select the NormalLoan business service.
    2. Click Submit.

      3. You are returned to the Edit Stage Configuration page.

  5. In the Operation drop-down list, select processLoanApp.

    6. This is the operation on the NormalLoan business service that is invoked at run time.

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

    The screen should appears as shown in the following figure.

    Figure 5-11 Configure Message Flow of LoanGateway3 Proxy Service

    Configure Message Flow of LoanGateway3 Proxy Service


     
  6. Click Save, then Save to save the configuration. You are returned to the MortgageBroker/ProxyService page.
  7. Click Activate, the Submit.

You can view the map of the message flow of the proxy service as shown in the following figure.

Figure 5-12 Map of Message Flow of the LoanGateway3 Proxy Service

Map of Message Flow of the LoanGateway3 Proxy Service


 

Step 6: Test Your Loan Application Routing Configuration

Now that you have configured BEA AquaLogic Service Bus to work with the client and the target business services, you can test the configuration. Testing is done on the command line by changing the value of the Loan duration (in years) field in the build.xml file and then running ant. The behavior for the proxy service in this scenario depends on the correct value being entered for the loan duration. If a non-integer value is entered for the loan, then a fault is triggered and an error message results:

This section describes how to test the proxy service for both cases. The message returned in the command window after running a test indicates whether a validation exception results or whether the message was routed to the appropriate business service.

Note: Run the tests in this section multiple times (at least five times) to generate data to enable you to explore the reporting and monitoring features described in Step 7: Using Reporting and Monitoring.

This section includes the following test scenarios:

To run this test correctly, ensure that WebLogic Server is started in the BEA AquaLogic Service Bus 2.1 (ServiceBusTutorial) domain.

To Test the Validation Exception

  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\weblogic91\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\weblogic91\samples\servicebus\examples\src\examples\webservices\jws_basic\normal
  4. To test the routing behavior of the proxy service, in this case, 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/gateway3 steve 555 2500 20.5 4.9 notes" />

    This changes the URI to that of the proxy service running in the tutorial domain, and specifies a value of 20.5 (a non-integer value) for the loan duration.

    The remainder of the input parameters specified on the arg line are described in the following table.

    Table 5-3 Input Parameters

    Input Parameter

    Description

    steve

    a single string representing the client name

    555

    the client ID

    2500

    the requested loan amount

    20.5

    the duration of the loan

    4.9

    the requested interest rate

    notes

    a string that can contain miscellaneous notes


     
  5. Ensure that the business services are deployed:
    1. In the Command window, change to the following directory:
      2. BEA_HOME\weblogic91\samples\servicebus\examples\src\examples\webservices\jws_basic\normal
    2. Enter ant, then press Enter.
  6. To run the test, on the command line, enter:
    7. ant run

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

     [java] Loan Application Response: ALSB Validate action failed validation
     [java] Rate: 4.9
BUILD SUCCESSFUL

The response message indicates that a validation exception occurred as the value entered in the loan duration field was a non-integer value.

To Test the NormalLoanApprovalService Business Service

  1. Follow the procedure To Test the Validation Exception to edit the build.xml file in the following directory:
    2. BEA_HOME\weblogic91\samples\servicebus\examples\src\examples\webservices\jws_basic\normal

    Note: In this case (to test the NormalLoanApprovalService business service), enter a value of 20 for the loan duration in the build.xml file (see Table 5-3), then save the changes.

  2. If you have not already done so, deploy the business services:
    1. In a Command window, change to the following directory:
      2. BEA_HOME\weblogic91\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: 4.9
    BUILD SUCCESSFUL

The response message indicates that the NormalLoan business service processed the request because the loan duration requested was 20, an integer value.

Step 7: Using Reporting and Monitoring

Now that you have tested the proxy service you can explore the reporting and monitoring features of the AquaLogic Service Bus Console.

Note: You must have run the tests in Step 6: Test Your Loan Application Routing Configuration multiple times (at least five times) to generate data to enable you to explore the reporting and monitoring features.

Reporting

AquaLogic Service Bus includes a JMS Reporting Provider for message reporting. The Reporting module in the AquaLogic Service Bus Console displays the information captured from this reporting provider. If you do not wish to use the out-of-the-box reporting provider, you can create your own reporting provider using the Reporting Service Provider Interface (SPI).

Reporting automatically happens in the AquaLogic Service Bus Console. Reporting features are available from the Dashboard. Information is presented in a drill-down format. The more you explore the links presented, the more information is made available to you.

For more information, see:

Monitoring

BEA AquaLogic Service Bus provides the capability to monitor and collect run-time information for both systems operations and business auditing purposes. AquaLogic Service Bus aggregates run-time statistics that you can view on a customizable Dashboard. The Dashboard allows you to monitor the health of the system and alerts you to problems in your messaging services. With this information, you can quickly and easily isolate and diagnose problems as they occur.

For more information, see:

 

Back to Top Previous Next