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:

1. 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. 

2. 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.

3. 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.

4. 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.

5. 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. 

6. The REST API takes the payment settlement response and generates the email response and sends it to the patient.

7. 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.
8. 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

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:

1. Open the <EI_HOME>/conf/jndi.properties file.

2. 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.

1. 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.

2. 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:

1. Open a terminal and navigate to the <EI_HOME>/bin directory.
2. 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
3. In your Web browser, navigate to the WSO2 EI management console using the following URL: https://localhost:9443/carbon/
4. Log into the management console using the following credentials:
   • Username: admin
   • Password: admin
5. Go to the Main tab and click Data Service -> Upload. 
   
6. Upload the DOCTORS_DataService.dbs file from the <QSG_HOME> directory.
7. 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:

1. Download the Healthcare service JAR file.
2. Copy the JAR file to the <EI_HOME>/wso2/msf4j/deployment/microservices directory. 
3. Open a terminal and navigate to the <EI_HOME>/wso2/msf4j/bin directory.

4. Start the runtime by executing the MSF4J startup script as shown below.

   • On Windows: carbon.bat
   • On Linux/Mac OS: sh carbon.sh

The Healthcare service is now active and ready to receive reservation requests. 

Start the Message Broker profile

The Message Broker profile of WSO2 EI is used to ensure reliable messaging in this integration scenario. Therefore, let's start the Message Broker profile before sending the appointment reservation request:

1. Open a new command line terminal and navigate to the <EI_HOME>/wso2/broker/bin directory.
2. Execute one of the following commands.
   • On Linux/Mac OS:  sh wso2server.sh
   • On Windows:  wso2server.bat

The system is now ready to receive appointment reservation requests.

Reserve an appointment

Now, we will prepare the ESB profile and reserve an appointment from the healthcare service.

Define the message mediation sequence

Let's define the integration sequence in WSO2 EI, which will mediate the appointment reservation request and send you an email confirming the reservation. For the purpose of this quick start, we have already created the artifacts for this sequence and packaged them as a composite application archive (CAR). Instead of creating the artifacts that are required to run this sample scenario from scratch, let's deploy the pre-packaged CAR file.

The SampleServicesCompositeApplication_1.0.0.car file consists of mediation artifacts such as the REST API, the endpoints (backend services the requests are sent to), and the sequences (list of mediators) that allow the Enterprise Integrator to process the appointment reservation request.

1. Open the ESB profile Management Console using https://localhost:9443/carbon, and log in using admin as the username and the password.
2. Download the SampleServicesCompositeApplication_1.0.0.car file with the integration artifacts.

3.  Deploy the SampleServicesCompositeApplication_1.0.0 .car as follows:

   1. On the Main tab of the management console, go to Manage -> Carbon Applications and click Add. 

   2. Click Choose File, select the SampleServicesCompositeApplication_1.0.0.car file that you downloaded, and click Upload. 

   3. Refresh the page to see the carbon application you just added in the Carbon Applications List screen.
      

Send the reservation request

Follow the steps below to reserve an appointment after you view the list of available doctors and decide on the doctor you want to channel. 

1. Create a JSON file named request.json with the following request:

   Make sure to:

   • Specify an appointment_date that is at least 3 days from the current date.
   • Be sure to add a valid email address. Notifications will be sent to this email address when the appointment is confirmed.

   { "name": "John Doe",
     "dob": "1940-03-19",
     "ssn": "234-23-525",
     "address": "California",
     "phone": "8770586755",
     "email": "johndoe@gmail.com",
     "doctor": "thomas collins",
     "hospital": "grand oak community hospital",
     "cardNo": "7844481124110331",
     "appointment_date": "2017-05-02"
   }

2. In a new terminal, navigate to the location where you saved the request.json file and execute the following command:

   curl -v -X POST --data @request.json http://localhost:8280/healthcare/categories/surgery/reserve --header "Content-Type:application/json"

   This sends an appointment request to the REST API, which is the configuration inside the Enterprise Integrator that receives and processes the request. Once all the message flows take place as described in the sample introduction, you will see a response similar to the following on the console:

   {"message":"Payment request successfully submitted. Payment confirmation will be sent via email."}

   An email similar to the following will be sent to the email address of the patient:

   Subject: Payment Status
    
   {
     "Appointment Number": 1,
     "Doctor":thomas collins,
     "patient":John Doe,
     "actualFee":7000.0,
     "discount":20,
     "discounted":5600.0,
     "status":"Settled",
     "cancellation link" : "https://localhost:9445/bpmn-explorer/"
   }

Cancel the reservation

