Using Configuration Migration Packages

With migration packages, you can migrate configuration changes and test data between two Vaults. Migration packages are particularly useful when your organization needs to configure and test in a sandbox Vault, and then move those configurations into a production Vault. In this example, you’d create and export an outbound package on the sandbox Vault and then import, review, and deploy the package on the production Vault.

Migration packages can contain components, data, and Vault Java SDK code and are used to migrate configuration and reference object data from one Vault to another. If you only need to migrate data, use a test data package.

How to Enable Migration Packages

You can enable this feature from Admin > Settings > General Settings. There are two settings involved:

Allow Outbound Packages: This setting must be on for the source Vault. This setting makes the Admin > Deployment tab visible.
Allow Inbound Packages: This setting must be on for the target Vault. This setting makes the Admin > Deployment tab visible.

After enabling, you may need to log out and log back in for the Deployment tab to appear.

How to Create & Export Migration Packages

To create an outbound migration package:

Navigate to Admin > Deployment > Outbound Packages and click Create.
In the dialog, select Migration as the Outbound Package Type.
Enter a Summary to help you and other users understand the purpose and contents of this package.
Optional: Select a user as Owner. If you leave this blank, it defaults to you. When importing the package, owner information appears in the target Vault to provide a contact person if there are questions about the package.
Optional: Select a Target Vault. This option allows Vault to check the package’s dependencies against the target Vault. You can select parent production Vaults and parent, child, or sibling sandbox Vaults as the target Vault.
Click Save. Vault opens the package details page.
Navigate to the Components section. Click Add to specify components for this package. In the dialog, use the checkboxes to add or remove components. You can add up to 200 components to a single package.
Navigate to the Data section. Click Add to add a new dataset to the outbound package. Enter a Set Label. If you leave this field blank, Vault will automatically generate a label based on the selected object. Select a data object from the Primary Object picklist. To add a related data object, click Add Related Object and select a related object. You can add up to nine (9) related objects to each dataset. Click Save to return to the Outbound Packages page.
Optional: Navigate to the Code section. Choose whether or not to include Vault Java SDK code. Yes defaults Vault Java SDK Deployment Options to Replace All.
Optional: In the Actions menu, select View/Add Dependencies. The resulting dialog shows all of the dependencies for components of your package that you have not included. If you did not select a Target Vault previously, the dependencies listed will not show what is already in the target Vault. Check the dependencies you would like to add to the package and click Save.
Optional: Navigate to the Packages section. Click Upload to store the exported VPK.
In the Actions menu, select Export. When the export is complete, a notice will appear in your Notifications page and Vault will send you an email. The notifications include a link to download your VPK. Vault does not automatically download the VPK to your machine.

Packages & Dependencies

The package will only include configuration details for the selected components. Sometimes, a configuration for one component depends on another component. For example, you wouldn’t create the picklist-type document field Audience without first creating the picklist it uses. We recommend exporting and deploying the complete configuration as a single package to prevent issues with dependencies. As described in the above steps, you can view and add the dependencies for a migration package prior to exporting it. You can also validate a package using the Vault API for information on dependent components and whether they exist in the package or the target Vault.

Creating Packages from Vault Compare

For Vaults on the same domain, Vault Compare can automatically create Outbound Packages based on the differences between the source Vault and target Vault.

About Datasets

Including datasets in an outbound migration package allows you to move both components and object data from one Vault to another. Datasets consist of object and related object data. Each dataset can contain up to ten (10) data objects, including one (1) primary object and up to nine (9) additional related objects. Each outbound package can contain up to 100 data objects.

Datasets can also include object relationships. For example, the grandparent, parent, and child relationship between Study, Country, and Site. Datasets leverage the Global ID and Link fields to migrate data.

Although the User object is available in migration packages, user data is unlikely to be the same in different Vaults, especially Vaults in different domains. Therefore, we recommend using Vault Loader to extract and move user records to another Vault in most cases.

Selecting Objects

To add objects to a dataset, from the Dataset Configuration page:

Select a Primary Object from a list of all available objects in your Vault. This list excludes object types and objects with system managed records. If Groups is selected as the Primary Object, review the considerations for adding groups to a dataset.
Optional: Click Add Related Objects to select from a list of applicable outbound and inbound relationships.
Click Save.

Editing Datasets

