Notification Design

Key concepts:

Channel

Channel is a service or interface that is used by user to receive the notifications. The examples of channels includes:

PPC Robot interface,
E-mail,
Slack,
(planned) Web Browser (powered by OneSignal), and
(planned) Mobile (powered by OneSignal).

The channels can be divided into two groups: internal and external. There is only one internal channel: PPC Robot interface, all other channels are external. External channels might require additional configuration and can be disabled and configured. The user cannot disable the internal channel and can not customize what messages he will get in the interface. However, the interface might provide further filtering of notifications.

Notification

Notification is a single message delivered to a user.

Notification Entity

The notification has the following attributes:

class ppc_robot_lib.models.Notification

created_time: Time the notification was emitted.

user: User.

service_account: Management account related to notification.

client_account: Client account related to notification.

job: Job (= report) that raised the notification.

level: Severity of the notification. The channel might have a different processing based on the severity. Can be error, warning, suggestion.

platform: Optional platform related to the notification. Can be adwords, sklik, bing, etc.

category: Numeric ID of notification category. See Categories and Codes for more details.

code

Numeric code of notification. The code is unique in the category, therefore the tuple (category, code) provides a unique identification of the notification type. This tuple will be used to generate a link to knowledge-base with additional details to the notification.

See Categories and Codes for more details.

Please note that one type of notification can be used on multiple platforms – for instance with URL checker.

score: Score that describes the importance of the notification. Two notifications of the same score might have a different score depending on the importance of the entity. For instance, if you receive two notifications about low performance of two campaigns, the notification score for the campaign with more impressions will be higher.

entity_ids: List of entities related to the notification. One notification is expected to be related only to one entity type.

silenced: Boolean flag indicating whether the notification has been silenced. Silenced notifications should be hidden in the in-app user interface.

localized: Boolean flag indicating whether the text of the notification shall be localized. In case of custom notifications, the text might be an user-entered string. In this case, we do not want to localize the text, as it is expected to already be in the user’s language.

text: Text of the notification. The text might be localized to user’s locale.

text_parameters: Parameters for string interpolation in the text. Enables localization of notifications.

details: JSON array with additional details. Each item will represent a table, paragraph, image or other structure that will be rendered into the resulting notification. See the Flow of delivery section for description of the structure.

state: State of the notification - new, seen, resolved, invalidated.

Flow of delivery

The following diagram describes the flow that is used to determine whether the delivery should be delivered to a channel.

User settings

The following diagram describes tables used to store user configuration of notifications. This includes configuration for channels, notification routing and list of ignored notifications.

Notification adapter

Notification adapter should implement the following abstract class:

class AbstractNotificationAdapter(celery_app, configuration)[source]

Abstract notification adapter. The implementing class should send notifications through the defined channel.

Initializes the adapter for channel with given configuration.

Parameters:: configuration (dict[str, Any]) – Channel configuration.

abstract send_notifications(user_id, notifications)[source]

Queues notification over the given channel. The implementing class should decide whether the notification shall be sent, according to the specifics of the given channel.

Parameters:

user_id (int) – User which should receive the notification.
notifications (list[Notification]) – Notification to send.

send_summary(user_id, last_at, enabled_categories=None)[source]

Creates and sends daily summary over the given channel. The implementing class should decide which notifications shall be sent in the summary.

Parameters:

user_id (int) – User for which the summary should be generated.
last_at (datetime) – Time when the last summary was sent.
enabled_categories (list[int]) – List of enabled notification categories.

abstract classmethod supports_summary()[source]

Returns whether the implementing adapter supports sending daily summaries.

Return type:: bool
Returns:: True if the adapter supports daily summaries.

Notification Details

Each of the items in the details array has a special attribute _type, which specifies type of the object. Currently allowed types are:

table – rendered as HTML tables.

`table` object

Tables has the following structure:

{
    "_type": "table",
    "caption": "An Example Table",
    "header": {
        "cells": ["Column A", "Column B", "Column C"]
    },
    "rows": [
        {"id": 1, "silenced": false, "cells": ["1", "A", "42"]},
        {"id": 2, "silenced": true,  "cells": ["2", "B", "42"]},
        {"silenced": false, "cells": ["3", "C", "42"]}
    ],
    "footer": {
        "cells": ["6", "ABC", "42"],
    }
}

Id in the rows structure is optional. It will be used to determine whether the row is silenced or not.