Document Find and Replace bulk action for Contacts and Companies

docs/companies/companies_overview.rst

@@ -34,10 +34,57 @@ In *Configuration > Company Settings* you can choose the operator used when merg
 
 These settings allow  Mautic to find and merge duplicate Companies during the import, using the Integrations Framework and in other parts of Mautic.
 
+Batch changes
+*************
+
+To apply changes to several Companies at once, select the checkboxes next to the Company names. A selection bar appears at the top of the table, showing **Delete selected** and a three-dot icon for more options.
+
+|
+
+.. image:: images/companies_batch_selection_bar.png
+  :alt: Two selected Companies in the list with the selection bar showing Delete selected and the three-dot menu open on Find and Replace
+
+|
+
+The following batch options are available:
+
+* **Delete Selected** - Deletes the selected Companies.
+* **Find and Replace** - Replaces a value in a chosen field across all selected Companies. Selecting this option opens a dialog.
+
+   #. Choose the **Company field** to update. Search or scroll to find it in the list.
+   #. Enter the value to find in **Find value**.
+   #. Enter the new value in **Replace with**.
+
+  Find and Replace updates only Companies that match the **Find value**. Both **Find value** and **Replace with** are case sensitive, so the value you enter must match the stored value exactly. For example, if you find and replace on the Country field, entering 'United states' or 'united states' changes nothing - you must enter 'United States'.
+
+  To update all Companies with a specific find and replace value, you don't need to select any checkboxes. In the Companies list table:
+
+   #. Click the gear icon at the top of the table to open **Options**.
+   #. Select **Find and Replace**.
+   #. Choose the **Company field** to update. Search or scroll to find it in the list.
+   #. Enter the value to find in **Find value**.
+   #. Enter the new value in **Replace with**.
+
+  |
+
+  .. image:: images/companies_find_and_replace_list_view.png
+     :alt: Companies list view with the gear icon menu open, showing the Find and Replace option
+
+  |
+
+  .. note::
+
+     To use **Find and Replace**, Users need these Role permissions under **Contacts**:
+
+     * View permission - **View Own** or **View Others**
+     * Edit permission - **Edit Own** or **Edit Others**
+
+       Users with only **Edit Own** can update Companies they own, and those with **Edit Others** can update any Company.
+
 Company actions
 ***************
 
-.. vale off 
+.. vale off
 
 Merging Companies
 =================

docs/contacts/manage_contacts.rst

@@ -129,47 +129,76 @@ So, Mautic takes care of duplicate Contacts created by the event tracking. You c
 
 |
 
-Batch actions
+Batch changes
 =============
 
-To make updates to several Contacts at once, select those Contacts then click the green arrow at the top of the checkbox column. 
-
-A modal window displays when you click one of the actions, with more configuration details. 
+You can use this feature to quickly update large volumes of Contacts, but if you need to change more than a few hundred Contacts at a time, it's better to use a Campaign - for example, add the Contacts to a Segment, then run a Campaign to trigger the change.
 
+To apply changes to several Contacts at once, select the checkboxes next to the Contact names. A selection bar appears at the top of the table, showing **Delete selected**, **Export to CSV**, and a three-dot icon for more options.
 
+|
 
-You can use this feature to quickly update large volumes of Contacts, but it might be better to use a Campaign action - for example add all the Contacts you need to update into a Segment and use a Campaign to trigger the change - if you need to change more than a few hundred Contacts at a time.
-
-.. image:: images/batch-actions.png
-    :width: 200
-    :align: center
-    :alt: Screenshot of Contact Batch actions
+.. image:: images/batch_actions.png
+   :align: center
+   :alt: Contacts list with two Contacts selected and the three-dot batch actions menu open, listing options such as Change Campaigns, Export to Excel, and Find and Replace
 
 |
 
-The following batch actions are currently available:
+You can find the following options:
+
+.. vale off
 
 * **Change Campaigns** - Allows you to add/remove the selected Contacts to/from Campaigns.
 
 * **Change Categories** - Allows you to add/remove the selected Contacts to/from global Categories.
 
