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 Notifications push notifications every time such an event happens or to register a pipeline listener for example and listen for such an event to a trigger a pipeline execution.
Table of Contents | ||
---|---|---|
|
Event Key Pattern
When registering a listener for an event key, also patterns can be used in the event key:
*
= Stands for a single word up to the next period.
#
= Stands for multiple words with multiple periods in between.
For example: pipeforce.event.workflow.#
matches all workflow event messages while pipeforce.event.workflow.*.my.app
matches only workflow event messages 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:
Code Block | ||
---|---|---|
| ||
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
.
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:
Code Block |
---|
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:
...
Default headers
Every message contains these default headers:
"namespace": ns
Whereasns
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):
Table of Contents | ||
---|---|---|
|
pipeforce.event.app
...
This topic group forwards all important events happening inside IAMrelated to app management.
.
...
install.finished
This event message is send after a new client was createdan app was successfully installed.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iamapp.admin.client.create.clientinstall.finished |
.
...
uninstall.
...
finished
This event message is send after a client was updated by an adminan app was successfully uninstalled.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.admin.update.client.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 scope mapping was deletedcreated.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.admin.delete.client.scopecreate.client.mapping |
.admin.
...
update.
...
client
This event message is send after a new group was createdclient was updated by an admin.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.admin.createupdate.groupclient |
.admin
...
.delete.client.scope.client.mapping
This event message is send after a new user was createdclient scope mapping was deleted.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.admin.create.user.delete.client.scope.client.mapping |
.admin
...
.create.
...
group
This event message is send after a new role group was created.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.admin.create.rolegroup |
.admin.create.
...
user
This event message is send after a member was added to a groupnew user was created.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.admin.create.group.membershipuser |
.admin.client.create
...
.role
...
This event message is send after a resource was mapped to a realm rolenew role was created.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.admin.create.realm.role.mapping |
.admin.create.
...
group.
...
membership
This event message is send after a user has done a predefined actionmember was added to a group.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.admin.create.actiongroup.usermembership |
.admin.
...
create.realm.role.mapping
This event message is send after an OAuth2 client has been logged-ina resource was mapped to a realm role.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.client.login.admin.create.realm.role.mapping |
.
...
admin.
...
action.
...
user
This event message is send after a code has been exchanged to tokenuser has done a predefined action.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.codeadmin.toaction.tokenuser |
.client.login
This event message is send after user an OAuth2 client has successfully been logged-in.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.client.login |
.code.to.
...
token
This event message is send after user has successfully logged-outa code has been exchanged to token.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.logincode. |
...
to.token |
.login
This event message is send after a token has been refresheduser has successfully logged-in.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.refresh.tokenlogin |
.
...
logout
This event message is send after a token has been exchangeduser has successfully logged-out.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.token.exchangelogin |
.
...
refresh.token
This event message is send after user information have been requesteda token has been refreshed.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.iam.userrefresh.info.requesttoken |
...
.
...
token.
...
This topic group forwards all property events as push notifications.
Every property topic key can additionally contain dynamic variables which will be replaced at runtime such as:
{appName}
= Will be replaced by the app name the property is stored inside (example: io.pipeforce.myapp
).
{path}
= The path 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.
.created
This event message is send after a new property was created.
exchange
This event message is send after a token has been exchanged.
The full structure of the event message routing key is like this:
Code Block |
---|
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:
Code Block |
---|
pipeforce.event.iam.propertyuser.createdinfo.{path}request |
pipeforce.
...
event.property
This event message is send after a property was deleted.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.property.deleted.{path} |
.updated
This event message is send after a property was updated.
The full structure of the event message routing key is like this:
Code Block |
---|
pipeforce.event.property.updated.{path} |
.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:
Code Block |
---|
pipeforce.event.property.comment.created.{appName} |
.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:
...
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 exampleio.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 examplens.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:Code Block pipeforce.event.property.*.global.app.com.mycompany.myapp.data.*
The body of most property event messages has a structure like this:
Code Block | ||
---|---|---|
| ||
{
"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 whereasorigin
andtarget
can also benull
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:
Code Block |
---|
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:
Code Block | ||
---|---|---|
| ||
{
"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:
Code Block |
---|
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:
Code Block | ||
---|---|---|
| ||
{
"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:
Code Block |
---|
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:
Code Block | ||
---|---|---|
| ||
{
"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:
Code Block |
---|
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:
Code Block | ||
---|---|---|
| ||
{
"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:
Code Block |
---|
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:
Code Block | ||
---|---|---|
| ||
{
"comment": {
"uuid": "theUuidOfThisCommentProperty",
"target": "theUuidOfTheTargetProperty",
"author": "authorUsername",
"text": "Text of the comment"
}
} |
Info |
---|
Note: Since a comment is also a property, also a |
.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:
Code Block |
---|
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:
Code Block | ||
---|---|---|
| ||
{
"comment": {
"uuid": "theUuidOfThisCommentProperty",
"target": "theUuidOfTheTargetProperty",
"author": "authorUsername",
"text": "Text of the comment"
}
} |
Info |
---|
Note: Since a comment is also a property, also a |
pipeforce.event.log
This topic group forwards all important log events of severity level WARN
or higher.
...
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.
...
Code Block |
---|
pipeforce.event.log.error.{loggerName} |
.warn
This event message is send after a new log entry of level WARN
was created.
...
Code Block |
---|
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:
...
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:
...
{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.#
), these additional address variables can be used in TO, CC and BCC fields to refer to data from the event message:
...
Duplicate addresses will always be removed.
.comment.create
This event message is send after comment to a workflow process was created.
...
Code Block |
---|
pipeforce.event.workflow.comment.create.{appName}.{wfName}.{commentUuid} |
.comment.update
This event message is send after comment to a workflow process was updated.
...
Code Block |
---|
pipeforce.event.workflow.comment.update.{appName}.{wfName}.{commentUuid} |
.end
This event message is send after a workflow process have been finished.
...
Code Block |
---|
pipeforce.event.workflow.end.{appName}.{wfName} |
.task.assignment
This event message is send after the task assignee has changed.
...
Code Block |
---|
pipeforce.event.workflow.task.assignment.{appName}.{wfName} |
.task.complete
This event message is send after a task was completed.
...
Code Block |
---|
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).
...
Code Block |
---|
pipeforce.event.workflow.task.create.{appName}.{wfName} |
.task.delete
This event message is send after a task was deleted.
...
Code Block |
---|
pipeforce.event.workflow.task.delete.{appName}.{wfName} |
.task.timeout
This event message is send after a task timeout happened.
...
Code Block |
---|
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.
...
Code Block |
---|
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.
...
Code Block |
---|
pipeforce.event.workflow.transition.{appName}.{wfName} |
.start
This event message is send after a new workflow process have been started.
...