Skip to main content
hamburger menu Created with Sketch.
PHP2Shell - PHP Vulnerability Announcement

Search the Knowledge Base

Importing & Deploying Vault Configuration Migration Packages

  • Updated

Introduction:

This article is pertaining to Importing and deploying Vault Configuration Migration packages.

Importing & Deploying Configuration Migration Packages

Before starting any deployment, make sure to enable the Configuration Mode setting in your Vault. Import & deploy migration packages individually. If there are multiple packages in the deployment, some components in a subsequent package may be dependent on a component in a previous package. Subsequent packages should be re-validated if they depend on previously deployed ones. Vault Loader steps may also be required to prepare and update data in the target Vault prior to configuration updates.

Reference: About Configuration Mode

6942568861782773760.png

 

When the deployment status of the Inbound Package is Blocked, it is likely due to missing dependencies.  Download and review the Validation log for which the deployment step failed validation. Dependencies and their validation status are listed in each component deployment step in the validation log.

Once the missing dependency is determined, add it to the outbound package and re-export the VPK file.

6942569051579224064.png

Generate a package component comparison report that compares the package contents to the target Vault’s current configuration. Confirm the incoming changes.

6942569308769751040.png

When the deployment status of the Inbound Package is Verified, Review & Deploy starts the deployment process.

6942569404894810112.png

When a deployment is completed, the user receives a notification and the deployment status of the package is Deployed. 

 

Deployed with warnings:

When the deployment status is received on the inbound package, it means that the deployment is successful and each step deployed successfully.  However, some steps provide more information about the behavior of the update. These warnings should be reviewed. Find the warnings in the deployment log.

6942569530681987072.png

 

References:

Package Deployment: Re-ordering Deployment Steps on Inbound Packages that are Blocked

Within the Review & Deploy process, update the step order for each step in the deployment.

It may be necessary to re-order steps in the package that contain component steps that are dependent on other steps within the package or contain circular dependencies. Re-order the data steps so that dependent steps are deployed before the components that depend on them.

ConfigMgmtProductBestPractice-DataCircDep2a.gif

Circular References between Components in Configuration Migration Packages

When the configuration of two components reference each other, then a circular dependency exists between the two components. When circular references exist in the configuration migration package, Vault cannot guarantee the correct step order for each component. The package may result in a Blocked deployment status.  

This is where some extra steps are needed to complete the deployment successfully.  This requires that multiple packages be prepared and documented in the deployment process with different configuration versions of the components referencing each other. This is ideal for circular references that can be isolated, removed, and re-added in the source Vault.

For a circular dependency that exists between two objects (Applications and Marketing Campaigns) whereby each object has an object reference field to the other:

  1. In the development Sandbox, remove the circular reference between Applications and Marketing Campaigns in the object configuration UI. One of the objects can keep the reference field.
  2. Create and export a configuration migration outbound package that contains Applications, Marketing Campaigns, and all dependent components for the target Vault. Document this package.

    6942575987922046976.png

  3. Add the circular reference between Applications and Marketing Campaigns in the object configuration UI. Both objects should now be referencing each other again.
  4. Create and export a configuration outbound package that only contains the object component for the object that is updated in Step 3. Document this package.

    6942576439237545984.png

  5. Import & deploy the package that does not contain the circular reference from step 2.

    ConfigMgmtProductBestPractice-DeployWarningsgif.gif

  6. Import & deploy the package that contains the circular reference from step 4.

    ConfigMgmtProductBestPractice-DeployGood.gif

 

Alternatively, update the deployment checklist with manual configuration steps in the target Vault’s web interface to create the circular reference configuration after the components are deployed in a package without the circular reference. This is ideal if it is not possible to export different versions of the component configuration from a source Vault.

 

Circular Reference Data in Configuration Migration Package Datasets

Circular references in your dataset configuration can also exist and require some extra steps. To deploy a dataset in your package with circular references you will need to add multiple datasets to your outbound package configuration.

  1. Add a new data set that only includes an UPSERT action for the Application object and remove the Marketing Campaigns reference field from the dataset configuration.

    ConfigMgmtProductBestPractice-DataCircDep.gif

  2. Add another data step that contains Application as the primary object and Marketing Campaign as a related object.
  3. Configure the Application object’s action to UPDATE and only include the Marketing Campaign Reference Field and the Application name__v field.  The Marketing Campaign object should be configured as an UPSERT with all editable fields included.

    ConfigMgmtProductBestPractice-DataCircDep2.gif

  4. When this package is exported and imported, notice on the Review & Deploy step that the order of the steps is incorrect. 
  5. Re-order these steps so that the sequence is as follows:
    1. UPSERT the Application object.
    2. UPSERT the Marketing Campaign object.
    3. UPDATE the Application object.

      ConfigMgmtProductBestPractice-DataCircDep3.gif

Vault Loader Steps in the Deployment Checklist

Deployments usually require data to be updated in the target Vault to enable incoming configuration updates. Use Vault Loader Extract and Load from the target Vault to update the target Vault's object data.  For instance, it may be necessary to remove data from fields populated in object records to enable the configuration update to remove an object field. The deployment checklist should have the precise steps to run these tasks in the deployment process.    

Related Documentation:

 

Powered by Zendesk