Manual:Extension/Workflows/Tutorial: Difference between revisions

No edit summary
Redaktion (talk | contribs)
No edit summary
Line 1: Line 1:
{{DISPLAYTITLE:Creating a custom workflow}}
{{DISPLAYTITLE:Creating a custom workflow}}
Simple workflows can be created directly in the wiki using a workflow editor.
Workflows can be created directly in the wiki with the Workflow editor.
== How to create a custom workflow ==
== How to create a custom workflow ==
In addition to the built-in workflows, users can create their own workflows in the wiki. The functionality of the workflows is based on the currently implemented workflow elements. Note that not all elements of the [[wikipedia:Business_Process_Model_and_Notation|BPMN standard]] are supported in the Workflows extension at this time.
In addition to the built-in workflows, users can create their own workflows in the wiki. The functionality of the workflows is based on the currently implemented workflow elements (based on the XML standard BPMN). Note that not all elements of the [[wikipedia:Business_Process_Model_and_Notation|BPMN standard]] are supported in the Workflows extension at this time.
=== Steps to create a custom workflow ===
=== Steps to create a custom workflow ===
'''To create a workflow:'''
'''To create a workflow:'''
# '''Defining''' the workflow required with the necessary steps and activities
# '''Define''' the workflow with the necessary steps and activities.
# '''Create''' a page with the extension <code>.bpmn</code> Ideally, this page is created in the MediaWiki namespace to limit edit-permissions to wiki admins.
# '''Create''' a page with the extension <code>.bpmn</code> . Ideally, this page is created in the MediaWiki namespace, which is reserved for the more technical pages in the wiki.
# '''Edit''' the page in ''Edit diagram'' mode or click on the pencil icon.[[File:WF_edit_diagram.png|alt=Edit menu with selected option "Edit diagram"|center|thumb|200x200px|Edit menu]]
# '''Edit''' the page in ''Edit diagram'' mode.[[File:WF_edit_diagram.png|alt=Edit menu with selected option "Edit diagram"|center|thumb|200x200px|Edit menu]]
# '''Add''' a ''start'' event, activities, gateways (optional) and an ''end'' event. The following BPMN-Elements are supported:
# '''Add''' a ''start'' event, activities, gateways (optional) and an ''end'' event. The following BPMN-Elements are supported:
#* '''Events:''' start and end event
#* ''Events:'' start and end event
#* '''Gateways:''' currently only parallel gateways are possible
#* ''Gateways:'' currently only parallel gateways are possible
#* '''Activities:''' BlueSpice has its own set of activities. [[Manual:Extension/Workflows/Activity|See the full list.]]
#* ''Activities:'' BlueSpice has its own set of activities. [[Manual:Extension/Workflows/Activity|See the full list.]]
#* In addition, you can bind the workflow to a particular page revision. (This is necessary for approval workflows, for example).
#* In addition, you can bind the workflow to a particular page revision. (This is necessary for approval workflows, for example).
# '''Save''' the BPMN diagram.
# '''Save''' the BPMN diagram.
# If data is to be collected when a workflow is started that needs to be taken into account in the workflow execution, a form page with the <code>.form</code> extension is also created.
# '''Create''' a form page with the <code>.form</code> extension if you want to collect any data from the user during workflow execution.
# '''Add''' a [[Manual:Extension/Workflows/Triggers|workflow trigger]].
# '''Add''' a [[Manual:Extension/Workflows/Triggers|workflow trigger]]. The workflow is now available in the wiki. 
# '''Test''' the workflow: The workflow is now available in the wiki. You should test whether the following functionality is available:
# '''Test''' the workflow. Ensure that:
#*The workflow is available to be started in the namespaces defined in the workflow trigger (if there are restrictions here).
#*The workflow is available to be started in the namespaces defined in the workflow trigger (if there are restrictions here).
#*The workflow is triggered.
#*The workflow is triggered.
Line 22: Line 22:
#*The assigned user received a task.
#*The assigned user received a task.
#*The workflow completes correctly in all possible scenarios (in case of gateways).
#*The workflow completes correctly in all possible scenarios (in case of gateways).
=== Customise workflows ===
As of BlueSpice 4.5, <code>.bpmn</code> pages can be customised via a workflow editor so that it is no longer necessary to adapt the xml source code.
Prior to BlueSpice 4.5, workflows can only be created via BPMN-XML.
=== Tips ===
To make the workflows as easy to manage as possible, it is recommended that the elements are named as meaningfully as possible and given the same ID as the name.
== Example 1 (basic): Obtaining a signature on a page ==
== Example 1 (basic): Obtaining a signature on a page ==
=== Defining the workflow ===
=== Defining the workflow ===
Line 76: Line 68:
# '''Execute workflow task''': J. Doe checks the page and executes his assigned feedback task using the blue banner. It is possible that the banner does not display the name, but the name of a system message assigned to the workflow. You can create this in the wiki.[[File:WF_User_feedback_Banner.png|center|thumb|750x750px|Workflow Banner]]
# '''Execute workflow task''': J. Doe checks the page and executes his assigned feedback task using the blue banner. It is possible that the banner does not display the name, but the name of a system message assigned to the workflow. You can create this in the wiki.[[File:WF_User_feedback_Banner.png|center|thumb|750x750px|Workflow Banner]]
# '''Signature is added to the page:''' The wiki signature is automatically appended to the end of the page content.[[File:John_Doe's_signature.png|center|thumb|Inserted signature]]
# '''Signature is added to the page:''' The wiki signature is automatically appended to the end of the page content.[[File:John_Doe's_signature.png|center|thumb|Inserted signature]]
== Example 2 (advanced): Classification of a wikipage ==
== Example 2 (advanced): Classification of a wiki page ==
=== Defining the workflow ===
=== Defining the workflow ===
Let's assume, we want to build a workflow, that asks for some classification of a wikipage. Based on the classification of the document, it either sends an e-mail to a member of the legal team or it first appends a wiki page and then sends the e-mail to the legal team.
Let's assume, we want to build a workflow, that asks for some classification of a wiki page. Based on the classification of the document, it either sends an e-mail to a member of the legal team or it first appends a wiki page and then sends the e-mail to the legal team.
The described workflow consists of four activities and one gateway. You can create a BPMN-Diagramm in the wiki to visualize the process:
The described workflow consists of four activities and one gateway. You can create a BPMN-Diagramm in the wiki to visualize the process:
[[File:Workflows-tutorial-diagram.svg|center|thumb|700x700px|alt=Document classification workflow|Document classification workflow]]
[[File:Workflows-tutorial-diagram.svg|center|thumb|700x700px|alt=Document classification workflow|Document classification workflow]]
=== Creating the workflow ===
=== Creating the workflow ===
To create the workflow, the following steps are necessary:
To create the workflow, the following steps are necessary:
#Creating a custom '''workflow definition:''' <code>MediaWiki:Classification-workflow.bpmn</code>
#Create the custom '''workflow definition:''' <code>MediaWiki:Classification-workflow.bpmn</code>
#Creating and connecting an '''initiation form''' that adds some information about the workflow before it sends the task. <code>MediaWiki:ContentClassificationInit.form</code>
#Create an '''initiation form''' that adds some information about the workflow before it sends the task: <code>MediaWiki:ContentClassificationInit.form</code>
#Creating and connecting the '''classification form''' that allows the assigned user to classify the document. <code>MediaWiki:ContentClassificationRequest.form</code>
#Create a '''classification form''' that allows the assigned user to classify the document: <code>MediaWiki:ContentClassificationRequest.form</code>
#Continuing the workflow configuration with the gateway, email configuration and the appending of the concerned wikipage
#Continue the '''workflow configuration''' for each step.
#Adding a '''trigger''' to the wiki that defines where and how to start the workflow.
#Add a '''trigger''' to the wiki that defines where and how to start the workflow.
#Testing the workflow.
#Test the workflow.
{{Textbox|boxtype=important|header=Note|text=XML which is provided below is incompatible with "BPMN Editor" added in BlueSpice 4.5. There is no way to edit it in visual way.|icon=yes}}
==== Creating the custom workflow definition ====
==== Creating a custom workflow definition ====
First, let's create a page called <code>MediaWiki:Classification-workflow.bpmn</code> .  It opens the Workflow editor.
First, let's create a page called <code>MediaWiki:Classification-workflow.bpmn</code> with the most basic stub XML. Each workflow that you define in the wiki needs the elements that you see here:
[[File:wfe start.png|alt=new workflow diagram in edit modewith only a start event|center|thumb|450x450px|Workflow editor]]
*Line 1: The XML prolog
Add the following shapes to your diagram (hover over the icons in the toolbar to see the name of each BPMN  element). Connect each element with an arrow. Double-click each shape to enter the necessary information:
*Line 2: The definitions element, which denotes the namespaces where the workflow elements are defined.
 
