Developer Guide

Workflow 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.

Key Workflow Actions (Overview)

1- Assignment activity

This activity allows the workflow to assign a value or expression to a target field — either a workflow variable or a document field. It is commonly used to update document properties, convert or normalize data, or prepare intermediate values that will be used by subsequent workflow actions.
The Target is selected from the workflow context, while the Value can be any constant or a computed expression created using the Expression Editor.

An Assignment activity is composed of one or more assignment steps, and users can freely disable,remove or reorder these steps to fit the required logic. This flexibility makes it possible to build multi-stage transformations such as mapping, cleanup, formatting, or merging values.

Because Assignment steps can write to workflow variables, this activity is frequently used to pass context between workflow steps, enabling advanced data handling such as storing interim results, preparing API request parameters, or holding computed values for later decision-making.

Each row maps : Target = Expression

2- Save Document activity

The SaveDocument activity commits any modifications made to the current workflow document. It does not require parameters and serves as the explicit instruction to persist all changes performed earlier in the workflow.

This action is typically used after updating document fields through Assignment actions or other processing steps.

Typical Use Cases

• After converting a device’s original raw message into the Platform Message Structure (PMS), SaveDocument stores the standardized result.
• After cleaning or normalizing incoming message data.
• After modifying device information (serial number, tags, groups, custom attributes, etc.).
• When transitioning a message through its lifecycle (e.g., New → Processed → Archived).
• After updating runtime variables into document fields during workflows.

Notes

• If no field changes were performed earlier in the workflow, SaveDocument simply completes without altering the stored document.
• SaveDocument only applies to the main workflow document (Message or Device), not to external entities.

3. Message Acquisition activity

The Message Acquisition activity is responsible for finalizing the processing of a device’s incoming message after it has been converted into the Platform Message Structure (PMS)—typically through Assignment actions and various Expression Editor functions. It acts as the consolidation step where normalized data, device attributes, and lifecycle logic are applied.

This activity prepares the message for persistence, analytics, and monitoring, ensuring that all received values are cleaned, interpreted, and correctly stored.

• Key Responsibilities

The Message Acquisition activity performs several essential tasks:

1. Normalize Attribute Values
   Standardizes raw values received from the device (units, scale factors, types, etc.) to ensure consistency across the platform.

2. Interpret Attribute values 

   Interpretation allows the platform to classify or transform raw attribute values. It can assign a status level and a comment, or extract additional attributes from a received value.
   For example, from a picture received as an attribute, an interpreter can analyze the image and automatically generate new attributes such as vehicle brand, color, or registration number, which are then injected into the message payload and device ledger.

3. Update Device Attributes
   Any attribute (temperature, humidity, signal strength, battery, etc.) included in the PMS payload is used to update the corresponding device’s real-time attribute values.

4. Generate Attribute Ledger Entries
   For every attribute, an entry is recorded with the correct timestamp.
   This provides full historical tracking of attribute evolution for analytics, dashboards, and reporting.

5. Update Message Lifecycle Status
   Message Acquisition automatically sets the message’s status—such as Processed, Normalized, Completed, or others—according to the internal lifecycle rules and workflow configuration.

    

• Attribute Interpretation

When the Interpret Attribute Values option is enabled, an additional section appears allowing the user to select one or more Attribute Interpreters and define their execution scope.  Attribute Interpreters provide advanced logic to translate raw values into higher-level statuses, alarms, or contextual information. 

Interpreter Scopes : Interpreters can be configured to run using different scopes:

       -   Global : The interpreter is always applied for the corresponding attribute, regardless of date or time.

       -   Date Range: Executes only during a specific period (e.g., seasonal interpretations).
           Example: A temperature of 45°C may trigger a Normal or Expected status in summer, but the same value in winter would be considered Critical or Abnormal. Different interpreters (e.g., Summer Interpreter and Winter Interpreter) can therefore apply season-specific logic.

      -  Time Range:   Executes only during specific hours of the day. Example:     00:00–06:00 → apply nighttime interpretation logic

      -  Attribute Scope:  The same attribute can be interpreted differently depending on its origin. An attribute coming from the device configuration does not carry the same meaning or usage as the same attribute collected as a live measurement, so each may require a distinct interpreter.

      -  Device attribute selection : Interpretation may vary according to the device that produced the value.
