Eventing architecture

Boomerang Flow supports events through an eventing implementation, based on CloudEvents and HTTPS/NATS. You can also optionally choose to extend this with other eventing systems, like Azure^® Event Grid and KNative eventing, for example.

In turn, these events are used as triggers (based on Workflow triggers) to invoke a Workflow, or to interact with an in-flight Workflow, through the Wait for Event Task.

Endpoints

Webhook

The webhook endpoint will accept a generic webhook style event with query parameters.

POST /listener/webhook?WorkflowId={id}&type={generic|slack|dockerhub}

Consumes

• application/json

Query Parameters

Payload

Any body passed in as part of the payload will be available as a Workflow parameter. See the section on Payload and Parameters.

Wait For Event

There is a special case of webhook reserved for the Wait For Event Task as part of an executing Workflow.

Note: This does not trigger a Workflow. This only completes a Task as part of the Workflow execution.

POST /listener/webhook/wfe?WorkflowId={id}&WorkflowActivityId={id2}&topic={topic}&status={status}

GET /listener/webhook/wfe?WorkflowId={id}&WorkflowActivityId={id2}&topic={topic}&status={status}

Consumes

• application/json

Query Parameters

Payload

Any body passed in as part of the payload will be available as a Task Result Parameter. See below section on Payload and Parameters.

The payload is only available to be processed when using the POST

Event

This endpoint accepts a full CloudEvent either in the JSON body or between the headers and the body. See below section on CloudEvents Specification.

This accepts any of the webhook types, a Wait For Event, or a custom event.

PUT /listener/event

Sample Custom Event Payload

{
  "specversion": "1.0",
  "type": "io.boomerang.eventing.custom",
  "subject": "/5f7e2c8969f04975a0fff357/hello",
  "source": "/origin",
  "id": "C234-1234-1234",
  "time": "2018-04-05T17:31:00Z",
  "datacontenttype": "application/json",
  "data": {
    "images": ["645e2bc24c223dc1cc3", "10196e304f6634cc582"],
    "pushed_at": 1.417566161e9,
    "pusher": "trustedbuilder",
    "tag": "latest"
  }
}

Sample Webhook Event Payload

{
  "specversion": "1.0",
  "type": "io.boomerang.eventing.custom",
  "subject": "/5f7e2c8969f04975a0fff357/hello",
  "source": "/origin",
  "id": "C234-1234-1234",
  "time": "2018-04-05T17:31:00Z",
  "datacontenttype": "application/json",
  "data": {
    "foo": "bar"
  }
}

Sample Wait For Event Payload

{
  "specversion": "1.0",
  "type": "io.boomerang.eventing.wfe",
  "subject": "/5f7e2c8969f04975a0fff357/6010b41bbadf2e7743e03324/hello",
  "source": "/origin",
  "id": "C234-1234-1234",
  "time": "2018-04-05T17:31:00Z",
  "status": "success",
  "datacontenttype": "application/json",
  "data": {
    "hello": "world"
  }
}

CloudEvents Specification

The CloudEvents specification allows for an industry-wide accepted implementation. See the specifications published here.

We are currently using v1.0 of the specification, along with the HTTP, JSON, and NATS protocol bindings.

Data attribute

The payload of the body is mapped to the CloudEvents data attribute, and in turn is available as parameters in the Workflow. See below Payload and Parameters for more details.

Type attribute

The CloudEvents type is based on the webhook type and prefixed with io.boomerang.eventing., for example, to become io.boomerang.eventing.webhook or io.boomerang.eventing.wfe or io.boomerang.eventing.custom.

Subject attribute

The Workflow ID is passed in as the CloudEvents subject as /<WorkflowId> with an optional /<topic> to become /<WorkflowId>/<topic>.

Payload and Parameters

There are two ways for retrieving parameters from the event payload.

Workflow Parameter JSON Path

Workflow input parameters allow a JsonPath to be set for mapping values in the event payload when an event triggers a Workflow.

For example, if the above sample event payload was received, and you had a Workflow input parameter with JsonPath of push_data.tag, then it would get a value as part of the execution of latest. You could also have an input parameter with a JsonPath of push_data.images[2], which would map to the value of 51a9c7c1f8bb2fa19bcd09789a34e63f35abb80044bc10196e304f6634cc582c at Workflow execution.

Workflow Payload Parameter

The entire CloudEvent data attribute becomes a Workflow input parameter called eventPayload that you can access in your Workflow.

Wait For Event Result Payload Parameter

The entire CloudEvent data attribute becomes a Task result parameter called eventPayload that you can access in other Tasks following the result parameter reference.

Boomerang Eventing Library

To facilitate eventing through NATS, all eventing-related services have Boomerang Eventing Library (lib.eventing) integrated - a Maven plugin that supports event streaming through NATS Jetstream.

This plugin has been built on top of jnats client library, targeting an easier integration with NATS Jetstream for Boomerang Flow, as well as for external applications that want to publish and subscribe to Flow-related events from Boomerang.

See the GitHub repo for Boomerang Eventing Library for more details and documentation.