api.utils Поиск объектов

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

  • utils.get (fqn, attributes)

    Поиск одного объекта по коду класса/типа объектов и его атрибутам.

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

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

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

    • конкретный объект;
    • "null", если объект не найден;
    • исключение, если найдено более одного объекта (обработка исключений в данном документе не рассматривается, обратитесь к документации Groovy).

    Пример 1. Поиск компании:

    def root = utils.get('root', [:])

    Пример 2. Поиск элемента справочника "Уровни срочности" с кодом low:

    def urg = utils.get('urgency', ["code": "low"])

  • utils.get(uuid)

    Поиск одного объекта по его уникальному идентификатору (1).

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

    • конкретный объект;
    • исключение, если объект не найден (обработка исключений в данном документе не рассматривается, обратитесь к документации Groovy).
  • utils.load(uuid)

    Поиск одного объекта по его уникальному идентификатору (2):

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

    • конкретный объект;
    • null, если объект не найден.
  • utils.find (fqn, attributes)

    Поиск нескольких объектов по коду класса/типа объектов и его атрибутам. Могут использоваться Условные операции

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

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

    Возвращает коллекцию объектов (может быть пустой, но не "null").

    Возвращается не сам объект, а только его идентификатор (UUID). При обращении к атрибутам найденного объекта, через его идентификатор производится поиск самого объекта, который берется из текущей сессии. Если в сессии его нет, то объект берется из базы данных.

    Примечания:

    • Если скрипт фильтрации может вернуть все объекты (более 500), то вместо конструкции типа:

      Использование utils.find в скрипте фильтрации значений атрибута при редактировании.

      return utils.find('class$type',[:])

      рекомендуется использовать конструкцию, которая значительно сократит время формирования списка объектов:

      return api.filtration.disableFiltration()

    • Для поиска элементов коллекции с помощью метода utils.find (найти совпадение хотя бы с одним из элементов) необходимо использовать Условные операции

      Пример: получение списка сотрудников с фамилиями Иванов и Петров.

      utils.find('employee', ['lastName' : op.in('Иванов', 'Петров')])

    • При проведении поиска по UUID, игнорируется все значение до $

      utils.find('serviceCall', ['UUID': 'location$81101'])

      Если "location$81101" изменить на "redSocks$81101", то возвращаемый результат не изменится.

    • Работа с логическими атрибутами:

      • В системе логические атрибуты представлены как объекты java, поэтому для всех логических атрибутов значение по умолчанию = null (если не указано "Значение по умолчанию Да = вкл).
      • В базе данных хранится значение атрибута null до момента явного сохранения значения атрибута на форме редактирования в интерфейсе оператора.
      • При получении значений для системных логических атрибутов, вернется:

        • false — если в базе данных значение атрибута установлено false или null;
        • true — если в базе данных значение атрибута установлено true.
      • В случае поиска объектов, у которых логический атрибут должен иметь значение false, необходимо учитывать кейс, что в базе данных валидными вариантами являются записи, которые хранят значения false и null для этого атрибута, например, utils.find('employee',['employeeForIntegration': false, 'employeeForIntegration': null])

    Пример 1. Поиск отдела по названию:

    utils.find('ou', ["title" : "Название отдела"])

    Пример 2. Поиск объекта по атрибуту типа "Ссылка на бизнес-объект":

    def author = utils.get('employee$12345');
    objs = utils.find('serviceCall', ["author" : author])

    Пример 3. Поиск объектов по атрибуту типа "Ссылка на бизнес-объект" по UUID объекта:

    utils.find('serviceCall', ["author" : 'employee$12345'])

    Пример 4. Поиск объектов по атрибуту типа "Ссылка на бизнес-объект" по набору объектов /UUID (качестве коллекции можно использовать null):

    def empls = ['employee$7035', 'employee$7007']
    utils.find('serviceCall', ["clientEmployee" : empls])

    Пример 5. Поиск объектов по атрибуту типа "Элемент справочника" по коду элемента справочника:

    utils.find('serviceCall', ["urgency" : "low"])

    Пример 6. Поиск всех элементов справочника "Уровни срочности":

    utils.find('urgency', [:])

    Пример 7. Поиск объектов по нескольким атрибутам (поиск запроса по автору и услуге):

    def author = subject.author
    def service = subject.service
    objs = utils.find('serviceCall', ["author" : author, "service" : service])
  • utils.findFirst (fqn, attributes)

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

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

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

    Возвращает первый объект из нескольких найденных объектов.

    Пример. Первый найденный элемент справочника "Уровни срочности":

    obj = utils.findFirst('urgency', [:])

  • utils.findUnique(attributes)

    utils.findUnique(attributes, defaultObject)

    utils.findUnique(attributes, defaultObject, ignoreCase)

    Поиск уникального объекта по карте атрибутов. Могут использоваться Условные операции

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

    • attributes — ассоциативный список значений атрибута <Код атрибута : Значение атрибута>. Наличие значения с ключом 'metaClass' обязательно в карте атрибутов, иначе FxException.
    • defaultObject — объект, возвращаемый по умолчанию, если поиск завершился неуспешно
    • ignoreCase — признак, определяющий будет ли учитываться регистр у строковых значений. Boolean.

    Возвращает:

    • Найденный объект, если он является единственным с таким набором атрибутов.
    • null, если объект не найден или найдено несколько объектов (если не указан defaultObject).
    • defaultObject, если объект не найден или найдено несколько объектов.

    Пример 1. Поиск отдела по названию:

    utils.findUnique(['title' : 'sampleTitle', 'metaClass' : 'sampleClass'])

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

    def defaultValue = "sample";
    def obj = utils.findUnique(['title' : 'sampleTitle', 'metaClass' : 'sampleClass'], defaultValue);

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

    def defaultValue = "sample";
    def obj = utils.findUnique(['title' : 'sampleTitle', 'metaClass' : 'sampleClass'], defaultValue, false);
  • utils.find(metaClass, sp.ignoreCase().limit(100).offset(100))

    utils.find(metaClass, attrCode : 'value', sp.ignoreCase().limit(100).offset(100))

    где sp (SearchParams) — параметры поиска.

    Параметры поиска можно задавать в любом порядке: sp.limit(5).offset(1) = sp.offset(1).limit(5).

    Отсчет элементов начинается с 0.

    Внимание! нельзя использовать параметр offset() без установки параметра limit()

    Пример 1. Поиск возвращает отделы с 0 по 9:

    utils.find('ou', [ : ], sp.limit(10));

    Пример 2. Поиск возвращает отделы с 10 по 99:

    utils.find('ou', [ : ], sp.limit(100).offset(10));

    Пример 3. Поиск возвращает все отделы, название которых "Отдел", независимо от регистра (ОТДЕЛ, отдел):

    utils.find('ou', ['title' : 'Отдел'], sp.ignoreCase());

    Пример 4. Поиск возвращает отделы с 5 по 9, название которых "Отдел", независимо от регистра (ОТДЕЛ, отдел):

    utils.find('ou', ['title' : 'Отдел'], sp.limit(10).offset(5).ignoreCase());

  • utils.find('employee', ['employeeSecGroups' : 'код группы'])

    utils.find('ou', ['ouSecGroups' : 'код группы'])

    utils.find('team', ['teamSecGroups' : 'код группы'])

    utils.find('employee', ['all_Group' : 'код группы'])

    Получение сотрудников (отделов, команд и сотрудников) по коду группы пользователей.

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

    • teamUserGroups — группы пользователей команды
    • ouSecGroups — группы пользователей отдела
    • employeeSecGroups — группы пользователей сотрудника
    • all_Group — группы пользователей сотрудника, отдела, команд. Возвращает всех сотрудников, сотрудников отделов и команд

Регистрозависимость поиска (метод поиска utils.find) зависит от типа используемой СУБД: PostgresSQL и Oracle поиск регистрозависим, MS SQL поиск регистроНЕзависим.

Условные операции

Условные операции могут использоваться при выполнении методов: utils.find(), utils.findFirst(), utils.get(), utils.count(), utils.findUnique().

  • op.like(value)

    Поиск по вхождению в строке (тексте) значения атрибута, который соответствует поисковому шаблону. Для формирования поискового шаблона допустимо использование спецсимвола '%'.

    Ограничение: используется для атрибутов типа "Строка", "Текст", "Текст в формате RTF". Иначе генерируется исключение.

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

    utils.find('employee', ['lastName' : op.like('Иванов')])

    Пример 2. Получение списка сотрудников, фамилия которых начинается на "Иванов":

    utils.find('employee', ['lastName' : op.like('Иванов%')])

  • op.orEq(value1, value2, value3, ...)

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

    Ограничение: минимальное количество параметров: 2, иначе генерируется исключение.

    Пример 1.

    utils.find('employee', ['parent' : op.orEq('ou$123321', 'ou$123322', 'ou$123323')])

    Пример 2. При поиске элементов справочника по условию, в качестве набора значений атрибута parent (типа "Ссылка на бизнес-объект"), передаются UUID родительских элементов справочника или папок:

    utils.find('cOCSclassific', ['parent' : op.orEq('cOCSclassific$2395602', 'cOCSclassific$2395603')])

  • op.not(value1, value2, value3, ...)

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

    Примеры:

    utils.find('employee', ['parent' : op.not('ou$123321')])

    utils.find('employee', ['parent' : op.not('ou$123321', 'ou$123322', 'ou$123323')])

  • op.gt(value)

    Поиск объектов, значение целевого атрибута которых больше значения указанного параметра:

    Ограничение: используется для атрибутов типа "Дата", "Дата/время" и числовых атрибутов, иначе генерируется исключение.

    Примеры:

    utils.find('employee', ['number' : op.gt(50)])

    utils.find('employee', ['date1' : op.gt(new Date().parse('yyyy-MM-dd', '2017-04-07'))])

  • op.lt(value)

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

    Ограничение: используется для атрибутов типа "Дата", "Дата/время" и числовых атрибутов, иначе генерируется исключение.

    Примеры:

    utils.find('employee', ['number' : op.lt(50)])

    utils.find('employee', ['date1' : op.lt(new Date().parse('yyyy-MM-dd', '2017-04-07'))])

  • op.between(value1, value2)

    Поиск объектов, значение целевого атрибута которых находится в рамках между value1 и value2, включая граничные значения (value1 <= value <= value2).

    Ограничение: используется для атрибутов типа "Дата", "Дата/время" и числовых атрибутов, иначе генерируется исключение.

    Примеры:

    utils.find('employee', ['number1' : op.between(50,60)]);

    utils.find('employee',['date1' : op.between(new Date().parse('yyyy-MM-dd', '2017-04-06'), new Date().parse('yyyy-MM-dd', '2017-04-10'))])

  • op.eq(value)

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

    Пример.

    utils.find('employee', ['parent' : op.eq('ou$123321')])

  • op.isNull()

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

    Пример:

    utils.find('employee', ['boLink' : op.isNull()])

  • op.isNotNull()

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

    Пример:

    utils.find('employee', ['boLink' : op.isNotNull()])

  • op.in(value1, value2, value3, ...)

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

    Допустимо использование коллекции объектов в качестве единственного параметра метода: op.in(value1, value2, value3) эквивалентно op.in([value1, value2, value3]).

    Примеры:

    utils.find('employee', ['boLink' : op.in('employee$5211', 'employee$5208')]);

    utils.find('employee', ['boLink' : op.in(['employee$5211','employee$5208'])]);

    utils.find('employee', ['dateTime' : op.in(new Date(1492319201000), new Date(1492319201050))])

    utils.find('employee', ['timer' : op.in('a', 'e')])