​
Overview

Some APIs return an async_result_id. While this is useful if you want to continue the workflow while it is running, sometimes you want to wait for the operation to complete. This is where the suspend_fn method comes in.

​
Suspending a Workflow

To suspend a workflow, you can use the ctx.suspend_fn method within a Step function. This will suspend the workflow until a resume event is received. The standard way to trigger a resume event when a async_result_id is ready is to use the resume_when_complete method. 
from workflows_py.workflow import ScreenStep, Step, Workflow
from client_manager import SampleHealthcareClient

def reasoning_sync(documents, task):
    if ctx.resume_data:
        return ctx.resume_data

    client = SampleHealthcareClient()
    async_result_id = client.v2.documents.legacy.reason(documents=documents, task=task).async_result_id
    
    client.v2.workflow_runs.resume_when_complete(
        async_result_id=async_result_id,
    )

    ctx.suspend_fn({"type": "generate-document", "asyncResultId": async_result_id})

def generate_document(ctx):
    ...

workflow = Workflow()
workflow.then(
    Step("reasoning", reasoning_sync)
).then(
    Step("generate-document", generate_document)
)
Note that the same function (reasoning_sync) will be called when the workflow is resumed, and the resume data will be passed via the ctx.resume_data property (in this case, the result from the async_result_id).

​
Showing a Loading Screen

While waiting for async results to complete, you can show a loading screen to provide visual feedback to users. To display a loading screen, call ctx.suspend_fn with a screen payload before the function returns: 
ctx.suspend_fn({
    "type": "screen",
    "props": {"asyncResultId": async_result_id, "taskDescription": "Processing documents"},
    "screenPath": "./screens/loading-screen.tsx"
})
Important Notes:
  • You must call suspend_fn before the function returns to ensure the loading screen is displayed
  • Any props passed in the props parameter will be passed to the React component at screenPath as props
  • This allows you to pass necessary metadata (such as the async_result_id or task descriptions) that the loading screen can use to provide more detailed feedback
This will display the loading screen specified in the screenPath while the workflow is suspended, providing a better user experience during long-running operations.