[ADD] marketing automation: added 'getting started' section and docs to round out documentation

closes odoo/documentation#3161

X-original-commit: 4f6b03dc5b
Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>

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.
 
+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.
 
-| 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.
+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
-
-
-Out of those 20 records, 25 have become participants, in other words, they have matched the criteria.
-
-
-.. image:: understanding_metrics/metrics3.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: Lead generation filters used to refine records on marketing automation campaigns in Odoo.
 
+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.
 
 .. note::
-   The filter here is applied to *all* activities. Leads that lose the tag in the meantime will be
-   excluded from later activities.
+   :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: Difference between real-time record count and total participants on a markeing campaign.
 
-*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*.
+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 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.
 
-   .. image:: understanding_metrics/metrics4.png
+   (*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/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.

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

@@ -0,0 +1,81 @@
+====================
+Marketing activities
+====================
+
+When creating a campaign in the :guilabel:`Marketing Automation` app, users can plan marketing
+activities such as email or SMS campaigns. To get started, navigate to the :guilabel:`Workflow`
+area, and click :guilabel:`Add New Activity`. A blank activity template will appear where
+parameters can be set for that specific activity.
+
+When :guilabel:`Add New Activity` is selected, a blank activity template will appear with the
+following customizable fields:
+
+.. image:: workflow_activities/activity-template.png
+   :align: center
+   :alt: An activity template in Odoo Marketing Automation.
+
+- :guilabel:`Activity Name`: the title of the activity.
+- :guilabel:`Activity Type`: choose between Email, Server Action (internal Odoo operation), or SMS.
+- :guilabel:`Mail Template`: choose from pre-configured templates (or create a new one on-the-fly).
+- :guilabel:`Trigger`: choose when this activity should be triggered.
+- :guilabel:`Expiry Duration`: configure to stop the actions after a specific amount of time (after
+  the scheduled date). When selected, a :guilabel:`Cancel after` field appears, in which the user
+  can choose how many :guilabel:`Hours, Days, Weeks, or Months` they want the actions to cease
+  after the initial date.
+- :guilabel:`Activity Filter`: domain related to this activity (and all subsequent Child
+  Activities).
+- :guilabel:`Applied Filter`: activity will *only* be performed if it satisfies the specified
+  domain (filter).
+
+After the activity's settings are fully configured, click :guilabel:`Save & Close` to finish
+creating the activity.
+
+Workflow activity
+=================
+
+Once saved, the :guilabel:`Workflow Activity` will appear in Odoo, where each activity will be
+shown as a graph by default. The configured trigger time for that activity can be found to the left
+of the :guilabel:`Workflow Activity` card.
+
+In the :guilabel:`Workflow Activity` section, there is also the number of activities that are
+successful or rejected. The :guilabel:`Success` and :guilabel:`Rejected` numbers are color-coded
+in the graph for easy reference (in green and red, respectively).
+
+.. image:: workflow_activities/workflow-activity.png
+   :align: center
+   :alt: Typical workflow activity in Odoo Marketing Automation.
+
+.. tip::
+   If the :guilabel:`Activity Type` of the activity is set to :guilabel:`Email`, there are more
+   in-depth analytics beneath the :guilabel:`Workflow Activity` data detailing how many emails have
+   been :guilabel:`Sent`, and what percentage of those have been :guilabel:`Clicked`,
+   :guilabel:`Replied` to, or :guilabel:`Bounced`.
+
+Child activities
+================
+
+Odoo also has the option to :guilabel:`Add Child Activity`. *Child Activities* are sub-activities
+that are connected to (and triggered by) the activity above it, which is also known as its *Parent
+Activity*.
+
+Odoo provides a number of triggering options to launch a :guilabel:`Child Activity` - all of which
+depend on the trigger configurations related to the parent activity. Under the desired parent
+activity, hover over :guilabel:`Add child activity`, and select the trigger:
+
+- :guilabel:`Add Another Activity`: instantly add another activity.
+- :guilabel:`Opened`: the next activity will be triggered if the (email) recipient opens the
+  mailing.
+- :guilabel:`Not Opened`: the next activity will be triggered if the recipient does not open the
+  mailing.
+- :guilabel:`Replied`: the next activity will be triggered if the recipient replies to the mailing.
+- :guilabel:`Not Replied`: the next activity will be triggered if the recipient does not reply to
+  the mailing.
+- :guilabel:`Clicked`: the next activity will be triggered if the recipient clicks on a link
+  included in the mailing.
+- :guilabel:`Not Clicked`: the next activity will be triggered if the recipient does not click on a
+  link included in the mailing.
+- :guilabel:`Bounced`: the next activity will be triggered if the mailing is bounced (not sent).
+
+Once a trigger is selected, the user can configure the child activity (it has the same
+configuration options as a regular activity) and click :guilabel:`Save & Close`` to finish creating
+the child activity.