Quick Start Guide

WSO2 Enterprise Integrator (WSO2 EI) is a comprehensive solution that allows you to seamlessly integrate applications, services, data and business processes to support modern enterprise integration requirements. This quick start guide will take you on a quick tour of WSO2 EI to help you understand what you can achieve using this product. We will use a sample use case for this purpose as explained below.

Let's consider a basic Health Care System where WSO2 EI is used as the integration software. An external party (a patient) should be able to achieve the following using our health care system:

Request a list of available doctors based on a specified specialization.
Reserve an appointment by providing personal details, preferred hospital, doctor's name, and credit card information.
Cancel a reservation if necessary. The cancellation request will be accepted by the healthcare service, only if the date of appointment is more than two days away.

Let's see how WSO2 EI will facilitate the above requirement:

WSO2 EI will process the patient's request and will return responses to the patient accordingly. In this example, we will use a microservice developed using MSF4J as the back-end service (Healthcare service) of this health care system. We will also use an H2 database as a back-end database, which contains the details of doctors available for channeling in the Healthcare service.

The following diagram illustrates all the service calls and payload manipulations that will be handled by WSO2 EI, based on the patient's request:

sequence diagram

When a patient sends a request to retrieve a list of available doctors for a specified specialization, the request is sent to a data service defined in WSO2 EI that exposes information from an external database.
When a patient makes a request to reserve an appointment, the request is sent to a REST API that is configured in WSO2 EI. The REST API processes the incoming request and forwards it to the healthcare service, which does the appointment reservation.
The REST API processes the appointment reservation response, sends a service call to the healthcare service to get the doctor's channeling fee, and receives the response.
The REST API processes the channeling fee response and sends a service call to the healthcare service to get the patient's eligibility for a discount.
When the responses for these service calls are returned, the REST API calculates the actual fee for the appointment and creates a new request with the payment details to be sent to the healthcare service. The healthcare service processes the payment settlement and returns the response to the REST API.
The REST API takes the payment settlement response and generates the email response and sends it to the patient.
When a patient clicks the cancellation link in the reservation confirmation email, the cancellation request is sent to the business process workflow defined in WSO2 EI. Next, the REST API sends a service call to the healthcare service to retrieve details of the reservation. If the cancellation request date is two days earlier than the appointment date, the workflow cancels the reservation and sends the appointment cancellation response email to the patient via the REST API.
If not, it will create a new admin workflow to which, an authorized administrator will log in and manually cancel the reservation. Then, the system sends the appointment cancellation response email to the patient.

Let's get started!

Download and set up WSO2 EI

Before you begin

Install Oracle Java SE Development Kit (JDK) version 1.8.* and set the JAVA_HOME environment variable.
Install Apache Ant.
If you are running on Windows, download the snappy-java_1.1.1.7.jar file and copy it to the <EI_HOME>\lib directory.

Download WSO2 EI and extract the ZIP file. The path to this folder will be referred to as <EI_HOME> throughout this quick start guide. See that <EI_HOME> contains five separate profiles (runtimes) as follows:

ESB profile: <EI_HOME>
Broker profile: <EI_HOME>/wso2/broker
Business Process profile: <EI_HOME>/wso2/business-process
MSF4J profile: <EI_HOME>/wso2/msf4j
Analytics profile: <EI_HOME>/wso2/analytics

Let's configure the ESB profile so that it can connect to the Broker profile for reliable messaging:

Open the <EI_HOME>/conf/jndi.properties file.
Add the queue.PaymentRequestJMSMessageStore=PaymentRequestJMSMessageStore line below the queue.MyQueue = example.MyQueue line to update the queue as shown below.
# register some connection factories # connectionfactory.[jndiname] = [ConnectionURL] connectionfactory.QueueConnectionFactory = amqp://admin:admin@clientID/carbon?brokerlist='tcp://localhost:5675' connectionfactory.TopicConnectionFactory = amqp://admin:admin@clientID/carbon?brokerlist='tcp://localhost:5675' # register some queues in JNDI using the form # queue.[jndiName] = [physicalName] queue.MyQueue = example.MyQueue queue.PaymentRequestJMSMessageStore=PaymentRequestJMSMessageStore

