BlueSpice Helpdesk - User contributions [en]

How to debug

2023-12-15T15:50:57Z

Rvogel:

==Help others to help you==
Sometimes things go wrong. In many cases the user is then confronted with cryptic or no error messages at all. This page provides help about getting more information about what exactly went wrong, so it can be fixed quickly. This is especially important when asking for help on locations like [https://community.bluespice.com community.bluespice.com].

Additional information can also be found at [[mediawikiwiki:Manual:How_to_debug|"Manual:How to debug" on MediaWiki.org]].

{{Textbox|boxtype=warning|header=Check for sensitive information|text=Most of the techniques described here will output very detailed information about the error, but also about the system and the context. The output may contain sensitive information like usernames, passwords, pathes, access-keys and many more. Before posting any information retrieved by this kind of debugging on a public location (like [https://community.bluespice.com community.bluespice.com]), make sure to redact all potential sensitive information!|icon=yes}}

== Generic information ==
In general it is a good idea to provide additional context information about the error. Usually this information is easily to access/gather by the one who reports an error and very valueable to anyone trying to help.

Such information can be
* Browser used (Firefox, Chrome, Edge, ...), ideally with the version
* URLs (which page the error occurs on, additional parameters that may play into the error)
* User permission level or role (admin, reader, editor, reviewer, ...)

Again: Be careful if the shared information contains sensible data and redact it if required.

== Server side debugging ==
There are various ways to get more information about errors by changing some configuration on the server side.

=== Wiki application ===

==== Enable detailed error reporting ====
Within you <code>LocalSettings.php</code> file, please add the following lines:<syntaxhighlight lang="php">
$GLOBALS['wgShowSQLErrors'] = true;
$GLOBALS['wgDebugDumpSql'] = true;
$GLOBALS['wgShowExceptionDetails'] = true;
$GLOBALS['wgShowDBErrorBacktrace'] = true;

</syntaxhighlight>This will turn error messages like <code>internal_api_error_DBQueryError</code> into a more detailed stack of program calls, including database queries and responses.

==== General debug log ====
Sometimes it can be useful to see all debugging information the application produces. To enable this general debug log please add the following lines within you <code>LocalSettings.php</code> file:<syntaxhighlight lang="php">
if ( isset( $_GET['dodebuglog'] ) ) {
$GLOBALS['wgDebugLogFile'] = "$IP/cache/debug.log";
}

</syntaxhighlight>Be aware that this configuration is set conditionally. It will only be used if the URL accessed in the browser contains some query string like <code>dodebuglog=1</code>. This is to allow a more isolated debug log file. Otherwise other requests (like calls to the <code>load.php</code> entrypoint for CSS and JS content) may also add into this file, which makes analysis more difficult.

==== Log channels ====

== Client side debugging ==
Many errors occur only on the client and server side debugging will not help. In such cases the webbrowser can be used to retrieve more information.

=== Browser development tools ===
Most modern browsers have sophisticated development tools. Usually they can be accessed by pressing the <code>F12</code> key on the keyboard.

==== JavaScript console ====
When some interface element (button, dialog, ...) does not behave like it should, it is usually worth checking the browsers JavaScript console.

{{Textbox|boxtype=tip|header=Nothing listed?|text=Sometimes it may be required to re-do the action that lead to the error with ''open console'' rather than opening it later.}}

'''Example:'''

[[File:How_to_debug_JS_console_01.png|center|frame]]

One can click the link on the right side of the line to see the location of where the error has emerged from.

'''Example:'''

[[File:How_to_debug_JS_console_02.png|center|frame]]

====Network panel====
Sometimes network communication in the background of the application fails. In such cases, the "Network" panel of the browsers developer tools may reveal more information.

The error is also shown in the "Console" tab.

'''Example:'''

[[File:How_to_debug_Network_panel_01.png|center|frame]]

When in the "Network" panel, one can select the faulty request from the list to get more information.

'''Example:'''

[[File:How_to_debug_Network_panel_02.png|center|frame]]

The various tabs "Header", "Payload", "Response", etc. can provide useful information. When reporting such an issue, you can just "copy" the information using the context menu.

'''Example:'''

[[File:How_to_debug_Network_panel_03.png|center|frame]]

How to debug

2023-12-15T15:50:06Z

Rvogel:

==Help others to help you==
Sometimes things go wrong. In many cases the user is then confronted with cryptic or no error messages at all. This page provides help about getting more information about what exactly went wrong, so it can be fixed quickly. This is especially important when asking for help on locations like [https://community.bluespice.com community.bluespice.com].

Additional information can also be found at [[mediawikiwiki:Manual:How_to_debug|"Manual:How to debug" on MediaWiki.org]].

{{Textbox|boxtype=warning|header=Check for sensitive information|text=Most of the techniques described here will output very detailed information about the error, but also about the system and the context. The output may contain sensitive information like usernames, passwords, pathes, access-keys and many more. Before posting any information retrieved by this kind of debugging on a public location (like [https://community.bluespice.com community.bluespice.com]), make sure to redact all potential sensitive information!|icon=yes}}

== Generic information ==
In general it is a good idea to provide additional context information about the error. Usually this information is easily to access/gather by the one who reports an error and very valueable to anyone trying to help.

Such information can be
* Browser used (Firefox, Chrome, Edge, ...), ideally with the version
* URLs (which page the error occurs on, additional parameters that may play into the error)
* User permission level or role (admin, reader, editor, reviewer, ...)

Again: Be careful if the shared information contains sensible data and redact it if required.

== Server side debugging ==
There are various ways to get more information about errors by changing some configuration on the server side.

=== Wiki application ===

==== Enable detailed error reporting ====
Within you <code>LocalSettings.php</code> file, please add the following lines:<syntaxhighlight lang="php">
$GLOBALS['wgShowSQLErrors'] = true;
$GLOBALS['wgDebugDumpSql'] = true;
$GLOBALS['wgShowExceptionDetails'] = true;
$GLOBALS['wgShowDBErrorBacktrace'] = true;

</syntaxhighlight>This will turn error messages like <code>internal_api_error_DBQueryError</code> into a more detailed stack of program calls, including database queries and responses.

==== General debug log ====
Sometimes it can be useful to see all debugging information the application produces. To enable this general debug log please add the following lines within you <code>LocalSettings.php</code> file:<syntaxhighlight lang="php">
if ( isset( $_GET['dodebuglog'] ) ) {
$GLOBALS['wgDebugLogFile'] = "$IP/cache/debug.log";
}

</syntaxhighlight>Be aware that this configuration is set conditionally. It will only be used if the URL accessed in the browser contains some query string like <code>dodebuglog=1</code>. This is to allow a more isolated debug log file. Otherwise other requests (like calls to the <code>load.php</code> entrypoint for CSS and JS content) may also add into this file, which makes analysis more difficult.

==== Log channels ====

== Client side debugging ==
Many errors occur only on the client and server side debugging will not help. In such cases the webbrowser can be used to retrieve more information.

=== Browser development tools ===
Most modern browsers have sophisticated development tools. Usually they can be accessed by pressing the <code>F12</code> key on the keyboard.

==== JavaScript console ====
When some interface element (button, dialog, ...) does not behave like it should, it is usually worth checking the browsers JavaScript console.

{{Textbox|boxtype=tip|header=Nothing listed?|text=Sometimes it may be required to re-do the action that lead to the error with ''open console'' rather than opening it later.}}
'''Example:'''
[[File:How_to_debug_JS_console_01.png|center|frame]]
One can click the link on the right side of the line to see the location of where the error has emerged from.

'''Example:'''
[[File:How_to_debug_JS_console_02.png|center|frame]]

====Network panel====
Sometimes network communication in the background of the application fails. In such cases, the "Network" panel of the browsers developer tools may reveal more information.

The error is also shown in the "Console" tab.

'''Example:'''[[File:How_to_debug_Network_panel_01.png|center|frame]]When in the "Network" panel, one can select the faulty request from the list to get more information.

'''Example:'''[[File:How_to_debug_Network_panel_02.png|center|frame]]The various tabs "Header", "Payload", "Response", etc. can provide useful information. When reporting such an issue, you can just "copy" the information using the context menu.

'''Example:'''[[File:How_to_debug_Network_panel_03.png|center|frame]]

How to debug

2023-12-15T15:43:32Z

Rvogel:

==Help others to help you==
Sometimes things go wrong. In many cases the user is then confronted with cryptic or no error messages at all. This page provides help about getting more information about what exactly went wrong, so it can be fixed quickly. This is especially important when asking for help on locations like [https://community.bluespice.com community.bluespice.com].

Additional information can also be found at [[mediawikiwiki:Manual:How_to_debug|"Manual:How to debug" on MediaWiki.org]].

{{Textbox|boxtype=warning|header=Check for sensitive information|text=Most of the techniques described here will output very detailed information about the error, but also about the system and the context. The output may contain sensitive information like usernames, passwords, pathes, access-keys and many more. Before posting any information retrieved by this kind of debugging on a public location (like [https://community.bluespice.com community.bluespice.com]), make sure to redact all potential sensitive information!|icon=yes}}

== Generic information ==
In general it is a good idea to provide additional context information about the error. Usually this information is easily to access/gather by the one who reports an error and very valueable to anyone trying to help.

Such information can be
* Browser used (Firefox, Chrome, Edge, ...), ideally with the version
* URLs (which page the error occurs on, additional parameters that may play into the error)
* User permission level or role (admin, reader, editor, reviewer, ...)

Again: Be careful if the shared information contains sensible data and redact it if required.

== Server side debugging ==
There are various ways to get more information about errors by changing some configuration on the server side.

=== Wiki application ===

==== Enable detailed error reporting ====
Within you <code>LocalSettings.php</code> file, please add the following lines:<syntaxhighlight lang="php">
$GLOBALS['wgShowSQLErrors'] = true;
$GLOBALS['wgDebugDumpSql'] = true;
$GLOBALS['wgShowExceptionDetails'] = true;
$GLOBALS['wgShowDBErrorBacktrace'] = true;

</syntaxhighlight>This will turn error messages like <code>internal_api_error_DBQueryError</code> into a more detailed stack of program calls, including database queries and responses.

==== General debug log ====
Sometimes it can be useful to see all debugging information the application produces. To enable this general debug log please add the following lines within you <code>LocalSettings.php</code> file:<syntaxhighlight lang="php">
if ( isset( $_GET['dodebuglog'] ) ) {
$GLOBALS['wgDebugLogFile'] = "$IP/cache/debug.log";
}

</syntaxhighlight>Be aware that this configuration is set conditionally. It will only be used if the URL accessed in the browser contains some query string like <code>dodebuglog=1</code>. This is to allow a more isolated debug log file. Otherwise other requests (like calls to the <code>load.php</code> entrypoint for CSS and JS content) may also add into this file, which makes analysis more difficult.

==== Log channels ====

== Client side debugging ==
Many errors occur only on the client and server side debugging will not help. In such cases the webbrowser can be used to retrieve more information.

=== Browser development tools ===
Most modern browsers have sophisticated development tools. Usually they can be accessed by pressing the <code>F12</code> key on the keyboard.

==== JavaScript console ====
When some interface element (button, dialog, ...) does not behave like it should, it is usually worth checking the browsers JavaScript console.

{{Textbox|boxtype=tip|header=Nothing listed?|text=Sometimes it may be required to re-do the action that lead to the error with ''open console'' rather than opening it later.}}
[[File:How_to_debug_JS_console_01.png|center|frame]]
'''Example:'''
[[File:How_to_debug_JS_console_02.png|center|frame]]

==== Network panel ====
[[File:How_to_debug_Network_panel_01.png|center|frame]]
[[File:How_to_debug_Network_panel_02.png|center|frame]]
[[File:How_to_debug_Network_panel_03.png|center|frame]]

How to debug

2023-12-13T10:09:30Z

Rvogel:

==Help others to help you==
Sometimes things go wrong. In many cases the user is then confronted with cryptic or no error messages at all. This page provides help about getting more information about what exactly went wrong, so it can be fixed quickly. This is especially important when asking for help on locations like [https://community.bluespice.com community.bluespice.com].

Additional information can also be found at [[mediawikiwiki:Manual:How_to_debug|"Manual:How to debug" on MediaWiki.org]].

{{Textbox|boxtype=warning|header=Check for sensitive information|text=Most of the techniques described here will output very detailed information about the error, but also about the system and the context. The output may contain sensitive information like usernames, passwords, pathes, access-keys and many more. Before posting any information retrieved by this kind of debugging on a public location (like [https://community.bluespice.com community.bluespice.com]), make sure to redact all potential sensitive information!|icon=yes}}

== Generic information ==
In general it is a good idea to provide additional context information about the error. Usually this information is easily to access/gather by the one who reports an error and very valueable to anyone trying to help.

Such information can be
* Browser used (Firefox, Chrome, Edge, ...), ideally with the version
* URLs (which page the error occurs on, additional parameters that may play into the error)
* User permission level or role (admin, reader, editor, reviewer, ...)

Again: Be careful if the shared information contains sensible data and redact it if required.

== Server side debugging ==
There are various ways to get more information about errors by changing some configuration on the server side.

=== Wiki application ===

==== Enable detailed error reporting ====
Within you <code>LocalSettings.php</code> file, please add the following lines:<syntaxhighlight lang="php">
$GLOBALS['wgShowSQLErrors'] = true;
$GLOBALS['wgDebugDumpSql'] = true;
$GLOBALS['wgShowExceptionDetails'] = true;
$GLOBALS['wgShowDBErrorBacktrace'] = true;

</syntaxhighlight>This will turn error messages like <code>internal_api_error_DBQueryError</code> into a more detailed stack of program calls, including database queries and responses.

==== General debug log ====
Sometimes it can be useful to see all debugging information the application produces. To enable this general debug log please add the following lines within you <code>LocalSettings.php</code> file:<syntaxhighlight lang="php">
if ( isset( $_GET['dodebuglog'] ) ) {
$GLOBALS['wgDebugLogFile'] = "$IP/cache/debug.log";
}

</syntaxhighlight>Be aware that this configuration is set conditionally. It will only be used if the URL accessed in the browser contains some query string like <code>dodebuglog=1</code>. This is to allow a more isolated debug log file. Otherwise other requests (like calls to the <code>load.php</code> entrypoint for CSS and JS content) may also add into this file, which makes analysis more difficult.

==== Log channels ====

== Client side debugging ==
Many errors occur only on the client and server side debugging will not help. In such cases the webbrowser can be used to retrieve more information.

=== Browser development tools ===
Most modern browsers have sophisticated development tools. Usually they can be accessed by pressing the <code>F12</code> key on the keyboard.

==== JavaScript console ====
When some interface element (button, dialog, ...) does not behave like it should, it is usually worth checking the browsers JavaScript console.

{{Textbox|boxtype=tip|header=Nothing listed?|text=Sometimes it may be required to re-do the action that lead to the error with ''open console'' rather than opening it later.}}

'''Example:'''
[[File:How_to_debug_JS_console_01.png]]

[[File:How_to_debug_JS_console_02.png]]

==== Network panel ====

[[File:How_to_debug_Network_panel_01.png]]

[[File:How_to_debug_Network_panel_02.png]]

[[File:How_to_debug_Network_panel_03.png]]

How to debug

2023-12-13T10:07:23Z

Rvogel:

==Help others to help you==
Sometimes things go wrong. In many cases the user is then confronted with cryptic or no error messages at all. This page provides help about getting more information about what exactly went wrong, so it can be fixed quickly. This is especially important when asking for help on locations like [https://community.bluespice.com community.bluespice.com].

Additional information can also be found at [[mediawikiwiki:Manual:How_to_debug|"Manual:How to debug" on MediaWiki.org]].

{{Textbox|boxtype=warning|header=Check for sensitive information|text=Most of the techniques described here will output very detailed information about the error, but also about the system and the context. The output may contain sensitive information like usernames, passwords, pathes, access-keys and many more. Before posting any information retrieved by this kind of debugging on a public location (like [https://community.bluespice.com community.bluespice.com]), make sure to redact all potential sensitive information!|icon=yes}}

== Generic information ==
In general it is a good idea to provide additional context information about the error. Usually this information is easily to access/gather by the one who reports an error and very valueable to anyone trying to help.

Such information can be
* Browser used (Firefox, Chrome, Edge, ...), ideally with the version
* URLs (which page the error occurs on, additional parameters that may play into the error)
* User permission level or role (admin, reader, editor, reviewer, ...)

Again: Be careful if the shared information contains sensible data and redact it if required.

== Server side debugging ==
There are various ways to get more information about errors by changing some configuration on the server side.

=== Wiki application ===

==== Enable detailed error reporting ====
Within you <code>LocalSettings.php</code> file, please add the following lines:<syntaxhighlight lang="php">
$GLOBALS['wgShowSQLErrors'] = true;
$GLOBALS['wgDebugDumpSql'] = true;
$GLOBALS['wgShowExceptionDetails'] = true;
$GLOBALS['wgShowDBErrorBacktrace'] = true;

</syntaxhighlight>This will turn error messages like <code>internal_api_error_DBQueryError</code> into a more detailed stack of program calls, including database queries and responses.

==== General debug log ====
Sometimes it can be useful to see all debugging information the application produces. To enable this general debug log please add the following lines within you <code>LocalSettings.php</code> file:<syntaxhighlight lang="php">
if ( isset( $_GET['dodebuglog'] ) ) {
$GLOBALS['wgDebugLogFile'] = "$IP/cache/debug.log";
}

</syntaxhighlight>Be aware that this configuration is set conditionally. It will only be used if the URL accessed in the browser contains some query string like <code>dodebuglog=1</code>. This is to allow a more isolated debug log file. Otherwise other requests (like calls to the <code>load.php</code> entrypoint for CSS and JS content) may also add into this file, which makes analysis more difficult.

==== Log channels ====

== Client side debugging ==
Many errors occur only on the client and server side debugging will not help. In such cases the webbrowser can be used to retrieve more information.

=== Browser development tools ===
Most modern browsers have sophisticated development tools. Usually they can be accessed by pressing the <code>F12</code> key on the keyboard.

==== JavaScript console ====
When some interface element (button, dialog, ...) does not behave like it should, it is usually worth checking the browsers JavaScript console.

{{Textbox|boxtype=info|text=Sometimes it may be required to re-do the action that lead to the error with ''open console'' rather than opening it later.}}

'''Example:'''
[[File:How_to_debug_JS_console_01.png]]

[[File:How_to_debug_JS_console_02.png]]

==== Network panel ====

[[File:How_to_debug_Network_panel_01.png]]

[[File:How_to_debug_Network_panel_02.png]]

[[File:How_to_debug_Network_panel_03.png]]

File:How to debug Network panel 03.png

2023-12-13T09:55:38Z

Rvogel:

File:How to debug Network panel 02.png

2023-12-13T09:55:11Z

Rvogel:

File:How to debug Network panel 01.png

2023-12-13T09:54:50Z

Rvogel:

File:How to debug JS console 02.png

2023-12-13T09:54:10Z

Rvogel:

File:How to debug JS console 01.png

2023-12-13T09:53:43Z

Rvogel:

How to debug

2023-12-13T09:53:17Z

Rvogel:

Sometimes things go wrong. In many cases the user is then confronted with cryptic or no error messages at all. This page provides help about getting more information about what exactly went wrong, so it can be fixed quickly. This is especially important when asking for help on locations like [https://community.bluespice.com community.bluespice.com].

Additional information can also be found at [[mediawikiwiki:Manual:How_to_debug|"Manual:How to debug" on MediaWiki.org]].{{Textbox|boxtype=warning|header=Check for sensitive information|text=Most of the techniques described here will output very detailed information about the error, but also about the system and the context. The output may contain sensitive information like usernames, passwords, pathes, access-keys and many more. Before posting any information retrieved by this kind of debugging on a public location (like [https://community.bluespice.com community.bluespice.com]), make sure to redact all potential sensitive information!|icon=yes}}

== Server side debugging ==
There are various ways to get more information about errors by changing some configuration on the server side.

=== Wiki application ===

==== Enable detailed error reporting ====
Within you <code>LocalSettings.php</code> file, please add the following lines:<syntaxhighlight lang="php">
$GLOBALS['wgShowSQLErrors'] = true;
$GLOBALS['wgDebugDumpSql'] = true;
$GLOBALS['wgShowExceptionDetails'] = true;
$GLOBALS['wgShowDBErrorBacktrace'] = true;

</syntaxhighlight>This will turn error messages like <code>internal_api_error_DBQueryError</code> into a more detailed stack of program calls, including database queries and responses.

==== General debug log ====
Sometimes it can be useful to see all debugging information the application produces. To enable this general debug log please add the following lines within you <code>LocalSettings.php</code> file:<syntaxhighlight lang="php">
if ( isset( $_GET['dodebuglog'] ) ) {
$GLOBALS['wgDebugLogFile'] = "$IP/cache/debug.log";
}

</syntaxhighlight>Be aware that this configuration is set conditionally. It will only be used if the URL accessed in the browser contains some query string like <code>dodebuglog=1</code>. This is to allow a more isolated debug log file. Otherwise other requests (like calls to the <code>load.php</code> entrypoint for CSS and JS content) may also add into this file, which makes analysis more difficult.

==== Log channels ====

== Client side debugging ==
Many errors occur only on the client and server side debugging will not help. In such cases the webbrowser can be used to retrieve more information.

=== Browser development tools ===
Most modern browsers have sophisticated development tools. Usually they can be accessed by pressing the <code>F12</code> key on the keyboard.

==== JavaScript console ====

[[File:How_to_debug_JS_console_01.png]]

[[File:How_to_debug_JS_console_02.png]]

==== Network panel ====

[[File:How_to_debug_Network_panel_01.png]]

[[File:How_to_debug_Network_panel_02.png]]

[[File:How_to_debug_Network_panel_03.png]]

Manual:Extension/Workflows/Tutorial

2023-12-08T13:09:08Z

Rvogel:

{{DISPLAYTITLE:Creating a custom 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.

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]]

==Steps==
To create the workflow, the following steps are necessary:

#Creating a 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>
#Creating and connecting the '''classification form''' that allows the assigned user to classify the document. <code>MediaWiki:ContentClassificationRequest.form</code>
#Adding a '''trigger''' to the wiki that defines where and how to start the workflow.

==Instructions==

===Creating a custom workflow definition===
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:

*Line 1: The xml prolog
*Line 2: The definitions element, which denotes the namespaces where the workflow elements are defined.
*Line3: The process element, which contains all other elements.
*Line 5: The workflow runs in the context of a specific revision of a wiki page.
*Line 11: The workflow needs a startEvent and
*Line 18: The workflow needs an endEvent.
<syntaxhighlight lang="xml" line="1">
<?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:endEvent id="TheEnd">
<bpmn:incoming>FromSendMailToTheEnd</bpmn:incoming>
</bpmn:endEvent>

</bpmn:process>

</bpmn:definitions>
</syntaxhighlight>
The above stub xml only features the "Start" and "End" event including - yet to be defined - "outgoing" and "incoming" flow references.

====Creating and connecting an 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.

[[File:WF-Tutorial initForm.png|alt=Worfklow initiation form|center|thumb|550x550px|Worfklow initiation form]]
To create the initiation form:

#'''Create''' the page <code>MediaWiki:ContentClassificationInit.form</code>
#'''Paste''' the following form definition in source edit mode:<syntaxhighlight lang="json">
{
"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"
}
]
}

</syntaxhighlight>
#'''Save''' the page.

Next, we tell the BPMN with the following userTask to show the form: <syntaxhighlight lang="xml">
<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" />

</syntaxhighlight>Let's look at what this does:

*The <code>id</code> and <code>name</code> 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" />'':<syntaxhighlight lang="xml" line="1">
<?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>
</syntaxhighlight>

====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:

#'''Create''' the page <code>MediaWiki:ContentClassificationRequest.form</code>
#'''Paste''' the following form definition in source edit mode:
<syntaxhighlight lang="json">
{
"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
}
]
}
</syntaxhighlight>

Next, we tell the BPMN to show the form to user that receives the workflow task. For that, we add a ''userTask'' activity:
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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 <code>assigned_user</code> 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 <code><nowiki>{{#show}}</nowiki></code> 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 <code>TheBoss</code> (assuming that such a user exists on the wiki). The <code><nowiki>{{ROOTPAGENAME}}</nowiki></code> variable is just an easy way to strip the "User" namespace, if the looked up value was something like <code>User:JaneDoe</code> instead of just <code>JaneDoe</code>.
*'''due date:''' The <code>due_date</code> 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 <code><nowiki>{{#time}}</nowiki></code> parserfunction.
*'''classification:''' The <code>classification</code> 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:

#If the assigned user classified the document as Class A (CLSA), an email will be sent to the legal department.
#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"
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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:<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

====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:<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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: s''ets 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.

====The final BPMN====
In the end, the bpmn page for the workflow looks like this:
<syntaxhighlight lang="xml" line="1">
<?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>
</syntaxhighlight>

workflows-activity-editpage-summary

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

#'''Click''' ''Workflow triggers'' in the Global actions menu.
#'''Click''' ''Add new trigger''.
#'''Select''' the option ''Manual'' from the dropdown menu.
#'''Click''' ''Continue''.
#'''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.
#'''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 [https://bpmn.io/ bpmn.io] service. The [[Media:Manual:Workflows-tutorial-raw.bpmn.xml|resulting BPMN file]] needs to be modified, before it can actually be imported and used in the wiki.

[[de:Handbuch:Erweiterung/Workflows/Tutorial]]
[[en:{{FULLPAGENAME}}]]

Manual:Extension/Workflows/Tutorial

2023-12-08T12:53:02Z

Rvogel:

{{DISPLAYTITLE:Creating a custom 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.

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]]

==Steps==
To create the workflow, the following steps are necessary:

#Creating a 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>
#Creating and connecting the '''classification form''' that allows the assigned user to classify the document. <code>MediaWiki:ContentClassificationRequest.form</code>
#Adding a '''trigger''' to the wiki that defines where and how to start the workflow.

==Instructions==

===Creating a custom workflow definition===
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:

*Line 1: The xml prolog
*Line 2: The definitions element, which denotes the namespaces where the workflow elements are defined.
*Line3: The process element, which contains all other elements.
*Line 5: The workflow runs in the context of a specific revision of a wiki page.
*Line 11: The workflow needs a startEvent and
*Line 18: The workflow needs an endEvent.
<syntaxhighlight lang="xml" line="1">
<?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:endEvent id="TheEnd">
<bpmn:incoming>FromSendMailToTheEnd</bpmn:incoming>
</bpmn:endEvent>

</bpmn:process>

</bpmn:definitions>
</syntaxhighlight>
The above stub xml only features the "Start" and "End" event including - yet to be defined - "outgoing" and "incoming" flow references.

====Creating and connecting an 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.

[[File:WF-Tutorial initForm.png|alt=Worfklow initiation form|center|thumb|550x550px|Worfklow initiation form]]
To create the initiation form:

#'''Create''' the page <code>MediaWiki:ContentClassificationInit.form</code>
#'''Paste''' the following form definition in source edit mode:<syntaxhighlight lang="json">
{
"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"
}
]
}

</syntaxhighlight>
#'''Save''' the page.

Next, we tell the BPMN with the following userTask to show the form: <syntaxhighlight lang="xml">
<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" />

</syntaxhighlight>Let's look at what this does:

*The <code>id</code> and <code>name</code> 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" />'':<syntaxhighlight lang="xml" line="1">
<?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>
</syntaxhighlight>

====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:

#'''Create''' the page <code>MediaWiki:ContentClassificationRequest.form</code>
#'''Paste''' the following form definition in source edit mode:
<syntaxhighlight lang="json">
{
"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
}
]
}
</syntaxhighlight>

Next, we tell the BPMN to show the form to user that receives the workflow task. For that, we add a ''userTask'' activity:
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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 <code>assigned_user</code> 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 <code><nowiki>{{#show}}</nowiki></code> 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 <code>TheBoss</code> (assuming that such a user exists on the wiki). The <code><nowiki>{{ROOTPAGENAME}}</nowiki></code> variable is just an easy way to strip the "User" namespace, if the looked up value was something like <code>User:JaneDoe</code> instead of just <code>JaneDoe</code>.
*'''due date:''' The <code>due_date</code> 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 <code><nowiki>{{#time}}</nowiki></code> parserfunction.
*'''classification:''' The <code>classification</code> 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:

#If the assigned user classified the document as Class A (CLSA), an email will be sent to the legal department.
#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"
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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:<syntaxhighlight lang="xml">
...
<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 "Class A" 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" />
...
</syntaxhighlight>

====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:<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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: s''ets 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.

====The final BPMN====
In the end, the bpmn page for the workflow looks like this:
<syntaxhighlight lang="xml" line="1">
<?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 "Class A" 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>
</syntaxhighlight>

workflows-activity-editpage-summary

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

#'''Click''' ''Workflow triggers'' in the Global actions menu.
#'''Click''' ''Add new trigger''.
#'''Select''' the option ''Manual'' from the dropdown menu.
#'''Click''' ''Continue''.
#'''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.
#'''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 [https://bpmn.io/ bpmn.io] service. The [[Media:Manual:Workflows-tutorial-raw.bpmn.xml|resulting BPMN file]] needs to be modified, before it can actually be imported and used in the wiki.

[[de:Handbuch:Erweiterung/Workflows/Tutorial]]
[[en:{{FULLPAGENAME}}]]

Manual:Extension/Workflows/Tutorial

2023-12-08T12:51:33Z

Rvogel:

{{DISPLAYTITLE:Creating a custom 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.

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]]

==Steps==
To create the workflow, the following steps are necessary:

#Creating a 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>
#Creating and connecting the '''classification form''' that allows the assigned user to classify the document. <code>MediaWiki:ContentClassificationRequest.form</code>
#Adding a '''trigger''' to the wiki that defines where and how to start the workflow.

==Instructions==

===Creating a custom workflow definition===
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:

*Line 1: The xml prolog
*Line 2: The definitions element, which denotes the namespaces where the workflow elements are defined.
*Line3: The process element, which contains all other elements.
*Line 5: The workflow runs in the context of a specific revision of a wiki page.
*Line 11: The workflow needs a startEvent and
*Line 18: The workflow needs an endEvent.
<syntaxhighlight lang="xml" line="1">
<?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:endEvent id="TheEnd">
<bpmn:incoming>FromSendMailToTheEnd</bpmn:incoming>
</bpmn:endEvent>

</bpmn:process>

</bpmn:definitions>
</syntaxhighlight>
The above stub xml only features the "Start" and "End" event including - yet to be defined - "outgoing" and "incoming" flow references.

====Creating and connecting an 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.

[[File:WF-Tutorial initForm.png|alt=Worfklow initiation form|center|thumb|550x550px|Worfklow initiation form]]
To create the initiation form:

#'''Create''' the page <code>MediaWiki:ContentClassificationInit.form</code>
#'''Paste''' the following form definition in source edit mode:<syntaxhighlight lang="json">
{
"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"
}
]
}

</syntaxhighlight>
#'''Save''' the page.

Next, we tell the BPMN with the following userTask to show the form: <syntaxhighlight lang="xml">
<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" />

</syntaxhighlight>Let's look at what this does:

*The <code>id</code> and <code>name</code> 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" />'':<syntaxhighlight lang="xml" line="1">
<?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>
</syntaxhighlight>

====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:

#'''Create''' the page <code>MediaWiki:ContentClassificationRequest.form</code>
#'''Paste''' the following form definition in source edit mode:
<syntaxhighlight lang="json">
{
"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
}
]
}
</syntaxhighlight>

Next, we tell the BPMN to show the form to user that receives the workflow task. For that, we add a ''userTask'' activity:
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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 <code>assigned_user</code> 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 <code><nowiki>{{#show}}</nowiki></code> 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 <code>TheBoss</code> (assuming that such a user exists on the wiki). The <code><nowiki>{{ROOTPAGENAME}}</nowiki></code> variable is just an easy way to strip the "User" namespace, if the looked up value was something like <code>User:JaneDoe</code> instead of just <code>JaneDoe</code>.
*'''due date:''' The <code>due_date</code> 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 <code><nowiki>{{#time}}</nowiki></code> parserfunction.
*'''classification:''' The <code>classification</code> 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:

#If the assigned user classified the document as Class A (CLSA), an email will be sent to the legal department.
#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"
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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:<syntaxhighlight lang="xml">
...
<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 "Class A" 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" />
...
</syntaxhighlight>

====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:<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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: s''ets 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.

====The final BPMN====
In the end, the bpmn page for the workflow looks like this:
<syntaxhighlight lang="xml" line="1">
<?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 "Class A" 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>
</syntaxhighlight>

workflows-activity-editpage-summary

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

#'''Click''' ''Workflow triggers'' in the Global actions menu.
#'''Click''' ''Add new trigger''.
#'''Select''' the option ''Manual'' from the dropdown menu.
#'''Click''' ''Continue''.
#'''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.
#'''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 [https://bpmn.io/ bpmn.io] service. The [[Media:Manual:Workflows-tutorial-raw.bpmn.xml|resulting BPMN file]] needs to be modified, before it can actually be imported and used in the wiki.

[[de:Handbuch:Erweiterung/Workflows/Tutorial]]
[[en:{{FULLPAGENAME}}]]

Manual:Extension/Workflows/Tutorial

2023-12-08T12:50:11Z

Rvogel:

{{DISPLAYTITLE:Creating a custom 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.

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]]

==Steps==
To create the workflow, the following steps are necessary:

#Creating a 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>
#Creating and connecting the '''classification form''' that allows the assigned user to classify the document. <code>MediaWiki:ContentClassificationRequest.form</code>
#Adding a '''trigger''' to the wiki that defines where and how to start the workflow.

==Instructions==

===Creating a custom workflow definition===
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:

*Line 1: The xml prolog
*Line 2: The definitions element, which denotes the namespaces where the workflow elements are defined.
*Line3: The process element, which contains all other elements.
*Line 5: The workflow runs in the context of a specific revision of a wiki page.
*Line 11: The workflow needs a startEvent and
*Line 18: The workflow needs an endEvent.
<syntaxhighlight lang="xml" line="1">
<?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:endEvent id="TheEnd">
<bpmn:incoming>FromSendMailToTheEnd</bpmn:incoming>
</bpmn:endEvent>

</bpmn:process>

</bpmn:definitions>
</syntaxhighlight>
The above stub xml only features the "Start" and "End" event including - yet to be defined - "outgoing" and "incoming" flow references.

====Creating and connecting an 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.

[[File:WF-Tutorial initForm.png|alt=Worfklow initiation form|center|thumb|550x550px|Worfklow initiation form]]
To create the initiation form:

#'''Create''' the page <code>MediaWiki:ContentClassificationInit.form</code>
#'''Paste''' the following form definition in source edit mode:<syntaxhighlight lang="json">
{
"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"
}
]
}

</syntaxhighlight>
#'''Save''' the page.

Next, we tell the BPMN with the following userTask to show the form: <syntaxhighlight lang="xml">
<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" />

</syntaxhighlight>Let's look at what this does:

*The <code>id</code> and <code>name</code> 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" />'':<syntaxhighlight lang="xml" line="1">
<?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>
</syntaxhighlight>

====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:

#'''Create''' the page <code>MediaWiki:ContentClassificationRequest.form</code>
#'''Paste''' the following form definition in source edit mode:
<syntaxhighlight lang="json">
{
"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
}
]
}
</syntaxhighlight>

Next, we tell the BPMN to show the form to user that receives the workflow task. For that, we add a ''userTask'' activity:
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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 <code>assigned_user</code> 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 <code><nowiki>{{#show}}</nowiki></code> 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 <code>TheBoss</code> (assuming that such a user exists on the wiki). The <code><nowiki>{{ROOTPAGENAME}}</nowiki></code> variable is just an easy way to strip the "User" namespace, if the looked up value was something like <code>User:JaneDoe</code> instead of just <code>JaneDoe</code>.
*'''due date:''' The <code>due_date</code> 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 <code><nowiki>{{#time}}</nowiki></code> parserfunction.
*'''classification:''' The <code>classification</code> 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:

#If the assigned user classified the document as Class A (CLSA), an email will be sent to the legal department.
#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"
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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:<syntaxhighlight lang="xml">
...
<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 "Class A" 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" />
...
</syntaxhighlight>

====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:<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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: s''ets 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.

====The final BPMN====
In the end, the bpmn page for the workflow looks like this:<syntaxhighlight lang="xml" line="1">
<?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 "Class A" 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>

</syntaxhighlight>

workflows-activity-editpage-summary

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

#'''Click''' ''Workflow triggers'' in the Global actions menu.
#'''Click''' ''Add new trigger''.
#'''Select''' the option ''Manual'' from the dropdown menu.
#'''Click''' ''Continue''.
#'''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.
#'''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 [https://bpmn.io/ bpmn.io] service. The [[Media:Manual:Workflows-tutorial-raw.bpmn.xml|resulting BPMN file]] needs to be modified, before it can actually be imported and used in the wiki.

[[de:Handbuch:Erweiterung/Workflows/Tutorial]]
[[en:{{FULLPAGENAME}}]]

Manual:Extension/Workflows/Tutorial

2023-12-08T12:48:30Z

Rvogel:

{{DISPLAYTITLE:Creating a custom 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.

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]]

==Steps==
To create the workflow, the following steps are necessary:

#Creating a 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>
#Creating and connecting the '''classification form''' that allows the assigned user to classify the document. <code>MediaWiki:ContentClassificiationRequest.form</code>
#Adding a '''trigger''' to the wiki that defines where and how to start the workflow.

==Instructions==

===Creating a custom workflow definition===
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:

*Line 1: The xml prolog
*Line 2: The definitions element, which denotes the namespaces where the workflow elements are defined.
*Line3: The process element, which contains all other elements.
*Line 5: The workflow runs in the context of a specific revision of a wiki page.
*Line 11: The workflow needs a startEvent and
*Line 18: The workflow needs an endEvent.
<syntaxhighlight lang="xml" line="1">
<?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:endEvent id="TheEnd">
<bpmn:incoming>FromSendMailToTheEnd</bpmn:incoming>
</bpmn:endEvent>

</bpmn:process>

</bpmn:definitions>
</syntaxhighlight>
The above stub xml only features the "Start" and "End" event including - yet to be defined - "outgoing" and "incoming" flow references.

====Creating and connecting an 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.

[[File:WF-Tutorial initForm.png|alt=Worfklow initiation form|center|thumb|550x550px|Worfklow initiation form]]
To create the initiation form:

#'''Create''' the page <code>MediaWiki:ContentClassificationInit.form</code>
#'''Paste''' the following form definition in source edit mode:<syntaxhighlight lang="json">
{
"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"
}
]
}

</syntaxhighlight>
#'''Save''' the page.

Next, we tell the BPMN with the following userTask to show the form: <syntaxhighlight lang="xml">
<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" />

</syntaxhighlight>Let's look at what this does:

*The <code>id</code> and <code>name</code> 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" />'':<syntaxhighlight lang="xml" line="1">
<?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>
</syntaxhighlight>

====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:

#'''Create''' the page <code>MediaWiki:ContentClassificiationRequest.form</code>
#'''Paste''' the following form definition in source edit mode:
<syntaxhighlight lang="json">
{
"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
}
]
}
</syntaxhighlight>

Next, we tell the BPMN to show the form to user that receives the workflow task. For that, we add a ''userTask'' activity:
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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 <code>assigned_user</code> 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 <code><nowiki>{{#show}}</nowiki></code> 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 <code>TheBoss</code> (assuming that such a user exists on the wiki). The <code><nowiki>{{ROOTPAGENAME}}</nowiki></code> variable is just an easy way to strip the "User" namespace, if the looked up value was something like <code>User:JaneDoe</code> instead of just <code>JaneDoe</code>.
*'''due date:''' The <code>due_date</code> 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 <code><nowiki>{{#time}}</nowiki></code> parserfunction.
*'''classification:''' The <code>classification</code> 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:

#If the assigned user classified the document as Class A (CLSA), an email will be sent to the legal department.
#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"
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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:<syntaxhighlight lang="xml">
...
<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 "Class A" 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" />
...
</syntaxhighlight>

====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:<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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: s''ets 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.

====The final BPMN====
In the end, the bpmn page for the workflow looks like this:<syntaxhighlight lang="xml" line="1">
<?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:ContentClassificiationRequest</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 "Class A" 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>

</syntaxhighlight>

workflows-activity-editpage-summary

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

#'''Click''' ''Workflow triggers'' in the Global actions menu.
#'''Click''' ''Add new trigger''.
#'''Select''' the option ''Manual'' from the dropdown menu.
#'''Click''' ''Continue''.
#'''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.
#'''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 [https://bpmn.io/ bpmn.io] service. The [[Media:Manual:Workflows-tutorial-raw.bpmn.xml|resulting BPMN file]] needs to be modified, before it can actually be imported and used in the wiki.

[[de:Handbuch:Erweiterung/Workflows/Tutorial]]
[[en:{{FULLPAGENAME}}]]

Manual:Extension/Workflows/Tutorial

2023-12-08T12:46:40Z

Rvogel:

{{DISPLAYTITLE:Creating a custom 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.

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]]

==Steps==
To create the workflow, the following steps are necessary:

#Creating a 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>
#Creating and connecting the '''classification form''' that allows the assigned user to classify the document. <code>MediaWiki:ContentClassificiationRequest.form</code>
#Adding a '''trigger''' to the wiki that defines where and how to start the workflow.

==Instructions==

===Creating a custom workflow definition===
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:

*Line 1: The xml prolog
*Line 2: The definitions element, which denotes the namespaces where the workflow elements are defined.
*Line3: The process element, which contains all other elements.
*Line 5: The workflow runs in the context of a specific revision of a wiki page.
*Line 11: The workflow needs a startEvent and
*Line 18: The workflow needs an endEvent.
<syntaxhighlight lang="xml" line="1">
<?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:endEvent id="TheEnd">
<bpmn:incoming>FromSendMailToTheEnd</bpmn:incoming>
</bpmn:endEvent>

</bpmn:process>

</bpmn:definitions>
</syntaxhighlight>
The above stub xml only features the "Start" and "End" event including - yet to be defined - "outgoing" and "incoming" flow references.

====Creating and connecting an 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.

[[File:WF-Tutorial initForm.png|alt=Worfklow initiation form|center|thumb|550x550px|Worfklow initiation form]]
To create the initiation form:

#'''Create''' the page <code>MediaWiki:ContentClassificationInit.form</code>
#'''Paste''' the following form definition in source edit mode:<syntaxhighlight lang="json">
{
"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"
}
]
}

</syntaxhighlight>
#'''Save''' the page.

Next, we tell the BPMN with the following userTask to show the form: <syntaxhighlight lang="xml">
<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" />

</syntaxhighlight>Let's look at what this does:

*The <code>id</code> and <code>name</code> 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" />'':<syntaxhighlight lang="xml" line="1">
<?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>
</syntaxhighlight>

====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:

#'''Create''' the page <code>MediaWiki:ContentClassificiationRequest.form</code>
#'''Paste''' the following form definition in source edit mode:
<syntaxhighlight lang="json">
{
"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
}
]
}
</syntaxhighlight>

Next, we tell the BPMN to show the form to user that receives the workflow task. For that, we add a ''userTask'' activity:
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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 <code>assigned_user</code> 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 <code><nowiki>{{#show}}</nowiki></code> 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 <code>TheBoss</code> (assuming that such a user exists on the wiki). The <code><nowiki>{{ROOTPAGENAME}}</nowiki></code> variable is just an easy way to strip the "User" namespace, if the looked up value was something like <code>User:JaneDoe</code> instead of just <code>JaneDoe</code>.
*'''due date:''' The <code>due_date</code> 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 <code><nowiki>{{#time}}</nowiki></code> parserfunction.
*'''classification:''' The <code>classification</code> 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:

#If the assigned user classified the document as Class A (CLSA), an email will be sent to the legal department.
#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"
<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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:<syntaxhighlight lang="xml">
...
<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 "Class A" 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" />
...
</syntaxhighlight>

====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:<syntaxhighlight lang="xml">
...
<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" />
...
</syntaxhighlight>

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: s''ets 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.

====The final BPMN====
In the end, the bpmn page for the workflow looks like this:<syntaxhighlight lang="xml" line="1">
<?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:ContentClassificiationRequest</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 "Class A" 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>

</syntaxhighlight>

workflows-activity-editpage-summary

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

#'''Click''' ''Workflow triggers'' in the Global actions menu.
#'''Click''' ''Add new trigger''.
#'''Select''' the option ''Manual'' from the dropdown menu.
#'''Click''' ''Continue''.
#'''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.
#'''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 [https://bpmn.io/ bpmn.io] service. The [[Media:Manual:Workflows-tutorial-raw.bpmn.xml|resulting BPMN file]] needs to be modified, before it can actually be imported and used in the wiki.

[[de:Handbuch:Erweiterung/Workflows/Tutorial]]
[[en:{{FULLPAGENAME}}]]

How to debug

2023-12-04T09:52:28Z

Rvogel:

How to debug

2023-12-04T09:33:57Z

Rvogel:

How to debug

2023-12-04T09:17:17Z

Rvogel: Created page with "== Server side debugging == === Wiki application === ==== General debug log ==== ==== Log channels ==== == Client side debugging == === Browser development tools === ==== JavaScript console ==== ==== Network panel ===="

== Server side debugging ==

=== Wiki application ===

==== General debug log ====

==== Log channels ====

== Client side debugging ==

=== Browser development tools ===

==== JavaScript console ====

==== Network panel ====

Debugging

2023-12-04T09:15:00Z

Rvogel: Redirected page to How to debug

#REDIRECT [[How to debug]]

Security:Security Advisories/BSSA-2023-02

2023-10-30T10:56:55Z

Rvogel:

{{Featurepage|featured=true|featuredesc=Current Security Advisory: BSSA-2023-01|featurestart=07/26/2023}}
{| class="wikitable"
|+
!
!
|-
|Date
|2023-10-30
|-
|Severity
|Low
|-
|Affected
|
* BlueSpiceAvatars
|-
|Fixed in
|
* BlueSpiceAvatars 4.3.3
* BlueSpiceAvatars 3.2.10.1
|-
|CVE
|[https://www.cve.org/cverecord?id=CVE-2023-42431 CVE-2023-42431]
|}

== Problem ==

When setting the avatar profile image, one can cause an XSS attack by inserting a modified URL in the dialog. The issue only occurs in the dialog itself and only in the context of the user that applied the change.
== Solution ==
* BlueSpice 4: Update to version 4.3.3
* BlueSpice 3: Update Extension:BlueSpiceAvatars version [https://github.com/wikimedia/mediawiki-extensions-BlueSpiceAvatars/tree/3.2.10.1 3.2.10.1]

== Acknowledgements ==
Special thanks to the security team of an undisclosed customer.

Security:Security Advisories/BSSA-2023-02

2023-10-30T10:53:49Z

Rvogel:

{{Featurepage|featured=true|featuredesc=Current Security Advisory: BSSA-2023-01|featurestart=07/26/2023}}
{| class="wikitable"
|+
!
!
|-
|Date
|2023-10-30
|-
|Severity
|Low
|-
|Affected
|
* BlueSpiceAvatars
|-
|Fixed in
|
* BlueSpiceAvatars 4.3.3
* BlueSpiceAvatars 3.2.10.1
|-
|CVE
|[https://www.cve.org/cverecord?id=CVE-2023-42431 CVE-2023-42431]
|}

== Problem ==

== Solution ==
* BlueSpice 4: Update to version 4.3.3
* BlueSpice 3: Update Extension:BlueSpiceAvatars version [https://github.com/wikimedia/mediawiki-extensions-BlueSpiceAvatars/tree/3.2.10.1 3.2.10.1]

== Resources ==
None

== Acknowledgements ==
Special thanks to the security team of an undisclosed customer.

Security:Security Advisories/BSSA-2023-02

2023-10-30T10:53:17Z

Rvogel:

{{Featurepage|featured=true|featuredesc=Current Security Advisory: BSSA-2023-01|featurestart=07/26/2023}}
{| class="wikitable"
|+
!
!
|-
|Date
|2023-10-30
|-
|Severity
|Low
|-
|Affected
|
* BlueSpiceAvatars
|-
|Fixed in
|
* BlueSpiceAvatars 4.3.3
* BlueSpiceAvatars 3.2.10.1
|-
|CVE
|[https://www.cve.org/cverecord?id=CVE-2023-42431 CVE-2023-42431]
|}

== Problem ==

== Solution ==
* BlueSpice 4: Update to version 4.3.3
* BlueSpice 3: Update Extension:BlueSpiceAvatars version [https://github.com/wikimedia/mediawiki-extensions-BlueSpiceAvatars/tree/3.2.10.1 3.2.10.1]

== Resources ==
None

== Acknowledgements ==
Found during an internal security audit.

Security:Security Advisories/BSSA-2023-02

2023-10-30T10:49:31Z

Rvogel: Created page with "{{Featurepage|featured=true|featuredesc=Current Security Advisory: BSSA-2023-01|featurestart=07/26/2023}} {| class="wikitable" |+ ! ! |- |Date |2023-07-25 |- |Severity |Medium |- |Affected | * BlueSpice Infrastructure: Ghostscript |- |Fixed in | * Ghostscript 9.53.3 and 10.01.2 |- |CVE |[https://www.cve.org/CVERecord?id=CVE-2023-36664 CVE-2023-36664] |} == Problem == A bug in ghostscript can be exploited to run arbitrary code on the host machine using prepared PDF docum..."

{{Featurepage|featured=true|featuredesc=Current Security Advisory: BSSA-2023-01|featurestart=07/26/2023}}
{| class="wikitable"
|+
!
!
|-
|Date
|2023-07-25
|-
|Severity
|Medium
|-
|Affected
|
* BlueSpice Infrastructure: Ghostscript
|-
|Fixed in
|
* Ghostscript 9.53.3 and 10.01.2
|-
|CVE
|[https://www.cve.org/CVERecord?id=CVE-2023-36664 CVE-2023-36664]
|}

== Problem ==
A bug in ghostscript can be exploited to run arbitrary code on the host machine using prepared PDF document. In BlueSpice, when a) PDFHandler is enabled and b) a PDF document is uploaded, a preview image is being generated using ghostscript. If an attacker uploads a prepared PDF, they can execute code on the server.

PDFHandler is not enabled by default, but many installations have set it active.

== Solution ==
Upgrade Ghostscript to a fixed version and ensure the updated version is used by adding <code>$wgPdfProcessor = '/usr/bin/gs';</code> to <code>LocalSettings.php</code>.

If upgrade of Ghostscript is not possible, disable the extension PDFHandler. This, however, removes the ability for BlueSpice to render PDF preview images.

== Resources ==
* For Debian: https://www.debian.org/security/2023/dsa-5446
* For Debian10: [https://security-tracker.debian.org/tracker/source-package/ghostscript Information on source package ghostscript (debian.org)]
* For Ubuntu: https://launchpad.net/ubuntu/+source/ghostscript/9.50~dfsg-5ubuntu4.8

== Acknowledgements ==
Found during an internal security audit.

Setup:Installation Guide/Optimization/Cronjobs

2023-06-14T12:37:47Z

Rvogel: Add

{{DISPLAYTITLE:Cronjobs}}
__TOC__

This document describes cronjobs an related configurations, which should be set for your BlueSpice (depending on the used version).

==Tips for this Document==
{{Setup-document-note}}

{{Messagebox|boxtype=Hinweis|Note text=It is recommended to specify the complete path to php.exe under Windows. For more information, see the [[Setup:Installation_Guide/Services_and_system_configuration/Environment_Variables|environment variables]] document.}}

==runJobs.php==
Time-consuming processes will be moved to a processing queue in the background of BlueSpice. With every page impression, a part of these will be processed. For the case that there are lots of processes in the queue and there are relatively litte page impressions, the tasks will not be processed promptly.

For this reason, the queue should be processed regularly by cronjob.

Create a cronjob (Windows: "Scheduled task") depending on your operating system. The command to execute is:

php <code><installpath-bluespice></code>/maintenance/runJobs.php ''(Linux)''
php.exe <code><installpath-bluespice></code>\maintenance\runJobs.php ''(Windows)''

Execute the cronjob every '''10 minutes'''.

==processRunner.php==
Certain tasks require server resources that can not be provided in the regular context of a webrequest. They will be moved to a special processing queue in the background of BlueSpice.

Create a cronjob (Windows: "Scheduled task") depending on your operating system. The command to execute is:

php <code><installpath-bluespice></code>/vendor/mwstake/mediawiki-component-processmanager/maintenance/processRunner.php <code><installpath-bluespice></code>/maintenance/Maintenance.php --max-processes=100 --wait ''(Linux)''
php.exe <code><installpath-bluespice></code>\vendor\mwstake\mediawiki-component-processmanager\maintenance\processRunner.php <code><installpath-bluespice></code>\maintenance\Maintenance.php --max-processes=100 --wait ''(Windows)''

Execute the cronjob every '''minute'''.

[[en:{{FULLPAGENAME}}]]
[[de:Setup:Installationsanleitung/Optimierungen/Cronjobs]]

Setup:Release Notes/erm/latest

2023-01-23T15:22:51Z

Rvogel:

== BlueSpice ERM 4.2 ==

=== BlueSpice ERM 4.2.4-23.01.23.1 ===
This is an unscheduled release of the BlueSpice ERM 4.2 branch.

The <code>bluespice/bluespice</code> container does now support "HTTP/2".

==== Changes since BlueSpice ERM 4.2.4 ====

* CHANGE: PermissionManager - Configure public access for some namespace (#31083)
* FIX: BSP overload issues (#3098; easysoftware#569052)

Setup:Release Notes/erm/latest

2023-01-23T15:22:34Z

Rvogel: Created page with "== BlueSpice ERM 4.2 == === BlueSpice ERM 4.2.4-23.01.23.1 === This is an unscheduled release of the BlueSpice ERM 4.2 branch. The <code>bluespice/bluespice</code> container..."

Setup:Installation Guide

2022-12-28T09:40:51Z

Rvogel:

{{Messagebox|boxtype=note|icon=|Note text=For general questions regarding the installation, maintenance, and usage of BlueSpice free, go to our [https://sourceforge.net/p/bluespice/discussion/1249668/ SourceForge help forum] .|bgcolor=}}
==Introduction==

We are happy that you decided to install the latest version of BlueSpice 4.

Please follow these steps:

# [[Setup:Installation Guide#Check the system requirements|Check the system requirements]]
# [[Setup:Installation Guide#Prepare the server environment|Prepare the server environment]]
# [[Setup:Installation Guide#Install the BlueSpice application|Install the BlueSpice application]]
# [[Setup:Installation Guide#Optimizing the configuration|Optimize the configuration]]

==Check the system requirements==

*[[Setup:System requirements|System requirements]]

== Prepare the server environment ==

* [[Setup:Installation Guide/System Preparation/Linux|Linux server environment]]
* [[Setup:Installation Guide/System Preparation/Windows|Windows server environment]]

==Install the BlueSpice application==
Please select which installation type you need:

*[[Setup:Installation Guide/With Installer|Full BlueSpice installation]]
**Extended Functions: [[Setup:Installation Guide/Advanced/VisualEditor Configuration|VisualEditor]], [[Setup:Installation Guide/Advanced/ExtendedSearch Configuration|ExtendedSearch]]
*[[Setup:Installation Guide/Installation BlueSpice WikiFarm|BlueSpice WikiFarm installation]]
*[[Setup:Installation Guide/Docker/Docker Hub|Docker image]]

==Upgrade and patch updates==

*[[Setup:Installation Guide/Patch Update|Patch update from BlueSpice 4.2.x to a higher version 4.2.x+n]]
*[[Setup:Installation Guide/Upgrade free to pro|Upgrade from BlueSpice free 3.2.x to BlueSpice pro 4.2.x]]
*Upgrade from Bluespice free 4.2.x to pro 4.2.x

==Migration from MediaWiki to BlueSpice==

*[[Setup:Installation Guide/Migration from MediaWiki to BlueSpice|Migration from MediaWiki to BlueSpice]]

==Optimize the configuration==
If you don't need to set up a server environment "from scratch", you can directly refer to the setup instructions for individual system components. Just make sure that you really have everything configured as needed:

===Webservices for Apache Tomcat===

{{Special:PrefixIndex/Setup:Installation Guide/Webservices/ |hideredirects=1 |stripprefix=1}}

===Additional settings and optimizations===

*[[Setup:Installation Guide/Optimization/Caching|Caching]]
*[[Setup:Installation Guide/Optimization/Cronjobs|Cronjobs]]
*[[Setup:Installation Guide/Optimization/Time Zone|Time Zone]]

===Security settings===

*[[Setup:Installation Guide/Security Settings/File System Permissions|File System Permissions]]
*[[Setup:Installation Guide/Security Settings/Deactivating installcheck file|Deactivating installcheck file]]
*[[Setup:Installation Guide/Security Settings/Save Directories|Save Directories]] 

===Compendium===

{{Special:PrefixIndex/Setup:Installation Guide/Advanced/ |hideredirects=1 |stripprefix=1}}

[[en:{{FULLPAGENAME}}]]
[[de:Setup:Installationsanleitung]]
[[Category:Setup]]

Setup:System requirements

2022-06-23T06:44:01Z

Rvogel:

{{DISPLAYTITLE:System Requirements}}
__NOTOC__

For a trouble-free installation of the current version BlueSpice 3.4, we recommend the following system requirements. The application BlueSpice is tested by Hallo Welt! for Windows and Linux.

==Browser==

*Microsoft Edge
*Google Chrome
*Firefox

==Server Environment==
{{Messagebox|boxtype=warning|icon=yes|Note text=PHP version 8 is currently not supported!|bgcolor=}}
*Operating system: Microsoft Windows Server >= 2016 or Linux (common distributions)
*Webserver: Apache 2.4.x, IIS >= 10 ''or'' nginx 1.x (''nginx'' ''not possible in WikiFarm'')
*PHP 7.4.x starting at 7.4.3
*MySQL: >= 5.6 oder MariaDB >= 10.3
*Main memory: 16 GB (minimal 8 GB)
*Available hard drive space: > 20GB (depends on the planned storage of data)
*CPU: 8 (minimal 4) cores
*Apache Tomcat >= 9 oder Jetty >= 9 (for PDF export and LaTexRenderer)
*ElasticSearch 6.8 with plugin “ingest-attachment”
*OpenJDK >= 10
*NodeJS 16
[[en:{{FULLPAGENAME}}]]
[[de:Setup:Systemanforderungen]]
[[Category:Setup]]

Manual:Extension/FlaggedRevs/Server script

2022-04-22T07:51:47Z

Rvogel:

== Mass approval using a script ==
The script <code>extensions/BlueSpiceFlaggedRevsConnector/maintenance/BSBatchReview.php</code> can be used to approve all drafts in the wiki. This affects both first drafts, drafts of pages with already approved versions and drafts for embedded resources.

===Options===
{| class="wikitable" style="width:100%;"
|+
!Option
!Description
|-
|<code>--username</code>
|Required. The user name of the existing user to use as the "reviewer"
|-
|<code>--pageids</code>
|Flat file containing page ids seperated by line break
|-
|<code>--pages</code>
|Flat file containing page names seperated by line break
|-
|<code>--namespace</code>
|Id of namespace to flag entirely
|-
|<code>--flag</code>
|Which flags to apply? Possible values: "quality", "pristine", "checked". Default is "quality".
|}
{{Messagebox|boxtype=note|icon=|Note text=The options <code>--pageids</code>, <code>--pages</code> and <code>--namespace</code> are mutual exclusive required. One - and only one - of them ''must'' be provided.}}

=== Examples ===

==== Whole namespace ====
<syntaxhighlight lang="bash">
php extensions/BlueSpiceflaggedRevsConnector/maintenance/BSBatchReview.php --username WikiSysop --namespace 3000
</syntaxhighlight>

==== List of page ids ====
Such a list can be created from a database query.

File <code>/tmp/page-ids-to-review.txt</code>:
23
42
1337

Command line:
<syntaxhighlight lang="bash">
php extensions/BlueSpiceflaggedRevsConnector/maintenance/BSBatchReview.php --username WikiSysop --pageids /tmp/page-ids-to-review.txt
</syntaxhighlight>

==== List of page names ====
Such a list can be created using a [[SMW queries|SMW query]].
File <code>/tmp/page-titles-to-review.txt</code>:
Some/Page
Other_page
Help:Some_help_page

Command line:
<syntaxhighlight lang="bash">
php extensions/BlueSpiceflaggedRevsConnector/maintenance/BSBatchReview.php --username WikiSysop --pages /tmp/page-titles-to-review.txt
</syntaxhighlight>

Manual:Extension/FlaggedRevs/Server script

2022-04-22T07:51:10Z

Rvogel:

== Mass approval using a script ==
The script <code>extensions/BlueSpiceFlaggedRevsConnector/maintenance/BSBatchReview.php</code> can be used to approve all drafts in the wiki. This affects both first drafts, drafts of pages with already approved versions and drafts for embedded resources.

===Options===
{| class="wikitable" style="width:100%;"
|+
!Option
!Description
|-
|<code>--username</code>
|Required. The user name of the existing user to use as the "reviewer"
|-
|<code>--pageids</code>
|Flat file containing page ids seperated by line break
|-
|<code>--pages</code>
|Flat file containing page names seperated by line break
|-
|<code>--namespace</code>
|Id of namespace to flag entirely
|-
|<code>--flag</code>
|Which flags to apply? Possible values: "quality", "pristine", "checked". Default is "quality".
|}
{{Messagebox|boxtype=note|icon=|Note text=The options <code>--pageids</code>, <code>--pages</code> and <code>--namespace</code> are mutual exclusive required. One - and only one - of them ''must'' be provided.}}

=== Examples ===

==== Whole namespace ====
<syntaxhighlight lang="bash">
php extensions/BlueSpiceflaggedRevsConnector/maintenance/BSBatchReview.php --username WikiSysop --namespace 3000
</syntaxhighlight>

==== List of page ids ====
Such a list can be created from a database query.

File <code>/tmp/page-ids-to-review.txt</code>;
23
42
1337

Command line:
<syntaxhighlight lang="bash">
php extensions/BlueSpiceflaggedRevsConnector/maintenance/BSBatchReview.php --username WikiSysop --pageids /tmp/page-ids-to-review.txt
</syntaxhighlight>

==== List of page names ====
Such a list can be created using a [[SMW queries|SMW query]].
File <code>/tmp/page-titles-to-review.txt</code>;
Some/Page
Other_page
Help:Some_help_page

Command line:
<syntaxhighlight lang="bash">
php extensions/BlueSpiceflaggedRevsConnector/maintenance/BSBatchReview.php --username WikiSysop --pages /tmp/page-titles-to-review.txt
</syntaxhighlight>

Manual:Extension/FlaggedRevs/Server script

2022-04-22T07:45:51Z

Rvogel:

== Mass approval using a script ==
The script <code>extensions/BlueSpiceFlaggedRevsConnector/maintenance/BSBatchReview.php</code> can be used to approve all drafts in the wiki. This affects both first drafts, drafts of pages with already approved versions and drafts for embedded resources.

===Options===
{| class="wikitable" style="width:100%;"
|+
!Option
!Description
|-
|<code>--username</code>
|Required. The user name of the existing user to use as the "reviewer"
|-
|<code>--pageids</code>
|Flat file containing page ids seperated by line break
|-
|<code>--pages</code>
|Flat file containing page names seperated by line break
|-
|<code>--namespace</code>
|Id of namespace to flag entirely
|-
|<code>--flag</code>
|Which flags to apply? Possible values: "quality", "pristine", "checked". Default is "quality".
|}
{{Messagebox|boxtype=note|icon=|Note text=The options <code>--pageids</code>, <code>--pages</code> and <code>--namespace</code> are mutual exclusive required. One - and only one - of them ''must'' be provided.}}

The pages are released per namespace and by a user with admin rights:
<syntaxhighlight lang="php">
php extensions/BlueSpiceflaggedRevsConnector/maintenance/BSBatchReview.php --username WikiSysop --namespace 3000
</syntaxhighlight>
If there is a large number of affected namespaces, a list of page titles or page IDs can be specified as a txt file. If necessary, this list can be created using a [[SMW queries|SMW query]].

User:Rvogel

2022-04-21T07:08:42Z

Rvogel: create user page