*Line 3: The process element, which contains all other elements.
# A ''Custom form''  to initiate the workflow.
*Line 5: The workflow runs in the context of a specific revision of a wiki page.
## Name: <code>Initiation form</code>
* Line 11: The workflow needs a startEvent and
## Form type: <code>On-wiki form</code>
*Line 18: The workflow needs an endEvent.
## From title: <code>MediaWiki:ClassificationInit.form</code>
<syntaxhighlight lang="xml" line="1">
## Use as initializer: <code>yes</code>
<?xml version="1.0" encoding="UTF-8"?>
# Another ''Custom form'' with name "Classification form" for classifying the page on which the workflow runs.
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:wf="http://hallowelt.com/schema/bpmn/wf" xmlns:di="http://www.omg.org/spec/DD/20100524/DI">
## Name: <code>Classification form</code>
<bpmn:process id="Classification_workflow_process">
## Form type: <code>On-wiki form</code>
<bpmn:extensionElements>
## Form title: <code>MediaWiki:ContentClassificationRequest.form</code>
<wf:context>
## Use as initializer: <code>yes</code>
<wf:contextItem name="pageId"/>
## Properties:
<wf:contextItem name="revision"/>
### assigned_user:<code><nowiki>{{ROOTPAGENAME:{{#show:{{FULLPAGENAME}}|?Responsible|link=none|default=WikiSysop}}}}</nowiki></code>
</wf:context>
### due_date: <code><nowiki>{{#time: c | now + 7 days}}</nowiki></code>
</bpmn:extensionElements>
### classification
<bpmn:startEvent id="TheStart">
# A G''ateway'' with name "Classsificationform.classification" that processes the user's classification choice.
<bpmn:outgoing>FromTheStartToTheEnd</bpmn:outgoing>
## Name: Classificationform.classification  (Note: The name has to match the name of the form and its property which has to be evaluated).
</bpmn:startEvent>
## Name of the connector to the ''Send mail'' activity: <code>Class_A</code>
<bpmn:sequenceFlow id="FromTheStartToTheEnd" sourceRef="TheStart" targetRef="TheEnd" />
## Name of the connector to the ''Record Class B'' activity: <code>Class_B</code>
<!-- ... -->
# A ''Send mail'' activity with name "Send mail" after the "Class_A" classification choice.
<bpmn:endEvent id="TheEnd">
# An ''Edit wiki page''  activity with name "Record Class B" after the "Class_B" classification choice. Connect it to the ''Send mail'' activity from step 5.
<bpmn:incoming>FromTheStartToTheEnd</bpmn:incoming>
# Add the end event after the Send mail activity.
</bpmn:endEvent>
## Name: <code>Send mail</code>
</bpmn:process>
## Properties:
</bpmn:definitions>
### Recipient: <code>legal@mycompany.co</code>m
</syntaxhighlight>
### Subject: <code>New "<nowiki>{{{Classificationform.classification}}}</nowiki>" content: <nowiki>{{FULLPAGENAME}}</nowiki></code>
The above stub xml only features the "Start" and "End" event including - yet to be defined - "outgoing" and "incoming" flow references.
### Body: <code><nowiki>{{{Classificationform.assigned_user}}}</nowiki> has classified page <nowiki>[[{{FULLPAGENAME}}]]</nowiki> as "<nowiki>{{{Classificationform.classification}}}</nowiki>.</code>
====Creating and connecting an initiation form====
# Save the diagram.
 
