How to Expose Several Services as a Single Service¶

What you'll build¶

When information from several services is required to construct a response to a client request, service chaining needs to be implemented. This means integrating several services based on some business logic and exposing them as a single, aggregated service.

In this tutorial, when a client sends a request for a medical appointment, the Micro Integrator performs several service calls to multiple back-end services to construct a response that includes all the necessary details. The HTTP connector will be used to invoke services sequentially within a single integration flow.

You will also use the Payload mediator to transform the response from one back-end service into the format required by another service.

Concepts and artifacts used¶

Let's get started!¶

Step 1: Set up the workspace¶

You need Visual Studio Code (VS Code) with the Micro Integrator for VS Code extension installed.

Info

See the Install Micro Integrator for VS Code documentation to learn how to install Micro Integrator for VS Code.

Step 2: Develop the integration artifacts¶

Follow the instructions given in this section to create and configure the required artifacts.

Create an integration project¶

The Integration project will contain all the required artifacts for the integration solution.

Launch VS Code with the Micro Integrator extension installed.
Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.
Click Create New Project on Design View.

Next, the Project Creation Form will be opened.
In the Project Creation Form, enter ExposeSeveralServicesTutorial as the Project Name.
Provide a location under Select Project Directory.
Click Create.

Now let's start designing the integration by adding the necessary artifacts.

Create HTTP connections¶

Let's create an HTTP connection to represent all three back-end services: Hospital Service, Channeling Service, and Payment Service.

Navigate to MI Project Explorer.
Click on Add artifact.
Click + View More under Create an Integration.
Select Connections under Other Artifacts to open the Connector Store Form.
Select HTTP.

In the Add New Connection form, specify the following values to create the new HTTP connection.

Property	Value	Description
Connection Name	`CommonServiceConn`	The name of the connection.
Base URL	`http://localhost:9090`	The base URL used to send requests to the back-end service.

Click Add.

You have now created the connection that is required for this tutorial.

Create a REST API¶

In the MI Project Explorer click on + Add artifact.
Select API under Create an Integration.

Specify values for the required REST API properties:

Property	Value	Description
Name	`HealthcareAPI`	The name of the REST API.
Context	`/healthcare`	Here you are anchoring the API in the `/healthcare` context. This will become part of the name of the generated URL used by the client when sending requests to the Healthcare service. For example, setting the context to `/healthcare` means that the API will only handle HTTP requests where the URL path starts with `http://host:port/healthcare`.

Click Create. This opens the Service Designer interface.

You can now start configuring the API resource.
On the Service Designer, click on the three dots (⋮) and then Edit to access the Properties of the default API resource.

Enter the following details:

Property	Value	Description
Resource Path	`/categories/{category}/reserve`	The request URL should match this resource path. The `{category}` variable will be replaced with the value sent in the request.
Methods	`POST`	This API resource will accept POST requests.

Click Update.

Update the mediation flow¶

You can now start updating the API resource with the mediation flow.

To get started, click on the Start node on the canvas to set an input payload for the integration flow.

Note

Setting an input payload for the integration flow is not mandatory. However, it is recommended, as it will be used to enable expression suggestions which you will explore in later steps of this tutorial.

Click Add Request, provide the following JSON payload, then click Add. Finally, click Save to complete the input payload setup.

{
    "patient":{
        "name":"John Doe",
        "dob":"1940-03-19",
        "ssn":"234-23-525",
        "address":"California",
        "phone":"8770586755",
        "email":"[email protected]"
    },
    "doctor":"thomas collins",
    "hospital_id":"grandoaks",
    "hospital":"grand oak community hospital",
    "cardNo":"7844481124110331",
    "appointment_date":"2025-04-02"
}

We need to use the Hospital ID (hospital_id) and card number (cardNo) in multiple HTTP calls later in the integration flow. To avoid losing these values, we will store them using the Variable mediator so that they can be easily reused throughout the flow.

Click on the + icon on the canvas to open the Mediator Palette.
Under Mediators, select the Variable mediator.
Provide hospital_id as the variable name. In the next, we will extract the Hospital ID from the incoming payload and assign it to this variable.
Click on the expression () icon to enable expression mode for the Value field.
Once expressions are enabled, click on the expression editor () icon to open the editor. Then, select Payload → hospital_id to extract the Hospital ID from the request payload.
Click Add to insert the Variable mediator into the integration flow.
Next, add a new Variable mediator right after the previous one. This mediator will extract and store the card number from the incoming payload.

