Add Company Segments documentation for ABM functionality

Documents the Company Segments feature from mautic/mautic PR #16025:
creating and managing Company Segments, Campaign integration, cron job
configuration, and search operators.

Author: promptless[bot]

docs/campaigns/campaign_builder.rst

@@ -132,6 +132,12 @@ The actions that Mautic offers in a Campaign include:
      - Updates the existing Contact's primary Company fields with the specified value. See :doc:`documentation on Companies </companies/companies_overview>`.
    * - **Update Contact owner**
      - Updates the Contact's owner.
+   * - **Modify Company's Segments**
+     - Adds or removes the Contact's primary Company to or from Company Segments. Use this for Account-Based Marketing workflows targeting Companies.
+
+.. _campaign company segment actions:
+
+.. vale on
 
 .. vale on
 
@@ -258,8 +264,10 @@ Here are the different conditions that Mautic offers in the Campaign Builder:
      - Checks if the selected User is the Contact's owner.
    * - **Contact Segments**    
      - Checks if the Contact is a member of selected Segments.
-   * - **Contact Tags**    
+   * - **Contact Tags**
      - Checks if specified Tags are on the Contact record.
+   * - **Company Segments**
+     - Checks if the Contact's primary Company is a member of selected Company Segments. Use this for Account-Based Marketing workflows.
    * - **Contact Points**
      - Checks if the Contact has a certain number of Points or a Group score.
    * - **Form Field value**    

docs/companies/companies_overview.rst

@@ -72,7 +72,18 @@ Company Segments
 
 .. vale on
 
-You can create a Segment based on a Company record. Select any Company field to filter with and the matching criteria for it, and Mautic lists any Contacts that match the selected fields in the Segment.
+Company Segments let you group Companies based on shared attributes or criteria for targeted Account-Based Marketing - ABM. Use Company Segments to organize Companies for Campaign targeting, reporting, and bulk operations.
+
+For detailed information on creating and managing Company Segments, see :doc:`Company Segments</companies/company_segments>`.
+
+.. vale off
+
+Contact Segments based on Company fields
+========================================
+
+.. vale on
+
+You can also create Contact Segments based on Company data. Select any Company field to filter with and the matching criteria for it, and Mautic lists any Contacts that match the selected fields in the Segment. This groups Contacts by their associated Company attributes.
 
 .. vale off
 

docs/companies/company_segments.rst

