Skip to main content

Find and Replace

find / replace is an update form that changes an attribute only where the sought value is already present. It works on scalar text attributes and on multi-value relations, and it is the tool of choice for mass edits where a blanket assignment would be wrong.

{
  "from": "<asset type or OID token>",
  "where": { /* optional narrowing */ },
  "update": {
    "<Attribute>": { "find": "<value>", "replace": "<value>" }
  }
}

On Scalar Text Attributes​

For Text and LongText attributes, find matches a substring and replace substitutes it in place. The surrounding text is preserved.

from: Story
where:
 Scope: Scope:1800
update:
 Name:
  find: Product-To-Be-Named-Later
  replace: Awesum.ly

Given two Stories named:

Product-To-Be-Named-Later is a marketing approved product name!
Product-To-Be-Named-Later is for math wizards who want to do their calculations in the cloud.

they become:

Awesum.ly is a marketing approved product name!
Awesum.ly is for math wizards who want to do their calculations in the cloud.
Substring, not token

find is a plain substring match. Replacing Cog also rewrites Cogent and Cognition. There is no word-boundary or regular-expression support. Preview the change first — see Preview mode.

Matching is exact and case-sensitive in every test in the suite; no case-insensitive variant is exercised.

On Multi-Value Relations​

For a relation, find and replace take references, and the semantics become "swap this reference for that one, but only where the first is already assigned".

from: Story
where:
 Scope: Scope:1800
update:
 Owners:
  find: Member:20
  replace: Member:1575

This projects to a per-asset command that keeps the find/replace pair intact rather than resolving it to add/remove — the decision is deferred to processing, where each asset's current membership is known:

[
  {
    "@33e9c481-29c7-4639-bb92-739be91f3da7": {
      "oid": "Task:1489",
      "update": { "Owners": { "find": "Member:20", "replace": "Member:1575" } }
    }
  },
  {
    "@e3991edc-106e-4d5a-947d-e0421e250faa": {
      "oid": "Task:1490",
      "update": { "Owners": { "find": "Member:20", "replace": "Member:1575" } }
    }
  }
]

If Task:1490 does not have Member:20 as an owner, it is left untouched — Member:1575 is not added to it.

warning
assetsModified counts matched assets, not changed ones

An asset lacking the find value is left untouched — but it is still counted in assetsModified, exactly as if it had been changed. The count tells you how many assets the command addressed, not how many it altered. There is no response field that distinguishes the two; read the assets back if you need to know what actually changed.

Why Not add / remove​

Wrong for a conditional swap
{
  "from": "Story",
  "where": { "Scope": "Scope:1800" },
  "update": { "Owners": { "remove": "Member:20", "add": "Member:1575" } }
}

This assigns Member:1575 to every matched Story, including those that never had Member:20. Use find / replace when the replacement should be conditional on the original value.