Manual Guide: Actions¶

1. Overview & Module Architecture¶

The Actions module or integration Actions serves as the core script execution and building block engine in MdlWr.

An Action is a modular unit of work containing executable Python code alongside configurations for target endpoints, authentication types, security certificates, timeouts, and retry parameters. These actions are designed to be invoked and orchestrated seamlessly within Logic Flows.

2. User Interface & Data Table Layout¶

The Actions management screen provides a high-density, searchable data table backed by server-side processing to handle enterprise-scale configurations.

Key Data Columns¶

ID: Displays a truncated unique identifier (last 8 characters) for quick referencing.
Category: Organizes actions into logical folders/groups.
Name: The human-readable title of the action.
Target URL: The destination endpoint associated with the action script.
Auth Type / Cred Key / Cert Path: Security parameters defining how the action authenticates with external resources.
Active Status: Visual indicator showing whether the action is enabled. Inactive rows are dynamically highlighted with warning text colors.

Standard Table Operations¶

For complete guidelines on how to use standard table utility features (such as ColVis, copying data, Export/Import, Refresh, Bulk Delete, etc.), please refer to the Standard Tables Guide.

3. Action Configuration Fields (Off-Canvas Form)¶

When creating or editing an action via the drawer form (#integration_form), the following parameters are available:

Field Name	Type	Description
Category	Dropdown (`select2`)	Organizes the action into custom catalog categories.
Name	Text Input	Unique, descriptive name for the action.
Description	Textarea	Summary notes detailing what the action performs.
Technical Doc	File Upload	Attaches supplemental documentation files (stored under `/static/exports/documentation/`).
Target URL	Text Input	Destination URL or hostname/IP address targeted by the script.
Auth Type	Dropdown	Authentication protocol to apply: `None`, `Basic`, or `Token`.
Cred Key	Dropdown (`select2`)	References stored credentials for secure authentication lookups.
Cert Path	Dropdown (`select2`)	Selects SSL/TLS certificates required for secure connections.
Retry Count	Numeric Input	Number of automatic retries upon execution failure.
Timeout (sec)	Numeric Input	Maximum execution duration allowed before timing out.
Active	Checkbox	Toggles the operational state of the action.

5. Action Payload & Attachment Architecture¶

When a request hits a Logic Flow (via webhook or API trigger), the system normalizes the data and wraps it into an items array format passed directly to the action step.

Complete Sample Payload Structure (with Attachments)¶

{
  "items": [
    {
      "body_raw": {
        "document_title": "Invoice Report Q2",
        "submitted_by": "Ikhsan"
      },
      "external_id": "INV-2026-0801",
      "files": {
        "attachment_file": {
          "filename": "invoice_q2.pdf",
          "content_type": "application/pdf",
          "size_bytes": 45210,
          "storage_path": "/tmp/mdlwr_uploads/invoice_q2.pdf"
        }
      },
      "integration_cert_path": null,
      "integration_cred_key": null,
      "integration_id": "019ee917-c969-7dab-ba66-72a3d85bfa4c",
      "integration_name": "SAMPLE - Document Processor",
      "integration_params": {
        "upload_folder": "/var/data/invoices"
      },
      "integration_retry_count": 0,
      "integration_target_url": "mdlwr-app:5000",
      "job_id": "019fba41-cc96-70b5-b48c-3d3dd0729942",
      "json": {
        "document_title": "Invoice Report Q2",
        "submitted_by": "Ikhsan"
      },
      "mdlwr_id": "MDLWR-20260801061915123-AB92",
      "metadata": {
        "current_node_id": "integration-019ed871-1c37-753f-842a-06676ee48f22",
        "depth": 0,
        "external_id": "INV-2026-0801",
        "has_attachments": true,
        "is_sync": true,
        "job_id": "019fba41-cc96-70b5-b48c-3d3dd0729942",
        "logic_flow_id": "019f12b8-6d36-72cb-8b27-3e904bfdb945",
        "parent_canvas_id": "root-e85570cc-461d-4458-a6e7-954cbee8a0da",
        "sniffer_mode": "MULTIPART_FORM",
        "trace_id": "WEB-2F3F26BC342C47CE",
        "trigger_mode": "SYNC"
      },
      "request": {
        "args": {},
        "headers": {
          "Content-Type": "multipart/form-data",
          "Host": "127.0.0.1"
        },
        "payload": {
          "document_title": "Invoice Report Q2"
        }
      },
      "trace_id": "WEB-2F3F26BC342C47CE"
    }
  ]
}

6. Action Script Editor & Standard Template¶

Why Python? In MdlWr, the core execution and data transformation logic rely on Python as the primary free-scripting language. Rather than locking developers into rigid, pre-built templates or heavy enterprise frameworks, MdlWr utilizes Python to deliver ultimate flexibility, agility, and performance.

Key Advantages of Python in MdlWr¶

Dynamic Flexibility vs. Rigid Templates

Traditional integration platforms often restrict engineers with rigid, drag-and-drop boxes or strict visual-only workflows that break when facing unique business logic. Python provides dynamic, code-level flexibility, allowing engineers to handle complex edge cases, custom data mapping, cryptographic hashing, and data transformations effortlessly.
Lightweight & Agile Execution

Unlike compiled or heavyweight enterprise languages (such as Java, which requires strict class structures, verbose boilerplate code, and resource-intensive runtimes like the JVM), Python offers:

Minimal Overhead: Bypasses heavy compilation steps, making it ideal for rapid, on-demand script execution inside the integration pipeline.

Agile Runtime: Lightweight process management that keeps resource consumption low, ensuring smooth performance even under high concurrency.
Universal Industry Standard

Python is widely recognized as the global standard for backend automation, scripting, and data manipulation. This ensures:

Zero Steep Learning Curve: Almost any IT engineer, systems integrator, or developer can immediately write, test, and debug scripts without learning a proprietary language.

Extensive Ecosystem: Seamless integration with standard libraries to parse JSON/XML, make HTTP requests, handle regex, and connect with external services out-of-the-box.

Standard Python Script Template (`Action Template`)¶

Every custom script in an integration action must follow a standardized structure to ensure safe payload handling, secure credential fetching, and seamless error tracing.

def process(req):
    import json
    from apps.helpers.integration_helper import get_integration_secrets
    from apps.helpers.email_helper import queue_email

    # -------------------------------
    # 1. Normalize payload
    # -------------------------------
    logs = []    # Will be shown in incoming logs only 
    result = []  # Default response of this api
    success = False # Default success is False

    # Ensure input is always handled as a list to support iteration
    items = req.get("items", [])
    if not isinstance(items, list):
        items = [req]

    for item in items:
        # -------------------------------
        # 2. Parse input JSON & Record Data
        # -------------------------------
        # Automatically fetched from the Action record configured in the database
        TARGET_URL = item.get("integration_target_url")
        PARAMS = item.get("integration_params")

        # Retrieve secure credentials and certificates based on Action record relations
        secrets = get_integration_secrets(
            cred_key=item.get('integration_cred_key'), 
            cert_key=item.get('integration_cert_path')
        )
        USERNAME = secrets.get('username')
        PASSWORD = secrets.get('password')
        CERT_PATH = secrets.get('cert_file')

        try:
            # Retrieve body_raw from the initial input 
            #(can be a JSON string or dict object)
            body_raw = item.get("body_raw", {})

            # Handle if body_raw is a string
            if isinstance(body_raw, str):
                body = json.loads(body_raw)
            else:
                body = body_raw

            logs.append(f"Parsed body: {body}")
        except Exception as e:
            logs.append(f"Failed to parse JSON: {str(e)}")
            # Return failure when parsing fails
            return {"success": False, "logs": logs}

        logs.append("Processing one item")

        # -------------------------------
        # 3. Do operation (Business Logic Execution)
        # -------------------------------
        # result.append(operation_status)

        # Sample usage of asynchronous email helper
        """
        email_record = queue_email(
            to="admin@example.com",
            subject="Integration Notification",
            body="Job processed successfully",
            html=True,
            module="INTEGRATION_ACTION",
            reference_id=item.get("job_id")
        )
        """

        # -------------------------------
        # 4. Append results/log per item
        # -------------------------------
        success = True
        logs.append("Item processed")

    # -------------------------------
    # 5. Return aggregated result
    # -------------------------------
    return {"success": success, "result": result, "logs": logs}

Detailed Script Mechanics & Architecture Breakdown:¶

Fetching Data from Action Records (integration_target_url, cred_key, etc.)
- Configuration parameters like integration_target_url, integration_cred_key, and integration_cert_path do not need to be hardcoded inside the script. They are automatically injected by the platform based on the UI form settings.
- The get_integration_secrets() helper securely bridges the Cred Key and Cert Path to look up, decrypt, and provide the correct username, password, or file path at runtime.
Handling Payload Data (body_raw)
- body_raw represents the raw payload data incoming from an external webhook or a preceding step in a Logic Flow.
- The script safely checks whether body_raw is a string format (parsing it via json.loads) or already a native dictionary object, preventing type mismatch errors.
Multiple JSON / Looping Mechanism (Items Array)
```
items = req.get("items", [])
if not isinstance(items, list):
    items = [req]
```
The system guarantees workflow flexibility via payload normalization, How it works:

If the payload is passed as a single object, the script automatically wraps it into a list containing one item.

If the payload contains multiple items in bulk structured as an array under the items key, the script will loop through each item seamlessly (for item in items:), optimizing asynchronous fan-out processing across workers.
Python Script Best Practices¶
- Always Wrap in Try-Except: Catch unexpected errors gracefully during parsing or data mapping, and append the exception message to the logs array for quick troubleshooting via the UI.
- Leverage the Log Array: Use logs.append() extensively during development stages so you can monitor step-by-step execution directly from Incoming Logs.
- Use Built-in Helpers: Utilize get_integration_secrets() to safely retrieve credentials and cert paths without hardcoding sensitive data inside your scripts.
Audit Logs & Version History The module maintains strict compliance and tracking via two supplementary audit mechanisms:
1. Execution Logs: Tracks runtime health, latency, request/response payloads, and historical execution results for each specific action.
2. Deleted History Log:
  - Captures change summaries when actions are modified or deleted.
  - Double-clicking or clicking the View button on any deleted log entry opens a detailed change modal itemizing exact fields and prior values.
  - Supports secure batch-purging of historical logs via the deletion toolbar controls.
Import & Export Package Workflow To facilitate migration between development, staging, and production environments, Mdlwr supports robust ZIP packaging:
1. Export: Select one or more rows in the data table and click Export. The platform generates a timestamped .zip file (e.g., mdlwr_integration_20260801_...zip).
2. Import Preview:
  - Upload an export .zip file via the import modal.
  - The system reads the archive and generates an itemized preview breakdown separating Actions, Credentials, Calendars, and Logic Flows.
  - Existing entries are flagged with status badges (e.g., Overwrite / Exists).
  - Uncheck any items you wish to exclude, then click Confirm Import to safely merge or update configurations.