Your workflow diagram should look like this:
 
====Creating the initiation form====
The initiation form allows to interact with the user who starts the workflow. It explains what happens when the workflow is started and allows to add a comment to provide some context for the user task.
The initiation form allows to interact with the user who starts the workflow. It explains what happens when the workflow is started and allows to add a comment to provide some context for the user task.
We are using the MediaWiki namespace here to make sure not every user can edit the form later. But in general, such forms can be created everywhere in the wiki.
We are using the MediaWiki namespace here to make sure not every user can edit the form later. But in general, such forms can be created everywhere in the wiki.
Line 285: Line 281:
After setting up the gateway, we need to define the tworelated activities.
After setting up the gateway, we need to define the tworelated activities.
====Sending an mail to the legal department====
====Sending an mail to the legal department====
For case 1, we need the workflow to immediately send an email:<syntaxhighlight lang="xml">
For case 1, we need the workflow to immediately send an email:<syntaxhighlight lang="xml">...
...
<bpmn:task id="SendMail" name="Send mail">
<bpmn:task id="SendMail" name="Send mail">
<bpmn:extensionElements>
<bpmn:extensionElements>
Line 305: Line 300:
</bpmn:task>
</bpmn:task>
<bpmn:sequenceFlow id="FromEndMailToTheEnd" sourceRef="SendMail" targetRef="TheEnd" />
<bpmn:sequenceFlow id="FromEndMailToTheEnd" sourceRef="SendMail" targetRef="TheEnd" />
...
...</syntaxhighlight>
</syntaxhighlight>
====Appending a wikipage ====
====Appending a wikipage ====
For case 2, we want the workflow to append the existing page ''Classification_incidents'' with the text shown in the ''content'' property.
For case 2, we want the workflow to append the existing page ''Classification_incidents'' with the text shown in the ''content'' property.

Revision as of 15:56, 17 July 2025

Workflows can be created directly in the wiki with the Workflow editor.

How to create a custom workflow

In addition to the built-in workflows, users can create their own workflows in the wiki. The functionality of the workflows is based on the currently implemented workflow elements (based on the XML standard BPMN). Note that not all elements of the BPMN standard are supported in the Workflows extension at this time.

Steps to create a custom workflow

