Шаблоны уведомлений
1. Общие сведения
1.1 Описание сущности «Шаблон уведомления»
- Id:
Уникальный идентификатор шаблона уведомления.
- Name:
Имя шаблона уведомления.
- Tags:
Теги.
- Notification title:
Заголовок уведомления, мульти-язычное поле – строка с поддержкой freemarker.
- Notification body:
Многокомпонентное поле для описания тела уведомления с привязкой к указанной локали (подробнее см. ниже).
- Model:
Модель, исходя из которой будет происходить шаблонизация текста (подробнее см. ниже).
- Multi templates:
Вычисляемые шаблоны в зависимости от типа документа, по которому отсылается уведомление (подробнее см. ниже).
- Predicate:
Позволяет задать дополнительные условия для связки шаблон - тип. Вычисление предикатов происходит на основе атрибутов модели.
Notification body
В одном шаблоне уведомления предусмотрена поддержка разных локалей (языков):
Lang — локаль сообщения, например en, ru.
Body — исходное содержимое текста сообщения c использованием freemarker. При нажатии на кнопку «Редактировать как HTML» открывается richText редактор сообщения для более удобного редактирования html-разметки.
Model
Модель, исходя из которой будет происходить шаблонизация текста – title или body для уведомлений. Модель – это map ключ: значение, где ключ – имя переменной, доступной в шаблоне, а значение – ecos records выражение для вычисления значения переменной.
Базовым record является документ, по которому идёт бизнес-процесс. То есть, если в модели указать значение
.disp, то вычисляется заголовок по документу. Также есть доступ к другим объектам через знак $, например,
если уведомление отправляется в рамках бизнес-процесса — $process.webUrl (по умолчанию доступны дополнительные
переменные $now, $user, $webUrl).
При использовании мульти-шаблонов модель из базового шаблона будет сливаться с моделью, найденной по типу — таким образом часть «базовой» модели может быть описана в базовом шаблоне, а более специфичные атрибуты вынесены в конкретный шаблон.
Multi templates
Вычисляемые шаблоны в зависимости от типа документа, по которому отсылается уведомление. Например, может быть «базовый» шаблон, который включает в себя несколько других шаблонов с разными типами документов.
При отправке уведомления, если у документа тип не соответствует ни одному из мульти-шаблонов, отправка осуществится по «базовому» шаблону; если тип документа соответствует мульти-шаблону — по соответствующему шаблону.
Тип проверяется на точное равенство ссылки, с учётом условий и порядка вариантов. Автоматическое совпадение с родительским типом не подразумевается.
Шаблоны поддерживают рабочие пространства: одинаковый простой ID в разных пространствах обозначает разные определения. Для локального шаблона используйте полный RecordRef, полученный системой, с префиксом области. Списки зависят от пространства и прав; переносимый экспорт очищает workspace в экспортируемой копии.
1.2 Журнал «Шаблоны уведомлений»
Журнал ”Шаблоны уведомлений” расположен в Разделе администратора → Конфигурация уведомлений:
2. Операции
2.1 Создание шаблона уведомления
Для создания необходимо перейти в журнал «Шаблоны уведомлений», см. 1.2 Журнал «Шаблоны уведомлений».
Шаблон уведомления может быть создан несколькими способами:
Создание нового объекта;
Импорт модуля (zip).
2.1.1 Создание нового объекта
Для создания нового объект необходимо нажать на «+» и выбрать «Создать новый шаблон уведомления»
Описание полей см. 1.1 Описание сущности «Шаблон уведомления».
Для примера создадим базовый шаблон c уведомлением о том, что создан новый документ.
Открываем форму создания и заполняем следующую информацию:
id - test-incident-base-new-incident-to-possible-responsible
name - Базовый шаблон. Новый документ
notification title - Новый инцидент: ${title}.
Notification body -
lang= ru,bodyзаполняем следующим текстом:
<#import "test-template-lib" as lib>
<@lib.its_test_message/>
<p>
Сообщаем, что сформирован документ, за обработку которого Вы являетесь ответственным.<br>
<@lib.document_link/><br>
Пожалуйста, проверьте рабочий список задач Скиф.<br>
<p>
В данном шаблоне импортируется библиотечный шаблон:
<#macro its_test_message>
<b>Это письмо было отправлено вам в рамках тестирования настроек новой системы.
Вам не нужно отвечать или как-то реагировать на него.</b>
</#macro>
<#macro document_link>
<a href="${web_url}/v2/dashboard?recordRef=${doc_recordRef}"><u><i>${title}</i></u></a>
</#macro>
В шаблонах уведомления поддерживается import и include других шаблонов по их id.
В текущем примере:
<@lib.its_test_message/> - печать блока текста, информирующего о том, что это сообщение является тестовым.
<@lib.document_link/> - печатает ссылку на документ, по которому идет бизнес процесс, в данном случае – сам документ.
Подробнее об использовании макросов, импорте и включении других шаблонов см. документацию apache freemarker - https://freemarker.apache.org
Model - описываем модель, которая потребуется для шаблонизации текста:
Flowable:
web_url : $process.webUrl – используется для формирования ссылки на документ
doc_recordRef : .id – уникальный id документа, так же используется для формирования ссылки на документ
title : .disp – заголовок документа
Citeck BPMN:
См. описание компонента «Уведомление» в документации по Citeck BPMN.
2.1.2 Импорт модуля
Для импорта модуля в журнале «Шаблоны уведомлений» нажмите на «+» и выберите «Загрузить шаблон уведомления»
В открывшейся форме загрузите zip архив с шаблоном уведомления. Подробнее про модуль «Шаблон уведомления» см. 2.4 Выгрузка шаблона уведомления.
2.2 Редактирование шаблона уведомления
Для редактирования шаблона уведомления перейдите в журнал (см. 1.2 Журнал «Шаблоны уведомлений»), найдите нужный шаблон и нажмите на действие «Редактировать».
2.3 Удаление шаблона уведомления
Для удаления шаблона уведомления перейдите в журнал (см. 1.2 Журнал «Шаблоны уведомлений»), найдите нужный шаблон и нажмите на действие «Удалить».
2.4 Выгрузка шаблона уведомления
Для выгрузки модуля шаблона уведомления перейдите в журнал (см. 1.2 Журнал «Шаблоны уведомлений»), найдите нужный шаблон и нажмите на действие «Скачать».
Модуль представляет собой zip-архив с мета-информацией по шаблону и самим контентом шаблона. Для примера, выгрузим модуль для шаблона, созданного на шаге 2.1.1 Создание нового объекта.
Файл test-incident-base-new-incident-to-possible-responsible.html.ftl.meta.yml содержит метаданные одиночного файла тела, например:
{
"id" : "test-incident-base-new-incident-to-possible-responsible",
"name" : "Базовый шаблон. Новый документ",
"notificationTitle" : {
"ru" : "Новый инцидент: ${title}"
},
"model" : {
"web_url" : "$process.webUrl",
"doc_recordRef" : ".id",
"title" : ".disp"
},
"multiTemplateConfig" : []
}
Файл test-incident-base-new-incident-to-possible-responsible.html.ftl является самим контентом шаблона, его содержимое:
<#import "test-template-lib" as lib>
<@lib.its_test_message/>
<p>
Сообщаем, что сформирован документ, за обработку которого Вы являетесь ответственным.<br>
<@lib.document_link/><br>
Пожалуйста, проверьте рабочий список задач Скиф.<br>
<p>
Обратите внимание, что модуль должен быть именно zip архивом, а файлы внутри него чувствительны к наименованию и расширению.
Для одиночного тела используется пара <id>.html.ftl и <id>.html.ftl.meta.yml. Для локализованного набора используется общее имя метаданных <id>.html.meta.yml и тела <id>.html_<lang>.ftl. При переносе сохраняйте структуру выгруженного архива.
Примечание
Если тело шаблона предусматривает несколько локалей, то в имени файла контента указывается локаль по следующему правилу:
test-incident-base-new-incident-to-possible-responsible.html_en.ftl для локали en
test-incident-base-new-incident-to-possible-responsible.html_ru.ftl для локали ru
и т.д.
2.5 Структура шаблона в репозитории проекта
При разработке приложения на платформе Citeck шаблоны уведомлений хранятся как артефакты в ресурсах проекта и деплоятся через ecos-apps.
Шаблоны размещаются внутри notification/template/. Для удобства их можно группировать в отдельные каталоги:
src/main/resources/<path>/
└── notification/
└── template/
└── my-notification-template/
├── my-notification-template.html.meta.yml ← метаданные
└── my-notification-template.html_ru.ftl ← тело письма (Freemarker, язык ru)
Правила именования:
Имя директории — соглашение проекта; оно не обязано совпадать с
idиз метаданных.Метафайл:
<id>.html.meta.ymlТело письма:
<id>.html_<lang>.ftl— по одному файлу на язык (_ru,_enи т.д.)
Для поддержки нескольких языков добавьте несколько .ftl-файлов:
my-notification-template/
├── my-notification-template.html.meta.yml
├── my-notification-template.html_ru.ftl ← русский
└── my-notification-template.html_en.ftl ← английский
Пример метафайла (<id>.html.meta.yml):
{
"id": "my-notification-template",
"name": "My Notification Template",
"notificationTitle": {
"ru": "${contract!\"\"} с ${counterparty!\"\"}: ${status}",
"en": "${contract!\"\"} with ${counterparty!\"\"}: ${status}"
},
"tags": [],
"model": {
"contract": "?disp",
"date": "date|fmt('dd-MM-yyyy')",
"counterparty": "counterparty.fullOrganizationName",
"initiator": "_creator",
"docRef": "?id",
"status": "_status",
"docNum": "_docNum"
},
"multiTemplateConfig": []
}
Примечание
Путь до папки notification/template/ зависит от конкретного проекта и настройки ecos-apps.
В поставке ecos-notifications используется src/main/resources/eapps/artifacts/. Для ECOS App путь начинается с artifacts/notification/template/.
2.6 Поле model — маппинг атрибутов Records API
Поле model — это JSON-объект: ключ — имя переменной, доступной в Freemarker-шаблоне, значение — выражение атрибута документа в синтаксисе Records API.
Документ для вычисления атрибутов — тот, на котором запущен процесс (задаётся в поле Record уведомления в Send Task; если не указано — документ процесса).
Примеры выражений:
Переменная в шаблоне |
Выражение в |
Описание |
|---|---|---|
|
|
Номер документа |
|
|
RecordRef документа (используется для построения ссылки) |
|
|
Системный статус документа |
|
|
Отображаемое название статуса на русском |
|
|
Отображаемое название документа |
|
|
Вложенный атрибут через |
|
|
Дата с форматированием через |
|
|
Локальный идентификатор типа через |
|
|
Создатель документа |
|
|
URL процесса (контекстная переменная) |
|
|
Текущая дата/время |
|
|
Текущий пользователь |
3. Использование переменных в шаблоне
В шаблонах уведомлений доступны переменные, определенные в модели, см 1.1 Описание сущности «Шаблон уведомления» блок «Model», а также добавленные сервисы в freemarker.
3.1 Сервисы и константы
В шаблонах уведомлений доступны следующие сервисы, добавленные в freemarker:
Сервис |
Метод / свойство |
Описание |
|---|---|---|
|
|
Возвращает ссылку на карточку recordRef; при наличии контекста пространства добавляет |
|
|
Возвращает настроенный webUrl сервера. |
|
|
Заголовок уведомления. |
|
|
Отправитель уведомления. |
|
|
Получатель уведомления. |
|
|
Копия уведомления. |
|
|
Скрытая копия уведомления. |
|
|
Возвращает base64 data image представление изображения по переданному имени файла изображения. См. пример — Вставка изображений в шаблон. |
|
|
Возвращает base64 представление изображения по переданному имени файла изображения. |
|
|
Получение значения по ключу. |
|
|
Получение значения по ключу; если значение не найдено — возвращается значение по умолчанию. |
|
|
Получение значения по ключу; если значение null — выбрасывается исключение. |
Сервис config предоставляет доступ к Конфигурации Citeck по ключу в формате <область>$<идентификатор>:
//получение значения конфигурации по ключу и приведение к типу String
<#assign replyEmail = config.getNotNull("app/service-desk$sd-email-reply").asText()>
Для добавления константы можно использовать в модели шаблона контекстный атрибут str:
$str.CONSTANT
вернется:
CONSTANT
3.2 Множественные атрибуты
Предположим, что в источнике есть атрибут eventLines, который возвращает список «строк» с атрибутами.
Для получения данных по множественным атрибутам, как и для всех других, используется стандартные records выражения:
lines: eventLines[]{id:skifem:eventLineId,text:VIEW_0POSTXT}- получить список строк, с атрибутами id и VIEW_0POSTXT. Внутри {} можно указывать атрибуты, которые необходимо подгрузить в объект.firstLine: eventLines{id:skifem:eventLineId,text:VIEW_0POSTXT}- аналогично примеру выше, с оговоркой, что будет загружен только первый объект.
В самом шаблоне уведомления выведем информацию по списку строк в виде html таблицы и отдельной строкой первый элемент:
<style>
table, tr, td {
border: 1px solid;
border-collapse: collapse;
overflow-wrap: break-word;
}
thead {
font-weight: bold;
}
</style>
<table>
<caption>Пример - информация по строкам</caption>
<tr>
<th>id</th>
<th>текст документа</th>
</tr>
<#if (lines?? && lines?size > 0)>
<#list lines as line>
<tr>
<td>${line.id!""}</td>
<td>${line.text!""}</td>
</tr>
</#list>
</#if>
</table>
<br>
Пример - информация по первой строке: id: ${firstLine.id!""}, text: ${firstLine.text!""}
<p>
В результате получим email со следующим содержанием:
3.3 Вставка изображений в шаблон
В шаблонах уведомлений реализована возможность вставлять изображения в html разметку в виде base64 data.
Доступные для вставки изображения находятся в журнале «Файлы уведомлений» в Разделе администратора → Конфигурация уведомлений:
Для загрузки нового изображения необходимо нажать на «+» и загрузить изображение. Имя изображения является идентификатором и должно быть уникально.
Для примера, предположим, что в шаблон письма необходимо добавить кнопку с ссылкой на ресурс https://citeck.com. Для этого необходимо осуществить следующие действия:
Загрузить файл изображения test-logo-citeck.png в журнал «Файлы уведомлений».
В шаблоне добавим html разметку с кнопкой и src в виде base64 изображения, загруженного в пункте №1.
Привет! Это тестовый шаблон с кнопкой-изображение :)
<form action="https://citeck.com/">
<input type="image" src="${image.toBase64Data("test-logo-citeck.png")}" style="max-height: 67px; max-width: 200px;">
</form>
Как видно из шаблона выше, для конвертации изображение в base64 data необходимо у сервиса image вызвать метод toBase64Data и передать ему идентификатор изображения.
В результате получим email с кнопкой в виде изображения:
Поддержка base64-изображений, HTML-форм и input type=image зависит от почтового клиента. Сервис формирует HTML, но не гарантирует одинаковую работу таких элементов во всех клиентах.
3.4 Прикрепление вложений (attachments) к email уведомлению
Для того чтобы прикрепить вложение необходимо в шаблоне уведомления в модель добавить атрибут _attachments. В него мы можем указать контент или список из контентов. Выглядеть это должно следующим образом:
В значении к полю _attachments необходимо указать Records API атрибут.
Для рекордов, которые хранятся в emodel - _content{bytes,meta:?json}
Примечание
Доступно с версии 2.15.0 микросервиса ecos-notification.
Можно использовать любой атрибут, в котором хранится content рекорда. В примере используется _content, так как он является атрибутом для хранения контента по умолчанию.
Ожидаемая модель:
{
"bytes": "SOj2",
"meta": {
"name": "test.txt",
"ext": "txt",
"mimeType": "text/plain"
}
}
Для рекордов, которые хранятся в Alfresco - cm:content{bytes,previewInfo?json}
Примечание
Доступно с версии 2.5.0 микросервиса ecos-notification.
Ожидаемая модель:
{
"bytes": "SOj2",
"previewInfo": {
"originalName": "test.txt",
"originalExt": "txt",
"mimeType": "text/plain"
}
}
Использование вышеуказанных атрибутов необязательно, главное чтобы атрибут _attachments соответствовал ожидаемой модели.
Непустое вложение должно содержать корректные Base64-байты, метаданные имени и определимый MIME-тип. Повреждённый элемент может вызвать ошибку подготовки письма. Вложения с одинаковым итоговым именем заменяют друг друга; используйте уникальные имена.
- bytes:
Контент файла закодированный в формат Base64
- mimeType:
Mimetype файла
- ext:
Расширение файла
- name:
Имя файла
Примечание
Если в
originalNameбудет находиться имя без расширения, то система сама допишет расширение файлу из originalExt.Если окажется, что
cm:contentбудет отсутствовать у ноды (или лист контентов будет пустым), то отправится уведомление без прикрепления вложений.
3.5 Шаблоны-библиотеки (библиотеки макросов)
Библиотека макросов — шаблон, предназначенный для переиспользования через Freemarker import/include. Это назначение, а не отдельный тип или запрет самостоятельной отправки. Файл <id>.html.ftl без кода языка также может быть обычным телом уведомления.
Структура библиотеки в репозитории:
notification/template/my-template-lib/
├── my-template-lib.html.ftl ← определение макросов
└── my-template-lib.html.ftl.meta.yml ← метаданные
Метафайл библиотеки (YAML, не JSON):
id: my-template-lib
name: My Template Library
Пример содержимого библиотеки (my-template-lib.html.ftl):
<#macro reply_message>
<#assign replyEmail = config.getNotNull("app/your-app$reply-email").asText()>
<hr/>
<i>Вы можете <a href="mailto:${replyEmail}?Subject=Re: ${_notification.title}"
target="_top">Ответить</a> на это сообщение.
Ваш ответ будет добавлен как комментарий.</i>
</#macro>
<#macro document_link docRef title>
<a href="${link.getRecordLink(docRef)}" target="_blank">${title}</a>
</#macro>
Импорт библиотеки в другом шаблоне:
<#import "my-template-lib" as lib>
<p>Уважаемый (-ая) ${initiator}!</p>
<p>Создана заявка: <@lib.document_link docRef=docRef title="SD-${docNum}"/></p>
<@lib.reply_message/>
Примечание
Для файла без кода языка определяется ключ en. Тело выбирается по запрошенному языку, затем языку по умолчанию, затем берётся первое доступное. Отсутствие языкового суффикса не определяет, является ли шаблон библиотекой.
Пример из ecos-service-desk: библиотека sd-template-lib содержит макрос reply_message,
который вставляет ссылку для ответа по email с автоматической привязкой к заявке.