Add documentation for configuring runtime argument schema for automation

en/docs/quick-start-guides/configure-runtime-argument-schema.md

@@ -0,0 +1,224 @@
+---
+title: Configure Runtime Argument Schemas
+description: Define structured runtime argument input forms for automations using component.yaml runtimeArguments in schema version 1.2.
+---
+
+## Prerequisite
+
+1. Create or import an automation. See [Schedule Your First Automation](schedule-your-first-automation.md).
+
+=== "WSO2 Integrator: BI"
+    ## WSO2 Integrator: BI
+
+    Devant derives the runtime argument schema from configured Ballerina entry/startup parameters and auto-generates `component-model.json`.
+
+    ### Step 1: Open the automation in Cloud Editor
+    1. Open the automation **Overview** page.
+    2. Click **Open in Cloud Editor**.
+
+    ### Step 2: Add Startup Parameters
+    1. In WSO2 Integrator: BI, go to **Automation** and click **Configure**.
+    2. Expand **Advanced Configurations** and click **Add Parameter**.
+    3. Select a type, provide a name, and click **Add**.
+
+    ### Step 3: Push changes and build
+    1. Click **Create** or **Save**.
+    2. Push changes and wait until build status is **Completed**.
+
+        <div style="width: 100%;">
+        ![Configure startup parameters in BI](../../assets/img/get-started/configure-runtime-argument-schema/runtime-args-bi.gif)
+        </div>
+
+    ### Step 4: Verify the generated runtime argument form
+
+    1. In Devant, go to the automation **Overview** page, click **Test with Arguments**.
+
+        <div style="width: 100%;">
+        ![Open generated runtime argument form](../../assets/img/get-started/configure-runtime-argument-schema/runtime-args-bi-trigger.gif)
+        </div>
+
+    ### Supported argument types
+
+    - `string`
+    - `int`
+    - `float`
+    - `decimal`
+    - `byte`
+
+=== "component.yaml (v1.2)"
+    ## component.yaml (v1.2)
+    Define runtimeArguments in .choreo/component.yaml to render a structured, validated runtime argument form in Devant.
+
+    ### Step 1: Create or update `.choreo/component.yaml`
+
+    1. In your project root, create `.choreo/component.yaml` if it does not exist.
+    2. Set `schemaVersion: 1.2`.
+
+    ### Step 2: Add `runtimeArguments`
+
+    1. Define runtime arguments based on your automation use case.
+    2. Include required fields such as `name` and `type`.
+
+    ### Step 3: Push changes and build
+
+    1. Commit and push your changes.
+    2. Wait until build status is **Completed**.
+
+    ### Step 4: Verify the generated runtime argument form
+
+    1. In Devant, go to the automation **Overview** page, click **Test with Arguments**.
+
+    ### Supported argument types
+
+    | Type | Notes |
+    |---|---|
+    | `string` | Text input |
+    | `number` | Numeric input |
+    | `boolean` | Flag-style argument (must include `prefix`) |
+    | `enum` | Dropdown selection (requires `values`) |
+
+    !!! note
+        Variadic (`string...`-style) input is supported with `repeat: true` for non-boolean types.
+
+    **Runtime argument object fields**
+
+    | Field | Required | Description |
+    |----|----|----|
+    | `name` | Yes | Unique argument key. Must be a valid identifier. |
+    | `type` | Yes | Argument type: `string`, `number`, `boolean`, `enum`. |
+    | `displayName` | No | Display label shown in the UI form. |
+    | `description` | No | Helper text shown to users in the form. |
+    | `required` | No | Whether input is mandatory. Default is `true` (except boolean behavior rules). |
+    | `prefix` | No | CLI flag prefix (for example, `--region`, `-D`). Must be unique if used. |
+    | `delimiter` | No | Separator between prefix and value: `""`, `"="`, or `":"`. |
+    | `values` | Conditional | Required only when `type: enum`. |
+    | `repeat` | No | Enables repeated values (`string...` style). Default is `false`. |
+
+    ### Sample component.yaml for HR service automation
+
+    **Use case:** Employee onboarding request automation
+
+    ```yaml
+    # +required The configuration file schema version
+    schemaVersion: 1.2
+
+    # +optional Incoming connection details for the component
+    endpoints: []
+
+    # +optional Outgoing connection details for the component
+    dependencies: {}
+
+    # +optional Runtime configurations
+    configurations:
+      env:
+        - name: jiraToken
+          valueFrom:
+            configForm:
+              displayName: Jira API token
+              required: true
+              type: secret
+
+    # +optional Runtime argument schema
+    runtimeArguments:
+      - name: employeeName
+        displayName: Employee name
+        type: string
+
+      - name: employeeId
+        displayName: Employee ID
+        type: number
+
+      - name: departmentName
+        displayName: Department
+        type: enum
+        values: ["Engineering", "Sales", "HR", "Finance", "Operations"]
+
+      - name: locatedFloor
+        displayName: Office floor
+        type: enum
+        values: ["1","2","3","4"]
+
+      # Must be the last positional argument
+      - name: requiredAssets
+        displayName: Required assets
+        description: Add each requested item such as laptop, monitor, keyboard, mouse.
+        type: string
+        repeat: true
+
+      - name: sendWelcomeEmail
+        displayName: Send welcome email
+        type: boolean
+        prefix: --send-welcome-email
+
+      - name: priority
+        displayName: Ticket priority
+        type: number
+        prefix: --priority
+        delimiter: "="
+
+      - name: notifyGroup
+        displayName: Notify group
+        type: string
+        repeat: true
+        prefix: --notify
+        delimiter: "="
+    ```
+    ### Common runtime argument patterns
+
+    === "Boolean flag"
+        ```yaml
+        - name: enableMonitoring
+          displayName: Enable monitoring
+          type: boolean
+          prefix: --enable-monitoring
+        ```
+        Result: `--enable-monitoring`
+
+    === "Key-value argument"
+        ```yaml
+        - name: deployProfile
+          displayName: Deploy profile
+          type: string
+          prefix: --profile
+          delimiter: "="
+        ```
+        Result: `--profile=prod`
+
+    === "Repeated argument"
+        ```yaml
+        - name: label
+          displayName: Label
+          type: string
+          prefix: --label
+          delimiter: "="
+          repeat: true
+        ```
+        Result: `--label=team-a --label=critical --label=backend`
+
+    ### Validation rules
+
+    - `name` must be unique across all runtime arguments.
+    - `prefix` (if set) must be unique across all runtime arguments.
+    - `values` is required only for `type: enum`; do not define it for other types.
+    - `delimiter` can only be `""`, `"="`, or `":"`.
+    - Do not define `delimiter` for positional arguments (without `prefix`).
+    - Do not define `delimiter` for `boolean` arguments.
+    - `boolean` arguments:
+        - must include `prefix`,
+        - cannot be `required: true`,
+        - cannot be `repeat: true`.
+    - Only one positional variadic argument is allowed (`repeat: true` without `prefix`).
+    - Do not define positional arguments after a positional variadic argument.
+    - For positional arguments, required ones must come before optional ones.
+
+    !!! note
+        `enum` arguments render as dropdowns and values are validated against the `values` list.
+
+    ### UI behavior
+    When a valid runtime argument schema is available, Devant renders typed input fields, enum dropdowns, repeat controls, and pre-execution validation.
+    If no schema is available, Devant falls back to generic argument input.
+
+    ### Current limitations
+    - Dynamic flag-name generation is not supported (for example, user-defined key names inside `-D<key>=<value>`).
+    - Cross-argument dependency validation is not supported (for example, enforcing `--ssl-key` when `--ssl-cert` is provided).
+    - Subcommand hierarchies are not supported.

