Developer Guide

Workflow Engine & Actions

The IoTRoutes Workflow Engine is the core automation framework that executes business and data-processing logic inside the platform.
Workflows define how incoming IoT messages, outgoing commands, or background maintenance tasks are processed, transformed, or triggered.

They enable developers and integrators to build no-code or low-code automations that interact with devices, APIs, and internal data structures.

Workflow Structure

A workflow consists of:

• Header Metadata
  Name, description, trigger type, activation status, and schedule (if applicable).

• Workflow Document

  Each workflow always runs in the context of a specific document type. This document represents the primary object the workflow operates on. Supported document types include:

  • Message : Used for processing inbound IoT messages and their related objects, typically: Convert incoming data into PMS structure, Interpret attributes, Normalize values into the Attribute Ledger, Apply business rules.

  • Device : Used when workflows must react to device lifecycle changes or perform scheduled operations. Typical use cases: Trigger events when a new device is registered, Analyze device health or telemetry trends, Generate periodic reports , Perform background tasks on device collections

• Workflow Variables
  Variables are dynamic values created and used during workflow execution. They act as temporary storage for the workflow instance. Common use cases:

  • Storing intermediate values while processing data
  • Holding the response from a Call API action
  • Managing counters or indices for loops
  • Keeping temporary device or attribute references
  • Building dynamic structures later reused in other actions

• Actions List
  A pipeline of actions executed sequentially or conditionally.

• Output & Status
  Each execution is logged in the Workflow Log with execution time, result, and any error details.

Expression Editor

The Expression Editor is a core component of IoTRoutes workflows. It allows developers and integrators to build dynamic expressions used in assignments, conditions, calculations, API calls, conversions, and message transformations.
It provides a guided editing environment that combines syntax assistance, contextual hints, and a structured view of all available variables and functions.

1. Tree View of Available Elements

The editor displays a hierarchical tree that organizes all accessible resources:

• Workflow Variables – dynamically created variables defined in the workflow.
• Document Fields – fields from the workflow’s main document (Message, Device, etc.).
• System Functions – a comprehensive library of functions grouped by category (Math, String, JSON, Date/Time, Collections, HTTP, Device tools, etc.).
• Constants & Helpers – built-in constants or predefined helper values specific to IoTRoutes.

This tree allows the user to simply click to insert a variable or function without manually typing long paths.

2. Function Catalog with Tooltips

Every system function includes a built-in helper tooltip that provides:

• Function name & category
• Description (what the function does)
• Parameters list with types
• Return type
• Usage hints or examples

This makes the editor self-documenting and reduces the need to look up syntax elsewhere.

Example tooltip structure:

 3. Insert Buttons & Quick Actions

Next to each input field using the Expression Editor, small buttons allow:

• Opening the full editor in a modal
• Quickly inserting variables or functions
• Copying/pasting expressions between fields

This accelerates workflow creation for more complex logic. The Expression Editor is what makes IoTRoutes workflows extremely powerful:

• No-code UI but highly technical capabilities
• Reusable expressions across many actions
• Reduces errors by guiding users through available options
• Encourages clean, modular workflow logic
• Allows complex IoT transformations without custom code

Core Action Categories

Below are the most common built-in actions available in IoTRoutes.

Each action, when opened in detail, presents three tabs that define its behavior and configuration.

The first tab (“General”) includes the action’s unique identifier (name), description, and an enable/disable switch that allows designers to temporarily bypass the action without removing it. It also contains the “Loop for elements in array” option: when enabled, additional fields appear allowing the user to specify the array object to iterate over and select a workflow variable that will hold the loop index. This feature allows executing the same action multiple times—once for each element in the array.

The third tab (“Connections”) defines how the workflow transitions after this action. Users can choose to continue execution on success, on failure, or based on a condition. When the conditional path is selected, a formula expression can be defined using the Expression Editor, enabling dynamic, data-driven branching.

