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 the 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.8.0 (download from http://wso2.com/products/enterprise-service-bus)
• WSO2 Application Server 5.2.0 (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.1.0 (download from http://wso2.com/products/data-services-server)

Necessary Software Libraries and Drivers

• ActiveMQ
  • activemq-core-5.4.2.jar (in ActiveMQ version 5.8.0 and above, activemq-core-5.8.0.jar has been split into activemq-broker-5.8.0.jar and activemq-client-5.8.0.jar)
  • geronimo-j2ee-management_1.1_spec-1.0.1.jar
  • geronimo-jms_1.1_spec-1.1.1.jar 
  • (for ActiveMQ 5.8.0 and above, you will need hawtbuf-1.9.jar too)
• 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 Issuing 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.com to 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 start in the command line.

Install and Configure WSO2 Servers

To install a WSO2 server, you 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 servers as follows.

• WSO2 App Server - 0 (App Server will now listen on 9763 and 9443)
• 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.xml to 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.xml as it is (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

Uncomment the following two sections in the App Server's configuration file. To enable JMS transport, we are going to edit $AS_HOME/repository/conf/axis2/axis2.xml. Look for the two sections that begin with [transportReceiver name="jms"] and [transportSender name="jms"] and uncomment the XML. After un-commenting, your axis2.xm lwill 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 ActiveMQ and not Qpid.

Configure WSO2 ESB

Avoid port conflicts

Edit $ESB_HOME/repository/conf/carbon.xml to 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 ESB ($ESB_HOME/repository/components/lib).

For more details in configuring ESB with ActiveMQ, refer the page Configure with ActiveMQ. 

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.xml to 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 Customer table and a stored procedure to retrieve and create customer data.

Set up Customer Data Service

Under the Developer Studio top menu item, click Open Dashboard to open the Developer Studio Dashboard.  

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

Select Import Data Service 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. 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

To create the Pojo Service, click Axis2 Service Project from the Developer Studio 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 the necessary details, click Finish. Now you can see that the Axis2 Service has been created in the workspace.

Now copy the two source files MainframePojoService.java and Account.java from $DOWNLOAD_HOME/banking-sample/appserver/AccountService/src/wso2/hcc and paste into the 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 the 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 modelling the Account Service.

2. Modeling Card System

Now we want to create the Card System. This will be another Apache Axis2 Service Project. Click Axis2 Service Project from the WSO2 Developer Studio Dashboard as you did 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 the 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 Composite Application Project to group the two created axis2 services.

3. Create a Composite Application Project to group mock objects

Open the Developer Studio Dashboard again and click Composite Application Project.

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

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

4. Deploy the Composite Application Project in to WSO2 App 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 Deploying a C-App to a Running Server inside Eclipse.

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

Wait till the application gets deployed successfully to the server. Once the deployment is completed, you will see logs similar to the following 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 displayed in the console log, you can see that the MainframePojoService and CardAxis2Service have been deployed to WSO2 Application Server. Go to management console in the browser and check for Deployed Services.

If you click on the MainframePojoService and check the  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 the above two services.

Create Proxy Services to abstract the Mainframe

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

Open the 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 an ESB Config Project, click on Create New Project link.

Give a name to the ESB Config Project and click Finish.

Now you will see that the created ESB Project is set in the Save endpoint in field.

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. In the Properties window below, select the row with the Endpoint on it, then click on the button on the far right containing ellipsis (…).

In the Resource Key Editor that pops up, click 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 that 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 A New Proxy Service 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. Next we have to configure it according to our scenario.

Once the CardService has been opened in Design view, you will see that there are three basic sections in the proxy service; InSequence, OutSequence and FaultSequence (red rectangle).

In the Properties window below, select the row corresponding to WSDL Type, and change its value from NONE to SOURCE_URL 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. The file CardService.wsdl can be found at $DOWNLOAD_HOME/banking-sample/appserver.Your file URI will be similar to: file:///$DOWNLOAD_HOME/banking-sample/appserver/CardService.wsdl .

Drag and drop the XSLT mediator from the tool palette to the InSequence of the CardService proxy.

Click on the newly created XSLT node, and change the Schema Key value to conf:/transform/transform.xslt.

This means that the transformation stylesheet is to be found in the local registry. But we don't have it there yet. The XSLT stylesheet 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 by dragging the Log mediator from the tool palette to before and after the XSLT.

Drag and drop a Send mediator and then drag and drop the cardServiceEP that we created earlier from the defined endpoints.

Now add a Send mediator as an OutSequence. We have successfully completed creating the proxy service for the card system.

Create Registry Resource for transform.xslt

On the Developer Studio Dashboard, select Registry Resource under the Governance Registry category.

Select Import from file system and click Next.

Click Browse 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 the necessary information for the Registry Resource Project and click Finish.

Now you can see that the created Registry Resources Project is set in the 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.

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 the Developer Studio Dashboard and click BPEL Workflow under the Business Process Server category.

Select Create New BPEL Workflow and click Next. 

Enter AccountOpeningProcess as the Project Name and Process Name, and leave the default values for the other fields. Click Finish .

You will see that the 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 Composite Application Archive from the Banking Sample Composite 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 the 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-clicking on the BankingSample C-App project and selecting Export Composite 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

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

Once you click this link, you will be prompted to select the CAR file 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 the following artifacts in different servers once you deploy the CAR file to all the servers. The application BankingSample should be listed in all the servers as well.

Let's test the 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.