Introduction

Analog to how messages make up a conversation, a timeline is made up of events. The Event API provides the functionality to work with Events within the context of Flowable Engage.

Events can serve as a log of things past. They can be used to notify users of situations as they develop and of facts as they materialise. Events can even be scheduled in the future.

Events are small data structures, defined by and Event Model. In order to present an event to the user (or an intermediate system), the data parameters contained in the Event are rendered into a message. You can define different ways of rendering for different languages and also per communication Channel. For instance, for the same event the message rendered for a web interface might be different from that used in an SMS or mobile push notification.

An Event Model configures both Event Parameters (meta data describing the actual data content of the Event, such as their name, type and behaviour with regards to fast search retrieval using ElasticSearch indices), and the Channels and languages that are available to render. Events link to an Event Model by way of the type and subType fields, and provide the instance data of the event as defined by the linked Event Model.

Ideas and Concepts

A surprisingly small number of parts work together to provide the Event system.

Event

An instance of an Event Model, providing the actual data to use when rendering an event. Can be created, read, updated and deleted. Updates can occur with or without resending notifications (if any are configured) and with or without moving the event to the "current" point in the timeline. The category of an Event is event. The type and subtype attributes further link the Event to an Event Model. The payload provides the event data as defined in the linked Event Model using name:value pairs.

Additionally to the data configured in accordance with the Event Model, an Event holds audit data such as time of creation and last update and the creator. The Events valueTime indicates the moment the event is deemed relevant, which may differ from both creation and update time. Visibility is controlled by assignedGroupId, assignee, candidateGroupIds and candidateUserIds.

Either the id or combination of sourceId and externalId uniquely identifies an Event (e.g. in case of updating).

Event Model

An Event Model defines the payload meta data (parameters) for an Event, and the channel configuration (message templates). Parameters anc Channels are further described in separate paragraphs below.

An Event Model has a name and description for documentation purposes. The category of an Event Model is event. Furthermore, the Event Model has a sourceType, and the above mentioned fields type and subType. If no id is provided, one will be created from {sourceType} - {category} - {type} - {subType}.

Parameters

The crux of an Event is the set of parameter values it provides. Parameters are substituted in (channel and language specific) templates when rendering the event.

Each of the items in the parameters list defines a single parameter. A Parameter has a human readable label and a name which can be used in templates enclosed in curly braces, e.g. {param_name}. The type (one of boolean, date, long, double, string) indicates the data type of the parameter and a formatter ('number', 'date') can be used to influence the rendered value of the parameter. Simple validation can be performed on the event using the mandatory attribute of the parameter. To enable searches of Events against ElasticSearch, the indexedField attribute provides five slots per data type: referenceId#, string#, long#, double#, date# and content#, where # takes a value from 1-5.

Channels

The rendering behaviour of an event is defined using the Event Models channelConfigurations. A Channel is identified by the channel attribute, e.g. 'default', 'web', 'mobile', &cetera. You are free to come up with your own channels. The templates attribute provides Templates, each of which has a locale (the key used for translations), a mainContent and optionally actions.

The mainContent of a Template provides the scaffold text to substitute the parameter values into. References to named parameters must be enclosed in curly braces, e.g. {param_name}.

A list of actions provides clients (e.g. a browser, mobile app) with the data needed to make an event actionable. Each Action has a type, label and optionally a url. Both label and url can reference parameters just as the mainContent can.

Event Models will normally be stored in a Configuration Case as serialised json.

Miscellaneous

Updating events

There are two reasons to update an existing Event; to fix and error (e.g. a typo) or because the Event is changed in a meaningful way. In the first case, notifications and the Events place on the timeline should not change. In the latter case, notifications and reordering may be required. The REST and Java interfaces provide the functionality to perform both kinds of updates (also referred to as PATCH vs PUT).

Timeline

While we’ve referred to a timeline in this documentation, it is important to understnad there is no such "thing" as a timeline in the Event API. Rather, the timeline is an emergent property of handling multiple Events.

Data Bots

As part of the validation process triggered by storing an Event, so called Data Bots can be triggered. These have the ability to block the storage of Events, or execute other actions.

Example

As an example, we’ll define an "Incoming Payment" Event Model, with two channels "web" and "mobile". An Incoming Payment has an account, currency and amount.

Incoming Payment Event Model

{
  "id": "event-incoming-payment",

  "sourceType": "banking",
  "category": "event",
  "type": "payment",
  "subType": "incoming",

  "name": "Payment Incoming",
  "description": "the data model for an incoming payment event",

  "parameters": [
    {
      "name": "account",
      "label": "account number",
      "type": "string",
      "mandatory": true,
      "indexedField": "string2"
    },
    {
      "name": "currency_iso",
      "label": "payment currency ISO code",
      "type": "string",
      "mandatory": true,
      "indexedField": "string1"
    },
    {
      "name": "amount",
      "label": "payment amount",
      "type": "double",
      "formatterId": "number",
      "mandatory": true,
      "indexedField": "double1"
    }
  ],

  "channelConfigurations": [
    {
      "channel": "web",
      "templates": [
        {
          "locale": "en",
          "mainContent": "You received <b>{currency_iso} {amount}</b> on your <b>{account}</b> account."
        }
      ]
    },
    {
      "channel": "mobile",
      "templates": [
        {
          "locale": "en",
          "mainContent": "You received a {currency_iso} payment on your {account} account."
        }
      ]
    }
  ]
}

Create an Incoming Payment Event

{
  "id": "INPAY-1234567890987654321",

  "sourceType": "banking",
  "category": "event",
  "type": "payment",
  "subType": "incoming",

  "valueTime": "2018-05-08T12:16:23.233Z"

  "payload": {
    "account": "CH1230004567890X",
    "currency_iso": "CHF",
    "amount": 12345.67
  }
}
Retrieving the same Event for the "web" Channel
{
  "id": "INPAY-1234567890987654321",

  "sourceType": "banking",
  "category": "event",
  "type": "payment",
  "subType": "incoming",

  "valueTime": "2018-05-08T12:16:23.233Z"

  "payload": {
    "account": "CH1230004567890X",
    "currency_iso": "CHF",
    "amount": 12345.67
  },

  "mainContent": "You received <b>CHF 12345.67</b> on your CH1230004567890X account.",

  "tenantId": "GEAR-5678987650",
  "ownerId": "GEAR-1234567890",
  "assignedGroupId": null,
  "assigneeId": "GEAR-1234567890",
  "candidateGroupIds": [],
  "candidateUserIds": [],

  "creationTime": "2018-05-08T12:16:23.205Z",
  "creatorId": "GEAR-0987654321",
  "updateTime": "2018-05-08T12:16:23.205Z",
  "updaterId": "GEAR-0987654321"
}

Disclaimer

Flowable AG may change, amend or delete information contained in its documents at any time and without formal arrangement. Documents and other informational items concerning a release of Flowable Engage that has not yet been officially released by Flowable AG are non-binding and may be incomplete or contain errors. Flowable AG strives to provide complete and exact information in its documents. If permitted by applicable law, Flowable AG takes no responsibility for the accuracy of the issued informational items and documentation and does not provide any warranty for their content. Flowable AG assumes no liability for any direct, indirect or incidental damages incurred by the use of its documents and informational items. Documents or informational items do not change or amend the contractual terms and conditions regarding Flowable Engage. For improved readability, the documentation uses male pronouns for all persons. It does, however, address both male and female readers to the same extent.