Application settings

1- Message Formats

IoTRoutes provides several standard message formats upon installation, optimized for efficient and high-performance data exchange. Administrators can freely customize these formats or create new ones to suit their specific device ecosystems.

The platform supports multiple exchange types: JSON, XML, and Protobuf. Each format can be enabled or disabled, allowing administrators to control which message types are accepted and processed by the brokers.

Each Message Format Definition describes how device messages are structured and interpreted by the platform.
The list view screen, shown below allows adding, editing, or reviewing a format’s parameters, which vary according to the selected exchange type.

Each Message Format Definition  describes how device messages are structured and interpreted by the platform.
The list view allows users to add, edit, or review message format parameters, which vary depending on the selected exchange type.  Every format, regardless of its original type, must include an equivalent JSON schema.
This schema enables the platform to interpret, normalize, and convert messages into a consistent internal JSON model — allowing workflows, interpreters, and storage modules to seamlessly read and map all message elements.

Main Parameters:

• Name: Unique code identifying the format; used in the conversion process.
• Exchange Type: Defines whether the message is in JSON, XML, or Protobuf.
• Message Definition:
  • For Protobuf: the  .proto  structure defining the message.
  • For JSON/XML: an example message showing the data layout.
• JSON Schema: Standard JSON equivalent of the message, describing its structure.
  The schema can be generated automatically by clicking the “Generate from message” button.

Built-in Formats

The default installation includes several predefined formats, such as:
STD_J001, STD_J002, STD_JMS, STD_PR01 — which serve as ready-to-use templates for various exchange types.

• Example: STD_J002 (Standard Json format 002)

  Is a Platform Standard Payload, Optimized message with an array of attributes ID and values. This format is compatibles with the platform payload strcuture. Attribute ID is the identifier of a measurement,configuration or event.

{
  "deviceId": "d15922X",
  "timestamp": "2023-11-23T18:25:43.511Z",
  "temperature": 32.8,
  "humidity": 12.0,
  "batteryLevel": 90
}

• STD_JPMS (Standard Json PMS)

Standard Json Platform Message Structure (PMS), this format does not require any basic conversion process as it is aligned with the platform message structure

{
  "ResponseToMessageId": 0,
  "SentOn": "2025-05-04T14:31:39",
  "Payloads": [
    {
      "NodeId": "node001",
      "DateTime": "2025-05-04T12:31:39Z",
      "Attributes": [
        {
          "Id": 100,
          "Value": "41.5"
        },
        {
          "Id": 110,
          "Value": "20"
        }
      ]
    }
  ]
}

• Example STD_PR01 (Standard Proto format 01)

  Is a Platform Structure (PMS) Proto message

When defining a Protobuf format, the system automatically generates an equivalent JSON schema based on the provided .proto structure. The received binary message is then converted and deserialized into JSON for further use.

The message format name must match the main Proto type defined in the schema.

• PMS Format  

When the PMS option is enabled, the message follows the Platform Message Standard — the native structure used internally by IoTRoutes.
PMS-aligned messages require no conversion and are acquired directly in an optimized manner.
PMS messages can be of JSON, XML, or Protobuf types.

2- Messages lifecycle

The IoT message lifecycle defines the sequence of stages that an IoTRoutes message passes through — from its initial emission or creation to its final processing, transmission, or archiving.

This lifecycle provides a structured model for how the platform handles incoming and outgoing messages, ensuring traceability, automation, and operational consistency throughout the entire data pipeline.

By formalizing these stages, IoTRoutes enables:

• Efficient tracking of each message’s journey.
• Workflow-based processing and decision automation.
• Error classification and management for invalid messages.

Built-in Statuses

IoTRoutes includes a set of built-in message statuses that represent the standard states of a message during its lifecycle.
These system-defined statuses are reserved for internal processing, but administrators can define additional custom statuses to adapt to specific business workflows or domain needs. Statuses are automatically updated through workflow actions as each message passes through its configured workflow pipeline.

Custom Statuses

Administrators can create custom message statuses to extend the lifecycle and adapt to specific operational or analytical requirements. Custom statuses can be linked to workflow rules to automate transitions based on message content, type, or processing outcome.

