Update eventDataFilter to call out that the entire event can be accessed (#349)

* Update eventDataFilter to make entire cloud-event accessible.

Signed-off-by: Jorgen Johnson <[email protected]>

* Small text fixes and Roadmap update

Signed-off-by: Tihomir Surdilovic <[email protected]>

Co-authored-by: Jorgen Johnson <[email protected]>
Co-authored-by: Tihomir Surdilovic <[email protected]>

Author: 3 people

comparisons/comparison-brigade.md

@@ -398,6 +398,7 @@ start: LogEventData
 events:
 - name: execEvent
   type: exec
+  dataOnly: false
 functions:
 - name: consoleFunction
   type: console
@@ -408,7 +409,7 @@ states:
   - eventRefs:
     - execEvent
     eventDataFilter:
-      results: "${ .event }"
+      toStateData: "${ .event }"
     actions:
     - name: eventInfoAction
       functionRef:
@@ -490,7 +491,7 @@ states:
   - eventRefs:
     - execEvent
     eventDataFilter:
-      data: "${ .event }"
+      toStateData: "${ .event }"
     actions:
     - name: helloAction
       actionDataFilter:
@@ -565,6 +566,7 @@ start: ExecEventState
 events:
 - name: execEvent
   type: exec
+  dataOnly: false
 - name: nextEvent
   type: next
   kind: produced
@@ -579,7 +581,7 @@ states:
     - execEvent
     actions: []
     eventDataFilter:
-      data: "${ .execEvent }"
+      toStateData: "${ .execEvent }"
   transition:
     nextState: NextEventState
     produceEvents:
@@ -597,7 +599,7 @@ states:
   - eventRefs:
     - nextEvent
     eventDataFilter:
-      data: "${ .nextEvent }"
+      toStateData: "${ .nextEvent }"
     actions:
     - name: consoleLogAction
       functionRef:

examples/README.md

@@ -317,7 +317,8 @@ filters what is selected to be the state data output which then becomes the work
      "onEvents": [{
          "eventRefs": ["GreetingEvent"],
          "eventDataFilter": {
-            "data": "${ .data.greet }"
+            "data": "${ .greet }",
+            "toStateData": "${ .greet }"
          },
          "actions":[  
             {  
@@ -363,7 +364,8 @@ states:
   - eventRefs:
     - GreetingEvent
     eventDataFilter:
-      data: "${ .data.greet }"
+      data: "${ .greet }"
+      toStateData: "${ .greet }"
     actions:
     - functionRef:
         refName: greetingFunction
@@ -3224,7 +3226,7 @@ the data for an hour, send report, and so on.
             }
           ],
           "eventDataFilter": {
-            "data": "${ .readings }"
+            "toStateData": "${ .readings }"
           }
         }
       ],
@@ -3307,7 +3309,7 @@ states:
     - functionRef:
         refName: LogReading
     eventDataFilter:
-      data: "${ .readings }"
+      toStateData: "${ .readings }"
   end: true
 - name: GenerateReport
   type: operation

roadmap/README.md

@@ -31,6 +31,7 @@ _Status description:_
 | ✔️| Add subflow actions `version` property | [spec doc](../specification.md) |
 | ✔️| Renamed `schemaVersion` to `specVersion` and it is now a required parameter | [spec doc](../specification.md) |
 | ✔️| Add GraphQL support for function definitions | [spec doc](../specification.md) |
+| ✔️| Added "dataOnly" property to Event Definitions (allow event data filters to access entire event) | [spec doc](../specification.md) |
 | 🚩 | Workflow invocation bindings |  |
 | 🚩 | CE Subscriptions & Discovery |  |
 | 🚩 | Error types | [issue](https://github.com/serverlessworkflow/specification/issues/200) | 

schema/events.json

@@ -61,6 +61,11 @@
           },
           "additionalItems": false
         },
+        "dataOnly": {
+          "type": "boolean",
+          "default": true,
+          "description": "If `true`, only the Event payload is accessible to consuming Workflow states. If `false`, both event payload and context attributes should be accessible "
+        },
         "metadata": {
           "$ref": "common.json#/definitions/metadata",
           "description": "Metadata information"

schema/workflow.json

@@ -1679,11 +1679,11 @@
       "properties": {
         "data": {
           "type": "string",
-          "description": "Workflow expression that filters of the event data (payload)"
+          "description": "Workflow expression that filters the received event/payload (default: '${ . }')"
         },
         "toStateData": {
           "type": "string",
-          "description": " Workflow expression that selects a state data element to which the event payload should be added/merged into. If not specified, denotes, the top-level state data element."
+          "description": " Workflow expression that selects a state data element to which the filtered event should be added/merged into. If not specified, denotes, the top-level state data element."
         }
       },
       "additionalProperties": false,

specification.md

@@ -536,6 +536,10 @@ Here is an example using an event filter:
 <img src="media/spec/event-data-filter-example1.png" height="400px" alt="Event Data Filter Example"/>
 </p>
 
+Note that the data input to the Event data filters depends on the `dataOnly` property of the associated [Event definition](#Event-Definition).
+If this property is not defined (has default value of `true`), Event data filter expressions are evaluated against the event payload (the CloudEvents `data` attribute only). If it is set to
+`false`, the expressions should be evaluated against the entire CloudEvent (including its context attributes).
+
 #### Using multiple data filters
 
 As [Event states](#Event-State) can take advantage of all defined data filters. In the example below, we define
@@ -1934,6 +1938,7 @@ defined via the `parameters` property in [function definitions](#FunctionRef-Def
 | type | CloudEvent type | string | yes |
 | kind | Defines the event is either `consumed` or `produced` by the workflow. Default is `consumed` | enum | no |
 | [correlation](#Correlation-Definition) | Define event correlation rules for this event. Only used for consumed events | array | no |
+| dataOnly | If `true` (default value), only the Event payload is accessible to consuming Workflow states. If `false`, both event payload and context attributes should be accessible | boolean | no |
 | [metadata](#Workflow-Metadata) | Metadata information | object | no |
 
 <details><summary><strong>Click to view example definition</strong></summary>
@@ -2138,6 +2143,10 @@ says that these events must all have a context attribute named "department" with
 This allows developers to write orchestration workflows that are specifically targeted to patients that are in the hospital urgent care unit, 
 for example.
 
+The `dataOnly` property deals with what Event data is accessible by the consuming Workflow states.
+If its value is `true` (default value), only the Event payload is accessible to consuming Workflow states. 
+If `false`, both Event payload and context attributes should be accessible.
+
 #### Correlation Definition
 
 | Parameter | Description | Type | Required |