Licenses	ENTERPRISE, CORPORATE
Since	VERSION 4.0

Events can be used to listen to certain things happened in PIPEFORCE or in other systems. It’s also possible to trigger such events from inside a pipeline.

The Event JSON

In PIPEFORCE an event is represented by a JSON object with a certain structure like this:

{
  "eventKey": "string",
  "namespace": "string",
  "payload": {JSON},
  "origin": {JSON},
  "target": {JSON},
  "async": true|false,
  "headers": {
    "key": "value",
    ...
  }
}

This event JSON object is automatically provided to you in the body of the pipeline and can be accessed from there by a pipeline expression (PE).

eventKey

Contains a unique key for this event type. The event keys are typically written lower case and in a dot notation where each part is separated by a dot.

Here are some examples of built-in event keys:

property.created
property.deleted
setup.finished

Events coming from external systems via webhooks must be prefixed with webhook.systemname. for example:

webhook.weclapp.order.created

Custom events (not part of the built-in events) must be prefixed with the reversed internet domain name of the creator. For example:

com.company.eventname

namespace

The namespace (= tenant) where this event happened. If null or empty, the event was fired by a global instance.

payload

The optional payload of the event as JSON object. The structure of this payload depends on the event type.

origin

The origin version of the payload in case the event changed the payload. For example if the event causes a property to change, the origin would contain the property BEFORE the change.

target

The final version of the payload in case the event changed the payload. For example if the event causes a property to change, the target would contain the property AFTER the change.

async

true, in case this event was sent in asynchronous way. Otherwise false.

headers

Optional name-value-pairs to describe the event. Its good practise to filter events based on header values and avoid filtering on payload because of performance.

Listening for events

In case a pipeline should be executed when a certain event was fired, the event.listen command can be used. When the pipeline is deployed, the event.listen registers itself as listener to the event system. Whenever an event is fired which matches the event.listen criteria, any subsequent commands of this pipeline are executed then.

Lets assume an example: Whenever a new lead was created in Salesforce, the pipeline must send an email to the sales team:

pipeline:
 - event.listen:
     key: webhook.salesforce.lead.created
 - mail:
     to: sales@company.tld
     subject: New lead created!

After this pipeline was deployed to the property store, it will be executed automatically any time a new event with key webhook.salesforce.lead.created happens. In this case a new email will be sent to sales@company.tld.

Note: Each pipeline can have only one event.listen an it must be the very first command in the pipeline.

Deep filtering for events

Beside the event key, each event can also be filtered by its properties. So a pipeline gets executed only in case such a filter evaluated with true. To do so, you can use the filter parameter of the event.listen command and place a pipeline expression here. Since the event object is automatically provided in the body for you, you can access it there from inside your pipeline expression (PE). For example:

pipeline:
 - event.listen:
     key: webhook.salesforce.lead.created
     filter: "#{body.target.CountryCode == 'DE'}"
 - mail:
     to: sales@company.tld
     subject: New lead created in #{body.target.CountryCode}!

In the filter parameter you can place a pipeline expression (PE). If this expression evaluates with true, all subsequent commands after event.listen will be executed.

In this example we assume that the event contains the Salesforce Lead object so we can filter for the CountryCode here. But this depends on the implementation of the webhook.

Sending event

In order to send an event, you can use the event.send command. Here is an example:

pipeline:
  - event.send:
      key: com.company.myevent

Every time this pipeline gets executed, it will send a new event with key com.company.myevent. Optionally you also set the payload of the event using its payload parameter. This can be a literal or a pipeline expression (PE) which points to an object to be attached to the payload.

Note: Whenever you send a custom event you need to prefix it with the reversed internet address of your company. In this example it is com.company. Otherwise it could be, that your event gets dropped or causes an exception.

Built-in events

These are events which come out-of-the-box with PIPEFORCE. Here is a list of those officially supported events:

Event Key	Description	Payload
`property.created`	Fired every time a new property was created in the property store.