Migration Key Fields

Successful migrations require a key field set by the migrator that stays stable across Vault refreshes and reloads. Because the system-assigned ID can change between sandbox, validation, and production Vaults, we recommend using an external ID, which links source records to target records across environments.

External IDs on Vault Objects

Section link for External IDs on Vault Objects

Vault objects require one key field for every row in a loader sheet. The field must be user-defined, configured as unique in the target Vault, and writable using Vault Loader or Vault API. We recommend using the external ID field when available, however, any unique key field satisfies this requirement.

Note

App-delivered objects may have key fields under a suffix such as __clin, __qdm, or __rim.

Many Vaults already have the external ID field configured as unique. Verify the field is present and configured unique before adding it to loader sheets. Add a key field only if the object's existing configuration does not include one and the owning application has not locked it.

Simple Join Objects

Section link for Simple Join Objects

Simple join objects do not require an external ID or key field because their identity is the combination of the two parent record IDs. Adding a field to a simple join object disables its Add button in the Vault UI for creating simple join records.

External IDs on Vault Documents

Section link for External IDs on Vault Documents

Vault documents also have an external ID field. This field must be unique across documents, document attachments, record attachments, and attachment fields. The external ID field is not visible on the Doc Info page even when added to a field layout, but remains accessible via the Library grid view, reports, and VQL.

Document Annotations

Section link for Document Annotations

Document annotations use external_id__sys, not external_id__v. For Vault-to-Vault migrations, the recommended format is {document_version_id}_{annotation_id}.

Other Key Fields

Section link for Other Key Fields

The following key fields exist in your Vault. Each is either set by you or managed by the system.

Field	Set By	Purpose
external_id__v / external_id__c (name and suffix may vary)	Migrator (user-defined)	Provides source traceability, serves as an upsert key, and supports parent-child linking.
id (BYOID, under Record Migration Mode)	Migrator, using BYOID	Preserves the source system's record ID for Vault-to-Vault migrations. See Bring Your Own ID (BYOID).
link__sys	Migrator or integration	Stores a source record's global_id__sys for Vault-to-Vault connections. Can be used as a key field only when the value is unique.
global_id__sys	Vault (system-managed, read-only)	Provides cross-Vault integration linking in the format {vault id}_{record id}, set by the record's ID.

External ID Naming Conventions

Section link for External ID Naming Conventions

We recommend creating external IDs from a predictable pattern that is reconstructible from the source ID of the source system's primary or natural key. A predictable pattern means the key is reconstructible from source data if a load fails mid-run and must be restarted. Prefix external IDs with an object-type identifier to prevent collisions when multiple objects share the same numeric key space. For example, STUDY-00123 or SITE-US-00045.

While the same external ID value can exist on two different objects without conflict, Vault API and Vault Loader reject a duplicate on the same object with the error message OPERATION_NOT_ALLOWED: Another resource already exists with [external_id__v=<value>]. For documents, there is a wider scope of uniqueness.

Do not derive external IDs from mutable attributes such as a record's status, name, or owner. Assign external IDs at the start of the transformation phase and leave them fixed. Regenerating keys after any records have been loaded invalidates all parent-child references in downstream files.

Bringing Your Own ID (BYOID)

Section link for Bringing Your Own ID (BYOID)

With Record Migration Mode enabled, you can supply the id column on create so that each target record's ID is generated cleanly from its source record ID. This strategy is particularly useful when performing Vault-to-Vault migrations.

Bring your own ID (BYOID) values brought from the source system must be 15 uppercase alphanumeric characters, with the object prefix as the first three characters and Z as the fourth. For example, 00PZA1B2C3D4E5F.

If the structure of the ID needs to remain the same across multiple restage cycles, use a cycle counter. Replace characters 4–5 with Z1 for the first load, Z2 for the next restage, Z3 for the one after, and so on. Each cycle claims fresh ID space that was never previously consumed. Because Vault does not enforce this convention, you must track the counter per engagement.

Caution

If your migration requires idempotent reloads, populate the external_id__v field on upsert rather than using BYOID. Vault never frees a consumed record ID on delete, so delete-and-restage cycles that reuse the same ID values will fail. Only a full Vault refresh resets the ID.

Managing Idempotent Reloads

Section link for Managing Idempotent Reloads

Use the idParam=external_id__v query parameter on the Create & Upsert Object Records endpoint to make loads re-runnable. Vault Loader matches incoming rows against existing records by external ID and creates or updates records accordingly. Vault Loader exposes this as the UPSERT action type with idParam=external_id__v.

Caution

If key fields are not set on the first load pass, a subsequent upsert has no values to match against and will create duplicates.

Resolving References

Section link for Resolving References

When populating object reference fields in loader sheets, we recommend using the external ID lookup form rather than the system ID. Record IDs differ between sandbox and production environments, while external ID lookups are transferable across environments.

Strategy	Column Header Format	Transferability
System ID	parent_field__v = 00P000000000101	Non-transferable
Name lookup	parent_field__vr.name__v = 'United States'	Transferable only when name__v is unique on the target object
External ID lookup	parent_field__vr.external_id__v = 'COUNTRY-US'	Transferable; preferred for migration

When creating new relationships between documents, the Create Multiple Document Relationships endpoint accepts a document's external ID in place of source_doc_id__v or target_doc_id__v. Ordinary document reference fields on records still expect the literal Vault document ID.

CSV Column Header Format

Section link for CSV Column Header Format

Both field-name form and the relationship-name form resolve correctly when using Vault API and Vault Loader. We recommend using the field-name form because it works with both API field names and relationship names without requiring the relationship name.

Form	Column Header Format	Example
Field-name form	<field_api_name>.external_id__v	product_family__v.external_id__v
Relationship-name form	<relationship_name>.external_id__v	product_family__vr.external_id__v

To use the relationship-name form, you must confirm the actual relationship_name within the object's metadata relationships[] array. Vault API ignores incorrect relationship names, leaving the reference null.

Note

Vault API's /vobjects/ endpoints do not reject incorrect column headers, silently dropping these unrecognized headers. Therefore, you should verify reference fields have been populated after loading. If a CSV contains a duplicated column header, Vault API returns SUCCESS and uses the last value with no error. The same applies when both header forms target the same field simultaneously.