Document workflow input when relying on event based schedule

[cdavernas]

What would you like to be added:

Document workflow input when relying on event based schedule.

Why is this needed:

So far, nothing in the DSL documents what should be done with the event(s) consumed by the event-based schedule of a workflow, which are therefore lost to authors.

[cdavernas]

To address that issue we could:

1. Pass the workflow events "as is" to the workflow input

If a single event has been consumed, then the input is the single event, otherwise, it is an array of the consumed events.

#$workflow.input

#single event
id: 1234
specversion: 1.0
source: https://serverlessworkflow.io
type: io.serverlessworkflow.someevent.v1
data:
  greetings: Hello, World
  
#multiple events
- id: 1234
  specversion: 1.0
  source: https://serverlessworkflow.io
  type: io.serverlessworkflow.someevent.v1
  data:
    greetings: Hello, World
- id: 5678
  specversion: 1.0
  source: https://serverlessworkflow.io
  type: io.serverlessworkflow.someevent.v1
  data:
    greetings: Hello, World

If only a single event has been consumed, the user can access it like so:

$workflow.input

If multiple events have been consumed, the user can access one of them like so:

$workflow.input[0]

Pros:

• Short
• No additional construct required

Cons:

• The author must know ahead of time if a single or multiple events are gonna be consumed

2. Pass an object with an events property to the workflow input

#$workflow.input
events:
- id: 1234
  specversion: 1.0
  source: https://serverlessworkflow.io
  type: io.serverlessworkflow.someevent.v1
  data:
    greetings: Hello, World
- id: 5678
  specversion: 1.0
  source: https://serverlessworkflow.io
  type: io.serverlessworkflow.someevent.v1
  data:
    greetings: Hello, World

The user can access input events with an array indexer, regardless of the number of events consumed:

$workflow.input.events[0]

Pros:

• Authors can access input events in a consistent fashion

Cons:

• Additional construct required

[cdavernas]

My personal preference obviously goes to n°2.

@ricardozanini @JBBianchi @fjtirado @matthias-pichler what do you guys think?

[JBBianchi]

I'd rather go for a mix of both I think, just as input but always as an array.

[ricardozanini]

I think we should distinguish the events in the data structure, hence option 2.

[JBBianchi]

I think we should distinguish the events in the data structure, hence option 2.

Does it really make sense as, when starting a scheduled workflow, the only input possible will be the said events ?

[fjtirado]

Im with @JBBianchi, the process instance is being started with the event, hence the input should be the event data.
Which I do not really understand is the array thing. If receiving multiple events, should not we start different workflow instance each one with one of the events as input?

[JBBianchi]

Im with @JBBianchi, the process instance is being started with the event, hence the input should be the event data. Which I do not really understand is the array thing. If receiving multiple events, should not we start different workflow instance each one with one of the events as input?

It depends on the event consumption strategy. If the author is waiting for all events, then the input would be an array.

[fjtirado]

It depends on the event consumption strategy. If the author is waiting for all events, then the input would be an array.

hmmm, so all is considered an and, so the trigger of the process instance will be more than one event. While in any (or) and one every event will trigger its own workflow instance.
But, I think the writer will know if the input is an array because he/she is the one specifying all, so there is not really cons there, isnt it?