Provides a fast Salesforce native tool for deploying any Vlocity Datapack JSON to any Salesforce org.
This CLI is built as showcase for the @vlocode/vlocity-deploy NPM library, and does not use the Vlocity build tools NPM library.The CLI exposes a single command deploy which leverages @vlocode/vlocity-deploy.
Key differences with vlocityinc/vlocity_build and Vlocity DX
- 🚀 Vlocode is significantly faster up to 10x-20x compared to Vlocity DX depending on the use case
- 💻 Vlocode does all the heavy lifting, dependency resolution, converting of datapacks client side
- 🌈 Vlocode supports true delta check that is both fast and reliable as it can detect changes made in your org and restore them without relying on git
- Vlocode deployment CLI is meant for deploying datapacks not for exporting/extracting them from an org
- Activate LWC OmniScripts and flex cards; for that use the client side LWC compiler of Vlocode (integration planed for future version)
- Provide you with a UI
The Vlocode CLI is packaged as a dependency-free CLI with a bit of help from Webpack making it very fast to install. This also allows Vlocode CLI to be easily integrated in any CI/CD setup and helps guarantee consistent behavior as all dependencies (and their dependencies) are pinned.
Note You should not depend on this package if you intend to use it as library, instead depend on @vlocode/vlocity-deploy which is the underlying library that implements all deployment logic.
$ npm i @vlocode/cli -gList all commands available using the --help command. To get help on a specific command use the following command vlocode <command> --help.
Usage: vlocode deploy [options] <folder>
Deploy datapacks to Salesforce
Arguments:
folder path to a folder containing the datapacks to be deployed
Options:
-v, --verbose enable verbose logging (default: false)
--debug print call stack when an unhandled error occurs (default: false)
-u, --user <username> Salesforce username or alias of the org to deploy the datapacks to
-i, --instance <url> the URL instance (default: "test.salesforce.com")
--purge-dependencies delete embedded dependencies with matching keys after the primary datapack record is
deployed. By default Vlocode will only delete child records that do not have a
matching key configuration, with this flag Vlocode will delete all child records that
have a lookup relationships to the primary datapack record. For example; when
deploying a Product2 datapack this flag will delete all child item records found in
the targer org with a lookup to the Product2 datapack that is deployed. (default:
false)
--lookup-failed lookup the Ids of records that failed to deploy but are dependencies for other parts
of the deployment (default: false)
--retry-count <count> the number of times a record deployment is retried before failing it (default: 1)
--bulk-api use the Salesforce bulk API to update and insert records (default: false)
--delta check for changes between the source data packs and source org and only deploy the
datapacks that are changed (default: false)
--strict-dependencies enforce datapacks with dependencies on records inside other datapacks are fully
deployed. By default Vlocode determines deployment order based on record level
dependencies, this allows for more optimal chunking improving the overall speed of
the deployment. If you are running into deployment errors and think that Vlocode does
not follow the correct deployment order try enabling this setting. (default: false)
--skip-lwc skip LWC activation for LWC enabled OmniScripts (default: false)
--use-metadata-api deploy LWC components using the Metadata API (slower) instead of the Tooling API
(default: false)
--remote-script-activation use anonymous apex to activate OmniScripts.By default Vlocode will generate script
definitions locally which is faster and more reliable than remote activation. Enable
this when you experience issues or inconsistencies in scripts deployed through
Vlocode. (default: false)
-h, --help display help for commandUsage: vlocode activate [options] [scriptFilter]
Activate OmniScripts in Salesforce and deploy associated LWC components
Arguments:
scriptFilter Salesforce ID <type>/<subType>(/<language>) filter of the scripts to activate. Supports
wildcard characters, i.e: "MACD/" to activate multiple scripts
Options:
-v, --verbose enable verbose logging (default: false)
--debug print call stack when an unhandled error occurs (default: false)
-u, --user <username> Salesforce username or alias of the org to deploy the datapacks to
-i, --instance <url> Salesforce instance URL; for example: test.salesforce.com (default: "test.salesforce.com")
--parallel-activations determines the amount of parallel activations to run
--skip-lwc skip LWC activation for LWC enabled OmniScripts (default: false)
--use-metadata-api deploy LWC components using the Metadata API (slower) instead of the Tooling API (default:
false)
--remote-activation use anonymous apex to activate OmniScripts.By default Vlocode will generate script
definitions locally which is faster and more reliable than remote activation. Enable this
when you experience issues or inconsistencies in scripts deployed through Vlocode. (default:
false)
-h, --help display help for commandYou can use any existing SFDX credentials or OAuth2 to login into tge target org. If you do not provided an SFDX username or alias you will automatically get an OAuth popup.
To deploy and login using OAuth2 (for production orgs pass --instance login.salesforce.com) use the following basic command, where the last argument is the path (relative or full) to the folder containing the *_DataPack.json files to deploy. Vlocode will recursively scan the specified folder and deploy all datapacks found.
vlocode deploy ./path-to-datapack-json-filesTo use an existing SFDX credential or alias use:
vlocode deploy ./path-to-datapack-json-files -u <SFDX alias/username>Q: Does vlocode deploy the LWC enabled OmniScripts?
A: Yes, vlocode will deploy the OmniScript and compile the LWC component and deploy it using either the Metadata API or the Tooling API. By default the tooling API is used as it can run in parallel to an ongoing metadata deployment.
Q: Does vlocode deploy custom datapack properties that are not part of the standard datapack definition?
A: Yes, vlocode will load the datapack and match the fields in the datapack against the fields available in the target org. Matching fields are deployed, for any field that is specified in the datapack but not available an error is generated which can be reviewed at the end of the deployment.
Q: Vlocode does not delete Product Child Item's (PCI) that I have removed from the datapack, why is that?
A: Vlocode will is designed to be safe to run on production orgs and does not delete records unless explicitly requested. When removing child items from the product hierarchy it is recommended to set the state to disabled instead of deleting the PCI as deleting the PCI will have side effects on cached content and Assets already created based on the old definition.
For none production orgs you can enable the --purge-dependencies option which will first delete all embedded records and only then deploy the new ones.
Q: Should I prefer the --bulk-api option for production deployments?
A: No, the performance of the bulk API is worse as it is dependent on the available resources on Salesforce and runs at a lower priority compared to regular database API operations. You will see inconsistent performance when using the --bulk-api and should only prefer it if you want to reduce API usage consumption when deploying.
Q: When I actictae my OmniScript from the UI it looks different then the one deployed by Vlocode
A: By default vlocode-cli will use a feature of the Vlocode deployment library called local script definition generation. This means that script definitions are generated by Vlocode instead of running a Vlocity remote APEX function. Although this feature has been extensively tested there is a possibility of mismatches which can either be due to bugs in the local script definition generation feature or in the APEX code running on Salesforce.
if you encounter such discrepancy you can disable local script definition generation by passing --remote-script-activation to the deployment. Also raise a bug on Github so that the local script definition generation can be updated to handle your specific use case.
Q: Does vlocode compile FlexCards into LWC components?
A: No, at this moment Vlocode does not generate the LWC components for Flexcards. This is planned but due to the complexity and effort involved in porting the flex-card activation code to Javascript it will a bit more time for this to become available in vlocode as stable feature.
Q: We want to use Vlocode to improve our deployment, can you help us?
A: Yes, support for project implementations can be provided on request.