Manage workflow templates
Workflow templates define how workflows work in Pentaho Data Catalog. A workflow template specifies the workflow stages, the transitions between those stages, the actions users can perform, and the roles eligible to act at each stage. After you configure and apply a workflow template to an asset in a hierarchy, all assets under that hierarchy follow the governed review and approval lifecycle defined by the template.
Administrators and support teams use workflow templates to implement consistent governance rules across the hierarchical assets. Workflow templates help ensure that updates undergo the right levels of validation, support separation of duties, and prevent unapproved changes from being published.
Workflow templates are created using JSON and deployed through internal workflow APIs. In Data Catalog 10.2.10, workflow templates are created with the assistance of the Pentaho Support team. Once a template is created, administrators can apply it to glossary hierarchies from the Data Catalog user interface.
The following topics describe the workflow template structure, how to create templates using APIs, and how to apply them to assets.
Workflow template
A workflow template defines how a workflow operates in Data Catalog. It includes the workflow stages, the transitions between them, the actions users can perform, and the roles eligible to act at each stage. In Data Catalog, workflow templates can be created and managed only through APIs using a JSON file. This topic describes the JSON structure, explains how each element works, and provides an annotated example to help administrators understand how workflows are defined.
A workflow template consists of three primary components:
Template metadata: Name and description of the workflow
Nodes: Workflow stages (initial, intermediate, final)
Edges: Transitions between stages, including actions and role assignments
These components work together to define the full workflow lifecycle. For more information on the workflow components, see Key concepts of workflows. Data Catalog does not limit the number of workflow stages or transitions, and it allows you to implement simple approval flows or multi-stage review processes that involve different business roles. Administrators can define workflow templates to match governance requirements. When designing a template, consider:
How many review stages are required
Who must validate and approve changes
Which transitions require role-based assignment
Whether multiple branches (approve/reject) are needed
The governance level appropriate for your organization
The following example template defines a three-stage workflow:
Draft → In Review → Approved/Rejected
Template metadata
The template object identifies the workflow and provides a human-readable description.
Administrators use this information to identify the workflow template when applying it to an asset in the hierarchy.
Nodes (Workflow stages)
Nodes represent the workflow stages. Each node defines the name of the stage and whether it is the starting state, an intermediate stage, or a final state.
nodeKey
Unique identifier for the stage
name
Label displayed in the UI
state
Type of stage: initial, intermediate, final_positive, final_negative
A workflow template must contain one initial node and one or more final nodes, and you can add any number of intermediate nodes to design multi-stage workflows. Stage names are fully customizable.
Edges (Transitions between stages)
Edges define how the workflow moves from one stage to the next. Each edge includes the transition name, the action that triggers the transition, and the roles eligible to execute that action.
name
Display name of the transition shown in the UI
fromNodeKey
Current workflow stage
toNodeKey
Next workflow stage
actionKey
Internal identifier for the user-triggered action
availableAssignees
PDC roles, communities, or users ID eligible to perform this transition
isAssigneeSelectionRequired
Whether the user must assign the next participant
When a user selects an action, the workflow follows the edge mapped to the corresponding actionKey. Transitions control the direction of the workflow, who can approve changes, and how the workflow ends. Edges implement the governance rules defined by your organization.
Once you have created a JSON, you can create a workflow template using the workflows API.
If you create a workflow template using the example template and apply it to an asset, the asset moves through the following transitions:
Draft → In Review
This transition occurs when the Author selects Submit for Review in the workflow dialog.
The Author must assign a Reviewer if isAssigneeSelectionRequired is set to true.
Only users whose roles match the entries in availableAssignees appear in the assignment list.
After submission, the asset remains locked while the workflow moves to the In Review stage.
In Review → Approved
This transition occurs when the Reviewer selects Approve.
The workflow moves to the Approved node, defined as the final_positive state.
The asset is unlocked, and the approved changes become visible to all users.
No further workflow actions are available for this asset unless a new change is made.
In Review → Rejected
This transition occurs when the Reviewer selects Reject.
The workflow transitions to the Rejected node, which is defined as the final_negative state.
The asset unlocks, allowing the Author to make further edits.
Any new edit triggers a new workflow instance.
At all active workflow stages, the asset remains locked for editing and is only available for viewing. It unlocks only when the workflow reaches a final state, such as Approved or Rejected.
Create a workflow template using the workflows API
This topic describes how to create a workflow template using the workflow APIs. A workflow template defines the lifecycle states, transitions, and role assignments that an asset must follow.
In PDC 10.2.10, workflow templates can be created only through APIs, with assistance from the Pentaho support team, and are managed by administrators.
Perform the following steps to create a workflow template using the API:
Before you begin
Ensure you have the Admin role in Data Catalog and access to the workflow APIs.
Procedure
Open the workflow templates API endpoint.
Prepare the workflow template JSON that defines the workflow structure.
Submit the POST request to create the workflow template.
Example using curl:
Verify the workflow template using the GET endpoint.
Confirm that:
The template appears in the list
The states and transitions match your JSON
The assignable roles are correct
Result
You created a workflow template that defines the lifecycle states, transitions, and role assignments for the assets in a hierarchy. It is available to all assets in the hierarchy and can be applied.
Next steps
Apply the workflow template to an asset in a hierarchy, such as a glossary, category, or term. For more information, see Apply a workflow template to assets. Additionally, you can retrieve workflow history using the Workflow APIs with the help of the Pentaho Support team.
Apply a workflow template to assets
Applying a workflow template enforces a governed lifecycle for all asset updates, including creation, modification, and deletion. When a workflow template is applied, every change must pass through the workflow states defined in the workflow template before it is published. This ensures that the correct users review the asset content, approve it through a consistent process, and record it with a complete audit history.
Perform the following steps to apply a workflow template to an asset. As an example, this process shows applying a workflow template to a Business Glossary:
Before you begin
Ensure you have the Admin role or are the glossary creator.
Ensure that a workflow template exists in the system and contains valid states, transitions, and role configurations.
Procedure
Click a hierarchy (Glossary) in the left navigation menu.
The Business Glossary page opens.
Select an asset, such as a glossary, category, or term, where you want to apply the workflow. When you apply a template to a parent, it is automatically applied to all child items. If required, you can also apply a different template at the individual level.
Click the Actions drop-down menu and select Apply Template. The Apply Template dialog box opens.
In the Template Name field, select the workflow template you want to apply to the asset. Only templates created through the workflow APIs appear in the list. If you don’t find the required workflow, request an admin to create it.
(Optional) In the Workflow Description box, add a description for the workflow, and click Apply Template. The success message appears, and the applied workflow template icon is visible below the asset’s name.
Result
You applied a workflow template to the glossary. All changes to the glossary, its categories, and its terms now follow the workflow lifecycle defined in the template. Any future edit to a governed asset automatically starts a workflow instance in the Draft state.
Last updated
Was this helpful?