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

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

Подсчет количества объектов

  • utils.count(fqn, attributes)

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

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

    • fqn — класс/тип объекта. Параметр может быть задан в виде строки, содержащей fqn типа/класса, или в виде объекта ClassFqn, или в виде бизнес-объекта;
    • attributes — ассоциативный список значений атрибута <Код атрибута : Значение атрибута>. Могут использоваться Условные операции

    Возвращает количество объектов указанного класса/типа.

    Пример 1. Количество объектов с метаклассом, совпадающим с метаклассом subject и с указанным названием:

    utils.count(subject.getMetainfo(), ['title':'some title'])

    или

    utils.count(subject, ['title':'some title'])

    Пример 2. Количество сотрудников с фамилией "Петров":

    utils.count('employee', ['lastName':'Петров'])

    С помощью метода utils.count невозможно выполнить подсчет количества объектов для следующих атрибутов:
    - вычислимые атрибуты, т.к. их значения не хранятся в базе данных и при вызове метода возникает ошибка;
    - атрибуты типа "Атрибут связанного объекта", т.к. метод не вернет никакого значения, потому что в отличие от других атрибутов нужно сначала обратиться к тем объектам, с которыми связан первичный объект, а затем искать объект, на которые ссылается связанный объект.

Получение коллекции объектов

  • utils.getObjects(uuids)

    Получение коллекции объектов по коллекции uuid.

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

    • uuids — коллекция строк — уникальных идентификаторов (UUID) объектов, которые необходимо получить.

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

    Пример:

    def objs = utils.getObjects(['serviceCall$123', 'serviceCall$321']);

Добавление объекта

  • utils.create(fqn, attributes)

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

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

    • fqn — тип создаваемого объекта для основных классов или класс создаваемого объекта для служебных классов;
    • attributes — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений. Если в списке изменяемых атрибутов отсутствует атрибут создаваемого объекта, то для него используется значение по умолчанию, если оно настроено.

    Пример 1. Создание объекта основного класса (не служебного):

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

    utils.create('userClass$userCase', ['attribute' : 'value'])

    или

    utils.create('userClass', ['attribute' : 'value', 'metaClass': 'userClass$userCase'])

    Пример 2. Создание отдела в компании:

    def root = utils.get('root', [:]);
def ou = utils.create('ou$simple', ["title" : "Название создаваемого отдела", "parent" : root]);

    или

    def attrs = [:]
attrs.title = "Название создаваемого отдела"
attrs.parent = root
def ou = utils.create('ou$simple', attrs);

Удаление объекта

  • utils.delete(obj)

    Удаление объекта.

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

    • obj — удаляемый объект.

    Особенности:

    • При использовании метода в скрипте пользовательского действии по событию с карточки объекта, необходимо отменить обновление страницы после выполнения действия, иначе произойдет ошибка и действие будет отменено.
    • Удаление объекта служебного класса "Событие" данным методом невозможно.
    • Удаление объекта служебного класса "Письмо" данным методом возможно только при нахождении письма в статусе "Обработано"

    Пример: скрипт для удаления объекта с карточки объекта и последующего перехода на карточку предыдущего объекта.

    utils.delete(subject.UUID)

    result.reload(false)

    result.executeJavaScript('window.history.back()')

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

Создание записи в истории событий объекта

  • utils.event(subject, message)

    Создание пользовательской записи в истории событий указанного объекта.

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

    • subject — объект, в историю которого добавляется запись.
    • message — сообщение в историю.

    Пример: добавление записи "Скрипт: Naumen" в историю событий объекта subject:

    def message = 'Naumen';
utils.event(subject, message);

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

  • utils.equal(obj1, obj2)

    Проверка двух объектов на равенство. Объекты сравниваются по уникальным идентификаторам.

  • utils.equal(objs1, objs2)

    Проверка двух коллекций на равенство. Коллекции сравниваются поэлементно.

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

  • utils.editWithoutEventActions(obj, attributes)

    utils.editWithoutEventActions(obj, attributes, newTransaction)

    Редактирование объекта без выполнения действий по событию.

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

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

    • newTransaction — признак, определяющий следует ли запускать редактирование объекта в отдельной транзакции. Boolean

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

    При использовании методов editWithoutEventActions, контекстная переменная changedAttributes равна пустому списку ([]).

