[FW][ADD] marketing automation: added 'getting started' section and docs …

content/applications/marketing/marketing_automation.rst

@@ -13,4 +13,5 @@ Marketing Automation
 .. toctree::
    :titlesonly:
 
+   marketing_automation/getting_started
    marketing_automation/advanced

content/applications/marketing/marketing_automation/advanced/understanding_metrics.rst

@@ -1,76 +1,80 @@
 =====================
-Understanding Metrics
+Understanding metrics
 =====================
-Metrics are values that help you measure progress and can be a powerful way of linking your
-employees to goals.
 
+Metrics are detailed statistics that measure the progress (and success) of marketing campaigns.
+When creating marketing activities in a workflow, Odoo will visually display various metrics
+related to the campaign with graphs and data.
 
-| When you create a workflow in Odoo, its visual content already shows metrics in a graph form and
-  in numbers.
-| Let’s consider the example below:
+Consider the following example:
 
-
-.. image:: understanding_metrics/metrics1.png
+.. image:: understanding_metrics/commercial-prospection-campaign-example.png
    :align: center
-   :alt: Metrics in Odoo Marketing Automation
-
+   :alt: An example of a marketing automation campaign in Odoo.
 
-| The *Target* - business object - is *Lead/Opportunity* and was narrowed down to the ones whose
-  *Tag Name* contain the description “Product”, and have an email address set.
-| A total number of 20 records match the criteria.
+In this case, the :guilabel:`Target` of this campaign is set to :guilabel:`Lead/Opportunity` and
+was narrowed down to only focus on the Leads (or Opportunities) whose :guilabel:`Tag Name` contain
+a value of `product` and they *also* have an email address set up in the database.
 
+Beneath the filter nodes, Odoo will display how many records in the database fall into the
+previously-specified criteria filter. In this example, there are 18 records in the database that
+match the criteria.
 
-.. image:: understanding_metrics/metrics2.png
+.. image:: understanding_metrics/marketing-automation-lead-filters.png
    :align: center
-   :alt: Metrics in Odoo Marketing Automation
-
+   :alt: Lead generation filters used to refine records on marketing automation campaigns in Odoo.
 
-Out of those 20 records, 25 have become participants, in other words, they have matched the criteria.
+At the top of the marketing automation form, there are a series of smart buttons. The
+:guilabel:`Participations` smart button in this example indicates that, out of those 18 records, 25
+have become participants. In other words, they have matched the criteria, and have already
+interacted with the campaign in one way or another.
 
-
-.. image:: understanding_metrics/metrics3.png
+.. note::
+   :guilabel:`Records` represent a real-time number. Therefore, while the workflow is running,
+   changes in opportunity records (deletions, additions, adjustments) may occur. This means there
+   will be real-time updates to the number of :guilabel:`Records`, but such updates do *not* change
+   the number of :guilabel:`Participants`, as the metric *will not* exclude opportunities that have
+   already been set as :guilabel:`Participants` before - Odoo will just add new ones. That's why
+   the number of :guilabel:`Records` can be different from the number of :guilabel:`Participants`
+   from time to time.
+
+.. image:: understanding_metrics/campaign-records-vs-participants.png
    :align: center
-   :alt: Metrics in Odoo Marketing Automation
-
-
-Every time the system runs, updating numbers and triggering actions, it will look at the *Target*
-model and check if new records have been added or modified, keeping the flow up-to-date.
+   :alt: Difference between real-time record count and total participants on a markeing campaign.
 
+Whenever the system runs, updating numbers and triggering actions, it will look at the
+:guilabel:`Target` model, and check if new :guilabel:`Records` have been added (or modified),
+which always keeps the flow up-to-date.
 
 .. note::
-   The filter here is applied to *all* activities. Leads that lose the tag in the meantime will be
-   excluded from later activities.
-
-
-*Records* is a real-time number, therefore while the workflow is running, changes in opportunity
-records can be made - delete, add, adjustment - updating the number of records, but not changing the
-number of participants, as the metric *will not* exclude opportunities that have been set as
-participants before. It will just add new ones. For this reason, the number of *Records* can be
-different from the number of *Participants*.
-
+   The filter here is applied to *all* activities. Leads that lose that specific :guilabel:`Tag`
+   in the meantime will be excluded from later activities.
 
 .. tip::