en/docs/quick-start-guides/schedule-your-first-automation.md

@@ -54,14 +54,47 @@ This redirects you to the **Create New Integration in VS Code** page.
 3. Add an appropriate commit message and commit.
 4. Click **Sync Changes** to push the changes to remote.
 
-## Step 5: Schedule Automation
+## Optional: Test the automation manually
+
+!!! note "Prerequisite"
+         Ensure the build has completed successfully (Build Status: `Completed`) before testing. You can view the Build History by clicking **Build** in the left navigation.
+
+You can execute your automation directly from the **Development** card on the **Overview** page:
+
+1. On the Overview page, locate the **Development** card.
+2. Click **Test** to run your automation immediately.
+
+    !!! info "Inject Dynamic Values into Your Application as Command-Line Arguments"
+        To pass dynamic values to your application when testing manually, follow these steps:
+
+        1. Click the drop-down icon next to **Test** and then click **Test with Arguments**.
+        2. In the **Runtime Arguments** pane, enter the arguments you want to pass to your application.
+        3. Click **Execute**. This triggers the task with the specified arguments.
+
+        To define a structured and validated runtime argument form, see [Configure Runtime Argument Schema](configure-runtime-argument-schema.md).
+
+        The capability to run a manual task with arguments is supported for the following build presets:
+
+        === "WSO2 MI"
+            To explore a WSO2 MI-based manual task with arguments, try out the [Weather to Logs Task](https://github.com/wso2/choreo-samples/tree/main/weather-to-logs-mi-manual-task) sample. For instructions, see the `README.md` file in the sample repository.
+
+            !!! info
+                When working on WSO2 MI projects and deploying a WSO2 MI integration as a manual task in Devant, use the WSO2 MI automation mode. For details, see [Running the Micro Integrator in Automation Mode](https://mi.docs.wso2.com/en/latest/install-and-setup/install/running-the-mi-in-automation-mode/).
+
+        === "WSO2 BI"
+            To explore a Ballerina manual task with arguments, try out the [Weather to Email Task](https://github.com/wso2/choreo-samples/tree/main/weather-to-email-integration) sample. For instructions, see the `README.md` file in the sample repository.
+
+            !!! info
+                If you want to pass arguments to Ballerina main functions, use the **Test with Arguments** capability. For details on the arguments you can pass, see the [Ballerina documentation](https://ballerina.io/learn/by-example/main-function/). You can also override configurable values in the same manner. For more information, see [Provide values to configurable variables](https://ballerina.io/learn/provide-values-to-configurable-variables/#provide-via-command-line-arguments).
+
+## Step 5: Schedule automation
 
 1. Once you push the changes, the overview page of the Devant automation will automatically refresh and show you the **Latest Commit** and automatically build your automation showing the **Build Status**.
 
     !!! note
-        The build process may take some time. Once complete, the build status changes to **Success**. You can see the Build History by clicking **Build** in the left navigation.
+        The build process may take some time. Once complete, the build status changes to **Completed**. You can see the Build History by clicking **Build** in the left navigation.
 
-2. Once the **Build Status** shows `Build completed`, click **Test** to run your automation once.
+2. Once the **Build Status** shows `Completed`, you can test your automation. See the [Optional: Test the automation manually](#optional-test-the-automation-manually) section for detailed instructions on testing, including testing with runtime arguments.
 3. The development card automatically updates with execution details. Click the refresh button in the top right corner if it is not automatically updated.
 4. Click **View Logs** on an execution. You will see the `Hello World` log printed along with the execution time.
 5. Click **Schedule** to schedule the automation.
@@ -75,7 +108,12 @@ This redirects you to the **Create New Integration in VS Code** page.
     </div>
 
 10. After successfully testing, you can promote your automation to production by clicking the **Promote** button.
-11. In critical environments (Production), you will be able to see automation metrics such as:
+11. Once promoted to production, click **Run** to run your automation immediately.
+
+    !!! info
+        If you want to pass runtime arguments when running in production, use the **Run with Arguments** option in the same way as described above in the [Test the Automation manually](#optional-test-the-automation-manually) section.
+
+12. In critical environments (Production), you will be able to see automation metrics such as:
 
     - **Error Rate**: Percentage of failed executions
     - **Average Duration**: Average time taken for executions

en/mkdocs.yml

@@ -78,6 +78,7 @@ nav:
       - Develop Your First Integration as API: quick-start-guides/develop-your-first-integration-as-api.md
       - Develop Your First Event Integration: quick-start-guides/develop-your-first-event-integration.md
       - Develop Your First File Integration: quick-start-guides/develop-your-first-file-integration.md
+      - Configure Runtime Argument Schema : quick-start-guides/configure-runtime-argument-schema.md
   - Devant Samples:
       - Explore the Samples Collection:
           - Samples Overview: devant-samples/samples-overview.md