Create rules

Create rules using Dashboard

Create WebHook rules

  1. Setup a Web Service, here we setup a simple web service using the linux tool nc:
  1. $ while true; do echo -e "HTTP/1.1 200 OK\n\n $(date)" | nc -l 127.0.0.1 8081; done;

  1. Create a rule:

    Go to EMQ X Dashboard Create rules - 图1 (opens new window), select the “rule” tab on the menu to the left.

    Select “message.publish”, then type in the following SQL:

    1.    SELECT
    2.      *
    3.    FROM
    4.        "t/#"
    5.    WHERE
    6.         qos = 1

    image

  2. Bind an action:

    Click on the “+ Add” button under “Action Handler”, and then select “Data to Web Server” in the pop-up dialog window.

image

  1. Bind a resource to the action:

    Since the dropdown list “Resource” is empty for now, we create a new resource by clicking on the “New Resource” to the top right:

    image

    then select “WebHook”:

    image

  2. Configure the resource:

    Fill in the “Request URL” and “Request Header”(Optional):

    http://127.0.0.1:8081

    And click on the “Testing Connection” button to make sure the connection can be created successfully, and then click on the “Create” button.

    image

  3. Back to the “Actions” dialog, and then click on the “Confirm” button.

    image

  4. Back to the creating rule page, then click on “Create” button. The rule we created will be show in the rule list

image

We have finished, testing the rule by sending an MQTT message to emqx:

image

  1. send a message

    Topic: “t/1”

    QoS: 1

    Payload: “Hello web server”

Then check if the web service receives the message:

image

Create Simple Rules using CLI

Create Inspect Rules

Create a rule for testing: print the content of the message and all the args of the action, when a MQTT message is sent to topic ‘t/a’.

  • The filter SQL is: SELECT * FROM “message.publish” WHERE topic = ‘t/a’;
  • The action is: “print the content of the message and all the args of the action”, the action we need is ‘inspect’.
  1. $ ./bin/emqx_ctl rules create \
  2.   "SELECT * FROM \"message.publish\" WHERE topic = 't/a'" \
  3.   '[{"name":"inspect", "params": {"a": 1}}]' \
  4.   -d 'Rule for debug'
  6. Rule rule:803de6db created

The CLI above created a rule with ID=’Rule rule:803de6db’.

The first two args are mandatory:

  • SQL: SELECT * FROM “message.publish” WHERE topic = ‘t/a’
  • Action List: [{“name”:”inspect”, “params”: {“a”: 1}}]. Action List is of type JSON Array. “name” is the name of the action, “params” is the parameters of the action. Note that the action inspect does not need a resource.

The last arg is an optional description of the rule: ‘Rule for debug’.

If a MQTT message “hello” is sent to topic ‘t/a’, the rule “Rule rule:803de6db” will be matched, and then action “inspect” will be triggered, the following info will be printed to the emqx console:

  1. $ tail -f log/erlang.log.1
  3. (emqx@127.0.0.1)1> [inspect]
  4.     Selected Data: #{client_id => <<"shawn">>,event => 'message.publish',
  5.                       flags => #{dup => false,retain => false},
  6.                       id => <<"5898704A55D6AF4430000083D0002">>,
  7.                       payload => <<"hello">>,
  8.                       peername => <<"127.0.0.1:61770">>,qos => 1,
  9.                       timestamp => 1558587875090,topic => <<"t/a">>,
  10.                       username => undefined}
  11.     Envs: #{event => 'message.publish',
  12.             flags => #{dup => false,retain => false},
  13.             from => <<"shawn">>,
  14.             headers =>
  15.                 #{allow_publish => true,
  16.                   peername => {{127,0,0,1},61770},
  17.                   username => undefined},
  18.             id => <<0,5,137,135,4,165,93,106,244,67,0,0,8,61,0,2>>,
  19.             payload => <<"hello">>,qos => 1,
  20.             timestamp => {1558,587875,89754},
  21.             topic => <<"t/a">>}
  22.     Action Init Params: #{<<"a">> => 1}
  • Selected Data listed the fields that selected by the SQL. All available fields will be listed here, as we used select *.
  • Envs is the environment variables that can be used internally in the action.
  • Action Init Params is the params we passed to the action.

Create WebHook Rule

Create a rule: Forward all the messages that send from client_id=’Steven’, to the Web Server at ‘http://127.0.0.1:9910 Create rules - 图11 (opens new window)’:

  1. Create a simpile Web service using linux tool nc:

    1. $ while true; do echo -e "HTTP/1.1 200 OK\n\n $(date)" | nc -l 127.0.0.1 9910; done;

  2. Create a resource of resource type “WebHook”, and configure the url:

    1). List all available resource types, make sure ‘web_hook’ exists:

    1. $ ./bin/emqx_ctl resource-types list
    3. resource_type(name='web_hook', provider='emqx_web_hook', params=#{...}}, on_create={emqx_web_hook_actions,on_resource_create}, description='WebHook Resource')
    4. ...

    2). Create a new resource using resource type ‘web_hook’, configure “url”=”http://127.0.0.1:9910 Create rules - 图14 (opens new window)”:

    1. $ ./bin/emqx_ctl resources create \
    2.   'web_hook' \
    3.   -c '{"url": "http://127.0.0.1:9910", "headers": {"token":"axfw34y235wrq234t4ersgw4t"}, "method": "POST"}'
    5. Resource resource:691c29ba created

    Above CLI created a resource with ID=’resource:691c29ba’, the first arg is mandatory - The resource type (web_hook). HTTP method is POST, and an HTTP Header is set: “token”.

  3. Create a rule, and bind action ‘data_to_webserver’ to it:

    1). List all available actions, make sure ‘data_to_webserver’ exists:

    1. $ ./bin/emqx_ctl rule-actions list
    3. action(name='data_to_webserver', app='emqx_web_hook', for='$any', types=[web_hook], params=#{'$resource' => ...}, title ='Data to Web Server', description='Forward Messages to Web Server')
    4. ...

    2). Create the rule, bind the action data_to_webserver, and bind resource resource:691c29ba to the action via the arg “$resource”:

  1.     $ ./bin/emqx_ctl rules create \
  2.       "SELECT username as u, payload FROM \"message.publish\" where u='Steven'" \
  3.       '[{"name":"data_to_webserver", "params": {"$resource":  "resource:691c29ba"}}]' \
  4.       -d "Forward publish msgs from steven to webserver"
  6. rule:26d84768

Above CLI is simlar to the first Inspect rule, with exception that the resource ‘resource:691c29ba’ is bound to ‘data_to_webserver’. The binding is done by a special arg named ‘$resource’. What the action ‘data_to_webserver’ does is sending messages to the specified web server.

  1. Now let’s send a message “hello” to an arbitrary topic using username “Steven”, this will trigger the rule we created above, and the Web Server will receive an message and return 200 OK:
  1. $ while true; do echo -e "HTTP/1.1 200 OK\n\n $(date)" | nc -l 127.0.0.1 9910; done;
  3. POST / HTTP/1.1
  4. content-type: application/json
  5. content-length: 32
  6. te:
  7. host: 127.0.0.1:9910
  8. connection: keep-alive
  9. token: axfw34y235wrq234t4ersgw4t
  11. {"payload":"hello","u":"Steven"}