From 0a5b965795c18e3a7adf0371247ebb72d6c20ada Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Wed, 21 Aug 2024 16:55:48 +0200 Subject: [PATCH 1/7] - 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 From 7a8d53da1a2c4603c105d98b70b7c0a0d823e093 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Wed, 21 Aug 2024 17:11:29 +0200 Subject: [PATCH 2/7] Added an event-driven subsection to scheduling to explain expected workflow input Signed-off-by: Charles d'Avernas --- dsl.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/dsl.md b/dsl.md index bd94a1d0..9d8f1975 100644 --- a/dsl.md +++ b/dsl.md @@ -12,6 +12,7 @@ - [Components](#components) + [Task](#task) - [Scheduling](#scheduling) + + [Event-Driven Scheduling](#event-driven-scheduling) + [Task Flow](#task-flow) + [Data Flow](#data-flow) + [Runtime Expressions](#runtime-expressions) @@ -150,7 +151,15 @@ 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 +##### Event-driven scheduling + +###### Input of event-driven scheduled workflows + +In event-driven scheduled workflows, the input is structured as an array containing the events that trigger the execution of the workflow. This array serves as a vital resource, providing workflow authors with access to all relevant data associated with each triggering event. When an event activates the workflow, it populates this array with one or more occurrences, allowing authors to process multiple events simultaneously as needed. + +Authors can reference individual events within the array using syntax such as $workflow.input[index], where index indicates the position of the event, starting from 0. For instance, $workflow.input[0] refers to the first event, while $workflow.input[1] refers to the second. This structure allows for easy access to specific event details, and if multiple events are received at once, authors can iterate through the array to handle each one appropriately. This flexibility ensures that workflows can respond effectively to various conditions and triggers, enhancing their overall responsiveness and functionality. + +###### 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: From 5d7a59814b1cb64a2268402c6029d134d716f6e9 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Wed, 21 Aug 2024 17:51:14 +0200 Subject: [PATCH 3/7] Update dsl.md Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> --- dsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsl.md b/dsl.md index 9d8f1975..49621014 100644 --- a/dsl.md +++ b/dsl.md @@ -155,7 +155,7 @@ See the [DSL reference](dsl-reference.md#schedule) for more details about workfl ###### Input of event-driven scheduled workflows -In event-driven scheduled workflows, the input is structured as an array containing the events that trigger the execution of the workflow. This array serves as a vital resource, providing workflow authors with access to all relevant data associated with each triggering event. When an event activates the workflow, it populates this array with one or more occurrences, allowing authors to process multiple events simultaneously as needed. +In event-driven scheduled workflows, the input is structured as an array containing the events that trigger the execution of the workflow. This array serves as a vital resource, providing workflow authors access to all relevant data associated with each triggering event. When an event activates the workflow, it populates this array with one or more occurrences, allowing authors to process multiple events simultaneously as needed. Authors can reference individual events within the array using syntax such as $workflow.input[index], where index indicates the position of the event, starting from 0. For instance, $workflow.input[0] refers to the first event, while $workflow.input[1] refers to the second. This structure allows for easy access to specific event details, and if multiple events are received at once, authors can iterate through the array to handle each one appropriately. This flexibility ensures that workflows can respond effectively to various conditions and triggers, enhancing their overall responsiveness and functionality. From eedfe91fd23591098b62f3677c507b62ec52bb8c Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Wed, 21 Aug 2024 17:51:28 +0200 Subject: [PATCH 4/7] Update dsl.md Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> --- dsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsl.md b/dsl.md index 49621014..4fe944b5 100644 --- a/dsl.md +++ b/dsl.md @@ -157,7 +157,7 @@ See the [DSL reference](dsl-reference.md#schedule) for more details about workfl In event-driven scheduled workflows, the input is structured as an array containing the events that trigger the execution of the workflow. This array serves as a vital resource, providing workflow authors access to all relevant data associated with each triggering event. When an event activates the workflow, it populates this array with one or more occurrences, allowing authors to process multiple events simultaneously as needed. -Authors can reference individual events within the array using syntax such as $workflow.input[index], where index indicates the position of the event, starting from 0. For instance, $workflow.input[0] refers to the first event, while $workflow.input[1] refers to the second. This structure allows for easy access to specific event details, and if multiple events are received at once, authors can iterate through the array to handle each one appropriately. This flexibility ensures that workflows can respond effectively to various conditions and triggers, enhancing their overall responsiveness and functionality. +Authors can reference individual events within the array using syntax such as $workflow.input[index], where index indicates the event's position, starting from 0. For instance, $workflow.input[0] refers to the first event, while $workflow.input[1] refers to the second. This structure allows for easy access to specific event details, and if multiple events are received at once, authors can iterate through the array to handle each one appropriately. This flexibility ensures that workflows can respond effectively to various conditions and triggers, enhancing their overall responsiveness and functionality. ###### Distinguishing event-driven scheduling from start `listen` Tasks From 856bbe902d6f194a96a7a5c09cdb59e4fbd751c2 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Wed, 21 Aug 2024 17:51:45 +0200 Subject: [PATCH 5/7] Update dsl.md Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> --- dsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsl.md b/dsl.md index 4fe944b5..0bff5dd7 100644 --- a/dsl.md +++ b/dsl.md @@ -163,7 +163,7 @@ Authors can reference individual events within the array using syntax such as $w 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. +- **`schedule.on`**: This property defines when a new workflow instance should be created based on an external event. When an event matches the criteria specified in `schedule.on`, a new workflow instance is initiated. The critical point here is that `schedule.on` solely manages the creation of new workflow instances. Any faults or timeouts related to the scheduling process 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. From 504b0d0848d503f98c76faa0d0593b2545ab8895 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Wed, 21 Aug 2024 17:51:58 +0200 Subject: [PATCH 6/7] Update dsl.md Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> --- dsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsl.md b/dsl.md index 0bff5dd7..02171c49 100644 --- a/dsl.md +++ b/dsl.md @@ -165,7 +165,7 @@ While both `schedule.on` and a start listener task enable event-driven execution - **`schedule.on`**: This property defines when a new workflow instance should be created based on an external event. When an event matches the criteria specified in `schedule.on`, a new workflow instance is initiated. The critical point here is that `schedule.on` solely manages the creation of new workflow instances. Any faults or timeouts related to the scheduling process 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. +- **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 is that a start listener task operates within 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. From de12562608b5fb1c7831890879e468e5c33f2b28 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Wed, 21 Aug 2024 17:52:15 +0200 Subject: [PATCH 7/7] Update dsl.md Co-authored-by: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> --- dsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsl.md b/dsl.md index 02171c49..f37afeb7 100644 --- a/dsl.md +++ b/dsl.md @@ -167,7 +167,7 @@ While both `schedule.on` and a start listener task enable event-driven execution - **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 is that a start listener task operates within 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. +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 crucial 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 directly and potentially severely impact the workflow instance they belong to. ### Task Flow