> 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

ALSB proxy services can be configured to validate messages passed between clients and business services. Validation actions can be configured at any stage in the message handling pipeline. However these actions are usually configured in the early stages to eliminate erroneous messages. XQuery conditional expressions can be used to perform explicit validation during message processing.
You can configure message validation logic in the following ways:

This tutorial includes the following topics:

 

Prerequisites

You must complete Tutorial 1. Routing a Loan Application and Tutorial 2. Transforming a Loan Application before beginning this tutorial:

 

Tutorial Objectives

The objective of this tutorial is to provide tasks to configure ALSB resources that implement message validation and error handling, in ALSB Console. This tutorial includes the following:

Features Highlighted

This tutorial exposes you to the following features of ALSB:

 

Definition of the Scenario

A primary mortgage company routes every loan application through an ALSB proxy service that validates the message. If the application is:

Figure 5-1 summarizes the logical architecture to support this scenario and illustrates how ALSB is positioned in the enterprise system environment to mediate the messaging between the client and the business services.

Figure 5-1 Validating a Loan Application using ALSB

Validating a Loan Application using ALSB

Overview of the Run-Time Process in ALSB

In this scenario, you can configure ALSB 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. When the value of the loan duration field is not an integer, the validate action raises an error. The context variable, $fault, is populated with the error details. 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 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 routing is as follows:

Required Resources

Use the MortgageBroker project folder 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 the following table.

Table 5-1 Routing a Loan Application Tutorial Resources
Resource Name
Description
normalLoan
The WSDL resource.
NormalLoan
The external business service used by ALSB.
LoanGateway3
The ALSB proxy service.

 

Tasks in This Tutorial

In this tutorial, ALSB 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, ALSB 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 by performing the following tasks:

Prepare Your Environment

Ensure that ALSB is running in the domain you created for the tutorial and that you have completed the tasks described in Tutorial 1. Routing a Loan Application.

Create a Session

For this tutorial, use the MortgageBroker project folder 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 ALSB Console navigation pane, select the Project Explorer.

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

  3. In the Project Explorer expand the MortgageBroker project tree to expose the subfolders containing the project artifacts:
    • ProxyService
    • BusinessService
    • WSDL

Create the Resources

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

Create a Proxy Service

In this task, you create a proxy service that is used to route the loan application to the appropriate business service. For creating this proxy service instance, follow the tasks described in To Create the Proxy Service, and use the proxy service name and the endpoint URI specified in Table 5-2.

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

Figure 5-2 LoanGateway3 Proxy Service

LoanGateway3 Proxy Service

While configuring the proxy service, accept the default settings for the HTTP transport configuration, message level security configuration, and default SOAP Body Type operation selection algorithm. When the Create a Proxy Service - Summary page is displayed, you must review the summary of configuration settings before to registering the proxy service.

Figure 5-3 Create a Proxy Service– Summary of LoanGateway3

Create a Proxy Service– Summary of LoanGateway3

When you complete this task, the MortgageBroker/ProxyService folder must contain the following proxy services you created in this tutorial and the previous tutorials:

Configure the LoanGateway3 Proxy Service

The proxy service is implemented in ALSB as a message flow. ALSB message flows define the implementation of proxy services using request and response pipelines. Message flows can include zero or more of the following pipeline pairs:

Each pipeline can include one or more stages, which in turn include actions.

To configure the behavior of the LoanGateway3 proxy service, you must complete the following tasks:

Create a Pipeline Pair

  1. In the ALSB Console navigation pane, select the 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.

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

  3. Click the LoanGateway3 node, then select Add Pipeline Pair.
    4. Figure 5-4 Add Pipeline Pair Node


    Add Pipeline Pair Node

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

