BaasixBaasix

Workflow Routes

← Back to Documentation Home

Table of Contents

  1. Overview
  2. Workflow Management
  3. Workflow Execution
  4. Testing & Validation
  5. Statistics & Monitoring
  6. Webhook Triggers
  7. Role-Based Access Control
  8. Node Types Reference
  9. Trigger Types Reference
  10. Template Variables

Overview

Baasix Workflow Manager provides a comprehensive workflow automation system with a visual drag-and-drop builder and powerful execution engine. It supports 17 different node types, 4 trigger types, real-time execution monitoring, and multi-tenant isolation.

Key Features

  • Visual Workflow Builder: Drag-and-drop interface using React Flow
  • 17 Node Types: HTTP, Transform, Condition, Service, Loop, Filter, Aggregate, Delay, Notification, Email, Workflow, Stats, File, Variable, Script, Try-Catch, Trigger
  • 4 Trigger Types: Manual, Webhook, Schedule (cron), Hook (on data changes)
  • Real-time Execution Monitoring: Track workflow execution with detailed logs via Socket.IO
  • Template Variables: Use {{trigger.field}}, {{outputs.node-id.data}}, {{variables.name}} syntax
  • Multi-tenant Support: Full tenant isolation for workflows and executions
  • Error Handling: Comprehensive error tracking and logging with try-catch nodes
  • Role-Based Access Control: Restrict workflow execution to specific roles (for manual, hook, and webhook triggers)

Database Collections

baasix_Workflow

Stores workflow definitions.

Fields:

  • id (String, max 100): Primary key - human-readable workflow identifier (e.g., "send-welcome-email", "process-order")
  • name (String): Workflow name
  • description (Text): Workflow description
  • status (ENUM): active, inactive, draft
  • trigger_type (ENUM): manual, webhook, schedule, hook
  • trigger_config (JSONB): Trigger configuration
  • flow_data (JSONB): React Flow diagram data (nodes, edges)
  • variables (JSONB): Global workflow variables
  • options (JSONB): Additional options
  • allowed_roles (JSON Array): Array of role IDs that can execute this workflow (applies to manual and hook triggers only). Empty array or null allows all authenticated users.
  • tenant_Id (UUID): Multi-tenant support

baasix_WorkflowExecution

Tracks workflow execution instances.

Fields:

  • id (UUID): Primary key
  • workflow_Id (String): Reference to workflow (matches workflow.id)
  • status (ENUM): queued, running, completed, failed, cancelled
  • trigger_data (JSONB): Data that triggered the workflow
  • context_data (JSONB): Execution context and variables
  • result_data (JSONB): Final workflow result
  • error_message (Text): Error details if failed
  • started_at, completed_at (DateTime): Timing info
  • duration_ms (Integer): Execution duration

baasix_WorkflowExecutionLog

Stores logs for each node execution.

Fields:

  • id (UUID): Primary key
  • execution_Id (UUID): Reference to execution
  • node_id (String): React Flow node ID
  • node_type (String): Type of node
  • node_label (String): User-defined label
  • status (ENUM): pending, running, success, failed, skipped
  • input_data (JSONB): Node input
  • output_data (JSONB): Node output
  • error_message (Text): Error details
  • duration_ms (Integer): Node execution duration

Workflow Management

List Workflows

Retrieve a list of workflows with filtering and pagination.

  • URL: /items/baasix_Workflow
  • Method: GET
  • Auth required: Yes

Query Parameters

ParameterTypeRequiredDescription
fieldsstringNoComma-separated list of fields to return
sortstringNoField(s) to sort by (JSON string)
filterstringNoFilter conditions (JSON string)
limitintegerNoNumber of items to return (default: 100)
pageintegerNoPage number for pagination (default: 1)

Example Request

GET /items/baasix_Workflow?filter={"status":"active"}&sort={"createdAt":"desc"}&limit=20
Authorization: Bearer <token>

Success Response

  • Code: 200 OK
  • Content:
{
  "data": [
    {
      "id": "user-registration-workflow",
      "name": "User Registration Workflow",
      "description": "Automated user registration process",
      "status": "active",
      "trigger_type": "hook",
      "trigger_config": {
        "collection": "users",
        "action": "items.create.after"
      },
      "createdAt": "2025-01-10T10:30:00Z"
    }
  ],
  "totalCount": 15
}

