.. include:: hyperlinks.txt

Events
=======

This applications record events. It can happen at a date or span during a
period of time.

An event is defined by a *starting date*, by an *ending date* and by a *type*.

An event contains *meta-data* linking the event to:

* a person
* a team
* a project
* a category (the category of people in this application)
* a funding agency

The events are stored in the ``history`` table and the meta-data in the foreign
tables ``fundings``, ``people``, ``people_categories``, ``projects`` and
``teams``. The organization of the table can not be changed. All the fields of
these tables are standard database field which can be used in SQL request or in
reports.

An event contains also the *user data block*. It is stored in one database
field. The user data block is a python dictionary serialized as a JSON_ string.
The structure of the dictionary, *the keys*, are defined by the user, once, for
each event type. The structure of the dictionary can be modified at any
time by the user. Mechanisms are in placed to guaranty the consistency across
the database. The SQL request are limited to string operations.
Individual key of the dictionary can not be used in SQL request. But, any key
can be manipulated in reports.

Define an event
----------------

The event definitions are stored in the ``events`` table.

In order to create a new event definition:

    1. Open the leaf ``events > definition`` in the left panel of the
       viewport.
    2. Open the contextual menu in the right panel.
    3. Select the menu item ``Add``.

        .. figure:: figures/event-form.png
           :align: center
           :width: 50%

           The form to enter an event definition in the database.

    4. Enter the event type in the ``event`` entry.
    5. Enter the python dictionary structure in the ``model`` field.
       Add the first key by right clicking on ``property`` label. Later on,
       key can be ``Add``, ``Modify`` or ``Delete`` using the
       contextual menu.

        .. warning::
            the data user block of the existing events are updated when the
            python dictionary structure is modified.

       A good practice is to enter the type of key (``boolean``,
       ``date``, ``string``, ``number``) or a default value.

Enter an event in the history
------------------------------

Events of any kind are stored in the ``history`` table.
In order to create a new one:

    1. Open the leaf ``events > history`` in the left panel of the
       viewport.
    2. Open the contextual menu in the right panel.
    3. Select the menu item ``Add``.

        .. figure:: figures/history-form.png
           :align: center
           :width: 50%

           The form to enter an event in the database.

    4. Scan the different tabs and fill the appropriate entries.

Make report on events
----------------------

The application provides a rich set of tools to configure and to
produce reports. They are covered in the Chapters :ref:`Configure the lists`,
:ref:`Configure the 1-dim metrics` and :ref:`Configure the 2-dim metrics`