Vlocity Build is a command line tool to export and deploy Vlocity DataPacks in a source control friendly format through a YAML Manifest describing your project. Its primary goal is to enable Continuous Integration for Vlocity Metadata through source control. It is written as a Node.js Command Line Tool.
- Installation Instructions
- Getting Started
- Step by Step Guide
- The Job File
- Troubleshooting
- All Commands
- Advanced Job File Settings
- Supported DataPack Types
- Advanced
Download and Install Node at:
https://nodejs.org/
This project requires Node Version 8+.
Use node -v to find out which version you are on.
Inside the Git repository you have cloned run the following command:
npm install
npm link
vlocity helpThis should show a list of all available commands confirming that the project has been setup successfully.
To begin, create your own property files for your Source and Target Salesforce Orgs with the following:
sf.username: <Salesforce Username>
sf.password: <Salesforce Password> When you (or your CI/CD server) is behind a proxy you can specify the proxy URL with a Username and password by adding the below line to your property file:
sf.httpProxy: http://[<Proxy server Username>:<Proxy server Password>@]<Proxy hostname>[:<Proxy Port>]It is best to not rely on a single build.properties file and instead use named properties files for each org like build_source.properties and build_target.properties
Commands follow the syntax:
vlocity packExport -propertyfile <filepath> -job <filepath>The propertyfile is used to provide the credentials of the org you will connect to. It will default to build.properties if no file is specified.
The Job File used to define the project location and the various settings for running a DataPacks Export / Deploy.
Once you have your build_source.properties file setup, you can get started with mirgation with the following:
Example.yaml shows the most Simple Job File that can be used to setup a project:
projectPath: ./example_vlocity_build
queries:
- VlocityDataPackType: DataRaptor
query: Select Id from %vlocity_namespace%__DRBundle__c where Name = 'DataRaptor Migration' LIMIT 1Run the following command to export this Job File:
vlocity -propertyfile build_source.properties -job dataPacksJobs/Example.yaml packExportWhich will produce the following output:
Salesforce Org >> source_org@vlocity.com
VlocityDataPackType >> DataRaptor
Query >> Select Id from vlocity_cmt__DRBundle__c where Name = 'DataRaptor Migration' LIMIT 1
Records >> 1
Query Total >> 1
Initializing Project
Exporting >> DataRaptor a191N000012pxsYQAQ
Creating file >> example_vlocity_build/DataRaptor/DataRaptor-Migration/DataRaptor-Migration_DataPack.json
Salesforce Org >> source_org@vlocity.com
Current Status >> Export
Successful >> 1
Errors >> 0
Remaining >> 0
Elapsed Time >> 0m 5s
Salesforce Org >> source_org@vlocity.com
Export success:
1 Completed
This has exported data from the org specified in your build_source.properties file and written it to the folder example_vlocity_build specified in the Example.yaml file found at dataPacksJobs/Example.yaml
To deploy the data you just exported run the following command:
vlocity -propertyfile build_target.properties -job Example.yaml packDeployWhich will produce the following output:
Salesforce Org >> target_org@vlocity.com
Current Status >> Deploy
Adding to Deploy >> DataRaptor/DataRaptor Migration - DataRaptor-Migration
Deploy Success >> DataRaptor/DataRaptor Migration - DataRaptor-Migration
Salesforce Org >> target_org@vlocity.com
Current Status >> Deploy
Successful >> 1
Errors >> 0
Remaining >> 0
Elapsed Time >> 0m 4s
Salesforce Org >> target_org@vlocity.com
A Job File is similar to a Salesforce package.xml file, however it also includes runtime options like the maximum number of concurrent API calls running.
The Default Job Settings will automatically be used if not explicitly specified in your file, and it is best to not add settings to the file unless you want to change them from the defaults.
The Job File's primary settings that you should define is specifying the folder that you would like to use to contain your project.
projectPath: ../myprojectPath The projectPath can be the absolute path to a folder or the relative path from where you run the vlocity command.
By default, all data will be exported from the org when running the packExport command. To narrow the exported data, you can define any Salesforce SOQL query that returns the Id of records you would like to export.
queries:
- VlocityDataPackType: DataRaptor
query: Select Id from %vlocity_namespace%__DRBundle__c where Name LIKE '%Migration' LIMIT 1This query will export a DataRaptor Vlocity DataPack by querying the SObject table for DataRaptor DRBundle__c and even supports the LIMIT 1 and LIKE syntax.
projectPath: ./example_vlocity_build
queries:
- VlocityDataPackType: DataRaptor
query: Select Id from %vlocity_namespace%__DRBundle__c LIMIT 1When creating your own Job File, the only setting that is very important is the projectPath which specifies where the DataPacks files will be written.
All other settings will use the Default Project Settings.
By Default, all DataPack Types will be Exported when running packExport, so to override the Export data, it is possible to use predefined queries, or write your own.
Vlocity has defined full queries for all Supported DataPack Types which will export all currently Active Vlocity Metadata. This is the most simple way to define your own Job File queries.
To Export All DataRaptors and OmniScripts from the Org use:
projectPath: ./myprojectPath
queries:
- DataRaptor
- OmniScriptThis predefined syntax is defined in dataPacksJobs/QueryDeifnitions.yaml and will load the following explicit queries:
queries:
- VlocityDataPackType: DataRaptor
query: Select Id, Name from %vlocity_namespace%__DRBundle__c where %vlocity_namespace%__Type__c != 'Migration'
- VlocityDataPackType: OmniScript
query: Select Id, %vlocity_namespace%__Type__c, %vlocity_namespace%__SubType__c, %vlocity_namespace%__Language__c from %vlocity_namespace%__OmniScript__c where %vlocity_namespace%__IsActive__c
= true AND %vlocity_namespace%__IsProcedure__c = falseThe WHERE clauses show that these Queries will Export all DataRaptors that are not internal Vlocity Configuration Data and all Active OmniScripts.
When Exporting, the DataPacks API will additionally export all dependencies of the Vlocity DataPacks which are being exported. So Exporting just the OmniScripts from an Org will also bring in all referenced DataRaptors, VlocityUITemplates, etc, so that the OmniScript will be fully usable once deployed.
Running packExport with no queries defined in your Job File will export all the predefined queries for each type. If you do have some special queires defined, you can also run: packExportAllDefault to specify running all the default queries.
Once Exported it is very important to validate that your data is in state that is ready to be deployed. The Vlocity Build tool primarily relies on unique data in fields across the different objects to prevent duplicate data being uploaded.
Generally errors will be due to missing or incorrect references to other objects.
Error >> DataRaptor --- GetProducts --- Not Found
Error >> VlocityUITemplate --- ShowProducts --- Not Found
This "VlocityUITemplate --- ShowProducts --- Not Found" error during Export means that something, likely an OmniScript, has a reference to a VlocityUITemplate that is not currently Active or does not exist in the org as a VlocityUITemplate. In some cases the VlocityUITemplate for an OmniScript can actually be included inside the Visualforce Page in which the OmniScript is displayed. In that case, this error can be completely ignored. The DataRaptor Not Found means that likely someone deleted or changed the name of the DataRaptor being referenced without updating the OmniScript using it.
Errors occurring during Export will likely result in Errors during deploy. But not always. Errors during Deploy will occur when a Salesforce Id reference is not found in the target system:
Deploy Error >> Product2/02d3feaf-a390-2f57-a08c-2bfc3f9b7333 --- iPhone --- No match found for vlocity_cmt__ProductChildItem__c.vlocity_cmt__ChildProductId__c - vlocity_cmt__GlobalKey__c=db65c1c5-ada4-7952-6aa5-8a6b2455ea02
In this Error the Product being deployed is the iPhone with Global Key 02d3feaf-a390-2f57-a08c-2bfc3f9b7333 and the error is stating that one of the Product Child Items could not find the referenced product with Global Key db65c1c5-ada4-7952-6aa5-8a6b2455ea02. This means the other Product must also be deployed.
Additionally, Deploys will run all of the Triggers associated with Objects during their import. As their are various rules across the Vlocity Data Model, sometimes errors will occur due to attempts to create what is considered "bad data". These issues must be fixed on a case by case basis.
This tool includes a script to help find and eliminate "bad data". It can be run with the following command:
vlocity -propertyfile <propertyfile> -job <job> runJavaScript -js cleanData.jsThis will run Node.js script that Adds Global Keys to all SObjects missing them, and deletes a number of Stale data records that are missing data to make them useful.
Most objects being deployed have a field or set of fields used to find unique records like an External Id in Salesforce. For many Vocity Objects this is the Global Key field. If a Deploy finds 1 object matching the Global Key then it will overwrite that object during deploy. If it finds more than 1 then it will throw an error:
Deploy Error >> Product2/02d3feaf-a390-2f57-a08c-2bfc3f9b7333 --- iPhone --- Duplicate Results found for Product2 WHERE vlocity_cmt__GlobalKey__c=02d3feaf-a390-2f57-a08c-2bfc3f9b7333 - Related Ids: 01t1I000001ON3qQAG,01t1I000001ON3xQAG
This means that Duplicates have been created in the org and the data must be cleaned up.
While there are protections against missing or duplicate Global Keys the logic is often in triggers which may have at points been switched off, and sometimes applies to data that may have existed before the Vlocity Package was installed.
You can fix missing GlobalKeys by running the following command which will start a set of Batch Jobs to add Global Keys to any Objects which are missing them:
vlocity -propertyfile <propertyfile> -job <job> runApex -apex AllGlobalKeysBatch.clsHowever, when you are attempting to migrate data from one org to another where both orgs have missing GlobalKeys, but existing data that should not be duplicated, a different strategy may need to be used to produce GlobalKeys that match between orgs.
Ultimately the best validation for a deploy will be testing the functionality directly in the org. However, another way to see any very clear potential issues is to see if recently deployed data matches exactly what was just exported.
You can run the following command to check the current local data against the data that exists in the org you deployed to:
vlocity -propertyfile build_uat.properties -job Example.yaml packGetDiffsThis will provide a list of files that are different locally than in the org. In the future more features will be added to view the actual diffs.
packExport: Export from a Salesforce org into a DataPack Directory
packExportSingle: Export a Single DataPack by Id
packExportAllDefault: Export All Default DataPacks as listed in Supported Types Table
packDeploy: Deploy all contents of a DataPacks Directory
packContinue: Continues a job that failed due to an error
packRetry: Continues a Job retrying all deploy errors or re-running all export queries
packGetDiffsAndDeploy: Deploy only files that are modified compared to the target Org
packGetDiffs: Find all Diffs in Org Compared to Local Files
packBuildFile: Build a DataPacks Directory into a DataPack file
runJavaScript: Rebuild all DataPacks running JavaScript on each or run a Node.js Script
packUpdateSettings: Refreshes the DataPacks Settings to the version included in this project. Recommended only if you are on the latest Major version of the Vlocity Managed Package
runApex: Runs Anonymous Apex specified in the option -apex at the specified path or in the /apex folder
packGetAllAvailableExports: Get list of all DataPacks that can be exported
refreshVlocityBase: Deploy and Activate the Base Vlocity DataPacks included in the Managed Package
packExport will retrieve all Vlocity Metadata from the org as Vlocity DataPacks as defined in the Job File and write them to the local file system in a Version Control friendly format.
vlocity -propertyfile <filepath> -job <filepath> packExportpackExportSingle will export a single DataPack and all its dependencies. It also supports only exporting the single DataPack with no dependencies by setting the depth.
vlocity -propertyfile <filepath> -job <filepath> packExportSingle -type <VlcoityDataPackType> -id <Salesforce Id> -depth <Integer>Max Depth is optional and a value of 0 will only export the single DataPack. Max Depth of 1 will export the single DataPack along with its first level depedencies.
packExportAllDefault will retrieve all Vlocity Metadata instead of using the Job File definition.
vlocity -propertyfile <filepath> -job <filepath> packExportAllDefaultpackDeploy will deploy all contents in the projectPath of the Job File to the Salesforce Org.
vlocity -propertyfile <filepath> -job <filepath> packDeploypackContinue can be used to resume the job that was running before being cancelled or if there was an unexpected error. It will work for Export or Deploy.
vlocity -propertyfile <filepath> -job <filepath> packContinuepackRetry can be used to restart the job that was previously running and will additionally set all Errors back to Ready to deployed again.
vlocity -propertyfile <filepath> -job <filepath> packRetrypackGetDiffs will provide a list of files that are different locally than in the org. In the future more features will be added to view the actual diffs.
vlocity -propertyfile <filepath> -job <filepath> packGetDiffspackGetDiffsAndDeploy will first find all files that are different locally than in the target Org, and then will deploy only the DataPacks that have changed or are new.
vlocity -propertyfile <filepath> -job <filepath> packGetDiffsAndDeployWhile this may take longer than doing an actual deploy, it is a great way to ensure that you are not updating items in your org more than necessary.
The Job File has a number of additonal runtime settings that can be used to define your project and aid in making Exports / Deploys run successfully. However, the Default settings should only be modified to account for unique issues in your Org.
projectPath: ../my-project # Where the project will be contained. Use . for this folder. The Path is always relative to where you are running the vlocity command, not this yaml file
expansionPath: datapack-expanded # The Path relative to the projectPath to insert the expanded files. Also known as the DataPack Directory in this DoecumentationExports can be setup as a series of queries or a manifest.
Queries support full SOQL to get an Id for each DataPackType. You can have any number of queries in your export. SOQL Queries can use %vlocity_namespace%__ to be namespace independent or the namespace of your Vlocity Package can be used.
queries:
- DataRaptor
- VlocityDataPackType: VlocityUITemplate
query: Select Id from %vlocity_namespace%__VlocityUITemplate__c where Name LIKE 'campaign%'Export by Predefined Queries is the recommened approach for defining your Project and you can mix the predefined and explicit queries as shown above
The primary use of this tool is to write the results of the Export to the local folders at the expansionPath. There is a large amount of post processing to make the results from Salesforce as Version Control friendly as possible.
Additionally, an Export Build File can be created as part of an Export. It is a single file with all of the exported DataPack Data in it with no post processing.
exportBuildFile: AllDataPacksExported.jsonThis file is not Importable to a Salesforce Org through the DataPacks API, but could be used to see the full raw output from a Salesforce Org. Instead, use the BuildFile task to create an Importable file.
The manifest defines the Data used to export. Not all types will support using a manifest as many types are only unique by their Id. VlocityDataPackTypes that are unique by name will work for manifest. These are limited to: DataRaptor, VlocityUITemplate, VlocityCard,
manifest:
VlocityCard:
- Campaign-Story
OmniScript:
- Type: Insurance
Sub Type: Billing
Language: EnglishDue to the limitation that not all DataPackTypes support the manifest format. It is best to use the Export by Queries syntax
This specifies a File to create from the DataPack Directory. It could then be uploaded through the DataPacks UI in a Salesforce Org.
buildFile: ProductInfoPhase3.json Vlocity has identified the Anonymous Apex that should run during most Deploys. It is not necessary to change these settings unless you want to change the default behavior. Currently the Vlocity Templates and Vlocity Cards will be deactivated before Deploy, and Products will have their Attribute JSON Generated after Deploy.
Anonymous Apex will run before and After a Job by job type and before each step of a Deploy. Available types are Import, Export, Deploy, BuildFile, and ExpandFile. Apex files live in vlocity_build/apex. You can include multiple Apex files with "//include FileName.cls;" in your .cls file.
preJobApex:
Deploy: DeactivateTemplatesAndLayouts.cls With this default setting, the Apex Code in DeativateTemplatesAndLayouts.cls will run before the deploy to the org. In this case it will Deactivate the Vlocity Templates and Vlocity UI Layouts (Cards) associated with the Deploy. See Advanced Anonymous Apex for more details.
The Job file additionally supports some Vlocity Build based options and the options available to the DataPacks API. All Options can also be passed in as Command Line Options with -optionName <value> or --optionName for Boolean values.
| Option | Description | Type | Default |
|---|---|---|---|
| compileOnBuild | Compiled files will not be generated as part of this Export. Primarily applies to SASS files currently | Boolean | false |
| manifestOnly | If true, an Export job will only save items specifically listed in the manifest | Boolean | false |
| delete | Delete the VlocityDataPack__c file on finish | Boolean | true |
| activate | Will Activate everything after it is imported / deployed | Boolean | false |
| maximumDeployCount | The maximum number of items in a single Deploy. Setting this to 1 combined with using preStepApex can allow Deploys that act against a single DataPack at a time | Integer | 1000 |
| defaultMaxParallel | The number of parallel processes to use for export | Integer | 1 |
| exportPacksMaxSize | Split DataPack export once it reaches this threshold | Integer | null |
| continueAfterError | Don't end vlocity job on error | Boolean | false |
| supportForceDeploy | Attempt to deploy DataPacks which have not had all their parents successfully deployed | Boolean | false |
| supportHeadersOnly | Attempt to deploy a subset of data for certain DataPack types to prevent blocking due to Parent failures | Boolean | false |
| addSourceKeys | Generate Global / Unique Keys for Records that are missing this data. Improves ability to import exported data | Boolean | false |
| useAllRelationships | Determines whether or not to store the _AllRelations.json file which may not generate consistently enough for Version Control. Recommended to set to false. | Boolean | true |
| buildFile | The target output file from packBuildFile | String | AllDataPacks.json |
| Option | Description | Type | Default |
|---|---|---|---|
| ignoreAllErrors | Ignore Errors during Job. It is recommeneded to NOT use this setting. | Boolean | false |
| maxDepth | The max distance of Parent or Children Relationships from initial data being exported | Integer | -1 |
| processMultiple | When false each Export or Import will run individually | Boolean | true |
These types are what would be specified when creating a Query or Manifest for the Job.
| VlocityDataPackType | SObject | Label |
|---|---|---|
| Attachment | Attachment | Attachment |
| AttributeAssignmentRule | AttributeAssignmentRule__c | Attribute Assignment Rule |
| AttributeCategory | AttributeCategory__c | Attribute Category |
| CalculationMatrix | CalculationMatrix__c | Calculation Matrix |
| CalculationProcedure | CalculationProcedure__c | Calculation Procedure |
| ContextAction | ContextAction__c | Context Action |
| ContextDimension | ContextDimension__c | Vlocity Context Dimension |
| ContextScope | ContextScope__c | Context Scope |
| ContractType | ContractType__c | Contract Type |
| DataRaptor | DRBundle__c | DataRaptor Interface |
| Document | Document | Document (Salesforce Standard Object) |
| DocumentClause | DocumentClause__c | Document Clause |
| DocumentTemplate | DocumentTemplate__c | Document Template |
| EntityFilter | EntityFilter__c | Entity Filter |
| ItemImplementation | ItemImplementation__c | Item Implementation |
| ManualQueue | ManualQueue__c | Manual Queue |
| ObjectClass | ObjectClass__c | Object Layout |
| ObjectContextRule | ObjectRuleAssignment__c | Vlocity Object Rule Assignment |
| ObjectLayout | ObjectLayout__c | Object Layout |
| OmniScript | OmniScript__c | OmniScript |
| OrchestrationDependencyDefinition | OrchestrationDependencyDefinition__c | Orchestration Dependency Definition |
| OrchestrationItemDefinition | OrchestrationItemDefinition__c | Orchestration Item Definition |
| OrchestrationPlanDefinition | OrchestrationPlanDefinition__c | Orchestration Plan Definition |
| Pricebook2 | Pricebook2 | Pricebook (Salesforce Standard Object) |
| PriceList | PriceList__c | Price List |
| PricingVariable | PricingVariable__c | Pricing Variable |
| Product2 | Product2 | Product (Salesforce Standard Object) |
| Promotion | Promotion__c | Promotion |
| QueryBuilder | QueryBuilder__c | Query Builder |
| Rule | Rule__c | Rule |
| StoryObjectConfiguration | StoryObjectConfiguration__c | Story Object Configuration (Custom Setting) |
| System | System__c | System |
| TimePlan | TimePlan__c | Time Plan |
| TimePolicy | TimePolicy__c | Time Policy |
| UIFacet | UIFacte__c | UI Facet |
| UISection | UISection__c | UI Section |
| VlocityAction | VlocityAction__c | Vlocity Action |
| VlocityAttachment | VlocityAttachment__c | Vlocity Attachment |
| VlocityCard | VlocityCard__c | Vlocity Card |
| VlocityFunction | VlocityFunction__c | Vlocity Function |
| VlocityPicklist | Picklist__c | Vlocity Picklist |
| VlocitySearchWidgetSetup | VlocitySearchWidgetSetup__c | Vlocity Interaction Launcher |
| VlocityStateModel | VlocityStateModel__c | Vlocity State Model |
| VlocityUILayout | VlocityUILayout__c | Vlocity UI Layout |
| VlocityUITemplate | VlocityUITemplate__c | Vlocity UI Template |
| VqMachine | VqMachine__c | Vlocity Intelligence Machine |
| VqResource | VqResource__c | Vlocity Intelligence Resource |
In order to make the Anonymous Apex part reusable, you can include multiple Apex files with "//include FileName.cls;" in your .cls file. This allows you to write Utility files that can be reused. The BaseUtilities.cls file includes an additional feature that will send the data as a JSON to your Anonymous Apex.
In Anonymous apex vlocity_namespace will be replaced with the vlocity.namespace from the propertyfile.
List<Object> dataSetObjects = (List<Object>)JSON.deserializeUntyped('CURRENT_DATA_PACKS_CONTEXT_DATA');
List<Map<String, Object>> dataPackDataSet = new List<Map<String, Object>>();
for (Object obj : dataSetObjects)
{
if (obj != null)
{
dataPackDataSet.add((Map<String, Object>)obj);
}
}The token CURRENT_DATA_PACKS_CONTEXT_DATA will be replaced with JSON data and converted into a List<Map<String, Object>> with data depending on the type of setting and type of job being run.
Pre Job Apex can run Anonymous Apex before the DataPack Job starts. While it is possible to use the CURRENT_DATA_PACKS_CONTEXT_DATA described above, for large projects it will be over the 32000 character limit for Anonymous Apex.
preStepApex will send only the DataPack context data for the currently running API call. For Deploys, this means that instead of Deactivating all Templates and Layouts for an entire project before beginning a full deploy, using the same provided DeactivateTemplatesAndLayouts.cls as preStepApex, the target Salesforce Org will be minimally impacted as each Template or Card will only be Deactivated while it is being deployed. Best when combined with the maximumDeployCount of 1.
postStepApex can be used to run any compilation steps in Apex that are not automatically run inside triggers. EPCProductJSONUpdate.cls is recommended to be run when Deploying Products.
Like Pre and Post Job Apex you can also run JavaScript against the project with the preJobJavaScript, postJobJavaScript in tyour Job File.
Your JavaScript file should implement:
/**
*
* @param {object} vlocity - This is the vlocity.js object. You can use vlocity.jsForceConnection for access to the current JSForce Session.
*
* @param {object} currentContextData - For preJobJavaScript this is null. For postJobJavaScript this will be a full list of records processed during the job.
*
* @param {object} jobInfo - This is the entire job state
*
* @param {function} callback - Callback - Must be called
*/
module.exports = function(vlocity, currentContextData, jobInfo, callback) {
// Your Code Here
});If Exporting with a Manifest, each JSON Object will be one entry in the Manifest in the form of:
manifest:
VlocityCard:
- Campaign-Story {
"VlocityDataPackType": "VlocityCard",
"Id": "Campaign-Story"
}"Id" is the default JSON key in the Manifest, but Manifests also support YAML Key/Value pair syntax:
manifest:
OmniScript:
- Type: Insurance
SubType: Billing
Language: EnglishWhich becomes:
{
"VlocityDataPackType": "VlocityCard",
"Type": "Insurance",
"SubType": "Billing",
"Language": "English"
}For a Query, each result from the Query will be a JSON Object with the appropriate DataPack Type.
queries:
- VlocityDataPackType: VlocityUITemplate
query: Select Id from %vlocity_namespace%__VlocityUITemplate__c where Name LIKE 'campaign%' # SOQL Becomes:
{
"VlocityDataPackType": "VlocityUITemplate",
"Id": "01r61000000DeTeAAN",
}Before a Deploy, each JSON Object will be a small amount of information about the Object. By default it is the Name of the Object. For a VlocityUILayout it would be:
{
"VlocityDataPackType": "VlocityUILayout",
"Name": "Campaign-Story"
}In the DeactivateTemplatesAndLayouts.cls this Name is used to Deactivate the Layouts that are pending for Deploy.
Post Job Apex runs after the Job completes successfully.
After a Deploy the Ids of every record deployed will be in the JSON Object List. This may be too much data for Anonymous Apex for large deploys.
{
"Id": "01r61000000DeTeAAN"
}DataPacks uses a Custom Metadata Object called a Vlocity Matching Key to define the uniqnueness of any SObject. Matching Keys contain the following fields:
| Name | API Name | Description |
|---|---|---|
| Matching Key Fields | MatchingKeyFields__c | Comma Separated list of Field API Names that define Uniqnuess |
| Vlocity Matching Key Name | Name | Name of the Matching Key |
| Label | Label | Label of the Matching Key |
| Object API Name | ObjectAPIName__c | Full API Name of the SObject |
| Matching Key Object | MatchingKeyObject__c | Full API Name of the SObject |
| Return Key Field | ReturnKeyField__c | Always "Id" for DataPacks |
| Composite Unique Field | CompositeUniqueFieldName__c | Leave empty - Reserved for future use |
Create these keys if you want to support connections between SObject Id fields that are not already supported by DataPacks, or if you would like to change the Vlocity Default for any SObject. Matching Keys created outside the Managed Package will always override ones contained inside (Post Vlocity v15).
| Object API Name | Matching Key Fields |
|---|---|
| %vlocity_namespace%__Attribute__c | %vlocity_namespace%__Code__c |
| %vlocity_namespace%__AttributeAssignment__c | %vlocity_namespace%__ObjectId__c, %vlocity_namespace%__AttributeId__c, %vlocity_namespace%__IsOverride__c |
| %vlocity_namespace%__AttributeAssignmentRule__c | Name |
| %vlocity_namespace%__AttributeCategory__c | %vlocity_namespace%__Code__c |
| %vlocity_namespace%__CalculationMatrix__c | Name |
| %vlocity_namespace%__CalculationMatrixVersion__c | %vlocity_namespace%__VersionNumber__c, %vlocity_namespace%__CalculationMatrixId__c |
| %vlocity_namespace%__CalculationProcedure__c | Name |
| %vlocity_namespace%__CalculationProcedureVersion__c | %vlocity_namespace%__VersionNumber__c, %vlocity_namespace%__CalculationProcedureId__c |
| %vlocity_namespace%__Catalog__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__CatalogProductRelationship__c | %vlocity_namespace%__CatalogId__c, %vlocity_namespace%__Product2Id__c |
| %vlocity_namespace%__CatalogRelationship__c | %vlocity_namespace%__ChildCatalogId__c, %vlocity_namespace%__ParentCatalogId__c |
| %vlocity_namespace%__ContextAction__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__ContextDimension__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__ContextScope__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__ContractType__c | Name |
| %vlocity_namespace%__ContractTypeSetting__c | Name, %vlocity_namespace%__ContractTypeId__c |
| %vlocity_namespace%__DocumentClause__c | Name |
| %vlocity_namespace%__DocumentTemplate__c | %vlocity_namespace%__ExternalID__c |
| %vlocity_namespace%__DRBundle__c | Name |
| %vlocity_namespace%__DRMapItem__c | %vlocity_namespace%__MapId__c |
| %vlocity_namespace%__Element__c | %vlocity_namespace%__OmniScriptId__c, Name |
| %vlocity_namespace%__EntityFilter__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__InterfaceImplementation__c | Name |
| %vlocity_namespace%__InterfaceImplementationDetail__c | %vlocity_namespace%__InterfaceId__c, Name |
| %vlocity_namespace%__ObjectClass__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__ObjectContextRule | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__ObjectLayout__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__OfferingProcedure__c | Name |
| %vlocity_namespace%__Picklist__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__PicklistValue__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__PriceList__c | %vlocity_namespace%__Code__c |
| %vlocity_namespace%__PriceListEntry__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__PricingElement__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__PricingVariable__c | %vlocity_namespace%__Code__c |
| %vlocity_namespace%__ProductChildItem__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__ProductConfigurationProcedure__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__ProductRelationship__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__Promotion__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__PromotionItem__c | %vlocity_namespace%__ProductId__c, %vlocity_namespace%__PromotionId__c |
| %vlocity_namespace%__PublicProgram__c | Name |
| %vlocity_namespace%__QueryBuilder__c | Name |
| %vlocity_namespace%__Rule__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__StoryObjectConfiguration__c | Name |
| %vlocity_namespace%__TimePlan__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__TimePolicy__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__UIFacet__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__UISection__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__VlocityAction__c | Name |
| %vlocity_namespace%__VlocityAttachment__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__VlocityCard__c | Name, %vlocity_namespace%__Author__c, %vlocity_namespace%__Version__c |
| %vlocity_namespace%__VlocityFunction__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__VlocityFunctionArgument__c | %vlocity_namespace%__GlobalKey__c |
| %vlocity_namespace%__VlocitySearchWidgetActionsSetup__c | %vlocity_namespace%__VlocityActionId__c, %vlocity_namespace%__VlocitySearchWidgetSetupId__c, %vlocity_namespace%__ActionType__c |
| %vlocity_namespace%__VlocitySearchWidgetSetup__c | Name |
| %vlocity_namespace%__VlocityState__c | Name, %vlocity_namespace%__DTPStateModelName__c |
| %vlocity_namespace%__VlocityStateModel__c | %vlocity_namespace%__ObjectAPIName__c, %vlocity_namespace%__FieldAPIName__c, %vlocity_namespace%__TypeFieldName__c, %vlocity_namespace%__TypeFieldValue__c |
| %vlocity_namespace%__VlocityStateModelVersion__c | %vlocity_namespace%__VersionNumber__c, %vlocity_namespace%__StateModelId__c |
| %vlocity_namespace%__VlocityUILayout__c | Name, %vlocity_namespace%__Version__c, %vlocity_namespace%__Author__c |
| %vlocity_namespace%__VlocityUITemplate__c | Name, %vlocity_namespace%__Author__c, %vlocity_namespace%__Version__c |
| %vlocity_namespace%__VqMachine__c | Name |
| %vlocity_namespace%__VqMachineResource__c | %vlocity_namespace%__VqMachineId__c, %vlocity_namespace%__VqResourceId__c |
| %vlocity_namespace%__VqResource__c | Name |
| Document | DeveloperName |
| Pricebook2 | Name |
| PricebookEntry | Product2Id, Pricebook2Id, CurrencyIsoCode |
| Product2 | %vlocity_namespace%__GlobalKey__c |
| RecordType | DeveloperName, SobjectType |
| User |
The Command Line API can also return JSON formatted output and accept some inputs as JSON. The primary input JSON would be the Manifest which can be passed in as:
vlocity packExport -manifest '["OmniScript/MACD_Move_English"]'The tool will return JSON is sent the argument --json or --json-pretty and will return a JSON in the format of
{
"action": "Export",
"message": "VlocityUITemplate --- SelectAssetToMove.html --- Not Found",
"records": [
{
"VlocityDataPackDisplayLabel": "MACD Move English",
"VlocityDataPackKey": "OmniScript/MACD_Move_English",
"VlocityDataPackStatus": "Success",
"VlocityDataPackType": "OmniScript"
}
],
"status": "error"
} Where each record contains the VlocityDataPackKey that was Exported / Deployed, and the Export / Deploy will be limited to only VlocityDataPackKeys passed in as part of the manifest if it is supplied.
A Deploy will always only include the -manifest keys, however for an Export it will be defauly include dependencies unless -maxDepth 0 is used as an argument.
It is possible to change the settings that are used to define the behavior of each DataPack is Imported, Deployed, and written to the files. Settings overrides are added inside the Job File definition with the following syntax which is also found in the actual lib/datapacksexpandeddefinition.yaml:
OverrideSettings:
DataPacks:
Product2:
SupportParallel: false
SObjects:
Product2:
FilterFields:
- AttributeMetadata__c
- ImageId__c
- JSONAttribute__c
FolderName:
- GlobalKey__c
JsonFields:
- CategoryData__c
SourceKeyDefinition:
- GlobalKey__c
UnhashableFields:
- JSONAttribute__c
- CategoryData__c
- IsConfigurable__c In this case the settings for Product2 include:
SupportParallel: false meaning that Product2 DataPacks do not support being uploaded in parallel due to record locking issues on the Standard Pricebook Entry.
FilterFields:
- AttributeMetadata__c
- ImageId__c
- JSONAttribute__c Filter Fields describes fields that will be removed from the JSON before writing to the file system. This is generally due to them being or containing Salesforce Id's that cannot be replaced during export and are not Version Control friendly.
FolderName:
- GlobalKey__c Folder Name is the field which contains the name of the folder where the Product2 will be written. This is seperate from the file name as the folder must be unique, but the file should be readable. In most cases the Folder Name is the Global / Unique Key for the Object such that it should never change no matter what else changes in the object.
JsonFields:
- CategoryData__cJsonFields is a list of fields on the SObject which should be written as formatted JSON as opposed to a String when writing to a file.
The following full list of settings are supported:
| Setting | Type | Default | Description |
|---|---|---|---|
| SortFields | Array | "Hash" | The fields used to sort lists of SObjects to make the sort as consistent as possible. Valid Values: Fields on the SObject (ie Name, Type__c, etc) |
| DoNotExpand | Boolean | false | Skip expanding the DataPack into Multiple Files. |
| FilterFields | Array | none | Fields to remove before writing to files. Valid Values: Fields on SObject |
| FileName | Array | Name | Fields used to create the File Names for an SObject. Valid Values: Fields on SObject or "_String" to add a Literal |
| SourceKeyFields | Array | Name | Fields used to build the readable key for a single SObject Valid Values: Fields on SObject or "_String" to add a Literal |
| SourceKeyGenerationFields | Array | none | Fields used to Generate a new Source Key when addSourceKeys: true Valid Values: Fields on SObject |
| MatchingSourceKeyDefinition | Array | none | Fields used to build the readable key for a single SObject when it is a Matching Key node. Valid Values: Fields on SObject or "_String" to add a Literal |
| FolderName | Array | Name | Fields used to create the Folder Name for an SObject. Valid Values: Fields on SObject or "_String" to add a Literal |
| FileType | String | json | Field or String used to determine the File Type when creating a file. Valid Values: Fields on SObject or a string for a literal |
| JsonFields | String | none | JsonFields is a list of fields on the SObject which should be written as formatted JSON as opposed to a String when writing to a file. Valid Values: Fields on SObject |
| ReplacementFields | Object | none | Fields that should be replaced with values from other fields. Valid Values: Key is Target Field - Value is Field to Replace with or "_String" for literals |
| NonUnique | Boolean | false | Declares that an SObject's data will always be created new during Deploy and will never be referenced by other objects and therefore does not need to keep extra metadata |
| PaginationSize | Integer | 1000 | Declares that an SObject should Paginate during Deploy |
| RemoveNullValues | Boolean | false | Delete all null values from JSON. Similar to NonUnique it will be created new, but can be referenced by other Objects |
| UnhashableFields | Array | none | Fields that should not be used for Checking Diffs as they are largely informational. Valid Values: Fields on SObject |
| SupportParallel | Boolean | true | Turn on / off parallel processing when Deploying the DataPack Type. Necessary when Master-Detail Parent might be shared with other DataPacks |
| MaxDeploy | Integer | 50 | Specify the maximum number of DataPacks which should be uploaded in a single transaction |
| HeadersOnly | Boolean | false | Support uploading only the top level SObject in the DataPack. Good for potentially fixing circular reference issues |
| ExportGroupSize | Integer | 5 | Specify the maximum number of DataPacks which should be Exported in a single transaction. Potentially large DataPacks like Matrix or Attachments could be set to 1 if necessary |