api.utils Работа с атрибутами объекта

Для доступа к операциям используется утилитарный метод api.utils или его короткий псевдоним utils.

Получение значения атрибута

  • utils.asString(def subject, def attrCode)

    Получение значения атрибута в виде строки.

  • utils.asText(def subject, def attrCode)

    Получение значения атрибута в виде описания (plain-text).

  • utils.asRTF(def subject, def attrCode)

    Получение значения атрибута в виде RTF-текста (html-text).

    Для преобразования простого текста в html формат используется метод utils.formatToHtml(text).

  • utils.getFromValueMap(attrCode, vmapItem, subject)

    Получение значения атрибута по таблице соответствий.

    Параметры метода:

    • attrCode — код атрибута, значение которого нужно получить. String
    • vmapItem — элемент справочника "Таблицы соответствий" или его uuid. Если null, то возвращается значение атрибута по умолчанию. При этом атрибут, значение которого нужно получить (attrCode), должен быть выбран в качестве определяемого в этой таблице соответствий
    • subject — объект, значение атрибута которого необходимо получить.

    Возвращает значение атрибута объекта, определенное по таблице соответствий, или значение по умолчанию, если значение не удалось определить по таблице соответствий.

  • utils.getIterableElement(iterable, position, defaultValue)

    Получение элемента коллекции.

    Параметры метода:

    • iterable — коллекция элементов
    • position — номер позиции в коллекции
    • defaultValue — значение по умолчанию, для случаев, когда нельзя извлечь значение из коллекции (указан неверный номер позиции или несуществующая коллекция)

Редактирование атрибутов объекта

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

Исключение. Значения некоторых системных нередактируемых атрибутов, например "Дата создания" (creationDate), методами utils.edit изменить невозможно.

  • utils.edit(obj, attrsCode)

    Редактирование атрибутов объекта (метод также можно использовать для добавления комментария к объекту).

    Параметры метода:

    • obj — редактируемый объект
    • attrsCode — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений

    Пример. Изменение названия компании:

    def root = utils.get('root', [:]);
utils.edit(root, ['title' : "Новое название"]);

    Псевдоатрибут @user — пользователь, инициирующий первое действие из цепочки действий.

    Пример цепочки действий: смена статуса → скрипт на вход в статус (редактирует subject через utils.edit) → скрипт проверки условия для счетчика времени (вызвался на редактирование) → действие по событию (событие: изменение объекта).

    @user используется в скриптах при редактировании объектов, в следующий скрипт цепочки действий в качестве user передается пользователь, указанный в @user. Переданный в псевдоатрибуте пользователь не устанавливается как автор события в системе, в истории изменения объекта автором изменения по прежнему будет система.

    Пример передачи в @user глобальной переменной user.

    def serviceCall = utils.get('serviceCall$3801');
utils.edit(serviceCall, ['title' : 'qwerty', '@user' : user]);

    Пример передачи в @user обычного объекта (определенного пользователя).

    def serviceCall = utils.get('serviceCall$3801');
def client = utils.get('employee$80113');
utils.edit(serviceCall, ['title' : 'qwerty', '@user' : client]);

    Особенности редактирования атрибута:

    • "Набор ссылок на БО"

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

      utils.edit('employeeUUID', ['teams' : []]);

      Вариант utils.edit('employeeUUID', ['teams' : null]) может привести к ошибкам при работе с объектом

    • "Файл"

      При выполнении скрипта: 

      def ou1 = utils.get('uuid_ou1')
