Event Message Keys Reference

An event message key (also known as topic) is a routing key pattern of an event message which is sent after a known event in PIPEFORCE happened. This key always starts with prefix pipeforce.event, followed by the concrete event type.

It can be used to listen and send push notifications every time such an event happens or to register a pipeline listener and listen for such an event to a trigger a pipeline execution.

Here is an example how to add such an event message listener to a pipeline. As soon as the pipeline got saved in the property store, the listener is activated:

pipeline:
  - message.listen:
      key: pipeforce.event.workflow.#
      
  - mail.send:
      to: admin@company.tld
      subject: A workflow event happened.

Pattern matching

When registering a listener for an event key, also pattern matching can be used:

* = Stands for a single word up to the next period .
# = Stands for multiple words with multiple periods in between.

For example the event key from above pipeforce.event.workflow.# matches all workflow event messages while pipeforce.event.workflow.*.my.app matches only workflow event messages inside the app my.app.

Default headers

Every message contains these default headers:

"namespace": ns
Whereas ns is the namespace this event happened inside. Cannot be changed for security reasons.
"content_type": application/json
An event message body is always of type JSON.

Reference Documentation

Here is the reference of these event messages and their keys (also known as topics):

1 pipeforce.event.app
- 1.1 .install.finished
- 1.2 .uninstall.finished
2 pipeforce.event.iam
- 2.1 .admin.client.create.client
- 2.2 .admin.update.client
- 2.3 .admin.delete.client.scope.client.mapping
- 2.4 .admin.create.group
- 2.5 .admin.create.user
- 2.6 .admin.client.create.role
- 2.7 .admin.create.group.membership
- 2.8 .admin.create.realm.role.mapping
- 2.9 .admin.action.user
- 2.10 .client.login
- 2.11 .code.to.token
- 2.12 .login
- 2.13 .logout
- 2.14 .refresh.token
- 2.15 .token.exchange
- 2.16 .user.info.request
3 pipeforce.event.property
- 3.1 .created
- 3.2 .copied
- 3.3 .deleted
- 3.4 .updated
- 3.5 .comment.created
- 3.6 .comment.updated
4 pipeforce.event.log
- 4.1 .error
- 4.2 .warn
5 pipeforce.event.webhook
6 pipeforce.event.workflow
- 6.1 Workflow address variables ($uri:wf-)
- 6.2 .comment.create
- 6.3 .comment.update
- 6.4 .end
- 6.5 .task.assignment
- 6.6 .task.complete
- 6.7 .task.create
- 6.8 .task.delete
- 6.9 .task.timeout
- 6.10 .task.update
- 6.11 .transition
- 6.12 .start

pipeforce.event.app

This topic group forwards all important events related to app management.

.install.finished

This event message is send after an app was successfully installed.

The full structure of the event message routing key is like this:

pipeforce.event.app.install.finished

.uninstall.finished

This event message is send after an app was successfully uninstalled.

The full structure of the event message routing key is like this:

pipeforce.event.app.uninstall.finished

pipeforce.event.iam

This topic group forwards all important events happening inside IAM.

.admin.client.create.client

This event message is send after a new client was created.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.client.create.client

.admin.update.client

This event message is send after a client was updated by an admin.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.update.client

.admin.delete.client.scope.client.mapping

This event message is send after a client scope mapping was deleted.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.delete.client.scope.client.mapping

.admin.create.group

This event message is send after a new group was created.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.create.group

.admin.create.user

This event message is send after a new user was created.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.create.user

.admin.client.create.role

This event message is send after a new role was created.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.create.role

.admin.create.group.membership

This event message is send after a member was added to a group.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.create.group.membership

.admin.create.realm.role.mapping

This event message is send after a resource was mapped to a realm role.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.create.realm.role.mapping

.admin.action.user

This event message is send after a user has done a predefined action.

The full structure of the event message routing key is like this:

pipeforce.event.iam.admin.action.user

.client.login

This event message is send after an OAuth2 client has been logged-in.

The full structure of the event message routing key is like this:

pipeforce.event.iam.client.login

.code.to.token

This event message is send after a code has been exchanged to token.

The full structure of the event message routing key is like this:

pipeforce.event.iam.code.to.token

.login

This event message is send after user has successfully logged-in.

The full structure of the event message routing key is like this:

pipeforce.event.iam.login

.logout

This event message is send after user has successfully logged-out.

The full structure of the event message routing key is like this:

pipeforce.event.iam.login

.refresh.token

This event message is send after a token has been refreshed.

The full structure of the event message routing key is like this:

pipeforce.event.iam.refresh.token

.token.exchange

This event message is send after a token has been exchanged.

The full structure of the event message routing key is like this:

pipeforce.event.iam.token.exchange

