Quick Start Guide

In this guide, you'll build a simple integration using the Ballerina Integrator plugin. You'll create an HTTP service with a single resource named greeting that invokes the public Hello World API endpoint and returns the response.

Step 1: Install Visual Studio Code

Download and install Visual Studio Code.

Step 2: Install the WSO2 Ballerina Integrator extension

1. Go to the Extensions view by clicking the extension icon on the sidebar or pressing Ctrl + Shift + X on Windows and Linux, or Shift + ⌘ + X on a Mac.
2. Search for Ballerina Integrator in the extensions view search box.

3. Click on the Install button to install the Ballerina Integrator extension.

   

4. This will install the Ballerina Integrator and Ballerina extensions on VS Code.

Step 3: Set up Ballerina Integrator for the first time

1. Click on the Ballerina Integrator icon on the sidebar.

   

2. Click on the Set up Ballerina distribution button.

3. The setup wizard will install and configure the Ballerina distribution required for Ballerina Integrator.

4. Click on the Restart Now button to complete the setup.

   

Step 4: Create a new integration project

1. Click on the Ballerina Integrator icon on the sidebar.
2. Click on the Create New Integration button.
3. Enter the Integration Name as HelloWorld.
4. Select the project directory by clicking on the Select Path button.

5. Click on the Create Integration button to create the integration project.

   

Step 5: Create an integration service

Generate with AI

The integration service can also be generated using the AI-assistant. Click on the Generate with AI button and enter the following prompt, then press Add to Integration to generate the integration service.

Create an http service that has base path as /hello, and 9090 as the port. Add GET resource on /greeting that invokes https://apis.wso2.com/zvdz/mi-qsg/v1.0 endpoint and forward the response to the caller.

1. In the design view, click on the Add Artifact button.
2. Select HTTP Service under the Integration as API category.
3. Select the Create and use the default HTTP listener option from the Listeners dropdown.
4. Select the Design From Scratch option as the Service Contract.
5. Specify the Service base path as /hello.

6. Click on the Create button to create the new service with the specified configurations.

   

Step 6: Design the integration

1. The generated service will have a default resource named greeting with the GET method.
2. Click on the greeting resource to view the resource details. Let's modify the resource to invoke the HelloWorld API endpoint.
3. Hover over the arrow after start and click the ➕ button to add a new action to the resource.
4. Select Add Connection from the node panel.
5. Search for HTTP in the search bar and select HTTP as the connection type.
6. Change the Connection Name to externalEP.

7. Add the URL "https://apis.wso2.com" to the connection URL field and click Save.

   

8. Click the ➕ button again and select Connections -> externalEP -> get from the node panel.

9. Fill in the request details as below and click Save.

   Field	Value
   Variable Name	epResponse
   Variable Type	string
   Connection	externalEp
   Target Type	string
   Path	"/zvdz/mi-qsg/v1.0"

10. Click ➕ button again and select Return from the node panel.

11. Select the epResponse variable as the Expression from the dropdown and click Save. This step will return the response from the HelloWorld API endpoint.

    

Step 7: Run the integration

1. Click on the Run button in top right corner to run the integration.
2. The integration will be compiled and started in the embedded Ballerina runtime.
3. Once the integration is started, click on the Test button to open the embedded HTTP client.

4. Click on the Send button to invoke the greeting resource.

   

5. Additionally, you can test the integration using REST clients like Postman or curl.

   curl http://localhost:9090/hello/greeting
   {"message":"Hello World!!!"}%
   

6. Click on the ⏹️ button or press Shift + F5 shortcut to stop the integration.