События сигнала

События сигнала ссылаются на именованный сигнал. Сигнал это событие с глобальной областью видимости (широковещательная рассылка, broadcast): он доставляется всем активным обработчикам.

Ниже пример взаимодействия двух отдельных процессов через сигналы. Первый процесс запускается при обновлении или изменении страхового полиса. После того как сотрудник проверит изменения, генерируется событие сигнала о том, что полис изменён:

event signal throwing

Этот сигнал могут перехватить все экземпляры процессов, которые на него подписаны. Ниже пример процесса, который подписывается на этот сигнал.

event signal catching

Событие сигнала рассылается всем активным обработчикам. В примере выше событие получат все экземпляры процесса, перехватывающего сигнал.

Определение события сигнала

Определение события сигнала объявляется элементом signalEventDefinition. Атрибут signalRef ссылается на элемент signal, объявленный как дочерний элемент корневого элемента definitions. Ниже фрагмент процесса, в котором промежуточные события генерируют и перехватывают сигнал. Элементы signalEventDefinition ссылаются на «глобальный» элемент сигнала.

<definitions>
  <!-- объявление сигнала -->
  <signal id="alertSignal" name="alert" />

  <process id="catchSignal">
    <intermediateThrowEvent id="throwSignalEvent" name="Alert">
      <!-- signal event definition -->
      <signalEventDefinition signalRef="alertSignal" />
    </intermediateThrowEvent>
    <!-- ... -->
    <intermediateCatchEvent id="catchSignalEvent" name="On Alert">
      <!-- signal event definition -->
      <signalEventDefinition signalRef="alertSignal" />
    </intermediateCatchEvent>
    <!-- ... -->
  </process>
</definitions>
В отличие от других событий, например событий ошибки, сигнал при перехвате не поглощается. Если два активных граничных события сигнала перехватывают один и тот же сигнал, сработают оба, даже если они относятся к разным экземплярам процессов.

Выражения

В имени сигнала в определении события сигнала можно использовать выражения. Имя вычисляется, когда процесс входит в область видимости сигнала. Например, выражение в имени вычисляется, когда экземпляр процесса доходит до промежуточного события-перехватчика сигнала.

Так имя сигнала можно формировать динамически из переменных процесса. Это пригодится, например, когда нужно прерывать параллельные ветки выполнения. Пример:

<signal id="alertSignal" name="alert-${execution.processBusinessKey}" />

API сигналов

Генерация сигналов

Сигнал генерирует экземпляр процесса через BPMN-конструкцию или приложение через Java API. Для программной генерации сигналов в RuntimeService есть fluent API:

// широковещательная рассылка сигнала
runtimeService
  .createSignalEvent("signalName")
  .setVariables(variables)
  .send();

// доставка сигнала конкретному выполнению
runtimeService
  .createSignalEvent("signalName")
  .executionId(executionId)
  .setVariables(variables)
  .send();

Можно также вызвать один из методов RuntimeService:

RuntimeService.signalEventReceived(String signalName);
RuntimeService.signalEventReceived(String signalName, String executionId);

Если указан executionId, сигнал доставляется только этому выполнению. Иначе сигнал рассылается всем подписанным обработчикам (broadcast).

Событие сигнала не коррелирует с конкретным экземпляром процесса, а рассылается всем экземплярам. Если сигнал нужно доставить только одному экземпляру процесса, не используйте BPMN-событие генерации сигнала. Вместо этого выполните корреляцию вручную через запросы и доставьте сигнал нужному выполнению программно.

Поиск подписок на события сигнала

Можно запросить все выполнения, подписанные на определённый сигнал:

List<Execution> executions = runtimeService.createExecutionQuery()
    .signalEventSubscriptionName("alert")
    .list();

Затем этим выполнениям можно доставить сигнал через API сигналов.

Перехват событий сигнала

Стартовое событие сигнала

Стартовое событие сигнала запускает экземпляр процесса именованным сигналом.

При развертывании определения процесса с одним или несколькими стартовыми событиями сигнала действуют правила:

  • Имя сигнала стартового события должно быть уникальным в пределах определения процесса: два стартовых события сигнала с одинаковым именем в одном определении недопустимы. Если несколько стартовых событий сигнала ссылаются на один сигнал или на сигналы с одинаковым именем, движок выбрасывает исключение при развертывании.

  • В отличие от стартовых событий сообщения, имя сигнала стартового события не обязано быть уникальным среди всех развернутых определений процессов.

  • Версионирование процессов: при развертывании новой версии определения процесса подписки на сигналы предыдущей версии отменяются. Это касается и событий сигнала, которых нет в новой версии.

Экземпляр процесса со стартовыми событиями сигнала запускается, когда генерируется сигнал с нужным именем. Сигнал может сгенерировать другой процесс (промежуточным или завершающим событием-генератором сигнала) или приложение методами RuntimeService:

void signalEventReceived(String signalName);
void signalEventReceived(String signalName, Map<String, Object> processVariables);
Один сгенерированный сигнал может запустить несколько экземпляров процессов, если у нескольких определений процессов есть стартовое событие сигнала с одинаковым именем.

В XML стартовое событие сигнала объявляется как обычное стартовое событие с дочерним элементом signalEventDefinition:

<startEvent id="signalStart" >
  <signalEventDefinition signalRef="alertSignal" />
</startEvent>

Промежуточное событие-перехватчик сигнала

Когда токен доходит до промежуточного события-перехватчика сигнала, он ждёт, пока не придёт сигнал с нужным именем.

<intermediateCatchEvent id="signal">
  <signalEventDefinition signalRef="newCustomerSignal" />
