Шаблоны нумерации
Описание
Шаблоны нумерации — механизм автоматической генерации последовательных номеров для сущностей в Citeck. С их помощью можно настроить сквозную, ежемесячную или проектную нумерацию через интерфейс администратора.
Шаблон задаёт правило формирования ключа счётчика. Счётчик хранит текущее значение и увеличивается при запросе следующего номера с инкрементом. Чтобы запись получала номер при создании, настройте нумерацию её типа или вычисляемый атрибут Counter. Шаблоны и счётчики хранятся в сервисе ecos-model.
Каждая пара шаблон + вычисленный ключ образует отдельную последовательность. При смене месяца или проекта числовые значения могут повторяться в разных последовательностях; для различения включите месяц или проект в отображаемый номер. Выдача номера выполняется в отдельной транзакции, поэтому откат сохранения бизнес-объекта может оставить пропуск в последовательности.
На этой странице описаны:
структура сущностей Number template и Number counter;
алгоритм работы механизма нумерации;
настройка шаблона через интерфейс;
привязка шаблона к типу данных;
использование счётчика в шаблоне отображения имени;
установка следующего выдаваемого номера.
Описание шаблона выгружается в формате YAML как артефакт model/num-template. Текущие значения счётчиков хранятся отдельно в БД и не входят в описание шаблона.
Number template
Сущность, которая определяет шаблон счетчика на основе текущей даты или полей в сущности, которую мы хотим пронумеровать.
Поле |
Описание |
|---|---|
id |
Локальный идентификатор шаблона, уникальный в его рабочем пространстве |
name |
Произвольное имя. Справочная информация |
counterKey |
Шаблон ключа счетчика. Может быть как константой (будет создан только 1 счетчик для шаблона), так и с вставками в формате |
workspace |
Рабочее пространство шаблона. Пустое значение соответствует глобальному шаблону. |
Number counter
Сущность, в которой ведется счет.
Поле |
Описание |
|---|---|
key |
Ключ счетчика. Константное значение, которое получилось после вычисления counterKey в шаблоне нумерации |
counter |
Значение счетчика |
Алгоритм работы
В приложении, которое использует шаблоны нумерации, настраивается синхронизация с загрузкой всех шаблонов из ecos-model с целью получения списка атрибутов, которые нужны шаблону.
При создании новой сущности мы берем её тип, из типа получаем шаблон нумерации и если он задан, то достаем список необходимых для шаблона атрибутов. Далее отправляем команду с необходимыми атрибутами в ecos-model для получения следующего значения счетчика. Получив значение счетчика, сохраняем его в одном из полей.
Для стандартной нумерации по настройке типа используется системный атрибут _docNum; за его значение отвечает источник записи. Если настроен отдельный вычисляемый атрибут Counter, обращайтесь к этому атрибуту.
Рабочие пространства и права
Глобальный шаблон имеет ссылку вида emodel/num-template@<id>. Для шаблона рабочего пространства используется emodel/num-template@<системный_префикс_пространства>:<id>. При привязке к типу и вызове API передавайте ссылку на нужный шаблон.
Создавать и изменять глобальные шаблоны могут администраторы и системный контекст. Менеджер обычного рабочего пространства также может создавать и изменять шаблоны своего пространства. Установка следующего номера через set-next-number требует отдельных полномочий администратора или системного контекста.
При экспорте описания шаблона поле workspace очищается; при деплое артефакта пространство назначения передаётся отдельно.
Настройка шаблона в интерфейсе
Перейти в журнал «Шаблоны нумерации» (Рабочее пространство «Раздел администратора» - Модель).
Нажать + и выбрать «Создать новый шаблон»
Ввести Id, name и counterKey и нажать Submit
Рассмотрим месячную нумерацию с ключом ${_created|fmt('yyyy-MM')}. Для каждого нового месячного ключа создаётся отдельный счётчик; первый выдаваемый номер — 1:
Новый шаблон нумерации создан.
Привязка к типу данных
Шаблон нумерации можно привязать к типу данных по любому из двух вариантов:
C использованием системного атрибута _docNum, содержащего номер, который генерируется по шаблону:
Выберите шаблон в поле «Шаблон нумерации» типа данных. Для наследования включите соответствующий флаг и оставьте собственную ссылку на шаблон пустой.
С привязкой счетчика к конкретному атрибуту. В поле будет записываться номер из счетчика:
Использование данных счетчика в шаблоне отображения имени
В шаблоне отображения имени можно задать данные счетчика. Например:
Форматирование через fmt
Реализована поддержка форматирования чисел и дат через fmt:
fmt('yyyy.MM', 'en', 'GMT+0')
fmt('00000', 'en')
Например, Test №${_docNum|fmt('00000')} позволяет указать количество символов (заполнение лидирующими нулями).
Шаблон |
Результат |
|---|---|
|
|
|
|
Примечание
${$now|fmt('yyyy-MM-dd')} — текущая дата; noteNumber — атрибут «Регистрационный номер», к которому привязан счетчик.
Установка следующего номера
Для установки следующего выдаваемого номера выполните mutate-запрос set-next-number от администратора или в системном контексте. Сначала создайте нужный шаблон.
Описание шаблона:
---
id: ept-issue-num-template
name: ept-issue-num-template
counterKey: '${link-project:project?id}'
Установка следующего номера для конкретного проекта:
const record = Records.get("emodel/num-template-action@");
record.att("type", "set-next-number");
record.att("args",
{
"templateRef": "emodel/num-template@ept-issue-num-template",
"counterKey": "emodel/ept-project@3059e6bc-1915-4afc-a36e-39effb8a04d9",
"nextNumber": 113
});
await record.save();
Параметр counterKey содержит уже вычисленное значение ключа — здесь ссылку на проект, а не выражение ${link-project:project?id} из шаблона. Если шаблон относится к рабочему пространству, укажите его полную ссылку с префиксом пространства.
После nextNumber: 113 сохранённое значение счётчика становится 112, а следующий запрос с инкрементом выдаёт 113. Установка меньшего значения может привести к повторной выдаче уже использованных номеров: операция не проверяет номера существующих бизнес-объектов.
Запрос к тому же источнику с языком get-next-number показывает следующее значение без инкремента и резервирования. Его следует отличать от получения номера с увеличением счётчика.