Creating Custom Configuration Migration Packages

This guide provides instructions on how to manually edit existing configuration migration packages (VPKs) to create custom VPKs. You can find instructions for creating and deploying Vault-generated VPKs in Vault Help.

Prerequisites

Section link for Prerequisites

Before you begin, ensure that you are able to change file extensions and zip and unzip files.

Changing the File Extension

Section link for Changing the File Extension

As a prerequisite to creating custom VPKs, you must be able to change the extension of files.

1. Enable file name extensions as follows:

   Enable file name extensions by opening File Explorer and selecting View > Show > File name extensions.

   Enable showing all filename extensions by opening Finder and selecting Finder > Settings > Advanced > Show all filename extensions.

2. Once it is visible, you can use Rename to change the file extension to .vpk for the package. Or, you can also use the terminal with the following command:

   Copy to clipboard

   ren my_vpk_package.zip my_vpk_package.vpk

   Copy to clipboard

   mv my_vpk_package.zip my_vpk_package.vpk

Extracting and Packaging VPK Content

Section link for Extracting and Packaging VPK Content

Configuration migration packages (VPKs) are structured as ZIP archives, and their content can be extracted (unzipped) and packaged (zipped) with any conventional tool that handles .zip files. These steps are not required when working with Vault-generated VPKs that you do not wish to modify.

Extracting VPK Content

Section link for Extracting VPK Content

You can extract VPK content by renaming the file from pkg_name.vpk to pkg_name.zip on your computer, and then unzipping the archive.

Packaging VPK Content

Section link for Packaging VPK Content

You can package VPKs by creating a ZIP archive. VPKs must have at least one components folder or one javasdk folder (or both) to be a valid package. When all steps are ready to package, select the components folder, javasdk folder, and the vaultpackage.xml file and compress them into a .zip file. Then change the file extension from .zip to .vpk. Learn more about VPK contents.

Creating Your First Custom VPK

Section link for Creating Your First Custom VPK

Perform the following steps to create a new Picklist component and deploy it with a VPK that you can import to any Vault:

1. Create a folder where you will build the VPK, for example, my-first-vpk.

2. In the my-first-vpk folder, create a folder called components.

3. In the my-first-vpk > components folder, create a folder called 00010. This folder represents the first deployment step.

4. Open a new file in a text editor and paste the following MDL to create a Picklist component:

   Copy to clipboard

   RECREATE Picklist my_first_picklist__c ( label('My First Picklist'), active(true), can_add_values(true), can_reorder_values(true), Picklistentry my_first_picklistentry__c( value('My First Picklistentry'), order(1), active(true) ) );

5. Save the file in the my-first-vpk > components > 00010 folder as Picklist.my_first_picklist__c.mdl

6. Open a new file in a text editor where we’ll create the MD5 Checksum file.

7. Generate the MD5 checksum for the Picklist.my_first_picklist__c.mdl file.

8. Paste the MD5 checksum to the text editor, followed by a space and Picklist.my_first_picklist__c, as shown below:

   Copy to clipboard

   <md5_checksum_value> Picklist.my_first_picklist__c

9. Save the file as Picklist.my_first_picklist__c.md5 in the my-first-vpk > components > 00010 folder.

10. Open a new file in the text editor and paste the following XML:

    Copy to clipboard

    <vaultpackage xmlns="https://veevavault.com/"> <name>my-first-vpk-package</name> <source> <vault>999999</vault> <author>your.email@yourcompany.com</author> </source> <packagetype>migration__v</packagetype> <summary>My First VPK Package</summary> <description></description> </vaultpackage>

11. Save the file as vaultpackage.xml in the my-first-vpk folder.

12. Select the vaultpackage.xml file and the components folder and create a ZIP archive from them with your preferred method.

13. Change the extension of the file from .zip to .vpk.

14. Within Vault, import the VPK package by navigating to Admin > Deployment > Inbound Packages and clicking Import.

15. Deploy the VPK package by clicking the imported package, clicking Review & Deploy, and following the on-screen instructions.

16. Once the deployment is complete, verify the existence of the new picklist in Business Admin.

Troubleshooting Deployments

Section link for Troubleshooting Deployments

When deploying VPKs, you may encounter errors and warning messages. The most common ones are documented in Configuration Migration Errors & Warnings. If you have trouble understanding an error message, you can reach out to the Vault Developer Support Community on Veeva Connect.