Skip to main content

Quickstart: Workflow

In this quickstart, you'll run an order processing workflow on Catalyst Cloud. You will learn how to:

  • Provision a Catalyst project with a managed workflow engine using the Diagrid CLI.
  • Run a stateful, multi-step order workflow that chains inventory checking, payment processing, and notification activities.
  • Start, monitor, and inspect workflow executions using both the API and the Catalyst web console.

1. Prerequisites​

Before you proceed, ensure you have the following prerequisites installed.

2. Log in to Catalyst​

Authenticate to Diagrid Catalyst using the following command:

diagrid login

This command opens a new browser window where where you'll be shown a confirmation code that should match the code in your terminal. Confirm the code, and if you're not logged into Catalyst, you'll be redirected to login.

Confirm your user details are correct using the following command:

diagrid whoami

The expected output contains the name of the organization, your user name, and the Catalyst API endpoint.

3. Clone Quickstart Code​

Clone the quickstart code from GitHub:

git clone https://github.com/diagridio/catalyst-quickstarts

Navigate to the quickstart directory:

cd catalyst-quickstarts/workflow/python

4. Install Dependencies​

Install the dependencies for the workflow application.

Create and activate a Python virtual environment:

uv venv
source .venv/bin/activate

Install dependencies:

uv sync

5. Run the application with Catalyst Cloud​

The diagrid dev run command creates your Catalyst project, provisions resources (App IDs, workflow engine, managed state store), configures environment variables, and launches your application connected to Catalyst Cloud.

Run the application:

diagrid dev run -f workflow-quickstart.yaml --project workflow-quickstart --approve
tip

Wait a few seconds until you see application logs in the terminal to ensure the application is up and running and connected to Catalyst.

6. Start and inspect a workflow instance​

The Order Processing workflow chains notification, inventory, payment, and shipping activities, see the diagram for more details.

6.1 Start workflow​

Open a new terminal and start a new workflow by making a POST request to the start endpoint:

curl -i -X POST http://localhost:5001/workflow/start -H "Content-Type: application/json" -d '{"name":"Car", "quantity":2}'

This returns a workflow instance ID. Copy the value from the response and save it as an environment variable for subsequent calls:

export INSTANCE_ID=<YOUR_INSTANCE_ID>

6.2 Get workflow status​

Get the workflow status by making a GET request to the status endpoint and providing the instance ID.

curl -i -X GET http://localhost:5001/workflow/status/$INSTANCE_ID

The response is a JSON structure that is similar to this:

{
    "exists":true,
    "isWorkflowRunning":false,
    "isWorkflowCompleted":true,
    "createdAt":"<DATE_TIME>",
    "lastUpdatedAt":"<DATE_TIME>",
    "runtimeStatus":1,
    "failureDetails":null
}

6.3 View in the Catalyst web console​

Open the Workflow viewer in the Catalyst Cloud web console and select the workflow instance that you just started to see a visual execution trace. The viewer displays each activity in sequence, its completion status, and the total workflow duration — useful for debugging long-running or failed executions.

Catalyst Workflow viewer showing the completed order-workflow execution with activity statuses and timing

7. Clean Up​

Press CTRL+C in the terminal that runs diagrid dev run to stop the application and disconnect from Catalyst Cloud.

To delete the entire project and all provisioned resources:

diagrid project delete workflow-quickstart

Summary​

In this quickstart you:

  • Logged in to Catalyst and provisioned a managed workflow project with a single CLI command (diagrid dev run).
  • Ran an order processing workflow that's using task chaining.
  • Inspected workflow execution state using the status endpoint and the Catalyst web console.

Catalyst handled workflow state durability, activity orchestration, and retries automatically — no infrastructure to manage.

Next steps​

  • Learn Dapr Workflow with Dapr University, a free online sandbox environment to explore the Dapr workflow API.
  • Explore the Workflow SDK guides for building workflows from scratch, understanding workflow patterns, and resiliency.
  • Try the Workflow Composer to scaffold workflow projects based on diagrams or try our Claude skills for Dapr to build entire Dapr workflow applications.