Аспекты
Аспект — механизм расширения функционала типа данных. Он позволяет переиспользовать определения атрибутов, форму конфигурации и связанное поведение, не копируя их в каждый тип. При подключении аспекта его атрибуты включаются в итоговую модель типа.
Один и тот же аспект можно подключить к нескольким типам данных, что позволяет переиспользовать логику без дублирования. Аспект может быть добавлен к типу явно — через вкладку Аспекты в настройках типа, или автоматически — в зависимости от конфигурации.
Атрибуты аспекта доступны через префикс в формате {prefix}:{attribute.id}, что позволяет однозначно идентифицировать их в формах, журналах, конфигурациях действий и мутациях записей.
Дочерние типы наследуют аспекты родительского типа. При повторном подключении того же аспекта настройка inheritConfig определяет основу конфигурации: при включённом наследовании используется конфигурация родительского объявления, иначе — конфигурация по умолчанию аспекта. Собственные значения переопределяют ключи основы по верхнему уровню; вложенные объекты заменяются целиком.
В Citeck представлены системные аспекты для типовых задач:
учёт времени;
управление связями между документами;
генерация штрихкода;
конфигурация истории событий;
импорт данных;
обработка активностей.
Для просмотра существующих аспектов и их редактирования создан журнал «Аспекты» (Рабочее пространство «Раздел администратора» - Модель):
В журнале администратору с каждой записью доступен стандартный набор действий:
редактировать json-файл;
редактировать свойства;
скачать определение в формате YAML;
удалить.
См. больше информации о разработке
Для изменения определений аспектов нужны права администратора. Через API изменение также доступно под SYSTEM. Это отдельные права, не определяющие доступ к значениям атрибутов конкретных записей.
Создание нового аспекта
Форма создания нового аспекта состоит из 2 вкладок.
Вкладка «Основные»:
п/п |
Наименование |
Описание |
|---|---|---|
1 |
Идентификатор |
уникальный идентификатор аспекта; допускаются латинские буквы, цифры, подчёркивание и дефис |
2 |
Префикс |
Предназначен, чтобы различать атрибуты из разных аспектов.
Префикс добавляется ко всем атрибутам аспекта по шаблону
{prefix}:{attribute.id}.Таким образом атрибуты могут быть доступны в формах, конфигах действий, мутации записей.
Если префикс отдельно не задан, то по умолчанию равен идентификатору.
Эффективный префикс должен быть уникален среди аспектов.
|
3 |
Название |
локализованное наименование |
4 |
Форма конфигурации |
Функционал позволяет расширять конфигурацию типа, не меняя форму типа.
Форма может быть выбрана из ранее созданных или создана.
|
Идентификатор и префикс задаются при создании; при редактировании в штатной форме эти поля заблокированы.
Вкладка «Атрибуты»:
Атрибуты аспекта и системные атрибуты аспекта, которые будут добавлены к сущностям с данным аспектом.
п/п |
Наименование |
Описание |
Пример заполнения |
|---|---|---|---|
1 |
Id |
идентификатор поля, по которому оно будет доступно на форме, в журнале. |
testAttribute (camelCase) |
2 |
Имя |
имя поля для отображения пользователю. |
Тестовый атрибут |
3 |
Тип |
тип поля. Поддерживаемые типы данных |
выбирается из списка предлагаемых. По умолчанию выставляется text. |
4 |
Множественный |
множественный ввод разрешен |
флаг |
5 |
Обязательный |
поле обязательно к заполнению |
флаг |
6 |
Вычисляемые атрибуты |
функционал, позволяющий создавать производные атрибуты с помощью выражений и скриптов. См. подробно |
настройка конфигурации в зависимости от типа и сложности вычисления атрибута |
Полное имя атрибута prefix:attributeId может содержать латинские буквы, цифры, подчёркивание, дефис и двоеточие. Для атрибутов, сохраняемых как столбцы, длина полного имени ограничена 63 байтами UTF-8, включая префикс и двоеточие. Для атрибутов, не сохраняемых как столбцы, ограничение длины не применяется, но требования к символам сохраняются.
В поле _aspects как и при добавлении любого другого аспекта вносится информация об аспекте.
Примечание
Аспект можно подключить явно во вкладке Аспекты типа данных. Автоматическое добавление зависит от реализации конкретного аспекта и конфигурации платформы.
Примеры
Связан с другим документом
Аспект «Связан с другим документом» создан для работы виджета «Связи документа» (добавление и отображение связей с сущностью ):
В поле assoc:associatedWith вносится информация о связанных сущностях.
Имеет штрихкод
Аспект «Имеет штрихкод» создан для формирования штрихкода к документу:
В аспекте нет атрибутов, но есть форма настройки:
При выборе аспекта в типе данных можно настроить формат штрих-кода и атрибут, из которого брать данные для формирования штрих-кода (по умолчанию номер документа _docNum).
Для реализации сложной логики - необходимо создать вычисляемый атрибут, и на основе него добавить аспект и далее брать настройку штрих-кода из атрибута.
Учет времени
Аспект «Учет времени» создает записи о потраченном времени по задаче:
В аспекте есть атрибут timeTracking - запись о потраченном времени:
Отражается в виде дочерней ассоциации: time-trackable:timeTracking:
При таком выборе атрибут аспекта является дочерней ассоциацией.
Следовательно, по сущности timeTracking можно перейти к родителю. В атрибуте timeTracking, соответственно, содержатся ссылки на все дочерние сущности.
Таким образом образуется двухсторонняя связь:
от дочернего к родителю по системному атрибуту
_parent,от родителя к дочернему по настроенному атрибуту.
По умолчанию при удалении родителя удаляются записи по дочерним ассоциациям. Если для дочерней ассоциации включена настройка сохранения дочерних записей (allowChildDetach), они сохраняются при удалении связи или родителя.
Доступ к записям timeTracking зависит от настроек прав дочернего типа и наследования прав от родителя. При настройке учёта времени проверьте доступ к дочерним записям для нужных пользователей.
При создании timeTracking- сущности доступны 2 атрибута, которые позволяют сделать связь с родителем:
_parent?str: "emodel/<source-id>@<record-id>" // Идентификатор родительской заявки.
_parentAtt?str: "time-trackable:timeTracking" // Атрибут родителя, содержащий дочерние записи.
Вместо emodel/<source-id>@<record-id> подставьте фактический RecordRef заявки. Ссылка вида emodel/type@document указывает на определение типа, а не на экземпляр документа.
Конфигурация истории
Аспект «Конфигурация истории» создан для возможности конфигурации записи свойств в историю.
Для настройки необходимо добавить этот аспект в тип данных на вкладке Аспекты:
Аспект добавляет 3 настройки, которые можно задать как в форме, так и напрямую в json:
Настройка |
Описание |
|---|---|
Исключенные атрибуты ( |
атрибуты, изменение которых не записывается в историю |
Атрибуты для записи истории при создании ( |
атрибуты, создание которых записывается в историю |
Отключить историю |
полностью отключает запись изменений в историю |
Исключенные атрибуты
По кнопке Настроить в строке Исключенные атрибуты доступен выбор атрибутов типа данных, информация об изменении которых не будет записываться в историю, и отражаться в виджете «История событий», соответственно.
Например, если в карточке изменить информацию о наименовании, категории и стоимости, то в виджете «История событий» отразится информация только об измененной стоимости:
Если в типе данных настроены аспекты (например, Версионные данные, Имеет документы), то атрибуты из них так же можно выбрать:
Атрибуты для записи истории при создании
По кнопке Настроить в строке Атрибуты для записи истории при создании доступен выбор атрибутов типа данных, информация о создании которых будет записываться в историю, и отражаться в виджете «История событий», соответственно.
Например:
Также можно вносить атрибуты непосредственно в json:
excludedAtts - исключенные атрибуты;
onCreationHistoricalAtts - атрибуты для записи истории при создании
Отключить историю
При выставленном чекбоксе Отключить историю при изменении никакие данные не будут записываться в историю, и отражаться в виджете «История событий», соответственно.
Импорт данных
Аспект import-data-config (Импорт данных) - необходим для настройки вариантов импорта данных.
Определение аспекта поставляется модулем ecos-integrations и использует форму конфигурации uiserv/form@import-data-aspect-form.
Форма настройки:
id - id варианта.
Название - название варианта, которое будет отображаться в журнале.
Camel DSL - Camel DSL с типом IMPORT_DATA, в котором описана обработка данных.
Разрешен для - можно указать группы или пользователей напрямую. Если оставить пустым, вариант будет доступен всем.
Для типа данных может быть добавлено несколько конфигураций импорта.
Созданные конфигурации будут доступны в журнале по кнопке Импорт:
Вариант «По умолчанию»
Если вариант «По умолчанию» включен, можно указать Маппинг для ассоциаций.
Указывается атрибут в Типе данных и атрибут в связанном типе, для поиска. Атрибутов для поиска может быть указано несколько. Если поле оставить пустым, то поиск будет вестись по системному атрибуту _name.
Примечание
Шаблон для варианта «По умолчанию» формируется по журналу, в котором выполняется скачивание шаблона.
Если в типе присутствуют обязательные атрибуты, которых нет в журнале, они будут добавлены в конец столбцов в шаблоне.
В шаблон не выгружаются системные, вычисляемые (созданные и в типе данных, и в журнале), вложенные поля.
Для варианта «По умолчанию» добавлен универсальный CamelDSL default-import-data.
Имеет активности
Чтобы письмо обрабатывалось и добавлялось как активность необходимо:
Добавить в тип данных аспект Имеет активности (has-ecos-activities) и настроить его конфигурацию:
Указать алиас, по которому будет осуществляться поиск типа данных в заголовке письма, выбрать атрибут типа данных.
В Теме сообщения в конце указывать связь в формате (Алиас: Значение)
Для рабочих пространств по умолчанию добавлена следующая настройка аспекта:
Для включения обработки писем в виджете «Активности» необходимо указать почтовый ящик в настройке mail-inbox-activity.
Вычисляемые атрибуты в аспекте
Пример показывает, как один раз описать вычисляемые атрибуты в аспекте и переиспользовать их в нескольких типах данных. Скрипт аспекта выполняется в контексте записи того типа, к которому подключён аспект, и может читать её атрибуты через value.load(...).
Пример состоит из трёх файлов:
Файл |
Назначение |
|---|---|
|
аспект «Вычисление возраста» с вычисляемыми атрибутами |
|
тип данных «Пример возраста — тип A», к которому подключён аспект |
|
тип данных «Пример возраста — тип B», к которому подключён тот же аспект |
Аспект
Аспект age-test содержит два вычисляемых атрибута типа SCRIPT. Оба используют storingType: ON_MUTATE — значение пересчитывается и сохраняется при каждом изменении записи.
Атрибут |
Тип |
Описание |
|---|---|---|
|
TEXT |
всегда возвращает строку |
|
NUMBER |
возраст на дату расчёта, вычисленный по атрибутам записи |
Алгоритм вычисления атрибута age:
Прочитать из записи
dateBirthиcalculationDateв строковом виде (?str).Если хотя бы одна из дат не заполнена — вернуть
null.Разобрать обе даты на год, месяц и день (первые 10 символов в формате
ГГГГ-ММ-ДД).Если дата расчёта раньше даты рождения — вернуть
null.Вычесть год рождения из года расчёта. Если в году расчёта день рождения ещё не наступил — уменьшить результат на 1.
age-test-aspect.yml
id: age-test
name:
ru: Вычисление возраста
attributes:
- id: constant
name:
ru: Проверка вычисления
type: TEXT
computed:
type: SCRIPT
storingType: ON_MUTATE
config:
fn: |
return "Любой текст";
- id: age
name:
ru: Возраст на дату расчёта
type: NUMBER
computed:
type: SCRIPT
storingType: ON_MUTATE
config:
fn: |
var birth = value.load('dateBirth?str');
var target = value.load('calculationDate?str');
if (!birth || !target) return null;
var b = birth.substring(0, 10).split('-').map(Number);
var d = target.substring(0, 10).split('-').map(Number);
if (d[0] < b[0] ||
(d[0] === b[0] &&
(d[1] < b[1] ||
(d[1] === b[1] && d[2] < b[2])))) {
return null;
}
var age = d[0] - b[0];
if (d[1] < b[1] ||
(d[1] === b[1] && d[2] < b[2])) {
age--;
}
return age;
Типы данных
Оба типа наследуются от emodel/type@user-base, хранятся в ECOS_MODEL и подключают аспект через aspects: - ref: emodel/aspect@age-test. Набор собственных атрибутов у типов одинаковый: name, dateBirth, calculationDate. Типы различаются только идентификатором и названием.
id: age-example-a
name:
ru: Пример возраста — тип A
parentRef: emodel/type@user-base
storageType: ECOS_MODEL
aspects:
- ref: emodel/aspect@age-test
model:
attributes:
- id: name
name:
ru: Имя
type: TEXT
- id: dateBirth
name:
ru: Дата рождения
type: DATE
- id: calculationDate
name:
ru: Дата расчёта
type: DATE
id: age-example-b
name:
ru: Пример возраста — тип B
parentRef: emodel/type@user-base
storageType: ECOS_MODEL
aspects:
- ref: emodel/aspect@age-test
model:
attributes:
- id: name
name:
ru: Имя
type: TEXT
- id: dateBirth
name:
ru: Дата рождения
type: DATE
- id: calculationDate
name:
ru: Дата расчёта
type: DATE
В результате у записей обоих типов автоматически появляются атрибуты аспекта, которые вычисляются по данным самой записи. Префикс в аспекте не задан, поэтому он равен идентификатору, и атрибуты доступны как age-test:constant и age-test:age.
Примечание
Аспект не объявляет атрибуты dateBirth и calculationDate — их нужно объявить в типе данных, как в примерах выше. Если одно из входных значений пустое, скрипт возвращает null.
Чтобы сделать аспект самодостаточным, dateBirth и calculationDate можно перенести в attributes самого аспекта. Тогда в типах их объявлять не нужно, но в скрипте необходимо использовать имена с префиксом:
var birth = value.load('age-test:dateBirth?str');
var target = value.load('age-test:calculationDate?str');
Эти же полные имена используйте в формах, журналах и других обращениях к перенесённым атрибутам.