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(obj, attrsCode)

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

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

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

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

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

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

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

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

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

      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, у каждого объекта типа "Файл" своя строчка в таблице базе данных, но ссылаются они на один реальный файл в хранилище или базе данных (в целях экономии ресурсов при хранении документов)

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

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

  • 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)

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

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

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

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

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

    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 — объект, для которого выполняется проверка