README.rst

Analytic Structure

What is it ?

The module provides a way of defining dynamic relationships between objects. We use the following concepts:

• Dimensions, represented by analytic.dimension
• Structure, represented by analytic.structure
• Codes, represented by analytic.code

These objects can be seen in Technical >> Analytics under Settings.

Dimensions act as labels for data points that can be used to perform analyses. Structures define mappings between models and dimensions, they can be configured through the Settings menu. Codes are the objects that are bound to instances of dimension models, they allow us to define dynamic relationships.

Example: Your company has several product lines and you would like to analyse expenses related to these product lines in your accounting system. You would then define a product line dimension and some structures that bind the product line dimension to product.product, invoice.line, account.move.line models.

How does it work ?

Analytic Structure provides the MetaAnalytic metaclass (see MetaAnalytic) that injects new behaviors into Odoo models. Dimension models and models that define analytic fields must use MetaAnalytic and define various class attributes.

A dimension model is declared with the _dimension attribute (see AnalyticDimensions). The metaclass automatically creates analytic.dimension records for each dimension model. Once a model is declared as a dimension, every new instance will automatically create a new analytic.code record that points to the relevant analytic.dimension record.

A model that is declared with the _analytic attribute (see AnalyticFields) can reference dimension objects. The MetaAnalytic will automatically create a number of M2O fields that point to analytic codes. The number of fields that will be added depends on the configuration (See ConfigureAnalyticFields). They are named with a predefined prefix and a number or slot eg. a1_id, a2_id, a3_id, ...

These analytic fields will be displayed in views with the names of the dimensions they point to thanks to view manipulation magic.

Schematic:

| AnalyticModel     Code        DimensionModel     Dimension
| -----             ----        --------------     ---------
| an_id ----------> id,name <-- analytic_code_id
|
|                   n_id    ---------------------> id,name

The relationship between a model and a dimension is configured by analytic structures. Structure define how models point to dimensions and what analytic field to use.

Example: You have a dimension D you wish to bind to model A. You would create an analytic.structure record for A that references D through the Analysis 1 slot. This would allow you to use the a1_id field (assuming the default prefix is used) to reference D records.

Integrity of analytic codes

You cannot delete analytic codes that are referenced by objects. The goal of this constraint is to ensure the integrity of your analyses.

Configure your OpenERP server for analytic fields

In your OpenERP server's configuration file, you can set several optional parameters related to the analytic module.:

[analytic]
key = value ...

Those options must be grouped under the [analytic] category. If the category doesn't exist, add it to your configuration file.

key (default value): description

analytic_size (5): define the maximum number of analytic dimensions that can be associated with a model.

translate (False): enable or disable the translation of field values on analytic dimensions (name) and codes (name and description).

Add the MetaAnalytic metaclass to a model

At the beginning of the source file, import the MetaAnalytic metaclass:

from openerp.addons.analytic_structure.MetaAnalytic import MetaAnalytic

Inside your Model class, define MetaAnalytic to be used as metaclass:

__metaclass__ = MetaAnalytic

Add analytic fields to a model

First of all, make sure you are using the MetaAnalytic metaclass. Then, add the _analytic attribute to your class, using the following syntax.

Use the analytic fields associated with the model:

_analytic = True

Use analytic fields associated with another model:

_analytic = 'account_move_line'

Use several analytic field structures, associated with different prefixes:

_analytic = {
    'a': 'account_asset_asset',
    't': 'account_move_line',
}

Add analytic fields to a view

Analytic fields can be added to the view individually, like any other field:

<field name="a1_id" />

'a' is the prefix associated with the structure. By default, it is 'a'. '1' is the dimension's ordering as defined by the analytic structure.

You can also use a field named 'analytic_dimensions' to insert every analytic field within a given structure (defined by its prefix) that wasn't explicitly placed in the view. This field is automatically generated when you call the Metaclass