What are Events?​

In PIPEFORCE, an event is a special form of a Message.

It is an action which happened inside the hub service and is represented by a JSON object with a certain structure like this:

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 in a lower case and 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:

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

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. Can be null in case the event doesn't contain any additional data. The structure of this payload depends on the event type and the Content-Type header.

origin and target​

In case the event represents a change of data in the system, usually the attributes origin and target are placed inside payload, whereas:

• origin: Contains the origin value BEFORE the change happened or null, if there was no origin value.

• target: Contains the final value AFTER the change happened.

Let's consider for example the event type property.moved:

• origin contains here the origin property key before the move. For example: "origin": "global/app/myapp/old"

• target contains here the final key, the property was moved to. For example: "target":"global/app/myapp/new".

It depends on the event type whether origin and / or target is provided inside payload and which structure they have. Consult the documentation for the certain event types to learn more about the available built-in event types.

async​

It is true, in case this event was sent in an asynchronous way. Otherwise, it is false.

traceId​

This contains a unique id in order to identify the message flow in logs and reports. Any message, origin to this message or successor to this message will contain this id.

headers​

These are optional name-value-pairs to describe the event. It is a good practice to filter events based on header values and avoid filtering on payload for better performance.

Listening to events​

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

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

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 occurs. In this case, a new email will be sent to sales@company.tld.

Note: Each pipeline can define exactly one event.listen command and it must be the very first command in the pipeline.

Multiple event keys

Since Version 10

It is also possible to listen to more than one event key by a single pipeline. Add all required event keys separated by a comma:

The pipeline will be executed if at least one of these events do match.

Deep filtering of events​

Besides 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:

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 events​

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

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​

This is the reference documentation of the built-in events which comes out-of-the-box with PIPEFORCE.

Here is an example on how to listen for such events in a persisted pipeline:

Every time an event is fired matching the given criteria, all commands after event.listen will be executed.

app.install.finished

It is fired after an app has been successfully installed or updated. The payload is like this:

Whereas location defines the location this app was loaded from. Can be one of:

GitHub Location:

Zip Location:

app.uninstall.finished

It is fired after an app has been successfully uninstalled. The payload is like this:

• payload.origin.appPath = The property path prefix of the app uninstalled.

property.created​

It is fired every time a new property gets created in the property store.

It contains as origin, the value null, and as target, the property created before.

property.copied​

It is fired every time a property gets copied in the property store.

It contains as origin, the source property, and as target, the property where source was copied to.

property.deleted​

It is fired every time a property was deleted from the property store.

It contains as origin, the property which was deleted, and as target, the value null.

property.moved​

It is fired every time a property was moved from one key to another.

It contains as origin, the key of the source property, and as target, the key of the property where it was moved to.

property.updated​

It is fired after a property has been updated in the property store.

It contains as origin, the property before the update, and as target, the property after the update.

property.restarted

If is fired after hub has been restarted with some property already existing in database.

It is fired only for properties matching these property path patterns:

• global/app/*/pipeline/**

• global/app/*/function/**

So these properties can re-register jobs and listeners and also functions will be re-deployed if required.

setup.finished​

It is fired after the hub service gets successfully started, and all setup scripts have been executed successfully.

This event contains no payload.

setup.starting​

It is fired after the hub service was successfully started, but right before all setup scripts are executed.

This event contains no payload.

hub.context.started​

It is fired after the hub service was successfully started.

It contains as origin, the configuration of the context as key-value-pairs. The target is null.

iam.bruteforce.detected​

It is fired every time a potential brute force attempt was detected.

iam.login.error​

It is fired every time a login attempt gets failed.