Document Find and Replace bulk action for Contacts and Companies

[promptless-for-oss]

Open this suggestion in Promptless to view citations and reasoning process

Documents the new Find and Replace bulk action that allows users to update field values across multiple Contacts or Companies by finding a specific value and replacing it. Covers both the selection-based action and the list-view/gear-icon action for current search results.

Trigger Events

• mautic/mautic PR #16207: [UXUI-253] Find and replace contact and company fields in bulk actions

---

Update — applied @adiati98's review feedback

Review #pullrequestreview-4782683700:

• manage_contacts.rst — Moved the "use a Campaign for large volumes" paragraph to be the first paragraph of the Batch changes section. ✅ Applied verbatim.
• manage_contacts.rst — Moved the batch-actions image to sit after the "To apply changes…" paragraph and renamed the asset batch-actions.png → batch_actions.png (updated the .. image:: reference to match). ✅ Applied verbatim.
• manage_contacts.rst — Added the "You can find the following options:" lead-in before the batch-action bullet list. ✅ Applied verbatim.
• companies_overview.rst — Moved companies_batch_selection_bar.png to after the "To apply changes to several Companies…" paragraph. ✅ Applied verbatim.

Review #pullrequestreview-4782699433:

• companies_overview.rst — Reworded the gear-icon paragraph to "…click the gear icon at the top of the table to open the Options, then select Find and Replace…". ✅ Applied verbatim.
• manage_contacts.rst — Same gear-icon rewording for Contacts. ✅ Applied verbatim.

All six edits applied verbatim; no deviations. Vale introduced no new findings on the changed lines.

---

Update — applied @adiati98's review feedback (codebase verification)

Review #pullrequestreview-4782732764:

• manage_contacts.rst — "Can you please investigate the codebase to confirm that this option is no longer available? I don't see this option anymore." (on the Delete Selected (batch delete) bullet). ✅ Applied — bullet removed.

Verified against mautic/mautic 7.x source. Findings:

