Page Properties

hidden	true
id	PROGRESS

Product Version
Report Note
Assignee

Resources & Remarks

Modification History

Name	Date	Product Version	Action
Antje	23 JUL 2021	2021 Autumn	created
Martin	26 JUL 2021	2021 Autumn	draft
Bratislav	29 JUL 2021	2021 Autumn	draft
Antje	29 JUL 2021	2021 Autumn	formatting, published
Agnieszka	25 AUG 2021	2021 Autumn	rLANG
Martin	24 SEP 2021	2021 Winter	Added the section for starting processes with a startform
Antje	27 OCT 2021	2021 Winter	client-specific Flowable variables added
Christoph	15 FEB 2022	2022 Spring	added Custom Confirm Actions (DOKU-2347)

Excerpt
Use the BPM Engine for process and task management within your client.

Section

border	true

Column

Introduction

The BPM Engine in yuuvis® Momentum is provided by the BPM-ENGINE service based on the workflow functionality of the open-source software Flowable. In yuuvis® client as reference implementation, it can be integrated in order to support process and task management via the browser application.

...

Column in yuuvis® client	Corresponding Counterpart in BPM Engine	Description
Description (not available anymore as of version 2021)	Process variable `whatAbout`	The description that was entered while creating the follow-up.
as of 2021 Winter: Subject	Web-API Gateway parameter `subject`, represented as Flowable string variable `subject`	Set while creating the process.
Created on	Process parameter `startTime`	The time the follow-up (process) was created.
Follow-up date	Process variable `expiryDateTime`	The due date that was entered while creating the follow-up.
Status	Derived from process parameters `endTime` and `suspended`	Possible values for Status are `running`, `completed` and `suspended`.

...

To provide the example Two step process action in a client, import the client plug-in configuration file shown below. To be able to import a settings file, users need an administrative role.
>> Extending the Clients with Plug-ins

The twosteptest_proc process model has to be deployed to the Flowable BPM Engine.

yml

Code Block

language

title	Plug-in Configuration for an Example 'Two step pocess'
collapse	true

{
  "disabled": false,
  "actions": [
    {
      "id": "yuv.custom.action.two.step.multi.label",
      "label": "yuv.custom.action.two.step.multi.label",
      "description": "yuv.custom.action.two.step.multi.description",
      "priority": 0,
      "icon": "<svg height=\"24\" viewBox=\"0 0 24 24\" width=\"24\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M0 0h24v24H0V0z\" fill=\"none\"></path> <path d=\"M4 10h12v2H4zM4 6h12v2H4zM4 14h8v2H4zM14 14v6l5-3z\"></path> </svg>",
      "group": "further",
      "range": "MULTI_SELECT",
      "isExecutable": "(item) => item.id",
      "run": "(selection) => this.http.post('/bpm/processes', {businessKey: selection[0].id, name: selection[0].title || selection[0].id, processDefinitionKey: 'twosteptest_proc', attachments: selection.map((s) => s.id), subject: selection[0].title, variables: [{ name: 'myVariable', type: 'string', value: 'Lorem ipsum' }]},'api-web').then(() => this.util.notifier.success(this.util.translate('yuv.custom.action.two.step.multi.success')))"
    },
    "yuv-download-action",
    "yuv-delete-action",
    "yuv-delete",
    "yuv-upload",
    "yuv-upload-action",
    "yuv-move-action",
    "yuv-move",
    "yuv-follow-up-action",
    "yuv-follow-up",
    "yuv-reference-action",
    "yuv-open-context-action",
    "yuv-open-versions-action",
    "yuv-clipboard-action",
    "yuv-clipboard-link-action"
  ],
  "translations": {
    "en": {
      "yuv.custom.action.two.step.multi.label": "Two step process",
      "yuv.custom.action.two.step.multi.description": "Starts simple process with two steps, also for many objects",
      "yuv.custom.action.two.step.multi.success": "Process has started"
    },
    "de": {
      "yuv.custom.action.two.step.multi.label": "Zweischritteprozess",
      "yuv.custom.action.two.step.multi.description": "Startet einen einfachen Prozess mit zwei Schritten, auch für mehrere Prozesse",
      "yuv.custom.action.two.step.multi.success": "Prozess wurde gestartet"
    }
  }
}