To edit an existing dataset, select Edit from the Actions menu next to the dataset on the Outbound Package detail page, or click Edit on the Dataset Configuration page.

Editing Default Settings for Data Objects

To edit default settings of data objects:

From the Outbound Package detail page, click the dataset.
From the desired object, select Edit from the Actions menu.
Optional: Select Upsert, Create, Delete, or Update from the Action picklist. This determines the default action for deployment. Vault sets Upsert as the default action.
Optional: Select a field from the Key Field picklist. This is a unique field used for looking up a record for the update portion of the Upsert, Update, or Delete actions. The Create action does not require a unique field for lookup.
Optional: Select the Record Migration Mode checkbox. Record Migration Mode allows you to migrate object records in a noninitial state and with minimal validation, create inactive records, and set system-managed fields such as Created By.
Optional: Expand the Filter section to apply filters by entering a VQL WHERE clause. This field is used to filter down the records you would like to move, using the same syntax as the Vault Loader Where Clause field. If the object has an inbound child relationship to another object, Vault automatically includes a status__v='active' filter, which you should not remove. Click Validate to check for syntax errors. Learn more about VQL in the Developer Portal.
Optional: Expand the Columns section to modify columns for the selected object. All editable columns are selected by default. You can choose not to move certain field values over by deselecting the columns to include. You can choose to replace the default reference field for an outbound relationship with any other unique reference field, however, you can only include one reference field for each outbound relationship. If there are no valid unique reference fields available, Vault excludes those columns. If the object has an inbound child relationship to another object, Vault excludes the status__v column.
Click Save.

Adding Groups to Datasets

If groups are included in a dataset, consider the following limitations:

You cannot add related objects to a dataset with Groups as the Primary Object.
You cannot create system-managed groups, but you can update existing system-managed groups.
You cannot export, create, or update Auto Managed Groups.
You cannot export group members. However, Vault may add or remove group members automatically depending on the security profile included for the group.

How to Import & Validate Migration Packages

To import and validate a migration package:

Navigate to Admin > Deployment > Inbound Packages and click Import.
Find and select the exported VPK file on your computer.
Vault imports and validates the package asynchronously and sends you a notification by email when complete. Click the link in the notification email to open the validation log for the import.
To validate an existing inbound package, select Validate from the Actions menu next to the inbound package Name.

About the Validation Log

The validation log contains details about deployment status and dependencies for each package step in an inbound package. Remember to add any missing dependencies, which appear in the Dependencies list with a Status of Missing - Block, to your package before deployment. The Package Status for the inbound package as a whole reflects the Deployment Status at the step level, which in turn reflects the Status from a dependency. If any required dependencies are missing, the deployment status for the step and, in turn, the entire package is set to Block.

Validation Status

Vault assigns a Status to each dependency in the list for a package step.

In Target: The dependent component already exists in the target Vault.
In Package: The dependent component exists in the package.
Missing - Ignore: The dependent component is missing, and Vault will ignore it.
Missing - Create: The dependent component is missing, and Vault will create it.
Missing - Block: The dependent component is missing, and Vault will block the VPK from deploying.
In Package - Ignore: The dependent component is in the package and the blocking type is ignore.
In Package - Create: The dependent component is in the package and the blocking type is create.
In Package - Wrong Order - Block: The dependent component is not in the correct order and the blocking type is block.

Exporting Package Component Comparisons

The Package Component Comparison export (XLSX) can help you understand the components in a given package, how those components compare to your Vault’s current configuration, and details about the package itself. This option is available on any imported package, before or after deployment.

To export a comparison:

Navigate to Admin > Deployment > Inbound Packages.
From the Actions menu on the package name or in the package detail page, select Package Component Comparison.
Vault begins the comparison process and sends you a notification when complete. The notification includes a link to download the package comparison report.

To compare the configuration of two Vaults, use Vault Compare.

Note: Package Component Comparison exports do not show details related to Workflow and does not include data comparison.

How to Deploy a Migration Package

Recommended: Enable Configuration Mode to lock non-Admin users out of Vault while deploying inbound packages.
From the Actions menu of the inbound package, select Review & Deploy. Vault displays a list of all components in the package.
Review the Deployment Status and Deployment Action for each item. To exclude specific steps, clear their checkbox.
Optional: To reorder steps, click Reorder, enter the desired step number in the Step field, then click Save.
Click Next. Depending on your Vault’s configuration, Vault may prevent you from clicking Next if a package step’s Deployment Status is Blocked.
On the confirmation page, review and click Finish.