• Delete selected still exists in 7.x, but it was relocated (mautic/mautic PR #14306 "[UI] Toolbar batch actions") from the old table-header dropdown into the selection bar at the top of the table, next to Export to CSV. It is no longer one of the three-dot "Options" menu items — which is why it wasn't visible where the bullet placed it. LeadController::batchDeleteAction() and the toolbar delete button are intact in 7.x.
• The bullet's "up to 100 Contacts at a time / performance precaution" limit does not exist in 7.x source (no count cap in batchDeleteAction, the JS precheck, or the select-all logic). It was stale/inaccurate.

Resolution: removed the misplaced, inaccurate bullet from the "You can find the following options:" (three-dot) list. Delete selected remains correctly documented in this section's intro paragraph as a selection-bar button, so no correct information was lost. The trailing pointer to the Segment docs for deleting large numbers of Contacts is retained. No deviation from the reviewer's request; the Companies page needed no change.

Update — applied @adiati98's review feedback

Review #pullrequestreview-4782787292:

• companies_overview.rst — "Remove the width." (on the companies_batch_selection_bar.png image). ✅ Applied verbatim — removed the :width: 600 option; :alt: retained.
• companies_overview.rst — "Remove the width" (on the companies_find_and_replace_list_view.png image). ✅ Applied verbatim — removed the :width: 600 option; :alt: retained.
• manage_contacts.rst — Suggestion on the Change Channels bullet. ✅ Applied verbatim.
• manage_contacts.rst — Suggestion on the Change Owner bullet. ✅ Applied verbatim.
• manage_contacts.rst — Suggestion on the Change Segments bullet. ✅ Applied verbatim.
• manage_contacts.rst — Suggestion on the Set Do Not Contact (DNC) bullet. ✅ Applied verbatim.
• manage_contacts.rst — "Wrap the whole options list in vale off/on statements." ✅ Applied — wrapped the entire batch-options list (from the first bullet through the Set Do Not Contact (DNC) bullet, including the Find and Replace sub-steps, note, and image) in .. vale off / .. vale on, matching the existing pattern in this file. The "You can find the following options:" lead-in stays outside the block.

All seven edits applied verbatim; no deviations. Vale introduced no new findings on the changed lines and the wrapping suppressed the prior Vale suggestions across the options list.

Update — applied @adiati98's review feedback

Review #pullrequestreview-4785117918 — three comments, each marked "apply this as well for Companies", so all three were applied in both manage_contacts.rst and companies_overview.rst:

• Comment r3655564436 — "Remove this. We've mentioned this step at the second paragraph. Apply this as well for Companies." ✅ Applied. Removed the redundant #. Click the three-dot icon to open this option step from the Find and Replace numbered steps in both files; the numbered list now starts with "Choose the … field to update." (Companies: the removed step also carried "This opens a dialog", so that detail was folded into the bullet lead-in — "Selecting this action opens a dialog." — to avoid losing it. Minor deviation from a pure deletion, on the grounds that dropping it would have lost a factual detail the reviewer did not ask to remove.)
• Comment r3655579683 — case sensitivity of Find value / Replace with. ✅ Applied in both files. Added: "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'."
• Comment r3655620838 — clarify no-selection behavior. ✅ Applied in both files. Reworded to: "Find and Replace updates all [Contacts/Companies] that match your current search when you don't select any checkboxes. To limit the change to specific [Contacts/Companies], select their checkboxes first." The gear-icon list-view path is retained.

All three comments applied in both files; one minor grounded deviation (preserving the "opens a dialog" fact for Companies). Additional style polish while applying: switched the "Only … get updated" sentence to active voice ("Find and Replace updates only …") per the Mautic style guide. Vale introduced no new findings on the changed lines.
Update — applied @adiati98's review feedback

Review #pullrequestreview-4785689894 — three suggestions; the first is marked "This applies to Companies too", so it was applied in both manage_contacts.rst and companies_overview.rst:

• Comment r3656041190 — restructure the no-checkboxes / list-view path into an explicit gear-icon step sequence ("This applies to Companies too"). ✅ Applied verbatim in manage_contacts.rst; mirrored in companies_overview.rst. The list-view paragraph is now: "To update all [Contacts/Companies] with a specific find and replace value, you don't need to select any checkboxes. In the [Contacts/Companies] list table:" followed by numbered steps (gear icon → Options; select Find and Replace; choose the field; enter Find value; enter Replace with).
• Comment r3656042373 — bold Contact field in the selection-based first step (manage_contacts.rst). ✅ Applied verbatim.
• Comment r3656043921 — bold Company field in the selection-based first step (companies_overview.rst). ✅ Applied verbatim.

All three suggestions applied verbatim (with the first mirrored to Companies per the reviewer's note); no deviations. Vale introduced no new findings on the changed lines.

Update — applied @adiati98's review feedback

Review #pullrequestreview-4787587851 — three suggestion blocks:

• companies_overview.rst — "The following batch actions are available:" → "The following batch options are available:". ✅ Applied verbatim.
• companies_overview.rst — Find and Replace bullet: "Selecting this action opens a dialog." → "Selecting this option opens a dialog." ✅ Applied verbatim.
• manage_contacts.rst — reword the "delete large numbers of Contacts" cross-reference to use :doc: link text Segments (target /segments/manage_segments) and wrap it for Vale. ✅ Applied, with one grounded deviation on the Vale directives: the suggestion added a standalone .. vale off/.. vale on pair around the sentence, but that sentence already sat between an existing .. vale on/.. vale off toggle whose only purpose was to lint this one line, itself inside the options list's .. vale off region. Pasting new toggles would have produced redundant adjacent directives. Instead I removed the existing .. vale on/.. vale off pair so the sentence stays inside the already-open Vale-off region — same net effect (sentence not linted), no redundant directives. The sentence text was applied exactly as in the reviewer's latest edited suggestion (link text Segments, added "page,", comma before "which", no trailing "easily"); the :doc: target /segments/manage_segments is unchanged and still resolves.

Review #pullrequestreview-4787700823 — "I just changed the wording slightly here." This referred to @adiati98's own edit of the third suggestion block above (its body was updated to drop "easily" and add "page,"). No separate branch commit was pushed by the maintainer, so there was nothing to rebase against; the reconciled sentence text applied here matches that edited wording exactly.

Vale introduced no new findings on the changed lines.

Update — applied @adiati98's review feedback

Review #pullrequestreview-4788207650 — one suggestion block on the Change Tags bullet in manage_contacts.rst:

• manage_contacts.rst — Change Tags bullet: "Selecting this option opens a modal" → "opens a dialog", and "You see this action only" → "You see this option only". ✅ Applied verbatim.

One edit applied verbatim; no deviations. "dialog" now matches the parallel Find and Replace wording in companies_overview.rst, and "option" agrees with the bullet's own "Selecting this option" lead-in. Tags/Change Tags is a Contacts-only batch action, so companies_overview.rst needed no change. Vale introduced no new findings on the changed line.

Update — applied @adiati98's review feedback

Review #pullrequestreview-4789781456 — three comments, the first marked "Apply the same thing for the Contacts", so all were applied in both docs/companies/companies_overview.rst and docs/contacts/manage_contacts.rst:

• Comment 1 — "I think we better make a new standalone subsection for this part rather than squeeze it here. Move this to after the note admonition and follow the suggestion below." ✅ Applied. Moved the no-checkboxes / gear-icon list-view flow out of the nested Find and Replace bullet into a new standalone subsection — "Find and Replace for all Companies" / "Find and Replace for all Contacts" — placed after the Role-permissions note, ending with "Case sensitivity and Role permission requirements are the same as for selected [Companies/Contacts]." per the suggested block. One grounded deviation: in manage_contacts.rst the new heading uses a - underline (not the suggestion's =) so it nests correctly as a child of the =-underlined "Batch changes" heading rather than becoming a sibling; in companies_overview.rst the = underline from the suggestion is correct because "Batch changes" there uses *. The Contacts subsection was placed after the "delete large numbers of Contacts" paragraph (the last item still belonging to Batch changes) so the DNC bullet and that paragraph stay under Batch changes.
• Comment 2 — "Remove the space." on the companies_batch_selection_bar.png image (companies_overview.rst). ✅ Applied verbatim — re-indented the :alt: option to align under .. image:: and added the trailing period.
• Comment 3 — "Remove the space." on the batch_actions.png image (manage_contacts.rst). ✅ Applied verbatim — added the trailing period to the alt text (indentation was already aligned).

All three comments applied in both files, with one grounded RST-structure deviation (Contacts heading underline). Vale introduced no new findings on the changed lines.

Update — applied @adiati98's review feedback

Review #pullrequestreview-4790102992 — five suggestion blocks across docs/contacts/manage_contacts.rst and docs/companies/companies_overview.rst:

• manage_contacts.rst — "Remove the space." on the batch_actions.png image. ✅ Applied verbatim — removed the | vertical-space (line-block) spacer markers above and below the image so only a single blank line surrounds the .. image:: directive.
• companies_overview.rst — "Remove the space." on the companies_batch_selection_bar.png image. ✅ Applied verbatim — removed the | spacer markers around the image.
• manage_contacts.rst — trim the Segments cross-reference: …visit the :doc:Segments</segments/manage_segments> page. (dropping the trailing ", which explains how to delete thousands of Contacts" clause). ✅ Applied verbatim; the :doc: target still resolves and the destination page still covers deleting large numbers of Contacts.
• manage_contacts.rst — wrap the "Find and Replace for all Contacts" heading in .. vale off / .. vale on. ✅ Applied verbatim.
• companies_overview.rst — wrap the "Find and Replace for all Companies" heading in .. vale off / .. vale on. ✅ Applied verbatim (this also cleared the pre-existing Google.Headings sentence-case warning on that heading).

All five suggestions applied verbatim, with one grounded follow-up fix: in manage_contacts.rst the new .. vale on that closes the "Find and Replace for all Contacts" wrapper sat inside a wider pre-existing .. vale off region, so it re-exposed the sibling "Individual Contact details" heading to Vale and introduced a new Google.Headings warning. To keep the reviewer's wrapper exactly as suggested while avoiding that regression, I re-added a .. vale off immediately before the "Individual Contact details" heading, restoring the suppression it had before this pass. Vale introduced no new findings on the changed lines.

Update — applied @adiati98's review feedback

Review #pullrequestreview-4790401733 — one suggestion block, marked "Apply this as well for Contacts", so it was applied in both docs/companies/companies_overview.rst and docs/contacts/manage_contacts.rst:

• Comment r3660008782 — "We can make this clearer." Reworded the list-view Find and Replace intro sentence. ✅ Applied verbatim in companies_overview.rst; mirrored in manage_contacts.rst.
  • companies_overview.rst — "To update all Companies with a specific find and replace value, you don't need to select any checkboxes." → "To update every Company that matches a specific Find and Replace value, you don't need to select any checkboxes."
  • manage_contacts.rst — same rewording with the noun swapped: "To update every Contact that matches a specific Find and Replace value, you don't need to select any checkboxes."

One suggestion applied verbatim (mirrored to Contacts per the reviewer's note); no deviations. Vale introduced no new findings on the changed lines.

---

Tip: Request one-off documentation tasks in the Dashboard under New Task 🚀

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks for the feedback @adiati98! I've addressed all the suggestions:

• Bolded Find and Replace as a UI term in all instances
• Replaced "page actions menu" with "list view actions" to avoid the Vale warning about "page"

[andersonjeccel]

• there's no green arrow above checkboxes
• when checking the checkboxes, a toolbar appears above table including a 3-dots icon menu where the Find and Replace option is available

[promptless-for-oss]

Thanks @andersonjeccel — you're right, and I've updated the PR to match.

I removed the incorrect "green arrow above the checkboxes" wording and corrected the workflow: selecting rows via the checkboxes surfaces a toolbar above the table with a three-dot icon menu, where Find and Replace is available. I also fixed the same pre-existing "green arrow" phrasing in the Contacts batch-actions intro since it was inaccurate too.

Changed files:

• docs/contacts/manage_contacts.rst
• docs/companies/companies_overview.rst

The Find/Replace behavior, the list-view action against the current search result, and the permission notes are unchanged. Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks @adiati98! I've applied all three suggestions to the PR:

• Updated the Companies batch-action intro to describe selecting rows via checkboxes, which surfaces a toolbar at the top of the table with a three-dot menu listing the available batch actions.
• Updated the Find and Replace and Delete Selected list items under the Companies batch actions to your wording.
• Applied the matching intro update to the Contacts batch-actions section.

Changed files:

• docs/companies/companies_overview.rst
• docs/contacts/manage_contacts.rst

Ready for another look.

[adiati98]

/aside

@andersonjeccel Promptless has addressed your request. Can you please review this again and approve if it meets your requests? Thanks!

[andersonjeccel]

correct

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks for the detailed review, @adiati98! I've applied all the suggestions and pushed the updates:

• Renamed the section to Batch changes in both files.
• Rewrote the batch intros to describe the selection bar and its options.
• Folded Find and Replace into a single bullet with the numbered sub-steps, the gear-icon/list-view usage, and the permissions note, and swapped the code permission strings for the UI terms Edit Own / Edit Others.
• Added the Companies selection-bar and list-view screenshots and replaced the Contacts batch-actions screenshot, all with descriptive alt text and underscore file names.
• Cleaned up the stray paragraph, extra blank lines, and image spacing on the Contacts page.

One small thing to confirm: in the Companies permissions note I kept your wording as written (Edit Own / Edit Others under Contacts, applied to Companies). Let me know if you'd prefer it phrased differently.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks for the review, @adiati98! I've addressed all three comments and pushed the updates.

1. Contacts permission text — Applied your suggested wording verbatim. Confirmed against the code (mautic/mautic #16207): LeadController::batchFindReplaceAction gates on (lead:leads:viewown OR lead:leads:viewother) and (lead:leads:editown OR lead:leads:editother), and the per-record access check limits Edit Own users to Contacts they own. Your text is accurate.

2. Companies permission text — Applied your suggested wording verbatim, including "under Contacts". I double-checked whether that should read "under Companies", and it should not: CompanyController::batchFindReplaceAction is identical to the Contacts gate and checks the Contact permission set (lead:leads:*), not company:companies:*. So Companies Find and Replace really is governed by Contact permissions — the "under Contacts" phrasing is code-correct (worth flagging since it may be counterintuitive to users).

3. Screenshot — Added the image directly after the gear-icon paragraph (which previously had no list-view screenshot, unlike the Companies doc). Applied all three formatting requests: filename uses underscores (contacts_find_and_replace_list_view.png), blank line before and after the .. image:: directive, and descriptive alt text that doesn't start with "Screenshot of".

Vale passes on the changed lines. Ready for another look.

[promptless-for-oss]

Thanks — on it. We'll remove the duplicated step, add a note that 'Find value' and 'Replace with' are case-sensitive, and clarify that running Find and Replace without selecting any rows applies to all matching records (select checkboxes to scope it) — applying all three to both the Contacts and Companies sections. We'll push the update shortly.

[promptless-for-oss]

All three comments addressed, @adiati98 — each applied to both the Contacts and Companies Find and Replace sections:

1. Removed the redundant "click the three-dot icon" first step (already covered in the intro paragraph). For Companies, that step also mentioned "opens a dialog," so I folded that detail into the option's description rather than lose it.
2. Added a note that the Find value and Replace with fields are case sensitive, using your Country / 'United States' example.
3. Clarified that running the action without selecting any rows updates all matching records, and that selecting checkboxes limits it to those specific records.

Vale introduced no new findings; the update is pushed to PR #750 and ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks — applying your suggested step restructuring for the no-selection Find and Replace flow to both the Contacts and Companies sections (with the correct Contact field / Company field wording each), and will push the update shortly.

[promptless-for-oss]

All three suggestions applied, @adiati98 — exactly as written, on both the Contacts and Companies pages:

• Bolded Contact field / Company field in the "Choose the field to update" step.
• Restructured the no-selection (list-view) path into a clear numbered sequence: click the gear icon to open Options, select Find and Replace, then choose the field and enter the Find value / Replace with values.

Pushed to PR #750; Vale introduced no new findings on the changed lines. Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks — applying your latest suggestions now: the batch-options lead-in, the Companies Find and Replace bullet wording, and the vale-wrapped Segments cross-reference for bulk deletion. We'll push the update to this PR shortly.

[promptless-for-oss]

Thanks for the heads-up on the wording tweak — noted. We'll reconcile with your change as we apply the rest of the suggestions and push everything together shortly.

[promptless-for-oss]

All applied and pushed, @adiati98:

• Companies (companies_overview.rst): "batch actions" → "batch options", and the Find and Replace bullet now reads "Selecting this option opens a dialog."
• Contacts (manage_contacts.rst): reworded the cross-reference to point to the Segments page with your latest wording.

One small note on your third suggestion: that sentence already sits inside an existing Vale-off region, so rather than add another .. vale off/.. vale on pair (which would duplicate adjacent directives) I removed the now-redundant toggles — same net effect (the sentence isn't linted), no duplicate directives. If you'd prefer literal toggles wrapping just that sentence, let me know and I'll add them back. The PR body records the per-review disposition. Vale introduced no new findings. Ready for another look.

[promptless-for-oss]

Applied, @adiati98 — the Change Tags bullet now reads "opens a dialog" and "You see this option only", exactly as you suggested. This is a Contacts-only batch action, so no change was needed on the Companies page. Pushed to PR #750; Vale is clean on the changed line. Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks — will do. We'll pull the no-selection Find and Replace flow into its own standalone subsection (after the note) on both the Companies and Contacts pages, and fix the whitespace on the two image directives. Pushing the update shortly.

[promptless-for-oss]

All three applied and pushed, @adiati98 — on both the Companies and Contacts pages:

• Moved the "update all records without selecting checkboxes" (gear-icon list view) flow into its own standalone subsection after the permissions note, as you suggested.
• Fixed the two batch-selection image directives (indentation + trailing period on the alt text).

One small structural note: on the Contacts page I used a lower heading level (- underline) for the new subsection than your block showed (=), so it nests correctly as a child of that file's =-underlined "Batch changes" heading — the rendered structure matches your intent. Vale is clean on the changed lines. Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks — on it. We'll wrap the two new subsection headings in vale off/on, fix the whitespace on the two image directives, and simplify the Segments cross-reference. Pushing the update shortly.

[promptless-for-oss]

All five applied and pushed, @adiati98:

• Removed the extra vertical-space markers around both batch-action screenshots.
• Trimmed the trailing clause on the Segments cross-reference.
• Wrapped both "Find and Replace for all …" headings in the .. vale off/.. vale on directives.

One small adjustment alongside the Contacts heading change: that heading sat inside an existing Vale-off region, so the new .. vale on was re-exposing the neighbouring "Individual Contact details" heading (which would have introduced a new Google.Headings warning). I re-added a .. vale off just before it to keep it suppressed as before. Vale reports no new findings on the changed lines. Ready for another look.

[promptless-for-oss]

Applied, @adiati98 — the list-view intro now reads "To update every Company that matches a specific Find and Replace value, you don't need to select any checkboxes," and I made the matching change on the Contacts page ("…every Contact that matches…") as you asked. Both went in exactly as suggested; Vale flagged nothing new on the changed lines. Pushed to PR #750 — ready for another look.