Skip to content

Quick Start Guide

Let's get started with WSO2 Ballerina Integrator by running an integration use case in your local environment. This is a simple service orchestration scenario. The scenario is about a basic healthcare system where Ballerina Integrator is used to integrate two backend hospital services to provide information to the client.

Most healthcare centers have a system that is used to make doctor appointments. To check the availability of the doctors for a particular time, users need to visit the hospitals or use each and every online system that is dedicated for a particular healthcare center. Here we are making it easier for patients by orchestrating those isolated systems for each healthcare provider and exposing a single interface to the users.

alt text

In the above scenario, the following takes place:

  1. The client makes a call to the Healthcare service created using Ballerina Integrator.

  2. The Healthcare service calls the Pine Valley Hospital backend service and gets the queried information.

  3. The Healthcare service calls the Grand Oak Hospital backend service and gets the queried information.

  4. The response is returned to the client with the required information.

Both Grand Oak Hospital and Pine Valley Hospital have services exposed over HTTP protocol.

Pine Valley Hospital service accepts a POST request in following service endpoint URL.


The expected payload should be in the following JSON format.

    "doctorType": "<DOCTOR_TYPE>"

Grand Oak Hospital service accepts a GET request in following service endpoint URL.


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

Before you begin

  • Download and install Ballerina Integrator for your operating system

    Note: This installs Ballerina language version 1.0.1, a compiler plugin to help mitigate errors, and snippet .jar files for custom auto-completion.

  • Install Oracle JDK 1.8.*
  • Install VS Code

    Tip: For a better development experience, use VS Code (which is the recommended editor for Ballerina Integrator).

  • Install the Ballerina Integrator Extension from the VS Code marketplace
  • Download curl or a similar tool that can call an endpoint.

Once you have installed the VS Code extension, you could press Command + Shift + P in Mac or Ctrl + Shift + P in Windows/Linux and search for the command Ballerina Integrator: Dashboard to find the Ballerina Integrator dashboard shown below. Please refer the extension's home page for more details on how to use the provided features.

alt text

Create a Project, Add a Template, and Invoke the Service

Let's create a project using the Ballerina Integrator dashboard. To do this, click Create under the Quick Start Guide template.

A module is a directory that contains Ballerina source code files.

A new window will appear at the top of your screen where you can specify the name of your module.

alt text

Once you specify the name of the module, you need to choose if your project is a new project or an existing project. In this case you would choose New Project.

alt text

Once this is done, specify the name of your project in the window that appears and choose the location of your project in your local machine.

alt text

Note: Alternatively, you could use the command line to create your project and add the healthcare_service module.

Click here to create a project and add a pre-defined template using the command line instead. Create a new project by navigating to a directory of your choice and running the following command.

ballerina new quick-start-guide

You see a response confirming that your project is created.

Let's use a predefined module from Ballerina Central, which is a public directory that allows you to host templates and modules.

A template is a predefined code that solves a particular integration scenario.

In this case, we use the healthcare_service module. Run the following command to pull this module from Ballerina Central.

ballerina pull wso2/healthcare_service

Now navigate into the project directory you created.

cd quick-start-guide

The following command enables you to apply a predefined template you pulled.

ballerina add -t wso2/healthcare_service healthcare_service

This automatically creates a healthcare service for you inside an src directory.

A Ballerina service represents a collection of network accessible entry points in Ballerina. A resource within a service represents one such entry point. The generated sample service exposes a network entry point on port 9090.

From the command line, navigate to the src directory.

cd <project-and-module-location>/src

Build the service using the ballerina build command.

ballerina build -a

Tip: The -a command builds all modules in the project.

You get the following output.

Compiling source

Creating balos

Running tests
    No tests found

Generating executables

Run the following Java command to run the executable .jar file that is created once you build your module.

java -jar target/bin/healthcare_service.jar

Your service is now up and running. You can invoke the service using an HTTP client. In this case, we use cURL.

Tip: If you do not have cURL installed, you can download it from

curl http://localhost:9090/healthcare/doctor/physician

You get the following response.

      "name":"Shane Martin",
      "time":"07:30 AM",
      "hospital":"Grand Oak"
      "name":"Geln Ivan",
      "time":"08:30 AM",
      "hospital":"Grand Oak"
      "name":"Geln Ivan",
      "time":"05:30 PM",
      "name":"Daniel Lewis",
      "time":"05:30 PM",

You just started Ballerina Integrator, created a project, started a service, invoked the service you created, and received a response.

To have a look at the code, navigate to the hospital_service.bal file found inside your module.

Ballerina code

import ballerina/http;
import ballerina/log;

http:Client grandOakHospital = new("http://localhost:9091/grandOak");
http:Client pineValleyHospital = new("http://localhost:9092/pineValley");

@http:ServiceConfig {
    basePath: "/healthcare"
service healthcare on new http:Listener(9090) {

    @http:ResourceConfig {
        path: "/doctor/{doctorType}"
    resource function getDoctors(http:Caller caller, http:Request request, string doctorType) returns error? {
        json grandOakDoctors = {};
        json pineValleyDoctors = {};
        var grandOakResponse = grandOakHospital->get("/doctors/" + doctorType);
        var pineValleyResponse = pineValleyHospital->post("/doctors", {doctorType: doctorType});
        // Extract doctors array from grand oak hospital response
        if (grandOakResponse is http:Response) {
            json result = check grandOakResponse.getJsonPayload();
            grandOakDoctors = check;
        } else {
            handleError(caller, <@untained> grandOakResponse.reason());
        // Extract doctors array from pine valley hospital response
        if (pineValleyResponse is http:Response) {
            json result = check pineValleyResponse.getJsonPayload();
            pineValleyDoctors = check;
        } else {
            handleError(caller, <@untained> pineValleyResponse.reason());
        // Aggregate grand oak hospital's doctors with pine valley hospital's doctors
        if (grandOakDoctors is json[] && pineValleyDoctors is json[]) {
            foreach var item in pineValleyDoctors {
        // Respond back to the caller with aggregated json response
        http:Response response = new();
        response.setJsonPayload(<@untained> grandOakDoctors);
        var result = caller->respond(response);

        if (result is error) {
            log:printError("Error sending response", err = result);

function handleError(http:Caller caller, string errorMsg) {
    http:Response response = new;

    json responsePayload = {
        "error": {
            "message": errorMsg
    response.setJsonPayload(responsePayload, "application/json");
    var result = caller->respond(response);
    if (result is error) {
        log:printError("Error sending response", err = result);

What's Next