2
.. i18n: .. warning:: This section needs to be rewritten or improved. If you think you
3
.. i18n: can contribute to this effort, and are already familiar with Launchpad
4
.. i18n: and OpenERP's source control system, Bazaar, please have a look at:
6
.. i18n: * the section explaining how you can download and build the
7
.. i18n: current documentation on your system: :ref:`building_documentation`
8
.. i18n: * an RST primer such as `this one <http://sphinx.pocoo.org/rest.html>`_ to learn
9
.. i18n: how you can start modifying the documentation content
12
.. warning:: This section needs to be rewritten or improved. If you think you
13
can contribute to this effort, and are already familiar with Launchpad
14
and OpenERP's source control system, Bazaar, please have a look at:
16
* the section explaining how you can download and build the
17
current documentation on your system: :ref:`building_documentation`
18
* an RST primer such as `this one <http://sphinx.pocoo.org/rest.html>`_ to learn
19
how you can start modifying the documentation content
21
.. i18n: .. _technical_update_procedure:
23
.. i18n: =========================
24
.. i18n: Upgrading Server, Modules
25
.. i18n: =========================
28
.. _technical_update_procedure:
30
=========================
31
Upgrading Server, Modules
32
=========================
34
.. i18n: The upgrade from version to version is automatic and doesn't need any special
35
.. i18n: scripting on the user's part. In fact, the server is able to automatically
36
.. i18n: rebuild the database and the data from a previously installed version.
39
The upgrade from version to version is automatic and doesn't need any special
40
scripting on the user's part. In fact, the server is able to automatically
41
rebuild the database and the data from a previously installed version.
43
.. i18n: The tables are rebuilt from the current module definitions. To rebuild the
44
.. i18n: tables, the server uses the definition of the objects and adds / modifies
45
.. i18n: database fields as necessary.
48
The tables are rebuilt from the current module definitions. To rebuild the
49
tables, the server uses the definition of the objects and adds / modifies
50
database fields as necessary.
52
.. i18n: To invoke a database upgrade after installing a new verion, you need to start
53
.. i18n: the server with the **--update=all** argument :
56
To invoke a database upgrade after installing a new verion, you need to start
57
the server with the **--update=all** argument :
61
.. i18n: openerp-server.py --update=all
66
openerp-server.py --update=all
68
.. i18n: You can also only upgrade specific modules, for example:
71
You can also only upgrade specific modules, for example:
75
.. i18n: openerp-server.py --update=account,base
80
openerp-server.py --update=account,base
82
.. i18n: The database is rebuilt according to information provided in XML files and
83
.. i18n: Python Classes.
84
.. i18n: You can also execute the server with **--init=all**. The server will then
85
.. i18n: rebuild the database according to the existing XML files on the system, delete
86
.. i18n: all existing data and return OpenERP to its basic configuration.
89
The database is rebuilt according to information provided in XML files and
91
You can also execute the server with **--init=all**. The server will then
92
rebuild the database according to the existing XML files on the system, delete
93
all existing data and return OpenERP to its basic configuration.
95
.. i18n: Detailed update operations
96
.. i18n: ++++++++++++++++++++++++++
99
Detailed update operations
100
++++++++++++++++++++++++++
102
.. i18n: OpenERP has a built-in migration and upgrade system which allows updates to be nearly (or often) automatic.
103
.. i18n: This system also allows to easily include custom modules.
106
OpenERP has a built-in migration and upgrade system which allows updates to be nearly (or often) automatic.
107
This system also allows to easily include custom modules.
109
.. i18n: Table/Object structure
110
.. i18n: """"""""""""""""""""""
113
Table/Object structure
114
""""""""""""""""""""""
116
.. i18n: When you run openerp-server with option ``--init`` or ``--update``, the table
117
.. i18n: structure is updated to match the new description that is in Python code. Fields
118
.. i18n: that are removed from Python code are not removed from the postgresql database
119
.. i18n: to avoid losing data.
122
When you run openerp-server with option ``--init`` or ``--update``, the table
123
structure is updated to match the new description that is in Python code. Fields
124
that are removed from Python code are not removed from the postgresql database
125
to avoid losing data.
127
.. i18n: So, simply running with ``--update`` or ``--init``, will upgrade your table structure.
130
So, simply running with ``--update`` or ``--init``, will upgrade your table structure.
132
.. i18n: It's important to run ``--init=module`` the first time you install the module.
133
.. i18n: Next time, you must use the ``--update=module`` argument instead of the init
134
.. i18n: one. This is because ``--init`` loads resources that are loaded only once and
135
.. i18n: never upgraded (i.e., resources with no ``id=""`` attribute or within a
136
.. i18n: ``<data noupdate="1">`` tag). The ``noupdate`` attribute can be overridden by
137
.. i18n: marking a record with ``forcecreate="True"``. This means that the record will be
138
.. i18n: created if it doesn't already exist in the database, but it won't be modified.
141
It's important to run ``--init=module`` the first time you install the module.
142
Next time, you must use the ``--update=module`` argument instead of the init
143
one. This is because ``--init`` loads resources that are loaded only once and
144
never upgraded (i.e., resources with no ``id=""`` attribute or within a
145
``<data noupdate="1">`` tag). The ``noupdate`` attribute can be overridden by
146
marking a record with ``forcecreate="True"``. This means that the record will be
147
created if it doesn't already exist in the database, but it won't be modified.
151
.. i18n: Some data is automatically loaded at the installation of OpenERP:
156
Some data is automatically loaded at the installation of OpenERP:
158
.. i18n: * views, actions, menus,
159
.. i18n: * workflows,
163
* views, actions, menus,
167
.. i18n: This data is also migrated to a new version if you run --update or --init.
170
This data is also migrated to a new version if you run --update or --init.
179
.. i18n: Workflows are also upgraded automatically. If some activities are removed, the documents states evolves automatically to the preceding activities. That ensure that all documents are always in valid states.
182
Workflows are also upgraded automatically. If some activities are removed, the documents states evolves automatically to the preceding activities. That ensure that all documents are always in valid states.
184
.. i18n: You can freely remove activities in your XML files. If workitems are in this activity, they will evolve to the preceding unlinked activity. And after the activity will be removed.
187
You can freely remove activities in your XML files. If workitems are in this activity, they will evolve to the preceding unlinked activity. And after the activity will be removed.
189
.. i18n: Things to care about during development
190
.. i18n: """""""""""""""""""""""""""""""""""""""
193
Things to care about during development
194
"""""""""""""""""""""""""""""""""""""""
196
.. i18n: Since version 3.0.2 of OpenERP, you can not use twice the same 'id="..."' during resource creation in your XML files, unless they are in two different modules.
199
Since version 3.0.2 of OpenERP, you can not use twice the same 'id="..."' during resource creation in your XML files, unless they are in two different modules.
201
.. i18n: Resources which don't contain an id are created (and updated) only once; at the installation of the module or when you use the --init argument.
204
Resources which don't contain an id are created (and updated) only once; at the installation of the module or when you use the --init argument.
206
.. i18n: If a resource has an id and this resource is not present anymore in the next version of the XML file, OpenERP will automatically remove it from the database. If this resource is still present, OpenERP will update the modifications to this resource.
209
If a resource has an id and this resource is not present anymore in the next version of the XML file, OpenERP will automatically remove it from the database. If this resource is still present, OpenERP will update the modifications to this resource.
211
.. i18n: If you use a new id, the resource will be automatically created at the next update of this module.
214
If you use a new id, the resource will be automatically created at the next update of this module.
216
.. i18n: **Use explicit id declaration !**, Example:
219
**Use explicit id declaration !**, Example:
221
.. i18n: * view_invoice_form,
222
.. i18n: * view_move_line_tree,
223
.. i18n: * action_invoice_form_open, ...
227
* view_move_line_tree,
228
* action_invoice_form_open, ...
230
.. i18n: It is important to put id="...." to all record that are important for the next version migrations. For example, do not forget to put some id="..." on all workflows transitions. This will allows OpenERP to know which transition has been removed and which transition is new or updated.
233
It is important to put id="...." to all record that are important for the next version migrations. For example, do not forget to put some id="..." on all workflows transitions. This will allows OpenERP to know which transition has been removed and which transition is new or updated.
235
.. i18n: Custom modules
236
.. i18n: """"""""""""""
242
.. i18n: For example, if you want to override the view of an object named 'invoice_form' in your xml file (id="invoice_form"). All you have to do is redefine this view in your custom module with the same id. You can prefix ids with the name of the module to reference an id defined in another module.
245
For example, if you want to override the view of an object named 'invoice_form' in your xml file (id="invoice_form"). All you have to do is redefine this view in your custom module with the same id. You can prefix ids with the name of the module to reference an id defined in another module.
252
.. i18n: <record model="ir.ui.view" id="account.invoice_form">
257
<record model="ir.ui.view" id="account.invoice_form">
261
.. i18n: This will override the invoice form view. You do not have to delete the old view, like in 3.0 versions of OpenERP.
264
This will override the invoice form view. You do not have to delete the old view, like in 3.0 versions of OpenERP.
266
.. i18n: Note that it is often better to use view inheritance instead of overwriting views.
269
Note that it is often better to use view inheritance instead of overwriting views.
271
.. i18n: In this migration system, you do not have to delete any resource. The migration system will detect if it is an update or a delete using id="..." attributes. This is important to preserve references duing migrations.
274
In this migration system, you do not have to delete any resource. The migration system will detect if it is an update or a delete using id="..." attributes. This is important to preserve references duing migrations.
283
.. i18n: Demo data do not have to be upgraded; because they are probably modified or
284
.. i18n: deleted by users. So, to avoid demo data to be upgraded, you can put a
285
.. i18n: ``noupdate="1"`` attribute in the ``<data>`` tag of your .xml data files.
288
Demo data do not have to be upgraded; because they are probably modified or
289
deleted by users. So, to avoid demo data to be upgraded, you can put a
290
``noupdate="1"`` attribute in the ``<data>`` tag of your .xml data files.
292
.. i18n: Summary of update and init process
293
.. i18n: ++++++++++++++++++++++++++++++++++
296
Summary of update and init process
297
++++++++++++++++++++++++++++++++++
304
.. i18n: modify/add/delete demo data and built-in data
307
modify/add/delete demo data and built-in data
314
.. i18n: modify/add/delete non demo data
317
modify/add/delete non demo data
319
.. i18n: Examples of built-in (non demo) data:
322
Examples of built-in (non demo) data:
324
.. i18n: * Menu structure,
325
.. i18n: * View definition,
326
.. i18n: * Workflow description, ...
327
.. i18n: * Everything that has an `id` attribute in the XML data declaration (if no attr noupdate="1" in the header)
332
* Workflow description, ...
333
* Everything that has an `id` attribute in the XML data declaration (if no attr noupdate="1" in the header)
335
.. i18n: What's going on during the update process:
338
What's going on during the update process:
340
.. i18n: 1. If you manually added data within the client:
341
.. i18n: * the update process will not change them
342
.. i18n: 2. If you dropped data:
343
.. i18n: * if it was demo data, the update process will do nothing
344
.. i18n: * it it was built-in data (like a view), the update process will recreate it
345
.. i18n: 3. If you modified data (either in the .XML or the client):
346
.. i18n: * if it's demo data: nothing
347
.. i18n: * if it's built-in data, data are updated
348
.. i18n: 4. If built-in data have been deleted in the .XML file:
349
.. i18n: * this data will be deleted in the database.
352
1. If you manually added data within the client:
353
* the update process will not change them
354
2. If you dropped data:
355
* if it was demo data, the update process will do nothing
356
* it it was built-in data (like a view), the update process will recreate it
357
3. If you modified data (either in the .XML or the client):
358
* if it's demo data: nothing
359
* if it's built-in data, data are updated
360
4. If built-in data have been deleted in the .XML file:
361
* this data will be deleted in the database.