BlueSpice Helpdesk - User contributions [en]

Manual:Extension/Workflows/Tutorial

2024-05-29T08:21:52Z

Akulbii:

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

{{Textbox|boxtype=important|header=Note|text=XML which is provided below is incompatible with "BPMN Editor" added in BlueSpice 4.5. There is no way to edit it in visual way.|icon=yes}}

===Creating 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.
*Line 3: 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:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:wf="http://hallowelt.com/schema/bpmn/wf" xmlns:di="http://www.omg.org/spec/DD/20100524/DI">
<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>FromTheStartToTheEnd</bpmn:outgoing>
</bpmn:startEvent>
<bpmn:sequenceFlow id="FromTheStartToTheEnd" sourceRef="TheStart" targetRef="TheEnd" />



<bpmn:endEvent id="TheEnd">
<bpmn:incoming>FromTheStartToTheEnd</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

2024-05-28T13:19:56Z

Akulbii: Fix sample workflow XML

{{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.
*Line 3: 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:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:wf="http://hallowelt.com/schema/bpmn/wf" xmlns:di="http://www.omg.org/spec/DD/20100524/DI">
<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>FromTheStartToTheEnd</bpmn:outgoing>
</bpmn:startEvent>
<bpmn:sequenceFlow id="FromTheStartToTheEnd" sourceRef="TheStart" targetRef="TheEnd" />



<bpmn:endEvent id="TheEnd">
<bpmn:incoming>FromTheStartToTheEnd</bpmn:incoming>
</bpmn:endEvent>

</bpmn:process>


<bpmndi:BPMNDiagram id="BPMNDiagram_1">
<bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Classification_workflow_process">
<bpmndi:BPMNEdge id="FromTheStartToTheEnd_di" bpmnElement="FromTheStartToTheEnd">
<di:waypoint x="192" y="120"/>
<di:waypoint x="342" y="120"/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNShape id="StartEvent_di" bpmnElement="TheStart">
<dc:Bounds x="156" y="102" width="36" height="36"/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="TheEnd_di" bpmnElement="TheEnd">
<dc:Bounds x="342" y="102" width="36" height="36"/>
</bpmndi:BPMNShape>

</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>

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

Setup:Installation Guide/Advanced/Maintenance scripts/executeTransfer

2023-06-06T18:17:47Z

Akulbii: Fix "--namespace" option description. Namespace's ID is used, not name

{{DISPLAYTITLE:extensions/ContentTransfer/maintenance/executeTransfer.php}}
[[Setup:Installation_Guide/Advanced/Maintenance_scripts|{{Icon|bi bi-arrow-right-circle|||}} all maintenance scripts]]
== Reference ==
BlueSpice Extension: [[Reference:ContentTransfer|ContentTransfer]]

== Usage ==

There are three ways to specify pages which pages to transfer:

* <code>'''--category'''</code>: This option lets you transfer based on category:<syntaxhighlight lang="php">
php extensions/ContentTransfer/maintenance/executeTransfer.php --category=GlobalPage --targets=Target1,Target2,Target3
</syntaxhighlight>
* <code>'''--namespace'''</code>: This option lets you transfer based on namespace ID:<syntaxhighlight lang="php">
php extensions/ContentTransfer/maintenance/executeTransfer.php --namespace=10 --targets=Target1,Target2,Target3
</syntaxhighlight>
* <code>'''--pages'''</code> This option lets you explicitly specify which pages to transfer:<syntaxhighlight lang="php">
php extensions/ContentTransfer/maintenance/executeTransfer.php --pages=Page1,Demo:Page2,Page3 --targets=Target1,Target2,Target3
</syntaxhighlight>

== Configuration ==
The maintenance script can consume a JSON file with the necessary configuration. A sample JSON file is located at this path: <code>extensions/ContentTransfer/docs/transfer-config.json.example</code>. This file can be used to create a JSON configuration file somewhere, so that it is not necessary to type all options in the CLI each time.

For that, <code>--json-config</code> can be used. There can be a specified path to the file with the JSON configuration.

If you need to create your own JSON configuration file, copy the sample JSON file somewhere and edit it to set the necessary configuration.

For example, you have the file <code>/home/some_user/config/transfer-config.json</code>. Then it can be used like that:
<code>php extensions/ContentTransfer/maintenance/executeTransfer.php --json-config=/home/some_user/config/transfer-config.json</code>
You can specify either an absolute file path from the root or a relative path from the present working directory.

'''Note!'''

It is also possible to use a JSON file and additionally pass options from the CLI. In that case, the options from CLI will have greater priority and '''will override''' the same options from JSON file.

Example:
<code>php extensions/ContentTransfer/maintenance/executeTransfer.php --json-config=/home/some_user/config/transfer-config.json --pages=Page1,Demo:Page2,Page3 --targets=Target1,Target2,Target3</code>
Here, the script will read the configuration from the specified JSON file , but the '''“pages”''' and '''“targets”''' options '''will be overridden''' from the CLI (if they are presented in JSON). The same is true for the other options.

== Options ==

* <code>--user</code>: The context user of the "sending" wiki who will be used to transfer wiki pages. This is just about recording the transfer in the DB. Default: '''“MediaWiki default”'''
* <code>--only-modified</code>: If the page should be transferred only if it was modified since the last transfer. '''It's just a flag, it can be passed or not.'''
* <code>--modified-since</code>:Transfer the page only if it was modified since the specified date. The date must be specified in the format '''"DD.MM.YYYY"'''. Default: '''“”'''
* <code>--include-related</code>:If all related wiki pages should also be transferred (templates, files, links, and so on, which are used on the page to be transferred. '''It's just a flag, it can be passed or not.'''
* <code>--force</code>:Transfer the page even if it is protected on the receiving wiki. '''It's just a flag, it can be passed or not.'''

Also there is a <code>--dry</code> option (it's a flag too), which may be useful if a user just wants to take a look at transferring titles, but without actual changes in “receiving” wikis.

You can see a complete list of possible options with descriptions by the following command:
<code>php extensions/ContentTransfer/maintenance/executeTransfer.php --help</code>

If there is a need to set a specific user for creating pages in the target wiki , it can be done that way:
<code>php extensions/ContentTransfer/maintenance/executeTransfer.php ... --targets=Target1=User1,Target2=User2,Target3...</code>

User:Akulbii

2023-06-06T18:08:42Z

Akulbii: create user page