The second tab, labeled with the action’s own name (e.g., Assignment, DataCleaning, HttpCall), contains all parameters specific to that action type. The content of this tab varies depending on the function the action performs and will be detailed individually for each action category in the upcoming sections.

Message Conversion Overview

Before workflow activities are described in detail, it is important to understand how IoTRoutes processes and converts device messages inside a workflow. Every workflow that handles IoT messages operates on a Message Document (the message model). This document contains several system fields (ID, topic, device, message format, status, timestamps, etc.) but also two core fields used during conversion:

1. DeviceBasedMessage (Raw Device Message)

This field contains the raw message exactly as received from the device, or—as in outgoing workflows—the raw command message before sending it.

The structure of DeviceBasedMessage depends entirely on the selected Message Format, which is defined by a JSON Schema. This is why every message format in the system must include a valid JSON Schema.

Strongly Typed Access in Workflow & Expression Editor

Inside the workflow engine, DeviceBasedMessage  becomes a strongly typed dynamic object.
The Expression Editor automatically interprets the JSON schema and exposes the message structure as navigable fields.

For example, if the Message Format “STD_J001” defines these fields:

• DeviceName
• Temperature
• Battery

Then inside workflow expressions you can directly access:

• Document.DeviceBasedMessage.STD_J001.DeviceName
• Document.DeviceBasedMessage.STD_J001.Temperature
• Document.DeviceBasedMessage.STD_J001.Battery

This provides a safe, schema-aware way to inspect and convert message data with autocomplete.

2. Payload (Platform Message Structure – PMS)

The Payload field is the standardized structure that IoTRoutes uses internally. All analytics, ledgers, dashboards, and workflows operate on this unified PMS format.

The workflow’s job during message processing is to transform:

DeviceBasedMessage → Payload (PMS)

This conversion is done primarily using:

• Assignment actions
• Expression Editor functions
• Custom logic, normalization, or type conversions

Example of typical conversions:

Custom formulas, units conversions, string manipulation, and conditional logic can all be applied during assignment.

Why This Matters?

• IoTRoutes supports many device protocols and formats
  (custom JSON, LoRa, MQTT proprietary objects, vendor payloads, etc.)
• PMS provides one unified model for the rest of the platform.
• Workflows allow integrators to convert, normalize, validate, and enrich data with complete flexibility.

  To better understand message conversion, readers are encouraged to open and review the out-of-the-box Inbound Workflow delivered with IoTRoutes. This workflow contains real, production-ready examples showing how raw device messages—specifically formats STD_J001 and STD_J002—are parsed, normalized, and converted into the standardized Platform Message Structure (PMS).

How IoTRoutes Detects the Message Format

When a message is placed in queue, IoTRoutes automatically attempts to identify the correct Message Format. This detection is essential, because the DeviceBasedMessage object inside the workflow is fully typed according to the JSON Schema of the selected format. The platform uses two detection mechanisms:

1. Topic-Based Format Detection: If the topic contains a format code (e.g., …/std_j001/…), the platform immediately assigns the corresponding message format.

2. Schema-Based Detection: If no format appears in the topic, IoTRoutes inspects the JSON payload and checks whether it matches any known JSON Schema of an active message format. If a match is found, that format is applied automatically.

If neither method identifies the structure, the message will enter the workflow without a resolved message format, and the first workflow activities (usually Assignment or Decision logic) must explicitly set the correct MessageFormat  so that downstream actions (conversion, acquisition, interpretation) function correctly.

Best Practices

• Keep workflows modular: small, single-purpose workflows are easier to maintain.

• Reuse actions across inbound and outbound flows when possible.

• Use variable naming conventions (e.g. msg, device, apiResponse).

• Validate PMS structure early to prevent downstream parsing errors.

• Avoid heavy logic in a single workflow; split into sub-workflows if needed.

• Periodically review Cleaning Workflows to ensure performance and data retention compliance.