-
Notifications
You must be signed in to change notification settings - Fork 4
Communications Notifications Overview
Notification is a layer on top of Communication.
The Notification Directory preforms two core functions:
- The listing and filtering of notifications.
- The definition of notifications that populate the directory.
Every notification definition describes the purpose of the notification and which channels can be subscribed to for the specific notification.
Notifications are a generic term used to describe a subscription endpoint allowing users to subscribe to specific notifications. A notification can be broadly used and defined in many ways; this is by design, to ensure that business use cases are as widely covered as possible.
Notifications allow business units to define a transactional or newsletter type of subscription that can be activated by business units, business processes, and interacting systems.
Examples of Notifications:
- Service Request Status Updates
- Neighbourhood Construction Alerts
- City-Wide Emergency Alerts
- Boil Water Advisories
- Product Recalls
- Travel Advisories
- Construction and Incident alerts for my Commuting Route
Every notification has:
- Title
- Short Description
- Icon
- Slug
- Long Description
- Channels
- Sub-Categories (Optional)
Notifications are used by [Communications] to determine the recipients of a communication.
Notification Channels are the available channels that a user can subscribe to as part of a Notification Subscription.
A subscription represents a record that the user is subscribed to the specific notification. A subscription relates to a Individual, a Notification and the DateTime of the subscription. Each channel that is subscribed to for a notification is child-record of the parent subscription to the Notification.
Has the Related User Related Notification Related Channels
Communication Channels represent the channels that a specific notification supports. Channels can be configured as part of the Channels configuration.
Subscription Channels are used by Communications to determine the recipients for a notification on a per channel basis.
Example:
If a Individual is subscribed to the Service Request Status Updates Notification, and has chosen the Subscription Channels of SMS and Email, when a Communication is generated, the Individual will receive a SMS and Email for the specific Service Request Status Update.
A communication is a blueprint that describes what the content of a communication is to a group of recipients.
A set of rules that describes what to be sent, to who, and how.
The input of a communication is the specific configuration of the communication's content and selection of recipients. The output is the generation of Messages which are sent Channels, which determine which Transports to use, Configured by Transport Profiles.
Fields: Communication Metadata:
- Title
- Description
Content (Collection):
Each Collection Defines:
- Channel (List of Communication Channels)
- Profile (List of Transport Profiles. The Profile list is dependent on the selection of a Channel)
- Template (List of Title and Presentation templates / Content Templates)
- Title
- Presentation
Selecting a Channel is used as a filter for Notifications. Selecting a Profile is used as the specific configuration to be used when sending the communication through the selected Channel.
Ability to add 1 or more Content Collections.
Criteria:
By default a communication is sent to no one. A criteria must be set for users to receive.
Notification Criteria: The Selection of a Notification in the Notification Directory, that will select all users who are subscribed to that notification. The Content Collection / The Channel field in the Content Collection is used as the filter for content per channel in the notification.
On Message Send / Communication Execution, The Criteria is executed once per Content Collection Row (basically once per channel) Using a Notification as a Criteria means that the Notification Subscriptions are respected for the specific channels to which a Individual will receive the communication / Receive their respective messages.
Example:
A Communication is created for a Service Request Status Update. The Individual has subscribed to the Service Request Status Updates Notification with the SMS and Email Subscription Channels. The Communication will generate two messages:
- Email Message
- SMS Message
The two messages are associated with same Communication.
A Communication may be used with transactional messages and recurring newsletter messages.
A Communication has several states and transitions:
- Draft
- Under Review
- Ready
- Scheduled
- Abandoned
- Preparing
- Sending
- Paused
- Sent
The transitions for the states are:
- --> Draft
- Draft <--> Under Review
- Draft <--> Ready
- Draft --> Abandoned
- Draft <--> Scheduled
- Scheduled --> Preparing
- Preparing <--> Ready
- Preparing --> Sending
- Sending --> Sent
- Sending <--> Paused
- Paused --> Ready
- ... WIP
Notes:
- When a communication is Preparing, and the Communication is then Cancelled, all messages that have been generated are deleted.
- When a communication is sending, and the Communication is then Cancelled/The Sending is cancelled, all Un-Sent Messages are deleted. Sent Messages are not deleted.
- When a Communication that is sending is cancelled, and then placed back into sending, messages are regenerated for all recipients, even recipients that have already received a messaged from the Cancelled communication
@TODO The configurations of the actual support channels for all communications. This listing of channels is the channels that appear in the Notification configuration page. (A channel must exist in the Communication Channels for a Notification to be Subscribable to that Channel)
A channel is a representation of the Channel to which a Message will be sent through. A channel provides endpoint to an Implementation. A Implementation is a php file that manages the transfer and data manipulation of a message being sent to a transport.
Fields:
- Title
- Description
- Icon
- Implementation (dropdown of )
- Default To (pattern)
@TODO the ability to schedule the sending of a Communication through OroBAP Job Queue or a BPM Process.
Messages contain the actual content that is sent through the Message Gateways.
Messages are generated by Communications and thus related to a Communication.
Messages contain the finalized content that is to be sent through the gateway.
Messages persist the actual content rather than a tokenized or relation to a template because of the need for a hardened audit trail of data of what was actually sent through a Message Gateway.
A message is related to a specific channel.
A message is related to Individual/User.
A Message tracks when it was sent.
WIP: A message could be extended to support Callbacks. Where a Gateway sends confirmation or status information about the success/failure/click-through/open-rate of a message.
A message represents is a hard-copy of what is being sent to a recipient. (it is like the hard-copy paper that is being sent in the mail).
A message is passed through a Channel into the Channel's Implementation. The message is then passed into a Transport that sends the message through the transport's gateway.
--
Example:
If a Individual is subscribed to the Service Request Status Updates Notification, and has chosen the Subscription Channels of SMS and Email, and the Communication was successfully generated, the SMS and Email are generated as separate messages, but both related to the single communication.
It is also possible that multiple messages for a single channel to a single recipient are generated as part of a communication.
Messages have a state which allows asynchronous job execution of the generation and sending of messages through message gateways.
The standard states for Messages is:
- Queued
- Sending
- Sent
- Cancelled
- Failed
The standard state transitions are:
- --> Queued
- Queued --> Sending
- Queued --> Cancelled
- Sending --> Sent
- Sending --> Failed
- Failed --> Queued
The state of a message can be controlled through a BPMN process or through the OroBAP Job Queue.
@TODO a way to group communications over periods of time. Typically related to calendar events, interactions or special conditions defined by a business unit.
A Transport is a component that actually does the sending. (also referred to as Message Transports). These components are made up of code libraries that provide the ability to send messages.
Examples of Transports:
- Twilio
- SMTP
- AWS SNS
- MailChimp
- MailGun
Transports configured through using Profiles.
Profiles (also referred to as Transport Profiles) are the configuration of Message Transports for use by Communications.
A Profile allows a Transport to be used with multiple configurations depending on the use case and business needs.
Examples of Transport Profiles:
- Twilio Canada
- Twilio Australia
- Twilio United States
- Government MS Exchange Email 1
- Government MS Exchange Email 2
In the examples above, all three Twilio Profiles use the same Twilio Transport, but the profiles offer different configurations such as a different "From" phone number for sending SMS/Text Messages based on the Country of the Recipient. The Government MS Exchange examples are two Microsoft Exchange email servers that have different credentials to send emails through.
A Profile can be used for many different configuration needs and purposes. The goal of using a Profile is to provide reusable configuration in a centralized location rather than having to control Transport configuration at a Service level.
A Profile can also be used to control what aspect of a transport is used for a Channel:
Example:
The AWS SNS Transport supports sending SMS, Push, and Email. Three profiles can be created, one for each Channel (SMS, Push, Email), that instruct the transport to use a specific aspect of the Gateway when using the select profile.
In some scenarios, a Individual's subscription to a Notification is mandatory:
Example 1:
Notification: City-Wide Emergency Alerts.
This notification is mandatory for all Individuals/users. A Individual is automatically subscribed to this notification upon account creation, and cannot un-subscribe at any time.
Example 2:
Notification: Service Request Status Updates.
This notification is mandatory for all Individuals/users. A Individual is automatically subscribed to this notification upon account creation, and cannot un-subscribe at any time. This notification only supports the Email Channel, but the administrator does not wish to show this notification in the notification directory. As a result, the visibility of the Notification set so that the user cannot see the Notification or their subscription to the notification in the Notification Directory
@TODO the ability to have notifications that are active but not visible in the notification directory.
@TODO When an individual subscribes to a notification there is often a need for additional notification subscription data to be collected as part of the subscription. Common examples include: Topics and Administrative Areas/Wards/Boroughs/Districts.
Example:
Notification: Community Events in the City
The Notification is for receiving information about community events across a City. The notification is used by multiple grouped within the organization. When a individual subscribes to this notification, they typically would like to choose a specific administrative area (such as a Ward, Borough) or Neighbourhood that they are interested in.
This information could also be determined by the Individual's Persona data but what is the Individual is interested in multiple areas? What if for specific Notification, the Individual is interested in all Community Events across a City?
Sub-Categories allow all of these scenarios to be supported. Sub-categories provide Communications a filtering term to target Individuals by a Notification and the sub-categories within that Notification. Example: The Individual is subscribed to the Community Events in the City Notification, but only for Boroughs: 1, 2 and 5.