Designing and creating custom workflows

Supported tools

Required skills

To create custom process definitions, you need the following skills and knowledge.

• Fundamental understanding of the business process you are supporting.
• Familiarity with Flowable.
• Programming skills.
• Familiarity with JavaScript.
• Basic understanding of the Java Unified Expression Language.

Limitations

In Cloud Pak for Data, workflows run in the synchronous workflow engine mode, which means that all workflow actions must be triggered by an external action. For example, a workflow can be triggered by a user action in Cloud Pak for Data, such as submitting a request or editing an asset.

Any interactions with other Cloud Pak for Data components or other applications, such as REST API calls, must be synchronous.

Custom workflow concepts

In Cloud Pak for Data, a workflow type is the set of resources and configurations that support your business process. The following diagram illustrates the components that you can create in Flowable to define a workflow type.

Top-level templates

At a minimum, you must associate at least one top-level template with a workflow type. A top-level template is a Flowable process definition.

In the Cloud Pak for Data web client, top-level templates are called workflow templates. When a workflow administrator creates a workflow configuration, they select a top-level template. The template is used when the workflow conditions trigger the workflow. For more information, see Configuring custom workflows.

All of the top-level templates for a workflow type must meet the following criteria.

• Each template must be in the same target namespace.

  For more information, see targetNamespace.

• For custom request workflows only, each template must use the same start form properties.

  The start form properties must describe the set of input fields that are presented to the user when they submit a new request. For more information, see User task fields.

Helper templates

You can optionally include one or more helper templates in your workflow type. A helper template is a Flowable process definition. However, you cannot use a helper template when you create a workflow configuration. Helper templates can be used by either top-level templates or other helper templates.

All of the helper templates must be in the helper namespace. For more information, see targetNamespace.

Restriction: You cannot upload helper templates individually. You must include them in a ZIP file that contains at least one top-level template.

Workflow type requirements

Required conventions for process definitions

As you develop your process definitions, use the following conventions.

targetNamespace

Use a targetNamespace to categorize your process definitions based on the workflow type it is associated with. You can use the targetNamespace to group workflow templates by use and to tailor the list of templates that are available to a user in a specific context.

Important: All of the templates in a workflow type must have the same targetNamespace. If you try to upload multiple process definition BPMN files with variations in the targetNamespace entries, the files cannot be uploaded to Cloud Pak for Data.

You can specify the targetNamespace in one of the following ways.

• In Flowable Modeler, specify the targetNamespace in the Namespace field in the properties for the process.
• In the root definitions element in each BPMN file. For example, see the following code sample.

  <definitions
    xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
    ...
    targetNamespace="targetNamespace="https://dataplatform.cloud.ibm.com/workflows/requests/Workflow_type">
       <process id="myProcess" name="My Sample Process">
       ...
       </process>
  
  </definitions>
  

Select the appropriate format for the targetNamespace.

• For governance artifact workflows, specify the following format.

  targetNamespace="https://dataplatform.cloud.ibm.com/workflows/artifacts/artifacts_cud"

• For custom request workflows, specify the following format.

  targetNamespace="https://dataplatform.cloud.ibm.com/workflows/requests/Workflow_type"

  Replace Workflow_type with an appropriate identifier for your workflow type.

• For helper templates, specify the following format.

  targetNamespace="https://dataplatform.cloud.ibm.com/workflows/helper"

Tip: The highlighted portion of the targetNamespace is used as the Template category when you import process definition files to Cloud Pak for Data.

https://dataplatform.cloud.ibm.com/workflows/ requests/workflow_types 

User tasks

Include the following elements in each user task.

User task name

A display name that is used to identify tasks in Flowable Modeler.

Tip: The user task name is also used to sort workflow tasks when a workflow administrator creates a workflow configuration in Cloud Pak for Data. Use prefixes to determine the order in which tasks appear in Cloud Pak for Data. For more information, see Configuring custom workflows.

Sample code

The highlighted portion of the following code shows how to define the user task name.

<userTask id="myTask"  name="User task name"  >
  ...
</userTask>

Title

A short display name for the task.

Every user task has a dynamic title and dynamic instruction, which is displayed to the user in the task inbox. A user task also has a static title and static instruction, which is displayed to the workflow administrator when the workflow is configured.

Provide static and dynamic titles and instructions in the <documentation> part of the user task and separate them by $$$. Make sure to include a space after the dollar signs.

Static title

The static title is displayed when a workflow administrator creates a workflow configuration.

Sample code

Specify the static title in the documentation element of the user task. The highlighted portion of the following code shows how to define the static title.

<userTask id="myTask" name="User task name" >
  <documentation>
      dynamic title $$$ dynamic instruction $$$ static instruction $$$  static title 
  </documentation>