-   | You can also have filters applied to activities individually, under *Domain*. A useful feature
-     to specify an individual filter that will only be performed if the records satisfied both
-     filters, the activity and its domain one.
-   | Example: for an activity sending an SMS, you could make sure a phone number is set to
-     avoid triggering a SMS that would never be sent and crash.
+   Filters can also be applied to individual activities, in the :guilabel:`Domain` section of the
+   activity pop-up form. Use this feature to specify an individual filter that will only be
+   performed if the records satisfy *both* filter criteria - the activity filter and its specific
+   domain filter.
+
+   (*Example*: when configuring an SMS activity, make sure a certain phone number is set,
+   in order to avoid triggering a SMS that would never be sent.)
 
-   .. image:: understanding_metrics/metrics4.png
+   .. image:: understanding_metrics/individual-filter-to-activity.png
       :align: center
-      :alt: Metrics in Odoo Marketing Automation
+      :alt: A relevant targeting filter that applies to a type of individual activity.
 
-| *Success* is the number of times the searching for participants - that match the filter(s) of that
-  activity - was performed successfully in relation to the total number of participants.
-| If a participant does not match the conditions, it will be added to *Rejected*.
+:guilabel:`Success` represents the number of times the searching for participants - who match the
+criteria filter(s) of that activity - was performed successfully, in relation to the total number
+of participants. If a participant does *not* match the conditions, it will be added to
+:guilabel:`Rejected`.
 
-.. image:: understanding_metrics/metrics5.png
+.. image:: understanding_metrics/participant-matching-success-vs-rejected.png
    :align: center
-   :alt: Metrics in Odoo Marketing Automation
+   :alt: Overview showing participants who do or do not match filtering criteria on an activity.
 
-Hovering over the graph, you can see the number of successful and rejected participants, per day,
-for the last 15 days.
+Hovering over the graph, Odoo displays the number of successful and rejected participants, per day,
+over the last 15 days.
 
 .. note::
-   Every time a new record is added to the *Target* model, it will be automatically added to the
-   workflow, and, it will start the workflow from the beginning (parent action).
+   Whenever a new record is added to the :guilabel:`Target` model, it will automatically be added
+   to the workflow, and it will start the workflow from the beginning (:guilabel:`Parent Action`).

content/applications/marketing/marketing_automation/getting_started.rst

@@ -0,0 +1,13 @@
+:nosearch:
+
+===============
+Getting Started
+===============
+
+.. toctree::
+   :titlesonly:
+
+   getting_started/first_campaign
+   getting_started/target_audience
+   getting_started/workflow_activities
+   getting_started/testing_running

content/applications/marketing/marketing_automation/getting_started/first_campaign.rst

@@ -0,0 +1,59 @@
+====================
+Marketing Automation
+====================
+
+The Odoo Marketing Automation app automates a variety of marketing tasks by combining specific
+rules and filters to generate timed actions. Instead of manually having to build each stage of a
+campaign (such as a series of timed massmails), the Marketing Automation app allows marketers to
+build the entire campaign, and all of its stages, in one place on one dashboard.
+
+Create a campaign
+=================
+
+To create a new automated marketing campaign, open the :guilabel:`Marketing Automation` app and
+click :guilabel:`Create`. On the :guilabel:`Campaign` page, there are the following smart buttons
+and fields:
+
+.. image:: first_campaign/marketing-template-sample.png
+   :align: center
+   :alt: A dashboard showing the creation of a new marketing automation campaign in Odoo.
+
+- :guilabel:`Templates`: represents the number of pre-configured mail templates being used in this
+  particular campaign. (Templates can always be created on-the-fly as well).
+- :guilabel:`SMS`: represents the number of personalized SMS messages connected to this campaign.
+- :guilabel:`Clicks`: represents the number of times attached links have been clicked by recipients
+  of this campaign.
+- :guilabel:`Participants`: represents the number of contacts that have directly participated in
+  this campaign.
+- :guilabel:`Target`: this field is a drop-down menu to choose which model is targeted by this
+  campaign (i.e., by Contacts, Sales Order, Lead/Opportunity, etc.).
+
+Campaign filters
+================
+
+To add a filter to the target audience, click :guilabel:`Add Filter`, and a node field will
+appear. In the node field, a custom equation can be configured for Odoo to use when filtering who
+to include (and exclude) in this specific marketing campaign.
+
+.. image:: first_campaign/filter-node.png
+   :align: center
+   :alt: A filter node in Odoo Marketing Automation.
+
+When the first field of the node is clicked, a nested drop-down menu of options appears on the
+screen where specific criteria is chosen based on needs of the campaign. The remaining fields on
+the node further define the criteria which determines which records to include (or exclude) in the
+execution of the campaign.
+
+To add another node, simply click the :guilabel:`+ (plus sign)` icon to the right of the filtering
+rule. To add a branch of multiple nodes at the same time, click the :guilabel:`... (ellipses)`
+icon.
+
+For further information on filters, refer to :doc:`this documentation page <target_audience>`.
+
+.. note::
+   :guilabel:`Records` represent the number of contacts in the system that fit the specified
+   criteria for a campaign.
+
+.. seealso::
+   - :doc:`testing_running`
+   - :doc:`workflow_activities`

