Skip to content

Developing Your First Integration Solution Using MI for VS Code

Integration developers need efficient tools to build and test all the integration use cases required by the enterprise before pushing them into a production environment. The following topics will guide you through the process of building and running an example integration use case using Micro Integrator extension for Visual Studio Code (MI for VS Code). This extension allows you to conveniently design, develop, and test your integration artifacts before deploying them in your production environment.

What you'll build

This is a simple service orchestration scenario. The scenario is about a basic healthcare system where the Micro Integrator is used to integrate two back-end hospital services to provide information to the client.

Click here to view the business scenario

This is the same scenario we considered in our Quick Start Guide where we executed the already-built integration scenario. In this tutorial, we are going to build the same integration scenario from scratch using the MI for VS Code extension.

Let’s recall the business scenario:

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.

We will simplify this process of booking doctor appointments by building an integration solution that orchestrates the isolated systems in each healthcare provider and exposes a single interface to the users.

Both the Grand Oak service and Pine Valley service are exposed over the HTTP protocol.

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

    http://<HOST_NAME>:<PORT>/grandOak/doctors/<DOCTOR_TYPE>
    

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

    http://<HOST_NAME>:<PORT>/pineValley/doctors
    

The expected payload should be in the following JSON format:

{
        "doctorType": "<DOCTOR_TYPE>"
}

Let’s implement a simple Rest API that can be used to query the availability of doctors for a particular category from all the available healthcare centers.

Step 1 - Set up the workspace

The following software and configurations are required to proceed with this tutorial:

  • Visual Studio Code (VS Code): with the Micro Integrator extension installed.
  • Java Development Kit (JDK): Version 11 or 17 is required. Ensure the JDK is properly configured in your system's PATH environment variable.
  • Apache Maven: Ensure Apache Maven is installed and its path is correctly set within the system's PATH environment variable.

Info

Follow the Install Micro Integrator for VS Code documentation for a complete installation guide.

Step 2 - Develop the integration artifacts

Create the integration project

Let's create an integration project with the required modules (to store artifacts) in VS Code.

  1. Launch VS Code with the Micro Integrator extension installed.
  2. Click Create New Project on Design View.

    Design View Pane Create New Project

    Tip

    To create a new project, click Create New Project on either the MI Project Explorer pane or the Design View pane.

    Create New Project

    Clicking Create New Project will open the Project Creation Form interface.

  3. In the Project Creation Form, enter Healthcare as the Project Name.

  4. Provide a location under the Select Project Directory.

    New Project Details

  5. Click Create.

    Upon clicking Create, the MI Project Overview interface will be displayed.

    Add Artifact Pane

Create Endpoints

The actual backend 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. Navigate to the MI Project Explorer > Endpoints.

  2. Click on the + icon next to Endpoints.

    Create Endpoint

    Tip

    You can also create an endpoint using the Add Artifact pane. 1. Click View More to see all the available artifacts. 2. Click Endpoint.

  3. Next, select the endpoint type you want from the Create Endpoint Artifact interface.

    Create HTTP Endpoint

  4. Select HTTP Endpoint.

  5. In Endpoint Artifact interface that appears, specify the following values for the ‘Grand Oak hospital service’.

    Parameter Value
    Endpoint Name GrandOakEndpoint
    URI Template http://localhost:9090/grandOak/doctors/{uri.var.doctorType}
    Method GET

    Grandoak Endpoint Artifact

  6. Click Create to save the endpoint configuration.

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

    Parameter Value
    Endpoint Name PineValleyEndpoint
    URI Template http://localhost:9091/pineValley/doctors
    Method POST

    Pinevalley Endpoint Artifact

Once the two endpoint artifacts are created, they will appear on the MI Overview interface as shown below:

Created Endpoints

Create the REST API

