Workflow basic configuration elements

Workflows created with the Flowable Designer can be deployed immediately. You can run and use the workflows without further customizations.

However, to be able to leverage the full potential of workflows in Collibra Data Intelligence Platform, you need to know some basic elements.

For an extensive manual about using Flowable, see the Flowable documentation.

Model keys

Model keys are unique identifiers for processes and forms in the Workflow Designer. The process key also identifies workflows in Collibra and must be unique in your environment.

If you change the process key of a workflow and deploy it again, it is considered as a completely new workflow and Collibra creates a different workflow definition for it.

If you deploy a workflow with the same key as the key or the process ID of an already existing one, a new version of the same workflow is created. All running workflow instances keep running with the old version. All workflows started after the deployment use the new version. The settings on the workflow definition remain the same and include any newly added configuration variables.

When you create new processes or forms, you must provide a key and one is automatically generated from the name of the model.

You can change the process key of a workflow:

• In the workflow BPMN: <process id="approvalProcess" ...
• In the Workflow Designer:
  1. Select your app.
  2. For the process model click → Modify Properties.

     The Modify model details dialog box appears.

  3. Change the Model key.
  4. Click OK to save your changes and close the dialog box.

     

Model keys cannot include special characters.

Workflow description

The workflow description provides details about the purpose and general usage of a workflow.

You can add a description when creating new process models.

You can change the description of a workflow:

<process id="approvalProcess" name="Approval Process" isExecutable="true">
  <documentation>
    This is the main approval process for terms.
    The subject matter expert starts by reviewing the definition. 
    After that the stakeholders are given an opportunity to provide 
    comments on the given term. The subject matter expert is then given a 
    task to process the comments and the stewards are asked to vote for 
    term approval. The stakeholders are notified of the final outcome.
  </documentation>....

Process variables

A process variable is a value that Collibra stores with each workflow instance. You can retrieve and change that value each time the workflow runs.

Setting process variables

You can use the start form to create process variables, including configuration variables. The value you enter as the Initiator variable field in the Details section of the start form is also a process variable. This variable defines the user who starts the workflow.

In your user tasks, each data entry or selection component becomes a process variable. Use the component Value to reference the variables.

In your script tasks, you set a variable with the following line of code where <variable_name> is a String and <variable_value> is an object:

execution.setVariable(<variable_name>, <varaible_value>);

Retrieving process variables

In your script tasks, you retrieve a variable with the following line of code where <variable_name> is a String:

execution.getVariable(<variable_name>);

Outside script tasks, you can retrieve the value of a variable by including the variable name in an expression: {{}}, for example {{startUser}}.

Use the form ID to reference variables created by forms.

Exchanging process variables with a sub-process

Sub-processes are workflows that run as part of a parent workflow. They are not meant to be stand-alone workflows. You must provide values at least for the start form variables that have the Required property set to true. You may also want to use the values of some of the sub-process variables in the parent workflow. To exchange information between the parent workflow and the sub-process, configure the call activity in the parent workflow:

• In the In section of the Details section, enter process variables from the parent workflow in the Source Variable column and the corresponding sub-process variables in the Target Variable column.

  Use an expression in the Source Expression column if you want to pass a hard-coded value to a sub-process variable, for example {{"Enter a brief description"}} or {{false}}.

• In the Out section of the Details section, enter sub-process variables in the Source Variable column and the corresponding process variables from the parent workflow in the Target Variable column.

Since the parent workflow and the sub-process are separate workflows, you can use the same name for corresponding variables.

Workflow dialog boxes

You can see workflow dialog boxes in the following distinct scenarios:

• When you need to provide data in a workflow start form before the workflow starts.
• When you need to complete a user task and the task sidebar is disabled in Collibra Console.

Start forms

When the start event of your workflow has a form reference, a dialog box appears before the start of the workflow. You must fill in the required information or accept the default values and submit them to start the workflow. If you close the dialog box instead of submitting the form, the workflow does not start. If you do not provide the required information and continue, the workflow starts but might not complete.

If you start a workflow from another workflow or via the API, you must provide the required information for the start forms with your request to start the workflow. In these cases, the workflow cannot generate a dialog box to request the information.

User tasks

You can see dialog boxes for user tasks only when the task sidebar option is disabled in Collibra Console. If the option is enabled, all task forms appear in the sidebar instead of dialog boxes.

The most common scenario in this case is a dialog box appearing when you click the task button in the task bar.

There are some scenarios where the dialog boxes appear automatically for user tasks:

• When the next available user task is assigned to the same user who has just completed a start form.
• When the next available user task is assigned to the same user who has just completed another user task.

For these scenarios to work, all of the following conditions must be met:

• You either start the workflow on the resource page for which the workflow is configured, or you use a global workflow.
• Any script tasks that are between the start form and the next available task or between a task and the next available task are completed.
• You do not close the first dialog box before the second one appears.
• The start form or user task and the next available task belong to the same workflow process and neither is part of a sub-process.

Create a pool and lanes

To help visualize the workflow and identify the process participants, especially in more complex diagrams, you can make use of pools and lanes. Collibra Data Intelligence Platform workflows usually have one pool that represents the process while lanes represent different participants or roles in the process.

Pools and lanes are optional in Workflow Designer.

Although lanes are merely visual aids and play no role in the execution of the workflow, use one lane per each stakeholder.

1. From the Swimlanes section of the Shape repository, drag a Pool to the canvas.

   Each pool contains by default one lane.

2. To add a second lane, from the Swimlanes section of the Shape repository, drag a Lane to the pool.

   You now have a pool with two lanes:

   

3. Move any existing diagram elements inside the lanes.
4. Rename the pool to match the name of the process.
5. Rename the lanes to match the participants in the process.

What's next

When you have added your pool and lanes, you can add your start and end events.

Create start and end events

Events represent something that happens in the process. A start event is the trigger of the process and is depicted as a circle. The end event concludes a process and is depicted as a circle with a bold outline. Each workflow must only have one start event but there may be multiple end events.

When you create a new process, it already contains a start event.

To create start and end events:

1. From the Start events section of the Shape repository, drag a Start event to the canvas.
2. From the End events section of the Shape repository, drag an End event to the canvas.

The start and end events are now disconnected but for the workflow definition to be executable there must always be a connection between them. You create that connection as you add more elements to the workflow.

Start event initiator

The start event configuration adds by default a variable that identifies the user who starts the workflow if you need that user to perform any other task or to receive workflow notifications:

• Initiator variable: initiator.

Start event form variables

The start event form variables set values that are used throughout the workflow. You can change these variables from the worfklow definition page in Collibra Data Intelligence Platform. You can use these variables to identify the users that need to perform workflow tasks and to set customizable values that are used by this or another workflow, for example the Voting Sub-Process.

To add a start event form variable:

1. On the canvas, select the start event.
2. In the attribute bar, in the Details section, select the Form properties attribute.

   The Form properties dialog box appears.

3. In the Form properties dialog box, click Add item.
4. Enter the required information.

   Set the Readable property to false to prevent the user who starts the workflow from being prompted for input.

5. Click OK to save the changes and close the dialog box.

Additional resources

• Workflow form properties
• Candidate user expressions
• Duration variables

What's next

When you have added your start and end events, you can add your workflow elements.

Add workflow elements

Once you have the start and end events and the optional pool and lanes configured, you can add other elements from the Shape repository to the canvas and connect them to create your workflow.

You add elements by dragging them from the Shape repository to the canvas. You connect elements with sequence flows.

What's next

When your workflow is ready, you can deploy it to Collibra and configure it by editing the workflow definition settings.