Get Single Workflow

Retrieve a single workflow with full flow data.

  • URL: /items/baasix_Workflow/:id
  • Method: GET
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow

Example Request

GET /items/baasix_Workflow/user-registration-workflow
Authorization: Bearer <token>

Success Response

  • Code: 200 OK
  • Content:
{
  "data": {
    "id": "user-registration-workflow",
    "name": "User Registration Workflow",
    "description": "Automated user registration process",
    "status": "active",
    "trigger_type": "hook",
    "trigger_config": {
      "collection": "users",
      "action": "items.create.after"
    },
    "flow_data": {
      "nodes": [
        {
          "id": "trigger-1",
          "type": "trigger",
          "position": { "x": 100, "y": 100 },
          "data": { "label": "Trigger" }
        },
        {
          "id": "transform-1",
          "type": "transform",
          "position": { "x": 300, "y": 100 },
          "data": {
            "label": "Format Email",
            "transformType": "mapping",
            "mapping": {
              "email": "trigger.email",
              "fullName": "trigger.firstName + ' ' + trigger.lastName"
            }
          }
        }
      ],
      "edges": [
        {
          "id": "e1",
          "source": "trigger-1",
          "target": "transform-1"
        }
      ]
    },
    "variables": {
      "apiKey": "your-api-key"
    }
  }
}

Create Workflow

Create a new workflow.

  • URL: /items/baasix_Workflow
  • Method: POST
  • Auth required: Yes

Request Body

Note: The id field is required and must be a unique, human-readable string (max 100 characters). Use URL-safe slugs like "send-welcome-email" or "user-registration-workflow".

{
  "id": "send-welcome-email",
  "name": "New Workflow",
  "description": "Description of the workflow",
  "status": "draft",
  "trigger_type": "manual",
  "trigger_config": {},
  "flow_data": {
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "position": { "x": 100, "y": 100 },
        "data": { "label": "Trigger" }
      }
    ],
    "edges": []
  },
  "variables": {}
}

Success Response

  • Code: 201 Created
  • Content:
{
  "data": {
    "id": "send-welcome-email"
  }
}

Update Workflow

Update an existing workflow.

  • URL: /items/baasix_Workflow/:id
  • Method: PATCH
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow

Request Body

{
  "name": "Updated Workflow Name",
  "status": "active",
  "flow_data": {
    "nodes": [...],
    "edges": [...]
  }
}

Success Response

  • Code: 200 OK
  • Content:
{
  "data": {
    "id": "user-registration-workflow"
  }
}

Delete Workflow

Delete a workflow and its executions.

  • URL: /items/baasix_Workflow/:id
  • Method: DELETE
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow

Success Response

  • Code: 200 OK
  • Content:
{
  "data": {
    "id": "user-registration-workflow"
  }
}

Workflow Execution

Execute Workflow

Execute a workflow manually.

  • URL: /workflows/:id/execute
  • Method: POST
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow

Request Body