Экспорт объектов в электронные таблицы формата .xlsx

  • utils.exportObjectsToXls(fqn, attributes)

    Экспорт объектов в электронные таблицы формата .xlsx, с фильтрацией по значению атрибутов. Метод экспортирует атрибуты, определенные в классе/типе, который указан в параметрах метода

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

    • fqn — класс/тип экспортируемых объектов
    • attributes — ассоциативный массив для фильтрации объектов экспорта: ключ — код атрибута; значение — значение атрибута

    Результат выполнения: Ссылка на скачивание xlsx файла. Файл доступен для всех пользователей после авторизации в приложении.

    Внутри файла колонки с атрибутами сортируются в следующей последовательности:

    • Системные атрибуты указанного класса/типа
    • Пользовательские атрибуты указанного класса/типа

    Пример 1. Выгрузка всех запросов:

    utils.exportObjectsToXls('serviceCall', [:])

    Пример 2. Выгрузка запросов, решенных сотрудником employee$2345:

    utils.exportObjectsToXls('serviceCall', [ state : 'resolved', solvedBy : 'employee$2345' ])

  • utils.exportObjectsToXlsWithAllAttrs(fqn, attributes)

    Экспорт объектов в электронные таблицы формата .xlsx, с фильтрацией по значению атрибутов.

    Метод экспортирует:

    • атрибуты, определенные в классе/типе, который указан в параметрах метода;
    • атрибуты, определенные во вложенных типах, указанного класса/типа.

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

    • fqn — класс/тип экспортируемых объектов
    • attributes — ассоциативный массив для фильтрации объектов экспорта: ключ — код атрибута; значение — значение атрибута.

    Результат выполнения: Ссылка на скачивание xlsx файла. Файл доступен для всех пользователей после авторизации в приложении.

    Внутри файла колонки с атрибутами сортируются в следующей последовательности:

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

Вложенные объекты

  • utils.getNested(obj)

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

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

    • obj — объект

    Возвращает коллекцию вложенных объектов

  • utils.getNested(obj, parentAttrCode)

    Получение вложенных объектов, если код атрибута-ссылки на родителя отличается от 'parent'.

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

    • obj — объект;
    • parentAttrCode — код атрибута-ссылки на родителя

    Возвращает коллекцию вложенных объектов.

  • utils.isUpper(upper, obj)

    Сравнение объектов в одной родительской ветке. Метод определяет, находится ли 'upper' выше по иерархии, чем 'obj'. Сравниваются объекты одного класса.

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

    • upper — объект
    • obj — объект;

    Возвращает true, если объект upper находится выше по иерархии чем obj, false в остальных случаях.

Получение истории смены статуса

В системе хранится история смены статусов и ответственных для объектов классов с настройкой жизненного цикла и/или ответственности. История характеризуется набором атрибутов служебного класса "История изменения ответственного и статуса", набор атрибутов одинаков для всех классов и расположен в карточках дочерних классов класса "История изменения ответственного и статуса".

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

  • utils.stateHistory(obj)

    Получение истории смены статуса.

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

    • obj — объект, для которого формируется история событий.

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

  • utils.lastState(obj)

    Получение события истории последней смены статуса.

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

    • obj — объект, для которого формируется история событий

    Пример:

    def stateEvt = utils.lastState(obj);
def lastStateCode = stateEvt.stateCode;//код предыдущего состояния
def currentStateCode = stateEvt.newStateCode;//код текущего состояния

Назначение ответственного

  • utils.setResponsible(subject, team, employee)

    Назначение ответственного.

    Пример:

    errors = utils.setResponsible(subject, team, employee);
if (!errors.isEmpty())
{
logger.error("Ошибка при назначении ответственного: " + errors);
}

Получение истории смены ответственного

В системе хранится история смены статусов и ответственных для объектов классов с настройкой жизненного цикла и/или ответственности. История характеризуется набором атрибутов служебного класса "История изменения ответственного и статуса", набор атрибутов одинаков для всех классов и расположен в карточках дочерних классов класса "История изменения ответственного и статуса".

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

  • utils.responsibleHistory(obj)

    Получение истории смены ответственного.

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

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

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

  • utils.lastResponsible(obj)

    Получение события истории последней смены ответственного.

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

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

Преобразование объекта в JSON строку

  • utils.asJson(object, attrs)

    utils.asJson(object)

    Преобразование любого объекта в JSON строку.

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

    • object — сериализуемый объект или список объектов (ScriptDtOCollection — результат api.db.query(...))

      object должен быть наследником IUUIdentifiable или ScriptObjectBase, т.е. данный объект был получен с помощью выполнения какого-либо api метода, например, utils.{get, find, findFirst, create, edit, editWithoutAction} или с помощью api.db.query(...).list()

    • attrs — коллекция кодов атрибутов, которые необходимо вернуть (если пусто или не указано, то весь сериализованный объект).

    Возвращает JSON строку.