Example: Attributes from devices located in the North region might be processed using a different interpreter than those from devices in the South, allowing location-specific interpretation rules.

Interpretation Results : The output of an interpreter updates:

       -   Status Level of the attribute (e.g., Normal, Warning, Critical).
These levels are configured globally in Attribute Interpret Level settings.

       -  Comment describing the interpretation result.

       -  Addtionnal attributes if exists:  Extracting other information from main attribute value, Example Image to data.

Example:

If temperature > 50°C, status is Warning, comment:
"Temperature is too high, attention is needed."

These results are stored on the Attribute Ledger, making them available for dashboards, alerts, and analytics.

4. Send MQTT Message

The SendMQTTMessage activity allows a workflow to publish MQTT messages toward a device or an external MQTT consumer. It supports three distinct sending modes, each designed for a different outbound scenario. When executed, the activity pushes the message into the platform’s MQTT outbound pipeline, where it is delivered by the configured MQTT broker connection.

   4.1 Queue the Current Outbound Message

This mode is used when the workflow is processing an outbound message document.
If selected, the activity simply queues the current workflow document (already containing the outbound payload and topic) for sending.
No additional configuration is required.

Use case examples:

• A workflow builds a command message in previous steps (via Assignment or JSON transformation) and now wants to publish it.
• A device command response is generated dynamically and must be sent immediately.

    4.2. Send from Control Table of Commands

This mode allows sending a predefined command stored in the Control Table of Commands.

When selected, two parameters appear:

• Control Table Command – pick from the list of stored commands (code composed of timestamp, command name, and device identifier).

• Outbound Process Workflow – defines which outbound workflow will process this command before it is published (e.g., to build payload, populate topic, enrich metadata).

  

How it works:

1. The selected command is retrieved from the command table.
2. The chosen outbound workflow processes and prepares the outbound message.
3. The final message is queued and sent through MQTT.

Typical use cases:

• Sending device control commands such as Turn on, Restart, Configure, etc.
• Triggering device actions based on business logic events.
• Resending or replaying a stored command.

  4.3. Send a JSON Device Message

This mode lets the workflow send a raw JSON structure directly to a device’s MQTT topic.

When selected:

• The workflow displays an Expression field, where the designer writes an expression that returns a JSON object or string.
• The platform sends this JSON payload as-is.

Use cases:

• Custom MQTT messages not based on the platform outbound message model.
• Integrations with external systems requiring specific JSON structures.
• Prototyping or debugging communication with devices.

5. Delay Activity

The Delay activity introduces a controlled waiting period within the workflow before executing the next step.
It pauses the workflow for a specified duration expressed in milliseconds (ms).

This is useful when:

• you need to wait for an external system to complete an action,
• you want to introduce spacing between operations,
• or you must ensure a specific timing sequence within the workflow.

Example: A Delay of 5000 ms makes the workflow wait for 5 seconds before continuing.

6. Send Mail activity

The SendMail activity allows the workflow to send emails using the platform’s default SMTP Communicator, as configured in the General Settings. It is used to notify users, send alerts, deliver generated reports, or communicate results of workflow processing.

How It Works

When designing the activity, the workflow editor provides fields for all email components, including:

• To, Cc, Bcc
• Subject
• Body (HTML or Text)
• Attachments

Each field supports expressions and dynamic placeholders using the Expression Editor. This allows email content to be constructed dynamically based on:

• Workflow Document fields (e.g., message details, device attributes)
• Workflow Variables
• API call results
• Calculated expressions

This makes it possible to personalize emails or include contextual operational information automatically.

Attachments Support

The SendMail activity can also attach files to the outgoing email. Attachments must be:

• Stored in a workflow variable as a byte array,
• Provided with a manually defined file name.

This is especially useful for:

• PDF or Word files generated earlier in the workflow
• Logs or diagnostic exports
• Screenshots or binary data returned by external APIs

Key Features

• ✔ Uses platform default SMTP configuration
• ✔ All email fields support placeholders and expressions
• ✔ HTML formatting supported for rich email content
• ✔ Multiple recipients: To / CC / BCC
• ✔ Support for binary attachments stored in workflow variables
• ✔ Allows building fully dynamic notification templates

Typical Use Cases

• Sending alerts when a device reports abnormal data
• Sending daily or scheduled reports created by another workflow activity
• Notifying administrators of processing errors
• Delivering external API results to users

7. Call WebAPI

