Skip to content

Latest commit

 

History

History
183 lines (136 loc) · 6.8 KB

README.md

File metadata and controls

183 lines (136 loc) · 6.8 KB

Human Interaction Pattern

Description of the Sample

This sample demonstrates the human interaction pattern with the Azure Durable Task Scheduler using the Python SDK. This pattern is used for workflows that require human approval or input before continuing.

In this sample:

  1. The orchestrator submits an approval request using the submit_approval_request activity
  2. It then waits for either an external event (approval response) or a timeout
  3. When it receives a response or times out, it calls the process_approval activity
  4. The final result includes the approval status and related information

This pattern is useful for:

  • Approval workflows (expense reports, document reviews, change requests)
  • Business processes that require human decision making
  • Multi-step processes with human validation steps
  • Implementing timeouts for human response

Prerequisites

  1. Python 3.9+
  2. Docker (for running the emulator) installed
  3. Azure CLI (if using a deployed Durable Task Scheduler)

Configuring Durable Task Scheduler

There are two ways to run this sample locally:

Using the Emulator (Recommended)

The emulator simulates a scheduler and taskhub in a Docker container, making it ideal for development and learning.

  1. Pull the Docker Image for the Emulator:
docker pull mcr.microsoft.com/dts/dts-emulator:latest
  1. Run the Emulator:
docker run --name dtsemulator -d -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest

Wait a few seconds for the container to be ready.

Note: The example code automatically uses the default emulator settings (endpoint: http://localhost:8080, taskhub: default). You don't need to set any environment variables.

Using a Deployed Scheduler and Taskhub in Azure

Local development with a deployed scheduler:

  1. Install the durable task scheduler CLI extension:

    az upgrade
az extension add --name durabletask --allow-preview true

  2. Create a resource group in a region where the Durable Task Scheduler is available:

    az provider show --namespace Microsoft.DurableTask --query "resourceTypes[?resourceType=='schedulers'].locations | [0]" --out table
    az group create --name my-resource-group --location <location>

  3. Create a durable task scheduler resource:

    az durabletask scheduler create \
    --resource-group my-resource-group \
    --name my-scheduler \
    --ip-allowlist '["0.0.0.0/0"]' \
    --sku-name "Dedicated" \
    --sku-capacity 1 \
    --tags "{'myattribute':'myvalue'}"

  4. Create a task hub within the scheduler resource:

    az durabletask taskhub create \
    --resource-group my-resource-group \
    --scheduler-name my-scheduler \
    --name "my-taskhub"

  5. Grant the current user permission to connect to the my-taskhub task hub:

    subscriptionId=$(az account show --query "id" -o tsv)
loggedInUser=$(az account show --query "user.name" -o tsv)

az role assignment create \
    --assignee $loggedInUser \
    --role "Durable Task Data Contributor" \
    --scope "/subscriptions/$subscriptionId/resourceGroups/my-resource-group/providers/Microsoft.DurableTask/schedulers/my-scheduler/taskHubs/my-taskhub"

How to Run the Sample

Once you have set up either the emulator or deployed scheduler, follow these steps to run the sample:

  1. First, activate your Python virtual environment (if you're using one):
python -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate
  1. If you're using a deployed scheduler, you need set Environment Variables:
export ENDPOINT=$(az durabletask scheduler show \
    --resource-group my-resource-group \
    --name my-scheduler \
    --query "properties.endpoint" \
    --output tsv)

export TASKHUB="my-taskhub"

  1. Start the worker in a terminal:

    python worker.py

    You should see output indicating the worker has started and registered the orchestration and activities.

  2. In a new terminal (with the virtual environment activated if applicable), run the client:

Note: Remember to set the environment variables again if you're using a deployed scheduler.

python client.py

This will launch an interactive console client that creates an approval request and waits for your response.

Identity-based authentication

Learn how to set up identity-based authentication when you deploy the app Azure.

Understanding the Output

When you run the sample, you'll see output from both the worker and client processes:

Worker Output

The worker shows:

  • Registration of the orchestrator and activities
  • Logging when the approval request is submitted
  • The orchestrator waiting for an external event (your approval)
  • Processing of the approval once received (or timeout handling)

Client Output

The client shows:

  • Creating a new approval request with a unique ID
  • Initial status of the request (Pending)
  • Prompting you to approve or reject the request (press Enter to approve, type "reject" to reject)
  • Submitting your response
  • Final status showing the outcome (Approved, Rejected, or Timeout)

The example demonstrates how a workflow can pause execution while waiting for human input, then continue processing once the input is received or a timeout occurs.

Reviewing the Orchestration in the Durable Task Scheduler Dashboard

To access the Durable Task Scheduler Dashboard and review your orchestration:

Using the Emulator

  1. Navigate to http://localhost:8082 in your web browser
  2. Click on the "default" task hub
  3. You'll see the orchestration instance in the list
  4. Click on the instance ID to view the execution details, which will show:
    • The call to the submit_approval_request activity
    • The waiting period for an external event
    • The potential parallel timeout task
    • The reception of the external event (if approved before timeout)
    • The call to the process_approval activity with the decision
    • The final result

Using a Deployed Scheduler

  1. Navigate to the Scheduler resource in the Azure portal
  2. Go to the Task Hub subresource that you're using
  3. Click on the dashboard URL in the top right corner
  4. Search for your orchestration instance ID
  5. Review the execution details

The dashboard visualizes how the orchestration pauses while waiting for human input, showing the power of durable orchestrations to maintain state across long-running operations even when waiting for external events.