# 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](/en/lr/20673/). Configuration migration packages and the **Admin > Deployment** tab are available in all Vaults. ## How to Create & Export Migration Packages {#how-to-create-and-export-packages} To create an outbound migration package: 1. Navigate to **Admin > Deployment > Outbound Packages** and click **Create**. 2. In the dialog, select **Migration** as the **Outbound Package Type**. 3. Enter a **Summary** to help you and other users understand the purpose and contents of this package. 4. 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. 5. 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. 6. Click **Save**. Vault opens the package details page. 7. Navigate to the **Components** section. Click **Add** to specify components for this package. In the dialog, use the checkboxes to add or remove components. To search for components by name, filter by _Component Name_ or _Name_. The filters are case-sensitive. You can add up to 200 components to a single package. 8. Navigate to the **Data** section. Click **Add** to add a new [dataset][6] 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. 9. 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_. 10. 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**. 11. Optional: Navigate to the **Packages** section. Click **Upload** to store the exported VPK. 12. 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][13], 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](/en/lr/40902/) can automatically create Outbound Packages based on the differences between the source Vault and target Vault. ## About Datasets {#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_](/en/lr/58176/) 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](/en/lr/26597/) 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: 1. 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][3] to a dataset. 2. Optional: Click **Add Related Objects** to select from a list of applicable outbound and inbound relationships. 3. 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: 1. From the **Outbound Package** detail page, click the dataset. 2. From the desired object, select **Edit** from the **Actions** menu. 3. 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. 4. 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. 5. Optional: Select the [**Record Migration Mode**](/en/lr/761685/) 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_. 6. 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](/en/lr/31536/#using-where-clause-filters). 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. 7. 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. 8. Click **Save**. ### Adding Groups to Datasets {#adding-groups} If [groups](/en/lr/3200/) 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](/en/lr/3200/#system-provided-groups), but you can update existing system-managed groups. * You cannot export, create, or update [Auto Managed Groups](/en/lr/3200/#auto-managed). * 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 {#import} To import and validate a migration package: 1. Navigate to **Admin > Deployment > Inbound Packages** and click **Import**. 2. Find and select the exported VPK file on your computer. 3. 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. 4. To validate an existing inbound package, select **Validate** from the **Actions** menu next to the inbound package **Name**. ### About the Validation Log {#validation-logs} 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 {#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 {#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: 1. Navigate to **Admin > Deployment > Inbound Packages**. 2. From the **Actions** menu on the package name or in the package detail page, select **Package Component Comparison**. 3. 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](/en/lr/40902/).
## How to Deploy a Migration Package {#deploy} 1. Recommended: Enable [Configuration Mode](/en/lr/36928/) to lock non-Admin users out of Vault while deploying inbound packages. 2. From the **Actions** menu of the inbound package, select **Review & Deploy**. Vault displays a list of all components in the package. 3. Review the _[Deployment Status][10]_ and _[Deployment Action][11]_ for each item. To exclude specific steps, clear their checkbox. 4. Optional: To reorder steps, click **Reorder**, enter the desired step number in the **Step** field, then click **Save**. 5. Click **Next**. Depending on your Vault's configuration, Vault may prevent you from clicking **Next** if a package step's _Deployment Status_ is _Blocked_. 6. On the confirmation page, review and click **Finish**. ### Deployment Status {#deploy-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][12]. * **Blocked**: Vault is unable to deploy the VPK because of missing or incorrectly ordered dependencies. ### Deployment Action {#deploy-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 {#review-deploy-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 {#error} Although most deployment errors can be avoided by reviewing the [Validation Log][4] and [Package Component Comparison][5], 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: 1. 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. 2. 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](/en/lr/39591/). 3. Return to the package with the error in **Inbound Packages**. From the actions menu, choose **Deploy**. 4. 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**.
## Component Types See [Component Types](/en/lr/43899/) 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](/en/lr/2942/) that reference [Auto Managed Groups](/en/lr/3200/#auto-managed) in configuration migration packages but does include any other security overrides not based on Auto Managed Groups. ### Document Lifecycles {#doclifecycle} 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 {#workflow} 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 {#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. Additional considerations apply when [migrating flash reports][7] and their associated job definitions. ### 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](/en/lr/30683/#state-type) manually in the target Vault. ### Object Types When migrating object types, keep the following rules in mind: * An object must have [object types enabled](/en/lr/32857/#enable) 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 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](/en/lr/46676/) in your target Vault. ### Permission Sets When migrating permission sets, Vault includes permissions for locked objects. Though the objects remain locked, importing a configuration migration package with locked object permissions does not impact the ability to successfully import the package. ### Reports {#reports} To migrate flash reports, include the associated _Report_ component and [job definition][1] in the migration package. When migrating flash reports, keep the following rules in mind: * If you add a flash report to a package without its associated job, the job is displayed as a dependency when using the _View/Add Dependencies_ () option. * _Active_ flash reports jobs are migrated as _Active_ in the target Vault and scheduled using the current job schedule. * If a flash report is migrated and its associated job is not, the report is migrated as a regular report. * If the flash report's _Runs As_ user is unavailable in the target Vault, the migrating user is set as the _Runs As_ user. ### Saved Views 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. ## Related Permissions 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. This permission is required on the source Vault. | | Security Profile | Admin: Migration Packages: Deploy | Ability to deploy packages for configuration or data migration. This permission is required 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: All Objects: Read | Ability to view the _Data_ section on packages. | | 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. [1]: #jobs [2]: #package-types [3]: #adding-groups [4]: #validation-logs [5]: #package-component-comparisons [6]: #datasets [7]: #reports [10]: #deploy-status [11]: #deploy-action [12]: #error [13]: #how-to-create-and-export-packages