-* **Change Channels** - Allows you to subscribe/unsubscribe the selected Contacts to/from communication Channels (Email, SMS, etc.) and also define frequency rules.
+* **Change Channels** - Allows you to subscribe/unsubscribe the selected Contacts to/from communication Channels, such as Email and SMS, and also define frequency rules.
 
-* **Change Owner** - Allows you to assign/unassign the selected Contacts to/from an owner (a Mautic User).
+* **Change Owner** - Allows you to assign/unassign the selected Contacts to/from an owner.
 
-* **Change Segments** - Allows you to add/remove the selected Contacts to/from Segments. Note that if you add or remove a Contact to or from Segment manually, then Segment filters won't apply for them in that particular Segment.
+* **Change Segments** - Allows you to add/remove the selected Contacts to/from Segments. Note that if you add/remove a Contact to/from Segment manually, then Segment filters won't apply for them in that particular Segment.
 
 * **Change Stages** - Allows you to add/remove the selected Contacts to/from a specified Stage.
 
-* **Export** - Allows you to export selected Contacts to CSV.
+* **Change Tags** - Allows you to add or remove multiple Tags across the selected Contacts in a single action. Selecting this option opens a dialog with 'Add tags' and 'Remove tags' fields, where you can select existing Tags or type a new one to create it inline. You see this option only when an administrator turns on the Tag Manager Plugin and grants your User the Contacts **Edit Own** or **Edit Others** permission together with the Tag Manager **View** permission.
 
-* **Set Do Not Contact (DNC)** - This action sets all selected Contacts as DNC for the Email Channel, and it allows you to provide a custom message as "reason" for why the Contacts were manually unsubscribed by a Mautic User.
+* **Export to Excel** - Allows you to export selected Contacts to Excel.
 
-* **Delete Selected (batch delete)** - The batch delete action in the Contact table allows the deletion of up to 100 Contacts at a time. This limit is there as a performance precaution, since deleting more Contacts at a time could cause performance degradation issues.
+* **Find and Replace** - Replaces a value in a chosen field across all selected Contacts.
 
-If you need to delete large numbers of Contacts, visit the :doc:`segment docs</segments/manage_segments>` which explains how to delete thousands of Contacts easily.
+   #. Choose the **Contact field** to update. Search or scroll to find it in the list.
+   #. Enter the value to find in **Find value**.
+   #. Enter the new value in **Replace with**.
 
-.. vale off
+  Find and Replace updates only Contacts that match the **Find value**. Both **Find value** and **Replace with** are case sensitive, so the value you enter must match the stored value exactly. For example, if you find and replace on the Country field, entering 'United states' or 'united states' changes nothing - you must enter 'United States'.
+
+  To update all Contacts with a specific find and replace value, you don't need to select any checkboxes. In the Contacts list table:
+
+   #. Click the gear icon at the top of the table to open **Options**.
+   #. Select **Find and Replace**.
+   #. Choose the **Contact field** to update. Search or scroll to find it in the list.
+   #. Enter the value to find in **Find value**.
+   #. Enter the new value in **Replace with**.
+
+  |
+
+  .. image:: images/contacts_find_and_replace_list_view.png
+     :alt: Contacts list view with the gear icon menu open, showing the Find and Replace option
+
+  |
+
+  .. note::
+
+     To use **Find and Replace**, Users need these Role permissions under **Contacts**:
+
+     * View permission - **View Own** or **View Others**
+     * Edit permission - **Edit Own** or **Edit Others**
+
+       Users with only **Edit Own** can update Contacts they own, and those with **Edit Others** can update any Contact.
+
+* **Set Do Not Contact (DNC)** - Sets all selected Contacts as DNC for the Email Channel and allows you to enter a custom reason explaining why you unsubscribed them.
+
+If you need to delete large numbers of Contacts, visit the :doc:`Segments</segments/manage_segments>` page, which explains how to delete thousands of Contacts.
 
 Individual Contact details
 **************************