To create a workflow:

  1. Define the workflow with the necessary steps and activities.
  2. Create a page with the extension .bpmn . Ideally, this page is created in the MediaWiki namespace, which is reserved for the more technical pages in the wiki.
  3. Edit the page in Edit diagram mode.
    Edit menu with selected option "Edit diagram"
    Edit menu
  4. Add a start event, activities, gateways (optional) and an end event. The following BPMN-Elements are supported:
    • Events: start and end event
    • Gateways: currently only parallel gateways are possible
    • Activities: BlueSpice has its own set of activities. See the full list.
    • In addition, you can bind the workflow to a particular page revision. (This is necessary for approval workflows, for example).
  5. Save the BPMN diagram.
  6. Create a form page with the .form extension if you want to collect any data from the user during workflow execution.
  7. Add a workflow trigger. The workflow is now available in the wiki.
  8. Test the workflow. Ensure that:
    • The workflow is available to be started in the namespaces defined in the workflow trigger (if there are restrictions here).
    • The workflow is triggered.
    • The workflow is listed in the Workflows Overview page.
    • The assigned user received a task.
    • The workflow completes correctly in all possible scenarios (in case of gateways).

Example 1 (basic): Obtaining a signature on a page

Defining the workflow

Let's look at a simple workflow: After completing a page (e.g., meeting minutes), the signature of the department head John Doe is required.

required workflow steps

We need a workflow definition with two workflow activities:

  1. User feeback (request signature): John Doe receives a feedback task. A feedback task adds a banner to the page. To complete the task, John Doe provides his feedback (for example: "noted").
    Workflow Banner
  2. Edit wiki page (add signature): After completing the feedback task, the workflow automatically adds John Doe's wiki signature to the page.
    Inserted signature

Creating the workflow

  1. Click on the wiki's New button and enter the page name with the extension .bpmn, e.g. Signature.bpmn.
    Create page using the "New" button
  2. Click Done.
  3. Open the page in edit mode. The diagram already shows the start activity.
  4. Add the activity User feedback.
    activity "User feedback"
    1. Open the dialog box for the activity (via double-click) and enter the name of the activity (e.g., "request signature"),
    2. Add the user name and an instruction (e.g., "Sign this page")
      dialog box for activity "User feedback"
    3. Click on Save.
    4. Connect the StartEvent with the activity User feedback.
  5. Add the activity Edit wiki page and connect it to the previous activity.
    Activity "Edit wiki page"
    1. Open the dialog box for the activity (via double-click) and enter the name of the activity (e.g. "add signature" or "sign page"),
    2. Specify the page on which the signature should be added. Normally this is the page on which the workflow is triggered. To do this, use the Magic word {{FULLPAGENAME}} as a placeholder.
    3. Specify the user name for the signature. (Note: In the next example we will see how the user name can be entered via a form when triggering the workflow, but in this example we will enter the name directly in the workflow for simplicity, since the same person always signs.)
    4. Enter four tildes as Content. This will automatically create the specified user's signature in the wiki.
    5. Mark the change (i.e. the insertion of the signature on the page) as a minor revision (Minor revision) if you do not want it to trigger a notification or display as the last change on overview pages in the wiki.
    6. Select Append as Edit mode. This will insert the signature at the end of the page.
      Dialog window for activity "Edit wiki page"
    7. Click on Save.
    8. Connect the activity User feedback with the activity Edit wiki page.
  6. Add an EndEvent and connect it to the previous activity.
    EndEvent
  7. Save the page.

The workflow should now look like this:

Finished workflow

The workflow can now be used in the wiki. The next step is to activate the workflow in the wiki.

Creating the workflow trigger

So that the workflow can now be used on a page, we still need to create a trigger:

  1. Click on Global Actions > Workflow Triggers.
  2. Click on Add new trigger.
  3. Select Manual as the type.
    Dialog field for selecting a trigger type
    Create a manual workflow trigger
  4. Set up the workflow trigger:
    1. Enter the name as you want it to appear in the workflow menu on the page.
    2. Enter a short description as you want it to appear in the workflow menu on the page (optional).
    3. Select the workflow Signature as the workflow to start.
    4. Specify as a condition in which namespaces the workflow should be available (optional). If no condition is specified, the workflow is automatically available in all content namespaces.
      Dialog field with parameters for workflow "Signature"
      Trigger setup

Applying the workflow

The workflow goes through the following steps:

  1. Start workflow: Users with editing rights in the wiki can now start the workflow to request a signature from J. Doe. To do this, the workflow is triggered, for example, on a protocol page using the corresponding menu item.
    Dialog window for selecting a workflow
    Select workflow
    A start dialog appears. Since there is no form for entering data here, the dialog can be closed with Start.
    Start dialog for workflow without form
    Start the workflow
    The assigned user J. Doe receives an email and a task appears in his user menu in the wiki.
  2. Execute workflow task: J. Doe checks the page and executes his assigned feedback task using the blue banner. It is possible that the banner does not display the name, but the name of a system message assigned to the workflow. You can create this in the wiki.
    Workflow Banner
  3. Signature is added to the page: The wiki signature is automatically appended to the end of the page content.
    Inserted signature

Example 2 (advanced): Classification of a wiki page

Defining the workflow

Let's assume, we want to build a workflow, that asks for some classification of a wiki page. Based on the classification of the document, it either sends an e-mail to a member of the legal team or it first appends a wiki page and then sends the e-mail to the legal team. The described workflow consists of four activities and one gateway. You can create a BPMN-Diagramm in the wiki to visualize the process:

Document classification workflow
Document classification workflow

Creating the workflow

To create the workflow, the following steps are necessary:

  1. Create the custom workflow definition: MediaWiki:Classification-workflow.bpmn
  2. Create an initiation form that adds some information about the workflow before it sends the task: MediaWiki:ContentClassificationInit.form
  3. Create a classification form that allows the assigned user to classify the document: MediaWiki:ContentClassificationRequest.form
  4. Continue the workflow configuration for each step.
  5. Add a trigger to the wiki that defines where and how to start the workflow.
  6. Test the workflow.

Creating the custom workflow definition

First, let's create a page called MediaWiki:Classification-workflow.bpmn . It opens the Workflow editor.

new workflow diagram in edit modewith only a start event
Workflow editor

Add the following shapes to your diagram (hover over the icons in the toolbar to see the name of each BPMN element). Connect each element with an arrow. Double-click each shape to enter the necessary information:

  1. A Custom form to initiate the workflow.
    1. Name: Initiation form
    2. Form type: On-wiki form
    3. From title: MediaWiki:ClassificationInit.form
    4. Use as initializer: yes
  2. Another Custom form with name "Classification form" for classifying the page on which the workflow runs.
    1. Name: Classification form
    2. Form type: On-wiki form
    3. Form title: MediaWiki:ContentClassificationRequest.form
    4. Use as initializer: yes
    5. Properties:
      1. assigned_user:{{ROOTPAGENAME:{{#show:{{FULLPAGENAME}}|?Responsible|link=none|default=WikiSysop}}}}
      2. due_date: {{#time: c | now + 7 days}}
      3. classification
  3. A Gateway with name "Classsificationform.classification" that processes the user's classification choice.
    1. Name: Classificationform.classification (Note: The name has to match the name of the form and its property which has to be evaluated).
    2. Name of the connector to the Send mail activity: Class_A
    3. Name of the connector to the Record Class B activity: Class_B
  4. A Send mail activity with name "Send mail" after the "Class_A" classification choice.
  5. An Edit wiki page activity with name "Record Class B" after the "Class_B" classification choice. Connect it to the Send mail activity from step 5.
  6. Add the end event after the Send mail activity.
    1. Name: Send mail
    2. Properties:
      1. Recipient: legal@mycompany.com
      2. Subject: New "{{{Classificationform.classification}}}" content: {{FULLPAGENAME}}
      3. Body: {{{Classificationform.assigned_user}}} has classified page [[{{FULLPAGENAME}}]] as "{{{Classificationform.classification}}}.
  7. Save the diagram.

Your workflow diagram should look like this:

Creating the initiation form

The initiation form allows to interact with the user who starts the workflow. It explains what happens when the workflow is started and allows to add a comment to provide some context for the user task. We are using the MediaWiki namespace here to make sure not every user can edit the form later. But in general, such forms can be created everywhere in the wiki.

Worfklow initiation form
Worfklow initiation form

To create the initiation form:

  1. Create the page MediaWiki:ContentClassificationInit.form
  2. Paste the following form definition in source edit mode:
    {
    "lang": "json",
    "form_name": "ContentClassificationInit",
    "items": [
    {
    "name": "intro",
    "widget_label": "Click  \"Start\" to ask an expert for classification. You can leave a comment for the expert below",
    "type": "label"
    },
    {
    "name": "comment",
    "label": "Comment",
    "noLayout": true,
    "showOn": [
    "create",
    "edit",
    "view"
    ],
    "editableOn": [
    "create",
    "edit"
    ],
    "type": "textarea"
    }
    ]
    }
    
  3. Save the page.

Next, we tell the BPMN with the following userTask to show the form:

<bpmn:userTask id="InitializeWorkflow" name="Start Content Classification Workflow">
<bpmn:extensionElements>
<wf:type>custom_form</wf:type>
<wf:form>MediaWiki:ContentClassificationInit</wf:form>
<wf:initializer>true</wf:initializer>
</bpmn:extensionElements>
<bpmn:property name="comment"></bpmn:property>
<bpmn:incoming>FromTheStartToInitializeWorkflow</bpmn:incoming>
<bpmn:outgoing>FromInitializeWorkflowToAskForClassification</bpmn:outgoing>
</bpmn:userTask>
<bpmn:sequenceFlow id="FromInitializeWorkflowToAskForClassification" sourceRef="InitializeWorkflow" targetRef="AskForClassification" />

Let's look at what this does:

  • The id and name of this activity are set to "InitializeWorkflow" and "Start Content Classification Workflow". Both values do not need to match, but usually they do.
  • <wf:type> is custom_form and tells the workflow that a form directly in the wiki (as opposed to a form located in code) is available.
  • <wf:form> points to the actual form page in the wiki
  • <wf:initializer> is set to true since it is used to show or collect some information before the actual workflow starts.

At the end, we have the incoming and outgoing flows referenced. (Note: the order of elements does not matter usually; only the nesting is important).

We add this userTask on line 16, after the line <bpmn:sequenceFlow id="FromTheStartToInitializeWorkflow" sourceRef="TheStart" targetRef="InitializeWorkflow" />:

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:wf="http://hallowelt.com/schema/bpmn/wf">
<bpmn:process id="Classification_workflow_process">
<bpmn:extensionElements>
<wf:context>
<wf:contextItem name="pageId"/>
<wf:contextItem name="revision"/>
</wf:context>
</bpmn:extensionElements>
<bpmn:startEvent id="TheStart">
<bpmn:outgoing>FromTheStartToInitializ</bpmn:outgoing>
</bpmn:startEvent>
<bpmn:sequenceFlow id="FromTheStartToInitializeWorkflow" sourceRef="TheStart" targetRef="InitializeWorkflow" />
<bpmn:userTask id="InitializeWorkflow" name="Start Content Classification Workflow">
<bpmn:extensionElements>
<wf:type>custom_form</wf:type>
<wf:form>MediaWiki:ContentClassificationInit</wf:form>
<wf:initializer>true</wf:initializer>
</bpmn:extensionElements>
<bpmn:property name="comment"></bpmn:property>
<bpmn:incoming>FromTheStartToInitializeWorkflow</bpmn:incoming>
<bpmn:outgoing>FromInitializeWorkflowToAskForClassification</bpmn:outgoing>
</bpmn:userTask>
<bpmn:sequenceFlow id="FromInitializeWorkflowToAskForClassification" sourceRef="InitializeWorkflow" targetRef="AskForClassification" />
<bpmn:endEvent id="TheEnd">
<bpmn:incoming>FromSendMailToTheEnd</bpmn:incoming>
</bpmn:endEvent>
</bpmn:process>
</bpmn:definitions>

Creating and connecting the classification form

The workflow will show a classification form to a user. This user will be defined in the workflow in a later step. To create the classification form:

  1. Create the page MediaWiki:ContentClassificationRequest.form
  2. Paste the following form definition in source edit mode:
{
"lang": "json",
"form_name": "ContentClassificationRequest",
"items": [
{
"name": "intro",
"widget_label": "Please review the given document and select an appropriate classification for the content from the list below",
"type": "label"
},
{
"name": "classification",
"label": "Classification",
"required": true,
"options": [
{
"data": "CLSA",
"label": "Class A"
},
{
"data": "CLSB",
"label": "Class B"
}
],
"type": "dropdown",
"widget_$overlay": true
}
]
}

Next, we tell the BPMN to show the form to user that receives the workflow task. For that, we add a userTask activity:

...
<bpmn:userTask id="AskForClassification" name="Provide classification">
<bpmn:extensionElements>
<wf:type>custom_form</wf:type>
<wf:form>MediaWiki:ContentClassificationRequest</wf:form>
<wf:initializer>true</wf:initializer>
</bpmn:extensionElements>
<bpmn:property name="assigned_user">
<![CDATA[{{ROOTPAGENAME:{{#show:{{FULLPAGENAME}}|?Responsible|link=none|default=TheBoss}}}}]]>
</bpmn:property>
<bpmn:property name="due_date">
<![CDATA[{{#time:YmdHis|now + 7 days}}]]>
</bpmn:property>
<bpmn:property name="classification"></bpmn:property>
<bpmn:incoming>FromTheStartToAskForClassification</bpmn:incoming>
<bpmn:outgoing>FromAskForClassificationToGateway</bpmn:outgoing>
</bpmn:userTask>
<bpmn:sequenceFlow id="FromAskForClassificationToGateway" sourceRef="AskForClassification" targetRef="Gateway" />
...

We should have a close look. This userTask has some additional properties besides the form reference (which was already explained in the initiation form):

  • assigned user: The assigned_user property is mandatory, as the workflow engine must know which user to query. In this case, we use some wikitext magic to calculate the assigned user from the context. The value consists of a combination of a wikitext variable and a parserfunction (this particular parserfunction is defined by the Semantic MediaWiki extension, which can be seen as a dependency here). The {{#show}} parserfunction tries to get a username from a semantic property, that may or may not be set on the page the workflow is started on. If it does not find a proper information, it will fallback to TheBoss (assuming that such a user exists on the wiki). The {{ROOTPAGENAME}} variable is just an easy way to strip the "User" namespace, if the looked up value was something like User:JaneDoe instead of just JaneDoe.
  • due date: The due_date property is also mandatory. All user facing activities need a due date. If the running activity is overdue, the workflow engine will end the workflow. In this case, we implement a concept of "lay days", as we do not have an absolute due date, but calculate it from the time the activity gets started using the {{#time}} parserfunction.
  • classification: The classification property is a random one. It must be specified, in order to allow the form to set it and the workflow context to access it. We could have provided a default value, but we want to keep it empty.

At the end, we have the incoming and outgoing flows referenced. (Note: the order of elements does not matter usually; only the nesting is important).

The gateway

Now we can proceed with adding the gateway. The gateway will provide the two necessary paths:

  1. If the assigned user classified the document as Class A (CLSA), an email will be sent to the legal department.
  2. If the assigned user classified the document as Class B (CLSB), a wiki page will be appended with the content defined in the task "AppendWikipage"
...
<bpmn:exclusiveGateway id="Gateway" name="AskForClassification.classification">
<bpmn:incoming>FromAskForClassificationToGateway</bpmn:incoming>
<bpmn:outgoing>FromGatewayToSendMail</bpmn:outgoing>
<bpmn:outgoing>FromGatewayToAppendWikipage</bpmn:outgoing>
</bpmn:exclusiveGateway>
<bpmn:sequenceFlow id="FromGatewayToSendMail" name="CLSA" sourceRef="Gateway" targetRef="SendMail" />
<bpmn:sequenceFlow id="FromGatewayToAppendWikipage" name="CLSB" sourceRef="Gateway" targetRef="AppendWikipage" />
...

After setting up the gateway, we need to define the tworelated activities.

Sending an mail to the legal department

For case 1, we need the workflow to immediately send an email:

...
<bpmn:task id="SendMail" name="Send mail">
<bpmn:extensionElements>
<wf:type>send_mail</wf:type>
</bpmn:extensionElements>
<bpmn:property name="recipient">
<![CDATA[legal@company.local]]>
</bpmn:property>
<bpmn:property name="subject">
<![CDATA[New "{{{AskForClassification.classification}}}" content: {{FULLPAGENAME}}]]>
</bpmn:property>
<bpmn:property name="body">
<![CDATA[Please check further actions now!]]>
</bpmn:property>
<bpmn:incoming>FromGatewayToSendMail</bpmn:incoming>
<bpmn:incoming>FromAppendWikipageToSendMail</bpmn:incoming>
<bpmn:outgoing>FromEndMailToTheEnd</bpmn:outgoing>
</bpmn:task>
<bpmn:sequenceFlow id="FromEndMailToTheEnd" sourceRef="SendMail" targetRef="TheEnd" />
...

Appending a wikipage

For case 2, we want the workflow to append the existing page Classification_incidents with the text shown in the content property.

This requirement can be fulfilled with the edit_page activity type:

...
<bpmn:task id="AppendWikipage" name="Append wikipage">
<bpmn:extensionElements>
<wf:type>edit_page</wf:type>
</bpmn:extensionElements>
<bpmn:property name="title" default="Classification_incidents"/>
<bpmn:property name="user" default="MediaWiki default"/>
<bpmn:property name="content" default="* [[{{FULLPAGENAME}}]] was classified {{{AskForClassification.classification}}}"/>
<bpmn:property name="mode" default="append"/>
<bpmn:property name="minor" default="1"/>
<bpmn:incoming>FromGatewayToAppendWikipage</bpmn:incoming>
<bpmn:outgoing>FromAppendWikipageToSendMail</bpmn:outgoing>
</bpmn:task>
<bpmn:sequenceFlow id="FromAppendWikipageToSendMail" sourceRef="AppendWikipage" targetRef="SendMail" />
...

The following properties are set for this activity type:

  • name: title of the wiki page to which the content will be appended.
  • user: user that is shown in the version history of the wiki page that was appended.
  • content: text that is added to the wiki page.
  • mode: shows where the text is added to the wiki page (append or ???)
  • minor: sets this page revision as a minor revision (1) or major revision (2).


After this task is completed, the workflow will send an email to the legal department.

Results: The final BPMN

In the end, the bpmn page for the workflow looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions
xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:wf="http://hallowelt.com/schema/bpmn/wf">
<bpmn:process id="Classification_workflow_process">
<bpmn:extensionElements>
<wf:context>
<wf:contextItem name="pageId"/>
<wf:contextItem name="revision"/>
</wf:context>
</bpmn:extensionElements>
<bpmn:startEvent id="TheStart">
<bpmn:outgoing>FromTheStartToInitializeWorkflow</bpmn:outgoing>
</bpmn:startEvent>
<bpmn:sequenceFlow id="FromTheStartToInitializeWorkflow" sourceRef="TheStart" targetRef="InitializeWorkflow" />
<bpmn:userTask id="InitializeWorkflow" name="Start Content Classification Workflow">
<bpmn:extensionElements>
<wf:type>custom_form</wf:type>
<wf:form>MediaWiki:ContentClassificationInit</wf:form>
<wf:initializer>true</wf:initializer>
</bpmn:extensionElements>
<bpmn:property name="comment"></bpmn:property>
<bpmn:incoming>FromTheStartToInitializeWorkflow</bpmn:incoming>
<bpmn:outgoing>FromInitializeWorkflowToAskForClassification</bpmn:outgoing>
</bpmn:userTask>
<bpmn:sequenceFlow id="FromInitializeWorkflowToAskForClassification" sourceRef="InitializeWorkflow" targetRef="AskForClassification" />
<bpmn:userTask id="AskForClassification" name="Provide classification">
<bpmn:extensionElements>
<wf:type>custom_form</wf:type>
<wf:form>MediaWiki:ContentClassificationRequest</wf:form>
</bpmn:extensionElements>
<bpmn:property name="assigned_user">
<![CDATA[{{ROOTPAGENAME:{{#show:{{FULLPAGENAME}}|?Responsible|link=none|default=TheBoss}}}}]]>
</bpmn:property>
<bpmn:property name="due_date">
<![CDATA[{{#time:YmdHis|now + 7 days}}]]>
</bpmn:property>
<bpmn:property name="classification"></bpmn:property>
<bpmn:incoming>FromInitializeWorkflowToAskForClassification</bpmn:incoming>
<bpmn:outgoing>FromAskForClassificationToGateway</bpmn:outgoing>
</bpmn:userTask>
<bpmn:sequenceFlow id="FromAskForClassificationToGateway" sourceRef="AskForClassification" targetRef="Gateway" />
<bpmn:exclusiveGateway id="Gateway" name="AskForClassification.classification">
<bpmn:incoming>FromAskForClassificationToGateway</bpmn:incoming>
<bpmn:outgoing>FromGatewayToSendMail</bpmn:outgoing>
<bpmn:outgoing>FromGatewayToAppendWikipage</bpmn:outgoing>
</bpmn:exclusiveGateway>
<bpmn:sequenceFlow id="FromGatewayToSendMail" name="CLSA" sourceRef="Gateway" targetRef="SendMail" />
<bpmn:sequenceFlow id="FromGatewayToAppendWikipage" name="CLSB" sourceRef="Gateway" targetRef="AppendWikipage" />
<bpmn:task id="SendMail" name="Send mail">
<bpmn:extensionElements>
<wf:type>send_mail</wf:type>
</bpmn:extensionElements>
<bpmn:property name="recipient">
<![CDATA[legal@company.local]]>
</bpmn:property>
<bpmn:property name="subject">
<![CDATA[New "{{{AskForClassification.classification}}}" content: {{FULLPAGENAME}}]]>
</bpmn:property>
<bpmn:property name="body">
<![CDATA[Please check further actions now!]]>
</bpmn:property>
<bpmn:incoming>FromGatewayToSendMail</bpmn:incoming>
<bpmn:incoming>FromAppendWikipageToSendMail</bpmn:incoming>
<bpmn:outgoing>FromEndMailToTheEnd</bpmn:outgoing>
</bpmn:task>
<bpmn:sequenceFlow id="FromEndMailToTheEnd" sourceRef="SendMail" targetRef="TheEnd" />
<bpmn:task id="AppendWikipage" name="Append wikipage">
<bpmn:extensionElements>
<wf:type>edit_page</wf:type>
</bpmn:extensionElements>
<bpmn:property name="title" default="Classification_incidents"/>
<bpmn:property name="user" default="MediaWiki default"/>
<bpmn:property name="content" default="* [[{{FULLPAGENAME}}]] was classified {{{AskForClassification.classification}}}"/>
<bpmn:property name="mode" default="append"/>
<bpmn:property name="minor" default="1"/>
<bpmn:incoming>FromGatewayToAppendWikipage</bpmn:incoming>
<bpmn:outgoing>FromAppendWikipageToSendMail</bpmn:outgoing>
</bpmn:task>
<bpmn:sequenceFlow id="FromAppendWikipageToSendMail" sourceRef="AppendWikipage" targetRef="SendMail" />
<bpmn:endEvent id="TheEnd">
<bpmn:incoming>FromSendMailToTheEnd</bpmn:incoming>
</bpmn:endEvent>
</bpmn:process>
</bpmn:definitions>

workflows-activity-editpage-summary

Creating a workflow trigger

For the workflow to appear in the wiki, we need to define a trigger:

  1. Click Workflow triggers in the Global actions menu.
  2. Click Add new trigger.
  3. Select the option Manual from the dropdown menu.
  4. Click Continue.
  5. Define the settings for the workflow trigger:
    • Name: Name that is displayed in the workflow selection menu.
    • Description: Explanation of the function and special features of this trigger.
    • Workflow to start: Workflow triggered by this trigger. In our case Classificiation-workflow.
    • Initial data for the workflow (optional): - Standard comment suggestion.
    • Conditions (optional): In which namespaces the workflow is displayed for selection.
  6. Click Save.


Your workflow is now ready to be tested.

Testing the workflow

The workflow is now available in the wiki. You should test whether the following functionality is available:

  • The workflow is available to be started in the namespaces defined in the workflow trigger (if there are restrictions here).
  • The workflow is triggered.
  • The workflow is listed in the Worklfows Overview page.
  • The assigned user received a task.
  • The workflow completes correctly in case A and B.

Using bpmn.io to create workflow definitions

Such a diagram can be created with the free bpmn.io service. The resulting BPMN file needs to be modified, before it can actually be imported and used in the wiki.



PDF exclude - start

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

PDF exclude - end