WOR-3087 - Update documentations

content/en/docs/refguide/modeling/app-explorer/app/app-settings/workflow-tab.md

@@ -17,6 +17,8 @@ Configure workflow-specific settings for your app in the Workflow tab.
 
 **Workflow group(s)** defines groups of users for [user task targeting](/refguide/user-task/#workflow-group). When users are added or removed from the group, the targeted users of a user task change accordingly. For more information, see [Workflow Groups](/refguide/workflow-groups/).
 
+**Group definition** defines where workflow groups are created and managed. When set to **Studio Pro** (default), groups are defined in this tab and synchronized to the database on deployment. When set to **Runtime**, administrators create and delete groups in the running app without redeployment. For more information, see the [Group Definition](/refguide/workflow-groups/#group-definition) section in *Workflow Groups*.
+
 ### Optimization
 
 This section allows you to configure the maximum number of workflow and microflow threads that can be executed simultaneously by the Runtime. This is an advanced setting that gives developers control over app performance. Change these settings when you face performance issues on executing workflow instances or workflow-initiated microflows. The two values in this field indicate the amount of threads that process the queues containing workflow instances or workflow-initiated microflows. For more information, see the [Workflow Instance Threads](#workflow-instance-threads) and [Microflow Threads](#microflow-threads) sections below. 

content/en/docs/refguide/modeling/application-logic/workflows/workflow-groups.md

@@ -2,6 +2,8 @@
 title: "Workflow Groups"
 url: /refguide/workflow-groups/
 weight: 40
+description: "Describes how to define and manage workflow groups."
+
 ---
 
 ## Introduction
@@ -18,27 +20,60 @@ The advantage of targeting users through groups is that it is a dynamic concept:
 
 To configure workflow groups, open **App** > **Settings** and select the **Workflow** tab:
 
-{{< figure src="/attachments/refguide/modeling/application-logic/workflows/workflow-groups/workflow-groups-config.png" >}}
+{{< figure src="/attachments/refguide/modeling/application-logic/workflows/workflow-groups/workflow-groups-config.png" alt="The Workflow tab of the App Settings dialog with Group definition set to Studio Pro and a Managers group listed in the workflow groups table">}}
+
+### Group Definition {#group-definition}
+
+{{% alert color="info" %}}
+The **Group definition** setting was introduced in Studio Pro 11.16.0. In earlier versions, workflow groups are always defined in Studio Pro.
+{{% /alert %}}
+
+The **Group definition** setting determines where workflow groups are created and managed. It has the following options:
 
-A Workflow group can be defined with the following properties:
+* **Studio Pro** (default) – Workflow groups are defined in the app settings in Studio Pro and are synchronized to the database when the app is (re)deployed. For more information, see [Defining Groups in Studio Pro](#studio-pro-groups).
+* **Runtime** – Workflow groups are created and deleted by administrators in the running app, for example, by using the [Workflow Commons](/appstore/modules/workflow-commons/) module. Adding or removing a group does not require a redeployment. In this mode, groups are not defined in Studio Pro. For more information, see [Managing Groups at Runtime](#runtime-groups).
+
+When you change this setting, Studio Pro asks you to confirm the change because it can affect existing groups and XPath constraints. For more information, see [Changing the Group Definition](#changing-group-definition).
+
+### Defining Groups in Studio Pro {#studio-pro-groups}
+
+When **Group definition** is set to **Studio Pro**, a workflow group can be defined with the following properties:
 
 * **Name**: The name of the group. It must be unique. The name can only contain letters, digits and underscores, and cannot start with a digit. 
 * **Documentation**: A description of the group. The description can contain any free-form text.
 
+### Managing Groups at Runtime {#runtime-groups}
+
+When **Group definition** is set to **Runtime**, the list of workflow groups is not shown in the app settings:
+
+{{< figure src="/attachments/refguide/modeling/application-logic/workflows/workflow-groups/workflow-groups-config-runtime.png" alt="The Workflow tab of the App Settings dialog with Group definition set to Runtime and no workflow groups table">}}
+
+Instead, administrators create, edit, and delete workflow groups in the running app. This is useful when the set of groups is not known at design time, or when it changes frequently and you do not want to redeploy the app for every change.
+
+In this mode, the app does not synchronize workflow groups on (re)deployment. Groups in the database are neither updated nor removed on start-up.
+
+The [Workflow Commons](/appstore/modules/workflow-commons/) module provides default pages to manage workflow groups at runtime. You can also build your own pages and microflows that create, change, and delete **System.WorkflowGroup** objects.
+
 ## The System.WorkflowGroup Entity
 
-The **System.WorkflowGroup** entity represents the defined workflow groups in the database. It has the following attributes and association:
+The **System.WorkflowGroup** entity represents the workflow groups in the database. It has the following attributes and association:
 
 * **Name**: The name of the workflow group.
 * **Description**: The description of the workflow group.
 * **WorkflowGroup_User**: The users that are part of the workflow group. The multiplicity is a many-to-many association.
 
-Each defined workflow group corresponds to one **System.WorkflowGroup** object.
+Each workflow group corresponds to one **System.WorkflowGroup** object.
 
-The **Name** attribute of the **System.WorkflowGroup** object matches the **Name** property of the workflow group, and the **Description** attribute matches the **Documentation** property of the workflow group.
+When **Group definition** is set to **Studio Pro**, the **Name** attribute of the **System.WorkflowGroup** object matches the **Name** property of the workflow group, and the **Description** attribute matches the **Documentation** property of the workflow group.
+
+When **Group definition** is set to **Runtime**, administrators create, change, and delete **System.WorkflowGroup** objects in the running app.
 
 ### Synchronization
 
+{{% alert color="info" %}}
+Synchronization only applies when **Group definition** is set to **Studio Pro**. When it is set to **Runtime**, workflow groups are not synchronized.
+{{% /alert %}}
+
 Changes to workflow group properties are automatically synchronized to the database, when the app is (re)deployed. When the properties (that is, the name and the documentation) of an existing workflow group are changed, the attributes of the corresponding object in the database are also updated.
 
 {{% alert color="warning" %}}
@@ -57,12 +92,58 @@ This is done by setting the **WorkflowGroup_User** association between the **Sys
 
 ## Using Workflow Groups in XPath
 
+### XPath Tokens
+
+{{% alert color="info" %}}
+XPath tokens for workflow groups are only available when **Group definition** is set to **Studio Pro**.
+{{% /alert %}}
+
 For each workflow group that is defined in app settings, an XPath token is defined, which you can use to select the group.
 
 For instance, to select a workflow group called *Managers*, you can use the following XPath constraint:
 
 ```[ id = '[%WorkflowGroup_Managers%]' ]```
 
-Mendix does not recommend to use the following, because it will NOT be updated automatically when a workflow group is renamed:
+Mendix recommends against using the following when **Group definition** is set to **Studio Pro**, because it will NOT be updated automatically when a workflow group is renamed:
 
 ```[ Name = 'Managers' ]```
+
+### Selecting Groups in Runtime Mode {#selecting-groups-in-runtime-mode}
+
+When **Group definition** is set to **Runtime**, workflow groups are not known at design time, so no XPath tokens are defined for them. Using a workflow group token, such as `[%WorkflowGroup_Managers%]`, results in a consistency error.
+
+Instead, select the group by its **Name** attribute:
+
+```[ Name = 'Managers' ]```
+
+For XPath constraints in [user task targeting](/refguide/user-task/#workflow-group), Studio Pro offers a quick fix for this consistency error. Right-click the error in the **Errors** pane and select **Convert group targeting to attribute targeting**. This replaces each token comparison, such as `id = '[%WorkflowGroup_Managers%]'`, with the corresponding comparison on the **Name** attribute, such as `Name = 'Managers'`.
+
+{{% alert color="warning" %}}
+Selecting a group by name depends on the group name in the database. If an administrator renames or deletes the group at runtime, the XPath constraint no longer selects it.
+{{% /alert %}}
+
+## Changing the Group Definition {#changing-group-definition}
+
+You can change the **Group definition** setting at any time, but the change has consequences for existing groups and XPath constraints. Studio Pro shows a confirmation dialog that describes these consequences before applying the change.
+
+### From Studio Pro to Runtime
+
+When you switch from **Studio Pro** to **Runtime**, the following happens:
+
+* The workflow groups defined in the app settings are removed from the model.
+* The existing **System.WorkflowGroup** objects in the database, including their user memberships, are preserved. Studio Pro no longer manages them. They are not updated or removed on (re)deployment, and you must manage them at runtime.
+* XPath constraints that use workflow group tokens, such as `[%WorkflowGroup_Managers%]`, result in consistency errors. Replace them with constraints on the **Name** attribute, as described in [Selecting Groups in Runtime Mode](#selecting-groups-in-runtime-mode).
+
+If no workflow groups are defined in the app settings, Studio Pro switches to **Runtime** without asking for confirmation.
+
+### From Runtime to Studio Pro
+
+When you switch from **Runtime** to **Studio Pro**, Studio Pro manages the workflow groups again and synchronizes them on the next (re)deployment.
+
+{{% alert color="warning" %}}
+On the next deployment, every workflow group in the database that is not defined in the app settings in Studio Pro is permanently deleted, including all its user memberships. This cannot be undone.
+
+To preserve an existing group, define it in the app settings in Studio Pro before you deploy. The **Name** of the group in Studio Pro must exactly match the **Name** attribute of the group in the database.
+
+Mendix strongly recommends testing this change in a non-production environment before you deploy it to production.
+{{% /alert %}}