Notifications - bcgov/PIMS GitHub Wiki
PIMS requires the ability to send email notifications to agencies to inform them of properties that are approved for the Enhanced Referral Program (ERP).
To support email notifications PIMS will be required to maintain a list of notification templates in the database (the table is NotificationTemplates) that can be populated with data through variable insertion. Additionally notifications will need to be sent based on workflow triggers and allow for adhoc triggers.
Right now when someone submits a new Disposal project, a "New Disposal Project Submitted" notification template (id = 1) will get triggered to be sent to whomever created the project.
When a new project gets approved for ERP, then notifications will be sent to all "parent" agencies (all the ministries in the BC government which have their notifications set to receive emails in PIMS) as well as the "owning" agency that created the project.
When a project's "Shared Notes" has changed, a "Project Shared Note Changed" notification template (id = 16) will get triggered to be sent to whomever created the project.
Notifications for a project are stored in the "NotificationQueue" table in the status column and the statuses are set here: https://github.com/bcgov/PIMS/blob/dev/backend/entities/NotificationStatus.cs
There are 4 configuration files for CHES which are located in the /backend/api folder: ches.Development.json, ches.Local.json, ches.Test.json, and ches.json
There are a number of challenges depending on requirements that will stil need to be solved;
- Once notifications are sent to CHES this current implementation does not verify or update the status, which essentially leaves all notifications as
pending
within PIMS, regardless of CHES status. - Post-dated notifications are sent to CHES that may need to be cancelled if an agency is not interested in received further notifications on a specific property.
Notification templates will be created to support dynamic content. These templates will be associated with project status transitions. This will allow the Simple Workflow Engine to determine whether a notification should be generated and sent when specific conditions are met (from status, to status event). When a notification trigger occurs a check against existing responses will be reviewed to determine whether there is an expressed interest on receive additional notifications. If the agency has responded to with a no desire for additional notifications, no notification will be generated. Otherwise a notification will be generated and added to the queue.
Generated notifications can include a callback (URL link) to capture a response. This callback can be the API endpoint to record the recipients response.
To support delayed notifications, the project status trigger will also include a Delay
parameter that provides the following options;
Delay | Description |
---|---|
None | Immediately send this notification |
EndOfDay | Send notification on the current day at midnight |
EndOfMonth | Send notification on the current end of month at midnight |
Days | Send notification x days from the current date, using the DelayDays value |
SetDay | Prompt the user to select a date that the notification will be sent on |
The API will have an endpoint /api/notifications/{key}/{response}
that will provide a way for recipients to click a link in their notification to inform PIMS of interest or the lack thereof.
The API will validate the Key
and record the response for the appropriate agency and project.
RISK - It is possible a bad agent could spam this endpoint and flood the API with fake responses, but it would still be limited to only valid
Key
values.
A notification template provides a way to reuse an notification subject and body for multiple emails.
The following templates will need to be provided;
- Inform Agencies of new properties in the ERP.
- Inform interested agencies of workflow events (30, 60, 90 days) while in ERP.
To support template the following variable contexts will be supported;
-
{{ Property.* }}
- any property field that will be included (i.e. Property.Name, Property.Address.Address1, Property.Agency.AddressTo) -
{{ Project.* }}
- any project field that will be included (i.e. Project.Name, Project.ProjectNumber) -
{{ NotificationKey }}
- the unique key to identify the notification
The NotificationTemplate
entity will need to include the following properties;
Name | Type | Required | Constraint | Description |
---|---|---|---|---|
Id | int | PRIMARY | IDENTITY | Unique identity within PIMS |
Name | nvarchar(100) | yes | A unique name to identify the template | |
Description | nvarchar(500) | A description of the template and its purpose | ||
Encoding | nvarchar(50) | yes | [base64, binary, hex, utf-8] | Notification encoding |
BodyType | nvarchar(50) | yes | [html, text] | Notification message body type |
Priority | int | yes | [normal, low, high] | Notification default priority |
Subject | nvarchar(200) | yes | Notification subject line (supports variables) | |
Body | nvarchar(max) | yes | Notification message template (supports variables) | |
IsDisabled | bit | yes | Whether the template is disabled | |
Tag | nvarchar(50) | A Tag passed to CHES to filter notifications | ||
Audience | int | yes | [Default, Agencies, ParentAgencies, OwningAgency] | The audience for this notification. Default requires the To property to have email addresses |
To | nvarchar(500) | A semi-colon separated lists of email addresses that this notification will be sent to | ||
Cc | nvarchar(500) | A semi-colon separated lists of email addresses that this notification will be carbon-copied to | ||
Bcc | nvarchar(500) | A semi-colon separated lists of email addresses that this notification will be blind carbon-copied to |
URL | HTTP | Query | Body | Description |
---|---|---|---|---|
/api/notifications/templates | GET | Returns all the notification templates | ||
/api/notifications/templates/{id} | GET | Return the notification template for the specified 'id' | ||
/api/notifications/templates | POST | Template | Add a new notification template | |
/api/notifications/templates/{id} | PUT | Template | Update the notification template | |
/api/notifications/templates/{id} | DELETE | Template | Delete the notification template | |
/api/notifications/templates/{id} | POST | to | {object} | Send a test notification for the specified template |
The Agency
entity will need to include the following properties;
Name | Type | Required | Constraint | Description |
---|---|---|---|---|
nvarchar(250) | Email address (semi-colon delimiter) that will receive notification emails from PIMS | |||
SendEmail | bit | yes | Whether notification emails should be sent to the agency | |
AddressTo | nvarchar(100) | The person/entity to address the notifaction to |
To automate the sending of emails and associating them to a workflow project status, each NotificationTemplate
will be linked to a ProjectStatus
.
Notifications will be triggered when the FromStatus
and/or ToStatus
conditions are met during the workflow project lifecycle.
Name | Type | Required | Constraint | Description |
---|---|---|---|---|
Id | int | PRIMARY | IDENTITY | Unique identity within PIMS |
TemplateId | int | yes | FOREIGN | Link to the template that this trigger will use when generating an notification |
FromStatusId | int | FOREIGN | Link to the project status that will trigger this notification | |
ToStatusId | int | FOREIGN | Link to the project status that will trigger this notification | |
Priority | int | yes | [normal, low, high] | The priority of the notification that will be sent |
Delay | int | yes | [none, endOfDay, endOfMonth, days, setDate] | Controls when a notification will be sent |
DelayDays | int | yes | Number of days to delay sending notification |
When a notification is sent a unique key will be generated that will allow responses to the notification to be tracked and acted upon. These responses will be stored and used to determine future notification decisions.
Name | Type | Required | Constraint | Description |
---|---|---|---|---|
ProjectId | int | PRIMARY | FORIEGN | Link to the project that this notification is related to |
AgencyId | int | PRIMARY | FORIEGN | Link to the agency that this notification was sent to |
MessageId | int? | FORIEGN | Link to the notification that was sent | |
Response | int | yes | [ignore, watch] | A way for agencies to indicate interest or the lack thereof in the notification subject |
A notification queue will be maintained to capture all generated notifications and their current status. Additionally this will provide a future ability to resend or cancel notifications.
Name | Type | Required | Constraint | Description |
---|---|---|---|---|
Id | int | PRIMARY | IDENTITY | Unique identifier within PIMS |
Key | uniqueidentifier | yes | Unique key to identify the messages when agencies respond | |
Status | int | yes | [accepted, cancelled, completed, failed, pending] | The currently known status of the notification within CHES |
Priority | int | yes | [normal, low, high] | The email priority |
Encoding | nvarchar(50) | yes | [base64, binary, hex, utf-8] | The email encoding |
SendOn | datetime2 | yes | Desired UTC time for sending the message. 0 = Queue to send immediately | |
To | nvarchar(100) | yes | Email address sent to | |
Subject | nvarchar(200) | yes | Email subject line | |
BodyType | nvarchar(50) | yes | [html, text] | Email body type |
Body | nvarchar(max) | yes | Email message | |
Bcc | nvarchar(100) | yes | Email blind carbon copy | |
Cc | nvarchar(100) | yes | Email carbon copy | |
Tag | nvarchar(50) | Notification tag to identify related notifications | ||
ProjectId | int? | FORIEGN | Link to the project that this notification is related to | |
ToAgencyId | int? | FORIEGN | Link to the agency that this notification was sent to | |
TemplateId | int? | FOREIGN | Link to the template that generated this notification | |
ChesMessageId | uniqueidentifier? | PRIMARY | Message identifier within CHES | |
ChesTransactionId | uniqueidentifier? | PRIMARY | Transaction identifier within CHES |
URL | HTTP | Query | Body | Description |
---|---|---|---|---|
/api/notifications/queue/{id} | GET | Return the notification for the specified 'id' | ||
/api/notifications/queue/{id} | PUT | Update the notification status from CHES |