Пользовательские скрипты

Пользовательские скрипты предназначены для расширения стандартной функциональности Business Studio без изменения исходного кода системы.

С помощью пользовательских скриптов можно:

реализовать собственную логику обработки объектов;
автоматизировать выполнение действий;
вычислять значения параметров.

Пользовательские скрипты имеют единые данные в ветках (см. Основные понятия и свойства ветки).

Внимание! Выполнение пользовательских скриптов регулируется лицензией продукта. Создание, редактирование и настройка пользовательских скриптов доступны только в редакции Ultimate. Во всех редакциях допускается выполнение поставляемых системой (вендорских) скриптов.

Внимание! При выполнении пользовательского скрипта не выполняется проверка прав доступа. Доступ к пользовательским скриптам необходимо регулировать правами. Обычным пользователям не следует предоставлять права на создание и редактирование пользовательских скриптов.

Пользовательские скрипты создаются на языке C# или JavaScript (JS) и выполняются сервером Business Studio.

Скрипты на JS и C#

JS cкрипты предназначены для выполнения лёгких автоматизируемых задач без прямого доступа к объектной модели Business Studio. Они рекомендуются для сценариев, где не требуется глубокая интеграция:

Триггеры и события.
Обращения к внешним системам — вызов REST/OData API, отправка вебхуков, интеграция со сторонними сервисами (например, уведомление в Slack, создание задачи в Jira).
Вывод информации в консоль.
Передача во внешние системы данных небольшого объема (например, ID записи, статус, метаданные).
Взаимодействие с Business Studio через OData или другие API-интерфейсы.

Для доступа к объектной модели и глубокой интеграции рекомендуется использование C# скриптов.

Типы скриптов

В Business Studio поддерживаются следующие типы пользовательских скриптов:

Тип	Примеры использования
Скрипты метаданных
Скрипты действия	Пользовательские действия в UX
Скрипты параметра	1. Вычисляемые параметры на пользовательских формулах 2. Проверка правильности диаграмм 3. · Сбор логов для отправки в системы класса CIEM.
Скрипты класса	1. Заполнение пользовательских умолчаний при создании объекта 2. Интеграции со сторониими системами (кейс: по событию создать объект в 1С) 3. Сбор логов для отправки в системы класса CIEM 4. Запуск оповещений, опросов
Скрипты в вычисляемых параметрах
Скрипты в вычисляемых параметрах	Расширение функционала вычисляемых параметров: расчет значений с использованием сложной логики

Таблица 1. Типы скриптов

Общий порядок создания скрипта

Работа со скриптами включает следующие этапы:

Создать Исполняемый скрипт.
Создать соответствующий скрипт метаданных или вычисляемый параметр, к которому будет привязан исполняемый скрипт.
Сохранить изменения, выполнить мягкую перезагрузку сервера и проверить выполнение скрипта.

Исполняемый скрипт

Исполняемые скрипты настраиваются и хранятся в справочнике Скрипты.

При создании исполняемого скрипта необходимо выбрать класс: C# скрипт или JS скрипт.

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

Блок кода – для вставки программного кода;
список Ссылки на сборки – подключаемые внешние библиотеки, использующиеся в скрипте.

Скрипты действия

Скрипты действия настраиваются и хранятся в справочнике Скрипты действия.

Скрипты действий запускаются пользователями при помощи следующих элементов интерфейса:

гиперссылки на форме свойств объекта соответствующего справочника (в десктопном приложении);
иконки быстрого действия на форме свойств объекта (в веб-приложении) и в Навигаторе (см. Рисунок 1).

Рисунок 1. Иконка быстрого действия на примере справочника «Физические лица»

Пример скрипта действия

Рассмотрим реализацию на примере создания скрипта «Показать ФИО+1», при выполнении которого для объекта справочника «Физические лица» в поле «Название» к текущему значению добавляется символ «1», а на панель уведомлений выводится значение параметра «ФИО».

Шаги:

Создать в справочнике «Скрипты» Исполняемый скрипт (C# скрипт) и заполнить поля:

Название: Показать ФИО+1
Ссылки на сборки:
- Sys.dll
- Sys.Server.dll
- AppPlatform.Server.dll
- BizArch.Server.dll
- CommonResources.dll

Блок кода:

using Byte.ORM.Sys;
using System.Collections.Generic;
var obj = Data["obj"] as Byte.ORM.AppPlatform.Person;
Byte.ORM.Sys.ServerApp.Notify($"ФИО: {obj.PersonFullName} "); //Вывод сообщения в консоль
obj.Name = obj.Name+"1"; //Модификация объекта
obj.Save(); //Сохранение объекта

Сохранить скрипт.
Создать в справочнике «Скрипты действия» Скрипт действия и заполнить поля:
- Активен: Да;
- Метакласс скрипта: выбрать класс «Физическое лицо»;
- Скрипт: выбрать скрипт «Показать ФИО+1»;
- ID действия: идентификатор для создания опции класса, оптимальная практика для выбора:
  - открыть Объектную модель и найти справочник (в данном примере «Физические лица»);
  - открыть вкладку Опции и посмотреть сколько опций по категории «Actions» присутствует в классе (2 опции на примере класса «Физическое лицо»);
  - в поле ID действия указать свободное число (рекомендуется для пользовательских действий вести нумерацию, отличную от нумерации вендорских действий, например, 101, 102 и т.д);
- Список Опции: указать следующие опции для действия:
  - Description = Показать ФИО+1
  - QuickAccess = Yes
  - Icon = 117
Выдать права на выполнение действия «Показать ФИО+1» в группе вертикальных прав (см. Редактирование группы вертикальных прав).
Выполнить Мягкий перезапуск сервера.

После указанных шагов в справочнике «Физические лица» появится иконка быстрого действия, при выполнении которого к названию выбранного объекта добавится символ «1», а на панель уведомлений будет выведено ФИО (см. Рисунок 2).

Рисунок 2. Вывод уведомления при выполнении действия.

Скрипты параметра

Скрипты параметра настраиваются и хранятся в справочнике Скрипты параметра.

Скрипты параметра позволяют выполнять пользовательский код при наступлении следующих событий:

При чтении – событие чтения параметра,
При изменении – событие изменения параметра.

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

Предусмотрены следующие вариации событий:

Чтение или изменение конкретного параметра класса.
Задается класс и параметр.
Чтение или изменение любого параметра класса.
Задается класс и устанавливается опция Все параметры.
Чтение или изменение любого параметра любого класса.
Устанавливаются опции Для всех классов и Все параметры.

Внимание! Скрипты с опциями Все параметры и/или Для всех классов работают только для хранимых параметров хранимых классов.

Для одного класса можно создать несколько скриптов параметра. В этом случае необходимо указать параметр Код, определяющий порядок их выполнения.

Данные, передаваемые в скрипт параметра

В скрипт параметра передаются:

Data["obj"] параметр, который обрабатывается:
```
Data["obj"] as Byte.ORM.Sys.DataObjectProperty;
```
Data["args"] – данные события.
Для события чтения передаётся значение параметра при чтении:
```
var e = Data["args"] as Byte.ORM.Sys.ЗначениеПараметраПриЧтении;
```
Для события изменения передаётся значение параметра при изменении:
```
var e = Data["args"] as Byte.ORM.Sys.ЗначениеПараметраПриИзменении;
```

Объект ЗначениеПараметраПриИзменении позволяет получить, в частности, старое и новое значения параметра, а также информацию о параметре.

Примеры скриптов параметра

Для параметра одного класса

Следующий скрипт выполняется при изменении заданного параметра и выводит старое значение и новое значение:

using Byte.ORM.Sys;
using System.Collections.Generic;

var args = Data["args"] as Byte.ORM.Sys.ЗначениеПараметраПриИзменении;
Byte.ORM.Sys.ServerApp.Notify($"При изменении названия оргединицы: {args.СтароеЗначение} -> {args.НовоеЗначение}");

Для всех параметров класса

Следующий скрипт выполняется при изменении любого параметра и выводит в панель сообщений название изменённого параметра, его старое и новое значения:

using Byte.ORM.Sys;
using System.Collections.Generic;
var args = Data["args"] as Byte.ORM.Sys.ЗначениеПараметраПриИзменении;
Byte.ORM.Sys.ServerApp.Notify($"Оргединица при изменении любого параметра: {args.Параметр.MetaClassProperty.Заголовок} {args.СтароеЗначение} ->{args.НовоеЗначение}");

Для всех параметров всех классов

Следующий скрипт выполняется при изменении любого параметра любого класса и выводит в панель сообщений название изменённого параметра, его старое и новое значения:

using Byte.ORM.Sys;
using System.Collections.Generic
var args = Data["args"] as Byte.ORM.Sys.ЗначениеПараметраПриИзменении;
if( args.Параметр.IsValueCalculating) return;
Byte.ORM.Sys.ServerApp.Notify($"При изменении все параметры все классы: {args.СтароеЗначение} ->{args.НовоеЗначение}, {args.Параметр.MetaClassProperty.Заголовок}");

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

Внимание! При применении скрипта ко всем классам или ко всем параметрам, нагрузка на систему возрастает.

Скрипты класса

Скрипты класса настраиваются и хранятся в справочнике Скрипты класса.

Скрипты класса позволяют выполнять пользовательский код при наступлении следующих событий:

При создании – создание объекта класса;
Перед сохранением – событие вызывается сразу после нажатия кнопки «Сохранить», но перед тем, как изменения будут записаны в базу данных;
После сохранения – событие вызывается после того, как изменения записаны в базу данных.

Примечание. Сначала выполняются стандартные обработчики событий, реализованные в Business Studio, затем – обработчики пользовательских скриптов.

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

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

Для конкретного класса.
Задается класс в поле Метакласс скрипта.
Для всех классов.
Поле Метакласс скрипта не заполняется, устанавливается опция Для всех классов.

Внимание! Скрипты с опцией Для всех классов работают только для хранимых параметров хранимых классов.

Для одного класса может быть задано несколько скриптов одного типа. В этом случае необходимо указать параметр Код, определяющий порядок выполнения скриптов.

Данные, передаваемые в скрипт класса

В скрипт класса передаются следующие данные:

Data["obj"] – объект, для которого выполняется скрипт. Доступ к объекту можно получить следующим образом:
```
Data["obj"] as Byte.ORM.Sys.DataObject;
```
При необходимости объект можно привести к совместимому типу.
Data["args"] – дополнительные данные, зависящие от события.

Для событий Перед сохранением и После сохранения передаётся объект АргументыСохранения:
```
Data["args"] as Byte.ORM.Sys.АргументыСохранения
```
Для события При создании передаётся тип объекта:
```
Byte.ORM.Sys.ТипОбъекта) Data["args"]
```

Пример скрипта класса

Следующий скрипт выполняется для всех классов и выводит уведомление при создании нового объекта:

using Byte.ORM.Sys; 
using System.Collections.Generic; 
var obj = Data["obj"] as Byte.ORM.Sys.DataObject; 
var obj_type = (Byte.ORM.Sys.ТипОбъекта)Data["args"]; 
if (obj_type == Byte.ORM.Sys.ТипОбъекта.Новый) Byte.ORM.Sys.ServerApp.Notify($"Глобальный скрипт {obj.MetaClass} ПриСоздании");

В результате при создании объекта выполняется пользовательский скрипт и в панели сообщений отображается уведомление с информацией о классе созданного объекта.

Скрипты в вычисляемых параметрах

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

Рекомендуется ознакомиться с вычисляемым параметром Процент согласовавших, представленном в системе Business Studio в справочнике Вычисляемые параметры по умолчанию. В данном вычисляемом параметре используется C# скрипт Расчёт процента согласовавших. С помощью данного вычисляемого параметра производится расчет процента согласовавших в справочнике Версии.

Данные, передаваемые в скрипт класса

В источниках данных находятся различные типы данных: строки, объект, список и перечисление.

В скрипт передаются следующие данные:

Объект, от которого вычисляется параметр. Способ получить:
```
Data["obj"] as Byte.ORM.Sys.DataObject;
```

Значение параметра при чтении. Способ получить:

var e = Data["args"] as Byte.ORM.Sys.ЗначениеПараметраПриЧтении;

Источники данных, обращение осуществляется по номеру. Например:
```
Var spr1 = Data["1"] as Byte.ORM.AppPlatform.SourcePropertiesRow;
```

Извлечение данных из источников производится при помощи методов класса AppPlatform.SourcePropertiesRow. Методы зависят от того, какие данные необходимо получить.

Пример скрипта вычисляемого параметра

Следующий пример призван продемонстрировать возможности вычисляемых параметров, работающих на скриптах. На Рисунке 3 показаны настройки вычисляемого параметра.

Рисунок 3. Настройки вычисляемого параметра.

Внимание! При разработке кода скрипта необходимо проверять объекты и их параметры на возможность чтения (горизонтальные и вертикальные права).

Пример кода скрипта:

using Byte.ORM.Sys; 
using System.Collections.Generic; 
using System.Text;
using Byte.ORM;
 
        var obj = Data["obj"] as Byte.ORM.Sys.DataObject;
        var e = Data["args"] as Byte.ORM.Sys.ЗначениеПараметраПриЧтении; //Получаем значение перечисления
var obj_enum = (Data["5"] as Byte.ORM.AppPlatform.SourcePropertiesRow)?.GetSourcePropertyEnumValue(Byte.ORM.BizArch.Objective.MetaClassStatic.Параметры[Byte.ORM.BizArch.Objective.n_PeriodLevel].ТипПеречисления, obj);
        Byte.ORM.AppPlatform.DateDiscretes obj_enum_val = Byte.ORM.AppPlatform.DateDiscretes.None;
        if (obj_enum != null) obj_enum_val = (Byte.ORM.AppPlatform.DateDiscretes)obj_enum;
 
        //Вы можете использовать ветвление, циклы, многие возможности языка C#
        switch (obj_enum_val)
        {
            case Byte.ORM.AppPlatform.DateDiscretes.Day:
                {
                    //Теперь возможны любые скобки и математические функции
                     e.Значение = (System.Math.Round(System.Math.Sin(155) + 100 / 500)).ToString();
                }
                break;
            case Byte.ORM.AppPlatform.DateDiscretes.Week:
               {
                     //Получаем объектное значение
                     e.Значение =  ((Data["6"] as Byte.ORM.AppPlatform.SourcePropertiesRow)?.GetSourcePropertyObjectValue(Byte.ORM.BizArch.ObjectiveAssessmentValue.MetaClassStatic, obj) as Byte.ORM.Sys.DataObject)?.ToString();
               }
               break;
            case Byte.ORM.AppPlatform.DateDiscretes.Month:
                {
                    //Получаем примитивное строковое значение
                    var obj_name = (Data["1"] as Byte.ORM.AppPlatform.SourcePropertiesRow)?.GetSourcePropertyPrimitiveValue(Byte.ORM.MD.MetaClassPropertyType.String, obj) as string;
                    e.Значение = obj_name;
                }
                break;
            case Byte.ORM.AppPlatform.DateDiscretes.Quarter:
            case Byte.ORM.AppPlatform.DateDiscretes.HalfYear:
                {
                    var obj_inCh = (Data["2"] as Byte.ORM.AppPlatform.SourcePropertiesRow)?.GetSourcePropertyPrimitiveValue(Byte.ORM.MD.MetaClassPropertyType.String, obj) as string;
                    if(obj_inCh == null) (obj_inCh = (Data["3"] as Byte.ORM.AppPlatform.SourcePropertiesRow)?.GetSourcePropertyPrimitiveValue(Byte.ORM.MD.MetaClassPropertyType.String, obj) as string;
                    e.Значение = obj_inCh;
                }
                break;
            case Byte.ORM.AppPlatform.DateDiscretes.Year:
                {
                    //Получаем списковое значение
                    var obj_MeasureList = (Data["3"] as Byte.ORM.AppPlatform.SourcePropertiesRow)?.GetSourcePropertyListValue(Byte.ORM.BizArch.Measure.MetaClassStatic, obj) as Byte.ORM.BizArch.MeasureList;
                    System.Text.StringBuilder sb = new System.Text.StringBuilder();
                    //Цикл по списку
                   foreach(Byte.ORM.BizArch.Measure measure in obj_MeasureList)
                    {
                       sb.Append(measure.Name).Append(",");
                    }
                    e.Значение = sb.ToString();
                }
                break;
            case Byte.ORM.AppPlatform.DateDiscretes.None:
                e.Значение = "Значение не определено, так как не задан тип переодичности.";
               break;
         }

Логирование скриптов в OpenSearch

В рамках скриптов можно отправлять данные в систему OpenSearch:

Byte.ORM.Sys.Debug.Log("Текст сообщения", "Файл сообщения", mode:
Byte.ORM.Sys.Debug.Modes.None, logLevel: Microsoft.Extensions.Logging.LogLevel.Debug);

Запуск Business Studio в безопасном режиме

Business Studio поддерживает запуск в безопасном режиме (/safemode).

После запуска Business Studio в безопасном режиме выполнение пользовательских скриптов отключается. Это позволяет изменить или отключить проблемный скрипт. В безопасном режиме пользовательские скрипты не выполняются независимо от их состояния.

Запуск в режиме /safemode доступен только администратору. Для запуска безопасного режима в web-приложении Business Studio, необходимо дописать ключ в env-файле:

COMMAND_LINE_ARGS="/DebugLogLevel=Info /safemode"