Similar to the previous steps, you can use the expression editor to select Payload → cardNo, or simply copy and paste the following details.

Property	Description
Name	Enter `CardNumber`.
Data Type	Select `STRING`.
Value	Follow the steps given below to specify the expression value: Click the expression () icon in the Value field. This specifies the value type as an expression. Enter `payload.cardNo` as the expression value.

Click Add to insert the second Variable mediator into the integration flow.
Search for post in the Mediator Palette to add the HTTP POST operation after the Variable mediator.

In the pane that appears, specify the following values.

Property	Description
Connection	Select `CommonServiceConn`.
Relative Path	`/${vars.hospital_id}/categories/${params.pathParams.category}/reserve`
Response Variable Name	`HospitalServiceRes`.

Note

We will leave the rest of the configurations as defaults: Content Type set to JSON, Request Body as ${payload}, and Overwrite Message Body checked.

Info

The output variable(HospitalServiceRes) of the HTTP call contains the following data:
- Attributes – Metadata such as the status code.
- Headers – The response headers of the HTTP call.
The response body from the HTTP call will be assigned to the message payload, which you can access using the Synapse expression ${payload}.

Info

A response similar to the following will be returned from different hospital services such as GrandOaks, Clemency, or PineValley.

{
    "appointmentNumber": 1,
    "doctor": {
        "name": "thomas collins",
        "hospital": "grand oak community hospital",
        "category": "surgery",
        "availability": "9.00 a.m - 11.00 a.m",
        "fee": 7000.0
    },
    "patient": {
        "name": "John Doe",
        "dob": "1990-03-19",
        "ssn": "234-23-525",
        "address": "California",
        "phone": "8770586755",
        "email": "[email protected]"
    },
    "fee": 7000.0,
    "confirmed": false
}

Let's use Variable mediators to extract and store the Appointment Number, Doctor, and Patient details from the received response.

Click on the + icon on the canvas to add another Variable mediator after the HTTP POST operation to extract and store the value received as appointmentNumber.

In the Add Variable Mediator pane, provide the following details.

Property	Description
Name	Enter `AppointmentId`.
Data Type	Select `STRING`.
Value	Follow the steps given below to specify the expression value: Click the expression () icon in the Value field. This specifies the value type as an expression. Enter `payload.appointmentNumber` as the expression value.

Similarly, add two more Variable mediators to extract and store the doctor and patient details from the received response.

To store doctor details:

Property	Description
Name	Enter `DoctorDetails`.
Data Type	Select `JSON`.
Value	Follow the steps given below to specify the expression value: Click the expression () icon in the Value field. This specifies the value type as an expression. Enter `payload.doctor` as the expression value. Note: This is the synapse expression that will extract the doctor's details from the request payload.

To store patient details:

Property	Description
Name	Enter `PatientDetails`.
Data Type	Select `JSON`.
Value	Follow the steps given below to specify the expression value: Click the expression () icon in the Value field. This specifies the value type as an expression. Enter `payload.patient` as the expression value. Note: This is the synapse expression that will extract the patient details from the request payload.

Click on the + icon after the Variable mediator and select the HTTP GET operation from the Mediator Palette.

Tip

You can search for get in the Mediator Palette to quickly find the HTTP GET operation.

In the pane that appears, specify the following values.

Property	Description
Connection	Select `CommonServiceConn`.
Relative Path	`/${vars.hospital_id}/categories/appointments/${vars.AppointmentId}/fee`

Info

A response similar to the following will be returned from the Channeling service.

{
    "patientName": " John Doe ",
    "doctorName": "thomas collins",
    "actualFee": "7000.0"
}

To invoke the payment service in the next steps, you first need to construct the following request payload. We will use the Payload mediator to create it.

{
    "appointmentNumber": 2,
    "doctor": {
        "name": "thomas collins",
        "hospital": "grand oak community hospital",
        "category": "surgery",
        "availability": "9.00 a.m - 11.00 a.m",
        "Fee": 7000.0
    },
    "patient": {
        "name": "John Doe",
        "dob": "1990-03-19",
        "ssn": "234-23-525",
        "address": "California",
        "phone": "8770586755",
        "email": "[email protected]"
    },
    "fee": 7000.0,
    "Confirmed": false,
    "card_number": "1234567890"
}

Click on the + icon after the HTTP GET operation and select the Payload mediator to construct the above request payload.

