Skip to content

Starts

StartDefinition

A StartDefinition may be defined using one of the following, depending on the desired behaviour:

If omitted from the workflow definition the DefaultStartDefinition will be used, which means the workflow will only be executed when called.

DefaultStartDefinition

The default start definition is used for workflows that should only execute when called. This means subflows, workflows triggered by scripts, and workflows triggered manually by humans.

Parameter Description Type Required
type Identifies which kind of StartDefinition is being used. In this case it must be set to default. string yes
state References a defined state's id. This state will be used as the entrypoint into the workflow. If left undefined, it defaults to the first state defined in the states list. string no

ScheduledStartDefinition

The scheduled start definition is used for workflows that should execute at regularly defined times.

Scheduled workflow can be manually triggered for convenience and testing. They never have input data, so accurate testing should use {} as input.

Parameter Description Type Required
type Identifies which kind of StartDefinition is being used. In this case it must be set to scheduled. string yes
state References a defined state's id. This state will be used as the entrypoint into the workflow. If left undefined, it defaults to the first state defined in the states list. string no
cron Defines the time(s) when the workflow should execute using a CRON expression. string yes

Example (snippet)

start:
  type: scheduled
  cron: '* * * * *' # Trigger a new instance every minute.

EventStartDefinition

The event start definition is used for workflows that should be executed whenever a relevant CloudEvents event is received.

See StartEventDefinition for an explanation of the input data of event-triggered workflows.

Parameter Description Type Required
type Identifies which kind of StartDefinition is being used. In this case it must be set to event. string yes
state References a defined state's id. This state will be used as the entrypoint into the workflow. If left undefined, it defaults to the first state defined in the states list. string no
event Defines what events can trigger the workflow. StartEventDefinition yes

EventsXorStartDefinition

The event "xor" start definition is used for workflows that should be executed whenever one of multiple possible CloudEvents events is received.

See StartEventDefinition for an explanation of the input data of event-triggered workflows.

Parameter Description Type Required
type Identifies which kind of StartDefinition is being used. In this case it must be set to eventsXor. string yes
state References a defined state's id. This state will be used as the entrypoint into the workflow. If left undefined, it defaults to the first state defined in the states list. string no
events Defines what events can trigger the workflow. []StartEventDefinition yes

EventsAndStartDefinition

The event "and" start definition is used for workflows that should be executed when multiple matching CloudEvents events are received.

See StartEventDefinition for an explanation of the input data of event-triggered workflows.

Parameter Description Type Required
type Identifies which kind of StartDefinition is being used. In this case it must be set to eventsAnd. string yes
state References a defined state's id. This state will be used as the entrypoint into the workflow. If left undefined, it defaults to the first state defined in the states list. string no
lifespan An ISO8601 duration string. Sets the maximum duration an event can be stored before being discarded while waiting for other events. string no
correlate CloudEvents event context keys can must exist on every event and have matching values to be grouped together. []string no
events Defines what events can trigger the workflow. []StartEventDefinition yes

StartEventDefinition

The StartEventDefinition is a structure shared by various start definitions involving events.

Parameter Description Type Required
type Identifies which CloudEvents events can trigger the workflow by requiring an exact match to the event's own type context value. string yes
filters Optional key-value pairs to further restrict what events can trigger the workflow. For each pair, incoming CloudEvents context values will be checked for a match. All pairs must find a match for the event to be accepted. The "keys" are strings that match exactly to specific context keys, but the "values" can be "glob" patterns allowing them to match a range of possible context values. object no

The input data of an event-triggered workflow is a JSON representation of all the received events stored under keys matching the events' respective type. For example, this CloudEvents event will result in the following input data in a workflow triggered by a single event:

CloudEvents Event

{
    "specversion" : "1.0",
    "type" : "com.github.pull.create",
    "source" : "https://github.com/cloudevents/spec/pull",
    "subject" : "123",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "text/xml",
    "data" : "<much wow=\"xml\"/>"
}

Input Data

{
    "com.github.pull.create": {
        "specversion" : "1.0",
        "type" : "com.github.pull.create",
        "source" : "https://github.com/cloudevents/spec/pull",
        "subject" : "123",
        "id" : "A234-1234-1234",
        "time" : "2018-04-05T17:31:00Z",
        "comexampleextension1" : "value",
        "comexampleothervalue" : 5,
        "datacontenttype" : "text/xml",
        "data" : "<much wow=\"xml\"/>"
    }
}