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