The CallAPI activity enables the workflow to interact with external or internal REST APIs, allowing powerful integrations such as device provisioning, synchronization with third-party systems, notifications, analytics services, or interactions with your own IoTRoutes APIs.

Before using this action, the API must be declared in the Communicator module, where the base URL, authentication mode, and default headers are configured.

How It Works

When the activity is added to the workflow, the designer selects which declared API to call. The activity exposes all configurable API parts (URL path, query parameters, headers, and request body), and each of these fields supports expressions and placeholders using the Expression Editor.

At runtime, the workflow engine resolves all expressions and placeholders into concrete values before sending the HTTP request.

Typical Use Cases

• Synchronizing device metadata with an external system
• Pushing alerts or notifications to a third-party application
• Fetching external configuration for dynamic workflows
• Calling platform APIs to create or update entities
• Sending commands to external cloud APIs (AWS IoT, Azure IoT, custom brokers, etc.)

Example Behavior

A workflow might:

1. Extract values from a received message
2. Build a JSON payload using an expression
3. Call an external API using this action
4. Store the response inside workflow variables
5. Make business decisions based on the API result

8. WordReport Activity

 1. Purpose

The Word Report Activity allows workflows to generate Microsoft Word documents (.docx) using:

• A Word template selected by the user from the Templates bucket in FileStore.
• The context of the current workflow, including documents and workflow variables.

The activity automatically maps placeholders in the template to variable values, renders the final document, and outputs it for:

• Saving in FileStore
• Sending via email
• Sending via API to external systems

This enables automated reporting, invoicing, or document generation in any workflow scenario.

 2. Prerequisites

Before using the Word Report Activity:

1. FileStore Templates

   • Users must create and upload .docx templates to the Templates bucket.
   • Templates must comply with NPOI formatting rules (see Section 4).

2. Workflow Variables

   • Variables referenced in the template must exist in the current workflow context.
   • Supported types:
     • Simple values: string, number, date, boolean
     • Lists / arrays for table rows
     • Binary content (images)

 3. Activity Configuration

When designing a workflow, the Word Report Activity requires:

 4. Template Requirements – NPOI Compliance

The Word Report Activity uses NPOI  to process templates. Templates must follow NPOI rules:

•  Placeholder Syntax
  • Use simple placeholders: {{VariableName}} or ${VariableName}
  • Placeholders must be inside a single run (avoid split runs across styling changes or line breaks)
  • Valid characters: letters, numbers, underscore

         Example:  {{CustomerName}} {{OrderDate}}

• Repeating Tables : 

  To populate list data:

  • Use marker rows for loops:  {{#Items}}  ...  {{/Items}} 
  • Place markers in their own row and single cells.
  • Inside repeated rows, reference variables as  {{Name}}, {{Items.Quantity}}, etc.

Example:

9. Data Cleanin Activity

The DataCleaning activity performs automated maintenance tasks on historical data generated by the IoT platform. It is typically used in scheduled workflows or post-processing steps to ensure the system remains performant, uncluttered, and compliant with data-retention rules.

This activity exposes several options—each controlled by a checkbox. When an option is enabled, additional parameters appear to configure the retention behavior.

 1- Archive Old Messages

Purpose: Move old IoT messages from the live message table to the archive table.

• Archive old messages (checkbox)
  When enabled, two additional fields appear:

  • Age in days greater than
    Messages older than the configured number of days will be archived.
  • Message status in (multi-select)
    Filters messages to archive only those matching selected statuses
    (e.g., Processed, Converted, Acquired, etc.).

 2- Delete Workflow Logs

Purpose: Permanently remove old workflow execution logs.

• Delete workflow logs (checkbox)
  When selected:

  • Age in days greater than
    Defines the minimum age of logs to delete.

This helps to prevent uncontrolled growth of logs, especially on high-throughput installations.

3. Delete Attribute Value History (Ledger Cleanup)

Purpose: Delete outdated attribute ledger entries (attribute history), if permitted by platform-wide rules.

• Delete attribute value history (if allowed) (checkbox)
  When enabled (and only if allowed by General Settings):

  • Age in days greater than
    Minimum allowed retention is 6 months.
    Ledger entries older than this threshold will be removed.

Important:
The ability to remove ledger history must be explicitly authorized in the Infrastructure / General Settings, since it may affect analytics, long-term history, and regulatory compliance.