Шаблоны уведомлений 

1. Общие сведения 

1.1 Описание сущности «Шаблон уведомления»

Id:: Уникальный идентификатор шаблона уведомления.
Name:: Имя шаблона уведомления.
Tags:: Теги.
Notification title:: Заголовок уведомления, мульти-язычное поле – строка с поддержкой freemarker.
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:: Вычисляемые шаблоны, в зависимости от типа документа, по которому отсылается уведомление. Например, может быть «базовый» шаблон, который включает в себя несколько других шаблонов с разными типами документов.
При отправке уведомления, если у документа, по которому отправляется уведомление, тип не соответствует ни одному из мульти-шаблонов, то отправка осуществится по «базовому» шаблону, если тип документа соответствует мульти-шаблону, то отправка произойдет по соответствующему шаблону.
Predicate:: Позволяет задать дополнительные условия для связки шаблон - тип. Вычисление предикатов происходит на основе атрибутов модели.

1.2 Журнал «Шаблоны уведомлений»

Журнал ”Шаблоны уведомлений” расположен в Разделе администратора → Конфигурация уведомлений:

../../_images/notifications_template_menu_1.png

2. Операции 

2.1 Создание шаблона уведомления 

Для создания необходимо перейти в журнал «Шаблоны уведомлений», см. 1.2 Журнал «Шаблоны уведомлений».

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

Создание нового объекта;

Импорт модуля (zip).

2.1.1 Создание нового объекта 

Для создания нового объект необходимо нажать на «+» и выбрать «Создать новый шаблон уведомления»

../../_images/notifications_template_create_1.png

Описание полей см. 1.1 Описание сущности «Шаблон уведомления».

Для примера создадим базовый шаблон c уведомлением о том, что создан новый документ.

Открываем форму создания и заполняем следующую информацию:

id - test-incident-base-new-incident-to-possible-responsible

name - Базовый шаблон. Новый документ

