Входные и выходные данные решения
Одно и то же решение DMN может вызываться из разных мест платформы, и от вызывающей стороны зависит и то, откуда решение получает входные переменные, и то, каким должен быть его результат.
Кто вызывает решение |
Откуда берутся входные переменные |
Какая версия решения используется |
|---|---|---|
Задача бизнес-правило в процессе BPMN |
Переменные процесса |
Определяется настройкой «Связь» в задаче |
Динамическая роль типа данных |
Свойство схемы «Модель» |
Всегда последняя опубликованная |
Свойство схемы «Модель» |
Всегда последняя опубликованная |
Важно
Это два независимых механизма: свойство «Модель» не участвует в вызове из задачи бизнес-правило, а переменные процесса недоступны при вычислении динамической роли и условия KPI.
Решение можно использовать в нескольких сценариях, если вызывающие стороны передают переменные с согласованными именами и типами, а результат соответствует требованиям каждого сценария.
Переменные процесса (вызов из BPMN)
При вызове из задачи бизнес-правило решение выполняется в контексте процесса, и ему доступны переменные этого процесса — в том числе documentRef.
В качестве Expression входного элемента указывается имя переменной процесса. Если нужного значения в переменных нет, его либо кладут туда заранее (например, script task), либо получают прямо в выражении на языке juel:
Records.get(documentRef).load("color")
Подробнее — в описании задачи бизнес-правило.
Модель (вызов вне процесса)
Динамическая роль и условие применения KPI получают входы из атрибутов документа. Переменные экземпляра BPMN в эти вызовы автоматически не передаются. Соответствие атрибутов документа переменным решения описывается на самой схеме DMN — в свойстве «Модель».
Модель — это набор пар Ключ — Значение:
Ключ — имя переменной, которая будет доступна в решении. Именно его указывают в поле Expression входного элемента таблицы;
Значение — атрибут рекорда (документа), из которого берётся значение переменной.
Чтобы заполнить модель, перейдите в режим DRD и кликните по свободному месту схемы — в панели свойств справа появится блок «Модель»:
Значением может быть любой атрибут в синтаксисе Records API, включая системные атрибуты и скалярные модификаторы:
Значение |
Что попадёт в переменную |
|---|---|
|
значение атрибута |
|
отображаемое имя документа |
|
логин автора документа |
|
идентификатор типа документа |
|
числовое значение атрибута |
|
ссылка на сам документ (RecordRef) |
Если атрибут может оказаться незаполненным, задайте в модели значение по умолчанию через пост-процессор ! — тогда переменная не придёт в решение как null:
Значение |
Что попадёт в переменную |
|---|---|
|
число, либо |
|
логин, либо пустая строка |
|
идентификатор статуса, либо константа |
Без значения по умолчанию незаполненный атрибут может прийти в решение как null. Результат зависит от выражения: правило может явно проверять пустое значение, не сработать или завершиться ошибкой. Вызов метода у null в JUEL может привести к ошибке, поэтому пустые значения нужно обрабатывать явно. Для многозначных атрибутов используйте признак [], чтобы получить список, в том числе пустой.
Тип входного элемента (Type) в таблице должен соответствовать типу загруженного атрибута: для текстовых значений — string, для чисел — integer/long/double и т. д.
Предупреждение
При вызове через модель входов переменная documentRef и другие переменные процесса автоматически не определяются. Обращение к отсутствующей переменной может привести к ошибке или пустому значению в зависимости от языка и выражения; пустой результат всей таблицы не гарантируется.
Если в выражении нужна ссылка на сам документ, добавьте в модель ключ со значением ?id и обращайтесь к нему по имени ключа.
Многозначные атрибуты и проверка вхождения
Многозначный атрибут (с [] в конце) приходит в решение списком. Типичная задача — проверить, входит ли значение в этот список: например, состоит ли автор документа в определённой группе.
Признак [] в модели обязателен: он гарантирует, что переменная всегда будет списком (возможно, пустым). Без него при отсутствии значения придёт null, и проверка в выражении завершится ошибкой.
Предупреждение
Тип колонки (Type) применяется к результату входного выражения. При Type: string список преобразуется в строку, поэтому вызов cellInput.contains(...) на JUEL проверяет подстроку вместо элемента списка. Например, поиск GROUP_finance может ложно сработать на GROUP_finance-accounting. Для точной проверки обращайтесь к исходной переменной списка, как показано ниже.
Ниже — два корректных способа. Первый проще и нагляднее, второй лучше масштабируется на большое число проверок.
Проверка в атрибуте
Проверку можно выполнить прямо в модели и передать в решение готовый признак boolean. Для групп пользователя это делает _has:
Ключ |
Значение |
|---|---|
|
|
|
|
В таблице для каждой проверки заводится своя колонка: Expression — ключ модели, Type — boolean, в ячейках true или -. Сравнение точное, переключать язык выражений не требуется.
Способ удобен, пока проверок немного: каждая добавляет колонку, и при десятке групп таблица становится слишком широкой.
Проверка в ячейках правил на JUEL
Второй способ позволяет обойтись одной колонкой на любое число проверок. Он опирается на то, что приведение типа не меняет исходную переменную: результат входного выражения кладётся в отдельную переменную с именем из поля Input Variable (по умолчанию cellInput), а переменные модели остаются доступны в ячейках в исходном виде.
Модель:
Ключ |
Значение |
|---|---|
|
|
В шапке колонки указывается Expression = creatorAuthorities, Type оставляется string. Выражение шапки при этом вычисляется как обычно, но его результат (cellInput) в ячейках не используется — колонке он нужен только как заголовок.
В ячейках правил обращение идёт напрямую к переменной модели, а не к cellInput:
creatorAuthorities.contains("GROUP_finance-accounting")
creatorAuthorities.contains("GROUP_lawyers")
creatorAuthorities.contains("GROUP_it") || creatorAuthorities.contains("GROUP_admins")
Для приведённых выражений с Java-методом .contains(...) каждой ячейке нужно задать язык JUEL. Язык по умолчанию для входных ячеек — FEEL; приведённый синтаксис JUEL к нему не относится. Язык задаётся не в шапке колонки, а на самой ячейке: кликните по ячейке правой кнопкой мыши, выберите Change Cell Expression Language и укажите JUEL. Настройка сохраняется для каждой ячейки отдельно.
Примечание
Имя в поле Input Variable не должно совпадать ни с одним ключом модели. При совпадении значение из колонки перекроет переменную модели, и в ячейке окажется строка вместо списка. По умолчанию используется cellInput, и менять его не нужно.
В выходных ячейках cellInput недоступен: выходы вычисляются на общем контексте переменных, без слоя со значением колонки. Переменные модели в них доступны.
В ячейке доступна вся булева логика языка выражений — отрицание, И, ИЛИ, сравнения:
Операция |
Формы записи |
|---|---|
НЕ |
|
И |
|
ИЛИ |
|
Равенство |
|
Сравнение |
|
Проверка на пустоту |
|
Например:
!creatorAuthorities.contains("GROUP_interns")
creatorAuthorities.contains("GROUP_it") && !creatorAuthorities.contains("GROUP_admins")
not creatorAuthorities.contains("GROUP_interns") and amount > 100000
Правило считается сработавшим, если выражение вернуло true.
Важно
Условия с отрицанием («не состоит в группе») истинны для большинства документов, поэтому правила начинают пересекаться. При политике выбора Unique одновременное срабатывание нескольких правил приводит к ошибке — используйте First или Collect.
Логические операции не защищают от отсутствующего в модели ключа: конструкция вида !empty creatorAuthorities && creatorAuthorities.contains(...) не поможет, потому что неизвестное имя вычисляется уже в первом операнде. От пустого значения такая защита работает — операнды вычисляются слева направо, и до вызова метода дело не доходит. От пустого значения защищает [] в атрибуте модели: переменная всегда существует, и в худшем случае это пустой список, на котором проверка вернёт false.
Правило по умолчанию. Чтобы правило срабатывало всегда, оставьте его входные ячейки пустыми: входная ячейка без выражения считается истинной и не вычисляется вовсе, поэтому язык выражений для неё не важен. В редакторе пустая входная ячейка отображается прочерком - независимо от выбранного для неё языка выражений. При политике выбора First правила проверяются в порядке следования, поэтому правило по умолчанию должно быть последним в таблице — иначе оно перехватит все остальные. Для динамической роли это удобный способ задать исполнителя по умолчанию, чтобы роль не осталась пустой, если ни одно правило не подошло.
Примечание
Если входных колонок несколько, в правиле по умолчанию должны быть пустыми все входные ячейки: достаточно одной заполненной, чтобы правило перестало быть безусловным.
Не используйте вместо пустой ячейки значение true: в ячейке на FEEL это сравнение значения колонки с true, которое на строковом входе не сработает.
Требования к результату
Динамическая роль
Результатом должны быть имена пользователей и групп, которые войдут в роль, — строки типа string:
"ivan.petrov"— имя пользователя;"GROUP_administrators"— группа (имя с префиксомGROUP_);"emodel/person@ivan.petrov"— recordRef пользователя;"emodel/authority-group@administrators"— recordRef группы.
Несколько участников в одной ячейке перечисляются через запятую, лишние пробелы обрезаются:
Важно
В состав роли попадают значения всех выходных колонок всех сработавших правил — они объединяются в один общий список. Лишняя выходная колонка (например, служебная пометка или комментарий) добавит в роль несуществующего участника, поэтому в решении для роли не должно быть выходов, не являющихся именами участников.
Для служебных пояснений используйте колонку Annotations — она в результат не входит.
Для единственного выхода Output Name может быть пустым. Если выходов несколько, каждому нужно задать уникальное имя. Для участников роли используйте тип string:
Политика выбора выбирается по задаче: Unique допускает не более одного сработавшего правила и завершается ошибкой, если подошло несколько; Collect собирает все сработавшие.
Состав, вычисленный решением, объединяется по ИЛИ с полями «Участники роли» и «Атрибуты» роли типа данных.
Условие применения KPI
Для условия KPI рекомендуется один выход типа boolean и однозначный результат. После выполнения таблицы значения группируются по именам выходов. Проверка KPI берёт первое значение из первой группы результата, преобразует его в строку и сравнивает с true без учёта регистра. Например, true означает применение KPI, а число 1 — нет. Если результат пустой, KPI не применяется.
Остальные значения не объединяются по ИЛИ. Политика выбора применяется при выполнении таблицы и влияет на полученный результат, включая агрегацию или ошибку при несовместимых правилах. Поэтому Collect не следует использовать для объединения булевых условий KPI. При нескольких выходах не полагайтесь на расположение колонок для выбора результата.
Вызов из процесса BPMN
Результат решения не сохраняется в переменные процесса автоматически — в задаче бизнес-правило указываются «Переменная результата» и «Сопоставление результата решения». См. задачу бизнес-правило.
Ограничения и производительность
Для динамической роли и условия KPI исполняемая таблица выбирается по ключу — используется последняя опубликованная версия.
Карта входов KPI загружается из текущей сохранённой модели. Изменение свойства «Модель» без публикации может изменить входные переменные для уже опубликованной таблицы. После согласованных изменений карты входов и таблицы опубликуйте модель заново.
DMN вычисляется сервисом процессов. Нельзя рассчитывать на единое кеширование для всех способов вызова: повторное вычисление зависит от вызывающего механизма.
Если состав роли определяется значением атрибута или фиксированным списком, используйте типы динамической роли Attribute или Value. DMN подходит для табличной логики принятия решений.