From 53489f1478f8ac6ca1f8f22da382546dbc5eee87 Mon Sep 17 00:00:00 2001 From: iamvirul Date: Mon, 15 Dec 2025 23:17:05 +0530 Subject: [PATCH 01/10] Add detailed documentation for `@mi:Operation` annotation in Ballerina module, including supported data types, compile-time validation, and runtime mapping examples. --- .../ballerina-module/overview.md | 81 ++++++++++++++++++- 1 file changed, 80 insertions(+), 1 deletion(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index 69684e8ec..7d97f3d89 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -75,12 +75,91 @@ For example, ```ballerina @mi:Operation {} public function gpa(xml rawMarks, xml credits) returns xml { - // Your logic to calculate the GPA + // Your logic to calculate the GPA } ``` Ballerina function that contains `@mi:Operation` annotation maps with an operation in the Ballerina module. +### Supported Data Types + +When you use the `@mi:Operation` annotation from the `wso2/mi` module, only a specific set of Ballerina types are supported. The compiler plugin (`@ballerina-module-wso2-mi`) enforces these at **compile time**, and the MI module generation tool (`@ballerina-mi-module-gen-tool`) maps them to MI connector parameters at **runtime**. + +#### Compile-time validation (`@mi:Operation`) + +The compiler plugin checks the parameter and return types of every function annotated with `@mi:Operation`. The allowed kinds are: + +| **Context** | **Supported Ballerina types** | +|------------------|--------------------------------------------------------------------------------------------------------------| +| **Parameters** | **Primitives:** `boolean`, `int`, `float`, `decimal`, `string`
**Structured:** `xml`, `json`, `record { ... }`, `map<...>`, `T[]` | +| **Return types** | **Primitives:** `()` (nil), `boolean`, `int`, `float`, `decimal`, `string`
**Structured / other:** `xml`, `json`, `any`, `record { ... }`, `map<...>`, `T[]` | + +If a parameter or return type is not in these categories, the build fails with diagnostics such as **"unsupported parameter type found"** or **"unsupported return type found"**. + +**Examples** + +```ballerina +import wso2/mi; + +// Primitive example +@mi:Operation +public function addInt(int a, int b) returns int { + return a + b; +} + +// JSON/XML example +@mi:Operation +public function mergeJson(json left, json right) returns json { + json|error merged = left.mergeJson(right); + if merged is error { + return { "status": "error" }; + } + return merged; +} + +// Record example +type Student record {| + string name; + int age; +|}; + +@mi:Operation +public function transformStudent(Student student) returns Student { + return { name: student.name.toUpperAscii(), age: student.age }; +} +``` + +#### Runtime mapping in MI (`mi-module-gen` tool) + +When you run the `bal mi-module-gen` tool, it inspects your Ballerina module and generates an MI connector. Supported Ballerina types are converted into connector metadata and UI elements as follows: + +- **Primitive types**: `string`, `int`, `float`, `decimal`, `boolean` +- **Structured types**: `json`, `xml`, `record { ... }`, `map<...>`, `T[]` + +At runtime: + +- **Function parameters** become connector **query/path/config parameters** and corresponding UI fields in the WSO2 MI VS Code extension. +- **Return types** are written to the configured response variable (for example, `result`) based on the generated `returnType` value in `functions/*.xml`. + +**Runtime example** + +```ballerina +remote function addIntegers(int first, int second) returns int|error { + return first + second; +} +``` + +After running: + +```bash +bal mi-module-gen -i +``` + +the generated connector will: + +- Expose `first` and `second` as integer input fields in the connector configuration. +- Set the operation `returnType` to `int`, so the result of `addIntegers` is written to the specified response variable in the MI mediation flow. + #### Generate the module 1. Use the `bal mi-module-gen` command to generate the WSO2 Integrator: MI module from Ballerina project. From 84e2c989f5d88a79e8e1370e9305d10bd2d07e57 Mon Sep 17 00:00:00 2001 From: iamvirul Date: Tue, 16 Dec 2025 11:16:09 +0530 Subject: [PATCH 02/10] Enhance documentation for `mi-module-gen` tool and `wso2/mi` module with links to Ballerina Central. --- en/docs/develop/customizations/ballerina-module/overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index 7d97f3d89..204068d42 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -50,7 +50,7 @@ There are two ways to use the Ballerina module in your WSO2 MI projects: #### Pull `mi-module-gen` tool -First, you need to pull the `mi-module-gen` tool which is used to create the WSO2 MI module. +First, you need to pull the `mi-module-gen` tool which is used to create the WSO2 MI module. The tool is available on [Ballerina Central](https://central.ballerina.io/wso2/mi_module_gen/0.4.3). ```bash bal tool pull mi-module-gen @@ -63,7 +63,7 @@ bal tool pull mi-module-gen #### Write Ballerina transformation Create a new Ballerina project using `bal new projectName` or use an existing one and write your transformation logic. -Import the module `wso2/mi` in your Ballerina program. +Import the module `wso2/mi` in your Ballerina program. The module is available on [Ballerina Central](https://central.ballerina.io/wso2/mi/0.4.0). ```ballerina import wso2/mi; @@ -83,7 +83,7 @@ Ballerina function that contains `@mi:Operation` annotation maps with an operati ### Supported Data Types -When you use the `@mi:Operation` annotation from the `wso2/mi` module, only a specific set of Ballerina types are supported. The compiler plugin (`@ballerina-module-wso2-mi`) enforces these at **compile time**, and the MI module generation tool (`@ballerina-mi-module-gen-tool`) maps them to MI connector parameters at **runtime**. +When you use the `@mi:Operation` annotation from the `wso2/mi` module, only a specific set of Ballerina types are supported. The [compiler plugin](https://central.ballerina.io/wso2/mi/0.4.0) enforces these at **compile time**, and the [MI module generation tool](https://central.ballerina.io/wso2/mi_module_gen/0.4.3) maps them to MI connector parameters at **runtime**. #### Compile-time validation (`@mi:Operation`) From 1c365465a01dd8e4b32068364e421865f7f3f583 Mon Sep 17 00:00:00 2001 From: iamvirul Date: Tue, 16 Dec 2025 11:22:40 +0530 Subject: [PATCH 03/10] Enhance documentation for Ballerina module types in overview.md --- en/docs/develop/customizations/ballerina-module/overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index 204068d42..5bd28734f 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -91,8 +91,8 @@ The compiler plugin checks the parameter and return types of every function anno | **Context** | **Supported Ballerina types** | |------------------|--------------------------------------------------------------------------------------------------------------| -| **Parameters** | **Primitives:** `boolean`, `int`, `float`, `decimal`, `string`
**Structured:** `xml`, `json`, `record { ... }`, `map<...>`, `T[]` | -| **Return types** | **Primitives:** `()` (nil), `boolean`, `int`, `float`, `decimal`, `string`
**Structured / other:** `xml`, `json`, `any`, `record { ... }`, `map<...>`, `T[]` | +| **Parameters** | **Primitives:** `boolean`, `int`, `float`, `decimal`, `string`
**Structured:** `xml`, `json`, `record { }`, `map` | +| **Return types** | **Primitives:** `()` (nil), `boolean`, `int`, `float`, `decimal`, `string`
**Structured / other:** `xml`, `json`, `any`, `record { }`, `map` | If a parameter or return type is not in these categories, the build fails with diagnostics such as **"unsupported parameter type found"** or **"unsupported return type found"**. @@ -134,7 +134,7 @@ public function transformStudent(Student student) returns Student { When you run the `bal mi-module-gen` tool, it inspects your Ballerina module and generates an MI connector. Supported Ballerina types are converted into connector metadata and UI elements as follows: - **Primitive types**: `string`, `int`, `float`, `decimal`, `boolean` -- **Structured types**: `json`, `xml`, `record { ... }`, `map<...>`, `T[]` +- **Structured types**: `json`, `xml`, `record { }`, `map`, `T[]` At runtime: From 2848caf0ffdac73e26b8d88a00fc6a07e00cd3c4 Mon Sep 17 00:00:00 2001 From: Virul Nirmala Wickramasinghe <89099391+iamvirul@users.noreply.github.com> Date: Tue, 16 Dec 2025 12:02:10 +0530 Subject: [PATCH 04/10] Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- en/docs/develop/customizations/ballerina-module/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index 5bd28734f..84a8f1c94 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -96,7 +96,7 @@ The compiler plugin checks the parameter and return types of every function anno If a parameter or return type is not in these categories, the build fails with diagnostics such as **"unsupported parameter type found"** or **"unsupported return type found"**. -**Examples** +##### Examples ```ballerina import wso2/mi; From 1ed8cb1b9a7c7285bb6b206c7c9a351d2754c2d1 Mon Sep 17 00:00:00 2001 From: Virul Nirmala Wickramasinghe <89099391+iamvirul@users.noreply.github.com> Date: Tue, 16 Dec 2025 12:06:32 +0530 Subject: [PATCH 05/10] Update en/docs/develop/customizations/ballerina-module/overview.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- en/docs/develop/customizations/ballerina-module/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index 84a8f1c94..c7c87ed08 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -141,7 +141,7 @@ At runtime: - **Function parameters** become connector **query/path/config parameters** and corresponding UI fields in the WSO2 MI VS Code extension. - **Return types** are written to the configured response variable (for example, `result`) based on the generated `returnType` value in `functions/*.xml`. -**Runtime example** +##### Runtime example ```ballerina remote function addIntegers(int first, int second) returns int|error { From d503df4bc4b08da343d65d62202e8012e317ab12 Mon Sep 17 00:00:00 2001 From: Virul Nirmala Wickramasinghe <89099391+iamvirul@users.noreply.github.com> Date: Mon, 22 Dec 2025 15:16:03 +0530 Subject: [PATCH 06/10] Update en/docs/develop/customizations/ballerina-module/overview.md Co-authored-by: Danesh Kuruppu --- en/docs/develop/customizations/ballerina-module/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index c7c87ed08..e3ce6e29b 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -50,7 +50,7 @@ There are two ways to use the Ballerina module in your WSO2 MI projects: #### Pull `mi-module-gen` tool -First, you need to pull the `mi-module-gen` tool which is used to create the WSO2 MI module. The tool is available on [Ballerina Central](https://central.ballerina.io/wso2/mi_module_gen/0.4.3). +First, you need to pull the `mi-module-gen` tool, which is used to create the WSO2 MI module. The tool is available on [Ballerina Central](https://central.ballerina.io/wso2/mi_module_gen/latest). ```bash bal tool pull mi-module-gen From 10135b4941adaf320a45baa0bc7b0e3dbb880f49 Mon Sep 17 00:00:00 2001 From: Virul Nirmala Wickramasinghe <89099391+iamvirul@users.noreply.github.com> Date: Mon, 22 Dec 2025 15:16:16 +0530 Subject: [PATCH 07/10] Update en/docs/develop/customizations/ballerina-module/overview.md Co-authored-by: Danesh Kuruppu --- en/docs/develop/customizations/ballerina-module/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index e3ce6e29b..06d3bb925 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -63,7 +63,7 @@ bal tool pull mi-module-gen #### Write Ballerina transformation Create a new Ballerina project using `bal new projectName` or use an existing one and write your transformation logic. -Import the module `wso2/mi` in your Ballerina program. The module is available on [Ballerina Central](https://central.ballerina.io/wso2/mi/0.4.0). +Import the module `wso2/mi` in your Ballerina program. The module is available on [Ballerina Central](https://central.ballerina.io/wso2/mi/latest). ```ballerina import wso2/mi; From 4c3420eff8b48a765892f4be49c9f69bd5ce763c Mon Sep 17 00:00:00 2001 From: Virul Nirmala Wickramasinghe <89099391+iamvirul@users.noreply.github.com> Date: Tue, 23 Dec 2025 10:41:07 +0530 Subject: [PATCH 08/10] Update overview.md Co-authored-by: Dilan Perera <39415471+RDPerera@users.noreply.github.com> --- en/docs/develop/customizations/ballerina-module/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index 06d3bb925..1df908728 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -83,7 +83,7 @@ Ballerina function that contains `@mi:Operation` annotation maps with an operati ### Supported Data Types -When you use the `@mi:Operation` annotation from the `wso2/mi` module, only a specific set of Ballerina types are supported. The [compiler plugin](https://central.ballerina.io/wso2/mi/0.4.0) enforces these at **compile time**, and the [MI module generation tool](https://central.ballerina.io/wso2/mi_module_gen/0.4.3) maps them to MI connector parameters at **runtime**. +When you use the `@mi:Operation` annotation from the `wso2/mi` module, a defined set of Ballerina data types is supported. The [compiler plugin](https://central.ballerina.io/wso2/mi/latest) enforces these at **compile time**, and the [MI module generation tool](https://central.ballerina.io/wso2/mi_module_gen/latest) maps them to MI connector parameters at **runtime**. #### Compile-time validation (`@mi:Operation`) From a5ac2148388d9d7028e3af8ab5bc91b9a7cb0514 Mon Sep 17 00:00:00 2001 From: Virul Nirmala Wickramasinghe <89099391+iamvirul@users.noreply.github.com> Date: Tue, 23 Dec 2025 13:39:06 +0530 Subject: [PATCH 09/10] Update en/docs/develop/customizations/ballerina-module/overview.md Co-authored-by: Dilan Perera <39415471+RDPerera@users.noreply.github.com> --- en/docs/develop/customizations/ballerina-module/overview.md | 1 - 1 file changed, 1 deletion(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index 1df908728..040514bf6 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -133,7 +133,6 @@ public function transformStudent(Student student) returns Student { When you run the `bal mi-module-gen` tool, it inspects your Ballerina module and generates an MI connector. Supported Ballerina types are converted into connector metadata and UI elements as follows: -- **Primitive types**: `string`, `int`, `float`, `decimal`, `boolean` - **Structured types**: `json`, `xml`, `record { }`, `map`, `T[]` At runtime: From 756b34e66596d714de02590e1f0288af779a904b Mon Sep 17 00:00:00 2001 From: Virul Nirmala Wickramasinghe <89099391+iamvirul@users.noreply.github.com> Date: Tue, 23 Dec 2025 13:39:13 +0530 Subject: [PATCH 10/10] Update en/docs/develop/customizations/ballerina-module/overview.md Co-authored-by: Dilan Perera <39415471+RDPerera@users.noreply.github.com> --- en/docs/develop/customizations/ballerina-module/overview.md | 1 - 1 file changed, 1 deletion(-) diff --git a/en/docs/develop/customizations/ballerina-module/overview.md b/en/docs/develop/customizations/ballerina-module/overview.md index 040514bf6..2474ac4d0 100644 --- a/en/docs/develop/customizations/ballerina-module/overview.md +++ b/en/docs/develop/customizations/ballerina-module/overview.md @@ -133,7 +133,6 @@ public function transformStudent(Student student) returns Student { When you run the `bal mi-module-gen` tool, it inspects your Ballerina module and generates an MI connector. Supported Ballerina types are converted into connector metadata and UI elements as follows: -- **Structured types**: `json`, `xml`, `record { }`, `map`, `T[]` At runtime: