[ADD] studio: documentation (#657)

applications.rst

@@ -77,4 +77,5 @@ Applications
    events
    survey
    expense/expense
-   mobile/firebase
+   studio
+   mobile/firebase

studio.rst

@@ -0,0 +1,11 @@
+:banner: banners/studio.png
+
+======
+Studio
+======
+
+.. toctree::
+   :titlesonly:
+
+   studio/concepts
+   studio/use_cases

studio/concepts.rst

@@ -0,0 +1,9 @@
+========
+Concepts
+========
+
+.. toctree::
+   :titlesonly:
+
+   concepts/understanding_general
+   concepts/understanding_automated_actions

studio/concepts/understanding_automated_actions.rst

@@ -0,0 +1,80 @@
+===============================
+Understanding Automated Actions
+===============================
+
+| Automated actions are used to trigger actions. They are based on conditions and happen on top of
+  Odoo’s default business logic.
+| Examples of automated actions include: creating a next activity upon a quote's confirmation;
+  adding a user as a follower of a confirmed invoice if its total is higher than a
+  certain amount; or preventing a lead from changing stage if a field is not filled in.
+
+.. image:: media/automated_action_flow.png
+   :align: center
+   :height: 270
+   :alt: Flowchart to exemplify an automated action rule for Odoo Studio
+
+| Let's understand how to properly define *when* an automated action runs and *how* to create one:
+| The first step is to choose the :doc:`Model <understanding_general>` on which the action is
+  applied.
+| The **Trigger** field defines the event that causes the automated action to happen:
+
+- *On Creation*: when a new record is created. Note that the record is created once saved for the
+  first time.
+- *On Update*: when the record is updated. Note that the update happens once the record is saved.
+- *On Creation & Update*: on the creation and/or on the update of a record once the form is saved.
+- *On Deletion*: on the removal of a record under the condition set.
+- *Based on Form Modification*: when the value of the specified *Trigger* field is changed in the
+  interface (user sees the changes before saving the record). Note that this action can only be used
+  with the *Execute Python Code* action type.
+- *Based on Timed Condition*: a delay happens after a specific date/time. Set a *Delay after trigger
+  date* if you need a delay to happen before the *Trigger Date*. Example: to send a reminder 15min
+  before a meeting. If the date/time is not set on the form of the model chosen, the date/time
+  considered is the one of the creation/update of the record.
+
+For every Trigger option, **conditions** can be applied, such as:
+
+- *Before Update Domain*: if designated, this condition must be satisfied before the record is
+  updated.
+- *Apply on*: if designated, this condition must be satisfied before executing the action rule
+  (*Action To Do*), and after the update.
+
+| The **Active** option is to be turned off when the rule should be hidden and not executed.
+| Under **Action To Do** choose the type of server action that must be executed once records meet
+  the *Trigger* conditions:
+
+- *Execute Python Code*: a block of code is executed. A *Help* tab with the variables that can be
+  used is available.
+- *Create New Record*: a new record with new values is created.
+- *Update a Record*: updates the record that triggered the action.
+- *Execute several actions*: defines an action that triggers other server actions.
+- *Send Email*: an automatic :doc:`email <../../discuss/advanced/emailtemplate>` is sent.
+- *Add Followers*: :doc:`followers <../../project/tasks/collaborate>` are notified of changes in
+  the task.
+- *Create Next Activity*: creates an activity such as: *Call*, *Email*, *Reminder*.
+- *Send SMS Text Message*: sends an :doc:`SMS <../../sms_marketing/pricing/pricing_and_faq>`.
+
+Example
+~~~~~~~
+
+This is the process of which the update of the *Email* field on the Lead/Opportunity *Model*, with a
+*Trigger Condition* set to *On Update*, goes through:
+
+.. image:: media/action_update_lead_example.png
+   :align: center
+   :alt: View of an automated action being created in Odoo Studio
+
+#. The user creates the record without an email address set.
+#. The user updates the record defining an email address.
+#. Once the change is saved, the automation checks if any of the *Watched Fields* are being updated
+   (for the example: field name *email_from* (Email).
+#. If true, it checks if the record matches the *Before Update Domain* (for the example: *email
+   is not set*).
+#. If true, it checks (*after the update*) whether the record matches the *Apply on* domain (for the
+   example: *email is set*).
+#. If true, the chosen *Action To Do* is performed on the record.
+
+.. seealso::
+   - :doc:`understanding_general`
+   - :doc:`../use_cases/automated_actions`
+
+

studio/concepts/understanding_general.rst

@@ -0,0 +1,95 @@
+==============================
+Understanding General Concepts
+==============================
+
+| Odoo Studio is a toolbox that allows you to add models or adapt functionalities on top of Odoo’s
+  standard behavior without coding knowledge. You can also create custom views and modify existing
+  ones without having to get into the XML code.
+| Even for experienced developers, typing out code requires time. By using Odoo Studio, you can
+  quickly get your models up and going and focus on the crucial parts of your application. The
+  result is a user-friendly solution that makes customizations and designing new applications easy
+  with or without programming skills.
+
+
+Getting started
+===============
+
+One you start using Odoo Studio, you automatically create a new *module* that contains all your
+modifications. These modifications can be done on existing screens (*views*), by adding new
+*fields* in existing applications, or by creating an entirely new *model*.
+
+What is a Module?
+-----------------
+
+| An Odoo **Module** can contain a number of elements, such as: business objects (models), object
+  views, data files, web controllers, and static web data. An application is a collection of modules.
+| In object-oriented programming, models usually represent a concept from the real world.
+  Example: Odoo has models for Sales Orders, Users, Countries, etc. If you were to build an
+  application to manage Real Estate sales, a model that represents the Properties for sale would
+  probably be your first step.
+
+.. image:: media/new_app.png
+   :align: center
+   :alt: Overview of the main dashboard emphasizing the option to create a new app in Odoo Studio
+
+.. _studio/concepts/understanding_general/models:
+
+What is a Model (also called Object)?
+-------------------------------------
+
+A **Model** determines the logical structure of a database and fundamentally determines in which
+manner data can be stored, organized, and manipulated. In other words, a model is a table of
+information that can be bridged with other tables.
+
+What are Fields?
+----------------
+
+| **Fields** compose models. It is where a record (a piece of data) is registered.
+| Example: on the Real Estate application, fields on the Properties model would include
+  the price, address, a picture, a link to the current owner, etc.
+| There are 2 main types of fields in Odoo: *basic (or scalar) fields* and *relational fields*.
+| Basic fields represent simple values, like numbers or text. Relational fields represent relations
+  between models. So, if you have a model for *Customers* and another one for *Properties*, you
+  would use a relational field to link each Property to its Customer.
+
+Relational Fields in detail
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| **Relational Fields** provide the option to link the data of one model with the data of another
+  model.
+| In Odoo, relational field types are: *One2many*, *Many2one*, *Many2many*.
+
+.. image:: media/relational_fields.png
+   :align: center
+   :alt: Tables with a visual explanation of related fields for Odoo Studio
+
+| An **One2many** field is a *one-way* direction of selecting *multiple* records from a table.
+| Example: a Sales Order can contain multiple Sales Order Lines, which also contain multiple fields
+  of information.
+| A **Many2one** field is a *one-way* direction of selecting *one* record from a table.
+| Example: you can have many product categories, but each product can only belong to one category.
+| A **Many2many** field is a *two-way* direction of selecting records from a table.
+| Example: multiple tags can be added to a lead’s form.
+
+.. note::
+   An *One2many* field must have a *Many2one* related to it.
+
+What are Views?
+---------------
+
+**Views** define how records are displayed. They are specified in XML which means that they can be
+edited independently from the models that they represent. There are various types of views in Odoo,
+and each of them represents a mode of visualization. Some examples are: *form*, *list*, *kanban*.
+
+What is a Menu?
+---------------
+
+A **Menu** is a button that executes and action. In Odoo Studio, to create menus (models) and
+rearrange their hierarchy, click on *Edit Menu*.
+
+.. image:: media/edit_menu.png
+   :align: center
+   :alt: Overview of a menu being edit in Odoo Studio
+
+.. seealso::
+   - `Studio Basics <https://www.odoo.com/fr_FR/slides/studio-31>`_

studio/use_cases.rst

@@ -0,0 +1,11 @@
+=========
+Use Cases
+=========
+
+.. toctree::
+   :titlesonly:
+
+   use_cases/models_fields
+   use_cases/filters_status_bar
+   use_cases/automated_actions
+   use_cases/views

studio/use_cases/automated_actions.rst

@@ -0,0 +1,26 @@
+=====================================
+Advanced Use Cases: Automated Actions
+=====================================
+
+- **Case scenario 1: when a Belgian lead is created, a 3-stars priority should be automatically
+  applied.**
+
+Under *Automations*,  click on *Create* and set the following rules:
+
+- *Model*: Lead/Opportunity
+- *Active*: On
+- *Trigger*: On Creation & Update
+- *Apply on*: Country > Country Name = Belgium
+- *Action To Do*: Update the Record
+- *Data to Write*: Lead/Opportunity > Value > 3
+
+.. image:: media/automated_actions/hight_priority_leads.png
+   :align: center
+   :alt: View of an automated action that sets a high priority to Belgian leads in Odoo Studio
+
+.. tip::
+   Check :doc:`this doc <filters_status_bar>` in order to have another automated action example.
+
+.. seealso::
+   - :doc:`../concepts/understanding_automated_actions`
+   - :doc:`../concepts/understanding_general`

studio/use_cases/filters_status_bar.rst

@@ -0,0 +1,61 @@
+==========================================
+Advanced Use Cases: Filters and Status Bar
+==========================================
+
+- **Case scenario 1: on Sales, set a filter on Belgian customers and define it as the default one
+  (the user should still be able to unset the filter).**
+
+On your customer’s page, use *Filters* > *Add Custom Filter* to group customers by country. Now,
+under *Favorites*, *Save Current Search* enabling *Use by default* and *Save*.
+
+.. image:: media/filters_status_bar/customer_filter.png
+   :align: center
+   :alt: View of a custom filter being set to be used by default in Odoo
+
+On *Filter Rules* in Studio mode, select the respective filter and enable *Default Filter*.
+
+.. image:: media/filters_status_bar/sales_default_filter.png
+   :align: center
+   :alt: View of a filter’s rule form emphasizing the field default filter in Odoo Studio
+
+- **Case scenario 2: add a status bar on the product form to manage its life cycle. Set the values:
+  ‘Prototype’, ‘In use’ and ‘Deprecated’. By default, the Kanban view must be grouped by status.**
+
+| On your product form, *Add a pipeline status bar* and name its values. Status bars are *selection*
+  fields that give you the ability to follow a specific flow. They are useful to show you the
+  progress that has been made.
+| On the *Views* menu, access *Kanban* and, under its *View* options, set the *Default Group by* as
+  *Pipeline status bar*.
+
+.. image:: media/filters_status_bar/add_pipeline.png
+   :align: center
+   :alt: Form view emphasizing the button add a pipeline bar in Odoo Studio
+
+Now, open your product form and set the right status for that product. As you move products
+throughout stages (also through the product’s form), stages are shown in the Kanban view.
+
+.. tip::
+   To make modifications in the pipeline status bar, for example, remember to go back to *Form View*.
+
+   .. image:: media/filters_status_bar/form_view.png
+      :align: center
+      :alt: View of Studio emphasizing the form view button in Odoo Studio
+
+- **Case scenario 2.a: when a product goes from ‘In use’ to ‘Deprecate’, set its cost to 0€.**
+
+Create an :doc:`automated action <../concepts/understanding_automated_actions>` with the selected
+values:
+
+- *Model*: Product Template
+- *Trigger*: On Update
+- *First Domain*: Pipeline status bar = In use
+- *Second Domain*: Pipeline status bar = Deprecated
+- *Action To Do*: Update the Record
+- *Data to Write*: Cost (Product Template) > Value > 0
+
+.. image:: media/filters_status_bar/automations_zero_price.png
+   :align: center
+   :alt: View of the automated action created to set the price of a product to zero in Odoo Studio
+
+.. seealso::
+   - :doc:`../concepts/understanding_general`

studio/use_cases/models_fields.rst

@@ -0,0 +1,139 @@
+=====================================================
+Advanced Use Cases: Creating Models and Adding Fields
+=====================================================
+
+- **Case scenario 1: on the leads’ form, if the chosen country is France, show a field
+  'Pay by check?'**
+
+| On your leads’ form, add a *Related Field* to *Country > Country Name*.
+| Now, add a *Checkbox* field and define its invisibility options as *Country* (carefully select
+  the one just created) *> is not = > France.*
+| You can now hide the related field created (*Country*) if you wish.
+
+.. image:: media/models_fields/invisible_domain.png
+   :align: center
+   :alt: View of the invisibility domain of a field being set in Odoo Studio
+
+| Another approach is to use the country’s ID. To do so, go to
+  :menuselection:`Contacts --> Configuration --> Countries`, select France (for example), and on the
+  URL check its *ID*.
+| The related field invisibility path should now be *Country* (carefully select the one just
+  created) *> is not = > 75*.
+| Again, hide the related field with the country’s ID if you prefer.
+
+.. image:: media/models_fields/url_id.png
+   :align: center
+   :alt: View of an URL emphasizing where a country’s ID can be found for Odoo Studio
+
+- **Case scenario 2: create a model called 'Properties' and add fields called: company, value, name,
+  address, active, image.**
+
+From the dashboard, (optionally) start a new module. Then, click on *Edit Menu* and start a
+*New Menu* (model). Set your menu name and *Confirm*. Now, on its form, drag & drop the necessary
+fields.
+
+.. image:: media/models_fields/new_menu.png
+   :align: center
+   :alt: View of the recommended fields for an object in Odoo Studio
+
+- **Case scenario 2.a: now, you would like to have a model called 'Regions' to which each property
+  must be linked. And, on 'Regions', you would like to see the properties for each region.**
+
+| Go to *Edit Menu > New Menu* and create your menu, calling it *Regions*. Add the necessary fields
+  on its form by dragging & dropping them.
+| Now, in the form view of *Properties*, add a *Many2one* field with a relation to your model
+  *Region*.
+
+.. tip::
+   The *Existing Fields* are the ones that are on the current model but not yet in the view.
+
+   .. image:: media/models_fields/new_existing_fields.png
+      :align: center
+      :height: 420
+      :alt: Form view and a Many2one field being dropped in Odoo Studio
+
+.. image:: media/models_fields/real_estate_many2one.png
+   :align: center
+   :alt: Form view and a Many2one field being dropped in Odoo Studio
+
+| Now, go to the model *Regions*, select the form view, and add a status button selecting *Regions
+  (Properties)* as your relational field.
+| *Status buttons* are computed fields, meaning that they count the numbers of records on the
+  related model, and allow you to access them.
+
+.. image:: media/models_fields/add_button.png
+   :align: center
+   :alt: Form view and the status button window being shown in Odoo Studio
+
+.. tip::
+   When searching for relations, click on *Search more* and filter it by *Custom*. This way you
+   avoid creating duplicates.
+
+   .. image:: media/models_fields/search_model_custom.png
+      :align: center
+      :alt: View of the search model window in Odoo Studio
+
+- **Case scenario 2.b: in the model 'Properties', show all the tags as checkboxes instead of tags.**
+
+Once the field *Tags* is added to the form, select it and, under its *Properties > Widgets*, choose
+*Checkboxes*.
+
+.. image:: media/models_fields/widget.png
+   :align: center
+   :alt: Form view showing the widgets available in Odoo Studio
+
+- **Case scenario 3: on the leads’ form, add a selection field with the values:'Tags' & 'List' &
+  'Checkboxes'. According to the value of the field, show tags as many2many_tags, many2many_radio,
+  or many2many(_list).**
+
+In your form view, add a *Tags* field and relate it to *Partners Tag*. Under *Properties*, define
+its *Widget* as *Many2many*. Do the same process another 2 times for *Checkboxes* and *Tags*.
+
+.. image:: media/models_fields/widget_checkboxes.png
+   :align: center
+   :alt: Form view emphasizing the widget property in Odoo Studio
+
+| Now, add a *Selection* field and the necessary values.
+| Continue by selecting your *Tags* fields, one by one, to set their *Invisible* options according
+  to their *Widget*. In the example below, the invisibility rule for the *Partner Tags* is set as:
+  *Select Tag type > is not = > Tags.*
+
+.. image:: media/models_fields/domain_select_tag_type.png
+   :align: center
+   :alt: Form view emphasizing a field added and its invisibility properties in Odoo Studio
+
+- **Case scenario 4: on a quotation’s form, add a selection field called 'Manager Validation' with
+  the values: ‘Accepted’ and ‘Refused’. Only a sales manager can see it, and the field should be
+  set as mandatory if the untaxed amount is higher than 500€.**
+
+On your quotation form, add a *Selection* field with the values *Accepted* and *Refused*. Set its
+*Required* condition as *Untaxed Amount > 500* and the *Limit visibility to groups* as *Sales /
+Administrator* or managers.
+
+.. image:: media/models_fields/domain_higher_500.png
+   :align: center
+   :alt: Form view of a required domain being set in Odoo Studio
+
+- **Case scenario 5: change the tooltip of a field for all views.**
+
+| Activate the :doc:`Developer mode <../../general/developer_mode/activate>` and open Studio.
+| Select the necessary field and, under *Properties*, click on *More* to write your tooltip message
+  on *Field Help*. The tooltip message is the explanatory message shown when the user hovers the
+  field. The message here written is displayed on all views forms where the field is added.
+
+.. image:: media/models_fields/field_help.png
+   :align: center
+   :alt: Form view showing more property options and emphasizing the help feature in Odoo Studio
+
+.. note::
+   The *Field Help* message can only be applied to *new* fields. If you would like to change/apply a
+   tooltip for a specific field, use the *Help Tooltip* option under *Properties*.
+
+   .. image:: media/models_fields/help_tooltip.png
+      :align: center
+      :height: 350
+      :alt: View of the properties emphasizing the help tooltip option in Odoo Studio
+
+.. seealso::
+   - :doc:`../concepts/understanding_general`
+

studio/use_cases/views.rst

@@ -0,0 +1,28 @@
+=========================
+Advanced Use Cases: Views
+=========================
+
+- **Case Scenario 1: in Sales, show orders in a Kanban View instead of a List View.**
+
+From the Sales page, access Studio and, under *Views*, set the *Kanban* option as the default one.
+
+.. image:: media/views/kanban_default.png
+   :align: center
+   :height: 380
+   :alt: View of the Kanban option being set as the default one in Odoo Studio
+
+- **Case scenario 2: allow for the list of leads to be edited inline without having to switch to
+  the form view.**
+
+| On the *List View*, under *View* > *Editable*, choose between *New record on top* or *New record
+  at the bottom*. This way, besides defining the order in which new records are displayed in the
+  view, you are able to edit them.
+| If the field is left blank, no editing is possible and records are shown based on your column
+  preferences on the lead's page (front-end).
+
+.. image:: media/views/view_editable.png
+   :align: center
+   :alt: View options emphasizing the editable options of a leads page in Odoo Studio
+
+.. seealso::
+   - :doc:`../concepts/understanding_general`