SmartDCIM

Операция

Операция

Операция ​

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

NOTE

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

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

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

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

NOTE

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

Операция ​

ПолеТипОписание
commentStringПользовательский комментарий к операции.
descriptionStringОписание операции.
idString

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-сообщения ​

json
type_id: 1

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

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

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

NOTE

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

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

json
type_id: 2

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

json
{
  "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. Для этого операции необходимо указать следующий флаг:

json
runOnReadWritePropertyModification: true

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

json
{
  "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 значение данной переменной заменяется на пустую строку.

| | При выполнении запросов Выполнить операцию объекта и Выполнить операцию связи напрямую через rest-api значение данной переменной заменяется на пустую строку. | | | При выполнении запросов Выполнить операцию объекта и Выполнить операцию связи напрямую через rest-api значение данной переменной заменяется на пустую строку. | | | | {{args.<arg_name>}} | Значение аргумента, передаваемого в теле запросов Выполнение Операции Объекта и Выполнение Операции Связи. | | | | {{id}} | Идентификатор Объекта, в котором запускается операция. | | | | {{jobId}} | При каждом запуске Операции создается Задача. Идентификатор созданной задачи можно передать в Операцию и использовать его для Добавления пользовательских результатов выполнения операции. | | | | {{properties.<prop_name>}} | Значение Свойства Объекта, в котором запускается операция. <prop_name> - имя Свойства. В именах свойств можно использовать пробелы, например, {{properties.name with spaces}}. | | | | {{user.id}} | Идентификатор пользователя, который запустил операцию. | | | | {{user.login}} | Имя пользователя, который запустил операцию. | | |

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

json
{
  "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/&#123;&#123;properties.My phone num&#125;&#125;",    // Variable
        "message": "Heater temp set to &#123;&#123;properties.Temperature&#125;&#125;"  // Variable
      },
      "description": "Heater temperature change notification",
      "type": 1,
      "id": "5df326a653e27e5dfa33aaaa"
    }
  ],
  ...
}