Vlocity Integration

Updated 2 weeks ago by Copado Solutions

Copado currently supports Vlocity Build Tool version 1.14.16.

Copado's Vlocity integration allows you to include Vlocity metadata in the same release management process as standard Salesforce metadata with a complete Git version control.

While working with Copado and Vlocity, you can promote and deploy Vlocity configurations in the same way as for Salesforce metadata, taking advantage of Copado's flexibility and quality gates. 

Vlocity configurations/metadata can be retrieved and committed to the repository or promoted and deployed without version control (org to org).

You can find Vlocity metadata in the same places as Salesforce metadata, from the Org Credential record, the Git Snapshot page, or the User Story Commit page.

Requirements

  • A fully enabled Copado user.
  • Vlocity feature activated in your Copado instance.
    • If the feature is not enabled, your system admin user will be able to activate it by following these steps:
      1. Go to the Account Summary tab.
      2. Switch the Toggle Vlocity button:
      3. Click on Refresh features.
    It might take 1 hour to complete the activation.
    In Winter ‘20, only system admin users can enable this feature. However, if you are in Summer ‘20, there is custom permission called Enable Vlocity Integration. Anyone with this permission will be able to enable Vlocity.
  • Vlocity metadata visibility.
    • Records (configurations) permission.

Getting Started

Once your organization has the Vlocity feature activated, refresh the metadata index of your credential(s), and you will see the Vlocity metadata listed alongside the Salesforce metadata:

In order to initialize your repository with Vlocity DataPacks, you can directly commit them in a User Story and start deploying it.

Otherwise, you can use Git Snapshots to synchronize all DataPacks with your version control. 

Additionally, you can use the Advanced Metadata Filter in your Git Snapshots or credentials to filter and exclude the types of Vlocity components that are retrieved during the Snapshot or in the Commit Grid:

If you cannot find a specific metadata type after your Snapshot has been taken or in the Commit Grid, please check and make sure that:

  • The metadata type exists in the org where you are committing from.
  • The user has all the necessary permissions to see this metadata type.
  • The metadata type is active.
  • User’s default credentials are not filtering the metadata type out.

Vlocity Commit Process

On the User Story Commit page, you can find Vlocity metadata listed in the metadata index grid. Once you select the Vlocity metadata you want to commit and click on Commit Changes, the Copado backend runs the Vlocity build tool and executes the packExport command to retrieve the selected Vlocity files from the source organization. Copado then commits the retrieved files in the corresponding branch:

User Story Commit page

You can also commit Vlocity components and dependencies on a user story’s feature branch using the webhook Commit Files on User Story. For more information about this webhook, please refer to our API documentation.

Since v17.8, you can commit Vlocity components through the Copado CLI.

Please bear in mind that Vlocity components are not supported for the Destructive Changes operation.

Vlocity Dependencies

Suppose you would like to resolve Vlocity dependencies before a commit. You can select the components you want to commit and click on Get Vlocity Dependencies on the Auto-Select Changes button. After completion of the job, you will see in the Selected Metadata tab your original selections plus the dependencies needed so that you can commit and deploy them together:

Get Vlocity Dependencies Button

Copado uses the default maxDepth value (-1), which means that it retrieves all levels of dependencies.

You see the Get Vlocity Dependencies button only when you commit from user stories but not when you commit from the Git snapshot records.

Max Depth

Add the parameter @maxDepth=X (1 min, 10 max, -1 all) in the commit message to retrieve Vlocity components that are not selectable in the grid and cannot be retrieved using the Get Vlocity Dependencies link. Max depth is the maximum distance of parent or children relationships from the initial data being exported: 

E.g.

@maxDepth=1

@maxDepth=5

@maxDepth=10

Vlocity Deployment Process

When executing a deployment with Vlocity metadata, the Copado backend runs the Vlocity build tool, and it executes the packDeploy command to deploy the Vlocity files from the source organization (MetaData step) or Git branch (Git Promotion or Git MetaData steps) into the destination organization: 

