Using Configuration Migration Packages

Using Configuration Migration Packages, you can migrate configuration changes 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 three settings involved:

  • Enable Component Directory: This setting must be on for the source and target vaults.
  • 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 for the Deployment tab to appear.

How to Create & Export Packages

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

  1. Navigate to Admin > Deployment > Outbound Packages and click Create.
  2. Enter a Summary to help you and other users understand the purpose and contents of this package.
  3. 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.
  4. Click Save. Vault opens the package details page.
  5. Find the Components section. Click Add to specify components for this package. In the pop-up, click the plus (+) icon to add components and the minus (-) icon to remove them. You can add up to 50 components to a single package.
  6. Optional: Find the Packages section. Click Upload to upload and attach additional files, for example, documentation explaining changes in the package configuration.
  7. Open the actions menu and select Export.
  8. Vault downloads a VPK file to your computer. Note that modifying this file after download will cause the import and deployment process to fail.

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 object field _Location Type _without first creating the picklist it uses. We recommend exporting and deploying the complete configuration as a single package to prevent issues with dependencies.

How to Import & Deploy Packages

We recommend enabling Configuration Mode while completing the following tasks.

To import and deploy a package:

  1. Navigate to Admin > Deployment > Inbound Packages and click Import.
  2. Find and select the exported VPK file on your computer.
  3. Vault opens the details page for the selected package.
  4. From the actions menu, select Review & Deploy. Vault displays a list of all components in the package.
  5. Review the Deployment Status and Deployment Action for each item. To exclude specific components, clear their checkbox.
  6. Click Next.
  7. On the confirmation page, review and click Finish.

How to Export Package Comparisons

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

Deployment Status

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

  • Verified: The package’s component matches the source vault, but has not yet been deployed.
  • Deployed: Vault successfully deployed the component’s configuration on the target vault.
  • 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.
  • Skipped: When deploying, the user chose to skip this component.
  • Error: Vault encountered an error when deploying the package. See error details.

Deployment Action

Vault determines Deployment Action of an inbound package by comparing the components already on the target vault to the components in the package. Deployment Action displays on the Review and Select Components and Confirmation steps during _Review & Deploy. _Unlike Deployment Status, Deployment Action only exists at the component level, for each component of the package.

  • Add: This is a new component that the package will add to the target vault.
  • 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. For these actions, you can click View comparison to see details of the component update. This option is available on all component types except Workflow and Permissionset.
  • No Change: The component in the package is identical to a component that already exists in the target vault.
  • Not Authorized: This is a standard component. You cannot include standard components in the package.

How to Resolve Deployment Errors

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:

  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 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.
  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 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 object field names in at the Admin > Configuration > Objects > {Object} > Fields or object workflow names in Admin > Configuration > Object Workflows > Details panel.

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.

Details for Object Type Migration

Vault cannot migrate the base__v object type. Vault automatically creates this object type. When migrating from a vault with object types, you should not add the Base (base__v) object type to the package.

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

Details for Saved View Migration

Only saved views shared or marked as required are eligible for migration.