@@ -0,0 +1,221 @@
+.. vale off
+
+Company Segments
+################
+
+.. vale on
+
+Company Segments group Companies based on shared attributes or criteria, enabling targeted Account-Based Marketing - ABM - strategies. Use Company Segments to organize Companies for Campaign targeting, reporting, and bulk operations.
+
+.. note::
+
+   Company Segments are distinct from Contact Segments. While Contact Segments group individual Contacts, Company Segments group entire Companies. This lets you target organizations rather than individuals in your marketing automation.
+
+.. vale off
+
+Creating a Company Segment
+**************************
+
+.. vale on
+
+#. Navigate to **Companies > Company Segments** in the menu.
+#. Click the **New** button to create a new Company Segment.
+#. In the **Details** tab, configure the following:
+
+   * **Name** - The internal name for your Company Segment.
+
+   * **Public name** - An optional alternate name visible in certain interfaces.
+
+   * **Description** - A description of the Segment's purpose.
+
+   * **Active** - Toggle to make the Segment available for use. Inactive Segments aren't available as Campaign sources or in other areas of Mautic.
+
+.. vale off
+
+Company Segment filters
+***********************
+
+.. vale on
+
+Use filters to create dynamic Company Segments that automatically include or exclude Companies based on field values. Mautic evaluates Companies against these filters during Segment rebuilds and updates membership accordingly.
+
+Configuring filters
+===================
+
+#. In the Company Segment editor, click the **Filters** tab.
+#. Select a Company field from the dropdown to filter by.
+#. Choose an operator and specify the filter value.
+#. Add additional filters using **And** or **Or** logic:
+
+   * **And** - Companies must match all connected filters.
+   * **Or** - Creates a new filter group where Companies matching any group are included.
+
+#. Click **Save and close** to save the Segment.
+
+Available filter operators
+==========================
+
+The available operators depend on the field type:
+
+* **Equals / Not equal** - Exact match or exclusion of a value.
+* **Empty / Not empty** - Whether the field has a value.
+* **Like / Not like** - Partial string matching with wildcards.
+* **Contains / Starts with / Ends with** - String position matching.
+* **Greater than / Less than** - Numeric or date comparisons.
+* **Regexp / Not regexp** - Regular expression pattern matching.
+
+.. note::
+
+   Companies automatically move into or out of dynamic Segments when their field values change and the Segment cron job runs. See :ref:`Company Segment cron job<company segment cron job>` for configuration details.
+
+.. vale off
+
+Static Company Segments
+***********************
+
+.. vale on
+
+Static Company Segments don't use filters. Instead, you manually manage membership through the methods below.
+
+.. vale off
+
+Adding Companies manually
+=========================
+
+From the Company record
+-----------------------
+
+.. vale on
+
+#. Open the Company you want to add to a Segment.
+#. Click the dropdown arrow next to **Edit** and select **Segments**.
+#. Select the Company Segments to add the Company to.
+#. Click **Save**.
+
+From the Company list view
+--------------------------
+
+#. In the Company list, select the checkboxes next to the Companies you want to modify.
+#. Click the green arrow that appears at the top of the column.
+#. Select **Change Segments**.
+#. Choose the Segments to add or remove Companies from.
+#. Click **Save**.
+
+.. vale off
+
+Using Campaign actions
+======================
+
+.. vale on
+
+You can add or remove Companies from Company Segments as part of a Campaign workflow using the **Modify Company's Segments** action. For more information, see :ref:`Campaign Company Segment actions<campaign company segment actions>`.
+
+.. vale off
+
+Viewing Company Segment membership
+**********************************
+
+.. vale on
+
+When viewing all Company Segments, the **# Companies** column displays the number of Companies in each Segment. During rebuilds, this column shows **Building** until the process completes.
+
+To view Companies in a Segment:
+
+#. Navigate to **Companies > Company Segments**.
+#. Click the Company count link for the Segment you want to view.
+
+This opens the Company list filtered to show only Companies in that Segment.
+
+.. vale off
+
+Searching Companies by Segment
+******************************
+
+.. vale on
+
+Filter the Company list by Segment membership using the search syntax:
+
+.. code-block::
+
+   segment:{segment-alias}
+
+Replace ``{segment-alias}`` with the alias of your Company Segment. The alias is automatically generated from the Segment name or can be set manually.
+
+.. vale off
+
+Managing Company Segments
+*************************
+
+.. vale on
+
+Editing a Company Segment
+=========================
+
+#. Navigate to **Companies > Company Segments**.
+#. Click the Segment name or select **Edit** from the dropdown menu.
+#. Make your changes and click **Save and close**.
+
+Cloning a Company Segment
+=========================
+
+#. Navigate to **Companies > Company Segments**.
+#. Click the dropdown arrow next to the Segment.
+#. Select **Clone**.
+
+Mautic creates a copy of the Segment with the same filters and settings.
+
+Publishing and unpublishing
+===========================
+
+Control Segment availability by publishing or unpublishing:
+
+#. In the Company Segment list, click the colored status indicator - green for published, red for unpublished.
+#. Alternatively, edit the Segment and toggle the **Published** setting.
+
+Unpublished Segments aren't available for use in Campaigns or other features.
+
+Deleting Company Segments
+=========================
+
+#. Navigate to **Companies > Company Segments**.
+#. Select the checkbox next to the Segment or Segments to delete.
+#. Click the dropdown arrow and select **Delete**.
+#. Confirm the deletion.
+
+.. warning::
+
+   Mautic prevents deletion of Company Segments that are referenced by filters in other Segments. Remove the dependency before deleting.
+
+.. _company Segment Cron job:
+
+.. vale off
+
+Company Segment Cron job
+************************
+
+.. vale on
+
+To keep Company Segments current, configure a cron job to run the rebuild command:
+
+.. code-block:: php
+
+   php /path/to/mautic/bin/console mautic:company-segments:update
+
+This command evaluates all Companies against Company Segment filters and updates membership accordingly.
+
+**Available options:**
+
+* ``--batch-limit=X`` - Number of Companies to process per batch. Default is 300.
+
+* ``--max-companies=X`` - Maximum number of Companies to process per execution.
+
+* ``--segment-id=X`` - Process only a specific Company Segment.
+
+Run this command regularly, for example every 15 minutes, staggered with other cron jobs to distribute server load.
+
+.. code-block::
+
+   0,15,30,45 * * * * php /path/to/mautic/bin/console mautic:segments:update
+   2,17,32,47 * * * * php /path/to/mautic/bin/console mautic:company-segments:update
+   5,20,35,50 * * * * php /path/to/mautic/bin/console mautic:campaigns:update
+

docs/configuration/cron_jobs.rst

@@ -22,9 +22,10 @@ When setting up cron jobs, you must choose how often you want the cron jobs to r
 
 For instance:
 
-.. code-block:: 
+.. code-block::
 
     - 0,15,30,45 <— mautic:segments:update
+    - 2,17,32,47 <— mautic:company-segments:update
     - 5,20,35,50 <— mautic:campaigns:update
     - 10,25,40,55 <— mautic:campaigns:trigger
 
@@ -48,6 +49,25 @@ You can also limit the number of Contacts to process per script execution using
 
 .. vale off
 
+Company Segment Cron jobs
+=========================
+
+.. vale on
+
+**To keep Company Segments current:**
+
+.. code-block:: php
+
+   php /path/to/mautic/bin/console mautic:company-segments:update
+
+By default, the script processes Companies in batches of 300. If this is too many for your server's resources, use the option ``--batch-limit=X`` replacing X with the number of Companies to process each batch.
+
+You can also limit the number of Companies to process per script execution using ``--max-companies`` to further limit resources used.
+
+To update a specific Company Segment, use the ``--segment-id=X`` option.
+
+.. vale off
+
 Campaign cron jobs
 ==================
 

docs/index.rst

@@ -125,6 +125,7 @@ There are different types of documentation available to help you navigate your w
    :hidden:
 
    companies/companies_overview
+   companies/company_segments
 
 .. toctree::
    :maxdepth: 2

docs/search/search_operators.rst

@@ -74,14 +74,15 @@ Contacts search filters
 Companies search filters
 ------------------------
 
-.. code-block:: 
+.. code-block::
 
     ids:ID1,ID2 (comma separated IDs, no spaces)
     is:published
     is:unpublished
     is:mine
     is:uncategorized
     category:{category alias}
+    segment:{segment-alias}
 
 Segments search filters
 -----------------------