{
  "data": {
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Success Response

  • Code: 200 OK
  • Content:
{
  "message": "Workflow execution started",
  "execution": {
    "id": "650e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "createdAt": "2025-01-10T10:30:00Z"
  }
}

Error Responses

  • Code: 400 Bad Request

    • Content: { "error": { "message": "Workflow is not active" } }

  • Code: 404 Not Found

    • Content: { "error": { "message": "Workflow not found" } }

Get Execution History

Retrieve execution history for a workflow.

  • URL: /workflows/:id/executions
  • Method: GET
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow

Query Parameters

ParameterTypeRequiredDescription
filterstringNoFilter conditions (JSON string)
sortstringNoField(s) to sort by (JSON string)
limitintegerNoNumber of items to return (default: 100)
pageintegerNoPage number for pagination (default: 1)
fieldsstringNoComma-separated list of fields to return

Example Request

GET /workflows/user-registration-workflow/executions?filter={"status":"completed"}&sort={"createdAt":"desc"}&limit=10
Authorization: Bearer <token>

Success Response

  • Code: 200 OK
  • Content:
{
  "data": [
    {
      "id": "650e8400-e29b-41d4-a716-446655440000",
      "workflow_Id": "user-registration-workflow",
      "status": "completed",
      "trigger_data": {
        "email": "user@example.com"
      },
      "result_data": {
        "success": true
      },
      "started_at": "2025-01-10T10:30:00Z",
      "completed_at": "2025-01-10T10:30:05Z",
      "duration_ms": 5000
    }
  ],
  "totalCount": 25
}

Get Execution Details

Get detailed information about a specific execution.

  • URL: /workflows/:id/executions/:executionId
  • Method: GET
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow
executionIdstringYesID of the execution

Example Request

GET /workflows/user-registration-workflow/executions/650e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>

Success Response

  • Code: 200 OK
  • Content:
{
  "data": {
    "id": "650e8400-e29b-41d4-a716-446655440000",
    "workflow_Id": "user-registration-workflow",
    "status": "completed",
    "trigger_data": {
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "context_data": {
      "variables": {},
      "outputs": {
        "transform-1": {
          "email": "user@example.com",
          "fullName": "John Doe"
        }
      }
    },
    "result_data": {
      "success": true,
      "finalOutput": "Completed successfully"
    },
    "started_at": "2025-01-10T10:30:00Z",
    "completed_at": "2025-01-10T10:30:05Z",
    "duration_ms": 5000,
    "logs": [
      {
        "id": "750e8400-e29b-41d4-a716-446655440000",
        "node_id": "trigger-1",
        "node_type": "trigger",
        "node_label": "Trigger",
        "status": "success",
        "input_data": {},
        "output_data": {
          "email": "user@example.com",
          "firstName": "John",
          "lastName": "Doe"
        },
        "duration_ms": 10,
        "createdAt": "2025-01-10T10:30:00Z"
      },
      {
        "id": "750e8400-e29b-41d4-a716-446655440001",
        "node_id": "transform-1",
        "node_type": "transform",
        "node_label": "Format Email",
        "status": "success",
        "input_data": {
          "email": "user@example.com",
          "firstName": "John",
          "lastName": "Doe"
        },
        "output_data": {
          "email": "user@example.com",
          "fullName": "John Doe"
        },
        "duration_ms": 50,
        "createdAt": "2025-01-10T10:30:00.100Z"
      }
    ]
  }
}

Get Execution Logs

Get logs for a specific execution.

  • URL: /workflows/:id/executions/:executionId/logs
  • Method: GET
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow
executionIdstringYesID of the execution

Example Request

GET /workflows/user-registration-workflow/executions/650e8400-e29b-41d4-a716-446655440000/logs
Authorization: Bearer <token>

Success Response

  • Code: 200 OK
  • Content:
{
  "data": [
    {
      "id": "750e8400-e29b-41d4-a716-446655440000",
      "node_id": "trigger-1",
      "node_type": "trigger",
      "node_label": "Trigger",
      "status": "success",
      "input_data": {},
      "output_data": {
        "email": "user@example.com"
      },
      "duration_ms": 10,
      "createdAt": "2025-01-10T10:30:00Z"
    }
  ]
}

Cancel Execution

Cancel a running workflow execution.

  • URL: /workflows/:id/executions/:executionId/cancel
  • Method: POST
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow
executionIdstringYesID of the execution

Success Response

  • Code: 200 OK
  • Content:
{
  "message": "Execution cancelled successfully",
  "data": {
    "id": "650e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled"
  }
}

Error Responses

  • Code: 400 Bad Request
    • Content: { "error": { "message": "Cannot cancel completed execution" } }

Testing & Validation

Test Workflow

Test a workflow with sample data without saving the execution.

  • URL: /workflows/:id/test
  • Method: POST
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow

Request Body

{
  "triggerData": {
    "email": "test@example.com",
    "firstName": "Test",
    "lastName": "User"
  },
  "saveExecution": false
}

Success Response

  • Code: 200 OK
  • Content:
{
  "message": "Workflow test completed",
  "execution": {
    "status": "completed",
    "duration_ms": 2500,
    "logs": [
      {
        "node_id": "trigger-1",
        "status": "success",
        "output_data": {
          "email": "test@example.com"
        }
      }
    ]
  }
}

Validate Workflow

Validate a workflow configuration before saving.

  • URL: /workflows/validate
  • Method: POST
  • Auth required: Yes

Request Body

{
  "flow_data": {
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "data": { "label": "Trigger" }
      },
      {
        "id": "http-1",
        "type": "http",
        "data": {
          "label": "API Call",
          "url": "https://api.example.com/users",
          "method": "GET"
        }
      }
    ],
    "edges": [
      {
        "source": "trigger-1",
        "target": "http-1"
      }
    ]
  }
}

Success Response

  • Code: 200 OK
  • Content:
{
  "valid": true,
  "errors": [],
  "warnings": []
}

Validation Errors Response

  • Code: 200 OK
  • Content:
{
  "valid": false,
  "errors": [
    "Workflow must have exactly one trigger node",
    "Node 'http-1' has no incoming connection"
  ],
  "warnings": [
    "Workflow has 2 orphaned nodes"
  ]
}

Statistics & Monitoring

Get Workflow Statistics

Get execution statistics for a workflow.

  • URL: /workflows/:id/stats
  • Method: GET
  • Auth required: Yes

URL Parameters

ParameterTypeRequiredDescription
idstringYesID of the workflow

Example Request

GET /workflows/user-registration-workflow/stats
Authorization: Bearer <token>

Success Response

  • Code: 200 OK
  • Content:
{
  "data": {
    "total": 150,
    "byStatus": {
      "completed": 120,
      "failed": 15,
      "running": 5,
      "queued": 10
    },
    "avgDuration": 2500,
    "lastExecution": "2025-01-10T10:30:00Z",
    "successRate": 0.88
  }
}

Webhook Triggers

Execute via Webhook

Trigger a workflow via webhook URL.

  • URL: /workflows/webhook/:webhookId
  • Method: POST
  • Auth required: No (public endpoint)

URL Parameters

ParameterTypeRequiredDescription
webhookIdstringYesWebhook ID from trigger_config

Request Body

Any JSON data will be passed as trigger data to the workflow.

{
  "event": "user.created",
  "data": {
    "email": "newuser@example.com",
    "name": "New User"
  }
}

Success Response

  • Code: 200 OK
  • Content:
{
  "message": "Workflow execution started",
  "execution": {
    "id": "650e8400-e29b-41d4-a716-446655440000",
    "status": "queued"
  }
}

Error Responses

  • Code: 404 Not Found
    • Content: { "error": { "message": "Webhook not found" } }

Role-Based Access Control

Overview

Baasix Workflow Manager supports role-based access control (RBAC) for manual and hook trigger types. This feature allows you to restrict workflow execution to users with specific roles, providing fine-grained control over who can trigger workflows in your application.

Key Points:

  • Role restrictions apply only to manual and hook trigger types
  • Webhook and schedule triggers are not affected by role restrictions
  • Empty or null allowed_roles array allows all authenticated users to execute the workflow
  • Multiple roles can be specified - users with any of the listed roles can execute the workflow

Configuring Allowed Roles

To configure role-based access for a workflow, include the allowed_roles field when creating or updating a workflow:

Create Workflow with Role Restrictions

POST /items/baasix_Workflow
Content-Type: application/json
Authorization: Bearer <token>

{
  "id": "admin-data-export",
  "name": "Admin Data Export",
  "description": "Export sensitive data - admin only",
  "status": "active",
  "trigger_type": "manual",
  "allowed_roles": [
    "550e8400-e29b-41d4-a716-446655440000",
    "650e8400-e29b-41d4-a716-446655440001"
  ],
  "flow_data": {
    "nodes": [...],
    "edges": [...]
  }
}

Update Workflow to Add Role Restrictions

PATCH /items/baasix_Workflow/user-registration-workflow
Content-Type: application/json
Authorization: Bearer <token>

{
  "allowed_roles": [
    "750e8400-e29b-41d4-a716-446655440000"
  ]
}

Remove Role Restrictions

To remove role restrictions and allow all authenticated users:

PATCH /items/baasix_Workflow/user-registration-workflow
Content-Type: application/json
Authorization: Bearer <token>

{
  "allowed_roles": []
}

Examples

Example 1: Admin-Only Manual Workflow

Create a workflow that only users with the "Admin" role can execute:

{
  "id": "delete-old-records",
  "name": "Delete Old Records",
  "description": "Cleanup workflow for administrators",
  "status": "active",
  "trigger_type": "manual",
  "allowed_roles": ["admin-role-id"],
  "flow_data": {
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "data": { "label": "Start" }
      },
      {
        "id": "service-1",
        "type": "service",
        "data": {
          "operation": "delete",
          "collection": "old_records",
          "filter": { "createdAt": { "lt": "2024-01-01" } }
        }
      }
    ],
    "edges": [
      { "source": "trigger-1", "target": "service-1" }
    ]
  }
}