.user.info.request

This event message is send after user information have been requested.

The full structure of the event message routing key is like this:

pipeforce.event.iam.user.info.request

pipeforce.event.property

This topic group forwards all property events as push notifications.

Every property topic key can optionally contain dynamic variables which will be replaced at runtime such as:

{appName}
Will be replaced by the name of the app, the related property is stored inside. For example io.pipeforce.myapp.
{propertyPath}
The namespace relative path (= no /pipeforce/ns prefix) of the related property whereas slashes in path of property will become dots. Dots and special chars in origin path will be replaced by underscores. Everything in path is lower-cased. For example ns.global.app.com.mycompany.myapp.data.
This way also pattern matching filtering can be applied on the path level. In order to listen on any property event on any property inside the data folder of your app you could use a key like this:
pipeforce.event.property.*.global.app.com.mycompany.myapp.data.*

The body of most property event messages has a structure like this:

{
  "timestamp": integer,
  "correlationdId": string,
  "namespace": "string",
  "payload": {
    "origin": {
      "uuid": "string",
      "path": "string",
      "type": "string",
      "value": "string",
      "created": timestamp,
      "updated": timestamp
    },
    "target": {
      "uuid": "string",
      "path": "string",
      "type": "string",
      "value": "string",
      "created": timestamp,
      "updated": timestamp
    }
}

Wheras:

timestamp = The unix timestamp in milliseconds when this event happened.
correlationId = In case this event is part of an async execution, this is the id of the execution.
namespace = The namespace this event happened inside.
payload = A JSON which contains more information about the related properties whereas origin and target can also be null depending on the event type. Their attributes are:
- uuid = The uuid of the related property.
- path = The path of the related property.
- type = The content type of the related property.
- value = The value of the related property.
- created = The unix timestamp in ms when this related property was created.
- updated = The unix timestamp in ms when this related property was updated last time.

.created

This event message is send after a new property was created.

The full structure of the event message routing key is like this:

pipeforce.event.property.created.{propertyPath}

{propertyPath} will be replaced by the namespace relative path of the property whereas each slash will be replaced by dots.

The structure of the message body:

{
    "timestamp": integer,
    "correlationId": "string",
    "namespace": "string",
    "payload": {
        "origin": null,
        "target": {
          "uuid": "string",
          "path": "string",
          "type": "string",
          "value": "string",
          "created": timestamp,
          "updated": timestamp
        }
    }
}

The field origin is null.

The field target contains information about the created property.

.copied

This event message is send after a new property was copied.

The full structure of the event message routing key is like this:

pipeforce.event.property.copied.{propertyPath}

{propertyPath} will be replaced by the namespace relative path of the property whereas each slash will be replaced by dots.

The structure of the message body:

{
    "timestamp": integer,
    "correlationId": "string",
    "namespace": "string",
    "payload": {
        "origin": {
          "uuid": "string",
          "path": "string",
          "type": "string",
          "value": "string",
          "created": timestamp,
          "updated": timestamp
        },
        "target": {
          "uuid": "string",
          "path": "string",
          "type": "string",
          "value": "string",
          "created": timestamp,
          "updated": timestamp
        }
    }
}

The field origin contains information about the property it was copied from.

The field target contains information about the property it was copied to.

.deleted

This event message is send after a property was deleted.

The full structure of the event message routing key is like this:

pipeforce.event.property.deleted.{propertyPath}

{propertyPath} will be replaced by the namespace relative path of the property whereas each slash will be replaced by dots.

The structure of the message body:

{
    "timestamp": integer,
    "correlationId": "string",
    "namespace": "string",
    "payload": {
        "origin": {
          "uuid": "string",
          "path": "string",
          "type": "string",
          "value": "string",
          "created": timestamp,
          "updated": timestamp
        },
        "target": null
    }
}

The field origin contains information about the deleted property.

The field target is null.

.updated

This event message is send after a property was updated.

The full structure of the event message routing key is like this:

pipeforce.event.property.updated.{propertyPath}

{propertyPath} will be replaced by the namespace relative path of the property whereas each slash will be replaced by dots.

The structure of the message body:

{
    "timestamp": integer,
    "correlationId": "string",
    "namespace": "string",
    "payload": {
        "origin": {
          "uuid": "string",
          "path": "string",
          "type": "string",
          "value": "string",
          "created": timestamp,
          "updated": timestamp
        },
        "target": {
          "uuid": "string",
          "path": "string",
          "type": "string",
          "value": "string",
          "created": timestamp,
          "updated": timestamp
        }
    }
}

The field origin contains information about the property before it was updated.

The field target contains information about the property after it was upated.

.comment.created

This event message is send after a comment was added to a property.

The full structure of the event message routing key is like this:

pipeforce.event.property.comment.created.{propertyPath}

{propertyPath} will be replaced by the namespace relative path of the property this comment is attached to, whereas each slash will be replaced by dots.

The structure of the message body:

{
    "comment": {
      "uuid": "theUuidOfThisCommentProperty",
      "target": "theUuidOfTheTargetProperty",
      "author": "authorUsername",
      "text": "Text of the comment"
    }
}

Note: Since a comment is also a property, also a pipeforce.event.property.created message will be send.

.comment.updated

This event message is send after a comment was updated to a property.

The full structure of the event message routing key is like this:

pipeforce.event.property.comment.updated.{propertyPath}

{propertyPath} will be replaced by the namespace relative path of the property this comment is attached to, whereas each slash will be replaced by dots.

The structure of the message body:

{
    "comment": {
      "uuid": "theUuidOfThisCommentProperty",
      "target": "theUuidOfTheTargetProperty",
      "author": "authorUsername",
      "text": "Text of the comment"
    }
}

Note: Since a comment is also a property, also a pipeforce.event.property.updated message will be send.

pipeforce.event.log

This topic group forwards all log events of severity level WARN or higher.

Every log topic key can additionally contain dynamic variables which will be replaced at runtime such as:

{loggerName} = The name of the logger used internally.

This way you can also listen to events of a certain level and logger type using a pattern. Here is an example which listens for all log levels (warn and above) happening inside the com.logabit package: this for example: pipeforce.event.log.*.com.logabit.#

.error

This event message is send after a new log entry of level ERROR was created.

The full structure of the event message routing key is like this:

pipeforce.event.log.error.{loggerName}

.warn

This event message is send after a new log entry of level WARN was created.

The full structure of the event message routing key is like this:

pipeforce.event.log.warn.{loggerName}

pipeforce.event.webhook

This key forwards all webhook calls. The structure of the event message routing key is like this:

pipeforce.event.webhook.{name}

Whereas {name} is the name, the user has given to this webhook in the setup. The payload of the message contains the body of the webhook request.

pipeforce.event.workflow

Every workflow topic key can additionally contain dynamic values which will be replaced at runtime such as:

{appName} = Will be replaced by the app name the workflow is stored inside (example: io.pipeforce.myapp).

{wfName} = Will be replaced by the property name of the workflow definition in the workflow folder inside the app (example: myworkflow)

Workflow address variables ($uri:wf-)

In case a push event is a workflow event (pipeforce.event.workflow.#), additional address variables can be used in TO, CC and BCC fields to refer to data from the event message. See here for more details: Notifications | $uri:wf (workflow addresses)

.comment.create

This event message is send after comment to a workflow process was created.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.comment.create.{appName}.{wfName}.{commentUuid}

.comment.update

This event message is send after comment to a workflow process was updated.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.comment.update.{appName}.{wfName}.{commentUuid}

.end

This event message is send after a workflow process have been finished.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.end.{appName}.{wfName}

.task.assignment

This event message is send after the task assignee has changed.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.task.assignment.{appName}.{wfName}

.task.complete

This event message is send after a task was completed.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.task.complete.{appName}.{wfName}

.task.create

This event message is send after a new task in a workflow process was started (created).

The full structure of the event message routing key is like this:

pipeforce.event.workflow.task.create.{appName}.{wfName}

.task.delete

This event message is send after a task was deleted.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.task.delete.{appName}.{wfName}

.task.timeout

This event message is send after a task timeout happened.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.task.delete.{appName}.{wfName}

.task.update

This event message is send after a metadata or variables of a task have been updated.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.task.update.{appName}.{wfName}

.transition

This event message is send after a (task) transition have been occurred from one state to another.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.transition.{appName}.{wfName}

.start

This event message is send after a new workflow process have been started.

The full structure of the event message routing key is like this:

pipeforce.event.workflow.start.{appName}.{wfName}

Event Message Keys Reference

pipeforce.event.app

.install.finished

.uninstall.finished

pipeforce.event.iam

.admin.client.create.client

.admin.update.client

.admin.delete.client.scope.client.mapping

.admin.create.group

.admin.create.user

.admin.client.create.role

.admin.create.group.membership

.admin.create.realm.role.mapping

.admin.action.user

.client.login

.code.to.token

.login

.logout

.refresh.token

.token.exchange

.user.info.request

pipeforce.event.property

.created

.copied

.deleted

.updated

.comment.created

.comment.updated

pipeforce.event.log

.error

.warn

pipeforce.event.webhook

pipeforce.event.workflow

Workflow address variables ($uri:wf-)

.comment.create

.comment.update

.end

.task.assignment

.task.complete

.task.create

.task.delete

.task.timeout

.task.update

.transition

.start

Related content