Retail Banking Sample

This page walks you through the development of a complete sample application. It includes the following sections:

Sample Scenario

This sample is about account opening process of a normal retail bank. We are going to develop a simple application to model that scenario using WSO2 Developer Studio. Here is a simplified description of a common retail banking process. When a potential customer walks into a bank branch to open an account, the first thing the bank does is establish the person's identity. Once the person's identity is established, the branch staff perform a query against a customer database to see if the person is an existing customer. Legacy banking systems are based on account numbers, but banks today are focused on getting a single view of the customer, which requires the generation of customer numbers. It's therefore important to ensure that a customer is not assigned more than one customer number by mistake. If the person is a prior customer, the customer number is retrieved from the customer database. If not, a fresh customer number is generated. This customer number is then associated with the new account number of the account that is to be opened. Accounts are still held on thirty year old mainframe systems, which alone can generate fresh account numbers. A debit card is normally issued with the first cheque or savings account that is opened. However, not all branches have the equipment to generate and issue them on the spot. Hence cards are issued centrally and sent to the customers. If this is an existing customer, the new account is linked to their existing debit card on the spot. Most branches are unable to provide secure PIN printing facilities, so this too is centralised.

The mainframe can only send and receive messages over a message queue, and uses a COBOL copybook format to structure its data inputs and outputs. The card system is an off-the-shelf product that supports web services, but these conform to a vendor-provided schema that is different from the rest of the bank's systems.

Design the Solution

There is only one process (Open Account) that needs to be initiated, and this consists of a number of steps, which would be natural points at which services are invoked. The functions performed at these various steps are:

1. Check if existing customer: This is the first thing that needs to be done, because the subsequent processing for prior and new customers is different. This query is to be made against the customer database, which requires a Data Service in front of it to turn it into a true service.
2. Create customer: This service is only invoked if the customer is new. This is once again a function that needs to be implemented against the customer database, so another Data Service is required to turn it into a true service.
3. Create account: This needs to be done regardless of whether this is an existing or new customer. Accounts are maintained on the mainframe, and account creation can only be invoked by passing in a special message formatted as a COBOL copybook sent over MQ. A Broker is required to act as an adapter to the MQ interface as well as a transformer to present the COBOL copybook syntax as a more open XML document.
4. Link card to account: This is done for both existing and new customers, but invoked at different points in the process.
5. Issue card: This is for new customers who don't already possess a debit card. The actual processing occurs on a card system that exposes a web service. However, the data elements of this service don't conform to the data model of the retail bank. A Broker is again required to transform the XML documents supported by the card system to equivalent ones that conform to the bank's data model.

The following diagram shows how these components hang together.

Prerequisites

Now we are going to implement the solution using WSO2 Developer Studio. Before start implementing, you will need following third party tools and WSO2 Products.

Third Party Tools

