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 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, select → Update model key.

     The Update model key dialog box appears.

  3. Change the model key.
  4. Click Save 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

Variables play a critical role in workflows by dynamically storing and passing data. This enables workflows to adapt to user input, system states, or external data.

Variables act as placeholders for data that you can dynamically assign, modify, or retrieve during the execution of a workflow. They allow workflows to respond to specific conditions, user inputs, or system states, making workflows more flexible and interactive.

For example, a variable can store:

• User input from a form, such as a due date entered by a user.
• Dynamic data retrieved from Collibra assets, such as the name of an asset.
• System-generated values, such as timestamps or IDs.

Setting process variables

Process variables originate from various sources:

• The start event initiator: The value you provide as the Initiator variable of the start event becomes one of the first variables, defining the user who starts the workflow. By default, the value is initiator and user tasks are automatically assigned to this candidate through the expression user(${initiator}).
• User task form fields: In user tasks, any data entry or selection component that a user interacts with becomes a process variable. You use the Value property of the component to reference this variable.
• Script task variables:
  • The scope of the variables you declare in a script task is limited to that script. However, you can set process variables, which become available outside the script, using execution.setVariable(<variable_name>, <varaible_value>);, where <variable_name> is a String and <variable_value> is an object.
  • Workflow beans: Built-in context variables that provide information about the context in which the workflow is running, such as users.current or item.type.

  • API interfaces: Interfaces such as AssetApi, UserApi, and FileApi are pre-instantiated and accessible via variables such as assetApi, userApi, and fileApi.

• Configuration variables: When you deploy a workflow, Collibra automatically adds a series of default configuration variables for each user task. These include duration variables for the due dates and escalation durations, in addition to any configuration variables you might have set.

Reserved variable names

When working with variables in workflows, it is important to be aware of reserved variable names. These are predefined variables that Collibra uses, and they cannot be overridden or redefined in your workflows. Using these reserved names for custom variables can lead to unexpected behavior or errors:

• escalationType
• event
• eventResourceId
• eventResourceType
• eventTaskCandidates
• eventTaskId
• eventTaskKey
• eventType
• eventV1
• eventV2
• initiator
• isApiV2Workflow
• item
• itemCommunity
• itemResourceId
• itemResourceType
• itemV1
• itemV2
• itemVocabulary
• mail
• users
• usersV1
• usersV2
• workflowDefinitionName
• workflowStartUserId

Retrieving process variables

You can retrieve process variables in several ways, depending on where this action occurs:

• In script tasks: You have direct access to all process variables. You can also explicitly retrieve a variable with execution.getVariable(<variable_name>);, where <variable_name> is a String.
• In other process components: Use JUEL expressions to access variables, such as ${myVariable}.
• In form components: Unless otherwise noted, retrieve the value of a variable by including the variable name in a form expression: {{}}, for example {{initiator}}.

Exchanging process variables with a sub-process

Sub-processes are workflows that run as part of a parent workflow. They are not designed to be stand-alone workflows. You must provide values for start form variables with the Required property set to true. Additionally, you may use sub-process variables in the parent workflow.

To exchange information between a parent workflow and a sub-process, configure the call activity in the parent workflow:

• In the In section of the Variable Mapping properties, add items and:
  • Enter parent workflow process variables in the Source variable field.
  • Enter the corresponding sub-process variables in the Target variable field.
  • Use an expression in the Source Expression field if to pass a hard-coded, for example ${"Enter a brief description"} or ${false}.
• In the Out section of the Variable Mapping properties, add items and:
  • Enter sub-process variables in the Source variable field.
  • Enter the corresponding parent workflow process variables in the Target variable field.

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

Important considerations

By understanding and leveraging variables effectively, you can create dynamic and responsive workflows in Collibra that cater to a wide range of business needs.

To maximize the potential of variables, consider the following:

• Descriptive naming: Use clear and meaningful names, such as requestorName instead of rn.
• Consistent naming conventions: Follow consistent patterns, for example camel case: usageRequestReason.
• Scope and data type awareness: Understand where variables are accessible and their data types.
• Variable validation: Implement validation where necessary to ensure data integrity.

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 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 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.