Building export definitions

July 1, 2026 · View on GitHub

An export definition tells the exporter how to turn a Salesforce record into a datapack: which fields identify it, which child records to embed, which fields to ignore, and how to split it into files. Definitions are written in YAML (or JSON) and passed with --definitions or referenced from an export manifest's exportDefinitions key.

This page is the reference for the definition format. The TypeScript types behind it live in exportDefinitions.ts.

File shape

A definitions file is a map of datapack type → definition:

Product2:            # <-- datapack type (the key)
  objectType: Product2
  name:
    - Name
  matchingKeyFields:
    - GlobalKey__c
# ... more datapack types
Pricebook2:
  objectType: Pricebook2
  name:
    - Name
  matchingKeyFields:
    - Name

The top-level key is the datapack type (a logical name, used for the output folder and to look the definition up). The objectType inside the definition is the Salesforce SObject API name. They are often the same for standard objects but differ for custom/Vlocity objects (e.g. type Product2 → objectType Product2; type CalculationMatrix → objectType %vlocity_namespace%__CalculationMatrix__c).

You may also wrap the map under a definitions: key — both shapes are accepted.

The `%vlocity_namespace%` placeholder

Anywhere an API name contains the Vlocity managed-package namespace, write %vlocity_namespace%__ instead of the literal prefix (e.g. %vlocity_namespace%__CalculationMatrix__c). Vlocode substitutes the real namespace at runtime, so the same definitions work against any org.

Definition fields

A DatapackExportDefinition supports the following keys.

objectType (required)

The SObject API name to export. Inherited from ObjectFilter.

objectType: '%vlocity_namespace%__CalculationMatrix__c'

name (required)

The format used to build the datapack's folder/file name. It is a field-value expression:

As a string, {FieldName} placeholders are replaced with field values: name: "{Name}".
As an array, each element is evaluated as an expression; literal constants are prefixed with _:

name:
  - Name
  - _v
  - VersionNumber__c   # → "<Name>v<VersionNumber>"

matchingKeyFields

The fields that uniquely identify the record. These drive the source key on export and the upsert lookup on import. Choose stable business fields, not Ids.

matchingKeyFields:
  - ParentId
  - Name

If omitted, the exporter falls back to org DataRaptor matching keys, then to auto-detected unique/DeveloperName/Name fields. See Concepts → Matching key for the full resolution order.

autoGeneratedMatchingKey

When true, the matching key is an auto-generated value rather than one derived from field data. Only valid for records that are not referenced via lookup fields (the generated key cannot be reproduced from another datapack). Use this for dependent child records that have no natural key.

SBQQ__LookupQuery__c:
  objectType: SBQQ__LookupQuery__c
  dependent: true
  autoGeneratedMatchingKey: true

dependent

When true, this object is exported only when referenced by another exported object — never as a top-level datapack. Use it for child records that should travel with their parent but never be the root of an export.

PricebookEntry:
  dependent: true
  objectType: PricebookEntry
  name:
    - Name
  matchingKeyFields:
    - Pricebook2Id
    - Product2Id

ignoreFields

Fields to exclude from the export entirely. Commonly used to drop volatile or runtime fields so datapacks stay clean and diff-friendly.

ignoreFields:
  - '%vlocity_namespace%__DRBundleName__c'
  - '%vlocity_namespace%__DRProgressData__c'
  - '%vlocity_namespace%__DRError__c'
  - '%vlocity_namespace%__DRStatus__c'

filter

A condition that restricts which records are exported. See Filters below.

limit

Maximum number of records to return for this object. Inherited from ObjectFilter; most useful on embedded objects.

embeddedObjects

A map of child records to embed inside this datapack. See Embedded objects.

fields

Per-field export settings — file expansion, processors, embedded lookups. See Field settings.

Filters

A filter selects which records belong to a (top-level or embedded) object. It can take three forms:

1. Field/value object — keys are field names, values are matched for equality. Placeholders in {...} are resolved against the parent record:

filter:
  Product2Id: '{Product2:Id}'
  Pricebook2Id: $StandardPricebookId

2. Field/value with an operator — give a value an explicit comparison operator with the op / value form:

filter:
  '%vlocity_namespace%__MatrixRecordType__c':
    op: '<>'
    value: RowVersioned

3. Raw SOQL string — for complex conditions, supply a WHERE-clause string; placeholders are interpolated before the query runs:

filter: "AccountId = '{parent.Id}' AND IsActive = true"

4. Array of filters — a list is treated as alternatives (an OR of the branches), each branch being a field/value object:

filter:
  - '%vlocity_namespace%__CalculationMatrixId__c': '{%vlocity_namespace%__CalculationMatrix__c:Id}'
    '%vlocity_namespace%__CurrentStatus__c': Active
  - '%vlocity_namespace%__CalculationMatrixId__c': '{%vlocity_namespace%__CalculationMatrix__c:Id}'
    '%vlocity_namespace%__CurrentStatus__c': Pending

Placeholder syntax

Inside filter values and name/fileName formats:

Syntax	Meaning
`{Field}`	A field on the current record.
`{Parent:Field}`	A field on the parent datapack, addressed by the parent's object/datapack type.
`{Parent:Child:Field}`	A nested path through the export hierarchy.
`{A\|B}` or `{A;B}`	Try `A`, fall back to `B`.
`$variable`	A special variable provided by the exporter (e.g. `$StandardPricebookId`).

A top-level definition typically filters by Id so that an export of specific Ids resolves to those exact records:

Attachment:
  objectType: Attachment
  name:
    - Name
  matchingKeyFields:
    - ParentId
    - Name
  filter:
    - Id: '{Id}'
    - ParentId: '{Id}'

