Message Republish

Through the Data Integration, it's possible to republish messages that meet certain conditions to other topics without writing any code. In the EMQX Broker, you can create rules, define rule SQL to filter and process data from source messages, and add a "Message Republish" action to the rule to forward the processed results via message publishing.

This page provides a demonstration of how to create data integration to republish a message to the greet topic whenever any message's msg contains the string hello. The main steps include:

1. Creating a rule to set filtering conditions.
2. Adding an action to the rule for message republishing.
3. Completing the creation of data integration and conducting tests.

Configuring the message republishing feature through data integration does not require adding any connectors. The following sections outline the specific configuration steps.

Create a Rule

1. In the Data Integration page, under the Data Forward service category, click Republish. If you have already created other connectors, click New Connector, and then select Republish under the Data Forward service category.

2. Define the rule SQL in the SQL Editor to trigger the engine whenever msg in any message contains the string hello:

   • Specify the source of message data in the FROM clause. This demonstration targets messages from all topics, i.e., #.
   • Perform regex matching in the WHERE clause on msg in the message payload to execute data integration if it contains the string hello.

   An example SQL definition based on the above principles is as follows:

   SELECT
     payload.msg as msg
   FROM
     "#"
   WHERE  
     regex_match(msg, 'hello')

3. You can click the Try It Out below the SQL input box and fill in the data:

   • Topic: t/a
   • Payload:

   {
     "msg": "hello test"
   }

   Click Test and check the Output Result. If set correctly, the Field and Value should display the complete JSON data, as follows:

   {
     "msg": "hello test"
   }

   If the test output matches expectations, you can proceed to the next steps.

   Note: If the test fails, please check if the SQL is compliant.

Add an Action

1. On the New Rule step page, click Next to add an action.

2. On the New Action step page, configure the following parameters:

   • Connector: Keep the default value Republish.
   • Topic: Set the target topic as greet.
   • Payload: Fill in ${msg} -- forward from EMQX Cloud as the message content template.
   • Leave QoS at its default value.

3. Configure the MQTT 5.0 Message Properties options (optional) by clicking the toggle switch. For more information on these options, see MQTT 5.0 Message Properties.

4. If you need to enable the Direct Dispatch, click the toggle switch. Once enabled, the message is dispatched directly to subscribers. It helps prevent the triggering of additional rules or the recursive activation of the same rule.

5. Click Confirm to complete the action and rule creation.

6. In the Successful new rule pop-up, click Back to Rules, and test the rule according to the instructions in Test Message Republish. Alternatively, you can click Test Rules and input simulated data on the page to test the rule. For details, see Test Rules.

Test Message Republish

You are recommended to use MQTTX to simulate message reporting, but you can also use any other client.

1. Use MQTTX to connect to the deployment and send a message to the test topic.

   {
     "msg": "hello"
   }

2. Find the message republishing rule in the rule list and click on the rule ID to enter the rule statistics page. You can see the related statistical indicators on the page. Click the reset button to reset the metrics data.

   TIP

   Serverless deployments do not support metrics reset.

   

3. Subscribe to the greet topic on the client. You will see that if msg contains hello, the message will be forwarded, and if not, it will not be forwarded.

   

Action Parameters

Parameter	Description
Topic	Sets the target topic for republished messages. Supports dynamic topic construction using ${field} syntax. Type $ in the input box to select available variables from the dropdown list.
QoS	Sets the QoS level for republished messages.
Retain	Sets whether to forward this message as a retained message.
Payload	Sets the message body content for republished messages. Supports ${field} syntax to reference fields from the rule SQL output. Type $ in the editor to select available variables from the dropdown list. Enter ${payload} to republish with the same payload as the original message without modification.
MQTT 5.0 Message Properties	Click the toggle switch to configure message properties as needed. Allows you to attach rich message metadata to republished messages. See details below.
Direct Dispatch	When enabled, the message is dispatched directly to subscribers, preventing the triggering of additional rules or recursive activation of the same rule.

MQTT 5.0 Message Properties

Parameter	Description
Payload Format Indicator	Indicates the payload format. When set to false, the message is treated as undetermined bytes. When set to true, the payload is UTF-8 encoded character data, helping clients parse the content efficiently.
Message Expiry Interval	Enter a value in seconds to specify when a message should expire if not delivered to the intended recipient.
Content Type	Specifies the type or format (MIME type) of the payload content in republished messages, for example text/plain, audio/aac, or application/json.
Response Topic	Enter the specific MQTT topic to publish response messages to, for example response/my_device.
Correlation Data	Enter a unique identifier linking a response to its original request, such as a transaction ID or request identifier.