If the deployment fails, Vlocity logs will be attached to the deployment step so that you can review them and troubleshoot the issues. Alternatively, if you want to review Vlocity logs regardless of the status of the deployment, you can enable the Attach Deployment File checkbox:

  • When creating a deployment from the deployments tab:
  • Or when creating a deployment from a promotion:
Attach Deployment File Checkbox

If the deployment contains Salesforce metadata, Copado will export the Salesforce .Zip file and the VlocityBuildLog.yaml. And if it only has Vlocity components, just the VlocityBuildLog.yaml will be exported.  

Copado will not export the Vlocity DataPacks that are part of the deployment.
Please note that if you include Vlocity logs, these can consume a considerable amount of file storage.
Deploying Vlocity Components with Copado Continuous Integration

Suppose you have set up a continuous integration in your organization to automate deployments from a Git repository branch to a Salesforce org; you can leverage this feature to deploy Vlocity components.

Build Tool Default Commands Used by Copado

These are the default settings used by Copado when generating the JobFile for each job operation. As explained in the section How to Override Copado’s Default Build Tool Commands below, you can override these settings:

  • packDeploy
    • -manifest
    • -projectPath
    • -separateMatrixVersions = true
    • -separateCalculationProcedureVersions= true
    • -autoUpdateSettings = true
    • -maxDepth = null
    • -oauthConnection = true
    • -reactivateOmniScriptsWhenEmbeddedTemplateFound = true
  • packExport/packUpdateSettings packExport
    • -manifest
    • -projectPath
    • -maxDepth = null
    • -autoUpdateSettings = true
    • -separateMatrixVersions = true
    • -separateCalculationProcedureVersions= true
    • -oauthConnection = true
  • packGetAllAvailableExports
    • -separateMatrixVersions = true
    • -separateCalculationProcedureVersions= true
    • -maxDepth = 0
    • -queries:
      • - AttributeAssignmentRule
      • - AttributeCategory
      • - CalculationMatrix
      • - CalculationMatrixVersion
      • - CalculationProcedure
      • - CalculationProcedureVersion
      • - Catalog
      • - ContextAction
      • - ContextDimension
      • - ContextScope
      • - ContentVersion
      • - ContractType
      • - CpqConfigurationSetup
      • - DataRaptor
      • - DocumentClause
      • - DocumentTemplate
      • - EntityFilter
      • - IntegrationProcedure
      • - InterfaceImplementation
      • - ItemImplementation
      • - ManualQueue
      • - ObjectClass
      • - ObjectContextRule
      • - ObjectLayout
      • - OmniScript
      • - OrchestrationDependencyDefinition
      • - OrchestrationItemDefinition
      • - OrchestrationPlanDefinition
      • - Pricebook2
      • - PriceList
      • - PricingPlan
      • - PricingVariable
      • - Product2
      • - Promotion
      • - QueryBuilder
      • - Rule
      • - StoryObjectConfiguration
      • - System
      • - TimePlan
      • - TimePolicy
      • - UIFacet
      • - UISection
      • - VlocityAttachment
      • - VlocityAction
      • - VlocityCard
      • - VlocityFunction
      • - VlocityPicklist
      • - VlocitySearchWidgetSetup
      • - VlocityStateModel
      • - VlocityUILayout
      • - VlocityUITemplate
      • - VqMachine
      • - VqResource

Auto Compilation of LWC OmniScript and Cards

Copado now supports the Auto Compilation of Lightning Web Components OmniScripts and FlexCards activation by default. 

This feature is only supported if your organization is registered against our CopaGCP backend. This feature is not supported for those organizations registered against the Heroku backend. If you wish to migrate to CopaGCP, please contact your Customer Success Manager. As an alternative, a manual task can be added as a deployment step so that you can be notified to run this action after the metadata/DataPacks deployment is completed.
Configuring the ignoreLWCActivationOS and ignoreLWCActivationCards settings as “false” will not have an impact on this functionality if your backend is Heroku.
Troubleshooting

Activation timeout

