Skip to content

Documentation for Event Sub-processes #10591

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DmytroKost wants to merge 6 commits into
base: development
Choose a base branch
from
Open

Documentation for Event Sub-processes #10591

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7ae456b
Documentation for Event Sub-processes
DmytroKost Jan 13, 2026
7d1fadd
Document new conflict Current Event Sub-Process Removed
DmytroKost Jan 13, 2026
18e602c
Update description for CurrentActivityMovedOutOfPath conflict
DmytroKost Jan 14, 2026
a94b5aa
Review comments
DmytroKost Jan 14, 2026
b16e490
Review comments
DmytroKost Jan 15, 2026
a5b0e96
Update Notify workflow action
DmytroKost Jan 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions ...ogic/microflows-and-nanoflows/activities/workflow-activities/notify-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,30 @@ This activity can only be used in microflows.

## Introduction {#introduction}

The **Notify workflow** activity can be used to notify a [workflow](/refguide/workflows/) that is suspended on the [Wait for notification](/refguide/wait-for-notification/) workflow activity.
The **Notify workflow** activity is used to resume or trigger logic within a [workflow](/refguide/workflows/). It specifically targets two types of elements:

If the workflow is suspended on the specified wait for notification activity, then this activity will return `true` and the workflow execution will continue further. Otherwise, it will simply return `false`.
* A [Wait for Notification](/refguide/wait-for-notification/) workflow activity currently suspended in a flow.
* A [Notification Event Sub-process](/refguide/workflow-event-sub-processes/) defined within the workflow.

When the **Notify workflow** action is executed, the engine checks for an active receiver. If a valid **Wait for Notification** activity or a **Notification Event Sub-process** is found and successfully triggered, the action returns `true`. If no active receiver is found, it returns `false`.

{{% alert color="warning" %}}
When you try to notify a workflow which is already `Completed` or `Aborted`, it will result in a Runtime error. For information on how to handle the error, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/).
Attempting to notify a workflow that is already `Completed` or `Aborted` will result in a runtime error. For information on how to handle these cases, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/).
{{% /alert %}}

### Execution Behavior

The table below describes how the workflow engine responds when a **Notify workflow** action is called, depending on the state of the workflow and the type of receiver configured.

| Workflow/Element State | Action Result | System Behavior |
|-------------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Aborted or Completed | Error | The action fails. An error is logged indicating the workflow is no longer in an active state and cannot be notified. |
| Paused, Failed, or Incompatible | True | The notification is accepted and "queued." The targeted activity or **Event Sub-process** will trigger automatically once the workflow is resumed or resolved. |
| **Wait for Notification** (Active) | True | The workflow resumes execution from the point of the **Wait for Notification** activity. |
| **Event Sub-process** (Inactive) | True | The **Event Sub-process** is triggered immediately and its execution path begins. |
| **Event Sub-process** (In Progress) | False | The notification is ignored because an instance of this specific sub-process is already running. No new instance is created. |
| No matching receiver | False | If the workflow is active but does not contain the specified **Wait for Notification** activity or **Event Sub-process**, the action returns `false`. |

## Properties

An example of **Notify workflow** properties is represented in the image below:
Expand Down
182 changes: 182 additions & 0 deletions ...nt/en/docs/refguide/modeling/application-logic/workflows/event-sub-processes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
---
title: "Event Sub-Processes"
url: /refguide/workflow-event-sub-processes/
weight: 20
---

## Introduction

An Event Sub-process is a separate execution flow that is not part of the normal sequence flow of its workflow. It resides inside the workflow and starts executing upon receiving a specific trigger.
It is crucial to understand that an Event Sub-process is part of the same workflow instance. It is not a "separate" workflow; rather, a single workflow instance can contain multiple concurrent processes.

Below is an example of what an Event Sub-process looks like:

{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/event-sub-process-example.png" alt="Event Sub-process example" width="400" >}}

### When to Use Event Sub-Processes

An Event Sub-process is like a Boundary Event, with the exception that an Event Sub-process can start at any time, whereas a Boundary Event can start only while the activity it is attached to is active.
Choosing between a Boundary Event and an Event Sub-process is a common architectural crossroads.
Copy link
Contributor

@hugomendix hugomendix Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe you could add a bit of introduction here:

"An Event Sub-Process is like a Boundary Event, with the exception that an Event Sub-Process can start at any time, whereas a Boundary Event can start only while the activity it is attached to is active."

Copy link
Contributor Author

@DmytroKost DmytroKost Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added


#### Ideal Use Cases

- **Global Exception Handling** – Handling errors or cancellations that could occur at any point during the workflow execution.
- **Isolated Logic** – Complex steps triggered by a specific event (e.g., "Change of Address") without cluttering the main flow.
- **Inline Updates** – Updating data in a long-running process without interrupting the primary state of the workflow.

#### When NOT to Use

- **Sequential Logic** – If the logic must happen after a specific task, use a standard sequence flow.
- **Conditional Logic Based on Activity State** – You may want to execute a flow only if a certain condition is met while a specific activity is active. A **Boundary Event** should be used here because it is triggered only if the activity it is attached to is active.
- **Returning to a Specific Point** – If you need to abort a specific task execution and resume it later, a **Boundary Event (Interrupting)** is often more appropriate. Once the event is triggered, the **Boundary Event** can utilize a **Jump activity** to return to the original task.

### How Event Sub-Processes Work

#### Lifecycle

The Event Sub-process is initialized (but not started) as soon as the main process starts and remains in a waiting state until a notification is received.

{{% alert color="info" %}}
**What keeps a workflow In Progress?** A workflow instance remains in the **In Progress** state as long as **at least one** of the following is true:
- The Main Process path has not yet reached its End Event.
- Any Event Sub-Process that was started has not yet reached its End Event.
{{% /alert %}}

The workflow will **not** complete until all active execution paths, both the main flow and any triggered event sub-processes, have reached their respective End Events.

#### Triggers and Notifications

Event Sub-processes are triggered by a **Notify Workflow** microflow action. When the trigger is received, the sub-process becomes **In Progress**.

#### Interrupting vs. Non-Interrupting

- **Interrupting (Solid line)** – Immediately cancels the main process flow.
- **Non-Interrupting (Dashed line)** – Runs in parallel with the main flow.

{{% alert color="warning" %}}
Currently, Mendix only supports the Non-interrupting variant of Event Sub-processes. Support for Interrupting Event Sub-processes is planned for a future release.
{{% /alert %}}

#### Concurrency Limitation

Mendix Workflows currently support a **single concurrent instance** per defined Event Sub-process. If a non-interrupting Event Sub-process is already active, subsequent attempts to trigger that same sub-process via the **Notify Workflow** action will return false. No new instances will be created for that specific sub-process while one is In Progress. A new instance can only be initiated once the active sub-process has completed its execution path.

If your workflow has multiple, distinct Event Sub-processes defined (e.g., one for "Address Change" and one for "Document Upload"), each one can have its own active instance simultaneously. One being active does not prevent a different one from being triggered.

## Getting started

### Adding Event Sub-Processes

To add an Event Sub-process to a workflow, follow these steps:

* Select an Event Sub-process from the **Sub-processes** section in the workflow **Toolbox**.

* Drag it onto a dashed drop zone adjacent to the main workflow process.

{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/drag-and-drop.png" alt="Add Event Sub-process example" width="500" >}}

* The sub-process flow will be contained within a dashed rectangle. This dashed border around the sub-process start event indicates that it is a non-interrupting sub-process.

* The flow can contain the same types of activities as the main process flow (e.g., **User Task**, **Call Microflow**, **Decision**).

* It must start with a **Start Event** (triggered by a notification) and end with at least one **End Event**.

## Execution

To start an Event Sub-process create a **Notify Workflow** microflow action and point it to the Event Sub-process start event.

{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/notify-workflow.png" alt="Notify workflow example" width="400" >}}

### Operational Lifecycle Management

An Event Sub-process is bound to the lifecycle of its parent workflow instance. Administrative actions and system-level events (such as errors or version conflicts) directly impact the execution state of active sub-processes.

The following table outlines how top-level workflow operations and system states affect any Event Sub-process currently In Progress:

| Event or Operation | Effect on Event Sub-process | System Behavior |
|---------------------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Abort Workflow | Aborted | The sub-process is permanently stopped and cannot be re-notified. |
| Restart Workflow | Aborted & Reset | The active sub-process instance is aborted. It returns to a waiting state and can be notified again. |
Copy link
Contributor

@hugomendix hugomendix Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider not using the word "notified" in this page, which is about event sub-processes. Notifying is only applicable to the type of event sub-process that we're implementing currently. In the future we might have other types, for which notifying is not applicable. Possibly using the term "start" is more future proof.

Copy link
Contributor Author

@DmytroKost DmytroKost Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see your point, using 'start' would be more future-proof as we expand the platform. My thinking for this specific version was to lean into 'notified' since it’s the only mechanism available to users today. I wanted to make the documentation as concrete as possible for the current release. However, once we introduce the Timer Start Event, we will update the terminology across the board.

Copy link
Contributor

@hugomendix hugomendix Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright, as long as we don't forget to do that...

| Pause Workflow | Execution Halted | Execution of the sub-process halts immediately. Logic resumes from the same point once the workflow is Unpaused. |
| Workflow Incompatible | Execution Halted | The sub-process is "frozen" due to a version conflict. Execution resumes from the current point once the conflict is Resolved. |
| Error Inside Sub-process | Failed | The sub-process activity enters a Failed state. After the issue is fixed and the workflow is Retried, the sub-process resumes from the failed activity. |
| Error Outside Sub-process | Execution Halted | If a failure occurs elsewhere in the workflow, the healthy sub-process stops processing. It resumes once the error is fixed and the workflow is Retried. |

## Jump Rules

Event Sub-processes have specific restrictions regarding [Jump activity](/refguide/jump-activity/) and [Jump to](/refguide/jump-to/):

* **Between Processes**: It is not possible to jump into a sub-process from the main process (or vice versa), nor between different sub-processes.
* **Within a Sub-process**: Jumps within the same sub-process are permitted.
* **Jump to Start Event**: Aborts the current sub-process instance and returns it to a waiting state.
* **Jump to End Event**: Completes the sub-process instance immediately.

## Domain Model Structure

To provide comprehensive monitoring, management, and auditing capabilities, the Mendix Workflow engine utilizes specific system entities and associations. These ensure that every Event Sub-process instance is traceable back to its definition and correctly linked to the overall workflow lifecycle.

### WorkflowSubProcessDefinition

The `WorkflowSubProcessDefinition` entity represents the metadata of a Sub-process as defined in the workflow model.

{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/domain-model/workflow-sub-process-definition.png" class="no-border" >}}

#### Attributes

| Attribute | Type | Description |
|--------------|---------|-------------------------------------------------------------------------------|
| `Caption` | String | The caption of the sub-process. |
| `IsObsolete` | Boolean | Set to `true` if the sub-process has been deleted from the application model. |

#### Associations

| Association | Parent Entity | Description |
|-----------------------------------------------------------|--------------------------------|-------------------------------------------------------------------------|
| `WorkflowSubProcessDefinition_WorkflowDefinition` | `WorkflowSubProcessDefinition` | Link to the parent workflow definition. |
| `WorkflowUserTaskDefinition_WorkflowSubProcessDefinition` | `WorkflowUserTaskDefinition` | Links user task definitions to their containing sub-process definition. |
| `WorkflowActivityRecord_WorkflowSubProcessDefinition` | `WorkflowActivityRecord` | Links historical activity records to the sub-process definition. |

### WorkflowSubProcess

The `WorkflowSubProcess` entity represents a specific runtime instance of an Event Sub-process. A `WorkflowSubProcess` object is created only after an Event Sub-process is notified and started its execution.

{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/domain-model/workflow-sub-process.png" class="no-border" >}}

#### Attributes

| Attribute | Type | Description |
|-------------|--------------------|--------------------------------------------------------------------------------------------------------------------------------|
| `Caption` | String | The caption of the sub-process instance. |
| `StartTime` | DateTime | The timestamp when execution began. This is set by the engine and is read-only. |
| `EndTime` | DateTime | The timestamp when execution ended (either through completion or failure). This is set by the engine and is read-only. |
| `State` | Enumeration | The current lifecycle state of the sub-process instance (see [WorkflowSubProcessState](#workflowsubprocessstate-enumeration)). |
| `Reason` | String (Unlimited) | A technical description providing context for the current state (e.g., error details). |

#### Associations

| Association | Parent Entity | Description |
|---------------------------------------------------|---------------------------|--------------------------------------------------------------------------------------------------------------------|
| `WorkflowSubProcess_WorkflowSubProcessDefinition` | `WorkflowSubProcess` | The association to the underlying definition for this instance. |
| `WorkflowSubProcess_Workflow` | `WorkflowSubProcess` | The association to the parent workflow instance. |
| `WorkflowUserTask_WorkflowSubProcess` | `WorkflowUserTask` | The association to active user tasks within this sub-process instance. |
| `WorkflowEndedUserTask_WorkflowSubProcess` | `WorkflowEndedUserTask` | The association to completed or ended user tasks within this instance. |
| `WorkflowActivityRecord_WorkflowSubProcess` | `WorkflowActivityRecord` | The association to the historical execution records for this instance. |
| `WorkflowCurrentActivity_WorkflowSubProcess` | `WorkflowCurrentActivity` | The association to the activities currently being executed in this sub-process (see [Jump to](/refguide/jump-to/). |

### WorkflowSubProcessState (Enumeration)

The `WorkflowSubProcessState` enumeration defines the possible lifecycle phases of a sub-process instance:

| Caption | Name | Description |
|-------------|--------------|-----------------------------------------------------------------------------------------------------------|
| In progress | `InProgress` | The sub-process has been triggered and is currently executing. |
| Aborted | `Aborted` | Execution was terminated, either because the parent workflow was aborted or due to an interrupting event. |
| Failed | `Failed` | Execution ended unsuccessfully because an activity within the sub-process encountered an error. |
| Completed | `Completed` | The sub-process reached its end event and finished successfully. |

## Read more

* [Notify Workflow](/refguide/notify-workflow/)
* [Workflow Versioning and Conflict Mitigation](/refguide/workflow-versioning/)
* [Jump activity](/refguide/jump-activity/)
* [Jump to](/refguide/jump-to/)
Loading