Merge pull request #616 from adiati98/cherry-pick-349-b71

Cherry-pick: "feat: Add documentation for new segment building status " to 7.1

Author: RCheesley

docs/segments/images/contact_segments.png

@@ -1,22 +1,19 @@
-.. vale off
-
 Managing Segments
 #################
 
-.. vale on
-
-Segments in Mautic are lists or groups of Contacts. Use Segments to send Emails, trigger Campaigns, or for analysis. You can add and remove Contacts into *static* and *dynamic* Segment types.
+Segments in Mautic are lists or groups of Contacts. Use Segments to send Emails, trigger Campaigns, or for analysis. You can add and remove Contacts from **static** and **dynamic** Segment types.
 
 Segments provide ways to easily organize your Contacts. There are a variety of fields available for configuring these Segments.
 
-When viewing all Segments, the **# contacts** column on the right shows the number of Contacts included in that particular Segment.
+.. vale off
 
-.. image:: images/contact-segment.png
-  :width: 700
-  :alt: Screenshot showing Contacts matching that particular Segment.
+When viewing all Segments, the **# contacts** column shows the number of Contacts included in each specific Segment. The **Building** or **Building (X Contacts)** label appears during the creation of a new Segment or when modifying an existing Segment's filter and remains visible until the building process completes.
 
-.. note::
-  Mautic renamed ``lead lists`` to ``Segments`` in Mautic :xref:`1.4.0 release`.
+.. vale on
+
+.. image:: images/contact_segments.png
+   :width: 700
+   :alt: Highlight Segments' Contacts column that consists of Contacts count and building labels
 
 .. vale off
 
@@ -26,7 +23,7 @@ Creating a Segment
 .. vale on
 
 1. To create a new Segment, navigate to Segments in the menu, and click the **+New** button.
-   
+
 2. In the **Details** tab, add a **Name**, **Public name** and **Description** to your Segment.
 
 .. image:: images/create-segment.png
@@ -43,8 +40,6 @@ On the Details tab, static, and dynamic Segments also have the option to display
 
 * **Public name** - Users can set a different name for the Segment, which is visible to Contacts in Preference Center options.
 
-Since :xref:`Mautic 3.2` it has been possible to provide a public name, in addition to an internal name, for a Segment.
-
 .. vale off
 
 Viewing and exporting Contacts in a Segment
@@ -113,7 +108,7 @@ Adding individual Contacts
 .. vale on
 
 1. Navigate to the Contact record you want to change.
-  
+
 2. Click the arrow in the top right, next to **Edit/Send Email/Close**.
 
 3. Select **Preference**.
@@ -148,7 +143,7 @@ Inside a :ref:`Campaign<campaigns overview>`, you can add or remove Contacts fro
     :alt: Screenshot Campaign builder connector.
 
 2. Select **Action**.
-   
+
 3. In the list of actions, select **Modify Contact's Segments**.
 
 4. Choose from the list of existing Segments you want to add or remove your Contact from.
@@ -202,10 +197,10 @@ Once a Contact has accrued an assigned number of Points, the system can add them
 
 5. Decide if you'd like to add all Contacts with at least that number of Points to the Segment:
 
-.. tip:: 
-     
+.. tip::
+
     * If you only want to add new Contacts who reach the threshold to this Segment, select **No** - default.
-    
+
     * To add all existing Contacts with at least a certain number of Points to the Segment, toggle the switch to **Yes**.
 
 1. Click **Events**.
@@ -270,29 +265,29 @@ Configuring Segment filters
 
 3. Click the **Filters** tab to add filters.
 
-4. Click the **Choose one**… menu and search for the field you'd like to Segment by. 
+4. Click the **Choose one**… menu and search for the field you'd like to Segment by.
 
-.. attention:: 
+.. attention::
 
   Listed below are three types of fields:
 
   * Contact fields
-  
+
     * Set Fields to **Available for Segments = Yes** in your Custom Field manager to display here.
 
   * Contact behavior and actions
   * Primary Company fields
-    
+
     * Set Fields to **Available for Segments = Yes** in your Custom Field manager to appear here.
-    
+
     * Contacts associates with multiple Companies, but Mautic adds them to Segments based on fields for the primary Company.
 
 5. Add more filters, using the **And** and **Or** operators. An **Or** operator creates a new group of filters which can include And operators.
 
 6. Click **Save and close**.
 
-.. note:: 
-    
+.. note::
+
     Segments are rebuilt according to how frequently you fire your :ref:`cron jobs<segment cron jobs>`.
 
     * If a Segment fails to rebuild for a predetermined length of time, Mautic displays a notification alerting you of an error. For information on defining this time period, see :ref:`Segment settings<segment settings>`