Check the availability of doctors

Let's look at how we can check the availability of doctors in the healthcare service by sending a simple request.

Set up the back-end database

First, let's set up a back-end database for our healthcare service. Follow the steps below to create the database.

Download the dataServiceSample.zip file and extract it to a location on your computer. Let's refer the extracted dataServiceSample directory as <QSG_HOME>, which contains the following:
- A DB script to create the back-end database (DATA_SERV_QSG) with the channelling information of the healthcare service.
- A pre-packaged data service (DOCTORS_DataService.dbs file), which can expose the back-end database as a service.
Open a terminal, navigate to the <QSG_HOME> directory and execute the following command:
ant -Ddshome=PATH_TO_EI_HOME

The DATA_SERV_QSG database is now created in the <EI_HOME>/samples/data-services/database directory with information of all available doctors in the healthcare service.

Expose the database as a data service

Now, let's start the ESB profile in WSO2 EI and upload the sample data service:

Open a terminal and navigate to the <EI_HOME>/bin directory.
Execute one of the following scripts to start the Integrator profile of WSO2 EI.
- On Windows: integrator.bat --run
- On Linux/Mac OS: sh integrator.sh
In your Web browser, navigate to the WSO2 EI management console using the following URL: https://localhost:9443/carbon/
Log into the management console using the following credentials:
- Username: admin
- Password: admin
Go to the Main tab and click Data Service -> Upload.
Upload the DOCTORS_DataService.dbs file from the <QSG_HOME> directory.
Refresh the page to see the deployed data service in the Deployed Services screen.

The database of the channeling service is now exposed through the DOCTORS_DataService data service, which we just deployed in WSO2 EI.

Request doctors' information

Assume that you want information on the availability of all surgeons. Open a terminal and execute the following command. Note that we are specifying 'surgery' as the specialty.

curl -v http://localhost:8280/services/DOCTORS_DataService/getDoctors?SPECIALITY=surgery

The information about the availability of all surgeons will be published on your terminal:

<DOCTORSLIST xmlns="http://ws.wso2.org/dataservice">
<DOCTOR>
    <NAME>thomas collins</NAME>
    <HOSPITAL>grand oak community hospital</HOSPITAL>
    <SPECIALITY>surgery</SPECIALITY>
    <AVAILABILITY>9.00 a.m - 11.00 a.m</AVAILABILITY>
    <CHARGE>7000</CHARGE>
</DOCTOR>
<DOCTOR>
    <NAME>anne clement</NAME>
    <HOSPITAL>clemency medical center</HOSPITAL>
    <SPECIALITY>surgery</SPECIALITY>
    <AVAILABILITY>8.00 a.m - 10.00 a.m</AVAILABILITY>
    <CHARGE>12000</CHARGE>
</DOCTOR>
<DOCTOR>
    <NAME>seth mears</NAME>
    <HOSPITAL>pine valley community hospital</HOSPITAL>
    <SPECIALITY>surgery</SPECIALITY>
    <AVAILABILITY>3.00 p.m - 5.00 p.m</AVAILABILITY>
    <CHARGE>8000</CHARGE>
</DOCTOR>
</DOCTORSLIST>

Start the back-end service

To be able to send requests to the back-end service (which is an MSF4J service deployed in the MSF4J profile of WSO2 EI), you need to first start the MSF4J runtime:

Download the Healthcare service JAR file.
Copy the JAR file to the <EI_HOME>/wso2/msf4j/deployment/microservices directory.
Open a terminal and navigate to the <EI_HOME>/wso2/msf4j/bin directory.
Start the runtime by executing the MSF4J startup script as shown below.
- On Windows: carbon.bat
- On Linux/Mac OS: sh carbon.sh