When a non-admin user tries to execute this workflow:

POST /workflows/delete-old-records/execute
Authorization: Bearer <non-admin-token>

Response:

{
  "error": {
    "message": "You do not have permission to execute this workflow",
    "code": 403
  }
}

Example 2: Hook Workflow with Manager Access

Create a hook workflow that only managers can trigger (via data changes):

{
  "id": "approve-large-order",
  "name": "Approve Large Orders",
  "description": "Triggered when large orders are created - requires manager approval",
  "status": "active",
  "trigger_type": "hook",
  "trigger_hook_collection": "orders",
  "trigger_hook_action": "items.create.after",
  "allowed_roles": ["manager-role-id", "admin-role-id"],
  "flow_data": {
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "data": { "label": "Order Created" }
      },
      {
        "id": "condition-1",
        "type": "condition",
        "data": {
          "operator": "AND",
          "conditions": [
            { "field": "trigger.amount", "operator": "greater_than", "value": 10000 }
          ]
        }
      },
      {
        "id": "notification-1",
        "type": "notification",
        "data": {
          "userId": "{{trigger.managerId}}",
          "title": "Large Order Requires Approval",
          "message": "Order #{{trigger.id}} for ${{trigger.amount}} needs approval"
        }
      }
    ],
    "edges": [
      { "source": "trigger-1", "target": "condition-1" },
      { "source": "condition-1", "target": "notification-1", "sourceHandle": "true" }
    ]
  }
}

