Skip to content

Commit 0adb51a

Browse files
jmagakGitHub Actionsclaude
authored
RHDHBUGS-3014: Create Guidance for Enforcing Unique Workflow IDs (#2123)
* Create Guidance for Enforcing Unique Workflow IDs * Create Guidance for Enforcing Unique Workflow IDs * Fix AsciiDoc structure validation errors in workflow ID guidance Fixed improperly nested description list syntax that was causing document structure validation failures. Replaced `:::` items with bold text and bullet points where they appeared within numbered list steps or as sub-headings within `::` sections. Changes: - proc-restore-workflow-visibility-by-removing-duplicate-entries.adoc: Converted description list items to bullet points within step 6.c - ref-unique-workflow-id-requirements-to-prevent-duplicates.adoc: Converted nested description list items to bold text headings Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * Fix CQA-03: Convert bullet list to numbered list in procedure Changed bullet points (*) to numbered sub-sub-steps (...) within the .Procedure section to comply with CQA requirement that all lists in PROCEDURE modules must be numbered. Fixes: Mixed list in .Procedure -- convert to numbered Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * Fix content structure * Fix content structure * Apply Tim's suggestion * Apply suggestions --------- Co-authored-by: GitHub Actions <github-actions@github.com> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 69003fc commit 0adb51a

4 files changed

Lines changed: 218 additions & 0 deletions

‎assemblies/extend_orchestrator-in-rhdh/assembly-build-and-deploy-serverless-workflows.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,5 +47,8 @@ include::../modules/extend_orchestrator-in-rhdh/proc-deploy-workflows-on-a-clust
4747

4848
// best practices when creating workflows
4949
include::../modules/extend_orchestrator-in-rhdh/ref-best-practices-when-creating-serverless-workflows.adoc[leveloffset=+1]
50+
51+
// maintaining unique workflow IDs to prevent duplicates
52+
include::../modules/extend_orchestrator-in-rhdh/ref-unique-workflow-id-requirements-to-prevent-duplicates.adoc[leveloffset=+1]
5053
ifdef::parent-context[:context: {parent-context}]
5154
ifndef::parent-context[:!context:]

‎assemblies/extend_orchestrator-in-rhdh/assembly-diagnose-and-resolve-serverless-workflow-issues.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,5 +20,8 @@ include::../modules/extend_orchestrator-in-rhdh/proc-troubleshoot-cross-namespac
2020

2121
// Troubleshooting workflows missing from the {product-very-short} UI
2222
include::../modules/extend_orchestrator-in-rhdh/proc-troubleshoot-workflows-missing-from-the-rhdh-ui.adoc[leveloffset=+1]
23+
24+
// Resolving duplicate workflow entries caused by shared workflow IDs
25+
include::../modules/extend_orchestrator-in-rhdh/proc-restore-workflow-visibility-by-removing-duplicate-entries.adoc[leveloffset=+1]
2326
ifdef::parent-context[:context: {parent-context}]
2427
ifndef::parent-context[:!context:]

‎modules/extend_orchestrator-in-rhdh/proc-restore-workflow-visibility-by-removing-duplicate-entries.adoc‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="restore-workflow-visibility-by-removing-duplicate-entries_{context}"]
4+
= Restore workflow visibility by removing duplicate entries
5+
6+
[role="_abstract"]
7+
To restore clear workflow visibility in the Orchestrator UI, identify workflows that share the same ID and assign unique identifiers. When you deploy multiple versions with distinct IDs, you remove duplicate entries and maintain accurate workflow tracking.
8+
9+
.Prerequisites
10+
11+
* You have administrator access to the {product-very-short} instance.
12+
* You have access to the workflow definitions and deployment manifests.
13+
14+
.Procedure
15+
16+
. Identify duplicate workflows in the Orchestrator UI:
17+
.. Navigate to the Orchestrator plugin in {product-very-short}.
18+
.. Review the workflow list for entries that appear multiple times with the same workflow name.
19+
.. Note the version information displayed in the version column of the workflow list and on the workflow details page to distinguish between duplicate entries.
20+
+
21+
[NOTE]
22+
====
23+
The version column displays metadata from the workflow definition, retrieved from the Data Index GraphQL schema. This information helps you identify which workflows share the same ID but does not prevent the duplicate entries. If a workflow definition does not specify a version, the field appears empty in the UI. Duplicate entries can occur when you deploy the same workflow ID to different runtime servers over time, because the Data Index records all executions.
24+
====
25+
26+
. Verify the workflow IDs in your workflow definitions:
27+
.. Locate the workflow definition files (`.sw.yaml` or `.sw.json` files).
28+
.. Check the `id` field in each workflow definition.
29+
.. Identify workflows that use the same `id` value, even if they have different `version` values.
30+
.. Review the `version` field in each workflow definition to understand how workflows appear in the UI.
31+
+
32+
Example of problematic workflow definitions:
33+
+
34+
[source,yaml]
35+
----
36+
# First deployment
37+
id: customer-onboarding
38+
version: "1.0"
39+
name: Customer Onboarding
40+
41+
# Second deployment (causes duplicate)
42+
id: customer-onboarding
43+
version: "2.0"
44+
name: Customer Onboarding
45+
----
46+
47+
. Determine which workflow version to retain:
48+
.. Review the workflow instances and their execution history.
49+
.. Identify which version is currently in active use.
50+
.. Check for any running instances of older versions that must complete before removal.
51+
52+
. Update workflow definitions with unique IDs:
53+
.. For the new workflow version, modify the `id` field to include a version identifier:
54+
+
55+
[source,yaml]
56+
----
57+
id: customer-onboarding-v2
58+
version: "2.0"
59+
name: Customer Onboarding
60+
----
61+
.. Maintain the original workflow ID for the current deployment.
62+
.. Build and deploy the updated workflow definition.
63+
64+
. Remove outdated workflow deployments:
65+
.. After confirming the new workflow operates correctly, remove the old workflow deployment.
66+
.. Verify that all instances of the old workflow have completed.
67+
.. Delete the workflow resources from your cluster:
68+
+
69+
[source,bash]
70+
----
71+
oc delete sonataflow <old-workflow-name> -n <workflow-namespace>
72+
----
73+
+
74+
[NOTE]
75+
====
76+
Deleting the workflow deployment removes it from the cluster but preserves historical execution records in the Data Index. Users can still view past workflow runs in {product-very-short}.
77+
====
78+
79+
. Clean historical data if necessary:
80+
+
81+
If duplicate entries persist in the UI after you remove the workflow deployments, the Data Index database has historical records from earlier workflow executions. These records preserve the execution history of workflows that ran on different runtime servers over time.
82+
+
83+
[IMPORTANT]
84+
====
85+
Back up your workflow execution records before you remove historical data from the Data Index database. Removing this data permanently prevents access to past execution records.
86+
====
87+
+
88+
.. Connect to the Data Index database to verify the duplicate entries.
89+
.. Query the workflow definitions to identify duplicate entries:
90+
+
91+
[source,sql]
92+
----
93+
SET search_path TO "sonataflow-platform-data-index-service";
94+
SELECT id, version, name FROM definitions;
95+
----
96+
.. Evaluate whether to remove the historical data.
97+
You can keep the historical data to retain past workflow execution records, which allows you to view the execution history and results of completed workflow instances.
98+
Alternatively, contact your system administrator or {company-name} Support for guidance on safely removing historical duplicate entries from the Data Index without affecting active workflow operations.
99+
100+
.Verification
101+
102+
. Navigate to the Orchestrator plugin in {product-very-short}.
103+
. Confirm that the UI shows only one entry for each workflow.
104+
. Verify that the version information displays correctly for each workflow.
105+
. Test workflow execution to confirm the correct version runs.

