Quickstart: Workflow

This quickstart showcases how to write applications containing stateful, long-running, reliable workflows using the Workflow API. Catalyst hosts the workflow execution engine and manages the workflow state, with the external application containing the workflow definition and business logic.

Prerequisites

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

Python

• Diagrid CLI
• Git
• Python 3.11+

.NET

• Diagrid CLI
• Git
• .NET 8.0+

JavaScript

• Diagrid CLI
• Git
• Node.JS LTS

Java

• Diagrid CLI
• Git
• Java 11.0+: OracleJDK or OpenJDK
• Apache Maven 3.9.5+

Log in to Catalyst

Authenticate to Diagrid Catalyst using the following command:

diagrid login

Confirm your organization and user details are correct:

diagrid whoami

Clone quickstart code

Clone the quickstart code from the Diagrid Labs GitHub repository and navigate to the appropriate directory:

Python

diagrid dev quickstart --type workflow --language python

.NET

diagrid dev quickstart --type workflow --language csharp

Javascript

diagrid dev quickstart --type workflow --language javascript

Java

diagrid dev quickstart --type workflow --language java

Run quickstart application

To run the quickstart locally, use the diagrid dev run command. This command uses the dapr multi-app run file in the root of the code directory to:

• Create a Catalyst project: If the project does not exist, the command will create a new project
• Create resources: Creates the necessary resources on Catalyst such as App IDs, Components, and Diagrid Pub/Sub or KV Store managed services
• Launch the quickstart applications: Locates the code directories using the values specified for workDir and launches each application using the respective app command inputs
• Inject environment variables: Configures the Dapr workflow client to talk to Catalyst

For additional details on the Catalyst local development experience, read Develop Locally with Catalyst APIs.

Python

Install python dependencies in a virtual environment.

note

This quickstart uses the venv module to create the virtual environment. Please feel free to adapt if you prefer to use conda, pipenv, or another alternative.

python -m venv venv

MacOS

If you are using MacOS, start the virtual environment with the following command:

source venv/bin/activate

tip

Don't forget to close your virtual environment with deactivate when done with the quickstart

Linux

If you are using Linux, start the virtual environment with the following command:

source venv/bin/activate

tip

Don't forget to close your virtual environment with deactivate when done with the quickstart

Windows

If you are using PowerShell on Windows, start the virtual environment with the following command:

venv/Scripts/Activate.ps1

If you are using the Command Prompt on Windows, start the virtual environment with the following command:

venv/Scripts/activate.bat

tip

If running in the Windows Command Prompt, don't forget to close your virtual environment with venv/Scripts/deactivate.bat when done with the quickstart

Install the python app requirements:

pip install -r requirements.txt

.NET

Install .NET dependencies.

dotnet restore

JavaScript

Install node dependencies.

npm install

Java

Install maven dependencies.

mvn clean install

Run the application using the following command:

Python

diagrid dev run -f dev-python-workflow.yaml --project dev-python-workflow

.NET

diagrid dev run -f dev-csharp-workflow.yaml --project dev-csharp-workflow

JavaScript

diagrid dev run -f dev-js-workflow.yaml --project dev-js-workflow

Java

diagrid dev run -f dev-java-workflow.yaml --project dev-java-workflow

Interact with Workflow API

With the quickstart application running, it's time to test the Workflow API. Use the curl commands below or take advantage of the REST Client extension using Visual Studio Code with the test.rest file in the root folder of the repo.

Upon successful execution of the three curl commands below, the order-workflow logs should show three requests:

1. A request to start the workflow execution
2. A status request
3. A final request for the completed workflow output

You can also use the Workflow viewer in the Catalyst web console to see the details for your completed workflow instance.

Start workflow

Open a new terminal and execute the following curl command to start a new workflow instance:

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

This command will return the instance ID of the workflow that has been started. Save this result as an environment variable for future API calls.

export WORKFLOW_ID=<YOUR_WORKFLOW_INSTANCE_ID>

Get workflow status

Get the current workflow status using the workflow instance ID:

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

You can also see more detailed workflow logs using the Diagrid CLI:

diagrid workflow get $WORKFLOW_ID --app-id order-workflow

Clean up resources

If you are not going to continue to use this application, you can delete the resources using the following commands:

diagrid appid delete order-workflow

If you want to delete the entire Catalyst project, including the managed infrastructure resources, run the diagrid project delete command.