Skip to content

Commit 0cd43a2

Browse files
Yiyun333Yiyun333
authored
Merge pull request mendix#10591 from DmytroKost/wor/event-sub-processes
Documentation for Event Sub-processes
2 parents d479e14 + 539e7db commit 0cd43a2

9 files changed

Lines changed: 243 additions & 21 deletions

File tree

‎content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/workflow-activities/notify-workflow.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,30 @@ This activity can only be used in microflows.
1111

1212
## Introduction {#introduction}
1313

14-
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.
14+
The **Notify workflow** activity is used to resume or trigger logic within a [workflow](/refguide/workflows/). It specifically targets two types of elements:
1515

16-
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`.
16+
* A [Wait for notification](/refguide/wait-for-notification/) workflow activity currently suspended in a flow.
17+
* A [Notification event sub-process](/refguide/workflow-event-sub-processes/) defined within the workflow.
18+
19+
When the **Notify workflow** activity is executed, the Workflow 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 activity returns `true`. If no active receiver is found, it returns `false`.
1720

1821
{{% alert color="warning" %}}
19-
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/).
22+
Attempting to notify a workflow that is already `Completed` or `Aborted` results in a runtime error. For information on how to handle these cases, see [Error Handling in Microflows](/refguide/error-handling-in-microflows/).
2023
{{% /alert %}}
2124

25+
### Execution Behavior
26+
27+
The table below describes how the Workflow Engine responds when a **Notify workflow** activity is called, depending on the state of the workflow and the type of receiver configured.
28+
29+
| Workflow/Element State | Action Result | System Behavior |
30+
| --- | --- | --- |
31+
| Aborted or Completed | Error | The activity fails. An error is logged indicating the workflow is no longer in an active state and cannot be notified. |
32+
| Paused, Failed, or Incompatible | True | The notification is accepted and "queued." The targeted activity or event sub-process is triggered automatically once the workflow is resumed or resolved. |
33+
| Wait for notification (Active) | True | The workflow resumes execution from the point of the **Wait for notification** activity. |
34+
| Event sub-process (Inactive) | True | The event sub-process is triggered immediately and its execution path begins. |
35+
| 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. |
36+
| No matching receiver | False | If the workflow is active but does not contain the specified **Wait for notification** activity or **Event sub-process**, the activity returns `false`. |
37+
2238
## Properties
2339

2440
An example of **Notify workflow** properties is represented in the image below:

‎content/en/docs/refguide/modeling/application-logic/workflows/event-sub-processes.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: "Event Sub-Processes"
3+
url: /refguide/workflow-event-sub-processes/
4+
weight: 20
5+
---
6+
7+
## Introduction
8+
9+
{{% alert color="info" %}}
10+
This feature was released in beta in Studio Pro 11.8.0. To enable this feature, navigate to Studio Pro **Preferences** > **New features** > the **Workflow** section and select the **Enable workflow event sub-processes (beta)** option.
11+
{{% /alert %}}
12+
13+
An event sub-process is a separate execution flow that is not part of the normal sequence flow of a 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 but a single workflow instance that can contain multiple concurrent processes.
14+
15+
Below is an example of an event sub-process, shown inside the dashed rectangle:
16+
17+
{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/event-sub-process-example.png" alt="Event sub-process example" width="400" >}}
18+
19+
### When to Use Event Sub-Processes
20+
21+
An event sub-process is similar to a [boundary event](/refguide/workflow-boundary-events/), 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.
22+
23+
#### Ideal Use Cases
24+
25+
Event sub-processes are particularly useful in the following scenarios:
26+
27+
* **Global exception handling** – Handling errors or cancellations that could occur at any point during the workflow execution.
28+
* **Isolated logic** – Handling complex steps triggered by a specific event (for example, "Change of Address") without cluttering the main flow.
29+
* **Inline updates** – Updating data in a long-running process without interrupting the primary state of the workflow.
30+
31+
### When Not to Use Event Sub-Processes
32+
33+
* **Sequential logic** – If the logic must happen after a specific task, use a standard sequence flow.
34+
* **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.
35+
* **Returning to a specific point** – If you need to abort a specific task execution and resume it later, an interrupting boundary event is often more appropriate. Once the event is triggered, the boundary event can utilize a **Jump** activity to return to the original task.
36+
37+
### How Event Sub-Processes Work
38+
39+
#### Lifecycle
40+
41+
An 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.
42+
43+
{{% alert color="info" %}}
44+
A workflow instance remains **In Progress** as long as at least ONE of the following conditions is met:
45+
46+
* The main process path has not yet reached its end event.
47+
* Any event sub-process that was started has not yet reached its end event.
48+
{{% /alert %}}
49+
50+
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.
51+
52+
#### Triggers and Notifications
53+
54+
Event sub-processes are triggered by a [Notify workflow](/refguide/notify-workflow/) microflow activity. When the trigger is received, the sub-process becomes **In Progress**.
55+
56+
#### Interrupting vs. Non-Interrupting
57+
58+
Event sub-processes can be configured as either interrupting or non-interrupting, depending on how they interact with the main process flow.
59+
60+
* **Interrupting (solid line)** – Immediately cancels the main process flow.
61+
* **Non-Interrupting (dashed line)** – Runs in parallel with the main flow.
62+
63+
{{% alert color="info" %}}
64+
Currently, Mendix only supports the non-interrupting variant of event sub-processes. Support for interrupting event sub-processes is planned for a future release.
65+
{{% /alert %}}
66+
67+
#### Concurrency Limitation
68+
69+
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** activity 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.
70+
71+
If your workflow has multiple, distinct event sub-processes defined (for example, 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.
72+
73+
## Getting started
74+
75+
### Adding Event Sub-Processes
76+
77+
To add an **Event sub-process** to a workflow, follow these steps:
78+
79+
* Select an event sub-process from the **Sub-processes** section in the workflow **Toolbox**.
80+
* Drag it onto a dashed drop zone adjacent to the main workflow process.
81+
82+
{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/drag-and-drop.png" alt="Add Event sub-process example" width="500" >}}
83+
84+
* The sub-process flow is contained within a dashed rectangle. This dashed border around the sub-process start event indicates that it is a non-interrupting sub-process.
85+
* The flow can contain the same types of activities as the main process flow (for example, **User Task**, **Call Microflow**, **Decision**).
86+
* It must start with a **Start** event (triggered by a notification) and end with at least one **End** event.
87+
88+
## Execution
89+
90+
To start an event sub-process, create a **Notify workflow** microflow activity and point it to the event sub-process start event.
91+
92+
{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/notify-workflow.png" alt="Notify workflow example" width="400" >}}
93+
94+
### Operational Lifecycle Management
95+
96+
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.
97+
98+
The following table outlines how top-level workflow operations and system states affect any event sub-process that is currently **In Progress**:
99+
100+
| Event or Operation | Effect on Event Sub-Process | System Behavior |
101+
| --- | --- | --- |
102+
| Abort Workflow | Aborted | The sub-process is permanently stopped and cannot be re-notified. |
103+
| Restart Workflow | Aborted and Reset | The active sub-process instance is aborted. It returns to a waiting state and can be notified again. |
104+
| Pause Workflow | Execution Halted | Execution of the sub-process halts immediately. Logic resumes from the same point once the workflow is Unpaused. |
105+
| 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. |
106+
| 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. |
107+
| 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. |
108+
109+
## Jump Rules
110+
111+
Event sub-processes have specific restrictions regarding [Jump activity](/refguide/jump-activity/) and [Jump to](/refguide/jump-to/):
112+
113+
* Between processes: It is not possible to jump into a sub-process from the main process (or vice versa), nor between different sub-processes.
114+
* Within a sub-process: Jumps within the same sub-process are permitted.
115+
* **Jump to Start Event**: Aborts the current sub-process instance and returns it to a waiting state.
116+
* **Jump to End Event**: Completes the sub-process instance immediately.
117+
118+
## Domain Model Structure
119+
120+
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.
121+
122+
### WorkflowSubProcessDefinition
123+
124+
The `WorkflowSubProcessDefinition` entity represents the metadata of a sub-process as defined in the workflow model.
125+
126+
{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/domain-model/workflow-sub-process-definition.png" class="no-border" >}}
127+
128+
#### Attributes
129+
130+
| Attribute | Type | Description |
131+
|--------------|---------|-------------------------------------------------------------------------------|
132+
| `Caption` | String | The caption of the sub-process. |
133+
| `IsObsolete` | Boolean | Set to `true` if the sub-process has been deleted from the application model. |
134+
135+
#### Associations
136+
137+
| Association | Parent Entity | Description |
138+
| --- | --- | --- |
139+
| `WorkflowSubProcessDefinition_WorkflowDefinition` | `WorkflowSubProcessDefinition` | Links to the parent workflow definition. |
140+
| `WorkflowUserTaskDefinition_WorkflowSubProcessDefinition` | `WorkflowUserTaskDefinition` | Links user task definitions to their containing sub-process definition. |
141+
| `WorkflowActivityRecord_WorkflowSubProcessDefinition` | `WorkflowActivityRecord` | Links historical activity records to the sub-process definition. |
142+
143+
### WorkflowSubProcess
144+
145+
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.
146+
147+
{{< figure src="/attachments/refguide/modeling/application-logic/workflows/event-sub-processes/domain-model/workflow-sub-process.png" class="no-border" >}}
148+
149+
#### Attributes
150+
151+
| Attribute | Type | Description |
152+
| --- | --- | --- |
153+
| `Caption` | String | The caption of the sub-process instance. |
154+
| `StartTime` | DateTime | The timestamp when execution begins. This is set by the Engine and is read-only. |
155+
| `EndTime` | DateTime | The timestamp when execution ends (either through completion or failure). This is set by the Engine and is read-only. |
156+
| `State` | Enumeration | The current lifecycle state of the sub-process instance (see [WorkflowSubProcessState](#workflowsubprocessstate-enumeration)). |
157+
| `Reason` | String (Unlimited) | A technical description providing context for the current state (for example, error details). |
158+
159+
#### Associations
160+
161+
| Association | Parent Entity | Description |
162+
| --- | --- | --- |
163+
| `WorkflowSubProcess_WorkflowSubProcessDefinition` | `WorkflowSubProcess` | The association to the underlying definition for this instance. |
164+
| `WorkflowSubProcess_Workflow` | `WorkflowSubProcess` | The association to the parent workflow instance. |
165+
| `WorkflowUserTask_WorkflowSubProcess` | `WorkflowUserTask` | The association to active user tasks within this sub-process instance. |
166+
| `WorkflowEndedUserTask_WorkflowSubProcess` | `WorkflowEndedUserTask` | The association to completed or ended user tasks within this instance. |
167+
| `WorkflowActivityRecord_WorkflowSubProcess` | `WorkflowActivityRecord` | The association to the historical execution records for this instance. |
168+
| `WorkflowCurrentActivity_WorkflowSubProcess` | `WorkflowCurrentActivity` | The association to the activities currently being executed in this sub-process (see [Jump to](/refguide/jump-to/)). |
169+
170+
### WorkflowSubProcessState (Enumeration)
171+
172+
The `WorkflowSubProcessState` enumeration defines the possible lifecycle phases of a sub-process instance:
173+
174+
| Caption | Name | Description |
175+
|-------------|--------------|-----------------------------------------------------------------------------------------------------------|
176+
| In progress | `InProgress` | The sub-process has been triggered and is currently executing. |
177+
| Aborted | `Aborted` | Execution was terminated, either because the parent workflow was aborted or due to an interrupting event. |
178+
| Failed | `Failed` | Execution ended unsuccessfully because an activity within the sub-process encountered an error. |
179+
| Completed | `Completed` | The sub-process reached its end event and finished successfully. |
180+
| Paused | `Paused` | The sub-process was paused because the parent workflow was paused. |
181+
182+
## Read more
183+
184+
* [Notify Workflow](/refguide/notify-workflow/)
185+
* [Workflow Versioning and Conflict Mitigation](/refguide/workflow-versioning/)
186+
* [Jump activity](/refguide/jump-activity/)
187+
* [Jump to](/refguide/jump-to/)

0 commit comments

Comments
 (0)