A Sample Workflow is a series of steps that can comprise automated actions or human-in-the-loop actions (called screens). Workflows are defined by a workflow definition file (typically in Python) and a set of screens (usually implemented in TypeScript).

A workflow definition file describes the sequence of steps, which may include:

  • Screen steps: Steps that present a UI to the user for input or review.
  • Automated steps: Steps that perform backend logic, such as calling APIs, processing documents, or transforming data.

Each step can access the results of previous steps, and workflows can be customized to fit a wide variety of business processes.

Here’s a simplified example of what a workflow definition might look like (in Python):

from workflows_py.workflow import ScreenStep, Step, Workflow

workflow = Workflow()
workflow.then(
    ScreenStep("step-1", "./screens/step-1-screen.tsx")
).then(
    Step("automated-step", lambda ctx: ...)
).then(
    ScreenStep("step-2", "./screens/step-2-screen.tsx")
)

This example shows a workflow with two screens and an automated step in between. Each step can use the context (ctx) to access data from previous steps or external systems. Read more in the context section.

​
Step Output Serialization

All outputs from workflow steps must be JSON serializable. This is a critical requirement 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:

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