8.2 Workflows

Latest revision as of 15:52, 30 January 2024

Introduction

In BlueSpice 4.1, workflows are based on BPMN 2.0. Four different types of page-based workflows are already integrated. Their purpose is a page review to obtain feedback via a user vote or to trigger a page approval. In the following, these workflows are therefore called review workflows.

Types of reviews
Workflow type	Participants	Description
Single user approval	1 user	A single user is asked to vote about a page. If a user submits a positive vote, the page is automatically approved.
Expert document control	3 users	After a page has been edited by a specific user, the page is reviewed by an expert and then approved by a user who is responsible for approvals.
Group feedback	1 group	A group (which needs to exist in the group manager) is requested to leave a comment on a page.
Single user feedback	1 user	A user is asked to send a comment regarding a page.

Workflow activities

All approval workflows start with a form where the necessary workflow data is entered by the workflow initiator. Each workflow results in one or more workflow activities.

Single user approval

Purpose: Approval of a draft page by a user with approval rights. This workflow only makes sense if the approval function (FlaggedRevs) is activated on a page.

Workflow instances: Only one approval workflow can run per page.

BPMN diagram of a "Single user approval" workflow

Activity	Description
CollectData	In the first workflow step, the workflow initiator enters the settings: User: ser who is assigned to the task. Instructions: A comment or instructions for the user to understand the task. Send report to: An email report with the results will be sent to this email address when the review is finished. If a username is specified here, an email address must be stored in the user administration so that the report can be sent.
PageCheckout	The page is locked for editing. The reviewer also cannot make any edits.
UserVote	The assigned user carries out a vote and either accepts the page or rejects it. Alternatively, the task can be delegated. In the event of a rejection, the workflow skips the next step (ApprovePage). The workflow initiator gets an email about the voting result.
ApprovePage	Only if the user has submitted a positive vote (accept), the page is set to an approved state.
SendMail	An email report is sent to the report recipient who was specified in the first step.
PageCheckin	The page is unlocked.

View BPMN

Expert document control

Purpose: Approval of a draft page according to the "4-eyes principle".

Workflow instances: A page can only have one approval worfklow at a time.

BPMN diagram of the "Expert document control" workflow

Activity	Description
CollectData	In the first workflow step, the workflow initiator enters the settings: User: User who is assigned to a task. Three different users have to be specified: Editor, Reviewer, Approver Instructions: A comment or instructions for the users to understand their tasks. Send report to: An email report with the results will be sent to this email address when the review is finished. If a username is specified here, an email address must be stored in the user administration so that the report can be sent.
PageCheckout	The page is locked for users who do not participate in the workflow. Only the Editor (first workflow participant) can edit the page during checkout. While the Reviewer (second participant) of the workflow is reviewing the page, the page stays checked-out to thecan edit the page can edit the page during checkout.checkout. in case the Reviewer requests more edits.
EditPage	The Editor user can edit the page and completes the task without comment.
UserVote	After the Editor step has been completed, the Reviewer user can review the page and submit a vote. Editing by the Reviewer is not possible. As an alternative, the Reviewer can delegate the task. If the vote is positive (Approve), the workflow continues. If the Reviewer rejects, the workflow goes back to the Editor. The workflow initiator gets an email about the voting result.
PageCheckin	After the Reviewer submits a positive vote (accept), the page is checked in and the workflow continues.
PageCheckout	In this step, the page checkout locks the page for editing completely. The Approver user will not be able to change the page, but needs to approve it.
ApprovePage	The Approver can either complete or delegate the task. After the Approver (or the delegate) finishes the assigned task, the page is set from "draft" to "approved" status if the page was in draft status (only if the approver submits a positive vote). If not, this step is skipped.
SendMail	If an email or user was specified in the workflow settings, the report is now getting sent to that user.
PageCheckin	The page gets unlocked for editing.

view BPMN

Group feedback

Purpose: Obtaining feedback from the members of a user group. The group must exist in the group manager.

