Skip to content

Feat/expose advanced workflow management apis - #837

Merged
JoshVanL merged 2 commits into
dapr:mainfrom
javier-aliaga:feat/expose-advanced-workflow-management-apis
Oct 5, 2026
Merged

JoshVanL merged 2 commits into
dapr:mainfrom
javier-aliaga:feat/expose-advanced-workflow-management-apis

Conversation

@javier-aliaga

@javier-aliaga javier-aliaga commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

Description

Closes the documentation and example gap for the advanced workflow management APIs. No SDK code was needed.

ListInstanceIDs, GetInstanceHistory and RerunWorkflowFromEvent are already reachable from the Go SDK: client.NewWorkflowClient() returns *durabletask-go/workflow.Client directly, so the SDK inherits the full upstream surface. What was missing was any documentation or example for them. None of the three appeared in the Go client guide or in examples/, and neither did 7 other management operations already available on the same client.

This PR adds:

A new examples/workflow-management example. It chains the three APIs the way a caller is expected to use them: list the instances, read one instance's history to locate a rerunnable event, then rerun from that event with a replacement input. Registered in the validate_examples.yaml matrix so CI exercises it.

A "Managing workflows" section in the Go client guide. Covers the three APIs plus the behaviour that is not evident from the signatures:

  • the pagination loop ends when the continuation token comes back nil, and the page size is an upper bound rather than an exact count;
  • GetInstanceHistory reports NotFound once state is purged;
  • rerun requires a terminal, non-child source instance, targets an event's own EventId rather than its position in the history, and accepts only TaskScheduled, TimerCreated and ChildWorkflowInstanceCreated events;
  • which work is replayed and which is re-executed. Work that completed and was recorded before the target event is replayed from history, but earlier work that had not completed (in-flight activities, unfired timers, unfinished child workflows) is re-executed in the new instance. In a parallel workflow this also covers an activity whose completion was recorded after the target event. This matters for activities that are not idempotent.

Listing requires a state store with actor support that can list keys; the Redis component in the example's config/ qualifies.

Issue reference

Please reference the issue this PR will close: #833

The API list being audited comes from dapr/dapr#9729.

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

  • Code compiles correctly
  • Created/updated tests
  • Extended the documentation

Add examples/workflow-management demonstrating the three advanced
workflow management APIs reachable through client.NewWorkflowClient():
ListInstanceIDs (paginated instance listing), GetInstanceHistory and
RerunWorkflowFromEvent.

The example chains them the way a caller is expected to: list the
instances, read one instance's history to locate a rerunnable event,
then rerun from that event. Register it in the example validation
matrix so CI exercises it.

Relates to dapr#833

Signed-off-by: Javier Aliaga <javier@diagrid.io>
@javier-aliaga
javier-aliaga requested review from a team as code owners September 1, 2026 13:06
@codecov

codecov Bot commented Sep 1, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 56.71%. Comparing base (c9af9fd) to head (290702f).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #837      +/-   ##
==========================================
- Coverage   56.73%   56.71%   -0.03%     
==========================================
  Files          52       52              
  Lines        3784     3784              
==========================================
- Hits         2147     2146       -1     
- Misses       1482     1483       +1     
  Partials      155      155              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@mikeee mikeee left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dapr/docs#4951

fyi - docs have moved to dapr/docs

Example looks good 👍

The validate-examples job failed on the new example. Its expected line
"worker started" is a substring of the sidecar's own log line
`msg="worker started with backend dapr.actors/v1"`, which Dapr emits
before the example prints anything.

mechanical-markdown searches for each expected line from the start of
the combined output and then requires the matched indices to ascend, so
the generic phrase bound to the earlier sidecar log and the run was
reported as out of order even though every line was present.

Print "workflow worker started" instead, which does not appear in
sidecar output, and update the assertion and sample output to match.
Verified with `mm.py README.md` (exit 0, twice), the same tool and
version CI installs.

Relates to dapr#833

Signed-off-by: Javier Aliaga <javier@diagrid.io>
@javier-aliaga

Copy link
Copy Markdown
Contributor Author

@mikeee moved the docs

javier-aliaga added a commit to javier-aliaga/docs that referenced this pull request Oct 5, 2026
The Workflows section of the Go client guide still used the removed
github.com/dapr/go-sdk/workflow package (workflow.NewWorker,
workflow.NewClient). Replace it with the current API from go-sdk
(dapr.NewWorkflowClient over durabletask-go), as updated in
dapr/go-sdk#777 before the docs moved here.

Add a "Managing workflows" section covering ListInstanceIDs,
GetInstanceHistory and RerunWorkflowFromEvent, moved out of
dapr/go-sdk#837 at the maintainer's request.

Signed-off-by: Javier Aliaga <javier@diagrid.io>
@JoshVanL
JoshVanL merged commit e06de53 into dapr:main Oct 5, 2026
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature [1.19]: Expose advanced workflow management APIs

3 participants