Behavior:

  • When a user with "manager" or "admin" role creates a large order, the workflow executes and sends a notification
  • When a regular user creates a large order, the workflow is skipped and no notification is sent
  • The system logs: "Skipping workflow approve-large-order - user does not have required role"

Example 3: Multiple Roles Allowed

Create a workflow accessible to multiple roles:

{
  "id": "generate-report",
  "name": "Generate Monthly Report",
  "description": "Available to analysts, managers, and admins",
  "status": "active",
  "trigger_type": "manual",
  "allowed_roles": [
    "analyst-role-id",
    "manager-role-id",
    "admin-role-id"
  ],
  "flow_data": {
    "nodes": [...],
    "edges": [...]
  }
}

Behavior:

  • Users with any of the three roles can execute this workflow
  • Uses OR logic - having one of the roles is sufficient

Example 4: Public Workflow (No Restrictions)

Create a workflow accessible to all authenticated users:

{
  "id": "update-profile",
  "name": "Update User Profile",
  "description": "Available to all authenticated users",
  "status": "active",
  "trigger_type": "manual",
  "allowed_roles": [],
  "flow_data": {
    "nodes": [...],
    "edges": [...]
  }
}

Behavior:

  • Any authenticated user can execute this workflow
  • No role restrictions apply

Notes

  1. Get User Roles: To get available roles for configuration:

    GET /items/baasix_Role
Authorization: Bearer <token>

  2. Check User's Roles: To see what roles a user has:

    GET /items/baasix_UserRole?filter={"user_Id":"user-id"}
Authorization: Bearer <token>

  3. Webhook and Schedule Triggers: These trigger types ignore allowed_roles since they don't have a user context

  4. Hook Triggers Without User: If a hook workflow has role restrictions but the triggering action has no user context (e.g., system-triggered change), the workflow will be skipped

Node Types Reference

1. Trigger Node

Entry point for workflow execution. Automatically added to every workflow.

Configuration: None (configured at workflow level)

Output: Trigger data passed to workflow

2. HTTP Request Node

Make HTTP requests to external APIs.

Configuration:

  • URL: Target endpoint (supports template variables)
  • Method: GET, POST, PUT, PATCH, DELETE
  • Headers: Key-value pairs (JSON)
  • Body: Request body (JSON)
  • Timeout: Request timeout in milliseconds

Example:

{
  "url": "https://api.example.com/users/{{trigger.userId}}",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {{variables.apiKey}}"
  },
  "timeout": 30000
}

Output:

{
  "status": 200,
  "statusText": "OK",
  "headers": {...},
  "data": {...}
}

3. Transform Node

Transform and manipulate data using JavaScript or field mapping.

