10 Oct, 2023 | 3 min read

Explore the New and Improved WSO2 Micro Integrator Runtime Versioning System with Choreo

  • Rukshan Chathuranga
  • Technical Lead - WSO2

Photo by Kelly Sikkema on Unsplash


Choreo now allows you to specify WSO2’s Micro Integrator runtime version and update level when deploying integrations. Previously, Choreo defaulted all deployments of WSO2 Micro Integrator projects to a specific runtime version and update level. With this improvement, developers can specify the exact runtime version and update level required for their integrations. This improvement simplifies the development and troubleshooting process for integration developers.

Decoding WSO2 Micro Integrator’s Version String

WSO2 Micro Integrator employs semantic versioning, utilizing three digits to represent its version. It regularly releases updates for each product version, addressing bugs and introducing enhancements. A numerical update level identifies these updates.

In Choreo, a more refined versioning system consisting of a four-digit number is used. This version number is constructed by combining the product version and the update level. This new versioning approach is adopted as the WSO2 Micro Integrator runtime version in Choreo, helping identify the product version and its associated update level. Figure 1 shows this in practice.

Figure 1: Runtime version format

This enhanced versioning helps to identify WSO2 Micro Integrators’ runtime version and is convenient for users when specifying versions during development.

Using WSO2 Integration Studio to Manage the Runtime Version

WSO2 Integration Studio is crucial for developing integrations. One of its key features allows users to define the target runtime version when creating an integration project. This chosen version helps set up the local development environment within WSO2 Integration Studio, enabling users to test their integrations locally. Let’s explore the steps to create an integration project with a specified target runtime version using WSO2 Integration Studio.

Create an Integration

  1. As seen in Figure 2, open WSO2 Integration Studio and initiate a new integration project from the Getting Started tab.
  2. Assign a name to the project.
  3. Specify the desired runtime version, e.g.,

    Figure 2: Specifying the runtime version

  4. Click 'Finish' to complete the setup.
  5. Create a new REST API and provide a name for the API. e.g., EchoAPI.

    This is seen in Figure 3 below.

    Figure 3: Create a new REST API

  6. As seen in Figure 4, add a 'Respond Mediator' to send back the same request data or switch to source view and use the configurations below.
      <?xml version="1.0" encoding="UTF-8"?>
            <api context="/echo" name="EchoAPI" xmlns="">
                 <resource methods="GET POST">
                         <respond description="Respond result back"/>

    Figure 4: Adding response mediator

Test the Integration

Using WSO2 Integration Studio, developers can locally test their integrations by setting up a WSO2 Micro Integrator server instance that is linked to a locally running WSO2 Micro Integrator server.

Follow these steps to set up a WSO2 Micro Integrator server locally:

  1. Download WSO2 Micro Integrator Runtime from the product page.
  2. Utilise the built-in update tool to update the WSO2 Micro Integrator server to the desired update level.
  3. Once the WSO2 Micro Integrator server is up and running with the desired configuration, you can set it up within WSO2 Integration Studio.

How to Set up WSO2 Micro Integrator Runtime in WSO2 Integration Studio:

  1. Go to the Getting Started tab in WSO2 Integration Studio and click "Add Server."
  2. As seen in Figure 5, select "WSO2 Remote Server" from the WSO2 options and name it, e.g., "MI"

    Figure 5: Add WSO2 Remote server

  1. Click "Next."
  2. Add "https://localhost:9164/management" as the Server URL, as seen in Figure 6.
  3. Verify the server connection by clicking on “Test connection.”

    Figure 6: Confirm adding the WSO2 Remote server

Deploy the project:

  1. Right-click on the server created in the Servers tab and select "Add and Remove."
  2. Choose the available exporter projects from the left and move them to the right.

    Figure 7: Choose an exporter project for deployment

  1. Click "Finish."
  2. Check the logs to confirm that the new composite application (capp) is successfully deployed.
  3. To test the integration, use the terminal and execute the following curl command: 
     curl -X POST http://localhost:8290/echo -d “Hello Integration”
  1. If further changes are needed, modify and redeploy as needed.
  2. To redeploy the changes, click on the created server, right-click the deployed composite application, and select "Redeploy."

    Figure 8: Redeploy a composite application

WSO2 Micro Integrator Runtime Version Interpretation in Choreo Deployments

Choreo interprets the WSO2 Micro Integrator runtime version format according to the following table.

Format Example Description
Product version 4.1.0, 4.2.0 Deploy on the latest U2 level of the mentioned product version
U2 update level, Deploy on exact U2 level
GA Release, Deploy on the GA release(with no update) of the mentioned product version
Default version Empty value Deploy on the latest U2 level of the default product version

The runtime version is mentioned in the project's root pom in the integration development process, simplifying version management. When building the Choreo-compliant integration, Choreo collects all the necessary resources, including the WSO2 Micro Integrator runtime, configurations, and the appropriate Java runtime. This eliminates the need for users to worry about Java version compatibility, as Choreo intelligently selects the runtime that aligns with the project's requirements. Furthermore, Choreo ensures the WSO2 Micro Integrator runtime associated with the chosen product version and update level is readily available from a shared location, with automatic updates applied whenever new updates become available. This streamlines the development workflow and ensures that integrations run seamlessly with the correct runtime components.

Migrating Between Runtime Versions

Users may need to migrate their integrations when new improvements, features, and bug fixes become available. Fortunately, WSO2 Integration Studio makes this process straightforward. Users can reestablish their local development environment by downloading the desired WSO2 Micro Integrator product version and update level. Then, they can create a WSO2 Integration Studio remote service, pointing it to the new runtime. WSO2 Integration Studio supports multiple server runtimes, facilitating easy testing of integrations on different runtimes. If the integrations perform as expected, users can update the target runtime version in the integration project. To do this, they can access the project's root pom, locate the "project.runtime.version" element, and update the runtime version. Or they can right-click on the project and select the “Change Runtime MI Version” option to update the version. Then commit the changes to the version control system. This streamlined workflow simplifies the migration process and ensures that integrations stay up-to-date with the latest runtime improvements.

Figure 9: Update runtime version in the pom.xml

Figure 10: Update runtime version from the UI

Local testing plays a pivotal role in risk reduction in the integration development process. It is crucial to identify and mitigate potential issues when migrating across different versions. These migrations can introduce breaking changes, making it imperative to test integrations locally before deploying them to a production environment. Even after successful local testing, pushing changes to a development environment in Choreo remains essential. This ensures that integrations perform as expected in a particular Choreo environment, mirroring the local deployment conditions. Once all tests have passed in the development environment, integrations can be confidently promoted to the production environment. The key to a smooth migration lies in updating the project's runtime version, allowing for minimal changes and a seamless deployment process to production.


Choreo's new feature lets users deploy WSO2 Micro Integrator runtimes precisely, allowing them to specify versions, including product and update levels. This offers greater control and flexibility.

Local testing remains a cornerstone of integration development, ensuring reliability across different versions and in production. It ensures that integrations work seamlessly in the same environment where they were perfected. WSO2 Integration Studio supports these practices, making development and testing easier.

In a nutshell, this feature streamlines the process of transitioning to newer WSO2 Micro Integrator versions, giving you access to the latest improvements. It's a valuable asset for Choreo integration developers, offering enhanced control and efficiency. Why not give it a try and experience the benefits firsthand?