In the Add Payload Mediator pane that appears, enter the following template in the Payload box and ensure that the Content Type is set to JSON.

{
    "appointmentNumber":${vars.AppointmentId},
    "doctor":${vars.DoctorDetails},
    "patient":${vars.PatientDetails},
    "fee":${payload.actualFee},
    "confirmed":"false",
    "card_number":"${vars.CardNumber}"
}

Note

Values inside ${...} are inline expressions dynamically fetching data during the flow.
vars refers to values stored using Variable mediators, while payload refers to the current message body.
This constructed payload will be sent to the Payments service for payment processing.

Field	Description
appointmentNumber	Retrieved from the variable `AppointmentId`, which stores the appointment ID extracted earlier.
doctor	Retrieved from the variable `DoctorDetails`, which contains the doctor's details.
patient	Retrieved from the variable `PatientDetails`, which contains the patient's details.
fee	Extracted from the `actualFee` field of the current message payload (the response payload of the HTTP GET call).
confirmed	Hardcoded to `false` to indicate that the appointment is not yet confirmed.
card_number	Retrieved from the variable `CardNumber`, containing the customer's card number.

Click Add to insert the Payload mediator into the integration flow.

Tip

When you use a Payload mediator, it replaces (overwrites) the current message body with the new payload you define. If you need to keep any previous payload data, make sure to store it in a variable before using the Payload mediator.
Click on the + icon after the Payload mediator and select the HTTP POST operation from the Mediator Palette.
In the Add POST pane, enter the following details and click Submit to add the HTTP POST operation.

Property Description

Connection Select CommonServiceConn.

Relative Path /healthcare/payments

Note

We will leave the rest of the configurations as defaults: Content Type set to JSON, Request Body as ${payload}, and Overwrite Message Body checked.
Click on the + icon after the HTTP POST operation and select the Respond mediator from the Mediator Palette to send the response back to the client.

Step 3: Build and run the artifacts¶

Now that you have developed an integration using the Micro Integrator for the Visual Studio Code plugin, it's time to deploy the integration to the Micro Integrator server runtime.

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

Step 4: Test the use case¶

Let's test the use case by sending a simple client request that invokes the service.

Start the back-end service¶

Download the JAR file of the back-end service from here.
Open a terminal, and navigate to the location where you saved the back-end service.
Execute the following command to start the service:
```
java -jar Hospital-Service-JDK11-2.0.0.jar
```

Send the client request¶

Now, let's test the integration service. For that, you can use the inbuilt try-it functionality in the MI for VS Code extension.

When you run the integration artifact as in Step 3, the Runtime Services interface is opened up. You can see all the available services.

Select the HealthcareAPI you have developed and test the resource using the following category and payload.

Category surgery

Payload


            {
                "patient":{
                    "name":"John Doe",
                    "dob":"1940-03-19",
                    "ssn":"234-23-525",
                    "address":"California",
                    "phone":"8770586755",
                    "email":"[email protected]"
                },
                "doctor":"thomas collins",
                "hospital_id":"grandoaks",
                "hospital":"grand oak community hospital",
                "cardNo":"7844481124110331",
                "appointment_date":"2025-04-02"
            }

This JSON payload contains details of the appointment reservation, which includes patient details, doctor, hospital, and date of appointment.

Optionally, you can use Postman or cURL to send the request. You can refer to the following request information.

Method	`POST`
Headers	`Content-Type=application/json`
URL	`http://localhost:8290/healthcare/categories/surgery/reserve` The URI-Template format that is used in this URL was defined when creating the API resource: `http://host:port/healthcare/categories/{category}/reserve`
Body	`{ "patient": { "name": "John Doe", "dob": "1940-03-19", "ssn": "234-23-525", "address": "California", "phone": "8770586755", "email": "[email protected]" }, "doctor": "thomas collins", "hospital_id": "grandoaks", "hospital": "grand oak community hospital", "cardNo": "7844481124110331", "appointment_date": "2025-04-02" }`

Analyze the response¶

You will see the following response received to your HTTP Client:

{
    "patient":"John Doe",
    "actualFee":7000.0,
    "discount":20,
    "discounted":5600.0,
    "paymentID":"480fead2-e592-4791-941a-690ad1363802",
    "status":"Settled"
}

You have now learned how the Micro Integrator can perform service chaining using the HTTP connector and transform message payloads between different formats using the Payload mediator.