> Tutorials > Tutorial 3. Validating a Loan Application

Tutorials

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

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 occur at any stage in the flow, though it usually happens as early as possible to prevent unnecessary processing of the message if an invalid result occurs. Validation can occur in several ways.

You can:

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 Objectives

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

Features Highlighted

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:

Figure 5-1 summarizes the logical architecture to support this scenario. It illustrates where AquaLogic Service Bus fits in the 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 can configure AquaLogic Service Bus to validate an incoming message in the message flow against a schema definition in a WSDL resource. Every field is checked for valid content. All elements must be populated for the application to be valid. However, in this case, when the value of the loan duration field is not an integer, the validation action raises an error. 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, the message is:

or

Required Resources

Use the Project folder, MortgageBroker, and the directory structure that you created in the previous tutorial to hold the project artifacts. The resources required for this scenario are described in Table 5-1.

Table 5-1 Routing a Loan Application Tutorial Resources
Resource Name
Description
normalLoan
The WSDL resource
NormalLoan Web Service
The external business service used by AquaLogic Service Bus
LoanGateway3
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, AquaLogic Service Bus raises a validation exception, and returns an error message 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, 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 pane, select Project Explorer.

    3. The Project Explorer pane is opened in the navigation pane 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:
    • ProxyService
    • BusinessServices
    • WSDL

Step 3: Create the Resources

In this step, you will create the proxy service, LoanGateway3. You will use the existing normalLoan service WSDL resource to validate the content of the message. If the loan application is valid, that is, if it meets the expected criteria, and is routed to the existing normalLoan business service. The WSDL resource and business service were created in "Create the normalLoan Service WSDL Resource" section in Tutorial 1. Routing a Loan Application.

Create a Proxy Service

In this step, you create a proxy service that is used to route the loan application to the appropriate business 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 Table 5-2.

Table 5-2 Proxy Service Configuration Settings
Proxy Service Name
LoanGateway3
Service Type
Select normalLoan WSDL
Endpoint URI
/loan/gateway3

You should also 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. The message flows can include zero or more pipeline pairs:

Pipelines can include one or more stages, which in turn include actions. To configure the behavior of the LoanGateway3 proxy service, for the message flow, you must complete the following:

Create a Pipeline Pair

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

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

    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 in Figure 5-2.

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 EditArrow symbolName and Description.
  4. Enter validate loan application and click Save.

The page is displayed as in Figure 5-3.

Figure 5-3 Add Stage to Request Pipeline

Add Stage to Request Pipeline

Configure an Action to Perform Message Validation
  1. To edit the stage, click validate loan application, then select EditArrow symbolStage. The Edit Stage Configuration page is displayed.
  2. Click the Add an Action link and select Message ProcessingArrow symbolValidate 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 Pipelineassociated 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. The Edit Stage Configuration page displays <XPath> which is replaced by the XQuery expression.

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

    10. You must validate the message against the resource as the proxy service is based on the WSDL resource that you originally created.

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

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

    1. In the Select WSDL Definitions pane, from the Types category, select the WSDL type for this WSDL as loanStruct.
    2. Click Submit to complete the selection.
  11. Select the Raise Error on validation failure option. The validate action appears as in Figure 5-4.
  12. Click Save to save the configuration.
    13. Figure 5-4 Configure Action for Message Validation
    Add Stage to Request Pipeline
Note: The validation of a message must occur as early as possible in a message flow. This prevents the unnecessary processing of a message in the case where the content of the message is invalid. When an exception is raised, further processing is stopped and a response is immediately returned to the client.
Note: Messages can be validated at the route node or using a separate Validate action (as in this case). When you create a Validation stage, the processing of the message is more modular and logically breaks down the actions in the message flow. If multiple validations are preformed on a message, the validate action is logically expanded.
Add a Stage Error Handler

The Stage Error Handler has to be configured as follows:

  1. Configure the Stage Error Handler to check the error code using an If...Then action and Else actions (Add an If...Then action to the Stage Error Handler).
  2. Add a Replace action within the If portion of the If...Then... action of the stage. Configure this action to replace the Notes element value with the fault context variable reason text. The fault description is returned to the client (Add a Replace Action to the Stage Error Handler).
  3. Add a Report action within the If portion of the If...Then... action of the stage (Add a Report Action to Report the Error).
  4. Add a Replace action within the Then... section of the stage (same as step 2).
  5. Add a Log action within the Then... action of the stage (Add a Log Action Within the Else Action).
  6. Add a Reply with Failure for both conditions of the stage (Add a Reply Action to Reply with a Failure Code).

The steps to add the Stage Handler are as follows:

  1. Click validate loan application, then select AddArrow symbolStage Error Handler. The Edit Error Handler page is displayed.
  2. Click Error handler, then select Add Stage. The stage1 node is displayed.
  3. Click stage1 and select EditArrow symbolName and Description as in Figure 5-5.
  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 EditArrow symbolStage. The Edit Stage Configuration page is displayed as in Figure 5-6.
    6. Figure 5-6 Edit Error Handler page


    Edit Error Handler page

Add an If...Then action to the Stage Error Handler
  1. Click the Add an Action link, then select Flow ControlArrow symbolIf...Then to add an If...Then action to the Reply stage.
  2. Click the <Condition> link to specify the expression that needs to be validated. The Xquery Condition Editor page is displayed.
    1. Enter $fault/ctx:errorCode in the Operand window
    2. Select the = Operator from the drop-down list.
    3. Enter "BEA-382505" in the Value window
    4. Select the And Conjunction from the drop-down list.
    5. Click Add to add expression to the Expressions window.
  3. Click Save to save the expression and return to the Edit Stage Configuration page.