</userTask>

Dynamic title

The dynamic title is displayed when a user is completing the task in an active workflow.

Sample code

Specify the dynamic title in the documentation element of the user task. The highlighted portion of the following code shows how to define the dynamic title.

<userTask id="myTask" name="User task name" >
  <documentation>
       dynamic title  $$$ dynamic instruction $$$ static instruction $$$ static title
  </documentation>
</userTask>

The dynamic title can include process instance variables with the format ${variableName}.

Instruction

An extended description of the task. The instruction must explain what the user is expected to do and provide context for the task.

Provide a static instruction and a dynamic instruction.

Static instruction

The static instruction is displayed when a workflow administrator creates a workflow configuration.

Sample code

Specify the static instruction in the documentation element of the user task. The highlighted portion of the following code shows how to define the static instruction.

<userTask id="myTask" name="User task name" >
  <documentation>
      dynamic title $$$ dynamic instruction $$$  static instruction  $$$ static title
  </documentation>
</userTask>

Dynamic instruction

The dynamic instruction is displayed when a user is completing the task in an active workflow.

Sample code

Specify the dynamic instruction in the documentation element of the user task. The highlighted portion of the following code shows how to define the dynamic instruction.

<userTask id="myTask" name="User task name" >
  <documentation>
      dynamic title $$$  dynamic instruction  $$$ static instruction $$$ static title
  </documentation>
</userTask>

The dynamic instruction can include process instance variables with the format ${variableName}.

User task fields

The user task fields determine the information that a user can enter or select when they complete the task. User tasks can include the following elements.

• Short text fields
• Long text fields
• Date fields
• Hyperlinks
• Multi-select lists
• Radio buttons
• Drop-down lists
• User picker

Short text field

Enables a user to enter a short string of alphanumeric text.

Specify type="string" in the formProperty. For example, see the following code sample.

<flowable:formProperty 
   id="request_name" 
   name="Request name" 
    type="string" 
   readable="false" 
   required="true">
</flowable:formProperty>

Long text field

Enables a user to enter a long block of alphanumeric text.

Specify the following values in the formProperty.

• type="string"
• expression with the appropriate format for your environment.
  • Flowable Modeler. For example, expression="${cpd:conf('{"cpd_type":"long_text"}')}" .
  • BPMN file. For example, expression="${cpd:conf('{"cpd_type":"long_text"}')}" .

For example, see the following code sample.

<flowable:formProperty 
   id="request_summary" 
   name="Summary" 
    type="string"  
    expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;long_text&quot;}')}"  
   readable="false" 
   required="true">
</flowable:formProperty>

Date field

Enables a user to specify a date with a predetermined format.

Specify the following values in the formProperty.

• type="date"

  Cloud Pak for Data supports the ISO 8601 date format.

For example, see the following code sample.

<flowable:formProperty 
   id="fulfill_date" 
   name="Fulfill by" 
    type="date" 
   readable="false">
</flowable:formProperty>

Hyperlink

Enables a user to specify a URL.

Specify the following values in the formProperty.

• type="string"
• expression with the appropriate format for your environment.
  • Flowable Modeler: expression="${cpd:conf('{"cpd_type":"url"}')}"
  • BPMN file: expression="${cpd:conf('{"cpd_type":"url"}')}"

For example, see the following code sample.

<flowable:formProperty 
   id="request_url" 
   name="Link to website (optional)" 
    type="string"  
    expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;url&quot;}')}"  
   readable="false">
</flowable:formProperty>

Multi-select list

Enables a user to select multiple values from a predefined list of values.

Specify the following values in the formProperty.

• type="enum"
• expression with the appropriate format for your environment.
  • Flowable Modeler: expression="${cpd:conf('{"cpd_type":"multi_select"}')}"
  • BPMN file: expression="${cpd:conf('{"cpd_type":"multi_select"}')}"

Additionally, each option is represented as a value of the enum set.

For example, see the following code sample.

<flowable:formProperty 
  id="options_list" 
   type="enum"  
   expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;multi_select&quot;}')}"  
  readable="false" 
  required="true">
      <flowable:value id="option1" name="Option 1" /> 
      <flowable:value id="option2" name="Option 2" /> 
      <flowable:value id="option3" name="Option 3" /> 
</flowable:formProperty>

Radio buttons

Enables a user to select only one option from a predefined list of values. The options are displayed as radio buttons.

Specify the following values in the formProperty.

• type="enum"
• expression with the appropriate format for your environment.
  • Flowable Modeler: expression="${cpd:conf('{"cpd_type":"radio"}')}"
  • BPMN file: expression=“${cpd:conf(‘{"cpd_type":"radio"}’)}”