‎modules/extend_orchestrator-in-rhdh/ref-unique-workflow-id-requirements-to-prevent-duplicates.adoc‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
:_mod-docs-content-type: REFERENCE
2+
3+
[id="unique-workflow-id-requirements-to-prevent-duplicates_{context}"]
4+
= Unique workflow ID requirements to prevent duplicates
5+
6+
[role="_abstract"]
7+
Unique workflow IDs prevent duplicate entries in {product-very-short}. You must use distinct IDs for each deployment to avoid tracking conflicts and maintain clear workflow visibility.
8+
9+
Understand how {product-very-short} identifies workflows::
10+
+
11+
{product-very-short} identifies each workflow by using its unique ID. When you deploy or update workflows, the system uses this ID to track, display, and manage workflow instances. If multiple workflows share the same ID, {product-very-short} cannot distinguish between them, resulting in unexpected behavior.
12+
13+
Follow workflow ID format requirements::
14+
+
15+
Workflow identifiers must comply with RFC 1123 DNS label standards to function correctly across all deployment configurations. Your workflow IDs must meet these format requirements:
16+
+
17+
* Contain only lowercase letters (a-z), digits (0-9), and hyphens (-)
18+
* Start and end with a lowercase letter or digit
19+
* Not contain underscores, uppercase letters, or leading or trailing hyphens
20+
+
21+
*Valid workflow ID examples:*
22+
+
23+
* `order-processing`
24+
* `invoice123`
25+
* `customer-onboarding-flow`
26+
* `flow-01`
27+
+
28+
*Invalid workflow ID examples:*
29+
+
30+
* `OrderProcessing` (contains uppercase letters)
31+
* `order_processing` (contains underscore)
32+
* `-orderflow` (starts with hyphen)
33+
* `orderflow-` (ends with hyphen)
34+
35+
Maintain workflow ID consistency across configurations::
36+
+
37+
You must use the same workflow identifier consistently across all configurations when you build and deploy your workflow. This requirement proves essential for operator-driven deployments that use the gitops profile.
38+
+
39+
For gitops profile deployments, the Kubernetes resource name must match the workflow ID field in your workflow definition file (`.sw.yaml` or `.sw.json`). This consistency prevents deployment failures and maintains proper workflow tracking in {product-very-short}.
40+
41+
Recognize version field limitations::
42+
+
43+
Although the Serverless workflow specification allows you to define a workflow version attribute in your workflow definition, the current SonataFlow and {product-very-short} ecosystem does not support multiple versions of a workflow that share the same ID.
44+
+
45+
[IMPORTANT]
46+
====
47+
Deploying multiple workflows with the same ID and different versions is not supported and results in unexpected behavior. Each workflow ID must be unique across all deployments.
48+
====
49+
+
50+
The version field serves as metadata and appears in the {product-very-short} UI for informational purposes to help you identify workflow definitions. The backend retrieves version information from the Data Index GraphQL schema and displays it in both the workflow list view and on individual workflow details pages. If you do not specify a version in your workflow definition, the field appears empty in the UI.
51+
+
52+
The system does not use the version field to differentiate between workflows or manage workflow versions. All workflow operations, including execution, deletion, and API calls, rely solely on the workflow ID.
53+
54+
Avoid deploying workflows with duplicate IDs::
55+
+
56+
Each workflow ID must be unique across all deployments, regardless of the configured version attribute. Deploying multiple workflows with the same ID and different versions is not supported and can result in the following issues:
57+
+
58+
* Duplicate workflow entries appear in the {product-very-short} Orchestrator UI.
59+
* Workflow deletion operations become unpredictable.
60+
* Historical workflow data becomes difficult to interpret.
61+
* Workflow instance tracking becomes unreliable.
62+
+
63+
Duplicate entries can occur when you deploy workflows with the same ID to different runtime servers over time, or when you redeploy a workflow with a new version by using the same ID. Because the Data Index records all workflow executions regardless of which runtime server executed them, historical records from multiple deployments with the same ID appear as duplicate entries in the {product-very-short} UI.
64+
65+
Apply workflow version management best practices::
66+
+
67+
To maintain different versions of a workflow, assign a new workflow ID for each version. Incorporate the version identifier into the workflow ID itself using a consistent naming convention.
68+
+
69+
*Recommended naming pattern:* Use a naming convention that clearly links related versions of the same workflow:
70+
+
71+
* `workflow-name-v1` implements and deploys version 1
72+
* `workflow-name-v2` implements and deploys version 2
73+
* `workflow-name-v3` implements and deploys version 3
74+
+
75+
*Example workflow ID evolution:*
76+
+
77+
----
78+
id: customer-onboarding-v1
79+
version: "1.0"
80+
name: Customer Onboarding Workflow
81+
----
82+
+
83+
When you need to deploy an updated version:
84+
+
85+
----
86+
id: customer-onboarding-v2
87+
version: "2.0"
88+
name: Customer Onboarding Workflow
89+
----
90+
+
91+
This approach provides clarity and prevents conflicts when you manage multiple iterations of a workflow.
92+
93+
Manage workflow transitions between versions::
94+
+
95+
When you transition from one workflow version to another:
96+
+
97+
* Deploy the new workflow version with a unique ID (for example, `workflow-name-v2`).
98+
* Verify the new workflow operates correctly.
99+
* Monitor running instances of the old workflow version.
100+
* After all instances of the old workflow complete, remove the old workflow deployment.
101+
+
102+
This process helps you maintain workflow history and prevents disruption to running workflow instances.
103+
104+
[role="_additional-resources"]
105+
.Additional resources
106+
107+
* link:https://serverlessworkflow.io/[Serverless workflow specification]

0 commit comments

Comments
 (0)