Шаблоны нумерации

Описание

Шаблоны нумерации — механизм автоматической генерации последовательных номеров для сущностей в 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 очищается; при деплое артефакта пространство назначения передаётся отдельно.

Настройка шаблона в интерфейсе

  1. Перейти в журнал «Шаблоны нумерации» (Рабочее пространство «Раздел администратора» - Модель).

    ../_images/Number_template_2.png
  2. Нажать + и выбрать «Создать новый шаблон»

  3. Ввести Id, name и counterKey и нажать Submit

Рассмотрим месячную нумерацию с ключом ${_created|fmt('yyyy-MM')}. Для каждого нового месячного ключа создаётся отдельный счётчик; первый выдаваемый номер — 1:

../_images/Number_template_3.png

Новый шаблон нумерации создан.

Привязка к типу данных

Шаблон нумерации можно привязать к типу данных по любому из двух вариантов:

C использованием системного атрибута _docNum, содержащего номер, который генерируется по шаблону:

Выберите шаблон в поле «Шаблон нумерации» типа данных. Для наследования включите соответствующий флаг и оставьте собственную ссылку на шаблон пустой.

../_images/Number_template_4.png

С привязкой счетчика к конкретному атрибуту. В поле будет записываться номер из счетчика:

  1. Перейти в настройки атрибута:

    ../_images/Number_template_5.png
  2. Указать тип Counter, storing type On create, выбрать созданный ранее шаблон нумерации, подтвердить:

    Для Counter также можно использовать метод хранения On empty, чтобы сохранять номер при отсутствии значения. Выбранный номер должен сохраняться в атрибуте.

    ../_images/Number_template_6.png

Использование данных счетчика в шаблоне отображения имени

В шаблоне отображения имени можно задать данные счетчика. Например:

Указывается системный атрибут _docNum:

../_images/Display_name_1.png

Для получения следующего отображения имени Заявка № 17.

Указывается атрибут/-ы, к которому привязан счетчик.

../_images/Display_name_3.png

Форматирование через fmt

Реализована поддержка форматирования чисел и дат через fmt:

fmt('yyyy.MM', 'en', 'GMT+0')

fmt('00000', 'en')

Например, Test №${_docNum|fmt('00000')} позволяет указать количество символов (заполнение лидирующими нулями).

Примеры шаблонов

Шаблон

Результат

Заметка №${$now|fmt('yyyy-MM-dd')} ${noteNumber}

Заметка №2023-02-23 15

Заявка № ${_created|fmt('yyyy-MM')}-${_docNum}

Заявка № 2025-07-1

Примечание

${$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 показывает следующее значение без инкремента и резервирования. Его следует отличать от получения номера с увеличением счётчика.