=======================
An Audit Log Convention
=======================

+-------------+------------------------------------------------+
| CCEP        | 6                                              |
+-------------+------------------------------------------------+
| Title       | An Audit Log Convention                        |
+-------------+------------------------------------------------+
| Version     | 1                                              |
+-------------+------------------------------------------------+
| Author      | Meriam Kharbat                                 |
+-------------+------------------------------------------------+
| Date        | 2019-04-25                                     |
+-------------+------------------------------------------------+
| Status      | Accepted                                       |
+-------------+------------------------------------------------+

Introduction
============

This CCEP outlines the audit log convention to be followed in ``cloud-app``.

Proposal
========

The goal of the audit log is to allow organization admins to view the
actions performed by the organization members. It will include details
such as *who* performed the action, *what* the action was, and *when*
it was performed.

Action Categories
-----------------

+---------------+------------------------------------------------+
| Category Name | Description                                    |
+===============+================================================+
| user          | user related actions                           |
+---------------+------------------------------------------------+
| organization  | organization related actions                   |
+---------------+------------------------------------------------+
| project       | project related actions                        |
+---------------+------------------------------------------------+
| product       | product related actions                        |
+---------------+------------------------------------------------+

Action Naming Convention
------------------------

The action name should be constructed as follows:

::

  CATEGORY.ACTION | CATEGORY.ACTION_RESOURCE

*CATEGORY:* The category is a noun in lowercase form that describes
the category of the action. Example: ``organization``.

*ACTION:* The action is a verb in the infinitive form, always lowercase.
Example: ``upgrade``.

*RESOURCE:* the resource is a noun, describing an additional resource
that complements the action verb, always in lowercase. Example: ``role``.
the full action ``ACTION_RESOURCE`` in this case, would be ``add_role``
for example.


Example
+++++++

Here is an example of the audit log of the action of adding a
user to an organization. The action in this case is
``organization.add_user``::

    Audit().log(
        "organization.add_user",
        "marvel.org",
        {
            "organization" : {
                "id": "marvel.org",
                "name": "Marvel",
            },
            "current_user": {
                "organization_id": "marvel.org",
                "username": "ironman",
            },
            "added_user": {
                "organization_id": "marvel.org",
                "username": "captain-marvel",
            },
        },
    )


This action will be displayed as follows in the console::

    ironman
    Added captain-marvel to marvel.org
    1 day ago