Let's define the BPMN process for canceling an appointment reservation. For the purpose of this quick start, we have already created the artifacts for this BPMN process and packaged it as a .bar file. Therefore, instead of defining the BPMN process from scratch, let's deploy the pre-packaged AppointmentCancellation.bar file.

Start the Business Process profile

The .bar file of the BPMN process should be deployed to the Business Process profile using the profile's management console. Let's start the profile first.

1. Open a command line terminal and navigate to the the <EI_HOME>/wso2/business-process/bin directory.
2. Execute the following command.
   • On Linux/Mac OS:  sh wso2server.sh
   • On Windows:  wso2server.bat

Define the appointment cancellation process

Next, let's deploy the pre-packaged AppointmentCancellation.bar file.

1. Open the Business Process profile Management Console using https://localhost:9445/carbon, and log in using admin as the username as well as the password.
2. Download the AppointmentCancellation.bar file.
3. Deploy the AppointmentCancellation.bar file as follows:
   
   1. On the Main tab of the management console, go to Manage -> Process-> Add, and click BPMN.
   2. Click Choose File, select the AppointmentCancellation.bar file that you downloaded and click Upload. 

Cancel the reservation using the BPMN explorer

If you successfully reserved an appointment and received an email confirming the reservation, follow the steps below to cancel the reservation. 

1. Click the cancelation link in the email. This takes you to the BPMN explorer.
2. Sign in to the BPMN explorer using admin as the username and password.
3. Click PROCESSES. This displays the appointment cancellation process.
4. Click Start. This displays the Start Process form.

5. Enter the appointment details you received via email, and click Start. Be sure to enter the correct appointment number and email address.
   You will receive an email confirming that the appointment is canceled.

   In this case, the appointment can be canceled because the appointment date is more than two days from the current date. 

Analyze the mediation statistics

Now let's have a look at how you can view the mediation statistics related to the processing that happens within WSO2 EI via the Analytics Dashboard of the Analytics profile.

Start the Analytics profile

To analyze statistics of integration processes, ensure that you start the Analytics profile before the ESB profile.

Let's start the Analytics profile:

1. Open a command line terminal and navigate to the <EI_HOME>/wso2/analytics/bin directory.
2. Start the Analytics profile by running one of the following startup scripts:
   • On Linux/Mac OS:  sh wso2server.sh
   • On Windows:  wso2server.bat

Restart the ESB profile

Let's restart the ESB profile:

1. Open a new command line terminal and navigate to the <EI_HOME>/bin directory.
2. Start the ESB profile by running one of the following startup scripts: 
   • On Linux/Mac OS:  sh integrator.sh
   • On Windows:  integrator.bat

Enable statistics and tracing for the artifacts

Follow the steps below to enable statistics for the endpoints:

1. Open the ESB profile Management Console using https://localhost:9443/carbon, and log in using admin as the username and the password.
2. On the Main tab of the management console, go to Manage -> Service Bus, and click Endpoints. The Manage Endpoints screen appears, and you will see several endpoints listed.
   
3. To enable the collection of mediation statistics for the endpoints, click Enable Statistics for each endpoint.

Send another appointment reservation request

Let's send a new appointment reservation request to WSO2 EI.

1. In a new terminal, navigate to the location where you saved the request.json file. 

2. Execute the following command:

   curl -v -X POST --data @request.json http://localhost:8280/healthcare/categories/surgery/reserve --header "Content-Type:application/json"

3. See that you have received an email confirming the reservation.

View statistics using the Analytics dashboard

Now, let's use the Analytics dashboard to view the mediation statistics.

1. In a new browser window or tab, open https://localhost:9444/carbon/ and log into the Analytics management console using admin as the username as well as the password.
2. On the Main tab, click Analytics Dashboard, and log in using admin as the username as well as the password. 
   You will then see the following:
   

3. Click View to open the EI Analytics Dashboard. You will see an OVERVIEW page similar to the following:

   The statistics you see depend on the number of requests that you have sent. If you follow the steps in the Sending a request to WSO2 EI section and send just one request, you will see the statistics for just that request.

   
   To view statistics for a specific date range, select the required date range from the top right menu bar. To view statistics for a specific date, click Custom in the menu bar and enter the required date.

4. To view statistics for the REST API, click API on the left navigator and search for  HealthcareAPI . 
   For more information on analyzing statistics displayed on this page, see Analytics Statistics for REST APIs.
   
5. To view statistics for an endpoint, click ENDPOINT on the left navigator and search for the required endpoint. You can view statistics for the following endpoints on this page:
   • ChannellingFeeEP
   • ClemencyEP
   • GrandOakEP
   • PineValleyEP
   • QueryDoctorEP
   • SettlePaymentEP
    For more information on analyzing statistics displayed on this page, see Analyzing Statistics for Endpoints.