Figure 5-5 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 icon, then select Add Stage.
  2. Click Stage1, then select Edit Name and Comments.
  3. Enter validate loan application and click Save.

    4. The page is displayed as shown in Figure 5-6.

    Figure 5-6 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 Edit Stage. The Edit Stage Configuration page is displayed.
  2. Select Add an Action, then select Message ProcessingArrow symbolValidate from the drop-down list. The Validate action is added to the stage.
    3. Figure 5-7 Add Validate Action


    Add Validate Action

  3. In the Validate statement, click the <XPath> link to edit the XPath expression. The XPath Expression Editor is displayed.
    4. Figure 5-8 XPath Expression Editor


    XPath Expression Editor

  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 application document is displayed.

      Figure 5-9 Variable Structures Pane

      Variable Structures Pane

    3. Drag-and-drop icon associated with the loanRequest element, in the XQuery Expression text box. The XQuery expression is written in the text box.

      4. ./exam:processLoanApp/loanRequest

      Figure 5-10 XQuery Expression Editor


      XQuery Expression Editor

      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 in 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. Click <resource> and select WSDL from the list. The Select a WSDL page is displayed.

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

    Figure 5-11 WSDL Resource Selection


    WSDL Resource Selection

  10. In the Select a WSDL page, select the normalLoan WSDL resource.

    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. Figure 5-12 WSDL Definitions Pane


      WSDL Definitions Pane

    2. Click Submit to complete the selection.
  11. Select the Raise Error on validation failure option. The Validate action will be displayed as shown in Figure 5-13.
  12. Click Save to save the configuration.
    13. Figure 5-13 Configured Message Validate Action


    Configured Message Validate Action

Note: Message validation must be done as early as possible in a message flow. This prevents unnecessary processing of invalid message content. By raising an exception, further message processing is stopped and an error 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, message processing is more modular since the configured validate actions logically break down the message flow. If multiple validations are performed on a message, the validate action is logically expanded.
To Configure the Stage Error Handler

You must perform the following tasks to configure the Stage Error Handler:

  1. Configure error code checking 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 clause of the If...Then... action of the stage. This action replaces 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 (as in 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).
Add Stage Error Handler Element
  1. Click validate loan application, then select Add Stage Error Handler. The Edit Error Handler page is displayed.
  2. Click Error Handler, then select Add Stage. The stage1 node is displayed.
    3. Figure 5-14 Add Stage Error Handler


    Add Stage Error Handler

  3. Click stage1 and select Edit Name and Comments as shown in Figure 5-15.
    4. Figure 5-15 Edit Stage Error Handler


    Edit Stage Error Handler

  4. Change the stage name to Reply, then click Save.
    5. Figure 5-16 Edit Name and Comments of Stage


    Edit Name and Comments of Stage

    The Edit Stage Configuration page is displayed as shown in Figure 5-17.

    Figure 5-17 Edit Error Handler


    Edit Error Handler

  5. To edit the stage, click Reply, then select Edit Stage.
Add an If...Then… action to the Stage Error Handler
  1. Select Add an Action, then select Flow ControlArrow symbol If...Then…
    2. Figure 5-18 Add Flow Control Action


    Add Flow Control Action

    The If...Then action is added to the Reply stage.

  2. Click the If...Then… action <Condition> link to specify the expression that needs to be validated. The Xquery Condition Editor page is displayed.
    1. Select the Builder pane.
    2. In the Comparison Expression pane within the Expression Builder pane, enter $fault/ctx:errorCode in the Operand textbox.
      3. Figure 5-19 Expression Builder Pane


      Expression Builder Pane

    3. Select the = Operator from the drop-down list.
    4. Enter "BEA-382505" (including double quotes) in the Value pane.
    5. Select the radio button for the And conjunction.

      6. The Expression Builder pane is displayed as in Figure 5-20:

      Figure 5-20 Conditions in the Expression Builder


      Conditions in the Expression Builder

    6. Click Add to add expression to the Expressions textbox.

      7. The following expression is displayed in the textbox:

      Figure 5-21 Expressions Textbox


      Expressions Textbox

  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. To add a Replace select Add an Action within the Then... portion of the If...Then action.
    2. Note: When adding multiple actions 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.
  2. Click to view available options icon, select Message ProcessingArrow symbolReplace.
    3. Figure 5-22 Add a Replace Action


    Add a Replace Action

    The replace statement will be displayed as shown in Figure 5-23.

    Figure 5-23 Replace Statement


    Replace Statement

  3. In the Replace statement, click the <XPath> link to edit the XPath expression. The XPath Expression Editor page is displayed.
  4. In the Variable Structures pane, select body from the Select Structure drop-down list.

    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 Node icon 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
      Figure 5-24 Replace Statement XPath Expression


      Replace Statement XPath Expression

  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.
  8. In the XQuery Text pane, enter:
    $fault/ctx:reason/text()
    9. Figure 5-25 Replace Statement XQuery Expression


    Replace Statement XQuery Expression

  9. Click Validate, then Save.
  10. Select Replace node contents option. You need not replace the entire node.

    11. The Replace action is displayed as shown in Figure 5-26.

    Figure 5-26 Add Error Handler Using Replace Action


    Add Error Handler Using Replace Action

