Automating WSO2 Integration Studio Project to MI 4.x Migration at Scale with a Go CLI Tool

Migrating from WSO2 Enterprise Integrator / Integration Studio to WSO2 Micro Integrator (MI) 4.x with the VS Code extension is becoming increasingly common as teams modernise their integration platforms.

WSO2 officially recommends using the VS Code extension for migration, and for many teams, that approach works perfectly. You open the legacy Integration Studio project in VS Code, follow the guided migration flow, and continue development in the new MI ecosystem.

But migration becomes a very different challenge when:

• You have dozens of Integration Studio projects
• Multiple teams are migrating simultaneously
• You want migration integrated into a CI/CD pipeline
• You need repeatable and auditable migration steps
• You want to reduce manual, repetitive work

That is exactly why I built the following:

wso2-is-esb-to-vscode-migrator

A lightweight Go CLI tool that automates the structural migration of WSO2 Integration Studio multi-module Maven projects into the newer flat project structure used by the MI 4.x VS Code Extension.

Understanding the Migration Challenge

The biggest challenge is that the two project structures are fundamentally different.

Old Structure — Integration Studio / ESB

Legacy WSO2 ESB projects are typically structured as multi-module Maven projects.

my-esb-project/
├── my-esb-project-config/       ← Synapse artifacts
├── my-esb-project-registry/     ← Registry resources
├── my-esb-project-mediators/    ← Java mediators
└── my-esb-project-car/          ← Composite application

Each concern is separated into its own Maven module.

New Structure — MI 4.x VS Code Extension

The newer MI tooling uses a flatter single-project structure.

my-esb-project-car/
├── pom.xml
├── src/main/
│   ├── java/
│   └── wso2mi/
│       ├── artifacts/
│       │   ├── apis/
│       │   ├── sequences/
│       │   └── templates/
│       └── resources/
│           └── registry/
└── deployment/
    ├── deployment.toml
    └── docker/Dockerfile

This new structure is cleaner and much more DevOps-friendly, but migrating manually can be repetitive and error-prone.

For one project, this is manageable.

For 20–50 projects, it becomes a serious migration bottleneck.

What the CLI Tool Automates

The tool performs the structural migration automatically.

The goal is not to replace WSO2 tooling.

The goal is to automate the repetitive structural work so teams can focus on reviewing and validating business logic.

Getting Started

Prerequisites

Before running the tool:

• Install Go 1.18+
• Install Git

Verify Go installation:

go version

Step 1 — Clone the Repository

git clone https://github.com/veneerac/wso2-is-esb-to-vscode-migrator.git
cd wso2-is-esb-to-vscode-migrator

Step 2 — Build the Tool

make build

This command:

• Compiles the binary
• Creates input/
• Creates output/
• Creates logs/

Step 3 — Add Legacy Projects

Copy one or multiple legacy Integration Studio projects into the input/ directory.

cp -r /path/to/my-old-studio-project ./input/

The tool supports batch migration.

Step 4 — Run the Migration

./migrate

Step 5 — Review the Output

Migrated projects will appear in:

output/

Detailed migration logs are generated per project:

logs/
└── my-old-studio-project/
    └── migration-my-old-studio-project.log

Optional — Migrate a Single Project Directly

Instead of copying projects in, you can migrate directly using the -project flag.

./migrate -project /path/to/my-old-studio-project

Connector Migration — The Hardest Part

One of the most difficult parts of migrating WSO2 Integration Studio projects is connector handling.

Legacy projects commonly use connector syntax such as:

<fileconnector.read>
<salesforcerest.query>

In MI 4.x, connectors require updated initialisation patterns.

Simply copying XML artefacts without handling connector initialisation often results in broken deployments.

How the Tool Handles Connectors

The migration tool performs several validation and preparation steps automatically.

1. Detects Connector Usage

The tool scans XML artefacts for connector-style patterns:

<name.operation>

2. Generates Warnings

Every detected connector is logged:

• Console output
• Migration log files

This makes the connector review visible and traceable.

3. Creates a connectors/ Review Folder

The tool generates connector initialisation templates inside:

connectors/

4. Generates a Review Checklist

A file named:

connectors/REVIEW_REQUIRED.md

is generated automatically with connector-specific review instructions.

Connector Handling Examples

Detected ConnectorMigration Actionfileconnector / fileGenerates MI 4. x-compatible file.init template salesforcerestCopies existing init configuration and flags for review. Unknown connectors. Generates a placeholder and a warning

After migration:

1. Review generated connector files
2. Update credentials/endpoints/paths
3. Move finalised files into:

src/main/wso2mi/artifacts/local-entries/

before building the project.

CI/CD Integration

Important: WSO2 officially recommends using the VS Code Extension migration flow for standard project migration.

However, for organisations migrating many projects, automation becomes extremely valuable.

This CLI tool works well inside:

• GitHub Actions
• Jenkins
• GitLab CI
• Ansible
• Docker-based build pipelines
• Bash automation scripts

Example GitHub Actions Pipeline

- name: Migrate IS projects
  run: |
    ./migrate -input-dir ./legacy-projects -output-dir ./migrated -logs-dir ./migration-logs

- name: Upload migrated projects
  uses: actions/upload-artifact@v3
with:
    name: migrated-projects
    path: ./migrated/

Why Automation Helps

Automating migration provides several operational benefits.

Reproducibility

The same project structure produces the same migration output every time.

Auditability

Migration logs can be stored as CI artefacts for compliance and troubleshooting.

Parallel Execution

Large migration programmes can process multiple project batches simultaneously.

Reduced Manual Work

Teams spend less time reorganising folders and more time validating integration behaviour.

What Still Requires Manual Review

The tool intentionally focuses on structural migration.

Some areas still require engineering validation.

Why is a review of connector credentials and endpoints needed? Environment-specific values cannot be auto-generated safely. Custom mediator logic, Java dependencies, or APIs may need updates. Environment-specific properties should move into deployment.toml environment variables. Complex connector flows. Some connectors require manual MI-specific configuration

The goal is to accelerate migration, not hide critical review steps.

Open Source Repository

The project is available on GitHub:

GitHub Repository

https://github.com/veneerac/wso2-is-esb-to-vscode-migrator

Feedback, issues, and pull requests are always welcome.

If your team uses connectors that are not yet supported, feel free to open an issue with sample tags, and I can add support templates.

Final Thoughts

Migration projects are rarely just about technology.

They are also about:

• Reducing repetitive engineering effort
• Improving migration consistency
• Making modernization scalable
• Creating repeatable operational processes

WSO2’s VS Code tooling is a major improvement for MI development, and for teams migrating at scale, automation can significantly reduce the migration burden.