Connector

In this section, you will find the list of supported connectors in IoT-Flow, as well as their specificity and how to set up them.

warning

Due to infrastructural limitation, once the messages are redirected to IoT-Flow from base station, the max duration of retention of a message is 24h before it gets processed in a flow.

Common Parameters for a connection

The following table lists the properties applicable to all connections:

Property	Description	mandatory	default value
active	- Enables or disables the connection. - When set to false, the connection stops within 1 minute if previously active.		true
connectorId	Defines the type of connector to use, e.g., actility-aws-iot or actility-azure-iot.	✓
name	Name of the connection (for informational purposes).	✓
alarms	Defines alarms for low flow rates. See the section below for more details.
configuration	- Defines all specific parameters of the connection. - Properties vary depending on the connector type. Refer to the specific chapter for each connector for details.	✓
configuration/description	Optional description text for the configuration.
configuration/createDevices	- If set to true, the connection attempts to auto-register devices on the cloud upon receiving the first uplink message (if not already created). - If set to false and a device is not found, the uplink is skipped.		true
configuration/sendMetadata	- For backward compatibility, setting this to true removes the DevEUI_uplink root node in uplinks. - Only uplink messages are received; downlink acknowledgments are filtered.		false
configuration/sendRawDecodedFormat	- If sendMetadata is false and sendRawDecodedFormat is true, only the payload field content is sent to the cloud. - If payload is absent, the entire uplink message body is sent.		false
configuration/uplinkTimeValidity	- Sets the validity period for uplinks (e.g., 1m for 1 minute). - Uplinks older than the specified value are skipped, and an alarm event is logged. - Useful for preventing outdated messages after downtimes.
configuration/downlinkEnabled	- Enables or disables downstream messaging. - Set to false to disable downstream capabilities.		true
configuration/downlinkAsId	Specifies the authentication AS_ID value for downlinks requiring authentication.
configuration/downlinkAsKey	Specifies the authentication AS_KEY value for downlinks requiring authentication.
configuration/downlinkPort	Sets the default port for downlink messages when no port is specified.
configuration/reconnectStrategy	Defines the reconnect strategy when a connection fails to reach the OPENED state. Options: - CALM: Retries every 10 minutes for 12 hours, then hourly for 1 day. - NORMAL: Retries every 5 minutes for 1 hour, then hourly for 1 day. - AGGRESSIVE: Retries every 3 minutes for 3 hours, then every 30 minutes for 1 week, followed by hourly retries indefinitely.		NORMAL

Reconnection strategy

Each connector follow a reconnection strategy when it failed and close. This setup could be set only using API and the field configuration/reconnectStrategy (default=NORMAL). Options are :

• CALM: Retries every 10 minutes for 12 hours, then hourly for 1 day.
• NORMAL: Retries every 5 minutes for 1 hour, then hourly for 1 day.
• AGGRESSIVE: Retries every 3 minutes for 3 hours, then every 30 minutes for 1 week, followed by hourly retries indefinitely.

Topic Pattern Expression

Some connection configuration fields, like uplinkTopicPattern, accept JsonPath expressions. Expressions defined within {} can reference fields in the uplink message. A fallback can be set using the | operator.

For example, given the uplink message, these expressions generate topics:

• mqtt/thing/{DevEUI}/uplink → mqtt/thing/0018B20000000BEE/uplink
• mqtt/thing/{DevEUI}/{FPort}/uplink → mqtt/thing/0018B20000000BEE/1/uplink
• mqtt/thing/{DevEUI|'None'}/uplink → mqtt/thing/0018B20000000BEE/uplink (Fallback: None if DevEUI is missing)
• mqtt/thing/{CustomerData.name|DevEUI|deviceEUI|'None'}/uplink → mqtt/thing/Adeunis_FieldTester_Bruno/uplink (# is replaced by _ automatically)

Note

• In MQTT connectors, if the resolved topic contains # or +, it is automatically replaced with _.
• Complex JsonPath expressions like mqtt/thing/{$..CustomerData.tags[?(@ =~ /Site=.*/)]}/uplink can be optimized to mqtt/thing/{tags='Site=.*'}/uplink for better efficiency.

For more information:

• Refer to the JsonPath GitHub project.
• Test expressions using the Online JsonPath Evaluator.

Connection States

The state of a connection reflects its current lifecycle. Due to the asynchronous architecture, an action like starting may not immediately change the state.

Connection State	Description
OPENING	The connection is currently opening.
OPENED	The connection is active and operational.
CLOSED	The connection is closing.
AUTHENTICATING	The connection is undergoing authentication.
AUTHENTICATION_FAILED	Authentication failed.
UNREACHABLE	The bridge hosting the connection is unreachable, and no information is retrievable.
DEACTIVATED	The connection is currently deactivated.

The connection workflow is illustrated in the following diagram: