Using Configuration Migration Packages

With configuration migration packages, you can migrate configuration changes or test data between two Vaults. This feature is 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.

How to Enable Configuration 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.

About Outbound Package Types

You can choose to create either a Migration or Test Data package.

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.
Test Data packages contain only data and are particularly useful for preserving object data when refreshing a sandbox Vault.

How to Create & Export Packages

When you create an outbound package, you’re exporting configuration elements from the current Vault. To create an outbound package:

Navigate to Admin > Deployment > Outbound Packages and click Create.
Select an Outbound Package Type. See about outbound package types.
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 for Migration packages: 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.
If you are creating a Migration package, 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 specify a new data step for this 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 for Migration packages: 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 for Migration packages: 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.
Open the actions menu and 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

Adding datasets to an outbound migration package allows you to include both components and object data to move as a group 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.

You can use an outbound test data package to migrate object data, including object relationships. For example, the grandparent, parent, and child relationship between Study, Country, and Site. Test data packages leverage the Global ID and Link fields to migrate data.

Although the User object is available in both migration and test data 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.
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 records in a noninitial state for objects with lifecycles. Additionally, Vault bypasses validation rules and reference constraints when creating records in migration mode. You can only use Record Migration Mode with the Create action.
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.

How to Import & Validate Packages

Note: We recommend enabling Configuration Mode while completing the following tasks.

To import and validate a 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.

How to Deploy a Package

From the Actions menu, 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.

How to Export 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.

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 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.

How to Resolve 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 roll back any configuration changes it already made.

To resolve the error and complete 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 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 Types

See Component Types for the list of configuration elements that Vault configuration migration supports.

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.

Details for Document Field Migration

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.

Details for Document Lifecycle Migration

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.

Details for Document Workflow Migration

When migrating workflows, keep the following rules in mind:

You can only migrate 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 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 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.

Details for Object Type Migration

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.

Details for Object Lifecycle Migration

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.

Details for Object Workflow Migration

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

Migrated object workflows will have an Inactive status in the target Vault. After the deployment, you must activate them manually.
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.

Details for Saved View Migration

Only saved views marked as required are eligible for migration.

Details for Searchable Object Field Migration

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

Details for Group Migration

When migrating groups, keep the following in mind:

You can only migrate groups using datasets within a Migration or Test Data package. Vault does not support related object migration for groups.
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 within a Migration or Test Data package. However, Vault may add or remove group members automatically depending on the security profile included for the migrated group.

The following permissions control actions for Configuration Migration Packages:

Type	Permission Label	Controls
Security Profile	Admin: Migration Packages: Create	Ability to create packages for configuration migration; you’ll need this permission on the source Vault.
Security Profile	Admin: Migration Packages: Deploy	Ability to deploy packages for configuration 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.