If you receive a timeout issue such as “Activation took longer than 5 minutes - Aborted LWC Activation Error”, you can follow the steps below to check if there is any issue with the activation URL that Puppeteer is trying to use:

  1. Access the Deployment’s Notes & Attachments related list and download the VlocityBuildLog.yaml file.
  1. Browse the file and look for a message, related to the DataPacks, that may have timed out in your Deployment. The message will be similar to the following one:  LWC FlexCards Activation URL >> https://org-test.my.salesforce.com/apex/vlocity_ins__FlexCardCompilePage?id=a318Hzzz000014T123Q
  2. Copy the URL and paste it in the corresponding environment. If you see a problem similar the one shown below, we suggest you to reach out to Vlocity/Salesforce Support for further assistance, since the aviation might be failing due to an incorrect configuration in the DataPack:

If the activation URL does not display any issue, try extending the default activation timeouts.

By default these are set to:

  • defaultMinToWaitForLWCOmniScript: 10
  • defaultMinToWaitForLWCClassicCards: 10
  • defaultMinToWaitForLWCFlexCards: 5

Configure the “vlocity-settings.yaml” as follows extending the timeout for the ones that are failing in your deployment (for more information, check the “How to Override Copado’s Default Build Tool Commands” section):

retrieve:
deploy:
  defaultMinToWaitForLWCOmniScript: <new value>
  defaultMinToWaitForLWCClassicCards: <new value>
  defaultMinToWaitForLWCFlexCards: <new value>
dependencies:

How to Override Copado’s Default Build Tool Commands 

The Vlocity build tool provides a series of settings that help you solve specific issues when working with Vlocity metadata.

In addition to the settings included in Copado’s backend, you can define your custom settings and add them to the Environment record using a YAML file: 

  • The custom settings that will apply when committing (retrieve) will be the ones attached to the environment of the org selected for the commit. 
  • The custom settings that will apply when deploying will be the ones attached to the destination org environment.

To apply your custom settings, this is the process you need to follow:

  1. Go to the corresponding Environment record.
  2. Upload your YAML file to the Notes & Attachment related list with the following name “vlocity-settings.yaml” as a Salesforce file.

The YAML file format that Copado receives supports this structure:

retrieve:
<option>: <value>
deploy:
<option>: <value>
dependencies:
<option>: <value>
Please ensure the YAML file is valid and syntactically correct before uploading it to Copado. Otherwise, retrieve and deploy operations might fail. All the parent nodes (retrieve, deploy, dependencies) should be present in the file, even though they have no options set. See the example below.

Retrieve: Represents the job options that can be defined to be used during the build tool Export operations.

Dependencies: Similar to the Retrieve, these are job options that can be defined to be used during the build tool Export operations for dependent components. 

Deploy: Represents the job options that can be defined to be used during the build tool PackDeploy operations.

File example with multiple options:

retrieve:
deploy:
compileOnBuild: true
autoUpdateSettings: true
autoRetryErrors: true
dependencies:
maxDepth: 1

File example with a single option:

retrieve:
deploy:
autoRetryErrors: true
dependencies:

Onboarding Vlocity Integration Strategies

If you are currently working with Copado and did not do the initial setup (production snapshot) including, Vlocity metadata, you can follow this strategy:

  1. Commit  to a user story all Vlocity metadata with production as the source environment
    1. Copado will now include the Vlocity metadata in your Git repository.
      You can use an org credential with visibility to Vlocity metadata only to reduce the chances of committing other metadata. 
  2. Back-promote the user story to all the lower environments to synchronize Vlocity metadata with all the environments and branches.
This strategy will back-promote the current status of your Vlocity configuration in production. Work in progress in Vlocity configurations will be overwritten in lower environments.

If you are currently working with Copado and did not do the initial setup, but your lower environments are aware of Vlocity configurations and have work in progress, you can follow this strategy:

  1. Create an independent auxiliary Git branch in your Git repository. 
  2. Create a Git Snapshot record:
    1. Select the production org credential.
    2. Write the name of the auxiliary branch name.
    3. From the advanced metadata, select only Vlocity Metadata.
    4. Save and click on Take Snapshot Now.
After completion, from your Git repository, manually merge the new Vlocity folder into your master branch. To achieve this, you can create a pull request from the auxiliary branch to master and merge.   

Each time a new user story gets created and changes are committed, changes are merged into the source environment until everything is in sync.


How did we do?