Table of contents

Designing and creating custom workflows

You can use Flowable to create process definitions to manage a specific business process.

A process definition is a series of connected steps that must be completed to accomplish a specific goal. The process definition specifies:
  • The tasks that comprise the process
  • The sequence of the tasks
  • The transitions between the tasks

Supported tools

You must use Flowable (https://flowable.com/open-source/) to create custom process definitions. You can import the following types of files to IBM® Cloud Pak for Data:
  • BPMN files
  • BPMN 2.0 XML files
  • ZIP files containing BPMN or BPMN 2.0 XML files and resource files for the process definitions

Recommended skills

To create custom process definitions, you should have 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.

The following process definition options are not supported in Cloud Pak for Data:
  • Submitting signals or messages
  • Timers, including timers based on events
  • Asynchronously execution of a workflow in the background

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.

The concepts are described in the subsequent text. This illustration shows a workflow type with three top-level templates. (The templates are called Template A, Template B, and Template C.) Template A does not have any helper templates. Template B uses to Helper template A, which uses Helper template B. Template C uses Helper template C.
Top-level templates
At a minimum, you must have at least one top-level template associated 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.

All of the top level templates for a given workflow type must meet the following criteria:
  • Be in the same target namespace

    For details, see: targetNamespace.

  • Custom request workflows only: Use the same start form properties

    Start form properties describe the set of input fields that are presented to the user when submitting a new request. For details, 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
  • Other helper templates
All of the helper templates must be in the helper namespace. For details, see targetNamespace.
Restriction: You cannot upload helper templates individually. You must include them in a ZIP file that contains at least one top-level templates.

Workflow type requirements

As you plan your workflow type, ensure that you consider the following requirements:
  • A workflow type must include at least one top-level template (process definition).
    • Any top-level templates with the same targetNamespace will be added to the same workflow type when they are imported to Cloud Pak for Data.
    • To create a new workflow type, specify unique target namespace.

    For details, see: targetNamespace.

  • Custom request workflows only: Any top-level templates that are associated with a given workflow type must have identical start form properties.
  • Each process definition must have a unique identifier. In Flowable, this identifier is called the process definition key. The identifier must be unique across all templates.
    The identifier is specified in the id attributed of the <process> XML tag:
    <process  id="Unique_ID"  name="Process name" isExecutable="true">

If the preceding requirements are not met, you cannot import the process definition BPMN files to Cloud Pak for Data

Required conventions for process definitions

As you develop your process definitions, ensure that you use the following conventions:

targetNamespace
Use a targetNamespace to categorize your process definitions based on the workflow type it is associated with. The targetNamespace enables you 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 and there is any variation 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:
    <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:
    targetNamespace="https://dataplatform.cloud.ibm.com/workflows/artifacts/artifacts_cud"
  • For custom request workflows, specify:
    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:
    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
Ensure that each user tasks include the following elements:
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. Consider using prefixes to determine the order in which tasks appear in Cloud Pak for Data.
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.

Provide a static title and a dynamic title.

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 should 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 what information a user can enter or select when completing the task. User tasks can include the following elements:
Short text field
Enables a user to enter a short string of alphanumeric text.

Specify type="string" in the formProperty. For example:

<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: expression="${cpd:conf('{"cpd_type":"long_text"}')}"
    • BPMN file: expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;long_text&quot;}')}"
For example:
<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:
<flowable:formProperty 
   id="fulfill_date" 
   name="Fulfill by" 
    type="date" 
   readable="false">
</flowable:formProperty>
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('{&quot;cpd_type&quot;:&quot;url&quot;}')}"
For example:
<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_list"}')}"
    • BPMN file: expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;multi_select_list&quot;}')}"

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

For example:
<flowable:formProperty 
  id="options_list" 
   type="enum"  
   expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;multi_select_list&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 type="enum" in the formProperty.

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

For example:
<flowable:formProperty 
  id="options_list_2" 
   type="enum"   
  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('{&quot;cpd_type&quot;:&quot;dropdown&quot;}')}"

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

For example:
<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>
Categories
You can give each user task a category. 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: Indicates that a task should be hidden in the Task inbox but that the action buttons should be displayed on the artifact details page.

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
Governance artifact workflows only: Indicates that when a workflow administrator creates a workflow configuration, the Automatically publish artifacts checkbox should be displayed for the step.
For example:
<userTask 
   id="review" 
   name="Review" 
   flowable:dueDate="${review_due_date}" 
    flowable:category="review"  
   flowable:formFieldValidation="true">
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 should 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 should be disabled until the user provides a comment.
For example:
<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>

Adding triggers to start form properties

When a workflow administrator creates a workflow configuration, they can specify which conditions trigger a workflow. However, this is only possible if your process definition includes triggers.

You can enable the workflow administrator to create different configurations depending on the values of the triggers. You can define a single trigger variable for each workflow type. You can use the following types of triggers:
Watson™ Knowledge Catalog category
Governance artifact workflows only: A different workflows can be triggered when a user selects or specifies a governance category in the start form.

Specify the following values in the formProperty:

  • expression with the appropriate format for your environment:
    • Flowable Modeler: expression="${cpd:conf('{"cpd_type":"wkc_category","kind":"trigger"}')}"
    • BPMN file: expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;wkc_category&quot;,&quot;kind&quot;:&quot;trigger&quot;}')}"
For example:
<flowable:formProperty 
   id="category" 
   name="Category" 
   type="string" 
    expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;wkc_category&quot;,&quot;kind&quot;:&quot;trigger&quot;}')}"  
   readable="false" 
   required="true">
</flowable:formProperty>
Drop-down list in a start form
Different workflows can be triggered when a user selects an option from a drop-down list.

Specify the following values in the formProperty:

  • expression with the appropriate format for your environment:
    • Flowable Modeler: expression="${cpd:conf('{"cpd_type":"dropdown","kind":"trigger"}')}"
    • BPMN file: expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;dropdown&quot;,&quot;kind&quot;:&quot;trigger&quot;}')}"
For example:
<flowable:formProperty 
   id="request_priority" 
   name="Priority" 
   type="enum" 
    expression="${cpd:conf('{&quot;cpd_type&quot;:&quot;dropdown&quot;,&quot;kind&quot;:&quot;trigger&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>
Radio button in a start form
Different workflows can be triggered when a user selects an option from a list of radio buttons.

Specify the following values in the formProperty:

  • expression with the appropriate format for your environment:
    • Flowable Modeler: expression="${cpd:conf('{"kind":"trigger"}')}"
    • BPMN file: expression="${cpd:conf('{&quot;kind&quot;:&quot;trigger&quot;}')}"
For example:
<flowable:formProperty 
  id="options_list_2" 
  type="enum"
   expression="${cpd:conf('{&quot;kind&quot;:&quot;trigger&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>

Sample workflows

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