Workflows and Steps

Normal Steps

You can use Step to define a normal step. Normal steps takes a body function that is called when the step is reached.

from workflows_py.workflow import Step, Workflow

def add_five(ctx):
    return ctx.get_step_result("multiply_by_two") + 5

workflow = Workflow()
workflow.then(
    Step("multiply_by_two", lambda ctx: ctx.get_start_data()["input_number"] * 2),
).then(
    Step("add_five", add_five)
)

This example shows a workflow with two automated steps. The body function of each step can either be defined inline (using the lambda keyword) or as a separate function. Body functions can use the context (ctx) to access data from previous steps or external systems. Read more in the context section. The return value of each function can be accessed by subsequent steps using ctx.get_step_result("step-id"). Normal steps also accept an options={...} argument for step-level behavior such as retries, on_failure, and next_task routing overrides. See Control Flow for those patterns.

Screen Steps

Screen steps are steps that present a UI to the user for input or review. To define a screen step, you need to both define

a React component (a .tsx file)
a ScreenStep in the workflow that points to the React component by file path

from workflows_py.workflow import ScreenStep, Step, Workflow

workflow = Workflow()
workflow.then(
    Step("prepare-greeting", lambda ctx: {"user_name": "John"})
).then(
    ScreenStep("greeting", screen_path="./screens/greeting-screen.tsx", get_props=lambda ctx: {"name": ctx.get_step_result("prepare-greeting")["user_name"]})
)

import ActionBar from "@/components/ui/action-bar";
import { useScreenFunctions } from "@samplehc/ui/contexts";

const GreetingScreen = ({ name }: { name: string }) => {
  const { handleComplete } = useScreenFunctions();
  
  return (
    <div>
      <h2>Hello, {name}!</h2>
      <p>Ready to continue with the workflow?</p>
      <ActionBar onConfirm={() => handleComplete({ result: "confirmed" })} />
    </div>
  );
};

export default GreetingScreen;

The return value of screen steps is the value passed into the result field of the handleComplete function. In the example above (see greeting-screen.tsx), the return value will be the string "confirmed". When a screen submits an object, downstream workflow steps receive that object directly. Do not unwrap an extra result field when reading the step output:

./src/screens/review-screen.tsx

handleComplete({
  result: {
    approved: true,
    memberId: "ABC123",
  },
});

./src/workflow.py

def use_review_result(ctx):
    review = ctx.get_step_result("review-screen")
    return {
        "approved": review["approved"],
        "member_id": review["memberId"],
    }

See the screens section for more information on how to create and customize screens.

Validating Screen Submissions

Use the before_complete option to run backend logic when the user completes a screen, before the workflow moves on. The handler receives the context and the screen’s submitted result, and its return value becomes the step’s result. Raising an ApiError from before_complete rejects the submission: the error is returned to the screen’s handleComplete call with the given HTTP status code, and the task stays open so the user can correct their input and resubmit.

from workflows_py.workflow import ApiError, ScreenStep

def validate_review(ctx, result):
    if not result.get("memberId"):
        raise ApiError("Member ID is required", 400)

    # The return value becomes the step result
    return {**result, "validated": True}

workflow.then(
    ScreenStep(
        "review-submission",
        screen_path="./screens/review-screen.tsx",
        before_complete=validate_review,
    )
)

before_complete is the right place for validation that needs backend data — for example, checking a submitted value against an external system before accepting it. Validation that only depends on the form itself is better done in the screen component.

Available in workflows-py >= 0.1.10.

Screen Task Priority

When several screen tasks are open at the same time — for example, from parallel branches or loop iterations — Sample routes the user to the highest-priority task after they complete their current one. Set a screen step’s priority with the priority option, either as a number or as a function of the context:

workflow.then(
    ScreenStep(
        "review-urgent-cases",
        screen_path="./screens/review-screen.tsx",
        options={
            "priority": lambda ctx: 10 if ctx.scope["item"]["is_urgent"] else 0,
        },
    )
)

Higher numbers are routed to first. The default priority is 0, and tasks with equal priority fall back to Sample’s standard routing order.

Available in workflows-py >= 0.1.22.

Step Outputs

Every step in a workflow can return a value. This value can be accessed by subsequent steps using ctx.get_step_result("step-id"). IMPORTANT: All outputs from workflow steps must be JSON serializable. This is critical for Sample Workflows to function properly, as step outputs are stored and passed between steps in a serialized format.

JSON Serializable Types

Step outputs can include:

Primitive types: string, number, boolean, null
Arrays: Lists of JSON-serializable values
Objects: Plain objects with JSON-serializable properties
Nested structures: Any combination of the above

Example: Correct Step Output

# ✅ Good - JSON serializable
def process_data(ctx):
    return {
        "user_id": 123,
        "name": "John Doe",
        "scores": [85, 92, 78],
        "metadata": {
            "processed_at": "2024-01-15T10:30:00Z",
            "status": "completed"
        }
    }

Example: Incorrect Step Output

# ❌ Bad - Not JSON serializable
def process_data(ctx):
    return {
        "user": User(id=123, name="John"),  # Class instance
        "callback": lambda x: x * 2,        # Function
        "created_at": datetime.now()        # Date object
    }

If you need to work with non-serializable data, convert it to a serializable format before returning from the step.

Version Control and Deployment

Sample Workflows are version controlled through Git, making it easy to track changes, collaborate with team members, and maintain different versions of your workflows.

Git-Based Version Control

Workflow definitions (Python files) and screen components (TypeScript files) are stored in a Git repository
This provides full history tracking and the ability to revert to previous versions if needed

Automatic Deployment

When changes are made to workflow files:

Automatic Detection: Sample automatically detects changes to workflow files
Deployment: Updated workflows are deployed and become available for use
Version Management: Previous versions remain accessible, ensuring running workflows can complete even after updates

Workflows

Screens

Integrations

Other guides

Normal Steps

Screen Steps

Validating Screen Submissions

Screen Task Priority

Step Outputs

JSON Serializable Types

Example: Correct Step Output

Example: Incorrect Step Output

Version Control and Deployment

Git-Based Version Control

Automatic Deployment

​Normal Steps

​Screen Steps

​Validating Screen Submissions

​Screen Task Priority

​Step Outputs

​JSON Serializable Types

​Example: Correct Step Output

​Example: Incorrect Step Output

​Version Control and Deployment

​Git-Based Version Control

​Automatic Deployment

Normal Steps

Screen Steps

Validating Screen Submissions

Screen Task Priority

Step Outputs

JSON Serializable Types

Example: Correct Step Output

Example: Incorrect Step Output

Version Control and Deployment

Git-Based Version Control

Automatic Deployment