Notifications are sent from the system when predefined events occur. An example of such an event could be a job that finishes. Examples of when this could be useful are:
- Getting a notification when a job finishes.
- Making sure the metadata input for a certain field is correct.
Notifications involve a quadruple:
- The resource or entity to be notified about.
- The event that should trigger the notification.
- The action that should be taken when the notification is triggered.
- Filters that further specifies the behavior of the trigger.
A number of different entity types support notifications. Below is a short description of the different entity types and what events can trigger a notification:
- Items – notifications can trigger on item delete/create, metadata changes, shape changes and access control changes.
- Collections – can trigger on creation/deletion, metadata changes and content changes.
- Jobs – can trigger on job create, update, finish, fail and stop.
- Groups – group notifications can trigger on group create, delete and modify.
- Storages – can trigger on storage create/delete, and on new files.
- Files – can trigger on group create, delete and modify.
- Quota – quota notifications can trigger on quota create, delete, and quota exceeded warnings.
- Document – can trigger on document create, delete and modify.
An action is what will be done when a notification is triggered. The action can either be to:
- Perform a HTTP request.
- Invoke a Java class method.
- Send a JMS message.
- Send a message to Amazon SQS.
- Send a message to Amazon SNS.
The data included in the request or message will be multivalued key-value data identifying the event that has occurred.
An action can be sent either synchronous or asynchronous. In the case of a synchronous action the message will be sent in the same thread as where the notification is triggered. And execution will only continue if the recipient acknowledges and approves the message. In the asynchronous case the message will be sent in another thread and execution will continue immediately.
For a full description of actions, refer to the API reference on Actions.
A trigger is the event that will cause the notification to perform its action. Different triggers exist for different resources. The trigger used determines what output that can be expected. Below an overview of available triggers can be seen:
- Item triggers.
- Collection triggers
- Group triggers
- Job triggers
- Storage triggers
- File triggers
- Quota triggers
- Document triggers.
- Deletion lock triggers.
- Placeholder (null) triggers.
The placeholder trigger is simply the lack of a trigger-type. For a full description of triggers, refer to the API reference on Triggers.
Filter criteria can be added to job notifications in order to filter which type of jobs they trigger on.
Either by string comparison or regular expressions.
Filters can be used to specify the trigger further. For example in the case of metadata, the notification can be filtered to only trigger for certain values.