MQTT activities

Configure MQTT connections and use MQTT triggers and activities in Elsa Workflows 3.9.0.

The Elsa.Mqtt extension connects Elsa Server to MQTT brokers. It provides a trigger that starts or resumes workflows when a topic filter matches, and an activity that publishes a text message to a topic.

Use this module when an application already communicates through MQTT, such as an IoT or telemetry system. It is a standalone MQTT integration; it is not a MassTransit transport and it does not move Elsa's own workflow-dispatch traffic onto MQTT.

Elsa Studio does not connect to the broker. The server owns the MQTT clients, subscriptions, and message delivery. Studio receives the activity descriptors and the configured connection names from the server.

Install and register the module

Install the Elsa.Mqtt package in the application that executes workflows:

dotnet add package Elsa.Mqtt --version 3.9.0

using Elsa.Extensions;
using Elsa.Mqtt.Options;

builder.Services.AddElsa(elsa =>
{
    elsa.UseMqtt(mqtt =>
    {
        mqtt.ConfigureOptions = options =>
        {
            options.AddConnection("telemetry", new MqttConnectionOptions
            {
                Host = "mqtt.example.com",
                Port = 8883,
                Username = configuration["Mqtt:Username"],
                Password = configuration["Mqtt:Password"],
                UseTls = true
            });
        };
    });
});

UseMqtt registers the activities, the MQTT client and subscriber managers, the Studio input handlers, the workflow trigger/bookmark handlers, and the startup task that restores subscriptions. The module uses MQTTnet 5.1.0.1559 in the 3.9.0 Extensions release.

Keep broker credentials and client-certificate passwords in deployment configuration or a secret store. Set AllowUntrustedCertificates only for development or controlled testing; it allows a broker certificate that cannot be validated against a trusted root.

Configure connections

MqttOptions stores named connections. An activity with no Connection Name uses the case-insensitive Default connection. Otherwise, the name must match one registered with AddConnection or AddDefaultConnection; an unknown name causes client creation to fail.

For more control than MqttConnectionOptions, pass an MQTTnet MqttClientOptions instance to AddConnection:

options.AddDefaultConnection(new MqttConnectionOptions
{
    Host = "localhost",
    Port = 1883,
    ClientId = "elsa-development"
});

options.AddConnection("secure", new MqttConnectionOptions
{
    Host = "mqtt.example.com",
    Port = 8883,
    UseTls = true,
    ClientCertificatePath = "/etc/elsa/mqtt-client.p12",
    ClientCertificatePassword = configuration["Mqtt:CertificatePassword"]
});

The convenience options configure a TCP server, a 30-second keep-alive, and a 30-second client timeout. A missing ClientId gets a generated Elsa... ID. Username-only credentials are supported; a password is used only when a username is also supplied.

The subscriber reconnects after an unexpected disconnection. By default, MaxReconnectAttempts = 0 means unlimited attempts, and ReconnectBaseDelay is five seconds. The delay doubles for each attempt and is capped at five minutes. After reconnecting, the module restores the active topic subscriptions:

elsa.UseMqtt(mqtt =>
{
    mqtt.ConfigureOptions = options =>
    {
        options.MaxReconnectAttempts = 10;
        options.ReconnectBaseDelay = TimeSpan.FromSeconds(2);
        options.AddDefaultConnection(new MqttConnectionOptions
        {
            Host = "mqtt.example.com",
            Port = 8883,
            UseTls = true
        });
    };
});

The module does not create brokers, topics, users, certificates, or access rules. Provision those through the MQTT platform or deployment tooling.

Receive MQTT messages

Add MQTT Message Received from the MQTT category. It has these inputs and outputs:

Property

Direction

Behavior

Connection Name

Input

Selects a configured connection; defaults to Default.

Topics

Input

One or more MQTT topic filters. At least one filter is required.

Received MQTT Message

Output

An MqttMessage containing Topic and text Message values.

The topic filter supports MQTT's + single-level and # multi-level wildcards. For example, devices/+/temperature matches one device level, while devices/# matches that prefix and any remaining levels.

At the start of a workflow, the activity is a trigger. Inside a running workflow, it creates a bookmark and waits for a matching message. The module passes the received message into the workflow, sets the output, and uses the message text as the activity result.