def ou2 = utils.get('uuid_ou2')
def file = ou1.fileAttribute
utils.edit(ou2, ['fileAttribute' : file]);

      В объекте ou2 будут лежать копии файлов из ou1. У оригинала и копии разные UUID, у каждого объекта типа "Файл" своя строчка в таблице базе данных, но ссылаются они на один реальный файл в хранилище или базе данных (в целях экономии ресурсов при хранении документов)

  • utils.edit (obj, attrsCode, newTransaction)

    Редактирование атрибутов объекта в отдельной транзакции аналогично оборачиванию метода edit без параметра в отдельную транзакцию с использованием api.tx.call, см. api.tx Работа с транзакциями.

    Параметры метода:

    • obj — редактируемый объект
    • attrsCode — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений
    • newTransaction — указывает, следует ли запускать редактирование объекта в отдельной транзакции. Boolean

    Пример. Изменение названия компании в новой транзакции:

    def root = utils.get('root', [:])
utils.edit(root, ['title' : "Новое название компании"], true)

Удаление значения атрибута

  • utils.clearAttribute(obj, attrCode)

    Удаление значения атрибута.

    Параметры метода:

    • obj — редактируемый объект
    • attrCode — код атрибута, у которого удаляется значение

Работа с агрегирующими атрибутами

Получение значения агрегирующего атрибута

  • utils.getAggrValueMap(obj, attrCode)

    Получение значения агрегирующего атрибута.

    Параметры метода:

    • obj — объект (IUUIDIdentifiable).
    • attrCode — код атрибута, значение которого нужно получить. String

    Возвращает значения агрегирующего атрибута в виде Map<String, Object>. Постфикс части агрегирующего атрибута, значение соответствующей части агрегирующего атрибута: _em, _ou, _te.

  • object['aggregateAttrCode']

    Получение значения агрегирующего атрибута (при обращении к полю объекта).

    Возвращаемое значение: При обращении к полю получаем UUID сотрудника. Если UUID сотрудника не указан, то UUID отдела. Если UUID отдела не указан, то UUID команды.

Редактирование значения агрегирующего атрибута

  • utils.edit(obj, attrsCode)

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

    Указанные правила работы с агрегирующим атрибутом распространяются и на создание объекта методом utils.create, и на работу аналогичных методов REST API.

    Пример 1. Редактирование значения агрегирующего атрибута:

    Значением агрегирующего атрибута является значение агрегируемого атрибута класса "Отдел" (ou) или "Команда" (team) или набор значений атрибутов "Сотрудник" (employee) и "Отдел" (ou) / "Сотрудник" (employee) и "Команда" (team).

    utils.edit(subject, ['aggrAttr' : ['ou$123', 'employee$123']]); // ответственным устанавливается сотрудник в рамках отдела с использованием уникальных идентификаторов объектов

    utils.edit(subject, ['aggrAttr' : [ou, employee]]); // ответственным устанавливается сотрудник в рамках отдела с использованием объектов

    utils.edit(subject, ['aggrAttr' : ['team$123', 'employee$123']]); // ответственным устанавливается сотрудник в рамках команды

    utils.edit(subject, ['aggrAttr' : ['ou$123']]) // ответственным устанавливается отдел

    utils.edit(subject, ['aggrAttr' : ['team$123']]) // ответственным устанавливается команда

    Пример 2 . Редактирование значения атрибута "Ответственный" (responsible):

    utils.edit(subject, ['responsible' : ['team$123']]); // ответственным устанавливается команда

    utils.edit(subject, ['responsible' : ['team$123', 'employee$123']]); // ответственным устанавливается сотрудник в рамках команды

    utils.edit(subject, ['responsible' : ['team$123', subject.responsibleEmployee]]); // ответственным устанавливается тот же сотрудник, но в рамках другой команды

    Ограничения:
    - Атрибут "Контрагент" (client) запроса нельзя заполнить набором значений атрибутов класса "Сотрудник" (employee) и "Команда" (team). Допустимы значения агрегируемого атрибута "Отдел" (ou) или "Команда" (team) или набор значений атрибутов "Сотрудник" (employee) и "Отдел" (ou).
    - Не рекомендуется использовать редактирование агрегирующих атрибутов, включая атрибут "Ответственный" (responsible), через изменение их составных частей.

