a9script

Docs / Data & bulk sync

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.

This is one part of the authoring pack — how a script is executed at all is the model part, and the other groups of functions are parts of their own. All of them are named at the end.

Generated — do not edit. Every block of script below is executed by the platform’s own test suite, and every error message is the one the platform produces today, so none of this can be what was true when someone last wrote it down.

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. 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.

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 } — where to start and how many to answer. 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");

The rest of this pack

The page above is everything that is true only HERE. Ask for these parts by name for the rest:

  • model — how a script is executed, the shape of its input, the rules enforced while it runs, and the mistakes that do not work here.
  • functions-core — the core functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-encoding — the encoding functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-crypto — the crypto functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-text — the text functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-number — the numbers functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-structured — the structured data functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-document — the documents functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-markdown — the markdown functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-datetime — the date & time functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-email — the email functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-blob — the files functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-dataset — the datasets functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-state — the state functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-pagination — the pagination functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-control — the run control functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-functions — the config functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • mistakes — the habits from general JS that do not work here — each with the exact error it produces and the shape to write instead.
  • standard-library — every built-in the language itself provides — JSON, Math, Object, String, Array, Number, Map, Set, Date, RegExp and the bare globals — one line each, with an example and its answer.
Rendered from docs/guide/authoring-pack-functions-mapping.md in the product's own repository, at build time. Found a problem on this page? Write to the address in the footer.