Additionally, each option is represented as a value of the enum set.

For example, see the following code sample.

<flowable:formProperty 
  id="options_list_2" 
   type="enum" 
   expression=“${cpd:conf(‘{&quot;cpd_type&quot;:&quot;radio&quot;}’)}”   
  readable="false" 
  required="true">
      <flowable:value id="option1" name="Option 1" /> 
      <flowable:value id="option2" name="Option 2" /> 
      <flowable:value id="option3" name="Option 3" /> 
</flowable:formProperty>

Drop-down list

Enables a user to select only one option from a predefined list of values. The options are displayed in a drop-down list.

Specify the following values in the formProperty.

• type="enum"
• expression with the appropriate format for your environment.
  • Flowable Modeler: expression="${cpd:conf('{"cpd_type":"dropdown"}')}"
  • BPMN file: expression="${cpd:conf('{"cpd_type":"dropdown"}')}"

Additionally, each option is represented as a value of the enum set.

For example, see the following code sample.

<flowable:formProperty 
   id="request_priority" 
   name="Priority" 
    type="enum"  
    expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;dropdown&quot;}')}" 
   readable="false">
       <flowable:value id="low" name="Low"></flowable:value> 
       <flowable:value id="medium" name="Medium"></flowable:value> 
       <flowable:value id="high" name="High"></flowable:value> 
</flowable:formProperty>

User picker

Enables a user to select one or more users and pass them to the workflow logic.

Specify the following values in the formProperty.

• type="string"
• expression with the appropriate format for your environment.
  • Flowable Modeler: expression="${cpd:conf('{"cpd_type":"cpd_user"}')}"
  • BPMN file: expression="${cpd:conf('{"cpd_type":"cpd_user"}')}"

For example, see the following code sample.

<flowable:formProperty 
	id="user" 
	name="Some user" 
	type="string" 
	expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;cpd_user&quot;}')}" 
	readable="true"
	writeable="false" 
	required="true">
</flowable:formProperty>

Categories - task types

You can give each user task a category, also called a task type. In the task inbox and on the task status page, tasks can be filtered by task type. You can use any value for the category; however, the following categories trigger special behavior in Cloud Pak for Data:

authoring

Governance artifact workflows only, this category describes the draft creation step. The draft was created but has not been sent for approval yet (or any other first user task as defined in the workflow).

The authoring task does not show up in the configurations page; therefore, you can’t configure any notifications for this step. The assignees are by default set to the category roles Owner, Admin, and Editor.

No due date can be set and hence the task can’t become overdue.

Typically, the Send for approval button is displayed if the author views the artifact details page.

approval

Indicates a regular user task.

voting

Indicates that the approval user task has an approval options drop-down menu.

Your workflow template must be able to handle special approvals. For an example, see the Multiple_approval_steps_and_one_review_step.bpmn20.xml governance artifact workflow template.

review

Indicates an optional user task. When a workflow administrator creates a workflow configuration, the administrator can leave the assignees empty.

publish

For governance artifact workflows only, this category indicates that when a workflow administrator creates a workflow configuration, the Automatically publish artifacts checkbox must be displayed for the step.

For example, see the following code sample.

<userTask 
   id="review" 
   name="Review" 
   flowable:dueDate="${review_due_date}" 
    flowable:category="review"  
   flowable:formFieldValidation="true">

For the checkbox to be visible, the template also needs to contain an additional workflow-level configuration property with ID publishing_step_mode:

<flowable:formProperty id="publishing_step_mode" type="enum" readable="false">
          <flowable:value id="auto_action" name="Automatically publish artifacts. Skip publishing approval."></flowable:value>
          <flowable:value id="explicit_action" name=""></flowable:value>
        </flowable:formProperty>

Action buttons

A form property that represents the actions that a user can take. The form property must include the following elements:

• id="action"
• type="enum"

Each action button is represented as a value of the enum set.

Sample code

<flowable:formProperty 
    id="action"  
    type="enum"  
   readable="false" 
   required="true">
      <flowable:value id="option1" name="Action Button 1" /> 
      <flowable:value id="option2" name="Action Button 2" /> 
      <flowable:value id="option3" name="Action Button 3" /> 
</flowable:formProperty>

The value that is specified in the name element is the display name of the button in the user interface.

Supported prefixes

You can optionally use one of the following prefixes on your id to trigger special behavior:

Prefix	Description
#	Indicates that this action is the final step in a workflow. In a governance artifact workflow, the interface directs the user to the published artifact rather than displaying the draft.
?	Indicates that the interface must display a confirmation dialog when a user selects this action. For example, you might want to display a confirmation dialog if a user click Cancel so that their progress isn't lost.
-	Indicates that the action must be disabled until the user provides a comment.