Configuration:

  • Transform Type: script or mapping
  • Script (for script type): JavaScript code
  • Mapping (for mapping type): JSON field mapping

JavaScript Transform Example:

// Available variables: context, data, trigger, outputs
return {
  fullName: data.firstName + " " + data.lastName,
  email: data.email.toLowerCase(),
  timestamp: Date.now()
};

Field Mapping Example:

{
  "fullName": "trigger.firstName",
  "userId": "outputs.http-1.data.id",
  "status": "active"
}

4. Condition Node

Conditional branching logic with multiple conditions.

Configuration:

  • Operator: AND / OR
  • Conditions: Array of conditions
    • Field path (e.g., trigger.status)
    • Operator: equals, not_equals, greater_than, less_than, contains, starts_with, ends_with, is_empty, is_not_empty, in, not_in
    • Value: Comparison value

Example:

{
  "operator": "AND",
  "conditions": [
    {"field": "trigger.status", "operator": "equals", "value": "active"},
    {"field": "trigger.amount", "operator": "greater_than", "value": 100}
  ]
}

Output:

{
  "conditionMet": true,
  "results": [true, true]
}

5. Service Operation Node

Perform CRUD operations on any collection.

Configuration:

  • Operation: create, read, update, delete
  • Collection: Target collection name
  • Item ID: For update/delete/read operations
  • Data: Data for create/update (JSON)
  • Filter: Filter for read multiple items (JSON)

Example:

{
  "operation": "create",
  "collection": "users",
  "data": {
    "email": "{{trigger.email}}",
    "name": "{{trigger.name}}",
    "status": "active"
  }
}

6. Loop Node

Iterate over arrays or counts with loop context variables.

Configuration:

  • Loop Type: array or count
  • Array Source: Path to array (for array type)
  • Start Index: Starting index (default: 0)
  • End Index: Ending index (optional)
  • Max Iterations: Maximum iterations (default: 1000)

Context Variables in Loop:

  • loop.index: Current iteration index
  • loop.item: Current array item
  • loop.total: Total iterations

Example:

{
  "loopType": "array",
  "arraySource": "trigger.users",
  "maxIterations": 100
}

7. Filter Node

Filter arrays based on conditions.

Configuration:

  • Array Source: Path to array
  • Operator: AND / OR
  • Conditions: Array of filter conditions

Example:

{
  "arraySource": "trigger.items",
  "operator": "AND",
  "conditions": [
    {"field": "status", "operator": "equals", "value": "active"},
    {"field": "price", "operator": "greater_than", "value": 50}
  ]
}

Output:

{
  "items": [...filtered items...],
  "count": 25
}

8. Aggregate Node

Perform aggregate operations on arrays.

Configuration:

  • Array Source: Path to array
  • Operation: count, sum, average, min, max, first, last
  • Field: Field to aggregate (for sum, avg, min, max)

Example:

{
  "arraySource": "outputs.filter-1.items",
  "operation": "sum",
  "field": "price"
}

Output:

{
  "result": 1250.50
}

9. Delay Node

Wait for a specified duration before continuing.

Configuration:

  • Delay: Duration in milliseconds

Example:

{
  "delay": 5000  // 5 seconds
}

10. Notification Node

Send in-app notifications to users.

Configuration:

  • User ID: Target user (supports template variables)
  • Title: Notification title
  • Message: Notification message
  • Type: info, success, warning, error
  • Data: Additional data (JSON)

Example:

{
  "userId": "{{trigger.userId}}",
  "title": "Workflow Completed",
  "message": "Your workflow has been processed successfully.",
  "type": "success",
  "data": {
    "workflowId": "{{workflow.id}}",
    "result": "{{outputs.aggregate-1.result}}"
  }
}

11. Email Node

Send emails to users with template support.

Configuration:

  • To: Email addresses (comma-separated)
  • Subject: Email subject
  • Body: Email body (supports HTML)
  • From: From email address (optional)
  • Template: Email template name (optional)
  • Template Data: Data for template (JSON)

Example:

{
  "to": "{{trigger.email}}",
  "subject": "Welcome to Our Platform",
  "template": "welcome",
  "templateData": {
    "name": "{{trigger.firstName}}"
  }
}

12. Workflow Node

Execute another workflow as a sub-workflow.