content/applications/marketing/marketing_automation/getting_started/target_audience.rst

@@ -0,0 +1,121 @@
+==================
+Target an audience
+==================
+
+Delivering marketing campaigns to the *right* audience is paramount when trying to grow a business.
+The :guilabel:`Odoo Marketing Automation` application helps marketers to do just that by providing
+filtering tools, that can be as simple or as complex as necessary, to reach the right customers at
+the right time.
+
+Work with target filters
+========================
+
+When configuring the filters on a marketing campaign, there are some options that have an arrow
+icon beside them. The arrow signifies that the filter has more refined parameters within it.
+
+.. image:: target_audience/marketing-filters.png
+   :align: center
+   :alt: The drop-down filter menu in the Marketing Automation application.
+
+Filters can be extended by adding *branches* and *nodes*. A *node* adds another filtering parameter
+to a group of targeting conditions (e.g. a new line), and a *branch* creates a narrowly refined
+cluster of parameters, allowing filters to be grouped with *Any* or *All* statements.
+
+Every time a new branch is created, there are two options:
+
+- Either the records can match :guilabel:`ALL` criteria for the upcoming rules (an AND statement
+  where all criteria must match).
+
+- Or, the records can match :guilabel:`ANY` criteria for the upcoming rules (an OR statement where
+  only one of the criteria must match).
+
+To change between these two options, simply click the drop-down arrow icon in the green box and
+select :guilabel:`Any` or :guilabel:`All`.
+
+To add a node, click on the :guilabel:`+ (plus sign icon)` and to add another branch click on the
+:guilabel:`... (ellipses icon)`. To exclude a :guilabel:`node` (or a :guilabel:`branch`), click on
+:guilabel:`x (delete)`.
+
+.. image:: target_audience/marketing-filter-nodes.png
+   :align: center
+   :alt: The drop-down filter menu in the Marketing Automation application.
+
+Use cases
+=========
+
+The following scenarios below outline different combinations of filters a marketing campaign might
+commonly use.
+
+Scenario #1: Narrow the target down to new opportunities in the pipeline
+------------------------------------------------------------------------
+
+While in Edit mode on a campaign template form, select the :guilabel:`Target` field, and click
+:guilabel:`Search More` from the drop-down menu. Then, search for :guilabel:`Lead/Opportunity` and
+select it.
+
+Next, click :guilabel:`Add Filter` in the :guilabel:`Filter` field. Click on the default
+:guilabel:`ID` filter option in the first portion of the filter equation. Doing so reveals a
+drop-down menu full of filter options. From this drop-down, scroll down (or search for)
+:guilabel:`Type`.
+
+Keep the second portion of the filter equation on the default :guilabel:`= (equal sign)`.
+
+Then, change the third (and final) portion of the filter equation from :guilabel:`Lead` to
+:guilabel:`Opportunity`. The number of :guilabel:`Records` that fit this specific filter equation
+will change as the equation is customized.
+
+Add another node to this filter by clicking the :guilabel:`+ (plus sign)` to the right of the
+equation.
+
+With "new" opportunities being the target of this filter, the second node will focus on only
+locating opportunities that are in the :guilabel:`New` stage of the pipeline. To do that, select
+the default :guilabel:`ID` from the first portion of the second filter equation, and scroll down
+(or search for) :guilabel:`Stage` from the field drop-down menu.
+
+Once again, leave the second portion of the filter equation on :guilabel:`= (equal sign)`.
+
+Lastly, highlight the default value in the third (and final) portion of the second filter equation
+and type in :guilabel:`New`. With that completed, Odoo will only target opportunities that are in
+the "New" stage of the pipeline.
+
+.. image:: target_audience/filters-opportunities.png
+   :align: center
+   :alt: A standard scenario using filters in the Odoo Marketing Automation app.
+
+Scenario #2: Narrow the target down to the event attendees that purchased a specific ticket
+-------------------------------------------------------------------------------------------
+
+While in Edit mode on a campaign template form, select the :guilabel:`Target` field, and click
+:guilabel:`Search More` from the drop-down menu. Then, scroll down (or search for)
+:guilabel:`Event` and select it.
+
+Next, click :guilabel:`Add Filter` in the :guilabel:`Filter` field. Click on the default
+:guilabel:`ID` filter option in the first portion of the filter equation. Doing so reveals a
+drop-down menu full of filter options. From this drop-down, scroll down (or search for)
+:guilabel:`Event`.
+
+Click the the default :guilabel:`= (equal sign)` in the second portion of the filter equation.
+This reveals a drop-down menu. On this menu, select :guilabel:`contains`.
+
+In the third (and final) empty portion of the filter equation, type in the name of the event(s)
+that you would like Odoo to consider for this campaign filter.
+
+Add another node to this filter by clicking the :guilabel:`+ (plus sign)` to the right of the
+equation.
+
+The second node will focus on targeting this campaign to attendees who purchase a specific type of
+ticket to the aforementioned event(s) in the first filter equation. To do that, select the default
+:guilabel:`ID` from the first portion of the second filter equation, and scroll down (or search
+for) :guilabel:`Event Ticket` from the field drop-down menu. Then, in that same drop-down menu,
+select :guilabel:`Name`.
+
+Once again, click the the default :guilabel:`= (equal sign)` in the second portion of the filter
+equation, and select :guilabel:`contains`.
+
+Lastly, in the third (and final) portion of the second filter equation, which will be blank, type
+in the name of the ticket type that should be used for the filter. In this case,
+:guilabel:`Standard` is the name of the event ticket type for this sample filter.
+
+.. image:: target_audience/filters-event-ticket.png
+   :align: center
+   :alt: An event ticket filter in the Odoo Marketing Automation application.

