Data Transformation Considerations

Several complications can occur when populating Vault metadata. Consider the following best practices to transform data before a migration.

Object Field Types

The following table outlines considerations by field type when migrating object records:

Field Type	Considerations
Text	Vault Loader API trims leading and trailing whitespace. We recommend adding double quotes (`"`) to any string values within CSV files. Email: Vault Loader API does not verify the address is valid nor verify the format. Phone: Stored as a plain string. Vault Loader API does not verify the format. Link: Accepts the full URL. For example, `http://veepharma.com`. Long Text: Supports up to 32,000 characters. Rich Text: Stored and loaded as HTML markup. Supports up to 32,000 plain text characters and a combined maximum of 64,000 plain text and HTML markup characters. Vault Loader API trims whitespace at the edges of the raw HTML value only; whitespace enclosed within markup is not affected.
Number	Number fields must adhere to the configured minimum value, maximum value, and decimal place. Currency: Must be a plain numeric value. For example, `232`. Percent: Must be a decimal value. For example, for 1.2%, enter `0.012`. Vault Loader API does not apply percentage formatting upon load, however, percentage values display properly in the Vault UI.
Date & Time	Vault Loader API accepts the following date and time formatting: Date: In `YYYY-MM-DD` format, based on UTC. DateTime: In `YYYY-MM-DDTHH:MM:SS.sssZ` format, based on UTC. The `.sss` portion must be in milliseconds and can be any value. The trailing `Z` is required. Time: Must be in `HH:MM:SS` 24-hour format.
Object Reference	The referenced records must exist prior to loading. To look up records by a field other than ID, append a unique field name (such as `name__v` or `external_id__sys`) to the column header. The input must consistently use the same field across all rows.
Parent Object	You must load parent records before child records. To look up records by a field other than ID, append a unique field name (such as `name__v` or `external_id__sys`) to the column header. The input must consistently use the same field across all rows.
Picklist	Picklist values are case-sensitive. We recommend providing Vault Loader API the picklist name instead of its label.
Roll-up	Omit Roll-up fields from input files. Vault calculates these values from child records.
Attachment	You must upload the attachment file to your Vault's file staging prior to loading. Provide the staged file path in the input file.
Yes/No	Vault Loader API automatically formats boolean values and accepts case-insensitive variants. For example, `TRUE` or `true`. When migrating data with Vault API, you must provide lowercase `true` or `false`.
Lookup	Only include Lookup fields from input files if you are setting a static override value with Record Migration Mode enabled. Otherwise, Vault automatically populates the value.
Formula	Formula fields provided within input files are not indexed or resolved upon loading. Vault calculates and manages these values.

Document Field Types

The following table includes considerations by field type when migrating documents:

Field Type	Considerations
Text	You must remove trailing spaces prior to loading.
Date & Time	Vault Loader API accepts the following date and time formatting: Date: In `YYYY-MM-DD` format, based on UTC. DateTime: In `YYYY-MM-DDTHH:MM:SS.sssZ` format, based on UTC. The `.sss` portion must be in milliseconds and can be any value. The trailing `Z` is required.
Yes/No	Vault Loader API automatically formats boolean values and accepts case-insensitive variants. For example, `TRUE` or `true`. When migrating data with Vault API, you must provide lowercase `true` or `false`.
Picklist	Picklist values are case-sensitive. We recommend providing Vault Loader API the picklist name instead of its label.
URL	Accepts the full URL. For example, `http://veepharma.com`.
Object Reference	The referenced records must exist prior to loading. To look up records by a field other than ID, append a unique field name (such as `name__v` or `external_id__sys`) to the column header. The input must consistently use the same field across all rows.
Lookup	Only include Lookup fields from input files if you are setting a static override value with Record Migration Mode enabled. Otherwise, Vault automatically populates the value.

Other Considerations

The following considerations apply to both object record and document migrations.

CSV Format

CSV files used to create or update documents using Vault Loader API must use UTF-8 encoding and conform to RFC4180.

Special Characters

Metadata must not contain special characters, for example, tabs and smart quotes (”). These special characters can be lost when migrating data into Vault.

Character Encodings

Saving Excel files in CSV format for use with Vault Loader API can corrupt the file in an undetectable manner. If the file becomes corrupt, your load will fail. Failure logs contain a record of each row that has failed and are accessible by email or Vault notification. Correct the CSV files to continue loading.

Language

If the data being migrated is multilingual, ensure your Vault is configured to support different languages.

Multi-value Field Comma Separator

When mapping multi-value fields, values with commas can be entered through quoting and escaping. For example, “veeva,,vault“ is equivalent to “veeva,vault“.

Windows & MacOS Formatting

Data formatting can differ per environment. For instance, a line separator behaves differently when being from Windows or a MacOS.

Trailing Spaces

Vault removes trailing spaces from text fields upon loading. These are commonly found after commas.

Leading Zeros

Vault removes leading zeros from number fields upon loading.

Unique Identifiers

On documents or object records where Name is not unique or is system-managed, set the External ID (external_id__v or external_id__c) to relate it to the original ID used in the legacy system. Additionally, this field helps distinguish between records in success and failure logs. See Migration Key Fields to learn more.

References to Users and Persons

Documents and objects can reference User (user__sys) and Person (person__sys) records. These records must be active in order to be referenced. If referencing people who have left the company or had a name change, reference a Person record as it does not have to be linked to a Vault user account. User names and Person names are not unique, therefore, external IDs must be referenced for these objects.