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.

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.

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"
    }
  ],
  ...
}

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.

{{ask.<argument_name>}}

Prompts user for this variable in the SAYMON UI. See the Operation article for more information.

This macro is replaced with an empty string when the operation is executed with the Execute Object Operation or Execute Link Operation requests.

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"
    }
  ],
  ...
}