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 | Stringrequired |
Operation's ID. |
name | Stringrequired |
Operation's name. |
type | Stringrequired |
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
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
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:
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"
}
],
...
}