Quick Start Guide

WSO2 Enterprise Integrator (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 helps you understand WSO2 EI and how to use its essential functionality by walking through a sample scenario. It contains the following sections:

Introduction

Let's take a look at the basic use cases of WSO2 EI using a sample scenario. Consider a basic health care system where a patient can do the following:

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

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

The following steps explain how WSO2 EI handles all the service calls and payload manipulations 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 hospital service, which does the appointment reservation.

3. The REST API processes the appointment reservation response, sends a service call to the hospital 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 hospital 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 response to be sent 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:

• Integration 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 Integration profile so that it can connect to the Broker profile for reliable messaging:

1. Open the <EI_HOME>/conf/jndi.properties file and update the connection factories and queues at the beginning of the file so that it now looks like this:

   # 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

2. Copy the following JARs from the <EI_HOME>/wso2/broker/client-lib folder to the <EI_HOME>/lib folder.
   • andes-client-3.2.13.jar
   • geronimo-jms_1.1_spec-1.1.0.wso2v1.jar
   • org.wso2.securevault-1.0.0-wso2v2.jar

Check the availability of doctors

Let's look at how we can check the availability of doctors in the hospital 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 hospital 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 Integration 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.db file from the <QSG_HOME> directory.
7. After a few moments, the deployed data service appears 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. 

Reserve an appointment

Now, we will prepare the Integration 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 Integration profile Management Console using https://localhost:9443/carbon, and log in using admin as the username and the password.
2. Download the 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. 

      After you upload a CAR file, you can confirm that it is successfully deployed by taking the following step:

      • On the Main tab of the management console, go to Manage -> Carbon Applications and click List. The Carbon Applications List screen appears. If successfully deployed, the CAR file will be listed here.

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.

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:

   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 -> 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 Integration 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 Integration profile

Let's restart the Integration profile:

1. Open a new command line terminal and navigate to the <EI_HOME>/bin directory.
2. Start the Integration 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 and tracing for the REST API:

1. On the Main tab of the management console, go to Manage -> Service Bus and click APIs. The Deployed APIs screen appears, and you will see the HealthcareAPI listed as follows:
   
2. To enable the collection of mediation statistics for the REST API, click Enable Statistics.
3. To enable mediation tracing for the REST API, click Enable Tracing.

Follow the steps below to enable statistics for the endpoints:

1. 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.
   
2. 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. For more information on analyzing the statistics displayed on this page, see Analyzing EI Statistics Overview.

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.