Операция

Операции - это действия, выполняемые в Объектах и Связях. Например, операция может перезапустить сервис, открыть дверь гаража или выключить освещение. Операции могут запускаться вручную Пользователями или автоматически при изменении Свойства и Состояния.

Операции запускаются сервером системы, а не агентами.

Операции добавляются Объектам, Связям и Классам. Если Операция добавляется Классу, то все сущности данного Класса наследуют Операцию. В Операциях можно использовать переменные Объектов и Пользователей.

Существует два типа Операций:

  • публикация MQTT-сообщения;

  • запуск скрипта.

Набор полей операции зависит от прав пользователя. Пользователи с правами manage-operations получают все поля, а пользователи с правами execute-operations только поля id, name и description.

Операция

Поле Тип Описание

description

String

Описание операции.

id

String
required

Идентификатор операции.

name

String
required

Имя операции.

parameters

Object

Набор параметров операции.

parameters.message

String

MQTT-сообщение. Этот параметр должен быть определён только для типа MQTT-сообщение.

parameters.topic

String

MQTT-топик. Этот параметр должен быть определён только для типа MQTT-сообщение.

parameters.type

String

Подтип операции запуск скрипта. Доступные подтипы – fileSystem, scriptReference, scriptText.

parameters.path

String

Путь до скрипта. Этот параметр должен быть определён только для подтипа fileSystem.

parameters.args

Array<String>

Массив аргументов скрипта. Этот параметр должен быть определён только для подтипа fileSystem.

parameters.ref

String

Идентификатор скрипта. Этот параметр должен быть определён только для подтипа scriptReference.

parameters.text

String

Исходный код скрипта. Этот параметр должен быть определён только для подтипа scriptText.

popupResult

Boolean

Показывать результаты операции во всплывающем окне в веб-интерфейсе.

runOnReadWritePropertyModification

Boolean

Запуск операции при изменении свойства типа ReadWrite.

type

String
required

Тип операции. 1 - MQTT-сообщение, 2 - программа/скрипт. Дополнительная информация и примеры доступны ниже в разделе Типы Операций.

Типы Операций

Публикация MQTT-сообщения

type_id: 1

Данный тип операции публикует сообщение в указаный топик, используя протокол MQTT.

В данном примере выключается свет:

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

Подключение к MQTT-брокеру указывается в конфигурационном файле сервера системы:

/etc/saymon/saymon-server.conf

Выполнение скрипта

type_id: 2

Данный тип операции запускает скрипт из файловой системы, Репозитория или скрипт с указанным текстом, например:

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

Запуск при изменении свойства

Операция может запускаться автоматически при изменении свойства типа ReadWrite. Для этого операции необходимо указать следующий флаг:

runOnReadWritePropertyModification: true

Пример запуска операции при изменении свойства Temperature объекта:

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

Переменные

В Операциях можно использовать Переменные. Переменные задаются в двойных фигурных скобках в MQTT-топике, MQTT-сообщении, тексте скрипта или поле args.

Список доступных переменных:

Переменная Описание

{{ask.<argument_name>}}

Запрашивает значение указанной переменной у пользователя в веб-интерфейсе системы. Дополнительная информация доступна в статье Операции.

При выполнении запросов Выполнить операцию объекта и Выполнить операцию связи напрямую через rest-api значение данной переменной заменяется на пустую строку.

{{args.<arg_name>}}

Значение аргумента, передаваемого в теле запросов Выполнение Операции Объекта и Выполнение Операции Связи.

{{id}}

Идентификатор Объекта, в котором запускается операция.

{{jobId}}

При каждом запуске Операции создается Задача. Идентификатор созданной задачи можно передать в Операцию и использовать его для Добавления пользовательских результатов выполнения операции.

{{properties.<prop_name>}}

Значение Свойства Объекта, в котором запускается операция. <prop_name> - имя Свойства. В именах свойств можно использовать пробелы, например, {{properties.name with spaces}}.

{{user.id}}

Идентификатор пользователя, который запустил операцию.

{{user.login}}

Имя пользователя, который запустил операцию.

Пример Объекта с набором Свойств и соответствующими Операциями с Переменными:

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