quickstarts/tutorials/workflow/python/external-system-interaction

External Events

This tutorial demonstrates how to author a workflow where the workflow will wait until it receives an external event. This pattern is often applied in workflows that require an approval step. For more information about the external system interaction pattern see the Dapr docs.

Inspect the code

Open the external_events_workflow.py file in the tutorials/workflow/python/external-system-interaction/external_events folder. This file contains the definition for the workflow. It is an order workflow that requests an external approval if the order has a total price greater than 250 dollars.

graph LR
   SW((Start
   Workflow))
   IF1{Is TotalPrice
    > 250?}
   IF2{Is Order Approved
   or TotalPrice < 250?}
   WAIT[Wait for
   approval event]
   EX{Event
   received?}
   PO[Process Order]
   SN[Send Notification]
   EW((End
   Workflow))
   SW --> IF1
   IF1 -->|Yes| WAIT
   IF1 -->|No| IF2
   EX -->|Yes| IF2
   EX -->|No| SN
   WAIT --> EX
   IF2 -->|Yes| PO
   PO --> SN
   IF2 -->|No| SN
   SN --> EW

Run the tutorial

1. Use a terminal to navigate to the tutorials/workflow/python/external-system-interaction/external_events folder.

2. Install the dependencies using pip:

   pip3 install -r requirements.txt
   

3. Navigate one level back to the external-system-interaction folder and use the Dapr CLI to run the Dapr Multi-App run file

   ```bash
   

   dapr run -f .

   <!-- END_STEP -->
   
   

4. Use the POST request in the externalevents.http file to start the workflow, or use this cURL command:

   curl -i --request POST \
   --url http://localhost:5258/start \
   --header 'content-type: application/json' \
   --data '{"id": "b7dd836b-e913-4446-9912-d400befebec5","description": "Rubber ducks","quantity": 100,"total_price": 500}'
   

   The input for the workflow is an Order object:

   {
       "id": "b7dd836b-e913-4446-9912-d400befebec5",
       "description": "Rubber ducks",
       "quantity": 100,
       "total_price": 500
   }
   

5. Use the GET request in the externalevents.http file to get the status of the workflow, or use this cURL command:

   curl --request GET --url http://localhost:3558/v1.0/workflows/dapr/b7dd836b-e913-4446-9912-d400befebec5
   

   The workflow should still be running since it is waiting for an external event.

   The app logs should look similar to the following:

   == APP - externalevents == Received order: Order { id = b7dd836b-e913-4446-9912-d400befebec5, description = Rubber ducks, quantity = 100, total_price = 500.0 }.
   

6. Use the POST request in the externalevents.http file to send an approval-event to the workflow, or use this cURL command:

   curl -i --request POST \
   --url http://localhost:3558/v1.0/workflows/dapr/b7dd836b-e913-4446-9912-d400befebec5/raiseEvent/approval-event \
   --header 'content-type: application/json' \
   --data '{"order_id": "b7dd836b-e913-4446-9912-d400befebec5","is_approved": true}'
   

   The payload for the event is an ApprovalStatus object:

   {
       "order_id": "b7dd836b-e913-4446-9912-d400befebec5",
       "is_approved": true
   }
   

   The workflow will only wait for the external approval event for 2 minutes before timing out. In this case you will need to start a new order workflow instance.

7. Again use the GET request in the externalevents.http file to get the status of the workflow. The workflow should now be completed.

   The expected serialized output of the workflow is:

   "\"Order b7dd836b-e913-4446-9912-d400befebec5 has been approved.\""
   

8. Stop the Dapr Multi-App run process by pressing Ctrl+C.