Workflow instances: Several feedback workflows can run independently of one another on one page at the same time.

BPMN diagram of the "Group feedback" workflow

Activity	Description
CollectData	In the first workflow step, the workflow initiator enters the settings: Group: User group who is assigned to the task. Instructions: A comment or instructions for the users to understand their task. Send report to: An email report with the results will be sent to this email address when the review is finished. If a username is specified here, an email address must be stored in the user administration so that the report can be sent.
GroupFeedback	All users in the assigned group provide feedback via a comment field. This is a parallel workflow, which means that the order of the feedback does not matter.
SendMail	If an email or user was specified in the workflow settings, the report is now getting sent to that user.

view BPMN

Feedback

Purpose: Obtaining feedback from a single user on a page.

Workflow instances: Multiple feedback worfklows can run independently of one another on one page at the same time.

BPMN diagram of the "Single user feedback" workflow

Activity	Description
CollectData	In the first workflow step, the workflow initiator enters the settings: User: User who is assigned to the task. Instructions: A comment or instructions for the users to understand their task. Send report to: An email report with the results will be sent to this email address when the review is finished. If a username is specified here, an email address must be stored in the user administration so that the report can be sent.
UserFeedback	The assigned user sends a comment.
SendMail	If an email or user was specified in the workflow settings, the report is now getting sent to that user.

view BPMN

Overview page

All workflows in the wiki are listed on the page Special:Workflows overview. A view for all active workflows and a view for all workflows can be selected.

Workflows overview page

Tasks overview

Users are informed about new and pending tasks in their notifications. They can view assigned workflows on their My tasks page.

Notifications

Events that trigger notifications

There are two types of events that trigger notification

generic: notifications happen for every workflow/activity type
activity-specifiy: activities themselves can decide to send additional notifications

Triggering event	Recipients	Generic	Notes
Task started (task assigned)	All assigned users	Yes	Only triggered for type UserInteractiveActivity, i.e., only for activities that have users assigned.
UserVote	Initiator	Yes	The workflow initiator gets an email about the voting result.
Workflow aborted (manual or automatic)	Initiator and all users that were assigned to the current task at time of aborting (not users who were assigned on previous tasks)	Yes
Workflow ended (only when naturally ended, not when aborted)	Initiator	Yes
DueDateClose (2 days before Workflow will expire)	Initiator and all currently assigned users	Yes
Workflow expired	Initiator and all currently assigned users	Yes	Expiration is just a type of workflow abort, so the same notification as for abort will be sent with the reason explaining that the workflow expired.
Task delegated	User to whom the task was delegated	No	Specific to UserVote activity. After delegation, the newly assigned user will be considered assigned and will receive all further notifications that go out to assigned users.

Sending out notifications

Users can choose whether to subscribe to e-mail notifications in their preferenceds. All users are force-subscribed to web notifications.
Web notifications are sent out immediatelly after triggering, while email notifications will be sent async, on runJobs.php execution. This applies to notifications in general, not only to workflows

Workflow triggers

Workflows can either be started manually on each wiki page or started only under certain conditions using individual workflow triggers. Triggers also allow to define in which namespaces both manual and automatic workflows are available.

How to add a custom workflow

Users can upload an xml-file of a BPMN diagram with custom activities to the wiki. Currently, the following predefined activities exist:

Extension: Workflows

Extension: PageCheckout

Extension: BlueSpiceFlaggedRevsConnector

ApprovePage

Example of a customized workflow (coming soon)

Permissions

The following permissions are used by this extension:


Permission	Included in role	Description
workflows-view	reader	allows viewing workflow elements, including listing of workflows (e.g., viewing all running workflows on a page user can view the page Special:Workflows_overview
workflows-execute	editor, reviewer, admin	allows starting a workflow and executing a task
workflows-admin	admin	allows aborting, restoring and administering all workflows user fcdan view and edit the page MediaWiki:WorkflowTriggers

Example tutorial

You can follow our tutorial for creating a custom workflow that allows users to classify a document and notify a user about the classification.

Technical Reference: Workflows

To submit feedback about this documentation, visit our community forum.

@@ Line 1: / Line 1: @@
+{{DISPLAYTITLE:Workflows}}
 <bookshelf src="Book:User manual" />
 ==Introduction==
@@ Line 25: / Line 26: @@
 |A user is asked to send a comment regarding a page.
 |}
