Add the Durable Workflows documentation section - #607
Open
rdulmina wants to merge 1 commit into
Open
Conversation
A new top-level section alongside AI Integrations, written low-code-first (designer steps with image placeholders, generated code as snippets): - Overview: durability, interruptibility, reliability; control-flow vs agentic comparison; section index. - Getting Started: Build a Claim Handling Agent — a durable agentic workflow with a gated payment approved from the Integration Control Plane, in seven simplified steps. - Workflow Features: Transaction Workflows (activities, exactly-once recording, Auto Retry, durable timers), Human Task Workflows (typed decisions render as forms, data events, timeouts), Review Activities & Error Handling (the three retry policies, approval gates), and Durable Agentic Workflows (the DurableAgent declaration and its capabilities). - Integration Control Plane: connecting the runtime bridge, roles, the execution graph (including waiting data events), the task inbox, and instance controls. - Tutorials: index with the planned tutorial list. - API Reference: the Management API, verified against the actual service routes (instances, execution graphs, human tasks, review activities). UX steps follow the current ballerina-vscode designer flows (Add Artifact -> Durable Agentic Workflow -> Create Agent, the agent canvas capability affordances, ICP inbox decisions). Site builds clean.
rdulmina
requested review from
KavinduZoysa,
NipunaRanasinghe,
anupama-pathirage and
rosensilva
as code owners
July 31, 2026 06:21
Contributor
📝 WalkthroughWalkthroughAdded a Durable Workflows documentation set. It covers transaction, human-task, error-handling, and durable-agent workflows, a claim-handling tutorial, Control Plane management, the Management API, navigation, and tutorials. ChangesDurable Workflows
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related issues
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
rdulmina
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 15
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@en/docs/workflows/develop/durable-agentic-workflow.md`:
- Around line 91-98: Update the durable-result wording after the
supportAgent.getResult example to refer to re-issuing waitForEventResult,
keeping the documented method name consistent with the preceding call.
- Around line 30-32: Update the payClaim activity declaration to remove
retryPolicy: "manager", while preserving userRoles: "manager" for the approval
gate and the object-based retryPolicy on notifyEmployee.
- Line 3: Update the frontmatter slugs in
en/docs/workflows/develop/durable-agentic-workflow.md and
en/docs/workflows/getting-started/build-a-claim-workflow-agent.md to concise
lowercase values, using durable-agentic and build-claim-handling-agent
respectively. Update every markdown link referencing the current filenames so
they point to the renamed slug paths.
In `@en/docs/workflows/develop/human-task-workflow.md`:
- Around line 82-87: Update the workflow data submission example around the post
resource for bills to require authentication and instance-level authorization
before calling workflow:sendData, or explicitly state that these security checks
are omitted for brevity. Ensure unauthorized callers cannot submit
BillSubmission data using only the workflowId.
In `@en/docs/workflows/develop/transaction-workflow.md`:
- Around line 87-90: Update en/docs/workflows/develop/transaction-workflow.md
lines 87-90 to pass a stable idempotency key through the chargeCard activity
alongside the order and amount. Update
en/docs/workflows/develop/review-activity-and-error-handling.md lines 36-39 so
notifyEmployee deduplicates retries using the same stable key, and lines 48-50
so manual makePayment retries preserve that key. Revise line 95 to qualify the
completion guarantee for failed attempts while retaining the requirement that
externally retried activities use idempotency.
In `@en/docs/workflows/getting-started/build-a-claim-workflow-agent.md`:
- Around line 181-182: Update the curl example in the getting-started workflow
documentation to assign the instance ID to a shell variable and use that
variable within a quoted request URL, replacing the angle-bracket placeholder
while preserving the existing endpoint and response example.
- Around line 96-100: Update the payClaim activity documentation to identify it
as a mock rather than a completed payment, since it only returns a payment
identifier and ignores amount; revise the later workflow descriptions at the
sections around lines 162 and 182 to state that the workflow proposed or
approved payment, not that it recorded a paid claim.
- Around line 82-89: Define the ExpenseClaim record before the validateClaim
activity, including claimId, employee, amount, and purpose fields with their
specified types, so the activity and subsequent HTTP resource snippets compile.
- Around line 131-149: Add the ballerina/http import in the example before the
service declaration that uses http:Listener, leaving the /claims service
implementation unchanged.
In `@en/docs/workflows/icp/managing-workflows.md`:
- Line 3: Align the frontmatter title with the visible H1 in the workflow
management documentation, using one canonical page title consistently. Apply the
same correction to the additionally affected 11-11 page.
In `@en/docs/workflows/overview.md`:
- Around line 2-6: Update the front matter slug for the Durable Workflows
Overview page to use a concise route aligned with the title, such as
/durable-overview, while keeping the existing title and directory hierarchy
unchanged.
In `@en/docs/workflows/reference/management-api.md`:
- Around line 14-21: Update the management API sample so its configuration and
curl examples are consistent: either disable enableApiKey in the base
configuration or add the configured x-api-key header with the sample key to
every affected request example. Apply the same change to the examples referenced
around lines 53-56, 68-72, and 86-90.
- Around line 25-30: Update the “Caller identity headers” section to define a
trusted source and trust boundary for x-user-id and x-user-roles, requiring
values to be set or overwritten by a trusted proxy or validated from signed IdP
claims before use in authorization, filtering, or audit fields.
- Around line 3-10: The Management API documentation must distinguish the
integration-local durable workflow REST API from the ICP Management API, which
uses GraphQL and signed JWT authorization. Update the introduction in
en/docs/workflows/reference/management-api.md to define this boundary and
clarify that it is not the ICP API, then update the link at
en/docs/workflows/icp/managing-workflows.md line 89 to point to the appropriate
ICP documentation rather than this workflow API reference.
- Line 3: Update the “Management API” documentation identified by the title and
its introduction to clearly describe it as the integration-local or workflow
Management API, not the ICP Management API; preserve the documented REST routes
and x-api-key, x-user-id, and x-user-roles authentication details, and remove
any claim that it represents the ICP GraphQL surface.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: bd2bceeb-73ea-4260-b94d-ba5e38e1c2a8
📒 Files selected for processing (10)
en/docs/workflows/develop/durable-agentic-workflow.mden/docs/workflows/develop/human-task-workflow.mden/docs/workflows/develop/review-activity-and-error-handling.mden/docs/workflows/develop/transaction-workflow.mden/docs/workflows/getting-started/build-a-claim-workflow-agent.mden/docs/workflows/icp/managing-workflows.mden/docs/workflows/overview.mden/docs/workflows/reference/management-api.mden/docs/workflows/tutorials/overview.mden/sidebars.ts
| @@ -0,0 +1,116 @@ | |||
| --- | |||
| sidebar_position: 4 | |||
| title: "Durable Agentic Workflows" | |||
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## candidate files:"
for f in \
en/docs/workflows/develop/durable-agentic-workflow.md \
en/docs/workflows/getting-started/build-a-claim-workflow-agent.md
do
if [ -f "$f" ]; then
echo "FOUND $f"
sed -n '1,4p' "$f" | cat -n
else
echo "MISSING $f"
fi
done
echo
echo "## reference count and sample references:"
python3 - <<'PY'
import os, glob, re
files = [
"en/docs/workflows/develop/durable-agentic-workflow.md",
"en/docs/workflows/getting-started/build-a-claim-workflow-agent.md",
]
patterns = [f"workflows/develop/durable-agentic-workflow", f"workflows/getting-started/build-a-claim-workflow-agent"]
for p in patterns:
hits = [(x, x) for x in glob.glob("**/en/**/*.md", recursive=True) if os.path.isfile(x) for pat in patterns if pat in x]
print("sample paths:")
for f in files:
if os.path.isfile(f):
print(f)
text = open(f, "r", encoding="utf-8").read()
rel = "/".join(f.split(os.sep)[1:])
# show headings/frontmatter and markdown link mentions of target filenames/slug forms
for i,line in enumerate(text.splitlines(),1):
if line.strip().endswith("]") or "durable-agentic" in line or "claim-workflow-agent" in line or line.startswith("title:"):
print(f"{rel}:{i}: {line[:220]}")
basenames = [os.path.basename(x)for x in files]
PY
python3 - <<'PY'
import os
file_to_base = {
"en/docs/workflows/develop/durable-agentic-workflow.md": "durable-agentic-workflow.md",
"en/docs/workflows/getting-started/build-a-claim-workflow-agent.md": "build-a-claim-workflow-agent.md",
}
def find_md_refs(base):
hits = []
for root, dirs, files in os.walk("."):
if ".git" in root:
dirs[:] = []
continue
for f in files:
if f.endswith(".md"):
path=os.path.join(root,f)
try:
text=open(path, encoding="utf-8").read()
except Exception:
continue
for i,line in enumerate(text.splitlines(),1):
if base in line:
hits.append((path,i,line.strip()))
return hits
for main,base in file_to_base.items():
print("##", base)
for path,i,line in find_md_refs(base):
print(f"{path}:{i}: {line}")
PYRepository: wso2/docs-integrator
Length of output: 5477
Define concise slugs for these workflow pages and update the links.
These new pages repeat the parent workflows keyword, and the tutorial slug repeats workflow while omitting handling. Use concise, lowercase slugs such as durable-agentic and build-claim-handling-agent, and update the markdown links that point to the current filenames.
📍 Affects 2 files
en/docs/workflows/develop/durable-agentic-workflow.md#L3-L3(this comment)en/docs/workflows/getting-started/build-a-claim-workflow-agent.md#L3-L3
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/develop/durable-agentic-workflow.md` at line 3, Update the
frontmatter slugs in en/docs/workflows/develop/durable-agentic-workflow.md and
en/docs/workflows/getting-started/build-a-claim-workflow-agent.md to concise
lowercase values, using durable-agentic and build-claim-handling-agent
respectively. Update every markdown link referencing the current filenames so
they point to the renamed slug paths.
Source: Path instructions
Comment on lines
+30
to
+32
| {activity: payClaim, requiresApproval: true, userRoles: "manager", | ||
| retryPolicy: "manager"}, | ||
| {activity: notifyEmployee, retryPolicy: {maxRetries: 3, retryDelay: 2}} |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
rg -n -C 3 'retryPolicy|requiresApproval|userRoles' en/docs/workflowsRepository: wso2/docs-integrator
Length of output: 6339
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== target file =="
sed -n '1,80p' en/docs/workflows/develop/durable-agentic-workflow.md
echo
echo "== relevant review doc sections =="
sed -n '30,90p' en/docs/workflows/develop/review-activity-and-error-handling.md
sed -n '112,128p' en/docs/workflows/getting-started/build-a-claim-workflow-agent.md
echo
echo "== all retryPolicy/hasRetry occurrences =="
rg -n 'retryPolicy|hasRetry|autoRetry|Auto Retry|Human Review|requiresApproval|userRoles' en/docs/workflowsRepository: wso2/docs-integrator
Length of output: 10404
Remove the invalid activity retry policy.
retryPolicy: "manager" does not belong on this activity declaration. Keep userRoles: "manager" for the approval gate; keep the automatic retry on notifyEmployee as an object, but remove retryPolicy from payClaim.
Proposed correction
- {activity: payClaim, requiresApproval: true, userRoles: "manager",
- retryPolicy: "manager"},
+ {activity: payClaim, requiresApproval: true, userRoles: "manager"},📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| {activity: payClaim, requiresApproval: true, userRoles: "manager", | |
| retryPolicy: "manager"}, | |
| {activity: notifyEmployee, retryPolicy: {maxRetries: 3, retryDelay: 2}} | |
| {activity: payClaim, requiresApproval: true, userRoles: "manager"}, | |
| {activity: notifyEmployee, retryPolicy: {maxRetries: 3, retryDelay: 2}} |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/develop/durable-agentic-workflow.md` around lines 30 - 32,
Update the payClaim activity declaration to remove retryPolicy: "manager", while
preserving userRoles: "manager" for the approval gate and the object-based
retryPolicy on notifyEmployee.
Comment on lines
+91
to
+98
| string token = check supportAgent.sendEvent(instanceId, "billSubmitted", submission); | ||
| string reply = check supportAgent.waitForEventResult(instanceId, token); | ||
|
|
||
| // Read the final outcome (AgentBusyError while a human decision is pending). | ||
| string|error result = supportAgent.getResult(instanceId); | ||
| ``` | ||
|
|
||
| All reads are durable: results live in the workflow history, so a crashed caller can re-issue `waitForResult` and get the same answer. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
rg -n '\b(waitForResult|waitForEventResult)\b' en/docs/workflowsRepository: wso2/docs-integrator
Length of output: 480
Use waitForEventResult in the durable-result wording.
The example uses supportAgent.waitForEventResult(...), but the next sentence tells callers to re-issue waitForResult. Use the documented method name consistently.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/develop/durable-agentic-workflow.md` around lines 91 - 98,
Update the durable-result wording after the supportAgent.getResult example to
refer to re-issuing waitForEventResult, keeping the documented method name
consistent with the preceding call.
Comment on lines
+82
to
+87
| Anyone with the workflow ID can deliver the data — typically a service resource: | ||
|
|
||
| ```ballerina | ||
| resource function post [string workflowId]/bills(BillSubmission submission) returns json|error { | ||
| check workflow:sendData(expenseApprovalWorkflow, workflowId, "billSubmitted", submission); | ||
| return {workflowId, status: "BILLS_SUBMITTED"}; |
Contributor
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift
Require authorization before accepting workflow data.
The text says that anyone with a workflow ID can submit BillSubmission. If this resource is exposed without authentication and instance-level authorization, a caller who obtains an ID can inject data and resume the workflow with untrusted input. Require authorization, or state that authentication is omitted from this example.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/develop/human-task-workflow.md` around lines 82 - 87,
Update the workflow data submission example around the post resource for bills
to require authentication and instance-level authorization before calling
workflow:sendData, or explicitly state that these security checks are omitted
for brevity. Ensure unauthorized callers cannot submit BillSubmission data using
only the workflowId.
Comment on lines
+87
to
+90
| string paymentRef = check ctx->callActivity(chargeCard, | ||
| {"orderId": input.orderId, "amount": input.amount}, | ||
| retryPolicy = {maxRetries: 3, retryDelay: 2, retryBackoff: 2.0}); | ||
| ``` |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Make retried external activities idempotent and qualify replay guarantees.
The payment and notification examples enable retries without showing a stable idempotency key. The compensation text also implies that an externally completed activity cannot be repeated, which is not safe to assume for failed attempts.
en/docs/workflows/develop/transaction-workflow.md#L87-L90: pass a stable idempotency key tochargeCard.en/docs/workflows/develop/review-activity-and-error-handling.md#L36-L39: makenotifyEmployeededuplicate retries.en/docs/workflows/develop/review-activity-and-error-handling.md#L48-L50: preserve the same key across manualmakePaymentretries.en/docs/workflows/develop/review-activity-and-error-handling.md#L95-L95: qualify the completion guarantee and retain the idempotency requirement.
📍 Affects 2 files
en/docs/workflows/develop/transaction-workflow.md#L87-L90(this comment)en/docs/workflows/develop/review-activity-and-error-handling.md#L36-L39en/docs/workflows/develop/review-activity-and-error-handling.md#L48-L50en/docs/workflows/develop/review-activity-and-error-handling.md#L95-L95
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/develop/transaction-workflow.md` around lines 87 - 90,
Update en/docs/workflows/develop/transaction-workflow.md lines 87-90 to pass a
stable idempotency key through the chargeCard activity alongside the order and
amount. Update en/docs/workflows/develop/review-activity-and-error-handling.md
lines 36-39 so notifyEmployee deduplicates retries using the same stable key,
and lines 48-50 so manual makePayment retries preserve that key. Revise line 95
to qualify the completion guarantee for failed attempts while retaining the
requirement that externally retried activities use idempotency.
Comment on lines
+2
to
+6
| title: Durable Workflows Overview | ||
| description: Build long-running, crash-safe business processes with WSO2 Integrator using durable workflows, human tasks, events, and durable AI agents. | ||
| keywords: [wso2 integrator, durable workflow, workflow, human task, agentic workflow, durable agent, temporal, long running, crash recovery] | ||
| sidebar_label: Overview | ||
| slug: /workflows/overview |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Align the overview slug with the page title and directory hierarchy.
slug: /workflows/overview repeats the workflows parent keyword and omits durable from Durable Workflows Overview. Use a concise slug such as /durable-overview, or change the title to match the intended route.
Proposed front matter change
-slug: /workflows/overview
+slug: /durable-overview📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| title: Durable Workflows Overview | |
| description: Build long-running, crash-safe business processes with WSO2 Integrator using durable workflows, human tasks, events, and durable AI agents. | |
| keywords: [wso2 integrator, durable workflow, workflow, human task, agentic workflow, durable agent, temporal, long running, crash recovery] | |
| sidebar_label: Overview | |
| slug: /workflows/overview | |
| title: Durable Workflows Overview | |
| description: Build long-running, crash-safe business processes with WSO2 Integrator using durable workflows, human tasks, events, and durable AI agents. | |
| keywords: [wso2 integrator, durable workflow, workflow, human task, agentic workflow, durable agent, temporal, long running, crash recovery] | |
| sidebar_label: Overview | |
| slug: /durable-overview |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/overview.md` around lines 2 - 6, Update the front matter
slug for the Durable Workflows Overview page to use a concise route aligned with
the title, such as /durable-overview, while keeping the existing title and
directory hierarchy unchanged.
Source: Path instructions
| @@ -0,0 +1,95 @@ | |||
| --- | |||
| sidebar_position: 1 | |||
| title: "Management API" | |||
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== relevant files =="
git ls-files | grep -E '(^|/)management-api\.md$|(^|/)management\.md$' || true
echo "== management-api first 120 lines =="
if [ -f "en/docs/workflows/reference/management-api.md" ]; then
sed -n '1,180p' "en/docs/workflows/reference/management-api.md" | nl -ba
fi
echo "== reference management around API mentions =="
if [ -f "en/docs/reference/api/management.md" ]; then
sed -n '1,220p' "en/docs/reference/api/management.md" | nl -ba
fi
echo "== searches for Management API protocol/auth terms =="
rg -n -i "Management API|graphql|JWT|signed|REST|API key|api-key|caller|identity" en/docs/workflows/reference/management-api.md en/docs/reference/api/management.md 2>/dev/null || trueRepository: wso2/docs-integrator
Length of output: 338
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
for path in [
Path("en/docs/workflows/reference/management-api.md"),
Path("en/docs/reference/api/management.md"),
]:
print(f"== {path} ==")
lines = path.read_text(encoding="utf-8").splitlines()
for i, line in enumerate(lines[:180], 1):
print(f"{i:4}: {line}")
PY
echo "== focused searches =="
python3 - <<'PY'
from pathlib import Path
terms = ["Management API", "graphql", "JWT", "JWT", "signed JWT", "REST", "API key", "api-key", "caller", "identity", "X-Caller", "Authorization"]
for path in [
Path("en/docs/workflows/reference/management-api.md"),
Path("en/docs/reference/api/management.md"),
]:
print(f"== {path} ==")
for term in terms:
for i, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
if term.lower() in line.lower():
print(f"{i}: {line.strip()}")
PYRepository: wso2/docs-integrator
Length of output: 16189
Distinguish this integration-local workflow API from the ICP Management API.
en/docs/workflows/reference/management-api.md describes a REST API with x-api-key, x-user-id, and x-user-roles, while en/docs/reference/api/management.md documents the ICP GraphQL Management API with signed JWT authorization. This page claims it is the same surface the Integration Control Plane uses. Either rename it to an integration-local or workflow Management API and update the introduction, or align its protocol/routes/authentication with the ICP Management API.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/reference/management-api.md` at line 3, Update the
“Management API” documentation identified by the title and its introduction to
clearly describe it as the integration-local or workflow Management API, not the
ICP Management API; preserve the documented REST routes and x-api-key,
x-user-id, and x-user-roles authentication details, and remove any claim that it
represents the ICP GraphQL surface.
Comment on lines
+3
to
+10
| title: "Management API" | ||
| description: REST API reference for managing WSO2 Integrator durable workflows — instances, execution graphs, human tasks, and review activities. | ||
| keywords: [wso2 integrator, durable workflow, management api, rest, human task api, review activity api] | ||
| --- | ||
|
|
||
| # Management API | ||
|
|
||
| Every integration with durable workflows can expose a **Management API** — the same REST surface the [Integration Control Plane](../icp/managing-workflows.md) uses. Enable it to build custom portals, automations, or operational tooling. |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Clarify the Management API contract for durable workflows.
en/docs/workflows/reference/management-api.md now describes a REST API, but the existing ICP Management API content uses GraphQL with signed JWT authorization. Resolve whether these are separate APIs; if the workflow API is integration-local, document that boundary and update the link from en/docs/workflows/icp/managing-workflows.md.
📍 Affects 2 files
en/docs/workflows/reference/management-api.md#L3-L10(this comment)en/docs/workflows/icp/managing-workflows.md#L89-L89
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/reference/management-api.md` around lines 3 - 10, The
Management API documentation must distinguish the integration-local durable
workflow REST API from the ICP Management API, which uses GraphQL and signed JWT
authorization. Update the introduction in
en/docs/workflows/reference/management-api.md to define this boundary and
clarify that it is not the ICP API, then update the link at
en/docs/workflows/icp/managing-workflows.md line 89 to point to the appropriate
ICP documentation rather than this workflow API reference.
Comment on lines
+14
to
+21
| ```toml | ||
| [ballerina.workflow.management] | ||
| enableManagementApi = true | ||
| port = 8234 # default | ||
| enableApiKey = true # optional API-key protection | ||
| apiKeyValue = "<key>" | ||
| apiKeyHeader = "x-api-key" | ||
| ``` |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the examples work with the sample configuration.
The sample enables API-key protection with x-api-key, but every curl example omits that header. A copied example will be rejected. Either disable API-key protection in the base example or add -H 'x-api-key: <key>' to each request.
Also applies to: 53-56, 68-72, 86-90
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/reference/management-api.md` around lines 14 - 21, Update
the management API sample so its configuration and curl examples are consistent:
either disable enableApiKey in the base configuration or add the configured
x-api-key header with the sample key to every affected request example. Apply
the same change to the examples referenced around lines 53-56, 68-72, and 86-90.
Comment on lines
+25
to
+30
| ### Caller identity headers | ||
|
|
||
| | Header | Purpose | | ||
| | --- | --- | | ||
| | `x-user-id` | Recorded in audit fields (`completedBy`, `decidedBy`). | | ||
| | `x-user-roles` | Comma-separated roles; tasks and reviews are filtered and authorized against them. | |
Contributor
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate file =="
git ls-files | rg '(^|/)management-api\.md$|workflows/reference/management-api\.md$' || true
echo "== target excerpt =="
if [ -f en/docs/workflows/reference/management-api.md ]; then
nl -ba en/docs/workflows/reference/management-api.md | sed -n '1,80p'
fi
echo "== search headers/usages =="
rg -n "x-user-id|x-user-roles|caller identity|trusted proxy|authorized|audit|completedBy|decidedBy" -S .Repository: wso2/docs-integrator
Length of output: 283
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== target excerpt =="
cat -n en/docs/workflows/reference/management-api.md | sed -n '1,140p'
echo "== search headers/usages =="
rg -n "x-user-id|x-user-roles|caller identity|trusted proxy|authorized|audit|completedBy|decidedBy" -S .Repository: wso2/docs-integrator
Length of output: 33209
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== management API docs references =="
rg -n "management api|x-api-key|apiKeyHeader|x-user-id|x-user-roles|proxy|auth|authorized|roles" en/docs/workflows -S
echo "== broader docs searches for identity-header wording =="
rg -n "Identity headers|caller identity|x-user-id|x-user-roles|proxy|trusted|overrid|overwrite|signed|claim" en/docs -SRepository: wso2/docs-integrator
Length of output: 50377
Define a trusted source for identity headers.
x-user-roles controls visibility and authorization, and x-user-id feeds audit fields. When the API accepts these headers directly, callers can impersonate another user or role. Define the trust boundary for these values, such as requiring a trusted proxy to set/overwrite them or validating signed identity claims from an IdP.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@en/docs/workflows/reference/management-api.md` around lines 25 - 30, Update
the “Caller identity headers” section to define a trusted source and trust
boundary for x-user-id and x-user-roles, requiring values to be set or
overwritten by a trusted proxy or validated from signed IdP claims before use in
authorization, filtering, or audit fields.
Broken links, images & orphan pages
Links/images come from one crawl of the production build (baseUrl-aware). Orphans are docs not referenced by Summary
Broken links & imagesIntroduced by this PRThis PR introduces 15 broken link(s)/image(s): Show 15
Already on
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A new top-level section alongside AI Integrations, written low-code-first (designer steps with image placeholders, generated code as snippets):
UX steps follow the current ballerina-vscode designer flows (Add Artifact -> Durable Agentic Workflow -> Create Agent, the agent canvas capability affordances, ICP inbox decisions). Site builds cleanly.
Summary by CodeRabbit