Tagging Process Definitions
Tagging enables users to label Process Definitions with one or many custom tags. This is useful in instances where a user wants to change a Process Definition without making code changes. Without tagging, if a user wants to change their Process Definition, they must update their calls to create Process Instances/Process Tokens to reference a newer Process Definition. The process of moving to a new Process Definition is streamlined with the use of activities as an existing tag can be easily moved to a new Process Definition and used as a reference for the Process Token.
Adding a Tag via Process Definition
A Tag can be added to a Process Definition by following the steps outlined below.
- Log in to the Backoffice application and navigate to Process Definitions found on the left vertical navigation menu.
- From the list of Process Definitions, expand the options available for the desired Process Definition by clicking the drop-down arrow.
- Under the 'Tags' column, click the green plus icon to open the 'Add Process Definition Tag' popup modal.
- The modal enables users to search existing Tags or create a new Tag to add to the Process Definition. A Tag can only be added to one Process Definition at a time. A Process Definition can have multiple Tags.
- If creating a new Tag, a unique Tag name and color must be provided. If no colour is set, the Tag will default to grey.
Moving Tags
Tags can be edited and moved using the Backoffice application. For instance, an existing tag can be associated with a new Process Definition by adding the tag using the plus icon. A tag can only be associated with one Process Definition at a time. If a tag is already associated with another Process Definition, a warning will be displayed to confirm the moving of the tag to a new Process Definition.
To add an existing tag to a new Process Definition, follow the steps outlined below:
- Click the 'Search Tags' filter to expand the list of existing tags created in TrustX.
- Beside each tag is the name of the Process Definition that the tag currently belongs to.
- Select the desired tag to add to the Process Definition. A warning will appear that reads: "The tag is currently used by Process Definition "SimpleTemplate v1".
- Clicking 'Add Tag' will open a second dialog box. To confirm the moving of the tag, enter the tag name into the text field and click 'Move'.
- Once confirmed, the existing tag will be moved to the chosen Process Definition.
Adding a Tag via API
A Tag can be added to a Process Definition using the TrustX API by calling the /api/process-manager/processDefinitions/{processDefinitionId}/tags endpoint. This section demonstrates a sample request and response that can be expected when adding a new tag to a Process Definition.
This operation will move an existing Tag from another Process Definition if it already exists. Returns HTTP 201 for successful creation or move of the tag(s) and tag(s) created or modified in body, otherwise an appropriate error. Note:
- Tags are unique but can be moved from one process definition to another.
- Tags must be alphanumeric and can contain spaces, hyphen (-) or underscore (_).
- Tags cannot start or end with a space; tags that start or end with a space will be trimmed.
Permissions: TNT#{tenantid}#ProcessManager:tagProcessDefinition
Example Request:
POST https://{{tenant}}.{{region}}.trustx.com/api/process-manager/processDefinitions/{processDefinitionId}/tagsContent-Type: application/jsonAuthorization: Bearer {{token}}{ "tags": [ { "name": "Example_Tag", "description": "Example", "displayColor": "#adff2f" } ]}Example Response:
{ "tags": [ { "processDefinitionName": "ExampleTagging", "processDefinitionVersion": 1, "processDefinitionFullName": "ExampleTagging v1", "name": "Example_Tag", "description": "Example", "displayColor": "#adff2f", "createdDtm": "2025-05-20T08:57:27.098Z", "lastUpdatedDtm": "2025-05-20T08:57:27.098Z", "createdBy": "API Key: aa22test", "lastUpdatedBy": "API Key: aa22test" } ]}Returning Tags
Using the TrustX API, a list of tags can be returned per tenant using the /api/process-manager/processDefinitions/tags endpoint
The API allows the caller to filter on one or more Tag names (comma-separated) parameters. Wildcard matches are performed for Tag names, unless the exactMatch parameter is set to true.
Permissions: TNT#{tenantid}#ProcessManager:tagProcessDefinition
Example Request:
GET https://{{tenant}}.{{region}}.trustx.com/api/process-manager/processDefinitions/tagsContent-Type: application/jsonAuthorization: Bearer {{token}}{ "names": "Example_Tag", "exactMatch": true}Example Response:
{ "tags": [ { "processDefinitionName": "ExampleTagging", "processDefinitionVersion": 1, "processDefinitionFullName": "ExampleTagging v1", "name": "Example_Tag", "description": "Example", "displayColor": "#adff2f", "createdDtm": "2025-05-20T08:57:27.099Z", "lastUpdatedDtm": "2025-05-20T08:57:27.099Z", "createdBy": "API Key: aa22test", "lastUpdatedBy": "API Key: aa22test" } ]}Previewing Process Definition Tags
The Tags page enables Backoffice users to view all tags and their associated Process Definitions that have been created in the system.
Deleting a Tag via API
A tag can be deleted from a Process Definition using the /api/process-manager/processDefinitions/{processDefinitionId}/tags/{tagName} endpoint.
Once the Tag is deleted, it cannot be referenced within the system (subject to cache expiry).
Deleting a Tag that is being used to reference a Process Definition when creating Process Tokens or Process Instances, it will no longer be possible to create new Process Tokens or Process Instances.
Permissions: TNT#{tenantid}#ProcessManager:tagProcessDefinition
Example Request:
DELETE https://{{tenant}}.{{region}}.trustx.com/api/process-manager/processDefinitions/tags/{tagName}Content-Type: application/jsonAuthorization: Bearer {{token}}{}