For example, a workflow can wait for a sensor event and then publish an alert:

using Elsa.Mqtt.Activities;
using Elsa.Workflows.Activities;
using Elsa.Workflows.Models;
using MQTTnet.Protocol;

var workflow = new Sequence
{
    Activities =
    {
        new MqttMessageReceived
        {
            ConnectionName = new("telemetry"),
            Topics = new(new List<string> { "devices/+/temperature" })
        },
        new PublishMqttMessage
        {
            ConnectionName = new("telemetry"),
            Topic = new("alerts/temperature"),
            Message = new("Temperature message received"),
            QualityOfServiceLevel = new(MqttQualityOfServiceLevel.AtLeastOnce),
            Retain = new(false)
        }
    }
};

The module converts the MQTT payload to a string before creating MqttMessage. It does not expose the original binary payload, MQTT 5 user properties, subscription identifiers, or shared-subscription metadata through this activity.

Publish MQTT messages

Add Publish MQTT message from the MQTT category. Configure:

Connection Name — the named broker connection.
Topic — the destination topic. Blank or whitespace-only values produce the Failure outcome.
Message — the text payload. A null value produces the Failure outcome.
QoS — 0 - At Most Once, 1 - At Least Once, or 2 - Exactly Once.
Retain — whether the broker should retain the message.

The activity performs one MQTT publish call. A successful broker response completes the activity with the Success outcome and a true result. A negative broker response completes it with Failure and a false result. The activity journals the broker reason code, reason string, topic, and message length; it does not add a dead-letter or retry queue.

The QoS dropdown is provided by the server module, so it appears in Studio after the MQTT package is installed and the server is restarted. The connection-name dropdown is populated from the names registered in MqttOptions.

How subscriptions and workflow delivery work

The module keeps MQTT subscriptions aligned with persisted Elsa state:

At startup, the MQTT background task loads stored MQTT Message Received triggers and bookmarks.
Elsa creates one subscriber for each named connection that has a trigger or bookmark. It subscribes to the distinct topic filters currently required by those bindings.
When a workflow definition or bookmark is indexed, added, removed, or deleted, the module updates the broker subscriptions.
An incoming message is matched against the stored filters. Matching start triggers invoke new workflow instances; matching bookmarks are queued to resume their workflow instances.

The subscriber asks the broker for QoS 1 (At Least Once) when it subscribes, independently of the QoS selected by Publish MQTT message. The module does not provide a shared-consumer group across Elsa hosts. Each host creates its own MQTT client, using a generated client ID by default, so a scale-out design must account for duplicate delivery and idempotent workflow effects according to the broker's client and subscription semantics.

Studio and deployment boundaries

The MQTT package is server-side. Studio can display and configure the activities after it receives their descriptors, but it does not open broker connections, manage topics, test credentials, or provide an MQTT resource administration page. Broker connectivity and subscription logs belong to the Elsa Server process.

For a split deployment, run the MQTT module on the host that should receive messages and has access to workflow persistence. Registering the module on multiple hosts creates multiple broker clients and is not a built-in load balancing strategy.

Troubleshooting

The activity is missing from Studio

Confirm that Elsa.Mqtt is installed in the server application, UseMqtt is registered, and the server has restarted. Studio receives the activity list from the server; installing a package only in the Studio frontend does not add the server activity.

The connection name is not available

The dropdown lists the keys in MqttOptions.Connections. Register the name with AddConnection or use AddDefaultConnection and leave the activity input empty. Check spelling and casing; resolution is case-insensitive, but a name still must exist.

A trigger never receives messages

Check that the server can connect to the configured broker, the topic filter is valid, and the incoming topic matches the filter. Inspect server logs for the subscription and reconnect messages. Remember that an inline MQTT Message Received activity creates a bookmark only after the workflow reaches that activity.

The workflow receives duplicate events

Inspect whether more than one Elsa host is connected with an active subscription. The module creates a client per host and does not coordinate a shared consumer group. Make downstream effects idempotent and verify the broker's subscription and client configuration.

Release source

This page describes the Elsa Extensions release/3.9.0 implementation:

PreviousKafka activities

NextLDAP activities

Last updated 18 days ago