Add a Report Action to Report the Error

Next, you must 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 icon and select Add an ActionArrow symbolReportingArrow symbolReport. The report action is added to the page.
    2. Figure 5-27 Adding a Report Action


    Adding a Report Action

    The Stage Error Handler is displayed as shown in Figure 5-28.

    Figure 5-28 Stage Error Handler with Report Action


    Stage Error Handler with Report Action

  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 associated with the $body element and drag-and-drop it on the XQuery Expression text box.

      2. The $body XQuery expression is typed 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 in the XQuery Expression text box.
    2. Click Validate, then Save.

      3. The Edit Stage Configuration page is displayed.

  5. In the key-value pair table, select the Add a key link.
    1. Enter a name for the key. In this case, enter errorCode.
      2. Figure 5-29 Report Action Expression Key


      Report Action Expression Key

    2. In the key value field, click <XPath> link. The XPath Expression Editor is displayed.
  6. In the Variable Structures pane, select fault from the Select Structure drop-down list.
    7. Figure 5-30 Fault Variable Structure


    Fault Variable Structure

    1. Drag-and-drop the Node icon associated with the errorCode in the XPath Expression text box.

      2. Type ./ctx:errorCode expression in the text box.

      Figure 5-31 Report Action ErrorCode Expression


      Report Action ErrorCode Expression

      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.

The Report action must be displayed as shown in Figure 5-32.

Figure 5-32 Configured Report Action

Configured Report Action

The Edit Stage Configuration page is displayed as shown in Figure 5-33.

Figure 5-33 Request Actions for LoanGateway3 Proxy Service

Request Actions for LoanGateway3 Proxy Service

Add an Else Action to the Stage Error Handler
  1. Click the If...Then… icon.
  2. Select Add else Condition to add an Else action to the stage error handler.
Add a Replace Action Within the Else Action
  1. Select Add an Action > Message ProcessingArrow symbolReplace.
  2. Execute step 3 to step 10 in the Add a Replace Action to the Stage Error Handler section.

    3. The Edit Stage Configuration page is displayed as shown in Figure 5-34.

    Figure 5-34 Edit Stage Configuration Page - Else Replace Action


    Edit Stage Configuration Page - Else Replace Action

Add a Log Action Within the Else Action
  1. Click the Replace icon within the Else action.
  2. Select Add an Action > ReportingArrow symbolLog.
    3. Figure 5-35 Reporting Log Action


    Reporting Log Action

    The reply error handler Else action is displayed as shown in Figure 5-35. Add the Log action

    Figure 5-36 Reporting Log Action
  3. Click the <Expression> link to display the XQuery Expression Editor page. Enter $fault/ctx:reason/text() in the XQuery Text page.
  4. Click Validate and Save to validate and save the expression and return to the Edit Stage Configuration page.
  5. Enter Other than validation error, in the With Annotation text box.
  6. Select Error from the At Severity Level drop-down list.

The completed Else condition must be displayed as shown in Figure 5-37.

Figure 5-37 LoanGateway3 Proxy Service Request Else Actions

LoanGateway3 Proxy Service Request Else Actions

Add a Reply Action to Reply with a Failure Code
  1. Click the Report icon under the If...Then action.
  2. Select Add an ActionArrow symbolFlow ControlArrow symbolReply. The reply action is added to the page.
  3. Select With Failure option. The Report Reply action is displayed as shown in Figure 5-38.
    4. Figure 5-38 Report Reply Action with Failure Code


    Report Reply Action with Failure Code

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

Add a Default Routing Case

You must now add a Route Node to the Pipeline pair and configure it to enable default routing to the NormalLoan business service.

