From 0a5b965795c18e3a7adf0371247ebb72d6c20ada Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Wed, 21 Aug 2024 16:55:48 +0200 Subject: [PATCH] - Documented the difference between an event-driven schedule and a startup listen task - Added examples to document event-driven and cron schedules Signed-off-by: Charles d'Avernas --- dsl.md | 10 ++++++++++ examples/cron-schedule.yaml | 13 +++++++++++++ examples/event-driven-schedule.yaml | 24 ++++++++++++++++++++++++ 3 files changed, 47 insertions(+) create mode 100644 examples/cron-schedule.yaml create mode 100644 examples/event-driven-schedule.yaml diff --git a/dsl.md b/dsl.md index 4315ded4..bd94a1d0 100644 --- a/dsl.md +++ b/dsl.md @@ -150,6 +150,16 @@ Workflow scheduling in ServerlessWorkflow allows developers to specify when and See the [DSL reference](dsl-reference.md#schedule) for more details about workflow scheduling. +##### Distinguishing event-driven Scheduling from start `listen` Tasks + +While both `schedule.on` and a start listener task enable event-driven execution of workflows, they serve distinct purposes and have different implications: + +- **`schedule.on`**: This property defines when a new instance of a workflow should be created based on an external event. When an event occurs that matches the criteria specified in `schedule.on`, a new workflow instance is initiated. The key point here is that `schedule.on` solely manages the creation of new workflow instances. Any faults or timeouts related to the scheduling process itself are typically invisible to the user and do not impact the workflow instance. + +- **Start `listen` task**: A start listener task defines a task that must be undertaken after a new workflow instance has been created. This task listens for specific events and begins processing once the instance is active. The critical difference lies in the fact that a start listener task operates within the context of an already instantiated workflow. If a start listener task experiences a timeout or fault, it can cause the entire workflow instance to fail or behave unexpectedly, directly impacting the flow's execution and outcome. + +In essence, while `schedule.on` is concerned with *when* a new workflow instance should be initiated, a start listener task deals with *what* should happen once the instance is active. This distinction is important because it influences how errors and timeouts are handled—`schedule.on` faults are typically invisible and do not affect the workflow, whereas start listener task failures can have a direct and potentially severe impact on the workflow instance they belong to. + ### Task Flow A workflow begins with the first task defined. diff --git a/examples/cron-schedule.yaml b/examples/cron-schedule.yaml new file mode 100644 index 00000000..dd261bd0 --- /dev/null +++ b/examples/cron-schedule.yaml @@ -0,0 +1,13 @@ +document: + dsl: 1.0.0-alpha1 + namespace: examples + name: cron-schedule + version: 1.0.0-alpha1 +schedule: + cron: 0 0 * * * +do: + - backup: + call: http + with: + method: post + endpoint: https://example.com/api/v1/backup/start \ No newline at end of file diff --git a/examples/event-driven-schedule.yaml b/examples/event-driven-schedule.yaml new file mode 100644 index 00000000..22ab0a06 --- /dev/null +++ b/examples/event-driven-schedule.yaml @@ -0,0 +1,24 @@ +document: + dsl: 1.0.0-alpha1 + namespace: examples + name: event-driven-schedule + version: 1.0.0-alpha1 +schedule: + on: + one: + with: + type: com.example.hospital.events.patients.heartbeat.low +do: + - callNurse: + call: http + with: + method: post + endpoint: https://hospital.example.com/api/v1/notify + body: + patientId: ${ $workflow.input[0].data.patient.id } + patientName: ${ $workflow.input[0].data.patient.name } + roomNumber: ${ $workflow.input[0].data.patient.room.number } + vitals: + heartRate: ${ $workflow.input[0].data.patient.vitals.bpm } + timestamp: ${ $workflow.input[0].data.timestamp } + message: "Alert: Patient's heartbeat is critically low. Immediate attention required." \ No newline at end of file