notification title - Новый инцидент: ${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 Импорт модуля 

Для импорта модуля в журнале «Шаблоны уведомлений» нажмите на «+» и выберите «Загрузить шаблон уведомления»

../../_images/notifications_template_import.png

В открывшейся форме загрузите zip архив с шаблоном уведомления. Подробнее про модуль «Шаблон уведомления» см. 2.4 Выгрузка шаблона уведомления.

2.2 Редактирование шаблона уведомления 

Для редактирования шаблона уведомления перейдите в журнал (см. 1.2 Журнал «Шаблоны уведомлений»), найдите нужный шаблон и нажмите на действие «Редактировать».

../../_images/notifications_template_edit.png

2.3 Удаление шаблона уведомления 

Для удаления шаблона уведомления перейдите в журнал (см. 1.2 Журнал «Шаблоны уведомлений»), найдите нужный шаблон и нажмите на действие «Удалить».

../../_images/notifications_template_delete.png

2.4 Выгрузка шаблона уведомления 

Для выгрузки модуля шаблона уведомления перейдите в журнал (см. 1.2 Журнал «Шаблоны уведомлений»), найдите нужный шаблон и нажмите на действие «Скачать».

../../_images/notifications_template_download.png

Модуль представляет собой zip-архив с мета-информацией по шаблону и самим контентом шаблона. Для примера, выгрузим модуль для шаблона, созданного на шаге 2.1.1 Создание нового объекта.

Файл test-incident-base-new-incident-to-possible-responsible.html.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 архивом, а файлы внутри него чувствительны к наименованию и расширению.
Файл с контентом должен иметь расширение «.html.ftl», а файл с мета информацией должен именоваться по правилу полное_имя_файла_контента_с_расширением.meta.yml

Примечание

Если тело шаблона предусматривает несколько локалей, то в имени файла контента указывается локаль по следующему правилу:
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. Обычно это src/main/resources/app/artifacts/ или src/main/resources/eapps/artifacts/.

2.6 Поле `model` — маппинг атрибутов Records API 

Поле model — это JSON-объект: ключ — имя переменной, доступной в Freemarker-шаблоне, значение — выражение атрибута документа в синтаксисе Records API.

Документ для вычисления атрибутов — тот, на котором запущен процесс (задаётся в поле Record уведомления в Send Task; если не указано — документ процесса).

Примеры выражений:

Переменная в шаблоне	Выражение в `model`	Описание
`docNum`	`_docNum`	Номер документа
`docRef`	`?id`	RecordRef документа (используется для построения ссылки)
`status`	`_status`	Системный статус документа
`statusLabel`	`_status._disp.ru`	Отображаемое название статуса на русском
`contract`	`?disp`	Отображаемое название документа
`counterparty`	`counterparty.fullOrganizationName`	Вложенный атрибут через `.`
`date`	`date\|fmt('dd-MM-yyyy')`	Дата с форматированием через `\|`
`type`	`_type?localId`	Локальный идентификатор типа через `?`
`initiator`	`_creator`	Создатель документа
`processUrl`	`$process.webUrl`	URL процесса (контекстная переменная)
`now`	`$now`	Текущая дата/время
`currentUser`	`$user`	Текущий пользователь

3. Использование переменных в шаблоне 

В шаблонах уведомлений доступны переменные, определенные в модели, см 1.1 Описание сущности «Шаблон уведомления» блок «Model», а также добавленные сервисы в freemarker.

3.1 Сервисы и константы 

В шаблонах уведомлений доступны следующие сервисы, добавленные в freemarker:

link - формирование ссылок
- getRecordLink(recordRef: String): String - возвращает полную ссылку на переданный recordRef вида http://<webUrl>/v2/dashboard?recordRef=<recordRef>
meta - сервис для получения различной мета информация
- getWebUrl(): String- возвращает настроенный webUrl сервера
_notification - информация о текущем уведомлении
- title - заголовок уведомления
- from - отправитель уведомления
- to - получатель уведомления
- cc - копия уведомления
- bcc - скрытая копия уведомления
image - работа с изображениями в шаблоне, см. пример - Вставка изображений в шаблон .
- toBase64Data(fileName: String): String - возвращает base64 data image представление изображения по переданному имени файла изображения
- toBase64(fileName: String): String - возвращает base64 представление изображения по переданному имени файла изображения
config - предоставляет доступ к Конфигурации Citeck по ключу в формате <область>$<идентификатор>.
- get(key: String): DataValue - получение значения по ключу
- getOrDefault(key: String, defaultValue: Any): DataValue - получение значения по ключу, если значение не найдено, то возвращается значение по умолчанию
- getNotNull(key: String): DataValue - получение значения по ключу, если значение null, то выбрасывается исключение
//получение значения конфигурации по ключу и приведение к типу 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} - аналогично примеру выше, с оговоркой, что будет загружен только первый объект.

../../_images/notifications_template_atts_list.png

В самом шаблоне уведомления выведем информацию по списку строк в виде 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 со следующим содержанием:

../../_images/notifications_template_atts_list_result.png

3.3 Вставка изображений в шаблон 

В шаблонах уведомлений реализована возможность вставлять изображения в html разметку в виде base64 data.

Доступные для вставки изображения находятся в журнале «Файлы уведомлений» в Разделе администратора → Конфигурация уведомлений:

../../_images/notifications_files_menu.png

Для загрузки нового изображения необходимо нажать на «+» и загрузить изображение. Имя изображения является идентификатором и должно быть уникально.

../../_images/notifications_template_image_1.png

../../_images/notifications_template_image_2.png

Для примера, предположим, что в шаблон письма необходимо добавить кнопку с ссылкой на ресурс 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 с кнопкой в виде изображения:

../../_images/notifications_template_image_result.png

3.4 Прикрепление вложений (attachments) к email уведомлению 

Для того чтобы прикрепить вложение необходимо в шаблоне уведомления в модель добавить атрибут _attachments. В него мы можем указать контент или список из контентов. Выглядеть это должно следующим образом:

../../_images/notifications_template_attachments_1.png

../../_images/notifications_template_attachments_2.png

В значении к полю _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 соответствовал ожидаемой модели.

bytes:: Контент файла закодированный в формат Base64
mimeType:: Mimetype файла
ext:: Расширение файла
name:: Имя файла

Примечание

Если в originalName будет находиться имя без расширения, то система сама допишет расширение файлу из originalExt.
Если окажется, что cm:content будет отсутствовать у ноды (или лист контентов будет пустым), то отправится уведомление без прикрепления вложений.

3.5 Шаблоны-библиотеки (библиотеки макросов)

Шаблон без языковых html_<lang>.ftl-файлов, но с файлом <id>.html.ftl, является библиотекой макросов. Такой шаблон не отправляется самостоятельно — он содержит переиспользуемые Freemarker-макросы, которые импортируются в другие шаблоны.

Структура библиотеки в репозитории:

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/>

Примечание

Ключевое отличие библиотеки от обычного шаблона — файл тела имеет расширение .html.ftl (без кода языка), а языковые .html_ru.ftl-файлы отсутствуют.

Пример из ecos-service-desk: библиотека sd-template-lib содержит макрос reply_message, который вставляет ссылку для ответа по email с автоматической привязкой к заявке.