</intermediateCatchEvent>

Расширения OpenBPM Engine

Для промежуточного события-перехватчика сигнала поддерживаются следующие расширения:

Атрибуты

Нет

Элементы расширений

Ограничения

Нет

Граничное событие сигнала

Когда выполнение доходит до активити, к которой прикреплено граничное событие сигнала, событие начинает перехватывать сигналы с нужным именем.

В отличие от других событий, например граничного события ошибки, граничное событие сигнала перехватывает сигналы не только из области видимости своей активити. У события сигнала глобальная область видимости (broadcast): сигнал можно сгенерировать откуда угодно, даже из другого экземпляра процесса.
<boundaryEvent id="boundary" attachedToRef="task" cancelActivity="true">
  <signalEventDefinition signalRef="alertSignal"/>
</boundaryEvent>

Генерация событий сигнала

Промежуточное событие-генератор сигнала

Промежуточное событие-генератор сигнала генерирует заданный сигнал.

Сигнал рассылается всем активным обработчикам, то есть всем событиям-перехватчикам сигнала. Сигналы можно публиковать синхронно или асинхронно.

  • По умолчанию сигнал доставляется синхронно: экземпляр процесса, сгенерировавший сигнал, ждёт, пока сигнал будет доставлен всем перехватывающим экземплярам процессов. Перехватывающие экземпляры уведомляются в той же транзакции, что и генерирующий экземпляр. Поэтому если один из уведомлённых экземпляров завершится технической ошибкой (выбросит исключение), ошибкой завершатся все участвующие экземпляры.

  • Сигнал можно доставить и асинхронно. Тогда движок определяет, какие обработчики активны в момент, когда выполнение доходит до события-генератора сигнала. Для каждого активного обработчика сохраняется асинхронное уведомление, задание (job), которое затем выполняет исполнитель заданий (Job Executor).

Промежуточное событие сигнала определяется как промежуточное событие-генератор с элементом signalEventDefinition.

<intermediateThrowEvent id="signal">
  <signalEventDefinition signalRef="newCustomerSignal" />
</intermediateThrowEvent>

Асинхронная генерация сигнала задаётся атрибутом camunda:async элемента signalEventDefinition:

<intermediateThrowEvent id="signal">
  <signalEventDefinition signalRef="newCustomerSignal" camunda:async="true" />
</intermediateThrowEvent>

Завершающее событие сигнала

Завершающее событие сигнала генерирует заданный сигнал и завершает текущий путь выполнения. В остальном оно ведёт себя так же, как промежуточное событие-генератор сигнала.

<endEvent id="signal">
        <signalEventDefinition signalRef="newCustomerSignal" />
</endEvent>

Передача переменных

Переменные процесса можно передать из экземпляра, генерирующего сигнал, во все экземпляры процессов, которые его перехватывают. Данные копируются в перехватывающий экземпляр, когда его запускает стартовое событие сигнала или перед выходом из состояния ожидания в промежуточном событии-перехватчике сигнала.

<signalEventDefinition signalRef="newCustomerSignal">
    <extensionElements>
        <camunda:in source="throwingVariableName" target="catchingVariableName" />
    </extensionElements>
</signalEventDefinition>

Переменные, объявленные в элементах camunda:in, устанавливаются в самой верхней области видимости перехватывающего экземпляра процесса.

Можно также использовать выражения и изменять данные перед передачей в перехватывающие процессы.

<signalEventDefinition signalRef="newCustomerSignal">
    <extensionElements>
        <camunda:in sourceExpression="${X + 5}" target="Y" />
    </extensionElements>
</signalEventDefinition>

Переменная процесса Y в перехватывающих экземплярах получит значение (X + 5), где X это переменная процесса в генерирующем экземпляре.

Можно также передать в перехватывающие процессы все переменные экземпляра, генерирующего сигнал.

<signalEventDefinition signalRef="newCustomerSignal">
    <extensionElements>
        <camunda:in variables="all" />
    </extensionElements>
</signalEventDefinition>

С local="true" передаются только локальные переменные выполнения, на котором работает событие-генератор сигнала. Это переменные, которые можно объявить как входные параметры.

<signalEventDefinition signalRef="newCustomerSignal">
    <extensionElements>
        <camunda:in variables="all" local="true" />
    </extensionElements>
</signalEventDefinition>

Варианты можно сочетать. Например, передать только локальные переменные, одну переменную верхнего уровня и выражение с этой же переменной.

<signalEventDefinition signalRef="newCustomerSignal">
    <extensionElements>
        <camunda:in variables="all" local="true" />
        <camunda:in source="X" target="Y" />
        <camunda:in sourceExpression="${X + 5}" target="Z" />
    </extensionElements>
</signalEventDefinition>

Передача бизнес-ключа

Кроме переменных процесса, в перехватывающие экземпляры можно передать бизнес-ключ (business key). Это работает только для экземпляров процессов, которые запускаются стартовым событием сигнала.

<signalEventDefinition signalRef="newCustomerSignal">
    <extensionElements>
          <camunda:in businessKey="${execution.processBusinessKey}" />
    </extensionElements>
</signalEventDefinition>

Элемент camunda:in для бизнес-ключа можно использовать вместе с элементами camunda:in для переменных процесса.

Расширения OpenBPM Engine

Для промежуточных и завершающих событий-генераторов сигнала поддерживаются следующие расширения:

Атрибуты

camunda:async

Элементы расширений

Ограничения

Нет

Документация создана на основе Camunda 7 Docs (Camunda, docs.camunda.org) и распространяется по лицензии Creative Commons Attribution-ShareAlike 3.0 Unported.