Find & replace: preview, confirm, undo

Renaming a product, moving a domain or retiring a term means the same edit in dozens of articles. Freshdesk has no find and replace for article text and no bulk update in its API, so this is the part of TidyKB that actually writes to your help center.

Everything about it is built around one idea: you approve a specific diff, and you can take it back.

The preview never writes

Starting a find & replace creates a preview. The preview only ever issues GET requests. It runs with your read-only scan key, it runs while fixes are switched off, and it cannot change an article even by accident.

What it does:

1. Narrows the scope using the last scan's copy of your knowledge base — language, category, folder, and then the articles whose stored copy mentions your term.
2. Reads each of those articles live, through the same rate limit as everything else. The diff you approve has to show the article as it is now: one edited in Freshdesk since the last scan is previewed against the edit, and one that no longer contains the term is dropped rather than shown from a stale copy.
3. Stores the before and after bytes and a rendered diff per article version.
4. Says what it did not do. The job page shows how many articles were in scope, how many were candidates, how many were read live, and a line for each article with no diff and why.

An article in scope ends up with no diff when the live copy no longer contains the term, when the term only appears somewhere the rules refuse to touch, when the article now 404s, when the read failed, when the replacement would leave the article with no title, or when the preview hit its ceiling of 500 article versions. In that last case the page says so; narrow the scope rather than hoping.

Scope and matching options

Some matches are reported but never changed: text split across inline tags, text inside an attribute you did not opt into, text wrapped around invisible characters. The preview counts those separately rather than quietly skipping them.

The second key fixes need

Your scan key stays read-only forever. Applying a change needs a second key, and turning fixes on is a separate action from adding it — two moves on purpose, so that adding a key never enables writing by itself.

1. 01

   Add an API key with edit rights

   On the Freshdesk connection page, paste the key of an agent whose role can edit (and publish) Solutions. The read-only connection has to be working first.
2. 02

   TidyKB proves the key can edit

   It calls agents/me, lists one Solutions endpoint, and then attempts a write against an article id no Freshdesk account can hold. A 403 means the role cannot edit; anything else means it got past the permission gate. The request can never land on a real article.
3. 03

   Turn fixes on

   A confirmation sheet names the domain and the last four characters of the edit key. Only this confirm moves the connection out of read-only, and it is recorded in the audit log with who did it.

Remove the edit key returns the connection to read-only immediately, and anything already queued refuses instead of running. Adding a new edit key also drops you back to read-only until that key is tested and you confirm again. Disconnecting deletes both keys at once.

Applying a batch

The apply button names the number of article versions, and the sheet it opens asks you to type the number of changes this preview found. That number belongs to this preview: if the preview has been run again in another tab, the number you type no longer matches and the confirm bounces rather than authorising a batch nobody read.

Then, one article version at a time:

1. Read the article again from Freshdesk.
2. Compare it byte for byte with the version you approved.
3. Write the smallest possible patch — only the fields that actually differ.
4. Read it back and store what Freshdesk now holds. That stored copy, not what we intended to write, is what undo argues with later.

Conflicts, stops and partly applied batches

• Somebody edited the article in the meantime. The row becomes a conflict, nothing is written, and the run carries on. Conflicts are answers, not failures.
• Three unexpected failures in a row stop the batch. Everything written keeps its snapshot and its undo; everything after the stop is untouched and still waiting. The job page offers Apply the rest.
• Freshdesk's rate limit is reached. The batch is rescheduled and resumes when your account's API budget refills. Nothing is rolled back, because a write cannot be.
• A write failed and we could not tell whether it landed. The row is marked as such, apply never retries it, and undo treats it as possibly live. Running apply twice can never write twice: every article is re-read and re-compared before it is touched.

The job page counts what happened — written, conflicts, failed, untouched — rather than reporting the batch as a single success or failure.

Undo

One button, on the job page, for as long as any article version of that batch is still holding our text. Per article it re-reads, compares with what we stored right after our write, and puts the original bytes back with another patch, then reads it once more to check.

• An article edited after our write is a conflict and is never forced, including one a colleague already restored by hand. It is theirs now.
• Undo restores stored bytes. It never runs the replacement backwards, which would be lossy when flexible spaces or "keep capitalisation" were used.
• If Freshdesk hands back something not byte-identical, the row says so rather than claiming a clean undo.
• Undo asks for less than apply does, deliberately: only a working edit key and the global safety switch — never your plan, never a second confirm. A cancelled subscription must not be able to keep our write in your help center.

Snapshots, and the record undo needs, are kept for 90 days from the last time that record changed.

Freshdesk and Freddy are trademarks of Freshworks Inc. TidyKB is an independent product and is not affiliated with, endorsed or sponsored by any company named on this page.