Скрипт вычисления значения атрибута при редактировании

Описание скрипта

Скрипт предназначен для вычисления значения атрибута на различных формах добавления и редактирования в интерфейсе оператора.

Место настройки скрипта

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

Скрипт настраивается для атрибутов с параметром "Вычисление значения при редактировании" =да, см. Типы атрибутов и их параметры.

Когда выполняется скрипт

Первый раз скрипт выполняется в интерфейсе администратора при сохранении атрибута с признаком "Вычисление значения при редактировании" (значение переменной form = null).

В интерфейсе оператора скрипт выполняется:

При открытии формы добавления /редактирования (в том числе форм смены статуса, смены ответственного и тд), на которой размещен атрибут с признаком "Вычисление значения при редактировании".
При изменении значений атрибутов, от которых зависит значение атрибута с признаком "Вычисление значения при редактировании" (коды атрибутов указаны в коллекции ATTRS_FOR_UPDATE_ON_FORMS). Скрипт выполняется, если поле ввода атрибута с признаком "Вычисление значения при редактировании" выведено на форму.

Скрипт не выполняется на форме выполнения массовых операций, в случае если выбрано более одного объекта.

Если включены параметры оптимизации получения данных, то скрипт выполняется только для видимых на форме атрибутов, см. dbaccess.properties.

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

При первом вычислении скрипт возвращает либо null, либо пустую коллекцию, либо коллекцию атрибутов объекта, от которых зависит вычисление значения скрипта.

При выполнении в интерфейсе оператора скрипт возвращает вычисленное значение атрибута на форме, (значение зависит от типа атрибута).

Переменные и их значения

Глобальные переменные:

user — пользователь, инициализировавший событие. Является объектом класса "Сотрудник" (employee). Если событие инициализировал суперпользователь, то user=null.
ip — ip-адрес рабочего места пользователя user. Если действие выполняется автоматически системой (а не пользователем), то переменная не определяется.
appVersion — версия приложения.
api — используется для обращения к методам api, например api.utils, api.ldap, api.timing, см. Методы API;
modules — используется для обращения к скриптовому модулю и конкретному методу, определенному в нем, с помощью конструкции: modules.{код модуля}.{имя метода}({параметры метода}...), см. Скрипт текста модуля;
logger — используется для отладки скриптов и позволяет вывести в лог на указанный уровень переданную строку, см. Оформление и отладка скриптов.
utils — синоним api.utils.

Переменные контекста:

form — значение атрибута с признаком "Вычисление значения при редактировании", выведенного на форму, в том числе текущее значение данного атрибута (представление объекта на клиенте).

Если атрибут не выведен на форму, то в переменной содержится сохраненное значение атрибута на момент открытия формы.
sourceForm — если скрипт выполняется при открытии формы быстрого добавления и редактирования, то переменная содержит значения полей формы, с которой была открыта текущая форма. В остальных случаях переменная имеет значение null.

Пример использования: sourceForm.title

На форме быстрого добавления предпочтительно использовать прямое сравнение вместо использования sourceForm как условие сравнения (в конструкциях проверки true/false, null/ not null ).

Пример 1. Вместо

return sourceForm ? sourceForm?.printFormRule?.UUID

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

return sourceForm != null ? sourceForm?.printFormRule?.UUID

Пример 2. Вместо

if (sourceForm)

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

if (sourceForm == true)
subject — значения атрибутов текущего объекта, которые были на момент открытия формы, в том числе значение атрибута с признаком "Вычисление значения при редактировании" на момент открытия формы. Переменную можно понимать, как представление объекта, хранящееся в данный момент в базе данных.

Если скрипт используется на форме добавления, то subject = null.

Если скрипт используется на формах смены статуса и смены ответственного, на которую выведен комментарий, то:
- при работе с атрибутами объекта в переменной subject будет содержаться объект, у которого меняем статус или ответственного;
- при работе с атрибутами комментария (в блоке "Комментарий") в переменной subject будет содержаться комментарий, для получения объекта необходимо использовать subject.source.
Если скрипт используется на форме добавления комментария (по кнопке добавления комментария), то subject = null. Обращение к атрибутам комментария в данном случае идет через переменную контекста form. Специально для получения объекта добавлена возможность получить значение параметра source, также через form.
attrCode — код атрибута, для которого вычисляется значение.
cardObject — объект, из карточки которого было инициировано действие.