@@ -307,8 +302,8 @@ Using Date Filters
 
 You can create dynamic Segments by using date filters.
 
-.. note:: 
-  
+.. note::
+
   The date format for values stored in the database is ``YYYY-MM-DD``. For example, December 11, 2020 is stored as 2020-12-11 and November 12, 2020 is stored as 2020-11-12. To update the display format for dates, go to **Settings > Configuration > System Settings > System Defaults**. However, this doesn't alter the storage format in the database.
 
 .. vale off
@@ -357,14 +352,14 @@ Once you've selected a date field as your filter, such as the default **Date las
 
   *For example, A value of 1 matches anyone whose field value is on the 1^st, 21^st, or 31^st of any month but a value of 01 matches the 1 st of a month. A value of 01-01 finds Contacts whose value is for January 1 of any year.*
 
-* **Contains** - Segment includes Contacts with the specified filter value anywhere in the field value. 
+* **Contains** - Segment includes Contacts with the specified filter value anywhere in the field value.
 
 .. image:: images/operators-2.png
     :alt: Screenshot showing Operators.
 
 Once you have selected the field you can then choose the type of operation to perform. These vary depending on the way you wish to filter your Contacts.
 
-.. vale off 
+.. vale off
 
 Matching part of a string
 =========================
@@ -385,18 +380,18 @@ First three filters match strings as you enter it. ``like`` filter is for advanc
 A few notes for text filters:
 
 * You should use ``starts with``, ``ends with``, ``contains`` rather than ``like`` as they're more specific, and therefore can be more effective.
-  
+
 *  A ``%`` character in the middle of the string has no special meaning. A ``contains`` filter with ``my % string`` searches for a string with ``%`` in the middle. The same is TRUE for a ``like`` filter with ``%my % string%`` value. There is no need to escape this character.
 
 * Mautic searches for the ``%`` character in a value for the ``like`` filter, if finding at least one ``%`` Mautic doesn't perform any modification.
 
-You can use regular expressions in a ``regexp`` filter. Mautic recognises all common operators like ``|`` for OR  - for example ``first string|second string``, character sets including ``[0-9]``, ``[a-z0-9]`` and so forth, repetitions (``+``, ``*``, ``?``) and more. 
+You can use regular expressions in a ``regexp`` filter. Mautic recognises all common operators like ``|`` for OR  - for example ``first string|second string``, character sets including ``[0-9]``, ``[a-z0-9]`` and so forth, repetitions (``+``, ``*``, ``?``) and more.
 
-You have to escape special characters with ``\`` if you want to use them as matching character. 
+You have to escape special characters with ``\`` if you want to use them as matching character.
 
-Learn more about :xref:`Regex`. 
+Learn more about :xref:`Regex`.
 
-.. note:: 
+.. note::
 
   MySQL (and Mautic) uses ``POSIX`` regular expressions, which could behave differently from other types of regular expressions.
 
@@ -427,7 +422,7 @@ Example - Consider that today is ``2022-03-05``:
 * ``Date identified equals -1 months`` returns all Contacts identified on 2022-02-05.
 * ``Date identified greater or equal -1`` year returns all Contacts identified 2021-03-05 and after.
 * ``Date identified greater than -1`` year returns all Contacts identified after 2021-03-05.
-  
+
 Beside this you can specify your date with text. These formulas are **translatable**, so make sure you use them in correct format.
 
 * ``birthday`` / ``anniversary``
@@ -487,11 +482,11 @@ Deleting thousands of Contacts this way in one Segment becomes a tedious task. L
 
 2. Use the :ref:`Delete contact action<using the campaign builder>`.
 
-This way the ``mautic:campaign:update`` and ``mautic:campaign:trigger`` commands delete all the Contacts in the Segment, and all the Contacts added to the Segment in the future. 
+This way the ``mautic:campaign:update`` and ``mautic:campaign:trigger`` commands delete all the Contacts in the Segment, and all the Contacts added to the Segment in the future.
 It's all done automatically in the background.
 It's necessary to configure the :ref:`cron jobs<segment cron jobs>`.
 
-.. danger:: 
+.. danger::
 
   You can't recover deleted Contacts unless you restore your entire Mautic database backup. **Use with extreme caution**.
 
@@ -511,4 +506,4 @@ Since :xref:`Mautic 4` there is a step when deleting or deactivating a Segment t
     :width: 300
     :alt: Screenshot deleting or deactivating a Segment
 
-If you attempt to delete or deactivate a Segment which is in use by a filter in another Segment, an alert prompts you to edit the other Segment, removing the dependency before you delete the Segment.
+If you attempt to delete or deactivate a Segment which is in use by a filter in another Segment, an alert prompts you to edit the other Segment, removing the dependency before you delete the Segment.