doc/reference/data.rst

   1 .. _reference/data:
   2
   3 ==========
   4 Data Files
   5 ==========
   6
   7 Odoo is greatly data-driven, and a big part of modules definition is thus
   8 the definition of the various records it manages: UI (menus and views),
   9 security (access rights and access rules), reports and plain data are all
  10 defined via records.
  11
  12 Structure
  13 =========
  14
  15 The main way to define data in Odoo is via XML data files: The broad structure
  16 of an XML data file is the following:
  17
  18 * The nested root elements ``openerp`` and ``data``
  19 * Any number of operation elements within ``data``
  20
  21 .. code-block:: xml
  22
  23     <!-- the root elements of the data file -->
  24     <openerp><data>
  25       <operation/>
  26       ...
  27     </data></openerp>
  28
  29 Data files are executed sequentially, operations can only refer to the result
  30 of operations defined previously
  31
  32 Core operations
  33 ===============
  34
  35 .. _reference/data/record:
  36
  37 ``record``
  38 ----------
  39
  40 ``record`` appropriately defines or updates a database record, it has the
  41 following attributes:
  42
  43 ``model`` (required)
  44     name of the model to create (or update)
  45 ``id``
  46     the :term:`external identifier` for this record. It is strongly
  47     recommended to provide one
  48
  49     * for record creation, allows subsequent definitions to either modify or
  50       refer to this record
  51     * for record modification, the record to modify
  52 ``context``
  53     context to use when creating the record
  54 ``forcecreate``
  55     in :ref:`update mode <reference/module/lifecycle/update>`, whether the
  56     record should be created if it doesn't exist.
  57
  58     Requires an :term:`external id`, defaults to ``True``.
  59
  60 ``field``
  61 '''''''''
  62
  63 Each record can be composed of ``field`` tags, defining values to set when
  64 creating the record. A ``record`` with no ``field`` will use all default
  65 values (creation) or do nothing (update).
  66
  67 A ``field`` has a mandatory ``name`` attribute, the name of the field to set,
  68 and various methods to define the value itself:
  69
  70 Nothing
  71     if no value is provided for the field, an implicit ``False`` will be set
  72     on the field. Can be used to clear a field, or avoid using a default value
  73     for the field.
  74 ``search``
  75     for :ref:`relational fields <reference/orm/fields/relational>`, should be
  76     a :ref:`domain <reference/orm/domains>` on the field's model.
  77
  78     Will evaluate the domain, search the field's model using it and set the
  79     search's result as the field's value. Will only use the first result if
  80     the field is a :class:`~openerp.fields.Many2one`
  81 ``ref``
  82     if a ``ref`` attribute is provided, its value must be a valid
  83     :term:`external id`, which will be looked up and set as the field's value.
  84
  85     Mostly for :class:`~openerp.fields.Many2one` and
  86     :class:`~openerp.fields.Reference` fields
  87 ``type``
  88     if a ``type`` attribute is provided, it is used to interpret and convert
  89     the field's content. The field's content can be provided through an
  90     external file using the ``file`` attribute, or through the node's body.
  91
  92     Available types are:
  93
  94     ``xml``, ``html``
  95         extracts the ``field``'s children as a single document, evaluates
  96         any :term:`external id` specified with the form ``%(external_id)s``.
  97         ``%%`` can be used to output actual *%* signs.
  98     ``file``
  99         ensures that the field content is a valid file path in the current
 100         model, saves the pair :samp:`{module},{path}` as the field value
 101     ``char``
 102         sets the field content directly as the field's value without
 103         alterations
 104     ``base64``
 105         base64_-encodes the field's content, useful combined with the ``file``
 106         *attribute* to load e.g. image data into attachments
 107     ``int``
 108         converts the field's content to an integer and sets it as the field's
 109         value
 110     ``float``
 111         converts the field's content to a float and sets it as the field's
 112         value
 113     ``list``, ``tuple``
 114         should contain any number of ``value`` elements with the same
 115         properties as ``field``, each element resolves to an item of a
 116         generated tuple or list, and the generated collection is set as the
 117         field's value
 118 ``eval``
 119     for cases where the previous methods are unsuitable, the ``eval``
 120     attributes simply evaluates whatever Python expression it is provided and
 121     sets the result as the field's value.
 122
 123     The evaluation context contains various modules (``time``, ``datetime``,
 124     ``timedelta``, ``relativedelta``), a function to resolve :term:`external
 125     identifiers` (``ref``) and the model object for the current field if
 126     applicable (``obj``)
 127
 128 ``delete``
 129 ----------
 130
 131 The ``delete`` tag can remove any number of records previously defined. It
 132 has the following attributes:
 133
 134 ``model`` (required)
 135     the model in which a specified record should be deleted
 136 ``id``
 137     the :term:`external id` of a record to remove
 138 ``search``
 139     a :ref:`domain <reference/orm/domains>` to find records of the model to
 140     remove
 141
 142 ``id`` and ``search`` are exclusive
 143
 144 ``function``
 145 ------------
 146
 147 The ``function`` tag calls a method on a model, with provided parameters.
 148 It has two mandatory parameters ``model`` and ``name`` specifying respectively
 149 the model and the name of the method to call.
 150
 151 Parameters can be provided using ``eval`` (should evaluate to a sequence of
 152 parameters to call the method with) or ``value`` elements (see ``list``
 153 values).
 154
 155 ``workflow``
 156 ------------
 157
 158 The ``workflow`` tag sends a signal to an existing workflow. The workflow
 159 can be specified via a ``ref`` attribute (the :term:`external id` of
 160 an existing workflow) or a ``value`` tag returning the id of a workflow.
 161
 162 The tag also has two mandatory attributes ``model`` (the model linked to the
 163 workflow) and ``action`` (the name of the signal to send to the workflow).
 164
 165 .. ignored assert
 166
 167 Shortcuts
 168 =========
 169
 170 Because some important structural models of Odoo are complex and involved,
 171 data files provide shorter alternatives to defining them using
 172 :ref:`record tags <reference/data/record>`:
 173
 174 ``menuitem``
 175 ------------
 176
 177 Defines an ``ir.ui.menu`` record with a number of defaults and fallbacks:
 178
 179 Parent menu
 180     * If a ``parent`` attribute is set, it should be the :term:`external id`
 181       of an other menu item, used as the new item's parent
 182     * If no ``parent`` is provided, tries to interpret the ``name`` attribute
 183       as a ``/``-separated sequence of menu names and find a place in the menu
 184       hierarchy. In that interpretation, intermediate menus are automatically
 185       created
 186     * Otherwise the menu is defined as a "top-level" menu item (*not* a menu
 187       with no parent)
 188 Menu name
 189     If no ``name`` attribute is specified, tries to get the menu name from
 190     a linked action if any. Otherwise uses the record's ``id``
 191 Groups
 192     A ``groups`` attribute is interpreted as a comma-separated sequence of
 193     :term:`external identifiers` for ``res.groups`` models. If an
 194     :term:`external identifier` is prefixed with a minus (``-``), the group
 195     is *removed* from the menu's groups
 196 ``action``
 197     if specified, the ``action`` attribute should be the :term:`external id`
 198     of an action to execute when the menu is open
 199 ``id``
 200     the menu item's :term:`external id`
 201
 202 ``template``
 203 ------------
 204
 205 Creates a :ref:`QWeb view <reference/views/qweb>` requiring only the ``arch``
 206 section of the view, and allowing a few *optional* attributes:
 207
 208 ``id``
 209     the view's :term:`external identifier`
 210 ``name``, ``inherit_id``, ``priority``
 211     same as the corresponding field on ``ir.ui.view`` (nb: ``inherit_id``
 212     should be an :term:`external identifier`)
 213 ``primary``
 214     if set to ``True`` and combined with a ``inherit_id``, defines the view
 215     as a primary
 216 ``groups``
 217     comma-separated list of group :term:`external identifiers`
 218 ``page``
 219     if set to ``"True"``, the template is a website page (linkable to,
 220     deletable)
 221 ``optional``
 222     ``enabled`` or ``disabled``, whether the view can be disabled (in the
 223     website interface) and its default status. If unset, the view is always
 224     enabled.
 225
 226 ``report``
 227 ----------
 228
 229 Creates a ``ir.actions.report.xml`` record with a few default values.
 230
 231 Mostly just proxies attributes to the corresponding fields on
 232 ``ir.actions.report.xml``, but also automatically creates the item in the
 233 :guilabel:`More` menu of the report's ``model``.
 234
 235 .. ignored url, act_window and ir_set
 236
 237 CSV data files
 238 ==============
 239
 240 XML data files are flexible and self-descriptive, but very verbose when
 241 creating a number of simple records of the same model in bulk.
 242
 243 For this case, data files can also use csv_, this is often the case for
 244 :ref:`access rights <reference/security/acl>`:
 245
 246 * the file name is :file:`{model_name}.csv`
 247 * the first row lists the fields to write, with the special field ``id``
 248   for :term:`external identifiers` (used for creation or update)
 249 * each row thereafter creates a new record
 250
 251 Here's the first lines of the data file defining US states
 252 ``res.country.state.csv``
 253
 254 .. literalinclude:: ../../openerp/addons/base/res/res.country.state.csv
 255     :language: text
 256     :lines: 1-15
 257
 258 rendered in a more readable format:
 259
 260 .. csv-table::
 261     :file: ../../openerp/addons/base/res/res.country.state.csv
 262     :header-rows: 1
 263     :class: table-striped table-hover table-condensed
 264
 265 For each row (record):
 266
 267 * the first column is the :term:`external id` of the record to create or
 268   update
 269 * the second column is the :term:`external id` of the country object to link
 270   to (country objects must have been defined beforehand)
 271 * the third column is the ``name`` field for ``res.country.state``
 272 * the fourth column is the ``code`` field for ``res.country.state``
 273
 274 .. _base64: http://tools.ietf.org/html/rfc3548.html#section-3
 275 .. _csv: http://en.wikipedia.org/wiki/Comma-separated_values