Переменная не поддерживается в мобильном приложении.

Если действие инициировано НЕ из карточки объекта, то cardObject = null.
origin — тип месторасположения.

Переменная не поддерживается в мобильном приложении.

Возможные значения:
- readForm (форма для чтения) — скрипт вычисляется на карточке объекта, на сложной форме добавления и редактирования связей (расширенная форма редактирования), в списке по ссылке на отдельной странице, в списке на странице результатов поиска, при нажатии на кнопку вызова действий в строке списка;
- addForm — скрипт вычисляется на форме добавления, на быстрой форме добавления;
- editForm — скрипт вычисляется на форме редактирования объекта, на форме редактирования атрибутов, вызванной из контента "Параметры объекта", на форме редактирования в ячейке списка, на форме быстрого редактирования, на форме массового редактирования, на форме смены типа; на форме смены ответственного, на форме смены привязки (переклассификации), на форме работы с массовостью (управление массовостью запроса), на форме смены статуса, на форме перемещения (смены родителя);
- addFormComment/editFormComment — скрипт вычисляется на форме добавления/редактирования комментария;
- addFormFile/editFormFile — скрипт вычисляется на форме добавления/редактирования файла.

Особенности скрипта

Особенности настройки скрипта:

Скрипт может быть задан только для редактируемых атрибутов.
Скрипт не задается для системных атрибутов "Тип объекта", "Контрагент", "Пароль", "Статус", "Соглашение" (agreement), а также для счетчиков времени.
В качестве атрибутов, от которых зависит значение атрибута с признаком "Вычисление значения при редактировании", могут быть указаны любые атрибуты объекта, в том числе вычислимые на форме.

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

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

Особенности выполнения скрипта:

На форме добавления объекта скрипт вычисления значения атрибута при редактировании имеет более высокий приоритет, чем скрипт вычисления значения по умолчанию.
Если на момент сохранения формы поле ввода атрибута с признаком "Вычисление значения при редактировании" на форме не отображается, то значение атрибута остается таким же как было на момент открытия формы.

Особенности скрипта для агрегирующих атрибутов:

Для агрегирующих атрибутов возвращаемое значение может быть задано в следующих форматах:
- отдел;
- команда;
- команда, сотрудник; отдел, сотрудник.
Также значение агрегирующего атрибута можно вернуть в виде subject[%атрибут%] или form[%атрибут%], где %атрибут% — код агрегирующего атрибута. В этом случае система вернет сохраненное значение данного агрегирующего атрибута или его значение на форме соответственно.

Структура скрипта

1. Установка списка кодов вычисляющих атрибутов (обозначены 'attrCode1', 'attrCode2', ...)

def ATTRS_FOR_UPDATE_ON_FORMS = ['attr1', 'attr2', ...]
if (form == null)
{
return ATTRS_FOR_UPDATE_ON_FORMS
}

2. Возврат значения атрибута, устанавливаемого на форме, в зависимости от значений вычисляющих атрибутов на форме, текущего значения атрибута на форме, текущего состояния объекта (зависимость обозначена функцией 'f')

return f(form.attr1, form.attr2, form[attrCode], subject.attr3, ...)

Если есть зависимость атрибута комментария от атрибута объекта, то указывается fqn класса в виде: fqn@attrCode.

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

Скрипт при изменении статуса задачи с "Зарегистрирована" (registered) на "В работе" (inprogress) заполняет поле "Исполнитель" (типа "Агрегирующий атрибут "Сотрудник в рамках отдела") текущим пользователем в рамках его отдела:
Copy
```
if (form == null)
{
return ['state']
}
if ((subject.state == 'registered') && (form.state == 'inprogress'))
{
return [user?.parent, user]
}
else
{
return subject[attrCode]
}
```
Скрипт заполняет описание задачи описанием шаблона (атрибут задачи с кодом "template"), выбранного на форме добавления задачи (код атрибута "Описание" у задачи и шаблона должен быть одинаковым):
Copy
```
if (form == null)
{
return ['template']
}
if ((subject == null) && (form.template != null))
{
return form.template[attrCode]
}
else
{
return form[attrCode]
}
```