• MySQL 5.x Server (download from http://www.mysql.com/)
• ActiveMQ 5.x (download from http://www.apache.org/)

WSO2 Products

This sample refers to the following products and their versions:

• WSO2 Enterprise Service Bus 4.6.0 (download from http://wso2.com/products/enterprise-service-bus)
• WSO2 Application Server 5.0.1 (download from http://wso2.com/products/application-server)
• WSO2 Business Process Server 3.0.0 (download from http://wso2.com/products/business-process-server)
• WSO2 Data Services Server 3.0.1 (download from http://wso2.com/products/data-services-server)

Necessary Software Libraries and Drivers

• ActiveMQ
  • activemq-core-5.4.2.jar
  • geronimo-j2ee-management_1.1_spec-1.0.1.jar
  • geronimo-jms_1.1_spec-1.1.1.jar
• MySQL JDBC Driver
  • mysql-connector-java-5.1.13-bin.jar

Install and configure the third party libraries and drivers. I assume you already have WSO2 Developer Studio installed Eclipse version with you. If you have not installed WSO2 Developer Studio yet, please refer the Installation Guide for more information on how to install WSO2 Developer Studio in your Eclipse instance.

Download Source

You can check-out the latest up-to-date version from here

Try the Sample with WSO2 Developer Studio

Getting Ready

Following is the logical solution diagram that we are going to use while implementing the solution. This diagram shows how each and every WSO2 Product incorparate to come up with end to end solution.



In this sample, we are going to create seven projects for each and every component.

• MainframePojoService - Model account creation mainframe
• CardAxis2Service - Model Card Issueing Service
• CustomerDS - Data Service that handles Customer ID Creation
• SynapseConfigs - Contains all the ESB configurations
• RegistryResources - Contains XSLT files, WSDL files etc
• AccountOpeningProcess - BPEL process
• BankingSample - Carbon Application

Install and configure MySQL

Follow the default instructions provided by MySQL.comto install MySQL server (the default procedure is typically unpack, install, and run). It is recommended that MySQL be set up to run automatically on system startup.

Install and configure Apache ActiveMQ

Follow the default instructions provided by http://activemq.apache.org/ to install ActiveMQ server (the default procedure is typically unpack, install, and run). To start activemq, go to bin folder of ACTIVEMQ_HOME and run the command activemq startin the command line.

Install and Configure WSO2 Servers

All you need to do to install a WSO2 server is to unpack the downloaded archive. As a reference point, we will use the following logical directory names to refer to the installation folders of each WSO2 server:

• WSO2 Application Server - AS_HOME
• WSO2 Data Services Server - DSS_HOME
• WSO2 ESB - ESB_HOME
• WSO2 Business Process Server - BPS_HOME

(We will refer to the installation directory of any generic server as CARBON_HOME.)

If you are running all the required WSO2 products on the same machine as these instructions assume, you will need to avoid port conflict, because all WSO2 server products listen on ports 9763 (HTTP) and 9443 (HTTPS) by default. This port conflict can be avoided by changing an "offset" parameter in the servers' main configuration file (the file carbon.xml found in $CARBON_HOME/repository/conf). We set offset for different carbon serversas follows.

• WSO2 App Server - 0 (App Server will now listen on 9764 and 9444)
• WSO2 ESB - 1 (ESB will now listen on 9764 and 9444)
• WSO2 BPS - 2 (Business Process Server will now listen on 9765 and 9445)
• WSO2 DSS - 6 (Data Services Server will now listen on 9769 and 9449)

Let's configure following WSO2 Servers.

Configure WSO2 Data Services Server

Avoid port conflicts

Edit $DSS_HOME/repository/conf/carbon.xmlto set the offset parameter. Set the value to

  <
  Offset
  >
  6
  </
  Offset
  >

Enable database access

Copy the MySQL driver library (mysql-connector-java-5.1.13-bin.jar) to ($DSS_HOME/repository/components/lib).

Configure WSO2 Application Server

Avoid port conflicts

Leave the offset parameter of the $AS_HOME/repository/conf/carbon.xmlas it is. That is keep the offset parameter to 0.

  <
  Offset
  >
  0
  </
  Offset
  >

Enable the Application Server to talk over a message queue

Copy the ActiveMQ libraries (activemq-core-5.4.2.jar, geronimo-j2ee-management_1.1_spec-1.0.1.jar and geronimo-jms_1.1_spec-1.1.1.jar) to the App Server ($AS_HOME/repository/components/lib).

Enable the JMS transport on the App Server (this can also be done via the admin console, but this will not be described here)

This only requires un-commenting two sections in the App Server's configuration file. To enable JMS transport, we are going to edit axis2.xml that resides in $AS_HOME/repository/conf/axis2. Look for the two sections that begin with [transportReceiver name="jms"] and [transportSender name="jms"] and uncomment the XML. After un-commenting, your axis2.xmlwill be as below.

  <
  transportReceiver
   
  name
  =
  "jms"
   
  class
  =
  "org.apache.axis2.transport.jms.JMSListener"
  >
  /
  transportReceiver
  >

AND

  <
  transportSender
   
  name
  =
  "jms"
   
  class
  =
  "org.apache.axis2.transport.jms.JMSSender"
  />

Ensure that you are uncommenting the section corresponding to ActiveMQand not Qpid.

Configure WSO2 ESB

Avoid port conflicts

Edit $ESB_HOME/repository/conf/carbon.xmlto set the offset parameter. Set the value to

  <
  Offset
  >
  1
  </
  Offset
  >

Enable the ESB to talk over a message queue

Copy the ActiveMQ libraries (activemq-core-5.4.2.jar, geronimo-j2ee-management_1.1_spec-1.0.1.jar and geronimo-jms_1.1_spec-1.1.1.jar) to the App Server ($ESB_HOME/repository/components/lib).

Enable the JMS transport on the ESB

Follow the same step that we did for App Server in the previous step.

Configure WSO2 Business Process Server

Avoid port conflicts

Edit $BPS_HOME/repository/conf/carbon.xmlto set the offset parameter. Set the value to

  <
  Offset
  >
  2
  </
  Offset
  >

Creating Mock Objects to represent Legacy Systems

There are three legacy systems in this environment which you will need to create in your environment:

1. The Customer Database
2. The Mainframe holding account data and performing account-related functions
3. The Cards System holding card data and performing card-related functions

The integration solution using WSO2 middleware components can then be run against these mock objects representing legacy systems.

Set up the Customer Database using MySQL

Create a database within MySQL called CustomersDatabase. Against this database, run the scripts CreateTables and getCustomer.sql from $DOWNLOAD_HOME/banking-sample/ds/sql This script will create the Customertable and a stored procedure to retrieve and create customer data.

Set up Customer Data Service

Open the Developer Studio Dashboard by clicking on Open Dashboard option under top menu item Developer Studio.



To create a Data Service, click on Data Service Project under Data Services Server category.



Select Import Data Service option and click Next.



Browse for the Data Services Descriptor file, CustomerDS.dbs under $DOWNLOAD_HOME/banking-sample/ds/dbs and click Finish.



Now you will see that the Data Service Project has been created in the workspace and make sure to change the User Name and Password according to your MySQL credentials.

Set up Mock Objects representing the Mainframe and Cards System

To create the mock objects, go to Eclipse instance which you have WSO2 Developer Studio installed.

1. Modeling Account System

Open the Developer Studio Dashboard by clicking on Open Dashboard option under top menu item Developer Studio.

To create the Pojo Service, select Axis2 Service Project from the Dashboard.

From the Axis2 Service Creation Wizard, select Create New Axis2 Service and click Next.

Fill the following information for Project Name, Package Name and Class Name.

• Project Name - MainframePojoService
• Package Name - wso2.hcc
• Class Name - MainframePojoService

After giving necessary details, click Finish. Now you can see that the Axis2 Servicehas been created in the workspace.

Now go and copy the two source files MainframePojoService.java and Account.java from $DOWNLOAD_HOME/banking-sample/appserver/AccountService/src/wso2/hcc and paste in to wso2.hcc package in the MainframePojoService project.

Now we want to enable, JMS transport since this service will communicate via JMS transport. To enable this, we need to add following block to services.xml under /src/main/resources/META-INF.

  <
  transports
  >
    <
  transport
  >jms</
  transport
  >
</
  transports
  >

Now your services.xml will look like below.

Now we are done with modeling Account Service.

2. Modeling Card System

Now we want to create the Card System. This will be another Apache Axis2 Service Project. Select Axis2 Service Project from WSO2 Developer Studio Dashboard as you done in the previous step.

Select Create New Axis2 Service option from the wizard and give following details to Project Name, Package Name and Class Name.

• Project Name - CardAxis2Service
• Package Name - org.wso2.sample
• Class Name - CardAxis2Service

Now you will see the CardAxis2Service has been created in the workspace. Now copy the original sources CardAxis2Service.java, Customer.java and Card.java from $DOWNLOAD_HOME/banking-sample/appserver/CardApplication/src/main/java/org/wso2/sample and paste in to org.wso2.sample package of CardAxis2Service project. Now we are done with creating two mock services and we are ready to deploy those two services in to WSO2 Application Server.

Before deploying the services to Application Server, we need to create a Carbon Application Project to group the two created axis2 services.

3. Create a Carbon Application Project to group mock objects

Open WSO2 Developer Studio Dashboard again and select Carbon Application Project under Destribution category.

Give a name to the Carbon Application Project and select both services that we created.

Now you will see that the Carbon Application Project has been created in the workspace with the name you have specified.

4. Deploy the Carbon Application Project in to WSO2 App Server

Now we are going to deploy the created Carbon Application Project in to WSO2 Application Server. Before starting the WSO2 App Server, make sure Apache ActiveMQ is up and running.

In this section, we are going to start the WSO2 App Service inside Eclipse. Follow the steps in Deploy C-App to a running Server inside Eclipse.

Once you add the server successfully, start the server and add BankingSample Carbon Application to the running server.

Wait till the application get deployed successfully to the server. Once the deployement is completed, you will see following logs in the Eclipse Console.

[2012-04-20 10:05:57,818] INFO {org.wso2.carbon.application.deployer.internal.ApplicationManager} - Deploying Carbon Application : BankingSample.car...

[2012-04-20 10:05:58,059] INFO {org.wso2.carbon.application.deployer.internal.ApplicationManager} - Successfully Deployed Carbon Application : BankingSample {super-tenant}

[2012-04-20 10:06:07,881] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 service: MainframePojoService {super-tenant}

[2012-04-20 10:06:10,517] INFO {org.apache.axis2.transport.jms.ServiceTaskManager} - Task manager for service : MainframePojoService [re-]initialized

[2012-04-20 10:06:11,528] INFO {org.apache.axis2.transport.jms.JMSListener} - Started to listen on destination : MainframePojoService of type queue for service MainframePojoService

[2012-04-20 10:06:11,570] INFO {org.apache.axis2.deployment.DeploymentEngine} - Deploying Web service: MainframePojoService-1.0.0.aar - file:/media/dev/CS-Resources/2.0.0/review-02-04-2012/servers/wso2as-4.1.2/repository/deployment/server/axis2services/MainframePojoService-1.0.0.aar

[2012-04-20 10:06:11,605] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 service: CardAxis2Service {super-tenant}

[2012-04-20 10:06:12,224] INFO {org.apache.axis2.transport.jms.ServiceTaskManager} - Task manager for service : CardAxis2Service [re-]initialized

[2012-04-20 10:06:13,233] INFO {org.apache.axis2.transport.jms.JMSListener} - Started to listen on destination : CardAxis2Service of type queue for service CardAxis2Service

[2012-04-20 10:06:13,234] INFO {org.apache.axis2.deployment.DeploymentEngine} - Deploying Web service: CardAxis2Service-1.0.0.aar - file:/media/dev/CS-Resources/2.0.0/review-02-04-2012/servers/wso2as-4.1.2/repository/deployment/server/axis2services/CardAxis2Service-1.0.0.aar

As deplayed in the console log, you can see that the MainframePojoService and CardAxis2Service have been deployed in to WSO2 Application Server. Go to management console in the browser and check for Deployed Services.

If you click on the MainframePojoService and check for Endpoints section, you will see a JMS endpoint. This is because we have specified transport for this service as JMS.

If you check on other service CardAxis2Service, you will see both HTTP and JMS transport endpoints are available.

Now we are going to create proxy services to abstract above two services.

Create Proxy Services to abstract the Mainframe

1. Create an "address endpoint" for the mainframe on the ESB

Open WSO2 Developer Studio Dashboard and select Endpoint.

Select Import Endpoint option and click Next. Browse for the MainFrameEP.xml from $DOWNLOAD_HOME/banking-sample/esb/synapse-configs/default/endpoints folder.

All your ESB configurations should be saved in a project type called ESB Config Project. Since our workspace does not have any created ESB Config Projects, we need to create an ESB Config Projects in order to save our endpoint. To create ESB Config Project, click on Create New Project link.

Give a name to ESB Config Project and click Finish.

Now you will see that the created ESB Project is set for Save endpoint in: option.

Now you will see that the endpoint has been created inside the ESB Project that you have created.

Once you double click on the MainFrameEP node, you will see that the Properties view gets focused. You need to update the URI field with the correct JMS URI that appears in the App Server after deploying the two mock services.

Save the configuration and now we are done with the address endpoint.

2. Create a service on the ESB that will act as a proxy to the mainframe

Right-click on the ESB Configuration Project, then select New ->Proxy Service. Choose the second radio button Import Proxy Service and click Next. Browse to $DOWNLOAD_HOME/banking-sample/esb/synapse-configs/default/proxy-services and select AccountServiceProxy.xml and click Finish.

Make sure the correct endpoint is being referenced. Expand AccountService -> InSequence -> Anonymous -> Send and click on the Endpoint below it. In the Properties window below, select the row with the Endpoint on it, then click on the button containing ellipsis (...).

In the Resource Key Editor that pops up, select workspace.

Expand Carbon Application Endpoints and ESB Configuration Project, then select MainframeEP.

Save the proxy service and now we complete the proxy service that wrap the AccountService mock object.

Create Proxy Services to abstract the Cards System

1. Create an "address endpoint" for the CardService on the ESB

In the same manner, you create the MainFrameEP, create the cardServiceEP. Resource file for cardServiceEP can be found at $DOWNLOAD_HOME/banking-sample/esb/synapse-configs/default/endpoints

Once the endpoint has been created, make sure that the correct URI has been specified.

2. Create a service on the ESB that will act as a proxy to the Cards system

Right click on the ESB Configuration Project and select New->Proxy Service. Select Create New Proxy Service option and click Next.

Give the name as CardService and select Custom Proxy from Proxy Service Type and click Finish.

Now you will find a basic template for a custom proxy has been created in the workspace. Now we have to configure it according to our scenario.

Once the CardService has been opened in Design view, you will see that there are five top level nodes as WSDL, InSequence, Endpoint, OutSequence and FaultSequence.

Select WSDL, then in the Properties window below, select the row corresponding to WSDL Type, and change its value from None to Specify source URI and hit Enter. Now a new row will open up with the name WSDL URL.

In this field, we specify the actual file location of the WSDL file as file URI. Actual file CardService.wsdl can be found at $DOWNLOAD_HOME/banking-sample/appserver.Your file URI will be something as below. file:///$DOWNLOAD_HOME/banking-sample/appserver/CardService.wsdl .

Select InSequence -> Anonymous, right-click on Anonymous and select New child -> Transform -> XSLT.

Click on the newly-created XSLT node, and in the Properties window below, enter the value conf:/transform/transform.xslt against Schema Key.

This means that the transformation style-sheet is to be found in the local registry. But we don’t have it there yet. The XSL style-sheet used for transformation (transform.xslt), now needs to be imported into the local registry.

We will create the Registry Resource in the next step. Before that , we will complete the proxy service assuming that the Registry Resource is being there.

You can create before and after logging elements under CardService -> InSequence -> Anonymous by right-clicking on Anonymous and selecting New Child -> Core -> Log. Move one of them above XSLT and the other below. For each of them, create a Property by right-clicking on the Log element and selecting New Child -> Log Property.

Add a Send mediator to point to cardServiceEP that we have created earlier.

To add Send mediator, right click on Anonymous and select New Child -> Core -> Send.

Right click on the Send mediator and select New Child -> Endpoint Reference (Registry).

Now go to Properties view and open Resource Key Editor and select workspace link.

Choose cardServiceEP and click OK.

Ensure that in the Design window, CardService -> OutSequence -> Anonymous has an element called Send under it.

Now your CardService will look like this.

Now we have successfully completed creating the proxy service for the card system.

Create Registry Resource for transform.xslt

Click on WSO2 Developer Studio Dashboard and select Registry Resource under Governance Registry category.

Select Import from file system option and click Next.

Select Browse file.. button and browse for the transform.xslt file at $DOWNLOAD_HOME/banking-sample/esb/cardService.

Set Registry path to deploy as /_system/config/transform. Note that this is the same path we set when creating CardService

With WSO2 Developer Studio, we create all the Registry Resources in a project type called Registry Resources Project. If your workspace has already created Registry Resources Projects, you can point one of them to save your registry resource.

If you do not have created Registry Resources Project, you will have to create a Registry Resource Project in order to create the Registry Resource. To create a Registry Resource Project, click on the link Create New Project....

Give necessary information for the Registry Resource Project and click Finish.

Now you can see that the created Registry Resources Project is being set for Save resource in: field. Once you fill all the information, click Finish.

Now you will see that the new Registry Resources Project has been created in the workspace.

Now we have successfully completed the two proxy services for the mock services.

Create the Process to co-ordinate all the above Services

Ideally, all WSDL files referenced by the Process Server should also be hosted on the global repository that is mounted on the BPEL server in order to appear like local resources. i.e., the decoupling model should follow the process described in the creation of the Card System Proxy. However, in the interests of simplicity, we will just import all the WSDL files directly and concentrate on the business process.

To create a BPEL Process, open WSO2 Developer Studio Dashboard, and select BPEL Workflow under Business Process Server category.

Select Create New BPEL Workflow and click Next.

Give Project Name and Process Name as AccountOpeningProcess and leave the other fields as default values. Then click Finish.

Now you will see that new BPEL Workflow has been created in the workspace.

Note that this is just a template BPEL. We need to create the process file according to our scenario. If you are familiar with BPEL, you can use the graphical editor to drag and drop necessary elements from the palette.

For this scenario, you can find already developed BPEL file and other WSDL files from $DOWNLOAD_HOME/banking-sample/bps/AccountOpeningProcess.

Copy all the files from that location and paste in to AccountOpeningProcess project.

Now we have successfully completed all the parts that we need to try the scenario.

Deploy the SOA Integration Solution

Now we will create a Carbon Application Archive from the Banking Sample Carbon Application Project.

Open the pom.xml under Banking Sample. If it is already opened, you will have to refresh the file in order to view all the artifacts in the design view.

Select all the artifacts by clicking Select All button. Now we want to change the server role of the Registry Resource from Governance Registry to Enterprise Service Bus since we need to deploy the XSLT file in to local registry of the WSO2 ESB.

Now we are ready to create the CAR file from the BankingSample C-App project.

To create the CAR file, click on the Create Archive button at the right hand corner of the design view of the pom.xml. You can achieve the same option by right click on the BankingSample C-App project and select Export Carbon Application Project.

Specify the location you want to save the CAR file. Now you will see that the BankingSample.car file has been created in the given location and you can deploy this CAR file in to WSO2 Servers.

Testing the Working Solution

1. Start apache activeMQ if it is not already started
2. Start WSO2 App Server it is not already started
3. Start WSO2 ESB, WSO2 DSS and WSO2 BPS

To open WSO2 Servers, go to $CARBON_HOME/bin and run the command wso2server.sh or wso2server.bat. Once all the servers get started servers will run on following ports.

• WSO2 App Server - 9443
• WSO2 ESB - 9444
• WSO2 BPS - 9445
• WSO2 DSS - 9449

I assume mock services are already being deployed in to WSO2 App Server. Deploy the CAR file in to WSO2 DSS, then to WSO2 ESB and finally to WSO2 BPS. You can deploy Carbon Application from the management console of each and every server. Go to Manage -> Applications -> Add.



Once you click this link, you will be prompted to select the CARfile you have saved to your file system. Upload it, then watch the console for messages that the CAR file has been deployed and the appropriate services have also been deployed.

You will find following artifacts in different servers once you deploy the CAR file in to all the servers. The application BankingSample should be listed in all the servers as well.

Let's test whole banking scenario.

In the Admin console of the BPS, click on Business Processes -> Processes, then on the displayed list of processes, click on AccountOpeningProcess.

On the right hand side of the screen, under WSDL details, you will find a Create Instance link.

Click this link. A new tab will open up displaying two windows for the request and response messages. The request message has been formatted for you and you only have to enter values into the appropriate placeholders.

1. Test the account opening process with a new customer

Enter a random integer value for nid and a string for name. Also enter the string CURRENT for accountType. Click Send. The response should be displayed in the other window with four fields including a card number.

2. Test the account opening process with an existing customer

Click Send again without changing any of the values in the request. The response displayed in the other window now only has two fields. One of them is a new account number. Significantly, there should be no field for card number because existing customers already have debit cards.