3- Attribute Value Interpreters

Attribute Value Interpreters are processes for analyzing or comparing attribute values sent by connected objects in IoT messages. 

Depending on the IoT domain and the attributes involved, they allow the received values to be classified into levels. This allows system flows to immediately identify urgent messages or those with critical values and provide timely notification or execute a defined process.

Levels are configured in the application as shown in the screenshot below. A value level is defined by the level number, name, description, and a color that will be displayed in KPIs or analysis tables.

The example below shows a level '5' with the name 'Critical', in red, for a value that significantly exceeds the standard value.

The application offers two modes for interpreting values received from connected objects:

•  The simple mode automatically compares each value to predefined thresholds, to determine whether it is normal, high, or critical. This mode is easy to use and suitable for traditional data such as temperature or pressure.

• Advanced mode, on the other hand, is intended for administrators or developers. It offers the ability to write custom functions using an integrated development language. This allows for more advanced analysis, especially for processing complex data such as images, audio files, or other types of media.

  Default Advanced script Sample :

 /****** IoTRoutes script  sample v0.1 : change code above to write your custom interpreter ****/
    
    var result = new AttributeInterpretResult(); //required. Result to return, contains the assigned Level and the comment and, if eligible, the sub-attributes
   //dynamic apiResponse= Fct.ApiCall(apinName,"/{{Variables.Id}}","",3); // You can call a web api to deep analysing and return result. See 'ApiCall' method schema.
   
   if ( Context.Value >100)  //value already casted based on attribute type definition
    {
        result.ValueLevel = Levels.Faulty;
        result.ValueLevelComment ="Value can't exceed 100";
    }
    else if ( Context.Value >  10 &&  Context.Value<45)
    {
        result.ValueLevel = Levels.Good;
        result.ValueLevelComment ="Good value measured";
    }
    else
    {
        result.ValueLevel =  Levels.Normal;    
        //set sub-attributes extracted from main value. Example media value to metadas like extracting Registration Number and color from car picture. 
        //result.AddSubResult([subAttributeId],apiResponse.myValue ,1,"comment as string"); 
    }
    return result;

4- Entities

Entities in IoTRoutes are hierarchical in structure and represent groups, divisions, or individuals, and are divided into two categories: internal (such as subsidiaries, departments, or services) and external (usually customers).

Their main role is to associate connected objects with a specific group, in order to restrict user access only to the data assigned to them. In a shared environment, for example, this allows a client to access only their own objects and a user in a department to have access only to their department's data.

Accessible from Application Settings >> Entities, the screen below allows you to view and manage the list of entities.

The detail screen shown in the screenshot below allows the creation and modification of entities as well as the association of devices, the assignment of users and the linking of sub-entities. A user assigned to an entity in the hierarchy will have access to the entity and all child entities.

5- General Settings

Allows you to define and manage a set of parameters essential to the operation of the IoTRoutes platform and the processes that run on it. This section serves as a central configuration point to adapt the application to different environments or usage contexts.

It offers the ability to create and save multiple distinct configurations, for example:

One setup for production environment, One for testing, Another for training or demonstration, etc. 

However, only one configuration can be active at a time, ensuring that the application always operates according to a consistent and controlled set of parameters. This flexibility allows the application's behavior to be quickly adjusted as needed without having to manually change parameters with each context switch.

There are two groups of settings as shown in the screenshot: Application settings and running process settings.

• Intra-server event topic: The topic used for events communicated between servers or internal services.
• Maximum allowed payload: Maximum message size sent by connected devices.
• Save payload as blob from: Size limit, beyond which attributes will be saved as a blob (media database) managed by the file storage manager.
• Timestamp calculation: A specific timestamp calculation method converts a date value into a small integer value used for optimized communication between the platform and devices. For example, the date will be represented by the number of milliseconds, seconds, or minutes since January 1, 2020.

• Parameter Refresh Interval: Continuously running services load their configurations at platform startup, any configuration changes are automatically taken care of at a specified interval in number of minutes

Next :  Workflows