Core concepts

July 1, 2026 · View on GitHub

These terms are used throughout the export and import documentation. Read this page first if you are new to Vlocode datapacks.

Datapack

A datapack is a JSON document (optionally split across many files) describing a primary record together with the embedded child records and references that make it self-contained. Each datapack has:

  • a datapack type — a logical name such as Product2, OmniScript or CalculationMatrix. This is not the SObject API name; it is the key under which the record's export definition is registered and the folder name used on disk.
  • a primary SObject record plus any number of embedded child records.
  • references to records that live outside the datapack.

On disk an exported datapack is written as <Name>_DataPack.json. When expanded (see below) large field values and child collections are split into separate sibling files and the JSON holds file-name references instead of inline values.

Source key (VlocityRecordSourceKey)

Every record inside a datapack carries a source key — a string that uniquely and stably identifies it across orgs. The source key is what links records together inside and across datapacks; it replaces the Salesforce Id, which is org-specific.

A source key normally has the form:

<ObjectType>/<matchingKey>

For records that have no business matching key, the exporter assigns a cheap, deterministic path key derived from the parent (for example Product2/SomeProduct/PricebookEntry/0) — but only when the record is actually referenced. Unreferenced child records are written without a source key, and the deploy engine synthesizes one at deploy time.

Matching key

A matching key is the set of fields that uniquely identify a record by its business data — for example GlobalKey__c for a Product2, or ParentId + Name for an Attachment. The matching key drives two things:

  1. Export — it is used to build the record's source key and to detect duplicate exports.
  2. Import — it is used to look up whether the record already exists in the target org, so the deploy becomes an upsert rather than a blind insert.

Matching keys are resolved in priority order during export:

  1. matchingKeyFields declared in the export definition.
  2. Vlocity DataRaptor matching keys configured in the org (%vlocity_namespace%__DRMatchingKey__mdt).
  3. Auto-detected unique/DeveloperName/Name fields.
  4. An auto-generated key (only allowed for embedded records, or when autoGeneratedMatchingKey: true).

Matching keys must be unique within an export. A collision aborts the export (or skips the record when --fail-on-error is off) so that the result remains deterministic.

References vs. embedded objects

When a record points at another record there are two possible outcomes:

  • Embedded object — the related record is written inside the same datapack. Use this for tightly-coupled children that have no independent identity (price book entries under a product, matrix rows under a matrix). Configured with embeddedObjects or embeddedLookup in the export definition.

  • Reference — the related record is not included; the datapack stores a pointer to it. There are two reference shapes in the datapack JSON:

    • VlocityMatchingKeyObject — an internal reference to another record in the same datapack (by source key).
    • VlocityLookupMatchingKeyObject — an external reference (a lookup) to a record in another datapack or one that must already exist in the target org. It carries the matching-key field values needed to find that record on deploy.

Dependencies and export depth

External references create dependencies between datapacks. During export the --depth option controls how far the exporter follows those references:

  • --depth 0 — export only the requested records, leaving external references as lookups (the referenced datapacks are not exported).
  • --depth 2 — also export referenced datapacks up to two hops away.
  • --depth -1 — follow all dependencies (full closure).

During deployment the same dependency information is used to compute a safe deployment order so that a record is always deployed after the records it references.

Foreign keys

While building a datapack the exporter tracks foreign keys: a map of external source keys to the Salesforce Ids they were resolved from. These tell the deploy engine which external dependencies a datapack expects, and drive the depth-based export of related datapacks.

Datapack type vs. SObject type

The same SObject can map to different datapack types depending on context (for example a %vlocity_namespace%__OmniScript__c row can be an OmniScript or an IntegrationProcedure). Export definitions are keyed by datapack type, and the deploy engine resolves the datapack type from the folder structure and SObject type when loading files. Keep this distinction in mind: the top-level keys in an export-definitions file are datapack type names, while the objectType field inside each definition is the SObject API name.