We are orchestrating multiple services and exposing a single API to the clients. The main integration artifact is going to be a REST API.

  1. Go to MI Project Explorer > APIs.

  2. Click on the + sign next to APIs to open the below Synapse API Artifact creation form.

  3. Specify values for the required REST API properties:

    Parameter Value
    Name HealthcareAPI
    Context /healthcare

    Healthcare API Artifact

  4. Click Create.

    The REST API is created in the /src/main/wso2mi/artifacts/apis folder under Healthcare.

    After creating the API artifact, the Service Designer pane will be displayed with the available resources.

    Service Designer

  5. Click on the GET API resource under available resources on the Service Designer.

    You will now see the graphical view of the HealthcareAPI with its default API Resource.

  6. Click the Edit icon to edit the API resource.

    Edit API Resource

  7. Specify values for the required resource properties:

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

    Note: '{doctorType}' is an 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

    Edit API Resource Details

  8. Click Update.

Create the mediation logic

  1. Create two parallel message flows.

    In this scenario, the Healthcare API receives an HTTP GET request, which should be delivered to two different back-end services. That is, we need to clone the message into two branches and process them in parallel. To do that, we can use the Clone Mediator.

    Tip

    You can simply click on the + icon on each arrow in the message sequence flow to add any connector or mediator and you will see the available connectors as well as the mediators to the right of the editor.

    a. To get started, click on the + icon to add the first mediator.

    Add Mediator

    b. Select Clone mediator in the Flow Control section under All Mediators.

    Select Clone Mediator

    c. Click Submit.

    Add Clone Mediator

    We need to have two branches inside the Clone mediator.

    d. Click on the + sign to create the first branch.

    Add Branch

  2. Invoke the GrandOak Endpoint:

    The Call mediator is used to invoke a back-end service. In Step 2, we have already created an Endpoint to represent the GrandOak endpoint.

    a. Click on the + sign placed on the first branch of the Clone mediator.

    Add Call Mediator

    b. Select Call mediator from the Core section under All Mediators.

    Upon clicking you will see the Add Call pane where you can Invoke external services in blocking/non-blocking mode.

    c. Under Select Endpoint, select GrandOakEndpoint.

    Select Grandoakendpoint

    d. Click Submit.

  3. Construct message payload for the PineValley Endpoint:

    Note

    Unlike the GrandOAK endpoint, which accepts a simple GET request, the PineValley endpoint requires a POST request with the following JSON message:

    {
        "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.

    a. Click on the remaining + sign inside the Clone mediator to create the second branch of the Clone mediator, as shown below.

    Add Branch

    b. Click on the + sign placed on the second branch.

    Add Payload Mediator

    c. Select Payload mediator from the Transformation section under All Mediators.

    Payload mediator

    d. In the Add Payload interface, specify the values for the required PayloadFactory properties as shown below:

    Parameter Value
    Payload Format Inline
    Media Type json
    Payload { "doctorType": "1" }</td> </tr> <tr> <td>Args</td> <td>ctx:uri.var.doctorType

    Note

    The $1 in the Payload format denotes a parameter that can get a value assigned dynamically. The value for the parameters needs to be assigned using Arguments (Args).

    e. Specify the Argument Value by clicking on Add Parameter under Args.

    Add payload args

    f. Once you specify the Argument Value, click on the EX button next to the input field to enable the button.

    Argument value expression

    g. Then click on the Edit (pen) icon just on top of that.

    h. On the next interface that appears, set the Expression Value to $ctx:uri.var.doctorType and click Save.

    i. Click Save.

    j. Click Submit.

  4. Invoke the PineValley Endpoint

    Use the Call mediator to invoke the PineValley Endpoint. Let’s follow the same steps we used under ‘Invoke GrandOak Endpoint’ as below.

    a. Click + icon next to the PayloadFactory mediator.

    Add call mediator

    b. Select Call Mediator from the Core section under All Mediators.

    c. Under Select Endpoint, select PineValleyEndpoint.

    Add call pane

    d. Click Submit.

  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.

    a. Click + icon next to the Clone mediator.

    Add aggregate mediator

    b. Select Aggregate mediator from the Flow Control section under All Mediators.

    c. In the Add Aggregate interface, specify values for the required Aggregate mediator properties.

    Parameter Value
    Aggregation Expression json-eval($.doctors.doctor)

    Add aggregate pane

    d. Click Submit.

  6. Send a response back to the client

    Note

    To send the response back to the client, we can use the Respond mediator.

    a. To add the Respond mediator, click on the + icon inside the Aggregate mediator.

    b. Select Respond mediator from the Core section under All Mediators.

    Respond mediator

    c. Click Submit.

The final mediation configuration looks similar to the below diagram.

Final resource view

Following is what you will see in the Source View of the VS Code.

Info

You can view the source view by clicking on the Show Source (</>) icon located in the top right corner of the VS Code.

Show source view

<?xml version="1.0" encoding="UTF-8"?>
<api context="/healthcare" name="HealthcareAPI" xmlns="http://ws.apache.org/ns/synapse">
<resource methods="GET" uri-template="/doctor/{doctorType}">
    <inSequence>
  <clone>
      <target>
    <sequence>
        <call>
      <endpoint key="GrandOakEndpoint"/>
        </call>
    </sequence>
      </target>
      <target>
    <sequence>
        <payloadFactory media-type="json">
      <format>{
            "doctorType": "$1"
               }
      </format>
      <args>
          <arg evaluator="xml" expression="$ctx:uri.var.doctorType"/>
      </args>
        </payloadFactory>
        <call>
      <endpoint key="PineValleyEndpoint"/>
        </call>
    </sequence>
      </target>
  </clone>
  <aggregate>
      <completeCondition>
    <messageCount max="-1" min="-1"/>
      </completeCondition>
      <onComplete expression="json-eval($.doctors.doctor)">
    <respond/>
      </onComplete>
  </aggregate>
    </inSequence>
    <outSequence/>
    <faultSequence/>
</resource>
</api>

Step 3 - Build and run the artifacts

There are two main options to build and run the integration scenario.

Prerequisites

Before you begin, install Micro Integrator on your machine:

  1. Go to the WSO2 Micro Integrator web page, click Download, provide necessary details, and then click Zip Archive to download the Micro Integrator distribution as a ZIP file.

  2. Extract the ZIP file. The extracted folder will be referred as the <MI_HOME> folder.

Once you have downloaded and set up the Micro Integrator locally, follow the steps given below. Use one of the below two methods.

Option 1: Using the Visual Studio Code

  1. Click on the Command Palette on the top of the VS Code.

    Command palette

  2. Type > to show the available commands.

  3. Select MI: Add MI server.

  4. Select Add MI server.

  5. Select the folder where <MI_HOME> is located. This wll be set as the current server path.

    Current server path

  6. Run the project.

    Use one of the following two options to build and run the project:

    Option 1

    1. Click on the Command Palette on the top of the VS Code.
    2. Type > to show the available commands.
    3. Select MI: Build and Run.

    Option 2

    Click the Build and Run icon located on the top right corner of the VS Code.

    Build and run

Option 2: Using a local Micro Integrator instance

  1. Export the artifacts as a deployable CAR file

    a. Go to the MI Overview pane using the Home icon.

    Home icon

    b. Click the Build icon located in the top right corner of VS Code.

    Build and export

    c. Click the Export icon next to the Build icon.

    d. Select a destination to export the .car file.

    e. Once you select a folder the artifacts will be exported as a deployable car file to that location.

  2. Deploy the Healthcare service: Copy the exported CAR file of the Healthcare service to the <MI_HOME>/repository/deployment/server/carbonapps directory.

  3. Start the Micro Integrator.

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

    ./micro-integrator.sh
    
    micro-integrator.bat
    

Step 4 - Observe deployed artifacts

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

Once you have started the dashboard server, access the dashboard using the following sign in details.

Username Password
admin admin

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 Postman

    Let's invoke the API from Postman as follows:

    1. Open the Postman application. If you do not have the application, download it from here : Postman
    2. Create a collection with appropriate name. Ex : 'IntegrationStudio collection'.
    3. Add a new request to this collection and name it appropriately. Ex: 'Healthcare request'.
    4. In the 'Enter request URL' section paste our endpoint URL : http://localhost:8290/healthcare/doctor/Ophthalmologist
    5. Select 'GET' as http method and click 'Send' button.



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

      curl -v http://localhost:8290/healthcare/doctor/Ophthalmologist
      

    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"
            }
        ]
    ]