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.

Boomerang Infrastructure Architecture

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

Name Description
WorkflowId The ID of the Workflow you wish to trigger.
type The type of webhook to trigger. By default, the type is generic. However, we also support special cases with Docker Hub® and Slack®, with the aim to offer support for GitHub®, GitLab®, PagerDuty®, and ServiceNow®. This allows us to implement specific functionality, such as responding to the Slack verification request or the Docker Hub callback URL.
token The access token can be provided as a query parameter or provided in the Authorization header. See the Security Architecture to know more.

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

Name Description
WorkflowId The ID of the Workflow.
WorkflowActivityId The ID of the particular Workflow activity.
topic The topic set on the particular Wait For Event Task in your Workflow.
status (Optional) The status for the Task you want set and allows you to use the link states when connecting from the Task to another Task. This defaults to "success" however you can set "failure."
token The access token can be provided as a query parameter or provided in the Authorization header. See the Security Architecture to know more.

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

CloudEvents Attribute Value
Type io.boomerang.eventing.custom
Subject /<WorkflowId>/<topic>
{
  "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

CloudEvents Attribute Value
Type io.boomerang.eventing.webhook
Subject /<WorkflowId>
{
  "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

CloudEvents Attribute Value
Type io.boomerang.eventing.wfe
Subject /<WorkflowId>/<WorkflowActivityId>/<topic>
CloudEvents Extension Value
Status `success
{
  "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.