Фильтрация атрибутов

  • utils.filterUUIDs(uuids, attrsCode)

    Фильтрация уникальных идентификаторов по значениям атрибутов.

    Параметры метода:

    • uuids — список проверяемых uuid
    • attrsCode — ассоциативный список кодов атрибутов и их значений.

    Возвращает uuid'ы с учетом указанных ограничений по атрибутам.

Копирование атрибутов

  • utils.copyFromRelated(subject, subjectAttr, relationAttr, attrOfRelatedObject)

    Копирование значения атрибута связанного объекта в атрибут текущего объекта.

    Параметры метода:

    • subject — объект, над которым производится действие
    • subjectAttr — код атрибута текущего объекта, куда будет помещено значение
    • relationAttr — код атрибута связи типа "Ссылка на бизнес-объект"
    • attrOfRelatedObject — код копируемого атрибута связанного объекта

  • utils.copyManyLinks(subject, subjectAttr, relationAttr, attrsOfRelatedObject)

    Копирование значения нескольких ссылочных атрибутов связанного объекта в атрибут типа "Набор ссылок на бизнес-объект" текущего объекта.

    Параметры метода:

    • subject — объект, над которым производится действие
    • subjectAttr — код атрибута текущего объекта, куда будет помещено значение
    • relationAttr — код атрибута связи типа "Ссылка на бизнес-объект"
    • attrsOfRelatedObject — коды копируемых атрибутов связанного объекта

  • utils.copyToRelated(subject, subjectAttr, relationAttr, attrOfRelatedObject)

    Копирование значения ссылочного атрибута связанного объекта в атрибут типа "Набор ссылок на бизнес-объект" текущего объекта.

    Параметры метода:

    • subject — объект, над которым производится действие
    • subjectAttr — код атрибута текущего объекта
    • relationAttr — код атрибута связи типа "Ссылка на бизнес-объект", куда будет помещено значение
    • attrOfRelatedObject — код копируемого атрибута

  • utils.copyToNested(subject, attr)

    Копирование значения атрибута объекта в атрибут вложенных объектов. Конструкция работает по всем уровням вложенности для классов, вложенных в самих себя ("Отдел" (ou) или "База знаний").

    Параметры метода:

    • subject — объект, у которого копируется значение атрибута
    • attr — код копируемого атрибута

  • utils.copyToChilds(subject, subjectAttr, childAttr, classOfChild, types)

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

    Параметры метода:

    • subject — объект, у которого копируется значение атрибута (атрибутов)
    • subjectAttr — код атрибута, значения которого требуется скопировать
    • childAttr — атрибут вложенных объектов
    • classOfChild — класс вложенных объектов
    • types — типы вложенных объектов. Все типы — пустые скобки []

Сравнения и проверки атрибутов

  • utils.containsAttribute(obj, attrCode)

    Проверка наличия атрибута у объекта.

    Параметры метода:

    • obj — объект, для которого проверяется наличие атрибута
    • attrCode — код проверяемого атрибута

    Возвращаемое значение:

    • true — при наличии атрибута
    • false — при отсутствии атрибута

  • utils.isFilled(obj, attrCode)

    Проверка заполнения атрибута объекта, при условии отличия его значения от значения по умолчанию.

    Параметры метода:

    • obj — объект, для которого выполняется проверка
    • attrCode — код проверяемого атрибута

  • utils.equalsDefaultValue(obj, attrCode)

    Проверка равенства значения атрибута значению по умолчанию.

    Параметры метода:

    • obj — объект, для которого выполняется проверка
    • attrCode — код проверяемого атрибута

  • api.utils.checkRestrictions(obj, skipRequired, skipUnique)

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

    Параметры метода:

    • obj — объект, для которого проверяется соответствие параметров атрибута
    • skipRequired — проверка обязательности: true (пропустить), false (не пропускать)
    • skipUnique — проверка уникальности: true (пропустить), false (не пропускать)

  • utils.isFolder(obj)

    Проверка, является ли элемент справочника папкой (каталогом).

    Параметр метода:

    • obj — объект, для которого выполняется проверка