Атрибуты

Синтаксис атрибутов

Самый простой способ получить значение атрибута - указать его имя:

name

Примечание

Двоеточие — часть имени и не является спец символом в данном контексте.

Если мы не указываем скаляр, то он по умолчанию принимается равным «?disp». То есть запись выше аналогична следующей:

name?disp

Для значений с типом «Строка (String)» разницы между скалярами «?disp» и «?str» нет т.к. вернется одно и то же значение.

Для обращения к вложенному атрибуту следует разделять имена точкой:

counterparty.fullOrgName?str

Если на каком-то из уровней в атрибуте ожидается список значений, то следует использовать квадратные скобки «[]» после имени атрибута:

counterparty[].fullOrgName?str
manager.subordinates[].userName?str
manager.department.managers[].subordinates[].userName?str

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

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

manager.subordinates[]{userName:"userName?str",firstName:"firstName"}

В результате получим следующую структуру:

[
  {
      "userName": "ivan.ivanov",
      "firstName": "Ivan"
  },
  {
      "userName": "petr.petrov",
      "firstName": "Petr"
  }
]

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

Пост-процессоры описываются после атрибута через символ вертикальной черты «|».

Для процессора «or» есть короткая запись через «!»

documentAmount?num!0

В процессоре «or» можно использовать другие атрибуты:

title?str!name?str
title?str|or("a:name?str")

В данном примере мы получим значение title или значение name, если title равен null или пустой строке.

Примечание

Данный атрибут приведен для примера и для получения «заголовок или имя» лучше использовать скаляр «?disp»

В полной форме нам нужно указать префикс «a:» чтобы обозначить, что нам нужно значение атрибута, а не константа «name?str» Если нам нужно строковое константное значение в короткой форме, то следует взять значение в кавычки:

title?str!"name"

Процессоры можно объединять:

title!name!"n-a"|presuf("prefix-","-suffix")
  1. Взять заголовок;

  2. Если заголовок пустой, то взять имя;

  3. Если имя пустое, то взять константу «n-a»;

  4. Добавить к результату пунктов 1-3 префикс «prefix-»;

  5. Добавить к результату пункта 4 суффикс «-suffix».

Список возможных пост-процессоров

Название

Аргументы

Описание

Пример

presuf

prefix: String
suffix: String
Добавить константу в начало и/или в конец строки. Значение суффикса можно не задавать. Если значение
префикса не нужно, а значение суффикса нужно, то первым аргументом можно передать пустую строку
name|presuf("prefix-","-suffix")
при name = "Имя" → "prefix-Имя-suffix"

or

orValue0: Any
orValue1: Any
orValueN: Any
Вернуть запасное значение, если атрибут равен null или пустой строке. Если аргумент является строкой
и начинается на «a:», то оставшаяся часть атрибута воспринимается как другой атрибут, который
нужно вычислить и вернуть в результате.
Для последовательного выбора запасных значений используйте отдельные процессоры: title!name!"n-a".
В ecos-records 3.60.0-SNAPSHOT при пустом исходном значении вызов одного or с несколькими аргументами
фактически возвращает последний вычисленный аргумент, а не первый непустой.

documentAmount?num|or(0) — если атрибут вернёт null, получим 0

rxg

pattern: String
groupIdx: Int = 1

Применить регулярное выражение ко всей строке и вернуть указанную группу. Если вся строка не соответствует шаблону, вернуть null

"some-text" | rxg("some-(.+)") -> text
"some-text-and-more" | rxg("(some)-(text)-(and)-(more)", 2) -> text

join

delimiter: String = ","

Объединить список значений в строку используя указанный разделитель

hex (3.26.0+)

delimiter: String = ""
Представить base64 строку как HEX строку (список шестнадцатеричных чисел,
где каждый байт представлен двумя символами)

fmt