Deployment Status

Vault determines Deployment Status of an inbound package first by verifying that each step (component or data) in the package matches (via checksum) the step in the source Vault. The status displays when you view an inbound package, and on the Review and Select Steps and Confirmation steps during Review & Deploy. Once you deploy, the status updates to reflect what happened. Deployment Status exists on each step and on the package as a whole. If an individual step encounters an error, the package’s status shows Error as well.

Imported: The VPK was successfully imported.
Verified: The package’s steps match the source Vault, but has not yet been deployed.
Not Verified: Indicates that the VPK or step was altered.
Deployed: Vault successfully deployed the component’s configuration on the target Vault.
In Deployment: VPK deployment is in progress.
Deployed: The VPK was successfully deployed without warnings or errors.
Deployed with Failures: Vault fully deployed VPK with some failures.
Deployed with Errors: Vault identified errors during deployment, but was still able to successfully deploy some components and data.
Deployed with Warnings: Vault identified some kind of problem during deployment, but was still able to successfully deploy. Example: The package included an object that referenced an object lifecycle, but the object lifecycle does not exist in the target Vault. Deployment was able to progress by creating a placeholder lifecycle. This status is only applicable for components.
Skipped: When deploying, the user chose to skip this step or Vault skipped this step because the component already existed in the target Vault.
Error: Vault encountered an error when deploying the package. See error details.
Blocked: Vault is unable to deploy the VPK because of missing or incorrectly ordered dependencies.

Deployment Action

Vault determines the Deployment Action of an inbound package by comparing the steps already on the target Vault to the steps in the package. Deployment Action displays on the Review and Select Steps and Deployment Confirmation steps during Review & Deploy. Unlike Deployment Status, Deployment Action only exists at the step level, for each step of the package.

Add: This is a new component that the package will add to the target Vault.
Create: This is a new data step that the package will add to the target Vault.
Upsert: This operation adds a data step to the target Vault if it does not already exist, or updates if it does.
Update: This component already exists on the target Vault, but its configuration is not identical. The package will update the existing component to match. This operation maintains all references to the component, such as the audit trail.
No Change: The component in the package is identical to a component that already exists in the target Vault.

Click on a Deployment Action to view detailed comparison and dependencies for each component in a pop-out viewer.

Deployment Notifications

If Vault is processing component configuration updates during Review & Deploy, it displays a warning message on the Review and Select Steps and Deployment Confirmation pages.

Deployment actions and statuses may not be accurate while Vault is processing component configuration updates, and deploying a package before processing is complete may result in deployment errors. We recommend waiting until configuration updates finish processing before completing a deployment.

Deployment Errors

Although most deployment errors can be avoided by reviewing the Validation Log and Package Component Comparison, deployment errors can still occur. When Vault encounters an error during a package deployment, it stops the deployment but does not revert any configuration changes it has already made.

To resolve the error and resume the deployment:

Review the deployment log to understand what caused the error. A link to this appears in the notification. The log is also attached to the inbound package. You can download it from the inbound package’s detail page.
Address the cause of the error. Depending on the error, you might need to deploy a different package that includes required components or manually make a configuration change. See details for resolving specific errors and warnings.
Return to the package with the error in Inbound Packages. From the actions menu, choose Deploy.
Vault restarts the process where it stopped on the previous deployment.

Component Deployment Order

If you are building a single configuration migration package, Vault handles ordering of components automatically. When building multiple configuration migration packages, however, building them with the right deployment order is essential to a successful migration project. Contact Veeva Managed Services if you are unable to resolve an ordering problem.

Component Names

Error and warning messages that occur when deploying packages refer to components by their name, rather than their label. Usually, names are based on labels and the connection should be clear. Sometimes, the names are not clear.

In these situations, you can see the component’s name in its configuration details. For example, you can find document field names in Admin > Configuration > Document Fields or object workflow names in Admin > Configuration > Object Workflow > Details.

Note: Names are not available through the UI for document types. If the name is not clear, you may have to find the component label through the API.

Component Types

See Component Types for the list of configuration elements that Vault configuration migration supports. Migration package limitations and considerations for some component types are described below.

