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:

.. py:class:: ppc_robot_lib.models.Notification

    .. py:attribute:: created_time

        Time the notification was emitted.

    .. py:attribute:: user

        User.

    .. py:attribute:: service_account

        Management account related to notification.

    .. py:attribute:: client_account

        Client account related to notification.

    .. py:attribute:: job

        Job (= report) that raised the notification.

    .. py:attribute:: level

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

    .. py:attribute:: platform

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

    .. py:attribute:: category

        Numeric ID of notification category. See :doc:`categories/index` for more details.

    .. py:attribute:: 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 :doc:`categories/index` for more details.

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

    .. py:attribute:: 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.

    .. py:attribute:: entity_ids

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

    .. py:attribute:: silenced

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

    .. py:attribute:: 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.

    .. py:attribute:: text

        Text of the notification. The text might be localized to user's locale.

    .. py:attribute:: text_parameters

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

    .. py:attribute:: 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 :ref:`notification-details` section for description of the structure.

    .. py:attribute:: state

        State of the notification - ``new``, ``seen``, ``resolved``, ``invalidated``.


.. _notification-details:


Flow of delivery
----------------

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

.. image:: images/notifications-flow.svg


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.

.. image:: images/notifications-settings-db.png


Notification adapter
--------------------

Notification adapter should implement the following abstract class:

.. autoclass:: ppc_robot_lib.notifications.AbstractNotificationAdapter
    :members:


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:

* |details_table|_ -- rendered as HTML tables.

.. |details_table| replace:: ``table``


.. _details_table:

``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.