Add a Replace Action to the Stage Error Handler
  1. Click the Add an Action link within the Then... portion of the If...Then action to add a Replace statement.
  2. Select Message ProcessingArrow symbolReplace.
  3. In the Replace statement, click the XPath link to edit the XPath expression. The XPath Expression Editor page is displayed.
  4. From the Select Structure drop-down list in the Variable Structures pane, select body.

    5. 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 Error Handler pageassociated 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.
  5. Click Validate to validate the expression, then click Save.
  6. In the Variable text field, enter body.
  7. Click the <Expression> link to display the XQuery Expression Editor page and accept the default selection of XQuery Text in the page.
  8. In the XQuery expression text box, enter:
    $fault/ctx:reason/text()
  9. Click Validate, then Save.
  10. Select the Replace node contents option. You need not replace the entire node.

The replace action should appear as in Figure 5-7.

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 ActionArrow symbolReportingArrow symbolReport. 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.

      3. 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 in 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 enables you to index the reporting data by error code. The keys are a convenient way to identify a message. You can use the error code 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 be added from there. Actions are added in sequence.

The report action should appear as in Figure 5-8.

Figure 5-8 Add Report Action

Add Report Action

The Edit Stage Configuration page appears as in Figure 5-9.

Figure 5-9 Request Actions for LoanGateway3 Proxy Service

Request Actions for LoanGateway3 Proxy Service

Add an Else Action to the Stage Error Handler

Click the If...Then icon Request Actions for LoanGateway3 Proxy Service and select Add else Condition to add an Else action to the Stage Error Handler.

Add a Replace Action Within the Else Action
  1. Click the Add an Action link to add a Replace statement. Select Message ProcessingArrow symbolReplace.
  2. Repeat all the steps in the Add a Replace Action to the Stage Error Handler section.
Add a Log Action Within the Else Action
  1. Click the Add an Action link to add a Replace statement. Select ReportingArrow symbolLog.
  2. Click the <Expression> link to display the XQuery Expression Editor page. Enter $fault/ctx:reason/text() in the XQuery Text window.
  3. Click Save to save the expression and return to the Edit Stage Configuration page.
  4. Enter Other than validation error, in the With Annotation window.
  5. Select Error from the At Severity Level drop-down list.

Now, the completed Else condition appears as in Figure 5-10.

Figure 5-10 Request Actions for LoanGateway3 Proxy Service - Else Condition
Request Actions for LoanGateway3 Proxy Service
Add a Reply Action to Reply with a Failure Code
  1. Click the Report action and select Add an ActionArrow symbolFlow ControlArrow symbolReply. The Reply action is added to the page.
  2. Select the With Failure option as in Figure 5-11.
    3. Figure 5-11 Reply Action to Reply with Failure Code


    Reply Action to Reply with Failure Code

  3. Click Save the stage configuration and return to the Edit Error Handler page.
  4. Click Save the error handler configuration.

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 EditArrow symbolRoute Node. The Edit Stage Configuration page is displayed.
  3. Click Add an Action, then select CommunicationArrow symbolRouting.

    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 and return 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 Edit Message Flow screen appears as in Figure 5-12.

    Figure 5-12 Configure Message Flow of LoanGateway3 Proxy Service


    Configure Message Flow of LoanGateway3 Proxy Service

  6. Click Save to save the configuration and return to the MortgageBroker/ProxyService page.
  7. Click Activate, then Submit.

You can view the map of the message flow of the proxy service as in Figure 5-13.

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

Map of Message Flow of the LoanGateway3 Proxy Service

Step 6: Test the 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 performed at the command prompt 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 the value is entered for the loan is a non integer, a fault is triggered and an error message results in the Notes field of the message. If the value is entered for the loan is an integer, the message is routed to the NormalLoanApprovalService business service.

This section describes how you can 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.5 (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\weblogic92\samples\servicebus\examples\src\
    2. In this directory, at the command prompt, run the following command: 
      3. setEnv.cmd
      Note: If you are testing the configuration on a UNIX system, run the setEnv.sh script at the command prompt.
  3. Change to the following directory:
    4. BEA_HOME\weblogic92\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 Table 5-3.

      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 as follows:
    1. In the command window, change to the following directory:
      2. BEA_HOME\weblogic92\samples\servicebus\examples\src\examples\webservices\jws_basic\normal
    2. Enter ant, then select Enter.
  6. To run the test, at the command prompt, enter:
    7. ant run

    This tests the routing logic of the proxy service. A response message from the Web Service is displayed at the command line. 

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

The response message indicates that a validation exception occurred because the loan duration is not an integer.

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\weblogic92\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 as follows:
    1. In a command window, change to the following directory:
      2. BEA_HOME\weblogic92\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 prompt, enter:
    4. ant run

    A response message from the Web Service is displayed at the command prompt: 

    [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 is an integer.

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 the 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. You can create your own reporting provider using the Reporting Service Provider Interface (SPI) if you do not wish to use the out-of-the-box reporting provider.

The dashboard of AquaLogic Service Bus Console contains reporting features that are presented in a drill-down format. When you explore the links presented, the information is made available to you.

For more information, see:

Monitoring

BEA AquaLogic Service Bus can 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