Guides

Common Patterns


Sequential Execution

The simplest pattern: execute tasks one after another, where each step depends on the previous one completing. If any step fails, the workflow stops at that point (unless you handle the error). On replay, completed steps are skipped automatically.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[workflow(
5
name = "sequential_workflow",
6
version = "1.0.0"
7
)]
8
pub async fn sequential_workflow(
9
ctx: WorkflowContext,
10
order_id: String,
11
) -> Result<OrderResult> {
12
// Step 1: Process payment
13
let payment: PaymentResult = ctx
14
.execute_task(process_payment, order_id.clone())
15
.await?;
16
17
// Step 2: Reserve inventory (only after payment succeeds)
18
let inventory: InventoryResult = ctx
19
.execute_task(reserve_inventory, order_id.clone())
20
.await?;
21
22
// Step 3: Arrange shipment (only after inventory reserved)
23
let shipment: ShipmentResult = ctx
24
.execute_task(arrange_shipment, order_id.clone())
25
.await?;
26
27
Ok(OrderResult {
28
payment_id: payment.id,
29
tracking_number: shipment.tracking,
30
})
31
}

Parallel Execution

When tasks are independent of each other, you can execute them concurrently to reduce total execution time. Orcher journals each task independently, so if the workflow crashes after two of three parallel tasks complete, only the incomplete task re-executes on replay.

Use your language's native concurrency primitives (tokio::try_join! in Rust, Promise.all in TypeScript, asyncio.gather in Python) to run multiple context calls simultaneously.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[workflow(
5
name = "parallel_workflow",
6
version = "1.0.0"
7
)]
8
pub async fn parallel_workflow(
9
ctx: WorkflowContext,
10
order_id: String,
11
) -> Result<OrderResult> {
12
// Execute multiple tasks in parallel
13
let (validation, inventory, credit_check) = tokio::try_join!(
14
ctx.execute_task::<_, _, ValidationResult>(validate_order, order_id.clone()),
15
ctx.execute_task::<_, _, InventoryResult>(check_inventory, order_id.clone()),
16
ctx.execute_task::<_, _, CreditResult>(check_credit, order_id.clone()),
17
)?;
18
19
// Process after all parallel tasks complete
20
let payment: PaymentResult = ctx
21
.execute_task(process_payment, order_id)
22
.await?;
23
24
Ok(OrderResult {
25
validated: validation.valid,
26
payment_id: payment.id,
27
})
28
}

Conditional Logic

Workflows can branch based on task results. Because the branching decision is based on a journaled value (the task result), replay will take the same branch — the determinism requirement is satisfied.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[workflow(
5
name = "conditional_workflow",
6
version = "1.0.0"
7
)]
8
pub async fn conditional_workflow(
9
ctx: WorkflowContext,
10
order_id: String,
11
) -> Result<String> {
12
let validation: ValidationResult = ctx
13
.execute_task(validate_order, order_id.clone())
14
.await?;
15
16
if validation.is_valid {
17
ctx.execute_task(process_order, order_id).await?;
18
Ok("Processed".to_string())
19
} else {
20
ctx.execute_task(reject_order, order_id).await?;
21
Ok("Rejected".to_string())
22
}
23
}

Loops

Workflows can iterate over collections. Each iteration's task call gets its own journal entry based on its sequence number, so if a workflow crashes on iteration 50 of 100, it replays the first 50 results from the journal and continues from iteration 51.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[workflow(
5
name = "batch_workflow",
6
version = "1.0.0"
7
)]
8
pub async fn batch_workflow(
9
ctx: WorkflowContext,
10
items: Vec<String>,
11
) -> Result<Vec<String>> {
12
let mut results = Vec::new();
13
14
for item in items {
15
let result: String = ctx
16
.execute_task(process_item, item)
17
.await?;
18
results.push(result);
19
}
20
21
Ok(results)
22
}

Error Handling

When a task fails (throws an exception or returns an error), the error propagates to the workflow. You can catch errors and run compensation logic — tasks that undo or clean up the effects of previously completed steps. This is the foundation of the Saga pattern, where a multi-step process is made reliable by pairing each step with a compensating action.

The compensation tasks themselves are also journaled, so if the workflow crashes during compensation, it resumes compensation from where it left off.

1
use orcher::prelude::*;
2
use anyhow::Result;
3
4
#[workflow(
5
name = "error_handling_workflow",
6
version = "1.0.0"
7
)]
8
pub async fn error_handling_workflow(
9
ctx: WorkflowContext,
10
order_id: String,
11
) -> Result<String> {
12
// Try to process payment
13
let payment_result = ctx
14
.execute_task::<_, _, PaymentResult>(process_payment, order_id.clone())
15
.await;
16
17
match payment_result {
18
Ok(payment) => {
19
// Payment succeeded, continue
20
ctx.execute_task(fulfill_order, order_id).await?;
21
Ok(format!("Success: {}", payment.id))
22
}
23
Err(e) => {
24
// Payment failed, run compensation
25
ctx.execute_task(send_failure_notification, order_id).await?;
26
Err(e)
27
}
28
}
29
}

Next Steps