How to Deploy Vlocity Components with Vlocity Build Tool

A few weeks ago we walked the last mile setting up the CI/CD pipeline at my current project, including the ability to deploy Vlocity components. And it is an experience that someone mentioned could be useful to other Salesforce folks, particularly if you are not using one of the specialized Salesforce CI/CD tools available in the market.

SFI (Salesforce Industries, aka. Vlocity ) components are different from traditional Metadata components. SFI components are represented as records and JSON files inside the platform. I am not sure if Salesforce plans to change that in the future, but right now in order to deploy these components, you require either the Vlocity Build tool (CLI) or Vlocity IDX tool (UI).

Assuming that you are using any tool that is capable of running SFDX commands already (e.g. Circle CI, Travis CI, Jenkins, ...), then it is also safe to assume you already have NodeJS and NMP incorporated into the pipeline. So, you can easily create a script to install the Vlocity Build Tool. The following is a traditional YAML file used in a CI tool, the important piece is the npm command.

deploy-vlocity:
    executor: sfdx/default
    steps:
      - checkout
      - sfdx/install
      - run:
          name: Install Dependencies
          command: |
            sudo npm install -global vlocity

Once the tool is installed, the next step is to make sure that it is authenticated into your org so that you can modify records and metadata. The easiest way to do that if you already have an SFDX session, is to use the same alias that you are using to work with standard salesforce components. For that, we will create a properties file that can be referenced in the upcoming scripts.

sfdx.username = DevHub
sf.intanceUrl = https://mycompany--vlocityorg.my.salesforce.com

As you can see, the file is very simple. You can create different property files for your different source and target environments. With that, we can start executing commands to retrieve and deploy the components using the "vlocity" keyword.

The full list of commands can be referenced in the Github repo of the Vlocity tool, but usually, you will end up writing a script like the following to be executed through your CI tool...

# Source Org
vlocity -propertyfile build_source.properties -job EPC.yaml cleanOrgData
vlocity -propertyfile build_source.properties -job EPC.yaml packExport
vlocity -propertyfile build_source.properties -job EPC.yaml packRetry # If any errors

# Target Org
vlocity -propertyfile build_target.properties -job EPC.yaml cleanOrgData
vlocity -propertyfile build_target.properties -job EPC.yaml packDeploy
vlocity -propertyfile build_target.properties -job EPC.yaml packRetry # If any errors

Let's break it down.

• Each command is using the -propertyfile that we created before. You need to make sure that your SFDX alias has a previous authenticated session. That way the vlocity tool can use it or just refresh the previous token.
• In the source org we execute three separate commands. First, we clean any cached information that can cause conflicts. Second, we export the components specified in the EPC.yaml file (I will talk about this one in a second). And finally, we retry it if something failed.
• Similarly, in the target org, we execute the same order of operations, but this time we deploy the components in the EPC.yaml file.

The last and probably the most important piece is the "EPC.yaml" file, where we will specify the components to be retrieved/deployed and some other important parameters.

projectPath: ./vlocity
queries: # Queries to get vlocity datapacks
  - VlocityDataPackType: IntegrationProcedure
    query: SELECT Id,vlocity_ins__SubType__c,vlocity_ins__Type__c FROM vlocity_ins__OmniScript__c WHERE vlocity_ins__IsActive__c = true AND vlocity_ins__IsProcedure__c =  true AND Name = 'My Integration Procedure'
 
manifestOnly: true
oauthConnection: true
activate: true

Shall we go through it?

• The projectPath is the place where components will be stored once we retrieve them. And subsequently, where we can take them to be deployed to the next environment.
  
• The next piece is the actual components to be deployed. The tool provides multiple options. You can specify a list of all the component types to be retrieved and deployed. Or, as you can see in my script, you can write a query to retrieve specific components and component types. I have found it to be more useful this way, because of the way my Circle CI pipeline behaves, but you can reference the other available options in the Github repo of the tool.
  
• The manifestOnly flag is a boolean that tells the tool that we will only retrieve and deploy the components in this manifest. If there are other components in the ./vlocity folder those won't be taken.
  
• oauthConnection lets us make use of the OAuth active session in SFDX.
• The last piece is the active flag, which tells the tool that the components must be activated in the org after the deployment.

One last thing worth mentioning is that you just need to include the component at the top (e.g. an Integration Procedure that encapsulates multiple Data Raptors) and any dependencies will be pulled and pushed automatically between the source and target orgs.

In our case, the way that developers tell the pipeline about new components to be deployed between environments is using the queries in the EPC.yaml file. But as mentioned before, there are other options that could work better depending on your workflow. For example, you can push the JSON metadata and records into the ./vlocity folder directly and skip the "packExport" command.

Happy coding!