Show/Hide Toolbars

Руководство администратора

LUA-скрипты (Прежний интерфейс)

Ссылки Назад Вверх Вперед

term_icon LUA-скрипт — это код, написанный на языке Lua.

По сравнению с использованием SMART-выражений смарт-скрипты имеют ряд преимуществ:

Смарт-скрипты выполняются на сервере, а не в СУБД, а значит

oпозволяют снизить нагрузку на СУБД;

oвыполняются быстрее чем SMART-выражения.

Смарт-скрипты позволяют работать с контекстными данными, еще не записанными в БД.

В отличие от SMART и SQL, Lua — это полноценный программный язык. В Lua-скриптах удобнее работать с циклами, массивами, файлами и пр.

Смарт-скрипты имеют более высокую степень безопасности (например, защищены от SQL-инъекций).

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

Смарт-скрипты могут использоваться как вместо смарт-выражений, так и вместо смарт-фильтров (в последнем случае они должны возвращать значение true/false). Но обычно с помощью смарт-скриптов автоматизируют какие-то действия (создать задачу, заполнить таблицу и пр.). Если нужно просто вычислить и вернуть какое-то значение, чаще используют смарт-выражения.

Создание и редактирование смарт-скрипта

Вы можете создать смарт-скрипт по кнопке + или отредактировать — по кнопке !editиз окна редактирования смарт-действия. Для создания и редактирования смарт-скрипта открывается специальный интерфейс в отдельной вкладке браузера.

По кнопке ? (1) откроется подсказка по работе с смарт-скриптом и вызову смарт-действий. В зависимости от контекста, в котором вызывается смарт-скрипт, в него передается разный набор контекстных параметров (2). Нажав кнопку Выполнить, вы можете протестировать Исходный код. Результаты выполнения будут отображаться внизу окна (3).

lua_help

Интерфейс редактирования смарт-скрипта

Работа с LUA-скриптами

Для выполнения смарт-скрипта можно использовать смарт-действие Выполнить смарт-скрипт (раздел Прочее).

warning_icon  Все названия регистрозависимы!

Отладка и тестирование

Для отладки и тестирования смарт-скрипта удобно использовать функции var_dump или print — они выводят результат выполнения исходного кода в область внизу страницы. Отличие между ними в том, что var_dump может принимать любые типы данных, а print — только строковые.

lua_var_dump

Вывод с помощью функции var_dump

Контекст и параметры событий

warning_icon  Для корректной работы циклических смартов не рекомендуется использовать смарт-скрипты, т.к. в них невозможна передача контекстных параметров "Номер итерации" и "Значение итератора"

В зависимости от контекста, в котором вызывается смарт-скрипт, в него передается разный набор контекстных параметров.

в параметр CONTEXT передаются задача Task, пользователь User или Email,

в параметр EVENTPARAMS в виде массива передаются параметры события, для которого вызывается смарт-скрипт,

в параметр SESSION_USER передаются данные о пользователе, от имени которого ведется работа в системе.

параметр DB_TYPE позволяет получить тип используемой базы данных. Возможные варианты: MSSQL, PG.

параметр SYSTEM_INFO позволяет получить системную информацию. Возвращает объект с полями version - версия приложения, app - имя приложения: TC или Uniform.

warning_icon  Если смарт-скрипт не использует параметры события EVENTPARAMS, то он сохраняется с EventId = null

Параметры могут представлять собой структуру данных (Task — данные о задачи, User — данные о пользователе). В этом случае в коде можно обратиться к элементам этой структуры. Например, если в параметре CONTEXT передается задача, текст задачи можно получить так:

CONTEXT.Text

или

CONTEXT['Text']

или

CONTEXT["Text"]

Некоторые параметры из EVENTPARAMS передаются в скрипт как материализованный объект из БД. Например, EVENTPARAMS[InitiatorUserId] — это таблица объекта User. Для получения Id пользователя из нее необходимо писать: EVENTPARAMS[InitiatorUserId]["Id"], либо EVENTPARAMS[InitiatorUserId] — параметр распознает объект из БД и возьмет его Id.

Названия элементов структуры немного отличаются от названий полей соответствующих таблиц в БД. Чтобы посмотреть названия элементов структуры, при отладке используйте функцию var_dump:

lua_var_dump_structure

Просмотр структуры при отладке смарт-скрипта

CONTXT объекта Task

Если смарт-скрипт выполняется не в своем контексте, при его вызове пользователь увидит сообщение об ошибке:

smart_script_context_error

Пример сообщения об ошибке при несовпадении контекста события

Ошибки, связанные с работой смарт-скриптов (LUA), отображаются в общем Логе ошибок и в Логе ошибок бизнес-логики.

Результат

Результат, который возвращает смарт-скрипт, должен быть записан в переменную RESULT.

lua_result

Результат выполнения смарт-скрипта

Функции

Использование подсказки по функциям

С помощью подсказки, которая вызывается нажатием на значок ?, вы можете посмотреть функции, которые можно использовать в смарт-скриптах, и параметры, которые эти функции принимают.

На вкладке Основное есть список доступных функций и их параметров. Функции сгруппированы в классы, название класса используется как префикс функции.

Например, вам нужно выполнить смарт-действие из смарт-скрипта. На вкладке Основное вы можете увидеть, что для этого используется класс SMART и функция execute_action. Там же вы можете посмотреть, какие параметры нужно передать этой функции. Обязательные параметры отмечены символом *. При наведении указателя мыши в правом верхнем углу всплывает значок копирования, по нажатию на нему в текущее место в коде будет добавлен шаблон вызова этой функции:

lua_smart_execute_actionПараметры для вызова SMART:execute_action

SMART:execute_action('AttachSignature', @contextId, @contextType, {
  File = @string
})

warning_icon  Если необязательные параметры не указываются, вместо них нужно передавать пустые значения: {} вместо параметра с типом LuaTable, вместо параметра с типом string.

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

lua_smart_help_searchПоиск описания параметров смарт-действия

SMART:execute_action('SetPriority', @contextId, @contextType, {
  Task = @int,
  Priority = @byte,
  ChangingUser = @int
})

Вызов смарт-действия

Для вызова смарт-действия из смарт-скрипта используется функция SMART:execute_action.

Например, вызов смарт-действия для изменения приоритета в Lua-скрипте будет выглядеть так:

SMART:execute_action(
  'SetPriority',         -- смарт-действие
  CONTEXT.Id,           -- контекст вызова смарт-действия
  'task',               -- тип контекста
  {                     -- параметры конкретного смарт-действия
    Task = EVENTPARAMS.TaskId.Id,
    Priority = 1,
    ChangingUser = EVENTPARAMS.InitiatorUserId.Id
  }
);

В данном примере предполагается, что скрипт вызывается по нажатию на дополнительную кнопку. Поэтому в нем доступны контекстные параметры события "нажатие на кнопку": EVENTPARAMS.TaskId — задача, в которой выполняется действие, и EVENTPARAMS.InitiatorUserId — пользователь, нажавший кнопку.

Асинхронное выполнение

Смарт-действия могут быть вызваны из смарт-скрипта в асинхронном режиме.

Пример вызова:

SMART:execute_action(

'ExecuteSmartScript',

nil,

nil,

{

Script = @string

}, true)

При асинхронном вызове результат не возвращается из execute_action, что значительно ускоряет работу.

В смарте, вызванном через ExecuteSmartScript (в любом режиме), доступны EVENTPARAMS пакета, из которого он вызван.

В смарт-действии, вызванном из смарт-скрипта LUA в асинхронном режиме через ExecuteSmartScript доступны контекстные параметры (EVENTPARAMS) пакета, из которого он вызван.

Вызов SQL запроса

Для выполнения смарт-запроса из смарт-скрипта используются функции SQL:scalar, SQL:query и SQL:query_one.

Например, так можно получить значение ИНН контрагента, выбранного в текущей задаче (ДП "Контрагент" имеет ID=11, ДП "ИНН" имеет ID=22):

local customerInn = SQL:scalar([[
  SELECT TOP 1 epv2.ExtParamValue
  FROM ExtParamValues epv1
     JOIN ExtParamValues epv2 ON epv2.TaskID = epv1.SelectedTaskId AND epv2.ExtParamId = 22
  WHERE epv1.TaskID = @taskId AND epv1.ExtParamId = 11
]], {taskId = CONTEXT.Id});
 
RESULT = customerInn

Так можно выбрать все активные задачи, где заказчиком является определенный пользователь:

RESULT = SQL:query(
  [[
    SELECT TaskID FROM Tasks WHERE UserId = @UserId AND IsActive = 1
  ]],
  { UserId = EVENTPARAMS.InitiatorUserId.Id }
);

В данном примере предполагается, что скрипт вызывается по нажатию на дополнительную кнопку. Поэтому в нем доступны контекстные параметры события "нажатие на кнопку", в том числе EVENTPARAMS.InitiatorUserId — пользователь, нажавший кнопку.

SQL:query_one  возвращает первую строку из результирующего запроса в виде Lua-таблицы, в отличии от SQL:query, которая возвращает весь набор как массив Lua-таблиц.

Пример использования функции SQL:query_one:

local Task = SQL:query_one("select top 5 TaskID, UserID from Tasks",{})

var_dump(Task)

var_dump(string.format("TaskID = %s UserID = %s",Task.TaskID,Task.UserID))

var_dump(string.format("№Задачи %s Идентификатор пользователя %s",Task["TaskID"],Task["UserID"]))

Вызов хранимой процедуры

Для вызова хранимой процедуры из смарт-скрипта также используется функция SQL:query.

Например, для вызова процедуры расчета бонусов из задачи вызывается хранимая процедура, в которую передается номер задачи:

SQL:query(
  [[
    exec [dbo].[calculate_bonus] @TaskId = @Id
  ]],
  { Id = CONTEXT.Id }
);

Вызов HTTP-запроса

Для выполнения HTTP-запроса из смарт-скрипта используется функция HTTP:send_http_request.

Например, так можно вызвать и обработать запрос, который получает курс валюты с сайта ЦБ:

local json_res = HTTP:send_http_request('get', 'https://www.cbr-xml-daily.ru/daily_json.js', {}, {}, '', {});
local content = json_res['HttpResponse']['ResponseContent'];     -- выделяем строку с телом ответа
local json_content = UTILS:json_decode(content);                 -- преобразуем строку с телом ответа в JSON
RESULT = json_content['Valute']['EUR']['Value'];

См. аналогичный пример, реализованный с помощью SMART.

Комментирование

Комментарий начинается с двойного дефиса -- и продолжается до конца строки. Вы можете управлять комментированием с помощью горячих клавиш:

CTRL + K + C — закомментировать выделенные строки в коде.

CTRL + K + U — раскомментировать выделенные строки в коде.

Lua подерживает блочные комментарии, которые начинаются с --[[ и продолжаются до закрывающего ]]. Вы можете закомментировать таким образом блок кода с помощью горячих клавиш: CTRL + /

Полезные ссылки