...

Code Block

title	Example Configuration
linenumbers	true
collapse	true

{
  "name": "twosteptest_proc:1st_task",
  "situation": "EDIT",
  "script": "",
  "elements": [
    {
      "name": "core",
      "type": "o2mGroup",
      "elements": [
        {
          "type": "o2mGroup", 
          "layout": {
              "align": "row"
          },
          "elements": [
           {
              "type": "o2mGroup", 
              "name": "xyzSimplefields",
              "layout": {
                  "align": "column"
              },
              "elements": [
                {
                  "name": xyzDatetime",
                  "type": "datetime",
                  "required": false,
                  "cardinality": "single",
                  "readonly": false
                },
                {
                  "name": "xyzDate",
                  "type": "datetime",
                  "required": false,
                  "cardinality": "single",
                  "readonly": false,
                  "resolution": "date"
                },
                {
                  "name": "xyzInteger",
                  "type": "integer",
                  "required": false,
                  "cardinality": "single",
                  "readonly": false                },
                {
                  "name": "xyzDecimal",
                  "type": "decimal",
                  "required": false,
                  "cardinality": "single",
                  "readonly": false
                },
                {
                  "name": "xyzString",
                  "type": "string",
                  "required": false,
                  "rows": 1,
                  "readonly": false                },
                {
                  "name": "xyzStringmultirow",
                  "type": "string",
                  "required": false,
                  "rows": 3,
                  "readonly": false
                }
              ]
            },
            {
              "type": "o2mGroup", 
              "name": "xyzComplexfields", 
              "layout": {
                  "align": "column"
              },
              "elements": [
                {
                  "name": "xyzEmail",
                  "type": "string",
                  "cardinality": "single",
                  "readonly": false,
                  "classifications": ["email"]
                },
                {
                  "name": "xyzUrl",
                  "type": "string",
                  "required": false,
                  "readonly": false,
                  "classifications": ["url"]
                },
                {
                  "name": "xyzPhone",
                  "type": "string",
                  "required": false,
                  "readonly": false,
                  "classifications": ["phone"]
                },
                {
                  "name": "xyzUser",
                  "type": "string",
                  "required": false,
                  "cardinality": "single",
                  "readonly": false,
                  "classifications": ["id:organization"]
                },
                {
                  "name": "xyzReference",
                  "type": "string",
                  "required": false,
                  "cardinality": "single",
                  "readonly": false,
                  "classifications": ["id:reference[]"],
                  "label": "Reference"
                },
                {
                  "name": "xyzCatalogcustom",
                  "type": "string",
                  "required": false,
                  "cardinality": "single",
                  "readonly": false,
                  "classifications": ["custom:catalog[/api-web/api/dms/catalogs/tenMytenant:processstatus]"],
                  "label": "Catalog status"
                },
                {
                  "name": "xyzBroc:boolean",
                  "type": "boolean",
                  "required": false,
                  "readonly": false,
                  "label": "Boolean"
                }
              ]
            }
          ]
        },
        {
          "name": "xyzTest_table",
          "type": "table",
          "required": false,
          "readonly": false,
          "label": "Notices",
          "description": "List of notices",
          "classifications": "sortable",
          "elements": [
            {
              "name": "xyzColumn_string",
              "type": "string",
              "required": false,
              "cardinality": "single",
              "readonly": false,
              "label": "String"
            },
            {
              "name": "xyzColumn_date",
              "type": "datetime",
              "required": false,
              "cardinality": "single",
              "readonly": false,
              "label": "Date"
            },
            {
              "name": "xyzColumn_user",
              "type": "string",
              "required": false,
              "cardinality": "single",
              "classifications": ["id:organization"],
              "readonly": false,
              "label": "User"
            },
            {
              "name": "xyzColumn_boolean",
              "type": "boolean",
              "required": false,
              "cardinality": "single",
              "readonly": false,
              "label": "Boolean"
            }
          ]
        }
      ]
    },
    {
      "name": "data",
      "type": "o2mGroupStack",
      "elements": [],
          "layout": { "align": "column" },
          "label": "Table group"
    }
  ]
}

