Skip to main content

References: ids and portable codes

A record points at another record in one of two forms.

By id. Every record has a uuid, and that is how the platform stores and returns every reference: a sequence's defaultSurfaceId, a journey action's sequenceId, a condition's field path. An id belongs to one deployment.

By portable code. Content records also carry an UPPER_SNAKE code, unique in their tenant and fixed once created. Written as @<resource>/<CODE>, with the resource named as the API names it, a reference means the same thing in any tenant or deployment that holds a record with that code:

{ "type": "createUserSequence", "sequenceId": "@sequences/SLEEP_CHECK", "surfaceId": "@surfaces/TODO" }

Where each form is accepted​

  • Content writes accept either. A create or update of atoms, sequences, journeys, surfaces and cohorts resolves @resource/CODE to the id before anything else sees it, so what is stored is always an id. A code that matches nothing is refused.
  • Content reads return ids, or codes with ?refs=code. ?refs=language gives codes only inside the reference language, leaving every other reference an id.
  • In the reference language (a condition's field path and value, a transition's When, a {{ }} token) a code is written bare, because the path already says what each segment is: sequenceResponses.SLEEP_CHECK.latest.scores.TOTAL, not …@sequences/SLEEP_CHECK…. See Referencing a participant's data.
  • The content file that export writes carries every reference as a code, which is what lets it be applied in another tenant.

The shared library​

Atoms, sequences, journeys, surfaces, assets, task types and relationships in the DEFAULT tenant are readable from every tenant. A code resolves in your own tenant first and then in that library, so a record of your own with the same code shadows the library's.

What never translates​

A reference inside free-form JSON that the platform does not declare as a reference (an id pasted into an atom's markdown, for instance) stays an id. Export flags such ids as not portable rather than guessing.