format: String
locale: String = "en"
timezone: String (необязательный)
Отформатировать число или дату по указанному формату. Шаблон для дат — SimpleDateFormat,
для чисел — DecimalFormat
Без явной timezone используется UTC; если шаблон содержит Z, z или X, используется зона исходной даты
_created|fmt("yyyy__MM__dd")
documentAmount|fmt("00000.00")

cast

type: { "str", "num", "bool" }

Преобразует значение в указанный формат

yaml

Любую структуру приводит к YAML строке

await Records.get('uiserv/form@ECOS_FORM').load('?json|yaml()')

Таблица содержит основные процессоры. В библиотеке также зарегистрированы plus, uppercase и lowercase; список может расширяться реализациями процессоров.

Поисковые запросы

Группировка

В query можно задать атрибуты для группировки через параметр groupBy. Если Records DAO поддерживает группировку (реализует интерфейс RecsGroupQueryDao), то RecordsService ничего не делает с запросом и передает его как есть в DAO. Если же Records DAO не поддерживает группировку, то RecordsService пробует выполнить группировку самостоятельно используя дополнительные запросы. Этот механизм называется «автогруппировка».

Автогруппировка зависит от поддержки преобразования языка запроса. Если язык нельзя преобразовать для обработчика группировки, в сообщения запроса добавляется ошибка.

Работа с MLText полями (3.26.0+)

Если известно. что в каком-то атрибуте лежит строка или MLText структура (объект, где в качестве ключей локаль, а в значении соответствующая строка), то можно применить преобразование «mltext».

Пример:

some.att._as.mltext // получение актуального значения по локали пользователя
some.att._as.mltext.ru // получение значения для конкретной локали
some.att._as.mltext.closest.ru // получение значения для конкретной локали с попыткой вычислить ближайшее не пустое значение
some.att._as.mltext?json // получение значения для всех локалей (если some.att является строкой, то она будет соответствовать локали "en")

Преобразование работает для String, DataValue, MLText, ObjectData, JsonNode (jackson)

Использование динамических атрибутов в предикатах (3.26.0+)

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

Пример запроса с текущим пользователем:

{
    "t": "eq",
    "att": "actor",
    "val": "${$user.userName}"
}

Если ${} один и занимает всю строку, то "${...}" меняется полностью на вычисленное значение. Таким образом результат вычисления шаблона может быть любым JSON типом включая null. Динамические вставки можно использовать на любом уровне вложенности для любых значений в объектах (можно задавать t, att, val).

Список доступных атрибутов можно посмотреть в разделе «Контекстные атрибуты».

Контекстные атрибуты

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

Пример таких атрибутов:

  • Текущий пользователь

  • Текущая дата

Для доступа к таким атрибутам при запросе данных к имени атрибута в начале добавляется знак «$».

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

$user.userName

Если нам нужно получить текущую дату и отформатировать её:

$now|fmt("yyyy")

Список контекстных атрибутов, которые доступны во всех источниках:

Атрибут

Описание

user

Текущий пользователь

now

Текущая дата

auth

Аутентификация текущего пользователя. С помощью этого атрибута можно проверить, является ли пользователь частью группы или глобальной роли:
$auth._has.GROUP_ECOS_ADMINISTRATORS?bool
$auth._has.ROLE_ADMIN?bool

str

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

ref

Атрибут для указания ссылки на другую сущность

appName

Имя текущего приложения

appInstanceId

Идентификатор инстанса текущего приложения

Если в серверном коде нужно расширить доступный список контекстных атрибутов, то работу с RecordsService нужно выполнять следующим образом:

val contextAtts = mutableMapOf<String, Any?>()
contextAtts["customVariable"] = RecordRef.valueOf("emodel/person@someuser")

val result = RequestContext.doWithAtts(contextAtts) {
  recordsService.getAtt("any-record", "\$customVariable?disp").asText()
}

В качестве значений для контекстных атрибутов могут быть EntityRef’ы (для доступа к другим сущностям) или значения любых других типов.