-==Notifications and reports==
-*'''When a task gets assigned:''' When a user needs to complete a workflow task, both a notification and a [[Reference:UnifiedTaskOverview|task]] are created.
-*'''At the end of a worfklow:''' After a workflow has ended, the initiator receives a notification and an email is sent to a report recipient (as defined at the beginning of the workflow).
-*'''When a workflow gets aborted''':
-**A notifications are sent to users with a pending workflow task
-**A notifications are sent to the originator if a workflow got aborted
-** Participants of past or future steps don't receive a notification
 ==Workflow activities==
@@ Line 56: / Line 48: @@
 |-
 | style="width:200px;" |PageCheckout
-|The page is locked for editing by other wiki users. Only the user  with the workflow task can edit while this workflow is running.
+|The page is locked for editing. The reviewer also cannot make any edits.
 |-
 | style="width:200px;" |UserVote
 |The assigned user carries out a vote and either accepts the page or rejects it. Alternatively, the task can be delegated. In the event of a rejection, the workflow skips the next step (ApprovePage).
+The workflow initiator gets an email about the voting result.
 |-
 | style="width:200px;" | ApprovePage
@@ Line 70: / Line 63: @@
 |The page is unlocked.
 |}
+{{Icon|bi bi-arrow-right-circle|||}}  [https://github.com/wikimedia/mediawiki-extensions-BlueSpiceDistributionConnector/blob/4.2.6/workflow/UserApproval.bpmn View BPMN]
 ===Expert document control===
 '''Purpose:''' Approval of a draft page according to the "4-eyes principle".
@@ Line 90: / Line 83: @@
 |-
 | style="width:200px;" | PageCheckout
-|The page is locked for users who do not participate in the workflow. Only the '''Editor''' (first workflow participant) and '''Reviewer''' (second participant)  of the workflow can edit the page during checkout.
+|The page is locked for users who do not participate in the workflow. Only the '''Editor''' (first workflow participant) can edit the page during checkout. While the '''Reviewer''' (second participant)  of the workflow  is reviewing the page, the page stays checked-out to thecan edit the page can edit the page during checkout.checkout. in case the Reviewer requests more edits.
 |-
 | style="width:200px;" |EditPage
@@ Line 96: / Line 89: @@
 |-
 | style="width:200px;" |UserVote
-|After the '''Edito'''r step has been completed,the '''Reviewer''' user can edit the page and submit a vote. As an alternative, the '''Reviewer''' can delegate the task.  If the vote is positive (Approve), the workflow continues. If the '''Reviewer''' rejects, the workflow goes back to the '''Editor'''.
+|After the '''Edito'''r step has been completed, the '''Reviewer''' user can review the page and submit a vote. Editing by the '''Reviewer''' is not possible. As an alternative, the '''Reviewer''' can delegate the task.  If the vote is positive (Approve), the workflow continues. If the '''Reviewer''' rejects, the workflow goes back to the '''Editor'''.
+The workflow initiator gets an email about the voting result.
 |-
 | style="width:200px;" |PageCheckin
@@ Line 113: / Line 107: @@
 |The page gets unlocked for editing.
 |}
+<span><span /><span /><br /></span>
+{{Icon|bi bi-arrow-right-circle|||}}  [https://github.com/wikimedia/mediawiki-extensions-BlueSpiceDistributionConnector/blob/4.2.6/workflow/DocumentControl.bpmn view BPMN]
 ===Group feedback===
@@ Line 137: / Line 134: @@
 |If an email or user was specified in the workflow settings, the report is now getting sent to that user.
 |}
