Docs / Language & functions

a9script authoring pack — mapping functions

The mapping functions, with their arguments and a line of real script each. Called by bare name; nothing is imported. A call marked pauses does real work outside the script: the run is saved, and continues on the next line with the result.

setMapping(namespace, source, target) — pauses

Remembers which id in the target system corresponds to a source id — for systems that cannot store each other’s keys. Writing a source that is already mapped replaces its target: a re-synced record moved.

• namespace (string) — Which kind of thing is being mapped — one namespace per remote entity type, such as "users" or "invoices". Namespaces are separate maps: the same source id may map differently in each.
• source (string) — The id on the source side.
• target (string) — The id it corresponds to on the target side.

Answers: Nothing. The mapping is durable: every later run of this environment sees it.

setMapping("users", "crm-4711", "hr-0815");
log("linked");

getMapping(namespace, source) — pauses

Answers the target id a source id was mapped to, or null when it never was.

• namespace (string) — The namespace the mapping lives in.
• source (string) — The source-side id to look up.

Answers: The target id as text, or null for a source nobody mapped — the everyday answer for a record seen for the first time, so check it rather than treating it as a failure.

const known = getMapping("users", "crm-4711");
if (known === null) { log("first sight — create, then setMapping"); }

deleteMapping(namespace, source) — pauses

Forgets a mapping — for the record that was DELETED in the far end. There is no new target id to write in that case, and a mapping pointing at an id that no longer exists makes every later sync update into nowhere.

• namespace (string) — The namespace the mapping lives in.
• source (string) — The source-side id whose mapping should go.

Answers: true when a mapping was removed, false when there was none — never an error, because the everyday caller is cleaning up and does not know which. After this, the next upsertBySourceId for that source CREATES rather than updates: the arm is chosen on whether a mapping exists.

if (deleteMapping("users", "crm-4711")) { log("forgot the old link — the next sync will create"); }

setMappings(namespace, pairs) — pauses

Stores many mappings in one call — the bulk form of setMapping, and the one to use inside a sync loop. The whole list lands together or not at all.

• namespace (string) — The namespace every pair goes into.
• pairs (array) — A list of { source, target } pairs, at most 10000 a call — past that the call is refused as DATA_CALL_TOO_LARGE; split the list. A pair whose source is already mapped replaces that target, exactly as setMapping would.

Answers: Nothing. Either every pair is stored or, on a refusal, none is.

setMappings("users", [
  { source: "crm-1", target: "hr-a" },
  { source: "crm-2", target: "hr-b" }
]);

getMappings(namespace, sources) — pauses

Looks up many source ids at once and answers their targets in the same order — one call for a whole page of records instead of one per record.

• namespace (string) — The namespace to look in.
• sources (array) — The source-side ids, as a list of text entries — at most 10000 a call; past that the call is refused as DATA_CALL_TOO_LARGE.

Answers: A list aligned with sources: at each position the mapped target id, or null where that source was never mapped — so sources[2] answers at position 2, always.

const targets = getMappings("users", ["crm-1", "crm-2", "crm-3"]);
log(targets.filter((t) => t === null).length + " still unmapped");

listMappings(namespace, page?) — pauses

Reads a namespace’s mappings back, ordered by source id — for reports and reconciliation.

• namespace (string) — The namespace to list.
• page (object, optional) — { offset, limit, after } — where to start and how many to answer, after the last source you read (the way to walk a large namespace), limit at most 1000 (past it the call is refused as DATA_CALL_TOO_LARGE). Left out, the platform still answers a bounded page rather than everything: walk with offsets when a namespace may be large. Never delete while you walk: a removed row moves every later one up, and the next page skips as many as you took out — collect what to forget, finish the walk, then delete.

Answers: A list of { source, target } pairs, ordered by source.

const pairs = listMappings("users", { offset: 0, limit: 100 });
log("first page holds " + pairs.length + " mappings");