Configuration:

  • Workflow ID: ID of target workflow
  • Pass Data: Data to pass to sub-workflow (JSON)
  • Wait for Completion: Whether to wait for sub-workflow to complete

Example:

{
  "workflowId": "data-processing-workflow",
  "passData": {
    "userId": "{{trigger.userId}}",
    "action": "process"
  },
  "waitForCompletion": true
}

13. Stats Node

Fetch statistics from a collection with aggregation.

Configuration:

  • Collection: Target collection
  • Aggregate: Aggregation functions (JSON)
  • Group By: Fields to group by (array)
  • Filter: Filter conditions (JSON)

Example:

{
  "collection": "orders",
  "aggregate": {
    "totalRevenue": {"function": "sum", "field": "amount"},
    "orderCount": {"function": "count", "field": "id"}
  },
  "groupBy": ["status"],
  "filter": {
    "createdAt": {"gte": "2025-01-01"}
  }
}

14. File Node

Handle file operations (upload, download, process).

Configuration:

  • Operation: upload, download, delete, get_metadata
  • File Source: Path to file data or file ID
  • File Name: Name for uploaded file
  • Storage Service: Storage service to use (optional)

Example:

{
  "operation": "upload",
  "fileSource": "trigger.fileData",
  "fileName": "document.pdf",
  "storageService": "s3"
}

15. Variable Node

Set or get workflow variables.

Configuration:

  • Operation: set or get
  • Variable Name: Name of the variable
  • Value: Value to set (for set operation)

Example:

{
  "operation": "set",
  "variableName": "userCount",
  "value": "{{outputs.aggregate-1.result}}"
}

16. Script Node

Execute custom JavaScript code with full context access.

Configuration:

  • Script: JavaScript code to execute

Example:

// Available: context, trigger, outputs, variables
const user = trigger.user;
const orders = outputs['service-1'].data;

const processedOrders = orders.map(order => ({
  ...order,
  processedAt: new Date().toISOString(),
  processedBy: user.id
}));

return {
  totalOrders: orders.length,
  processedOrders
};

17. Try-Catch Node

Error handling with try-catch logic.

Configuration:

  • Try Branch: Nodes to execute in try block
  • Catch Branch: Nodes to execute if error occurs
  • Finally Branch: Nodes to always execute

Example:

{
  "tryNodes": ["http-1", "transform-1"],
  "catchNodes": ["notification-1"],
  "finallyNodes": ["log-1"]
}

Trigger Types Reference

1. Manual Trigger

Execute workflows on-demand via API or UI.

Configuration:

{
  "trigger_type": "manual",
  "trigger_config": {}
}

Execute:

POST /workflows/{id}/execute
Content-Type: application/json
Authorization: Bearer <token>

{
  "userId": "123",
  "data": {...}
}

2. Webhook Trigger

Execute workflows via HTTP webhooks.

Configuration:

{
  "trigger_type": "webhook",
  "trigger_config": {
    "webhookId": "unique-webhook-id"
  }
}

Execute:

POST /workflows/webhook/unique-webhook-id
Content-Type: application/json

{
  "event": "user.created",
  "data": {...}
}

3. Schedule Trigger

Execute workflows on a schedule using cron expressions.

Configuration:

{
  "trigger_type": "schedule",
  "trigger_config": {
    "cron": "0 0 * * *"  // Daily at midnight
  }
}

Cron Examples:

  • 0 * * * * - Every hour
  • */15 * * * * - Every 15 minutes
  • 0 9 * * 1 - Every Monday at 9 AM
  • 0 0 1 * * - First day of every month

4. Hook Trigger

Execute workflows on data changes.

Configuration:

{
  "trigger_type": "hook",
  "trigger_config": {
    "collection": "users",
    "action": "items.create.after"
  }
}

Available Actions:

  • items.create.after - After item creation
  • items.update.after - After item update
  • items.delete.after - After item deletion

Template Variables

Use template variables to access data from previous steps:

Trigger Data

{{trigger.field}}
{{trigger.userId}}
{{trigger.data.email}}

Node Outputs

{{outputs.node-id.field}}
{{outputs.http-1.data.userId}}
{{outputs.transform-1.fullName}}

Global Variables

{{variables.apiKey}}
{{variables.environment}}

Loop Context

{{loop.index}}
{{loop.item}}
{{loop.total}}

System Variables

