Document Find and Replace bulk action for Contacts and Companies

docs/companies/companies_overview.rst

@@ -34,10 +34,41 @@ 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.
+
+The following batch actions are available:
+
+* **Delete Selected** - Deletes the selected Companies.
+* **Find and Replace** - Replaces a value in a chosen field across all selected Companies.
+
+   #. Click the three-dot icon to open this option.
+   #. 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**.
+
+   Only Companies that match the **Find value** get updated.
+
+.. image:: images/companies_batch_selection_bar.png
+  :width: 600
+  :alt: Two selected Companies in the list with the selection bar showing Delete selected and the three-dot menu open on Find and Replace
+
+You can also use **Find and Replace** without selecting any rows, from the list view, by clicking the gear icon to open the options. This applies the replacement to all Companies matching your current search.
+
+.. image:: images/companies_find_and_replace_list_view.png
+  :width: 600
+  :alt: Companies list view with the gear icon menu open, showing the Find and Replace option
+
+.. note::
+
+   You need edit permissions to use Find and Replace. Users with the **Edit Own** permission under **Contacts** can update Companies they own. Users with **Edit Others** can update any Company.
+
 Company actions
 ***************
 
-.. vale off 
+.. vale off
 
 Merging Companies
 =================

docs/contacts/manage_contacts.rst

@@ -129,26 +129,22 @@ 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. 
+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.
 
-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.
 
-
-
-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
+   :width: 200
+   :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:
-
 * **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.
@@ -163,6 +159,21 @@ The following batch actions are currently available:
 
 * **Export** - Allows you to export selected Contacts to CSV.
 
+* **Find and Replace** - Replaces a value in a chosen field across all selected Contacts.
+
+   #. Click the three-dot icon to open this option.
+   #. 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**.
+
+   Only Contacts that match the **Find value** get updated.
+
+   You can also use this option without selecting any rows. Click the gear icon at the top of the table, then select **Find and Replace**. This applies the replacement to all Contacts matching your current search.
+
+   .. note::
+
+      You need edit permissions to use Find and Replace. Users with the **Edit Own** permission under **Contacts** can update Contacts they own. Users with **Edit Others** can update any Contact.
+
 * **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.
 
 * **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.