Developing Your First Integration Solution


What you'll build


Integration Scenario

The scenario is about a basic healthcare system where WSO2 Micro Integrator is used as the integration middleware. Most healthcare centers use a system to help patients book doctor appointments. To check the availability of doctors, patients will typically use every online system that is dedicated to a particular healthcare center or personally visit the healthcare centers.



  • The Grand Oak service accept GET requests in the following service endpoint URL:


  • The Pine Vallery service accepts POST requests in the following service endpoint URL:


    The expected payload should be in the following JSON format:

            "doctorType": "<DOCTOR_TYPE>"


Step 1 - Set up the workspace


Step 2 - Develop the integration artifacts

Create the integration project

Let's create an integration project with the required modules (to store artifacts) in WSO2 Integration Studio.

  1. Open WSO2 Integration Studio and click New Integration Project in the Getting Started view as shown below. New Integration Project

  2. In the New Integration Project dialog box that opens, enter Healthcare as the project name. This is a maven multi module project.

    Be sure to leave the Create ESB Configs and Create Composite Exporter check boxes selected as shown below.

  3. Click Finish.

The integration project with the ESB Config module (HealthcareConfigs) and Composite Exporter module (HealthcareCompositeExporter) are created as shown below.

project folder

Create Endpoints

The actual back-end services (healthcare services) are logically represented in the integration solution as Endpoint artifacts.

Let's create two Endpoint artifacts for the two healthcare services:

  1. Right-click HealthcareConfigs and go to NewEndpoint to open the New Endpoint Artifact dialog box.

  2. In the New Endpoint Artifact dialog box that opens, select Create a New Endpoint and click Next.

  3. For the ‘Grand Oak hospital service’, let’s use the following values:

    Parameter Value
    Endpoint Name GrandOakEndpoint
    Endpoint Type HTTP Endpoint
    Method GET

  4. Click Finish to save the endpoint configuration.

  5. Follow the same steps to create an endpoint for ‘Pine Valley Hospital’. Use the following parameter values:

    Parameter Value
    Endpoint Name PineValleyEndpoint
    Endpoint Type HTTP Endpoint
    Method POST

Create the REST API


  1. Right-click HealthcareConfigs in the project explorer and go to NewREST API to open the API Artifact Creation Options dialog box.
  2. Select Create A New API Artifact and click Next.
  3. Specify values for the required REST API properties:

    Parameter Value
    Name HealthcareAPI
    Context /healthcare


  5. Open the new artifact from the project explorer. You will see the graphical view of the HealthcareAPI with its default API Resource.



    Specify values for the required resource properties:

    Parameter Value
    Url Style URL_TEMPLATE
    Uri Template /doctor/{doctorType}

    Note that '{doctorType}' is a uri variable that gets resolved to the path parameter value in the runtime. We can access the value of the uri variable in the mediation flow using the variable (property) called ‘uri.var.doctorType’.
    Methods Get

Create the mediation logic

  1. Create two parallel message flows:


    Drag the Clone mediator from the mediator palette and drop it into the request path (in sequence) of the API Resource canvas.


  2. Invoke the GrandOak Endpoint:




  3. Construct message payload for the PineValley Endpoint:


        "doctorType": "<DOCTOR_TYPE>"

    Therefore, we need to first construct the required message payload. There are several Transformation mediators for constructing messages. Let's use the PayloadFactory mediator. Drag the PayloadFactory mediator into the 2nd branch of the Clone mediator as shown below.

    Specify values for the required PayloadFactory properties:

    Parameter Value
    Payload Format Inline
    Media Type json
    Payload { "doctorType": "$1" }
    Args $ctx:uri.var.doctorType

    Note the $1 in the Payload format. It denotes a parameter that can get a value assigned dynamically. The value for the parameters needs to be assigned using Arguments (Args). Args can be added using the PayloadFactoryArgument dialog box, which appears when you click the () sign.


  4. Invoke the PineValley Endpoint:


  5. Aggregating response messages:

    Since we are cloning the messages and delivering them into two different services, we will receive two responses. So we need to aggregate those two responses and construct a single response. To do that, we can use the Aggregate mediator.


    Specify values for the required Aggregate mediator properties.

    Parameter Value
    Aggregation Expression json-eval($
  6. Send a response back to the client :

    To send the response back to the client, we can use the Respond mediator. Add the Respond mediator as shown below.

The final mediation configuration looks similar to the above diagram.

      <endpoint key="GrandOakEndpoint"/>
        <payloadFactory media-type="json">
            "doctorType": "$1"
      <endpoint key="PineValleyEndpoint"/>
      <onComplete expression="json-eval($">

Step 3 - Build and run the artifacts

There are several ways to deploy and run the integration scenario.

Option 1: Using WSO2 Integration Studio

  1. Right-click HealthcareCompositeExporter and click Export Project Artifacts and Run.

  2. You will see the following dialog box. Select the HealthcareConfigs folder in the artifact list and click Finish.

The embedded Micro Integrator starts with the deployed artifacts. You will see the server startup log in the Console tab, and the endpoints of the deployed services in the Runtime Services tab as shown below.

Option 2: Using a local Micro Integrator instance


  1. Go to the WSO2 Micro Integrator web page, click Download, and then click Zip Archive to download the Micro Integrator distribution as a ZIP file.
  2. Extract the ZIP file. This will be the <MI_HOME> folder.


  1. Export the artifacts as a deployable CAR file: Right-click HealthcareCompositeExporter in WSO2 Integration Studio and select Export Composite Application Project.


  3. Start the Micro Integrator:

    1. Open a terminal and navigate to the <MI_HOME>/bin folder.
    2. Execute one of the commands given below.


Step 4 - Observe deployed artifacts

Once you have deployed the artifacts and started the Micro Integrator server, you can install and start the Dashboard to observe details of the deployed artifacts.

If you are running the embedded Micro Integrator, click Open Monitoring Dashboard in the Runtime Services tab as shown below.

You will be directed to the sign-in screen of the Dashboard from your default browser as shown below. Sign in using admin as the user name and password.

Once you sign in, click the required artifact type to view details.

Step 5 - Test the use case

Now, let's test the integration service.

Start back-end services

Let's start the mock back-end services for this use case:

  1. Download the DoctorInfo-JDK11.jar file. This contains two healthcare services.
  2. Open a terminal, navigate to the location of the downloaded DoctorInfo-JDK11.jar file, and execute the following command to start the services:

    java -jar DoctorInfo-JDK11.jar

Invoke the Healthcare service

There are two ways to invoke the service:

  • Option 1: Using WSO2 Integration Studio

    Let's invoke the API from the embedded HTTP Client of WSO2 Integration Studio as follows:

    1. Open the HTTP Client of WSO2 Integration Studio.


      If you don't see the HTTP Client tab, go to Window -> Show View - Other and select HTTP Client to enable the client tab.


      Method GET
      URL http://localhost:8290/healthcare/doctor/Ophthalmologist

    The response is printed in the HTTP Response section.

  • Option 2: Using your terminal

    If you want to send the client request from your terminal:

    1. Install and set up cURL as your REST client.
    2. Open a terminal and execute the following curl command to invoke the service:


    You will receive the following response:

                "name": "John Mathew",
                "time": "03:30 PM",
                "hospital": "Grand Oak"
                "name": "Allan Silvester",
                "time": "04:30 PM",
                "hospital": "Grand Oak"
                "name": "John Mathew",
                "time": "07:30 AM",
                "hospital": "pineValley"
                "name": "Roma Katherine",
                "time": "04:30 PM",
                "hospital": "pineValley"

What's Next?