Document Fields

When migrating document fields, Vault does not include security overrides that reference Auto Managed Groups in configuration migration packages but does include any other security overrides not based on Auto Managed Groups.

Document Lifecycle

When migrating document lifecycles, keep the following rules in mind:

Lifecycle Role Assignment Rules are not included in the Doclifecycle component type. You will need to migrate your Default Rules and Override Rules using the Lifecycle Role Assignment Rules API.

Document Workflows

When migrating document workflows, keep the following rules in mind:

You can only migrate document workflows in Active status. If the workflow is currently in editing mode in the source Vault, the outbound package will include the last active version of the workflow.
You cannot migrate document workflows between Limited Release and General Release Vaults unless they are on the same version of Vault. This only occurs immediately after the general release.
You cannot migrate document workflows from one lifecycle to another. Configuration migration may not work across application families, as they depend on component names that may not be the same in all families. We recommend refreshing sandbox and test environments from a clone of production before making configuration changes.
If activation fails, Vault updates the status to Editing in the target Vault and logs an error in the deployment log.

Jobs

When migrating job definitions, keep the following rules in mind:

Job definitions in the Active state will deploy as Active.
If activation fails, Vault updates the status to Inactive in the target Vault and logs an error in the deployment log.
Job definitions in the Inactive state will deploy as Inactive.

Active job definitions immediately begin running, potentially before the deployment is complete. Only deploy job definitions in the Active state if you know they will not interfere with your deployment.

Object Types

When migrating object types, keep the following rules in mind:

An object must have object types enabled before adding an object type to the package.
A new, default object type can be set after the object type is added.
When migrating from a Vault with object types, exclude the Base (base__v) object type from the package. Vault automatically creates this object type.

Object Lifecycles

When you migrate an object that has an associated Object Lifecycle, Vault creates a temporary Placeholder Lifecycle in the target Vault. That placeholder is associated with the object and has the same public key as the source Vault’s object lifecycle, but the placeholder is Inactive. When importing the Object Lifecycle, Vault overwrites the Placeholder Lifecycle and activates the new Object Lifecycle.

To migrate an Object Lifecycle, you must include the Lifecyclestatetype components and the lifecycle’s Lifecyclestatetypeassociation components in your VPK. If you don’t include these, you’ll see an error when you create object records. You’ll need to associate object state types with lifecycle states manually in the target Vault.

Object Workflows

When migrating object workflows, keep the following rules in mind:

Migrated object workflows will have an Active status in the target Vault. If the object workflow is in Editing status in the source Vault, and no workflow exists in the target Vault, the workflow will remain in Editing status.
If activation fails, Vault updates the status to Editing in the target Vault and logs an error in the deployment log.
If you are importing a VPK from a 17R3 Vault that contains an object workflow with eSignatures, you’ll first need to enable eSignatures on that object in your target Vault.

Saved View

Only saved custom views marked as managed as part of Vault configuration are eligible for migration.

Searchable Object Fields

Searchable object fields are included when migrating objects. You must only include custom fields in a package.

The following permissions control actions for migration packages:

Type	Permission Label	Controls
Security Profile	Admin: Migration Packages: Create	Ability to create packages for configuration or data migration; you'll need this permission on the source Vault.
Security Profile	Admin: Migration Packages: Deploy	Ability to deploy packages for configuration or data migration; you'll need this permission on the target Vault.
Security Profile	Admin: Various	Ability to create or edit various components. When deploying packages, you'll need the same permissions that you'd need if you were manually creating the components, for example, Admin > Picklists > Edit to deploy a package that includes the picklist component.
Security Profile	Objects: Outbound Package: Read	Ability to view the Outbound Package object. You must also have Read permission on all fields for this object.
Security Profile	Objects: Inbound Package: Read	Ability to view the Inbound Package object. You must also have Read permission on all fields for this object.
Security Profile	Objects: Inbound Package Step: Read	Ability to view the Inbound Package Step object. You must also have Read permission on all fields for this object.
Security Profile	Objects: Inbound Package Data: Read	Ability to view the Inbound Package Data object. You must also have Read permission on all fields for this object.
Security Profile	Objects: Inbound Package Component: Read	Ability to view the Inbound Package Component object. You must also have Read permission on all fields for this object.

The standard Vault Owner and System Admin security profiles have all of the necessary permissions.