Configure the Route Node
  1. Click PipelinePairNode1, then select Add Route.
    2. Figure 5-39 Pipeline Route Node


    Pipeline Route Node

    The Edit Message Flow page is displayed as shown in Figure 5-40.

    Figure 5-40 Edit Message Flow Page - Pipeline Route Node


    Edit Message Flow Page - Pipeline Route Node

  2. Click RouteNode1, then select Edit Route. The Edit Stage Configuration page is displayed.
  3. Click Add an Action, then select CommunicationArrow symbolRouting.
    4. Figure 5-41 RouteNode1 Communication Routing Action


    RouteNode1 Communication Routing Action

    The Route to action is displayed in the Edit Stage Configuration page as shown Figure 5-42.

    Figure 5-42 Route to Statement


    Route to Statement

  4. In the route statement, click the <Service> link to define the service to which you want to route messages. The Select Service page is displayed as shown in Figure 5-43.
    5. Figure 5-43 Route to Statement Service


    Route to Statement Service

    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. Click Save.

    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 page is displayed as shown in Figure 5-44.

    Figure 5-44 LoanGateway3 Proxy Service Message Flow


    LoanGateway3 Proxy Service Message Flow

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

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

    Figure 5-45 Map of Message Flow for LoanGateway3 Proxy Service

    Map of Message Flow for LoanGateway3 Proxy Service

To Test the Loan Application Routing Configuration Using Test Console

Now that you have configured ALSB to work with the client and the target business services, you must test the configuration. To test the routing configuration, you must change the value of the Loan duration (in years) field in the build.xml file. Then you must test the routing logic by verifying whether the proxy service behavior changes for different loan values. If the loan value entered is a non integer, an exception must be triggered and an error message displayed in the Notes field of the message. If the loan value entered is an integer, the message must be routed to the NormalLoan business service. The message returned in the command window indicates whether a validation exception occurred or the message was routed to the appropriate business service.

To test the loan application using the test console, you must first deploy the client jars in the WLS console. For more information see, Load the Client Application.

To test the Validation of the Loan Application by LoanGateway3

Scenario One
  1. Start WLS Server in ServiceBusTutorial Domain
  2. In ALSB Console activate the current session.
  3. Click on Resource Browser in the left panel to navigate to Summary of Proxy Services page.Click on Launch Test Console icon in Actions column for LoanGateway3 to launch the test console (see Figure 3-40).
  4. Replace the default payload in loanRequest field with the following code:
    5. <loanRequest xmlns:java="java:normal.client">
        <!--Optional:-->
        <java:Name>Smith</java:Name>
        <!--Optional:-->
        <java:SSN>1234567</java:SSN>
        <!--Optional:-->
        <java:Rate>5</java:Rate>
        <!--Optional:-->
        <java:Amount>900000000</java:Amount>
        <!--Optional:-->
        <java:NumOfYear>10.1</java:NumOfYear>
        <!--Optional:-->
        <java:Notes>Large Loan Processing</java:Notes>
    </loanRequest>

Accept other default settings and click Execute. The response as in Figure 5-46.

Figure 5-46 Response from Error Handler

Response from Error Handler

This response message indicates that a validation exception occurred because the loan duration specified was not an integer.

Scenario Two
  1. Start WLS Server in ServiceBusTutorial Domain
  2. In ALSB Console activate the current session.
  3. Click on Resource Browser in the left panel to navigate to Summary of Proxy Services page.Click on Launch Test Console icon in Actions column for LoanGateway1 to launch the test console (see Figure 3-40).
  4. Replace the default payload in loanRequest field with the following code:
    5. <loanRequest xmlns:java="java:normal.client">
        <!--Optional:-->
        <java:Name>Smith</java:Name>
        <!--Optional:-->
        <java:SSN>1234567</java:SSN>
        <!--Optional:-->
        <java:Rate>4</java:Rate>
        <!--Optional:-->
        <java:Amount>300000000</java:Amount>
        <!--Optional:-->
        <java:NumOfYear>10</java:NumOfYear>
        <!--Optional:-->
        <java:Notes>Normal Loan</java:Notes>
    </loanRequest>

Accept other default settings and click Execute. The response as in

Figure 5-47 Response From Normal Loan Processor

Response From Normal Loan Processor

The response message indicates that the NormalLoan business service processed the loan application because the loan duration value was 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 ALSB Console.

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

Reporting

ALSB includes a JMS Reporting Provider for message reporting. The Reporting module in the ALSB 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 ALSB 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

ALSB can monitor and collect run-time information for both systems operations and business auditing purposes. ALSB 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