- 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 <[email protected]>

Author: cdavernas

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.

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

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."