Updates to schedule definition (#281)

jorgenj · Jorgen Johnson · web-flow · commit dfc7de7e4771 · 2021-03-08T21:54:07.000-05:00
* Remove directInvoke

Signed-off-by: Jorgen Johnson &lt;jorgen.johnson@oracle.com&gt;

* Redefine schedule.interval to be about scheduled execution of workflows (rather than about limiting when workflows can be invoked)

Signed-off-by: Jorgen Johnson &lt;jorgen.johnson@oracle.com&gt;

* Integrate PR feedback

Signed-off-by: Jorgen Johnson &lt;jorgen.johnson@oracle.com&gt;

Co-authored-by: Jorgen Johnson &lt;jorgen.johnson@oracle.com&gt;
diff --git a/comparisons/comparison-bpmn.md b/comparisons/comparison-bpmn.md
@@ -259,7 +259,7 @@ name: Execution Timeout Workflow
 version: '1.0'
 start: Purchase Parts
 execTimeout:
-  interval: PT7D
+  duration: PT7D
   interrupt: true
   runBefore: Handle timeout
 states:
diff --git a/examples/README.md b/examples/README.md
@@ -2066,7 +2066,7 @@ Bidding is done via an online application and bids are received as events are as
     "description": "Store a single bid whole the car auction is active",
     "start": {
       "stateName": "StoreCarAuctionBid",
-      "schedule": "2020-03-20T09:00:00Z/2020-03-20T15:00:00Z"
+      "schedule": "R/PT2H"
     },
     "functions": [
         {
@@ -2115,7 +2115,7 @@ name: Car Auction Bidding Workflow
 description: Store a single bid whole the car auction is active
 start:
   stateName: StoreCarAuctionBid
-  schedule: 2020-03-20T09:00:00Z/2020-03-20T15:00:00Z
+  schedule: R/PT2H
 functions:
 - name: StoreBidFunction
   operation: http://myapis.org/carauctionapi.json#storeBid
@@ -2827,7 +2827,7 @@ This example shows the use of the workflow [execTimeout definition](../specifica
   "version": "1.0",
   "start": "StartNewOrder",
   "execTimeout": {
-    "interval": "PT30D",
+    "duration": "PT30D",
     "interrupt": true,
     "runBefore": "CancelOrder"
   },
@@ -2986,7 +2986,7 @@ name: Purchase Order Workflow
 version: '1.0'
 start: StartNewOrder
 execTimeout:
-  interval: PT30D
+  duration: PT30D
   interrupt: true
   runBefore: CancelOrder
 states:
@@ -3107,7 +3107,7 @@ the data for an hour, send report, and so on.
   "version": "1.0",
   "start": "ConsumeReading",
   "execTimeout": {
-    "interval": "PT1H",
+    "duration": "PT1H",
     "runBefore": "GenerateReport"
   },
   "keepActive": true,
@@ -3194,7 +3194,7 @@ name: Room Temp and Humidity Workflow
 version: '1.0'
 start: ConsumeReading
 execTimeout:
-  interval: PT1H
+  duration: PT1H
   runBefore: GenerateReport
 keepActive: true
 states:
diff --git a/roadmap/README.md b/roadmap/README.md
@@ -37,6 +37,7 @@ _Status description:_
 | ✔️| Change function definition 'parameters' to 'arguments' | [spec doc](../specification.md) |
 | ✔️| Replace JsonPath with jq | [spec doc](../specification.md) |
 | ✔️| Update start definition (move to top-level worklow param) | [spec doc](../specification.md) |
+| ✔️| Updated schedule definition | [spec doc](../specification.md) |
 | 🚩 | Workflow invocation bindings |  |
 | 🚩 | CE Subscriptions & Discovery |  |
 | 🚩 | Error types | [issue](https://github.com/serverlessworkflow/specification/issues/200) | 
diff --git a/schema/workflow.json b/schema/workflow.json
@@ -138,9 +138,9 @@
     "exectimeout": {
       "type": "object",
       "properties": {
-        "interval": {
+        "duration": {
           "type": "string",
-          "description": "Timeout interval (ISO 8601 duration format)",
+          "description": "Timeout duration (ISO 8601 duration format)",
           "minLength": 1
         },
         "interrupt": {
@@ -155,7 +155,7 @@
         }
       },
       "required": [
-        "interval"
+        "duration"
       ]
     },
     "transition": {
@@ -1550,7 +1550,7 @@
               "minLength": 1
             },
             "schedule": {
-              "description": "Define the time/repeating intervals or cron at which workflow instances can/should be started",
+              "description": "Define the time/repeating intervals or cron at which workflow instances should be automatically started.",
               "$ref": "#/definitions/schedule"
             }
           },
@@ -1565,7 +1565,7 @@
       "oneOf": [
         {
           "type": "string",
-          "description": "Time interval (can be repeating) described with ISO 8601 format. Declares when workflow instances can be created.",
+          "description": "Time interval (must be repeating interval) described with ISO 8601 format. Declares when workflow instances will be automatically created.  (UTC timezone is assumed)",
           "minLength": 1
         },
         {
@@ -1574,20 +1574,15 @@
           "properties": {
             "interval": {
               "type": "string",
-              "description": "Time interval (ISO 8601 format) describing when workflow instances can be created.",
+              "description": "Time interval (must be repeating interval) described with ISO 8601 format. Declares when workflow instances will be automatically created.",
               "minLength": 1
             },
             "cron": {
               "$ref": "#/definitions/crondef"
             },
-            "directInvoke": {
-              "description": "Define if workflow instances can be created outside of the defined interval/cron",
-              "type": "boolean",
-              "default": false
-            },
             "timezone": {
               "type": "string",
-              "description": "Timezone name used to evaluate the cron expression. Not used for interval as timezone can be specified there directly. If not specified, should default to local machine timezone."
+              "description": "Timezone name used to evaluate the interval & cron-expression. (default: UTC)"
             }
           },
           "oneOf": [
diff --git a/specification.md b/specification.md
@@ -728,7 +728,7 @@ You can reference the [specification examples](#Examples) to see the `keepActive
 
 | Parameter | Description | Type | Required |
 | --- | --- | --- | --- |
-| interval | Timeout interval (ISO 8601 duration format) | string | yes |
+| duration | Timeout duration (ISO 8601 duration format) | string | yes |
 | interrupt | If `false`, workflow instance is allowed to finish current execution. If `true`, current workflow execution is stopped immediately. Default is `false`  | boolean | no |
 | runBefore | Name of a workflow state to be executed before workflow instance is terminated | string | no |
 
@@ -765,7 +765,7 @@ runBefore: createandsendreport
 
 </details>
 
-The `interval` property defines the time interval of the execution timeout. Once a workflow instance is created,
+The `duration` property defines the time duration of the execution timeout. Once a workflow instance is created,
 and the amount of the defined time is reached, the workflow instance should be terminated.
 
 The `interrupt` property defines if the currently running instance should be allowed to finish its current 
@@ -3107,7 +3107,7 @@ If the start definition is of type `object`, it has the following structure:
 | Parameter | Description | Type | Required |
 | --- | --- | --- | --- |
 | stateName | Name of the starting workflow state | object | yes |
-| [schedule](#Schedule-Definition) | Define the time/repeating intervals or cron at which workflow instances can/should be started | object | yes |
+| [schedule](#Schedule-Definition) | Define the time/repeating intervals or cron at which workflow instances should be automatically started. | object | yes |
 
 <details><summary><strong>Click to view example definition</strong></summary>
 <p>
@@ -3150,19 +3150,10 @@ If `string` type, it defines the name of the workflow starting state.
 If `object` type, it provides the ability to set the workflow starting state name, as well as the `schedule` property.
 
 The `schedule` property allows to define scheduled workflow instance creation. 
-Scheduled starts have two different choices. You can define time-based intervals during which workflow instances are **allowed**
-to be created (can be repeating), or cron-based times at which a workflow instance **should** be created (automatically). 
+Scheduled starts have two different choices. You can define a repeating interval or cron-based schedule at which a workflow 
+instance **should** be created (automatically). 
 
-To better explain interval-based scheduled starts, let's say
-we have a workflow that orchestrates an online auction and should be "available" only from when the auction starts until it ends. 
-Customer bids should only be allowed during this time interval. Bids made before or after the defined time interval should not be allowed.
-
-There are two cases to discuss when dealing with interval-based scheduled starts:
-
-1. **Starting States in [Parallel](#Parallel-State) state [branches](#parallel-state-branch)**: if a state in a parallel state branch defines a scheduled start state that is not "active" at the time the branch is executed, the parent workflow should not wait until it becomes active, and just complete the execution of the branch.
-2. **Starting states in [SubFlow](#SubFlow-State) states**: if a state in a workflow definition (referenced by SubFlow state) defines a scheduled start state that is not "active" at the time the SubFlow state is executed, the parent workflow should not wait until it becomes active, and just complete the execution of the SubFlow state.
-
-You can also define cron-based scheduled starts, which allow to define periodically started workflow instances based on a [cron](http://crontab.org/) definition.
+You can also define cron-based scheduled starts, which allows you to specify periodically started workflow instances based on a [cron](http://crontab.org/) definition.
 Cron-based scheduled starts can handle absolute time intervals (i.e., not calculated in respect to some particular point in time).
 One use case for cron-based scheduled starts is a workflow that performs periodical data batch processing. 
 In this case we could use a cron definition
@@ -3192,22 +3183,21 @@ the needed events at the defined times to trigger workflow instance creation.
 #### Schedule Definition
 
 `Schedule` definition can have two types, either `string` or `object`.
-If `string` type, it defines time interval describing when the workflow instance can be created.
+If `string` type, it defines time interval describing when the workflow instance should be automatically created.
 This can be used as a short-cut definition when you don't need to define any other parameters, for example:
 
 ```json
-"schedule": "2020-03-20T09:00:00Z/2020-03-20T15:00:00Z"
+"schedule": "R/PT2H"
 ```
 
-If you need to define the `cron`, `directInvoke` or the `timezone` parameters in your `schedule` definition, you can define 
+If you need to define the `cron` or the `timezone` parameters in your `schedule` definition, you can define 
 it with its `object` type which has the following properties:
 
 | Parameter | Description | Type | Required |
 | --- | --- | --- | --- |
-| interval | Time interval (can be repeating) described with ISO 8601 format. Declares when workflow instances can be created | string | yes if `cron` not defined |
+| interval | Time interval (must be repeating interval) described with ISO 8601 format. Declares when workflow instances will be automatically created. | string | yes if `cron` not defined |
 | [cron](#Cron-Definition) | Cron expression defining when workflow instances should be created (automatically) | object | yes if `interval` not defined |
-| directInvoke | Defines if workflow instances can be created outside of the interval/cron interval. Default value is `false` | boolean | no |
-| timezone | Timezone name (for example "America/Los_Angeles") used to evaluate the cron expression against. Not used for `interval` property as timezone can be specified there directly. If not specified, should default to local machine timezone | string | no |
+| timezone | Timezone name used to evaluate the interval & cron-expression. If the interval specifies a date-time w/ timezone then proper timezone conversion will be applied. (default: UTC). | string | no |
 
 <details><summary><strong>Click to view example definition</strong></summary>
 <p>
@@ -3222,8 +3212,7 @@ it with its `object` type which has the following properties:
 
 ```json
 {
-   "cron": "0 0/15 * * * ?",
-   "directInvoke": true
+   "cron": "0 0/15 * * * ?"
 }
 ```
 
@@ -3232,7 +3221,6 @@ it with its `object` type which has the following properties:
 
 ```yaml
 cron: 0 0/15 * * * ?
-directInvoke: true
 ```
 
 </td>
@@ -3241,31 +3229,27 @@ directInvoke: true
 
 </details>
 
-The `interval` property uses the ISO 8601 time interval format (can be repeating) to describe when workflow instances are allowed be created.
-There is a number of ways to express the time interval:
+The `interval` property uses the ISO 8601 time repeating interval format to describe when workflow instances will be automatically created.
+There are a number of supported ways to express the repeating interval:
 
-1. **Start** + **End**: Defines the start and end time, for example "2020-03-20T13:00:00Z/2021-05-11T15:30:00Z", meaning workflow instances can be
-created from March 20th 2020 at 1PM UTC until May 11th 2021 at 3:30pm UTC.
-2. **Start** + **Duration**: Defines the start time and the duration, for example: "2020-03-20T13:00:00Z/P1Y2M10DT2H30M", meaning workflow instances can be created
-from March 20th 2020 at 1pm UTC and continue to do so for 1 year, 2 months, 10 days 2 hours and 30 minutes.
-3. **Duration** + **End**: Defines the duration and an end, for example: "P1Y2M10DT2H30M/2020-05-11T15:30:00Z", meaning that workflow instances can be created from
-when the first instance is created until 1 year, 2 months, 10 days 2 hours and 30 minutes from that time, or until May 11th 2020 at 3:30PM UTC, whichever comes first.
-4. **Duration**: Defines the duration only, for example: ""P1Y2M10DT2H30M"", meaning workflow instances can be created for 1 year, 2 months, 10 days 2 hours and 30 minutes
-from the time the first instance is created.
+1. `R/<Start>/<Duration>`: Defines the start time and a duration, for example: "R/2020-03-20T13:00:00Z/PT2H", meaning workflow 
+instances will be automatically created every 2 hours starting from March 20th 2020 at 1pm UTC.
+2. `R/<Duration>/<End>`: Defines a duration and an end, for example: "R/PT2H/2020-05-11T15:30:00Z", meaning that workflow instances will be 
+automatically created every 2 hours until until May 11th 2020 at 3:30PM UTC.
+3. `R/<Duration>`: Defines a duration only, for example: "R/PT2H", meaning workflow instances will be automatically created every 2 hours.
 
 The `cron` property uses a [cron expression](http://crontab.org/) 
-to describe a repeating interval upon which a workflow instance should be created (automatically).
+to describe a repeating interval upon which a workflow instance should be created automatically.
 For more information see the [cron definition](#Cron-Definition) section.
 
-The `timezone` property is used to define a time zone name to evaluate the cron expression against. If not specified, it should default to the local
-machine time zone. See [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of timezone names.
+The `timezone` property is used to define a time zone name to evaluate the cron or interval expression against. If not specified, it should default 
+to UTC time zone. See [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of timezone names.  For ISO 8601 date time 
+values in `interval` or `cron.validUntil`, runtimes should treat `timezone` as the 'local time' (UTC if `interval` is not defined by the user).
 
 Note that when the workflow starting state is an [Event](#Event-State) 
 defining cron-based scheduled starts for the runtime implementations would mean that there needs to be an event service that issues 
 the needed events at the defined times to trigger workflow instance creation.
 
-The `directInvoke` property defines if workflow instances are allowed to be created outside of the defined interval or cron expression.
-
 #### Cron Definition
 
 `Cron` definition can have two types, either `string` or `object`.
