Events and subscriptions
Introduction
The ability to configure triggers that check changesets and trigger events based on the applied configuration is an important core feature of the ShareAspace platform.
The form of the signal that follows an event happening, be it an email sent or an HTTP request sent, is also controlled by the applied configuration.
Through the configuration, either during initial configuration of a Space Template or by runtime update in an existing Space, it is possible for both administrators and end users to explicitly define when and how events should be triggered and managed.
The figure below, shows an overall flow of an event being triggered, leading up to a signal of this event being sent.
Details of the different functions and configurations are described further on in this article.
| Number | Description |
|---|---|
| 1 | A Changeset with data is committed to a Space. |
| 2 | A Trigger Definition has been configured in the Space Template. 4 of the 9 objects in the changeset match the configuration of the Trigger Definition. i.e. 4 events will be triggered, represented by the orange and green flashes. |
| 3 | A user has setup a Personal Subscription. This Subscription is based on a Subscription Definition. The Subscription Definition is defined for the Trigger Definition that triggered the 4 events. Within the Subscription the user has further filtered the base filter defined by the Trigger Definition. |
| 4 | After the Subscription filtering is done, there is one event left, the green event. Now it is time to signal this event. ShareAspace will check the Subscription Definition. In it there is a configuration for how the signal message should be. There is also a configuration stating that, to be able to send the signal, the Collection hosting the Space must have been setup with an extension. Any security settings required to signal the event can be kept on the Collection Level. |
| 5 | Finally ShareAspace will send a message (email or HTTP request) to an external service. The message can include information about the event, information about the data that triggered the event, and some ShareAspace system data, etc. |
Constructs
There is a set of components involved for managing:
- When to trigger events and for what.
- How to manage events that have been triggered.
- Post to external service (of different types).
- Send email.
- General and/or personal subscriptions for additional filtering of events before signaling.
Trigger definition
To manage the configuration of what types of events to trigger there is a concept of trigger definition. There are two different types: system event trigger definitions and SoftType trigger definitions.
To describe a configured trigger there is a set of attributes including: a unique identifier, a name, a description, and a category.
Contract
It is required to define a contract for the SoftType Trigger Definition. The contract defines two things.
First, a list of SoftTypes that the trigger should be valid for. Secondly, a contract for selecting what values of the defined SoftType(s) (SoftType ports, like id, name etc.) that should be made available for defining criteria.
e.g. It is possible to define a contract that has Id and Name. The Id will bind to the id port of the selected SoftType(s) and the Name will bind to the name port of the selected SoftType(s).
Note
The contract can only include ports that are in common to all the SoftTypes included in a contract.
Setting up the contract allows for use of the defined values when:
- Setting up the criteria for when the trigger definition should trigger events.
- Setting up filtering criteria on subscription definitions and subscriptions.
Both these are described in more detail later.
Filter criteria
Action criteria
The action criteria allows you to configure if you want the trigger definition to trigger events when a SoftType is created, updated, deleted, or all three combined. For this last case, the action criteria is optional. If an action criteria is not defined, events will be triggered for when SoftTypes (of the specified types) are created, updated, or deleted.
If, for example, the action criteria is specified as created, events will only trigger when SoftTypes are created, etc.
Attribute criteria
The attribute criteria are optional but it is possible to define more than one of them. All defined criteria are AND operated, i.e., all the defined attribute criteria must be fulfilled for an event to be triggered.
There are two types of attribute criteria, action and value. For the action criteria it is possible to state if a port value (like the name of a SoftType) was created, updated, or deleted.
The value criteria can be configured to evaluate the value of a port, e.g., "name was set to ...".
Depending on the value type for the port there are different operators that can be used. The matrix over operators and types where they are applicable is as follows:
| > | >= | < | <= | = | != | starts | ends | like | |
|---|---|---|---|---|---|---|---|---|---|
| Real | ⚫ | ⚫ | ⚫ | ⚫ | ⚫ | ⚫ | |||
| Integer | ⚫ | ⚫ | ⚫ | ⚫ | ⚫ | ⚫ | |||
| DateTime | ⚫ | ⚫ | ⚫ | ⚫ | ⚫ | ⚫ | |||
| String | ⚫ | ⚫ | ⚫ | ⚫ | ⚫ | ||||
| External | ⚫ | ⚫ | |||||||
| Boolean | ⚫ | ⚫ | |||||||
| ObjectId | ⚫ | ⚫ | |||||||
| Enumeration | ⚫ | ⚫ |
The attribute criteria does not only address simple types. It also can be used for object database ids (i.e. reference ports) and other ports as well.
Examples:
- "When this object is referenced".
- "The name contains the value of the id".
Yet another aspect to the comparison is the possibility to compare the new value, called "Current", with the old value, called "Previous". With this kind of configuration a trigger definition could be configured to only trigger events for statements like "the new value (Current) is larger than the old (Previous) value".
The only place where you would configure the trigger definitions is in the Space Template configuration.
Subscription definition
The purpose of the subscription definition is to setup a configuration for defining the signal method for events triggered by a SoftType trigger definition. Using the subscription definitions it is then possible to instantiate subscriptions.
The subscription definition has some base information like, a unique identifier, a name, and a description.
There are two types of subscription definitions, General and Personal. The general subscription definition is used when creating general subscriptions and the personal subscription definition is made available for users to create personal subscriptions (more on subscriptions in the next section).
A subscriptions definition has a reference to only one trigger definition.
Subscription Definitions can be defined both in a Space configuration template and at runtime using the ShareAspace Web UI. All setup capabilities available in the user interface can also be managed using the ShareAspace REST APIs. Typically it is the Space administrator that would define new subscription definitions at runtime.
Signal method
To define where information about an event should be sent when a subscription based on a subscription definition has received an event to handle, the subscription definition can set up one or more signal methods.
There are three types of signal methods:
- External - makes use of a defined endpoint, a trusted endpoint, or an external event resource defined in a ShareAspace extension.
- Email - makes use of an email resource defined in a ShareAspace extension.
- Logging - makes use of a logger resource defined in a ShareAspace extension.
A subscription definition can take multiple actions once an event is triggered.
Read more about extensions here.
The external extension has its base configuration as defined when setup, typically by the Collection administrator. But further configuration for the use of the external extension is defined in the configured external extension.
Caution
When defining a subscription definition it is very important to keep in mind what kind of external extension is being used. Trusted endpoints and Nova external events will pass on an impersonation access token (JWT) to the external extension. These will give the external extension the right to act as a user within the Space. Read more on the access tokens that are issued in the Subscription section.
Configured email
When configuring the use of an email extension the creator of the subscription definition can define:
| Description | |
|---|---|
| to | Email address of the recipient of the email. |
| from | Email address of the sender of the email. |
| subject | The subject of the email. |
| body | The email message body. Can use formatting, like HTML. |
Configured external
When configuring the use of an external extension the creator of the subscription definition can define additional headers and the body of the HTTP request that will be invoked by ShareAspace to the external extension.
In the configuration of the external extension there might already be a set of headers defined. This cannot be altered. However, it is possible to configure additional headers.
Liquid
When defining the parameters and body for emails to be sent or when configuring headers and the message body of the HTTP request sent to an external extension, one would typically want to provide dynamic information.
This dynamic information could be:
- Data from the SoftType instance(s) that triggered the event(s), typically the data defined in the contract of the trigger definition.
- ShareAspace system data, like Space Id, ShareAspace API base URL, etc.
- Email address of the person triggering the event or the person owning the subscription.
To achieve this ShareAspace uses a templating language called Liquid. ShareAspace has its own implementation of Liquid but the base functions that are defined for the Liquid language are implemented. In addition to these base functions there is also a ShareAspace specific "API" that can be used in order to access additional information.
Simple example for an email body:
A Part with Id {{current.id}} and Name {{current.name}} was created.
Notice that variable values are written as text when put within double curly brackets {{ }}.
The ShareAspace Liquid implementation is descried in more detail and with examples in the configuration section.
Aggregated
On the subscription definition there is a setting called aggregated. Aggregated can be set to either true or false.
To understand this setting we must first look at relation between a changeset that is committed and how events are triggered.
Say you have a trigger definition that listens to the creation of instances of a SoftType "Document". If there is an import job creating 100 new "Document" instances. (Data in an import is always committed as one changeset). This will trigger 100 events.
The events are however grouped under the commit, meaning that they could be handled as a group of events, or be handled individually, one by one.
If the aggregated setting is set to true on the subscription definition the events will be handled as a group and only one signal per signal method is sent. i.e. only one email or only one HTTP request.
To handle the fact that there is a set of grouped events the templating language, Liquid, has the ability to loop through all the object references so that you could, for example, send an email with a table of all objects created or an HTTP request with a JSON array containing information about all Documents that were created.
If, however, the aggregated setting is set to false, each event will be handled separately, meaning that the signal method will send one message for each event. Taking the same example, 100 emails would be sent and/or 100 HTTP requests made.
Caution
Setting aggregated to false should be done with great care! Always bear in mind the scenarios where a trigger definition could trigger an event. Triggers for data that can be imported are, of course, the most sensitive ones when it comes to triggering large numbers of events.
One consequences of making mistakes with this setting is that a large amount of emails might be sent to the same recipient during a very short amount of time. This is of course annoying for the user that receives these emails but it can also lead to the configured sender being blocked from sending any more emails.
Active/Inactive
The subscription definitions has an Active/Inactive state. If a subscription definition is deactivated any Subscriptions that use this definition will be inactive. Typically it is only the Space administrator that would manage this state.
Subscription
The subscriptions are the end configurations that actually activates all the functions that we have covered so far.
There are two types of subscription. The general subscriptions that are instantiated with a reference to a general subscription definition. Then there are the personal subscriptions that are instantiated with a reference to a personal subscription definition.
A subscription has a unique identifier and a name. In addition to this there is also the possibility to apply filtering of the events (in addition to the filtering already defined on the Trigger Definition).
General subscription
General subscriptions are generally defined by a Space administrator or a "Participant administrator". When an event is triggered and the profile is reading data from objects referenced by the events, the access filtering applied will be that of the participant that owns the general subscription.
Note
When coupled with a subscription definition that uses an external extension (trusted external endpoint or external event) the user that triggered the event will be used for the impersonation access token (a JSON Web Token - JWT) sent to the external extension.
Personal subscription
Personal subscriptions are typically created and managed by any user with editing rights within a Space. The personal subscription has a reference to the user that created the subscription. Only the user creating the subscription will be able to see and manage it. Also, the access filtering applied will be that of the user that created the subscription.
Note
When coupled with a subscription definition that uses an external extension (trusted external endpoint or external event) the user that created the subscription will be used for the impersonation access token (JWT) sent to the external extension.
Filter criteria
Just like with the filter criteria configuration on the trigger definitions it is possible to define filter criteria on the subscription. Events that are passing through the filters of the trigger definitions can be further filtered on the subscription.
Multiple criteria will be AND operated during the filtering.
There are a set of keywords that can be used when defining the attribute criteria.
| Keyword | Description |
|---|---|
| TriggeredBy | The user that performed the commit that triggered the event(s). |
| Today | The day when the event is evaluated. |
| SubscriptionOwner | The Participant that owns the Subscription. |
| SubscriptionCreator | The user that created the Subscription. |
Active/Inactive
The subscription has an Active/Inactive state. If a subscription is deactivated, triggers will no longer be evaluated against that subscription / subscription definition pair. Typically it is the user that created the subscription that would manage this state.
OOTB Configuration
In pre-packaged configurations there are additional trigger definitions, subscription definitions, and subscriptions configured for managing a specific process of that particular configuration. These configurations are covered in the their specific documentation.