+{{Icon|bi bi-arrow-right-circle|||}}  [https://github.com/wikimedia/mediawiki-extensions-Workflows/blob/4.1.1/workflow/GroupFeedback.bpmn view BPMN]
 ===Feedback===
@@ Line 161: / Line 160: @@
 |If an email or user was specified in the workflow settings, the report is now getting sent to that user.
 |}
+{{Icon|bi bi-arrow-right-circle|||}}  [https://github.com/wikimedia/mediawiki-extensions-Workflows/blob/4.1.1/workflow/UserFeedback.bpmn view BPMN]
 ==Overview page==
@@ Line 167: / Line 168: @@
 === Tasks overview===
 Users are informed about new and pending tasks in their notifications. They can view assigned workflows on their  [[Reference:UnifiedTaskOverview|''My tasks'']]  page.
+== Notifications ==
+=== Events that trigger notifications ===
+There are two types of events that trigger notification
+* '''generic:''' notifications happen for every workflow/activity type
+* '''activity-specifiy''': activities themselves can decide to send additional notifications
+{| class="wikitable" style=""
+!Triggering event
+!Recipients
+!Generic
+!Notes
+|-
+|'''Task started'''
+(task assigned)
+|All assigned users
+|Yes
+|Only triggered for type  ''UserInteractiveActivity,'' i.e., only for activities that have users assigned.
+|-
+|'''UserVote'''
+|Initiator
+|Yes
+|The workflow initiator gets an email about the voting result.
+|-
+|'''Workflow aborted'''
+(manual or automatic)
+|Initiator and all users that were assigned to the current task at time of aborting (not users who were assigned on previous tasks)
+|Yes
+|
+|-
+|'''Workflow ended'''
+(only when naturally ended, not when aborted)
+|Initiator
+|Yes
+|
+|-
+|'''DueDateClose'''
+(2 days before Workflow will expire)
+|Initiator and all currently assigned users
+|Yes
+|
+|-
+|'''Workflow expired'''
+|Initiator and all currently assigned users
+|Yes
+|Expiration is just a type of workflow abort, so the same notification as for abort will be sent with the reason explaining that the workflow expired.
+|-
+|'''Task delegated'''
+|User to whom the task was delegated
+|No
+|Specific to ''UserVote'' activity. After delegation, the newly assigned user will be considered assigned and will receive all further notifications that go out to assigned users.
+|}
+=== Sending out notifications ===
+* Users can choose whether to subscribe to e-mail notifications in their preferenceds. All users are force-subscribed to web notifications.
+* Web notifications are sent out immediatelly after triggering, while email notifications will be sent async, on runJobs.php execution. This applies to notifications in general, not only to workflows
+== Workflow triggers ==
+Workflows can either be started manually on each wiki page or started only under certain conditions using individual [[Manual:Extension/Workflows/Triggers|workflow triggers]]. Triggers also allow to define in which namespaces both manual and automatic workflows are available.
 ==How to add a custom workflow==
@@ Line 181: / Line 244: @@
 *[[Manual:Extension/Workflows/Activity/EditRequest|EditRequest]]
+<span><span /><span /><br /></span>
 '''Extension: PageCheckout'''
@@ Line 187: / Line 250: @@
 *[[Manual:Extension/Workflows/Activity/PageCheckIn|PageCheckIn]]
+<span><span /><span /><br /></span>
 '''Extension: BlueSpiceFlaggedRevsConnector'''
@@ Line 194: / Line 257: @@
 Example of a customized workflow (coming soon)
+<span><span /><span /><br /></span>
 == Permissions ==
 The following permissions are used by this extension:
@@ Line 220: / Line 283: @@
 * user fcdan view and edit the page ''MediaWiki:WorkflowTriggers''
 |}
+== Example tutorial ==
+You can follow our [[Manual:Extension/Workflows/Tutorial|tutorial for creating a custom workflow]] that allows users to classify a document and notify a user about the classification.
 {{translation}}