Quick Start Guide

WSO2 Enterprise Service Bus (ESB) is a lightweight, high performance, comprehensive ESB to enable interoperability among various heterogeneous systems and business applications. WSO2 ESB effectively supports integration standards and patterns.

Let's take a look at the basic use cases of the ESB using a sample scenario. 

Introducing the sample

This is a healthcare system in which a user reserves a medical appointment by providing his/her personal details, preferred hospital, doctor's name, credit card information etc. 

The ESB processes the user's request and returns an appointment confirmation or a refusal. The following diagram shows how the ESB handles all the service calls and payload manipulations involved in a reservation:

Note the following regarding the diagram:

1. When a patient makes a request to reserve an appointment, the request is sent to a REST API that is configured in the ESB. The REST API processes the incoming request and forwards it to the hospital service, which does the appointment reservation.

2. The REST API processes the appointment reservation response and sends a service call to the hospital service to get the doctor's channeling fee and receives the response.

3. The REST API processes the channeling fee response and sends a service call to the hospital service to get the user's eligibility for a discount. 

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

5. The REST API takes the payment settlement response and generates the response to be sent to the user.

Let's go through the main features of WSO2 ESB using this healthcare service as an example.

Deploying the sample to create mediation artifacts

Instead of creating the ESB artifacts that are required to run this sample scenario from scratch, let's deploy them using a Composite Application Archive (CAR) file. The 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 ESB to process the requests.

Let's get started!

Follow the steps below to deploy the healthcare sample:

1. Set the following properties in the <ESB_HOME>/repository/conf/synapse.properties file to true so that the ESB can publish mediation statistics:

   ...
   mediation.flow.statistics.enable=true
   mediation.flow.statistics.tracer.collect.payloads=true
   mediation.flow.statistics.tracer.collect.properties=true
   ...

2. Start the WSO2 ESB Analytics server by going to <ANALYTICS_HOME>/bin using the Command-Line/Terminal and executing one of the following commands:
   • On Linux/Mac OS:  sh wso2server.sh

   • On Windows:  wso2server.bat --run

3. Start WSO2 ESB server by going to <ESB_HOME>/bin using the Command-Line/Terminal and executing one of the following commands: (Be sure you have successfully started the Analytics server before taking this step.)

   • On Linux/Mac OS:  sh wso2server.sh

   • On Windows:  wso2server.bat --run

4. Open the WSO2 ESB Management Console using https://localhost:9443/carbon/ and log in using admin/admin as the credentials.

5. Deploy WSO2QuickStartGuideCapp_1.0.0.car to the ESB as follows:
   

   Tip: The CAR file was created using WSO2 ESB tooling. For information on getting started with WSO2 ESB tooling, see Working with WSO2 ESB Tooling.

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

   2. Click Choose File, select the WSO2QuickStartGuideCapp_1.0.0.car file you downloaded in the Before you begin... section above, and click Upload. 

      Note

      After you upload a CAR file, you can confirm that it was 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.
6. 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 HospitalServiceApi 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.
7. 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.

You have now created mediation artifacts in the ESB and enabled statistics. Let's send a request to the ESB.

Sending a request to the ESB

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

   {
   	"reserveRequest": {
   		"patientDetails": {
   			"name": "Mark Smith",
   			"dob": "1990-03-19",
   			"ssn": "ASJK-asnda-AAA",
   			"address": "100 MAIN ST, SEATTLE WA 98104, USA",
   			"phone": "0770596754",
   			"email": "marksm@mymail.com"
   		},
   		"doctor": "thomas collins",
   		"hospital": "grand oak community hospital",
   		"category": "surgery",
   		"cardNo": "7844481124110331"
   	}
   }

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

   curl -v -X POST "http://localhost:8280/hospitalservice/reserve" --header "Content-Type: application/json" -d @reserve_appointment.json -k -v

   This sends an appointment request to the REST API, which is the configuration inside the ESB 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:

   {
       "appointmentNumber": 1,
       "Doctor": {
            "fee": 7000,
            "name": "thomas collins",
            "availability": "9.00 a.m - 11.00 a.m",
            "hospital": "grand oak community hospital",
            "category": "surgery"
        },
        "Payment": {
            "patient": "Mark Smith",
            "actualFee": 7000,
            "discount": 0,
            "discounted": 7000,
            "paymentID": "c5edddf3-d7d7-4756-8a03-5e8e31f2e716",
            "status": "Settled"
        }
   } 

When you receive the response for the request that you sent, you can view the mediation statistics related to the processing that happens within WSO2 ESB via WSO2 ESB Analytics.

Now let's have a look at how you can view the mediation statistics on the Analytics Dashboard of WSO2 ESB Analytics.

Analyzing 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 for both the username and password.
2. On the Main tab, click Analytics Dashboard and log in using admin for both the username and password. You will then see the following:
   

3. Click View to open the ESB Analytics Dashboard. The OVERVIEW page is displayed by default. You will see an OVERVIEW page similar to the following:

   Note

   The statistics you see will be for the number of requests that you have sent. If you follow the steps in the Sending a request to the ESB 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. If you want 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 ESB Statistics Overview.
4. To view statistics for the REST API, click API on the left navigator and search for HospitalServiceApi . For more information on analyzing statistics displayed on this page, see Analyzing 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:
   • reserveAppointmentEp
   • discountEligibility
   • channellingFee
   • settlePayment
    For more information on analyzing statistics displayed on this page, see Analyzing Statistics for Endpoints.

Where to go next

You have now explored the basics of using WSO2 ESB and are ready to get started creating your own ESB artifacts. Next, you can have a look at the lessons in the Tutorials section to understand more about some of the most common usage scenarios of WSO2 ESB, how to use WSO2 ESB Tooling to create your artifacts, and how to use WSO2 ESB Analytics to publish statistics related to the processing carried out in WSO2 ESB to the Analytics Dashboard.

Explore the topics in the table of contents of this guide to learn more about working with the ESB runtime, ESB tooling as well as ESB analytics.

For information on the various integration patterns you can implement, see Enterprise Integration Patterns with WSO2 ESB.