For example, see the following code sample.

<flowable:formProperty id="action" type="enum" readable="false" required="true">
  <flowable:value id="#approve" name="Approve" />
  <flowable:value id="-reject" name="Reject" />
  <flowable:value id="?" name="Cancel" />
</flowable:formProperty>

Task duration

Enables a user to specify how long the task lasts before is marked as Overdue. The value set when configuring the task can still be overwritten, for example, with a due date set for this task when completing the previous task, or if the user sets a specific due date when placing a new request from Task inbox.

Specify the following values in the formProperty.

• id="due_date_period"
• type="string"
• expression with the appropriate format for your environment.
  • Flowable Modeler: expression="${cpd:conf('{"cpd_type":"period","kind":"config"}')}"
  • BPMN file: expression="${cpd:conf('{"cpd_type":"period","kind":"config"}')}"

For example, see the following code sample.

<flowable:formProperty 
id="due_date_period" 
name="Due date period" 
type="string" 
expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;period&quot;,&quot;kind&quot;:&quot;config&quot;}')}" 
readable="true" 
required="true">
</flowable:formProperty>

Additional workflow and task configuration properties

You can add an additional section with some extra configuration properties for the workflow as a whole and the individual tasks that you define in the workflow. These extra properties, when defined in Flowable, are then listed in new sections in the workflow configuration panel.

• For a workflow as a whole - Properties section
• For individual tasks - Task configuration properties section in each workflow step

You can use the same elements as for the user task fields.

• Short text fields (type: string )
• Long text fields (type: string, cpd_type: long_text)
• Date fields (type:date)
• Hyperlinks (type: string, cpd_type: url)
• Multi-select lists (type: enum, cpd_type: multi_select)
• Radio buttons (type: enum, cpd_type: radio)
• Drop-down lists (type: enum, cpd_type: dropdown)

To add the properties in a template, add the flowable:formProperty section in the following sections.

• For workflow-level configuration properties: startEvent, see the following example.

      <startEvent>
        <extensionElements>
          <flowable:formProperty></flowable:formProperty>
        </extensionElements>
      </startEvent>

• For task-level configuration properties: userTask section for the respective task, see the following example.

      <userTask>
        <extensionElements>
          <flowable:formProperty></flowable:formProperty>
        </extensionElements>
      </userTask>

In expression, set the type or cpd_type to whatever type of field you need and add "kind":"config".

• Flowable Modeler: expression="${cpd:conf('{"cpd_type":"date","kind":"config"}')}"
• BPMN file: expression="${cpd:conf('{"cpd_type":"date","kind":"config"}')}"

If you want the property to be mandatory, add required="true" as in the following example.

 <flowable:formProperty id="workflow_level_config_prop3" name="Required String" type="string" expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;short_text&quot;,&quot;kind&quot;:&quot;config&quot;}')}" readable="true" required="true"></flowable:formProperty>

Sample code for a drop-down list used as a workflow property.

    <startEvent id="startevent1" name="Start" flowable:formFieldValidation="true">
      <extensionElements>
        <flowable:formProperty id="publishing_step_mode" type="enum" readable="false">
          <flowable:value id="auto_action" name="Automatically publish artifacts. Skip publishing approval."></flowable:value>
          <flowable:value id="explicit_action" name=""></flowable:value>
        </flowable:formProperty>
        <flowable:formProperty id="workflow_level_config_prop6" name="Any priority" type="enum" default="med" readable="true" expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;dropdown&quot;,&quot;kind&quot;:&quot;config&quot;}')}">
          <flowable:value id="low" name="Low"></flowable:value>
          <flowable:value id="med" name="Medium"></flowable:value>
          <flowable:value id="high" name="High"></flowable:value>
        </flowable:formProperty>
      </extensionElements>
    </startEvent>

Sample code for multi-select list used as a task configuration property.

        <flowable:formProperty id="config_prop7" name="Multi select property name" type="enum" default="c" readable="true" expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;multi_select&quot;,&quot;kind&quot;:&quot;config&quot;}')}">
          <flowable:value id="a" name="Option A"></flowable:value>
          <flowable:value id="b" name="Option B"></flowable:value>
          <flowable:value id="c" name="Option C"></flowable:value>
        </flowable:formProperty>

Adding triggers to start form properties

When a workflow administrator creates a workflow configuration, they can specify which conditions trigger a workflow. For more information, see Configuring custom workflows.

Sample workflows

Need a little more guidance? Review the sample CP4Dworkflows on GitHub.