Skip to main content
Version: Next (nightly)

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 foreign key sent as a link resolves with |last: $.parent|last takes the last segment of a value like /api/storage_locations/1, so an API that expresses relations as URLs (API Platform, Django REST hyperlinked serializers, JSON:API) feeds parent and cross-section references without a code change. Null passes through untouched and a bare id is a no-op. A misspelled operator is rejected when the manifest is saved, rather than silently importing a flat tree.
  • 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.
  • tags: a source field holding the record's tags, as an array or as one delimited string with split ({ "from": "$.tags", "split": "," }). They become Cobblr tags on the mirrored record: attached by name, created if missing, never removed. A tag that cannot be attached is counted in the import result rather than dropped quietly.

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.