{{workflow.id}}
{{workflow.name}}
{{execution.id}}
{{user.id}}
{{user.email}}

Real-time Updates

Workflows support real-time execution monitoring via Socket.IO. Connect to the socket server and listen for workflow execution updates:

// Client-side Socket.IO connection
import { io } from "socket.io-client";

const socket = io(API_URL, {
  auth: { token: accessToken }
});

// Join execution room
socket.emit("workflow:execution:join", { executionId });

// Listen for updates
socket.on("workflow:execution:update", (data) => {
  console.log("Node update:", data.nodeId, data.nodeStatus);
  console.log("Input:", data.inputData);
  console.log("Output:", data.outputData);
});

// Listen for completion
socket.on("workflow:execution:complete", (data) => {
  console.log("Workflow completed:", data.status);
});

Usage Examples

Example 1: User Registration Workflow

Trigger: Hook on users collection, items.create.after

Flow:

  1. Trigger - Receives new user data
  2. Transform - Format welcome email data
  3. HTTP - Send welcome email via external API
  4. Service - Create user profile record
  5. Notification - Notify admin of new registration

Example 2: Data Processing Pipeline

Trigger: Webhook

Flow:

  1. Trigger - Receives batch of records
  2. Loop - Iterate over each record
  3. Transform - Clean and format data
  4. Condition - Check if valid
  5. Service (true branch) - Save to database
  6. Aggregate - Count successful imports
  7. Notification - Send summary report

Example 3: Scheduled Report

Trigger: Schedule (daily at 9 AM)

Flow:

  1. Trigger - Starts at 9 AM
  2. Service - Fetch yesterday's orders
  3. Filter - Filter completed orders
  4. Aggregate - Calculate total revenue
  5. Transform - Format report data
  6. Email - Send report via email
  7. Notification - Notify managers

See also

← Back to Documentation Home

Utils Routes

Utils Routes

Custom Workflow Modules

Custom Workflow Modules

On this page

Workflow RoutesTable of ContentsOverviewKey FeaturesDatabase Collectionsbaasix_Workflowbaasix_WorkflowExecutionbaasix_WorkflowExecutionLogWorkflow ManagementList WorkflowsQuery ParametersExample RequestSuccess ResponseGet Single WorkflowURL ParametersExample RequestSuccess ResponseCreate WorkflowRequest BodySuccess ResponseUpdate WorkflowURL ParametersRequest BodySuccess ResponseDelete WorkflowURL ParametersSuccess ResponseWorkflow ExecutionExecute WorkflowURL ParametersRequest BodySuccess ResponseError ResponsesGet Execution HistoryURL ParametersQuery ParametersExample RequestSuccess ResponseGet Execution DetailsURL ParametersExample RequestSuccess ResponseGet Execution LogsURL ParametersExample RequestSuccess ResponseCancel ExecutionURL ParametersSuccess ResponseError ResponsesTesting & ValidationTest WorkflowURL ParametersRequest BodySuccess ResponseValidate WorkflowRequest BodySuccess ResponseValidation Errors ResponseStatistics & MonitoringGet Workflow StatisticsURL ParametersExample RequestSuccess ResponseWebhook TriggersExecute via WebhookURL ParametersRequest BodySuccess ResponseError ResponsesRole-Based Access ControlOverviewConfiguring Allowed RolesCreate Workflow with Role RestrictionsUpdate Workflow to Add Role RestrictionsRemove Role RestrictionsExamplesExample 1: Admin-Only Manual WorkflowExample 2: Hook Workflow with Manager AccessExample 3: Multiple Roles AllowedExample 4: Public Workflow (No Restrictions)NotesNode Types Reference1. Trigger Node2. HTTP Request Node3. Transform Node4. Condition Node5. Service Operation Node6. Loop Node7. Filter Node8. Aggregate Node9. Delay Node10. Notification Node11. Email Node12. Workflow Node13. Stats Node14. File Node15. Variable Node16. Script Node17. Try-Catch NodeTrigger Types Reference1. Manual Trigger2. Webhook Trigger3. Schedule Trigger4. Hook TriggerTemplate VariablesTrigger DataNode OutputsGlobal VariablesLoop ContextSystem VariablesReal-time UpdatesUsage ExamplesExample 1: User Registration WorkflowExample 2: Data Processing PipelineExample 3: Scheduled ReportSee alsoRelated Documentation