Skip to main content

Sync-source manifests

A sync source is a manifest, not code: a JSON description of how to read an external system and where its records land in Cobblr. You install it into a workspace, and the generic sync engine does the rest, which is why Cobblr never needs a release to support your system.

What a manifest declares​

Per entity type you want mirrored (a section), the manifest gives:

  • The list endpoint: the path to call, and where in the response the array of records lives. An optional per-record endpoint covers sources that need a second fetch for detail.
  • Identity: which field is the record's id in the source, and, for hierarchies, which field names its parent. The engine keeps an id map across imports, so parents and re-syncs resolve to the records it already mirrored.
  • A field map: source paths onto Cobblr fields, with literals, defaults, and value mappings where the vocabularies differ.
  • Auth: a header template carrying the source's credential.

Section extras​

  • references: a field that points at another section's record, resolved through that section's id map, so relations survive the mirror.
  • images: a field mapped to a source image URL; the engine fetches it into Cobblr's file storage and points the field at the stored copy.
  • targetInstance / instanceBy: land a section's rows in a specific instance, or fan one endpoint out across several based on a field's value (one machines endpoint splitting into 3D printers and laser cutters).
  • filter: import only the rows matching a condition.

Installing and testing​

Paste the manifest into a new sync connection (owner or admin). The editor validates it structurally before it saves, down to warning when an instance slug doesn't match a real instance in the workspace. Then run the first import preview: both sides shown, nothing written until you approve, which is also the fastest way to debug a field map.