Embedded objects

embeddedObjects pulls child records into the same datapack instead of emitting them as separate, referenced datapacks. Each entry is keyed by the name under which the children are written, and its value is an object filter (plus any field settings):

AttributeCategory:
  objectType: '%vlocity_namespace%__AttributeCategory__c'
  name:
    - Name
  matchingKeyFields:
    - Code__c
  embeddedObjects:
    '%vlocity_namespace%__Attribute__c':
      objectType: '%vlocity_namespace%__Attribute__c'
      filter:
        '%vlocity_namespace%__AttributeCategoryId__c': '{%vlocity_namespace%__AttributeCategory__c:Id}'

The filter usually references the parent's Id with the {Parent:Id} placeholder. You can nest embeddedObjects arbitrarily deep; the exporter resolves each level with batched queries.

Alternatively, an embedded object can be expressed as a relationship by name instead of a filter:

embeddedObjects:
  ChildItems:
    relationshipName: '%vlocity_namespace%__ProductChildItems__r'

Embedding decisions and matching keys

A practical rule observed in the bundled definitions: when you embed a child via a parent's embeddedObjects and give that child no top-level definition and no matching key, the deploy engine recreates those child rows rather than upserting them. Conversely, shared records that several parents point at should stay as standalone definitions with matching keys, and be embedded only once to avoid exporting the same SObject twice. Choose embedding to model ownership: private children embed (and may be recreated), shared records are referenced.

Field settings

The fields map (and any embedded-object entry) accepts per-field settings via ExportFieldDefinition:

fileName — write a field to its own file

When set, the field's value is written to a separate file instead of inline in the datapack JSON. The value uses the same field-value expression format as name (string with {...}, or array with _-prefixed constants). If no extension is given it is inferred from the field type (.json for JSON, .bin for binary).

fields:
  '%vlocity_namespace%__Content__c':
    fileName: '{Name}'      # writes Content to <Name>.html / .json / .bin

expandArray — split an array field into files

When true, an array-valued field is expanded so each item becomes its own file. Combine with --expand on the export command.

fields:
  '%vlocity_namespace%__Sequence__c':
    expandArray: true

embeddedLookup — inline a lookup target

When true on a lookup field, the referenced record is exported as an embedded object in the same datapack instead of as an external reference. Use ignoreFields alongside it to break circular references (for example, exclude the back-reference from the embedded child to its parent):

fields:
  AccountId:
    embeddedLookup: true
    ignoreFields:
      - ParentId     # avoid Account <-> Contact cycle

sortFields — deterministic ordering

When exporting a field as an embedded collection, sortFields lists the fields to sort by, keeping output stable and diff-friendly:

sortFields:
  - '%vlocity_namespace%__SequenceNumber__c'

processor — transform a value

A JavaScript snippet that processes the field value before it is written. The snippet runs with access to the field value (and supporting context such as the datapack and a logger) and returns the transformed value:

fields:
  Config__c:
    processor: 'JSON.stringify(value)'

Use processors sparingly — they are an escape hatch for data that needs massaging that the declarative options cannot express.

A worked example

Product2:
  objectType: Product2
  name:
    - Name
  matchingKeyFields:
    - GlobalKey__c
  ignoreFields:
    - '%vlocity_namespace%__DRBundleName__c'
    - '%vlocity_namespace%__DRProgressData__c'
  fields:
    '%vlocity_namespace%__JSONAttribute__c':
      fileName: '{Name}_attributes'   # split JSON blob into its own file
  embeddedObjects:
    PricebookEntry:
      objectType: PricebookEntry
      filter:
        Product2Id: '{Product2:Id}'
        Pricebook2Id: $StandardPricebookId
      limit: 500
    '%vlocity_namespace%__ProductChildItem__c':
      objectType: '%vlocity_namespace%__ProductChildItem__c'
      filter:
        '%vlocity_namespace%__ParentProductId__c': '{Product2:Id}'

# Referenced-only child: never a top-level datapack, travels with its parent.
PricebookEntry:
  dependent: true
  objectType: PricebookEntry
  name:
    - Name
  matchingKeyFields:
    - Pricebook2Id
    - Product2Id

Reference: example files in this repository

Several complete, real-world definition files ship in the repository root and are good starting points:

export-definitions.yaml — a large catalog of standard Vlocity object definitions.
sbqq-export.yaml and sbqq-expor.tpl.yaml — Salesforce CPQ / SBQQ design-time configuration, with extensive comments explaining the embedding and matching-key decisions.

Definition field reference

Field	Type	Applies to	Purpose
`objectType`	string	definition, embedded	SObject API name to export.
`name`	string \| string[]	definition	Folder/file name format.
`matchingKeyFields`	string[]	definition	Fields that identify the record (source key + upsert).
`autoGeneratedMatchingKey`	boolean	definition	Use a generated key (non-lookup records only).
`dependent`	boolean	definition	Export only when referenced; never top-level.
`ignoreFields`	string[]	definition, field	Fields to exclude.
`filter`	string \| object \| object[]	definition, embedded	Records to select.
`limit`	number	definition, embedded	Max records to return.
`embeddedObjects`	map	definition	Child records to embed.
`relationshipName`	string	embedded	Embed by relationship instead of filter.
`fields`	map	definition	Per-field settings.
`fileName`	string \| string[]	field, embedded	Write value to a separate file.
`expandArray`	boolean	field	Split an array field into files.
`embeddedLookup`	boolean	field	Inline a lookup target as an embedded object.
`sortFields`	string[]	field, embedded	Sort embedded collections deterministically.
`processor`	string	field	JS snippet to transform the value.