content/applications/marketing/marketing_automation/getting_started/testing_running.rst

@@ -0,0 +1,41 @@
+==============================
+Testing and running a campaign
+==============================
+
+Odoo gives users the ability to test marketing campaigns (and mailings) before officially running
+them.
+
+First, open the :guilabel:`Marketing Automation` application and click on a campaign. Make sure
+the campaign already has activities configured on it (or build a campaign by following the
+directions here on :doc:`this documentation <workflow_activities>`). To start a test, click the
+:guilabel:`Launch a Test` button at the top of the template form.
+
+.. image:: testing_running/launch-test.png
+   :align: center
+   :alt: Launch a test button in Odoo Marketing Automation.
+
+When clicked, a pop-up window appears. In the dropdown field choose a specific record to run the
+test on, or create a brand new record by clicking the :guilabel:`Search More...` link at the bottom
+of the dropdown menu, and then click the :guilabel:`Create` button.
+
+Once the record is selected, click :guilabel:`Continue`, and Odoo will redirect to the campaign
+test page.
+
+.. image:: testing_running/test-screen.png
+   :align: center
+   :alt: Test screen in Odoo Marketing Automation.
+
+Here, the name of the :guilabel:`Record` being tested is visible, along with the precise time this
+test workflow was started. Beneath that is the first activity (or activities) in the workflow.
+
+To start a test, click the :guilabel:`Run` icon beside the first activity in the workflow. When
+clicked, the page will reload, and Odoo will show the various results (and analytics) connected to
+that specific activity.
+
+.. image:: testing_running/workflow-test-progress.png
+   :align: center
+   :alt: Workflow test progress in Odoo Marketing Automation.
+
+Once all the workflow activities are completed, the test will end and be moved to the
+:guilabel:`Completed` stage. To stop a test before all the workflow activities are completed, click
+the :guilabel:`Stop` button.