Real-Time Notifications via BPMN Events

The Mechanism

Stateway delivers real-time push notifications to the frontend through Intermediate Message Throw Events in your BPMN diagram. When the process reaches one of these elements, the SDK emits a notification event with the element's name as the message.

No additional Stateway configuration is needed — the behavior is derived directly from the diagram.

How to Add to Your Diagram

In your BPMN modeler, insert an Intermediate Throw Event of type Message at the point in the flow where you want to notify the user. Give the element a descriptive name — that name becomes the message received by the frontend.

[Submit Request] ──→ [Analyze Credit] ──→ (✉ Analysis complete) ──→ [Sign Contract]
   userTask              serviceTask        intermediateThrowEvent      userTask

Receiving in the SDK

sw.on('notification', ({ message, variables }) => {
  // message: "Analysis complete"
  showToast(message);
});

// When the next human task arrives:
sw.on('task.assigned', (task) => {
  hideSpinner();
  renderTaskForm(task);
});

Including Data in Notifications

By default, notifications include no variables. To include process data, declare stateway:variableFilter in the element's extensionElements:

<bpmn:intermediateThrowEvent id="notify_analysis" name="Analysis complete">
  <bpmn:extensionElements>
    <stateway:variableFilter variables="creditScore,approvedLimit" />
  </bpmn:extensionElements>
  <bpmn:messageEventDefinition messageRef="msg_analysis_done" />
</bpmn:intermediateThrowEvent>

sw.on('notification', ({ message, variables }) => {
  // message: "Analysis complete"
  // variables: { creditScore: 720, approvedLimit: 50000 }
  showToast(`${message}. Score: ${variables.creditScore}`);
});

Feedback on Automatic Steps

The most common pattern is using notifications to provide feedback while automatic steps (service tasks, timers) run between two human tasks:

sw.on('task.completed', ({ next }) => {
  if (next.kind === 'automatic') {
    showSpinner(`Processing: ${next.elementName}...`);
  }
  if (next.kind === 'timer') {
    showCountdown('Next step in', next.estimatedFireAt);
  }
});

sw.on('notification', ({ message }) => {
  hideSpinner();
  showToast(message);
  // task.assigned arrives next with the next human task
});

Naming Recommendations

Name elements for the end user, not the technical process:

❌ Avoid	✅ Prefer
invoke_erp_callback	Order registered in system
payment_service_response	Payment confirmed
notify_step_3_complete	Proposal sent to client

Limitations

Only Intermediate Throw Events of type Message generate WebSocket push. Signal, Escalation, and Compensation events are not intercepted by the Gateway. The element must be in a flow associated with the connected user's instance.