External Notifications
Overview
An administrator can configure triggers in Signals that publish events that you can process. When you are notified of an event, it then can take subsequent action, such as calling the Signals API. The benefit of this sort of integration approach is that it allows for the integration to kick off flows automatically without need for user action or interruption.
There are two types of notifications available, Push and Pull. Push notifications are sent to a user configured URL when they are triggered. Pull notifications are accessed via Signals Rest APIs
Consider, for example, an archival use case in which events are published when a user electronically signs an experimental record. The archival application is subscribed to these events via Push Notifications, and thus takes action when the event is fired (i.e., calls a Signals API to get the content of the experiment and then stores it in an archive). If that archival application is offline or cannot reach the service temporarily, it can utilize Pull notifications when it is available again to get all of the notifications it missed while unavailable. These notifications can be flagged as dismissed using the Signals API.
Setup
As an administrator you can enable External Notifications. Once enabled, all selected notifications become available for push and pull events based on the configuration.
A setup guide for External Notifications is included in the System Configuration Guide.
Additional Technical Details for External Action Setup
Authentication
During setup Administrators can include an API Key and header key name to include as part of the URL Request sent.
Auto dismissal of Notifications
During setup Administrators can enable auto-dismissal of notifications. If enabled, once a notification is delivered, receiving any 2XX response from your external servers, the notification is flagged as dismissed. This does not delete the notification but sets the isDismissed flag to true. Dismissed notifications are still queryable via the Signals Rest APIs. If left unchecked the notifications isDismissed flag will remain false unless set via Rest APIs.
Available triggers
All Signing Events: These notifications are triggered when users perform any signing action.
All Export to PDF/ZIP Events: These notifications are triggered whenever a user exports top-level entities to PDF or ZIP.
Top Level Entity Creation: These notifications are triggered when a user creates Signals Notebook entities.
NOTE: Top Level Entities Include: Notebook, Experiment, Request, Parallel Experiment, Sub Experiments, Admin Defined Objects, Samples, Tasks, and Materials.
Push Notifications
Push notifications are sent when one of the configured events trigger. These are sent directly to the configured url and are meant to be the kick off process for external workflows that happen in real time with the events.
Example of a Push Notification Body
{
"links": {
"self": "https://snb.example.com/api/rest/v1.0/notifications/519"
},
"data": {
"type": "notification",
"id": "519",
"links": {
"self": "https://snb.example.com/api/rest/v1.0/notifications/519"
},
"attributes": {
"id": "519",
"createdAt": "2023-12-13T20:42:50.427Z",
"type": "close",
"isDismissed": true,
"isRead": false,
"isFlagged": false,
"comment": "This experiment was a success"
},
"relationships": {
"createdBy": {
"links": {
"self": "https://snb.example.com/api/rest/v1.0/users/100"
},
"data": {
"type": "user",
"id": "100"
}
},
"entity": {
"links": {
"self": "https://snb.example.com/api/rest/v1.0/entities/experiment:d5dc8e92-580d-41e2-9c65-99726294966c"
},
"data": {
"type": "entity",
"id": "experiment:d5dc8e92-580d-41e2-9c65-99726294966c"
}
}
}
},
"included": [
{
"id": "experiment:d5dc8e92-580d-41e2-9c65-99726294966c",
"type": "entity",
"links": {
"self": "https://snb.example.com/api/rest/v1.0/entities/experiment:d5dc8e92-580d-41e2-9c65-99726294966c"
},
"attributes": {
"type": "experiment",
"eid": "experiment:d5dc8e92-580d-41e2-9c65-99726294966c",
"name": "Experiment 100",
"isTemplate": false
}
},
{
"type": "user",
"id": "100",
"links": {
"self": "https://snb.example.com/api/rest/v1.0/users/100"
},
"attributes": {
"userId": "100",
"id": "100",
"userName": "user.name@email.com",
"email": "user.name@email.com",
"alias": null,
"firstName": "User",
"lastName": "Name",
"picture": {
"link": null
}
}
}
]
}
Here you can see that notifications follow the same basic specification of our REST API responses. The relationships (in the data) object and the top level included object give more details about the user and entities related to the notification.
The key object to reading notifications is the attributes found in the data object:
“id:” This is the id our our notification, it can be used to lookup notifications via the REST API. This is also found in the data object.
“createdAt:” This is the timestamp for when our the triggering event occurred.
"type:" This dictates which of the specific events the we enabled occurred. A list of events and their corresponding types are below.
"isDismissed:" This is a boolean flag which is able to be automatically set to true for Push notifications if enabled when setting up external notifications. It will be set to true when receiving a 2XX response when sending the notification externally. Additionally this can be set manually via the REST API.
"isRead:" This is a boolean flag that can be set via the REST API.
"isFlagged:" This is a boolean flag that can be set via the REST API.
"comment:" This is used for All Signing Event triggers to include the comment left while signing. This will be null if there is not option for comments for that particular event such as Top Level Entity Creation and All Export to PDF/ZIP Events.
Notification Types:
Top Level Entity Creation:
Entity Creation: create
All Export to PDF/ZIP Events:
Print/ZIP Export: print
Signing Events:
Sign and Close: close
Sign and Keep Open: sign
Close Without Signing: close_without_signing
Reopen: reopen
Request Reviewer: review_request_for_reviewer
Request Two Stage Review: two_stage_review_request_for_reviewer
Reviewer Request Accepted: review_accepted_for_owner
Reviewer Request Rejected: review_rejected_for_owner
First Reviewer Request Accepted: first_review_accepted_for_owner
First Reviewer Request Rejected: first_review_rejected_for_owner
Second Reviewer Request Accepted: second_review_accepted_for_owner
Second Reviewer Request Rejected: second_review_rejected_for_owner
Archive: archive
Return From Archive: unarchive
Void: void
Pull Notifications
Pull notifications are available via the REST API to be pulled down and processed via a GET request. This is typically used to "catch-up" external services that may have gone down or otherwise failed to process push notifications that occurred. These come in an array containing individual notification objects in the format seen with Push Notifications.
These notifications "dismissed" or "read" flags can be edited via the REST API PATCH endpoints to stay in sync with future notifications.
Limits
Push notifications are sent to a single URL per tenant.
Pull notifications expire after 180 days.
Which notifications to use?
We recommend both push and pull notifications are used. Using auto-dismissed Push notifications enables the benefit of real-time response to configured events. Coupled with pulling down notifications on a regular schedule and any time your service handling notifications restarts to verify all notifications were dismissed allows for an extra layer of protection against missing any notifications.
Notification Databases and Queues
We recommend storing notifications in a database while your service works off a queue. This is an effective approach in building scalable and reliable systems, especially when dealing with a high volume of incoming notifications.
To accomplish this upon receiving a notification the details would be written to a database by a service or application. A separate service would read from this database and process the content asynchronously from the service writing to your notification database.
There are many benefits of this approach with regards to decoupling of components, fault tolerance, prioritization and more.
Example Architecture
In our example architecture below we will look at a simplified architecture of an external server that handles External Notifications. In this example Signals is configured to send **All Signing Events** and **Top Level Entity Creation** events.
When receiving a "Sign and Close" signing event, you have configured your external server to handle this notification, request a PDF via the Signals REST API, and send it to your archive to maintain a record.
When receiving a an entity creation event for an experiment your have configured your external server to read this notification, request details about the newly created experiments (e.g. User, Experiment Name, etc) and sends it to y compliance dashboard to monitor its life cycle.
