Skip to content

Commit b424a9d

Browse files
committed
Cross-link Design Patterns and Guides
Design Patterns and Guides moved to sibling top-level sidebar sections recently and had zero cross-links in either direction. Adds a "Guides" section to 8 pattern pages pointing to matching worked examples, and reciprocal links back from those guides' Related resources sections. Also fixes two stale links to the saga pattern that pointed at an external site and a thin blurb instead of the in-depth /design-patterns/saga-pattern page, and renames "Related resources" to "Related patterns" on the four batch-processing pages for heading consistency with the rest of the section.
1 parent d07dd49 commit b424a9d

20 files changed

Lines changed: 54 additions & 9 deletions

docs/best-practices/error-handling.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ consistent across retries but unique across Workflow Executions.
123123
## Implement compensation with the Saga pattern {/* #saga-pattern */}
124124

125125
When a multi-step process fails partway through, previous steps may need to be undone. The
126-
[Saga pattern](/evaluate/use-cases-design-patterns#saga) coordinates a sequence of operations where each step has a
126+
[Saga pattern](/design-patterns/saga-pattern) coordinates a sequence of operations where each step has a
127127
compensating action that reverses its effects. If any step fails, the compensating actions for previously completed
128128
steps execute in reverse order.
129129

docs/design-patterns/approval.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -863,6 +863,10 @@ If the approver's interface needs immediate confirmation that the approval was a
863863
- [Updatable Timer](/design-patterns/updatable-timer): Extending approval deadlines dynamically.
864864
- [Saga Pattern](/design-patterns/saga-pattern): Executing compensating actions on rejection.
865865

866+
## Guides
867+
868+
- [Reliable document approvals](/guides/reliable-document-approvals): A complete Python implementation with SLA timers, automatic escalation, resubmission loops, and audit logging.
869+
866870
## Sample code
867871

868872
**Java**

docs/design-patterns/batch-iterator.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -244,7 +244,7 @@ public class BatchIteratorWorkflowImpl implements BatchIteratorWorkflow {
244244
- **Passing unnecessary state into `continueAsNew`.** All arguments are serialized and stored in history. Pass only the minimal state needed (offset, counters) — not accumulated result lists or large collections that grow with each page.
245245
- **Sequential processing bottlenecks.** The default implementation processes one record at a time per page. You can fan out Activities concurrently within a page using the SDK's async primitives for higher per-page throughput — note this increases per-page event count accordingly. If record-set-wide throughput matters more than rate limiting, consider [Sliding Window](/design-patterns/sliding-window) or [MapReduce Tree](/design-patterns/mapreduce-tree).
246246

247-
## Related resources
247+
## Related patterns
248248

249249
- [Continue-as-New pattern](/design-patterns/continue-as-new) — core concepts for history management via `continueAsNew`
250250
- [Sliding Window](/design-patterns/sliding-window) — bounded concurrency that progresses at the rate of the fastest processor

docs/design-patterns/continue-as-new.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -414,6 +414,11 @@ You cannot undo Continue-As-New once triggered.
414414
- **[Child Workflows](/design-patterns/child-workflows)**: Decomposing work into sub-Workflows. Consider Parent Close Policy when combining with Continue-As-New.
415415
- **[Signal with Start](/design-patterns/signal-with-start)**: Idempotent Workflow start with an initial Signal — use Workflow ID without Run ID to interact with continued executions.
416416

417+
## Guides
418+
419+
- [Track customer loyalty points with durable Workflows](/guides/entity-pattern-loyalty-points): Uses Continue-As-New to keep a long-lived customer loyalty account within Event History limits, including an upgrade path at the Continue-As-New boundary for Worker Versioning.
420+
- [Player Sessions That Survive Anything](/guides/durable-gaming-sessions): Uses Continue-As-New so a multiplayer game session can run for weeks without unbounded history growth.
421+
417422
## Sample code
418423

419424
**Java:**

docs/design-patterns/downstream-rate-limiting.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,10 @@ The concurrency slots (`MaxConcurrentActivityExecutionSize`, `MaxConcurrentWorkf
287287
- **[Fairness](/design-patterns/fairness)**: Give each tenant an equal throughput share when multiple tenants share capacity.
288288
- **[Worker-Specific Task Queues](/design-patterns/worker-specific-taskqueue)**: Route Activities to a specific Worker host for resource or data affinity.
289289

290+
## Guides
291+
292+
- [Rate-limit downstream APIs with separate Task Queues](/guides/rate-limit-downstream-apis): A Python walkthrough covering multiple rate-limited APIs (SendGrid, Stripe, OpenAI), 429 handling with `Retry-After`, and backlog draining strategies.
293+
290294
## References
291295

292296
- **Python**[`max_task_queue_activities_per_second`](https://python.temporal.io/temporalio.worker.WorkerConfig.html#max_task_queue_activities_per_second) on [`Worker`](https://python.temporal.io/temporalio.worker.Worker.html)

docs/design-patterns/entity-workflow.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -536,6 +536,11 @@ Trade-offs:
536536
- **[Request-Response via Updates](/design-patterns/request-response-via-updates)**: Synchronous operations with validation.
537537
- **[Signal with Start](/design-patterns/signal-with-start)**: Idempotent Workflow start with an initial Signal.
538538

539+
## Guides
540+
541+
- [Track customer loyalty points with durable Workflows](/guides/entity-pattern-loyalty-points): A complete Python implementation of this pattern, including tier calculation, Continue-As-New, and Worker Versioning for accounts that span years.
542+
- [Player Sessions That Survive Anything](/guides/durable-gaming-sessions): Extends the Entity Workflow into an Actor Workflow that executes game actions — joining rooms, resolving combat — rather than only holding state.
543+
539544
## Sample code
540545

541546
**Python:**

docs/design-patterns/fanout-child-workflows.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -317,7 +317,7 @@ public class RecordBatchWorkflowImpl implements RecordBatchWorkflow {
317317
- **Passing large lists of IDs.** Workflow inputs are stored in event history. Passing millions of record IDs as a list will blow the history size limit. Use offset + length instead.
318318
- **Ignoring child failures.** A failed child does not automatically fail the parent unless you await all results. Always await child handles and handle errors explicitly.
319319

320-
## Related resources
320+
## Related patterns
321321

322322
- [Child Workflows pattern](/design-patterns/child-workflows) — core concepts for parent/child Workflow coordination
323323
- [Batch Iterator](/design-patterns/batch-iterator) — unbounded record sets with Continue-as-New pagination

docs/design-patterns/mapreduce-tree.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -431,7 +431,7 @@ public class NodeWorkflowImpl implements NodeWorkflow {
431431
- **History bloat in the Root Workflow.** Each child start and signal received adds events to the Root's history. For very large record sets, consider adding an extra tree level to keep the Root from receiving too many direct signals.
432432
- **Attempting external/downstream writes from Node Workflows.** Nodes may be retried. Any external write in a Node Workflow will be executed multiple times. Keep all side effects in Leaf Workflows (or Activities called by Leaves).
433433

434-
## Related resources
434+
## Related patterns
435435

436436
- [Fan-Out with Child Workflows](/design-patterns/fanout-child-workflows) — simpler flat fan-out for smaller record sets
437437
- [Sliding Window](/design-patterns/sliding-window) — bounded concurrency with rate limiting

docs/design-patterns/non-retryable-errors.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -480,6 +480,10 @@ try {
480480
- [Resumable Activity](/design-patterns/resumable-activity): Park the Workflow and accept a corrected input via Signal when retries are exhausted.
481481
- [Error Handling & Retry Patterns](/design-patterns/error-handling-patterns): Overview and decision tree for all retry patterns.
482482

483+
## Guides
484+
485+
- [Recover business processes without restarting](/guides/recover-without-restart): Uses `ApplicationFailure.nonRetryable()` throughout a loan pipeline to distinguish permanent failures that need a human fix from transient ones the default Retry Policy already handles.
486+
483487
## References
484488

485489
- [Temporal Retry Policies](/encyclopedia/retry-policies)

docs/design-patterns/resumable-activity.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -560,3 +560,7 @@ stateDiagram-v2
560560
- [Fast/Slow Retries](/design-patterns/fast-slow-retries): Infinite patient retries when the downstream system is temporarily unavailable.
561561
- [Signal with Start](/design-patterns/signal-with-start): Start the Workflow and send the correction Signal atomically.
562562
- [Error Handling & Retry Patterns](/design-patterns/error-handling-patterns): Overview and decision tree for all retry patterns.
563+
564+
## Guides
565+
566+
- [Recover business processes without restarting](/guides/recover-without-restart): A `recoverableStep` implementation of this pattern in a six-step loan pipeline, with Search Attribute-based routing so operators can find and fix blocked cases.

0 commit comments

Comments
 (0)