Operation

Operations are actions that are executed within Objects and Links. For example, you can restart a service, open garage doors, turn off the lights. They can be started manually by Users or automatically on Property modification and State changing.

Warning

Operations are executed by SAYMON Server, not SAYMON Agents.

Operations can be added to Objects, Links or Classes. If an operation is set to Class, all entities of this Class inherit this Operation. You can also use variables to add an Operation to Class and execute it with Object- or User- specific data.

There are two types of Operations:

MQTT message publish;
script execution.

Info

Set of operation fields depends on user's permissions. Users with the manage-operations permission get all existing fields, while users with the execute-operations permission get id, name and description fields only.

Operation Model

Field	Type	Description
id	String `required`	Operation's ID.
name	String `required`	Operation's name.
type	String `required`	Operation's type. `1` is an MQTT message, `2` is a program/script. See the Operation Types section for more information and examples.
description	String	Operation's description.
popupResult	Boolean	Whether to show the results of the operation in a popup message.
runOnReadWritePropertyModification	Boolean	Whether to run this operation on ReadWrite property modification.
parameters	Object	A set of type-specific parameters for the operation.
parameters.message	String	An MQTT message. This parameter should be specified only for the MQTT message type.
parameters.topic	String	An MQTT topic. This parameter should be specified only for the MQTT message type.
parameters.type	String	A subtype of the current script's type. Available types: `fileSystem`, `scriptReference`, `scriptText`.
parameters.path	String	A path to a script. This parameter should be specified only for the `fileSystem` subtype.
parameters.args	Array<String>	An array of script's input parameters. This parameter should be specified only for the `fileSystem` subtype.
parameters.ref	String	The ID of a script. This parameter should be specified only for the `scriptReference` subtype.
parameters.text	String	A script's source code. This parameter should be specified only for the `scriptText` subtype.

Operation Types

MQTT Publish

type_id: 1

This type of Operation publishes a message to a topic with MQTT protocol.

Here is an example that turns off the lights:

{
  "name": "Lights control",
  "operations": [
    {
      "name": "Turn off",
      "parameters": {
        "topic": "home/lights/control",
        "message": "off"
      },
      "description": "Turn off all lights",
      "type": 1,
      "id": "5df326a653e27e5dfa33aaaa"
    }
  ],
  ...
}

Info

Connection to MQTT-broker is specified in SAYMON Server configuration file:

/etc/saymon/saymon-server.conf

Script Execution

type_id: 2

This Operation executes a script from a file system, Repository or a script with the given text.

This example shows all possible sources for the scripts that can be executed by the operation — a script from a file system, a repository or a script written in the operation's text field.

{
  "name": "Heater",
  "operations": [
    {
        "name": "Script from a file system",
        "parameters": {
            "path": "/home/scripts/start_heater.py",
            "type": "fileSystem",
            "args": [
                "1_h"
            ]
        },
        "description": "Start a heater for 1 hour.",
        "type": 2,
        "id": "5df32c4f53e27e5dfa33aacd"
    },
    {
        "name": "Script from a repository",
        "description": "Start a heater for 1 hour.",
        "type": 2,
        "popupResult": false,
        "parameters": {
            "ref": "5ecfc1e06d9341263ceaaeb3",
            "type": "scriptReference",
            "args": [
                "1_h"
            ]
        }
    },
    {
        "name": "Plain text script",
        "description": "Print 'Hello World!'",
        "popupResult": true,
        "type": 2,
        "parameters": {
            "type": "scriptText",
            "text": "echo 'Hello World!'"
        }
    }   
  ],
  ...
}

Run on Property Modification

Operation can be started automatically when ReadWrite Property is modified. To do this, use the following flag for Operation:

runOnReadWritePropertyModification: true

Here is an example of an Object that executes an Operation when the Temperature is modified:

{
  "name": "Heater",
  "properties": [
    {
      "name": "Temperature",
      "value": "24",
      "type_id": 3,                                  // ReadWrite Property
      "id": "5df1f64453e27e5dfa333da7"
    }
  ],
  "operations": [
    {
      "runOnReadWritePropertyModification": true,    // Run when Property modified
      "name": "Script from a file system",
      "parameters": {
        "path": "/home/scripts/config_heater.py",
        "type": "fileSystem"
      },
      "description": "Set heater temperature.",
      "type": 2,
      "id": "5df32c4f53e27e5dfa33aacd"
    }
  ],
  ...
}

Variables

It's possible to use Variables in Operations. Define Variable with double curly braces in MQTT-topic, MQTT-message, script text or args.

Here is a list of supported Variables:

Usage	Description
{{args.<arg_name>}}	Value of an argument you can post in a body of Execute Object Operation and Execute Link Operation requests.
{{id}}	ID of an Object, where Operation is started.
{{properties.<prop_name>}}	Value of Property of an Object, where Operation is started. <prop_name> is a name of Property. You can use spaces in Properties name for example {{properties.name with spaces}}.
{{jobId}}	Every time you execute an Operation, a Job is created. You can use this variable to pass the ID of the created Job to your Operation. Use it to Add Custom Job Result.
{{user.id}}	ID of User, who starts Operation.
{{user.login}}	Login of User, who starts Operation.

Here is an example of Object with some Properties and respective Operation with Variables:

{
  "name": "Heater",
  "properties": [
    {
      "name": "Temperature",
      "value": "24",
      "type_id": 3,                                            // ReadWrite Property
      "id": "5df1f64453e27e5dfa333da7"
    },
    {
      "name": "My phone num",
      "value": "14151234567",
      "type_id": 1,
      "id": "5df1f6ae53e27e5dfa333dce"
    }
  ],
  "operations": [
    {
      "runOnReadWritePropertyModification": true,              // Run when Property modified
      "name": "Send SMS",
      "parameters": {
        "topic": "sms/send/{{properties.My phone num}}",    // Variable
        "message": "Heater temp set to {{properties.Temperature}}"  // Variable
      },
      "description": "Heater temperature change notification",
      "type": 1,
      "id": "5df326a653e27e5dfa33aaaa"
    }
  ],
  ...
}