HintNote: the The key-value pair "classifications": ["sortable"] allows the user to sort the table rows manually by drag & drop.

The following client-spezific specific Flowable variables are available:

Task parameter
(Web-API Gateway GET tasks) Example format Flowable variable name Example format Description

subject

"subject": "My subject"

appClientsystem_subject

Code Block
{ "action": "save", "variables": [ { "name": "appClientsystem_subject", "type": "string", "value": "My subject" }

Process subject

The client-specific task parameter subject is presented in the Subject column of the Inbox.

The parameter can be set using the Web-API Gateway GET/PUT endpoints for tasks or the corresponding BPM-API endpoints for setting the variable appClientsystem_subject.

attachments

"attachments": ["GUID1","GUID2", "GUID2"]

appClientsystem_attachments

Code Block
{ "action": "save", "variables": [ { "name": "appClientsystem_attachments", "type": "json", "value": [ "GUID1", "GUID2" ] }

Process attachments

The client-specific task parameter attachment is used for the tasks' Attachments aspect area of the Inbox. The value is an array of object GUIDs. The title of the corresponding objects is displayed in the list of attachments for users.

The parameter can be set using the Web-API Gateway GET/PUT endpoints for tasks or the corresponding BPM-API endpoints for setting the variable appClientsystem_attachment.

taskMessages

Example code for the GET task's response of the Web-API Gateway:

Code Block

"taskMessages": [
  {
    "message": "messageWithoutColor"
  },
  {
    "level": "error",
    "message": "messageError",
    "type": "ul"
  },
  {
    "level": "warning",
    "message": "messageWarning",
    "type": "ul"
  },
  {
    "level": "info",
    "message": "messageError"
  },
  {
    "message": "Not translated message"
  }
]

appClientsystem_taskMessages

Example code for setting the Flowable variable appClientsystem_taskMessages via BPM-API PUT tasks:

Code Block
{ "action": "save", "variables": [ { "name": "appClientsystem_

taskForm

taskMessages",
      "type": "json",
      "value":

{

"schemaProperties":

[

          "message": "

tenMytenant:strsingle

messageWithoutColor"

,

},

"tenMytenant:datesingle"

] }

},

{

name

level": "

appClientsystem_taskMessages

error",

"type":

"json",

value

message":

[ {

"messageError",
          "

message

type": "

messageWithoutColor

ul"
        },
        {
          "level": "

error

warning",
          "message": "

messageError

messageWarning",
          "type": "ul"
        },
        {
          "level": "

warning

info",
          "message": "

messageWarning

messageError"

,

"type": "ul"

},
        {
          "

level

message": "

info

Not translated message"

,

"message":

"messageError"

    ]
    }

,

{ "message": "Not translated message" } ] } ] }

]
}

Configure Task Messages

This client-specific task parameter can be used to present necessary information for working on this particular task. The messages are presented on the top of the Task aspect area in the Inbox.

The level parameter specifies the formatting of the corresponding messages. The following values are available:

level	description
`without level`	The message is rendered in the normal format
`info`	The text is rendered in the accent color
`error`	Text is rendered in Red
`warning`	Text is rendered in Orange

If the message is a localization key, the key will be translated (see messageError in the example). The keys do not need an appended _label as required for the name for a form field.

'"Type": "ul" can be used to render messages with this setting in a list.

The value specified for taskMessages is retrieved by the GET tasks endpoint of the Web-API Gateway and can only be set by via the Flowable variable appClientsystem_taskMessages.

Image Modified

taskForm

Example code for the GET tasks response of the Web-API Gateway using schemaProperties:

Code Block
"taskForm": { "schemaProperties": [ "tenMytenant:strsingle", "tenMytenant:datesingle" ]

Example code for the GET tasks response of the Web-API Gateway using a form model:

Code Block

"taskForm": {
    "model": {
            "name": "twosteptest_proc:2nd_task",
            "situation": "EDIT",
            "script": "",
            "elements": [
              {
                "name": "core",
                "type": "o2mGroup",
                "elements": [
                  {
                    "type": "o2mGroup", 
                    "layout": {
                        "align": "row"
                    },
                    "elements": [
                    {
                        "type": "o2mGroup", 
                        "name": "twosteptest_proc:simplefields",
                        "layout": {
                            "align": "column"
                        },
                        "elements": [
                          {
                            "name": "twosteptest_proc:date",
                            "labelkey": "Date",
                            "type": "datetime",
                            "required": false,
                            "cardinality": "single",
                            "readonly": false,
                            "resolution": "date"
                          },
                          {
                            "name": "twosteptest_proc:string",
                            "type": "string",
                            "cardinality": "single",
                            "required": false,
                            "rows": 1,
                            "readonly": false                
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
     ]

appClientsystem_taskForm

Example code for setting the Flowable variable appClientsystem_taskForm via BPM-API PUT tasks using schemaProperties:

Code Block
{ "action": "save", "variables": [ { "name": "appClientsystem_taskForm", "type": "json", "value": { "schemaProperties": [ "tenMytenant:strsingle", "tenMytenant:datesingle" ] } } ] }

Example code for saving the Flowable variable appClientsystem_taskForm via BPM-API PUT tasks using a form model:

Code Block

{
  "action": "save",
  "variables": [
    {
      "name": "appClientsystem_taskForm",
      "type": "json",
      "value": { 
        "model":
          {
            "name": "twosteptest_proc:2nd_task",
            "situation": "EDIT",
            "script": "",
            "elements": [
              {
                "name": "core",
                "type": "o2mGroup",
                "elements": [
                  {
                    "type": "o2mGroup", 
                    "layout": {
                        "align": "row"
                    },
                    "elements": [
                    {
                        "type": "o2mGroup", 
                        "name": "twosteptest_proc:simplefields",
                        "layout": {
                            "align": "column"
                        },
                        "elements": [
                          {
                            "name": "twosteptest_proc:date",
                            "labelkey": "Date",
                            "type": "datetime",
                            "required": false,
                            "cardinality": "single",
                            "readonly": false,
                            "resolution": "date"
                          },
                          {
                            "name": "twosteptest_proc:string",
                            "type": "string",
                            "cardinality": "single",
                            "required": false,
                            "rows": 1,
                            "readonly": false                
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
          }
      }
    }
  ]
}

Configure the Task Form

This client-specific task parameter can be used to

select

specify user-relevant properties to be displayed in the task form. Each property is specified by its name. The attributes of this property

will be used in

determine the style of the form field.

Form fields can be handled either by

listing the relevant properties in schemaProperties or
configuring a more complex form with form model syntax in a model.

If name does not have a representation in the schema, it will be ignored.

The code clock below shows an example for the Flowable representation of a yuuvis table property. Tables are only shown up in a form where the types of the column properties are added as seen above.

...

As of version 2021 Winter, a plug-in action is available that allows to start a process via a start form as shown in the example screenshot. If all form fields are filled with valid values, the Start button is enabled. Both form fields User and Comment are required variables for starting a process. The code block below shows the corresponding plug-in configuration offering a start form with the name taskform in the object action view (displayed after a click on the object action Test process with role assignment).

yml

Code Block

language

title	Example Plugin Configuration Start Form
linenumbers	true	collapse	true

{ 
  "disabled": false,
  "actions": [
    {
      "id": "yuv.custom.action.userGroupAssignment.multi.label",
      "label": "yuv.custom.action.userGroupAssignment.multi.label",
      "description": "yuv.custom.action.userGroupAssignment.multi.description",
      "priority": 1,
      "icon": "<svg height=\"24\" viewBox=\"0 0 24 24\" width=\"24\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M0 0h24v24H0V0z\" fill=\"none\"></path> <path d=\"M4 10h12v2H4zM4 6h12v2H4zM4 14h8v2H4zM14 14v6l5-3z\"></path> </svg>",
      "group": "further",
      "range": "MULTI_SELECT",
      "isExecutable": "(item) => item.id",
      "buttons": {
        "finish": "yuv.custom.action.userGroupAssignment.multi.start"
      },
      "plugin": {
        "component": "yuv-object-form",
        "inputs": {
          "__initOptions": "this.http.get(`/resources/config/taskform`, 'api-web').then((res) => {component.cmp.options = {formModel: res.data.tenant, disabled: false}})",
          "__init": "() => parent.finished.subscribe((event) => { var selection = parent.selection; var cmp = component.cmp; this.http.post('/bpm/processes',{businessKey: selection[0].id,name: selection[0].title || selection[0].id,processDefinitionKey: 'userGroupAssignment',attachments: selection.map((s) => s.id),subject: selection[0].title,variables: [{ name: 'user', type: 'string', value: cmp.formData.user || '' },{ name: 'comment', type: 'string', value: cmp.formData.comment || '' },{ name: 'nextUserAssignee', type: 'string', value: 'fakeUserId' },{ name: 'nextGroupAssignee', type: 'string', value: 'YUUVIS_MANAGE_SETTINGS' }]},'api-web').then(() => this.util.notifier.success(this.util.translate('yuv.custom.action.userGroupAssignment.multi.success')))})"
        },
        "outputs": {
          "statusChanged": "(status) => { parent.disabled = status.invalid; }"
        }
      }
    },
    "*"
  ],
  "translations": {
    "en": {
      "yuv.custom.action.userGroupAssignment.multi.label": "Test process with role assignment",
      "yuv.custom.action.userGroupAssignment.multi.description": "Starts a process with two tasks. Second task assigned to YUUVIS_MANAGE_SETTINGS",
      "yuv.custom.action.userGroupAssignment.multi.success": "Process has started"
    }
  }
}

The following code block shows the form definition for the plug-in action example displayed above:

yml

Code Block

language

title	Definition Example
linenumbers	true
collapse	true

 {
  "description": "This form is used during process start and both task of process userGroupAssignment",
  "name": "taskform",
  "situation": "EDIT",
  "elements": [
    {
      "name": "core",
      "type": "o2mGroup",
      "elements": [
        {
          "name": "user",
          "labelkey": "userGroupAssignment:user",
          "type": "string",
          "cardinality": "single",
          "required": true,
          "readonly": false,
          "classifications": ["id:organization"]
        },
        {
          "name": "comment",
          "labelkey": "userGroupAssignment:comment",
          "type": "string",
          "required": true,
          "readonly": false,
          "rows": 3
        }
      ],
      "layout": {
        "align": "column"
      }
    },
    {
      "name": "data",
      "label": "data",
      "type": "o2mGroupStack",
      "elements": []
    }
  ]
}

...

If the cardinality of a field is single, its type is mapped to the type of the Flowable variable with the same name.
If the cardinality of a field is multi, the Flowable variable type is set to JSON and its values are listed in the specified JSON structure.

Custom Confirm Actions

As of version 2022 Spring, it is possible to configure custom confirm actions for BPM tasks. These custom confirm actions trigger optional forms that give users the possibility to provide further data that is relevant only for this particular outcome. The so-called outcomes can be configured in static BPM form files as well as in dynamic ones:

Code Block

title	Outcomes configuration

{
  "model":
  {
    ...
  },
  "outcomes": [
    {
      "name": "taskflow_finish",
      "variable": "status",
      "value": "close"
    },
    {
      "name": "taskflow_forward",
      "secondary": true,
      "variable": "status",
      "value": "open",
      "model": "taskflow-form-forward"
    }
  ]
}

The outcomes list contains custom task confirm actions that will be displayed as buttons in the UI instead of the standard confirm button. The order of the buttons is from right to left. The buttons are displayed in the accent color per default. The outcomes section can be used in dynamic action forms as well.

Parameter	Description
`name`	Technical name of the custom confirm action that is used as label for the button to be displayed in the client if not localized.
`variable`	The name of the Flowable variable for which the specified value is saved after the user has clicked the button. The variable can be used to control the process flow.
`value`	The value of the Flowable `variable`.
`secondary`	If `false` (default), the button is shown in the accent color. If `true`, the button is NOT shown in the accent color.
`model`	Specify the technical name of a defined BPM form or a complete valid form model. This form will only be shown if users click the corresponding custom confirm action.

Versions Compared

Old Version 45

New Version Current

Key

Table of Contents

Introduction

Custom Confirm Actions

Page Comparison

Versions Compared

Old Version 45

New Version Current

Key

Table of Contents

Introduction

Custom Confirm Actions