2020 - 09 Vlocity Design Principles and Best Practices

Vlocity Design Principles and Best
Practices
September’ 2020
© 2020 Deloitte Development LLC. All rights reserved.

Revision History
Document Information
Document Name Design Principles and Best Practices for

Vlocity
Document Author Praveen Singh

Rahul Gupta
Jaideep Pagadala
Document Version V 1.0
Date Releases September 2020
Document Edit History

Version Date Additions/ Modifications Prepared/ Revised by
1.0 First version authored Praveen Singh
Rahul Gupta
Jaideep Pagadala
Document Review/Approval History

Date Name Comments
9/1/2020 Rajesh Kumar - Sr. Manager Document review
Abhishek Srivastava - Spec. Leader
Soumya Ray - Manager
Shankar Rao - Manager
Praveen Singh - Manager

Table of Contents
Revision History ......................................................................................................................... 2

Document Information ........................................................................................................ 2
Document Edit History.......................................................................................................... 2
Document Review/Approval History .................................................................................. 2
Introduction .............................................................................................................................. 5
Design Principles & Customer Customizations Performance Factors .................................. 6
Application factors & levels that impact performance: ................................................... 6
OmniScripts Best Practices ...................................................................................................... 7
General Best Practices ........................................................................................................ 7
For ease of maintenance ................................................................................................ 7
For best performance .......................................................................................................... 7
Business Process & Logic Best Practices .......................................................................... 7
Client-side & Server-Side Best Practices.......................................................................... 8
Element Naming Best Practices:...................................................................................... 9
UI Look & Feel - Templates Best Practices......................................................................10
Optimizing Omniscript For Good Performance ................................................................10
Update your Version of Vlocity .......................................................................................10
Reduce Extraneous Elements: ........................................................................................10
Platform Cache and Its Importance ..............................................................................10
Use Reusable Omni Scripts Where Applicable ..............................................................11
Use "Out of the Box" Functionality Whenever Possible..................................................12
Perform Calls Asynchronously .........................................................................................12
Hiding fields in OmniScript while still allowing them to be prefilled .............................12
Hiding OmniScript Elements ............................................................................................12
LWC OmniScript Overview .....................................................................................................13
Introduction .........................................................................................................................13
How To Use Custom LWC Into Vlocity OS ..........................................................................14
LWC Limitations over AngularJS .........................................................................................14
Converting an Angular OmniScript to an LWC OmniScript..............................................15

Changes in Functionalities Exclusive to Vlocity Cards Lightning Web Component ......15
Error Handling in LWC ..........................................................................................................16
Parallel Action Block ...........................................................................................................16
OmniScript Architecture .....................................................................................................17
UI Control Decisions and Patterns ......................................................................................17
DataRaptors Best Practices ....................................................................................................18
Integration Procedures Best Practices ..................................................................................19
Cards Best Practices ...............................................................................................................22
Naming convention ............................................................................................................23
LWC Cards ...........................................................................................................................23
Troubleshooting for the Cards Framework ........................................................................23
Console Size and Card Layout Best Practices ......................................................................24
General Recommendations ...............................................................................................24
Naming Conventions ..........................................................................................................24
Layout Data Sources ...........................................................................................................24
Bad Practices of Card Layouts to Avoid............................................................................25
Templates and UI Best Practices ...........................................................................................26
General Best Practices .......................................................................................................26
JavaScript Best Practices....................................................................................................26
Bad JS Practices to Avoid ...............................................................................................26
HTML / CSS Best Practices ...................................................................................................27
Bad UI Practices to Avoid ...............................................................................................27
Naming Conventions ......................................................................................................27
Actions Best Practices ............................................................................................................28
Calculation Matrix Best Practices ..........................................................................................29
Matrix Version Best Practices .............................................................................................30
Calculation Procedures Best Practices .................................................................................31
Recommended Tool Set for Vlocity.......................................................................................32
Vlocity Testing Strategy ..........................................................................................................32
Org Assessment – By Vlocity Expert Services .......................................................................33
Issues resolutions in OmniScripts: ..........................................................................................34
References ..............................................................................................................................41

Introduction
With the recent acquisition of Vlocity, Salesforce introduced a new cloud platform called
as Industry Cloud, which will collectively focus on Salesforce cloud solutions and Vlocity
specific Industry models, business process and solutions.
Vlocity is a native Salesforce product, which either adds its capabilities using Salesforce
custom objects and fields or enhances by leveraging existing standard objects or fields.
There are various Vlocity tools which are provided as part of the managed package
which are used to achieve business requirements and solutions to support Client vision.
Before any implementation effort is undertaken, it is critical for any developer /
configurator to be aware of the best practices of the tool.
Tools offered as part of Managed package are:
1. Vlocity OmniScripts
2. Vlocity DataRaptors
3. Vlocity Cards
4. Vlocity Layouts
5. Vlocity Templates
6. Vlocity Actions
7. Vlocity Integration Procedures.
8. Vlocity Calculation Matrix.

Design Principles & Customer Customizations Performance
Factors
• Prefill: Minimize the amount of data your users must enter by using the context to
prefill any available key information.
• Display only essential information: Whenever possible, remove information that is
optional or tangential to your use case.
• Keep it short: To minimize the cognitive load on your users and ease their decision-
making, divide long, complex processes into short, easy-to-understand passages.
Minimize the number of elements in steps.
• Use sequence to aid understanding: Put input fields in an order that makes sense
for your use case. Use Block elements under steps only if required for your use case.
• Guide the user: Provide informative, actionable help text and feedback in the UI.
Application factors & levels that impact performance:
• Use Configuration is stead of code.

• Use Maps instead of Loops
• Query only the fields you need
• Never query within a loop
• Do not create nested for loops
• Workflow & Triggers – Not more than 135 workflow per object and not more than
1 Apex trigger per object.
• Process Builder: Not more than 2 Process builder per object.
• If you have 2 or more than 2 Process Builder per object, it’s not a good practice.
• If you have 2 or more than 2 Apex Triggers per object, it’s not a good practice.
• If you have more than 1 Process Builder, Apex Triggers and Workflows per object,
it’s not a good practice.
• Ensure the criteria is as tight as possible
• Understand how and when Workflows and Trigger fire.
• Classes with large amounts of code > 1000 lines will use more memory and take a
longer time to load onto the application server on a cold invocation. Also, large
classes can be difficult to maintain, test, and frequently creates unnecessary
dependencies.
• It is advised to use maximum of 70% of Allocated storage space for static
resources, Data Storages, File Storages.

OmniScripts Best Practices
This section describes best practices for designing and implementing Omni Scripts. From
the user’s standpoint, strive to maximize the clarity of the UI by choosing the right
elements and providing descriptive, unambiguous text and an understandable logical
structure. From the script developers' standpoint, use standard naming conventions for
ease of maintenance, and optimize the script for best performance as described.
General Best Practices
For ease of maintenance

• To document the purpose and change history of an element, annotate its Internal
Notes property.
• To ensure mappings remain valid after you create your script and its related Data
Raptors, do not rename elements.
For best performance

• Minimize the number of conditions and merge fields
• Avoid prefilling hidden elements. When you must prefill a hidden element, set its
accessibleInFutureSteps JSON property to true.
• Avoid nesting blocks in other blocks.
• Try to avoid selectable items in blocks or repeat blocks.
Business Process & Logic Best Practices

• One owner for each Omni Script- owns the logic and requirements.
• Build a skeleton of the entire Omni Script. This can help identify reusable
components.
• Use the Omni Script Designer to build quick mockups of processes.
• Use the Internal Notes property to document the purpose and change history of
an element. This is especially useful for Formula or Action Elements. The maximum
length is 255 characters.
• To ensure Data Raptors/Apex classes/Integration Procedures remain valid after
script creation, do not rename Omni Script elements. It is recommended to build
these integrations after completing the initial Omni Script structure.
• ContextId is a reserved key and is assigned from the URL. Use Set Values to set
other important Ids to the root of the Data JSON, (for example- AccountId,
PolicyId)

• Omni Script can act as a parent (wrapper) that contains one or more embedded
reusable Omni Scripts. Reusable Omni Scripts can be shared across multiple
parents.
• Reusable Omni Scripts adopt the script configuration of the parent script - The
reusable Omni Script JSON will be embedded inside of the parent JSON and at
compilation time there is no functional difference between the two.
• A reusable Omni Script cannot contain another reusable Omni Script - Only one
level down is allowed (Parent and child)
• No element in a reusable Omni Script can have the same name as an element in
the parent script (including remote response data). It is recommended to
namespace elements in a reusable Omni Script. (For example, cc_FirstName for a
field in the Create Contact reusable Omni Script).
Client-side & Server-Side Best Practices

Client-Side Best Practices Server-Side Best Practices
o Reduce Conditional Views, Merge o Use Send/Response Transformations
Fields, Formulas where possible. to cut down JSON payload to external
o Speed up the application of services.
responses by trimming the o Reduce server roundtrips by using
Response JSON. Integration Procedures whenever
o Remove spaces from UI element multiple server-side actions run
names to improve the Omni Script's between steps.
load time. o Run Integration Procedures
o Reduce the number of elements in asynchronously, whenever response is
the script. A single OmniScript not required, by enabling the fire and
should not exceed 200 elements. forget property.
Create and use reusable child o Avoid unnecessary data by trimming
OmniScripts to avoid this. the Data Raptor extract output.
o Run logic on the server wherever o If multiple server calls in between steps
possible, for example, include take too much time cumulatively,
conditional logic in Integration distribute the actions (if possible) to
Procedures and Formulas in Data other parts of the OmniScript.
Raptors instead of OS.
o Test performance by enabling time
tracking. If time tracking is not used
in production, disable the feature
before deploying to production.
o Make sure OmniOut application
and JSON definitions are loaded
from CMS.

Element Naming Best Practices:
• Element Names - Choose short, descriptive names.
• Capitalization - Use UpperCamel case. No spaces and avoid special characters.
• Use standard names - FirstName, LastName, MiddleName, Street, City, State,
PostalCode, Email, Dob, Age, etc.
• Ids - Specify the object (AccountId, PolicyAssetId, Contact Id, CaseId, etc.)
• Use Standard abbreviations - wk (week), wkly (weekly), mos (months), mnly
(monthly), yr (year), yrly (yearly), hrs (hours), hh (household), bene (beneficiary),
rel (relationship),
• Same object, different purpose - Relate the element to the purpose. For example,
if an insurance script uses contact data for three different parties - the insured,
claimants, and beneficiaries - assign element names that disambiguate them:
InsuredStreet, ClaimantStreet, and BeneficiaryStreet.
• Actions - Use VerbObjectDetails and standardize the verbs you use.
For REST actions, use Get and Post as verbs. For DataRaptor actions, use Create,
Read and Update as verbs. Other recommended verbs for action element names:
o Remote actions: Invoke
o DocuSign envelope: DocuSend
o DocuSign signature: DocuSign
o Email: Send
o Calculation: Calc
o Set Values, Set Errors: Set
o PDF: PDFGen
• Repeating blocks: Use plural for the block name and a singular prefix for element
names. For example, the "Beneficiaries" block contains elements named
"BeneficiaryName," "BeneficiaryStreet," and so on.
• Checkboxes: Append "chk" to the element name
• Display elements: Append an indication of the content, such as "Hdln" for
headlines, "Txt" for text blocks, and "img" for images.
• Conditional views: Use "BRANCHn" for Step element names to indicate where
logical paths begin.
• Date format: Use MM-dd-yyyy.

UI Look & Feel - Templates Best Practices
• Each Omni Script UI element comes with one or more standard HTML/AngularJS
templates.
• Standard templates can be overridden, but, with exception of Selectable Items, it
is recommended to only modify the CSS, not HTML/JS (unless necessary). Extensive
changes to standard templates are not considered as best practices and raise a
risk factor.
• Custom Templates and styling should be controlled from a centralized location
(Vlocity Templates/VF Component/Page/Static Resource).
• Common use cases to override a standard template:
• Branding and specific styling of elements
• Adaption to fields or specific data attributes which need to be displayed and
read.
• Custom Functionality – JS events or custom filtering which require extending
existing modules or creating new ones.
• Selectable Items modification – Selectable Items templates are samples provided
by Vlocity and intended to be modified.
Tips:
• Always refer first to the OOTB template of the element and start your
development on top of this baseline. These templates are available for
import in the Vlocity Template Designer.
• The Script Configuration section in the OS Designer allows easy and quick
testing within the Custom HTML and Custom JavaScript sections.
Optimizing Omniscript For Good Performance
Update your Version of Vlocity

We are always making changes to improve performance at the software level. Ensuring
that your org has the latest version of the Vlocity package installed allows you to take
advantage of the benefits in each new version of OmniScript.
Reduce Extraneous Elements:

Each element that you use in an OmniScript adds overhead, especially when editing the
OmniScript in the Designer. The general recommendation is to keep any single
OmniScript below 500 elements. (Note that things like Steps, Actions, and Blocks are all
considered elements.)
Platform Cache and Its Importance

Using a cache to store frequently accessed, infrequently updated data saves round trips
to the database and improves performance.

We can have multiple cache partition on basis of the functionality we are using in Vlocity.
Some recommended partitions are:
• CPQ Partition: Product Definitions and Rules

• Vlocity Metadata: Cached definitions of DataRaptors and Integration Procedures.
• Rating Cache Metadata: Calculation Procedure definitions, Matrices header
definitions.
• Vlocity API Response: Cached responses from Cached VIP or Cache Block.
We need to make sure we have CPQ Partition, Vlocity Metadata, Rating Cache
Metadata are present, and size allocated to them is more than 0.
Use Reusable Omni Scripts Where Applicable

Reusable Omni Scripts allow you to create one OmniScript and embed it into another
OmniScript. For example, if you have a Step that collects a customer's information, you
can create that as a reusable script and include it in any other Omni Scripts where you
might need it. This has a few benefits:
• Because you can include a reusable script on many other Omni Scripts, this saves
you from having to create the same group of elements more than once.
• The OmniScript Designer only to load the reference to the reusable script, rather
than all the elements contained in it, improving performance in the Design.
• There are a few things to note when using reusable Omni Scripts:
o OmniScript checks for duplicate element names within a given OmniScript.
However, it does not currently check for duplicates when a reusable script
is embedded within another OmniScript. Therefore, it is a good practice to
include a prefix (or suffix) on all element names within a given reusable
OmniScript, to ensure that the element names are unique.

o A reusable OmniScript can only be included in a non-reusable script. You
cannot "nest" reusable scripts by including a reusable script inside of
another reusable script.
Use "Out of the Box" Functionality Whenever Possible

It is possible to use HTML, CSS, and JavaScript to customize your OmniScript to enhance
and extend the style and functionality of the Vlocity product suite within your own
organization. This allows OmniScript to be a massively useful tool for nearly all use cases,
customized to your own needs.
However, whenever possible, it is recommended to use the "out of the box" functionality
for OmniScript elements. Adding custom templates and functionality to an element adds
additional overhead and processing requirements and has greater potential to
introduce bugs. Customizations made in this manner are not within the scope of Vlocity
Support.
Perform Calls Asynchronously

In a project where the customer experience is critical, being able to execute
independent calls asynchronously drastically increases performance. You can use the
"asyncStart" and "asyncEnd" parameters to run actions asynchronously. “Ideally load time
for Omniscript, should be 2-5 seconds at maximum.”
Hiding fields in OmniScript while still allowing them to be prefilled

In order to configure fields to always remain hidden but to still be accessible to be
prefilled, follow these instructions:
• Reference the following documentation to hide the element.

• Never place a manufactured Conditional to hide the element, this will not allow
the element to be prefilled. Here's a failing example:
Hiding OmniScript Elements

• Use the hide property on OmniScript Input Components, Blocks, Steps, Groups,
Formula, aggregate to hide an element and child elements.
• To enable hiding:
o From the element properties panel, click Edit as JSON.
o Set the "hide" property's value to true.
• To enable a hidden element to be prefilled:
o Click the element you want to prefill with.
o Check the box labeled Available for Prefill When Hidden.

LWC OmniScript Overview
Introduction
Vlocity software for its six industries – built using Lightning Web Components, a modern
JavaScript programming model for building applications on the Salesforce Platform.
Using Lightning Web Components allows Vlocity to fully leverage low-code tools to
deliver modern, fast industry cloud software that enables digital transformation in
customer-centric industries.
Vlocity Lightning Web Components provide four compelling business benefits:

1. Low Total Cost of Ownership (TCO)
2. High Performance
3. They’re OmniChannel-enabled
4. They’re extremely flexible

How To Use Custom LWC Into Vlocity OS
• Update XML metadata file in your LWC component with below

o Set the isExposed metadata tag to true
o add the namespace of your Vlocity package by using the
runtimeNamespace metadata tag.
o Add Targets
• Extend the Base Mixin- Update JavaScript file as below

o import and extend the Lightning web component(example in below :
OmniscriptText)
LWC Limitations over AngularJS
• We cannot use expressions in LWC.

• We cannot pass parameters to functions.
• Two way binding is not available.
• Limited API such as Navigation Item, Workspace, Utility bar are not available in
LWC yet.
• @api properties that gets passed on to children’s are read-only.
• Modifying an element inside of a tracked array property will not trigger a render
update.
● Component styling cannot reach across component boundaries.

Converting an Angular OmniScript to an LWC OmniScript
• LWC OmniScripts may begin with an uppercase letter.

• Check the ‘Enable LWC’ checkbox.
• Replace any existing Done Actions in the OmniScript with a Navigate Action
• Elements in an Angular OmniScript that use custom templates must now use
custom Lightning web components to provide custom functionality. (see below
section to achieve this)
• Before previewing an LWC OmniScript that uses custom Lightning web
components, you must activate the OmniScript. If the OmniScript is not active,
custom Lightning web components won't render in the preview. If you deploy
changes to a custom Lightning web component that is present in an Active
OmniScript, the OmniScript will display the changes.
Changes in Functionalities Exclusive to Vlocity Cards Lightning Web Component
Functionality Description Reference
Card and Card When creating a card or layout in the Card Card and Card Layout
Layout Naming Designer, the name and author must only Naming Conventions
Conventions contain underscores and alphanumeric
characters.

Functionality Description Reference
Configure the Configure metadata properties on an LWC Configuring the

Metadata Values for enabled card with an updated, more user- Metadata Values for an
an LWC Card friendly Show XML Interface LWC Card
Download LWC In the Card Designer, download Custom Downloading Custom

Component LWC components templates and Unmanaged LWCs From
components only. Vlocity managed LWCs the Card Designer
are not downloadable.
Error Handling in LWC
• Error handling is very crucial in LWC.

• Small error on state template LWC will crash your entire layout.
• Always check for undefined fields before processing it.
• Use if:true={dynamicField}, to check before using a field that may have invalid
values.
• Easiest way to identify error in your component is to use errorCallback(), add this
method in both of your state and layout template LWC.
Parallel Action Block
• New OmniScript Action enables calling up to four actions in parallel from the
browser.
• Improved performance in scenarios that don’t require serialized callout
Note: Vlocity will continue to support the older AngularJS version of the
platform tools. However, it is strongly recommended to move to LWC in order
to be able to consume further product updates.

OmniScript Architecture
UI Control Decisions and Patterns
 HTML
• Leverage Standard LWC toolkit and can use available slots

• Components can be customized to be reused
 CSS
Lightning & Newport Themes are available OOTB

• Use Newport Design system to update Sass theme and components
• Use Sass mixins to generalize and reuse any styling logic with Newport
 JS
The following functionalities are available OOTB:

• Extensions and Imports
• Get & Set (can be used with changes)
Best Practice: Maintain a single global branding style sheet using Newport
Design System to unify and have a consistent look & feel across pages.

DataRaptors Best Practices
To maximize the benefits of DataRaptors, follow these best practices whenever possible:
• Create targeted DataRaptors that only extract or load the data needed for one
operation.
• Use relationship notation (queries) whenever possible to pull data from other
SObjects. For more information, see Using Relationship Notation Instead of Multiple
Extract Steps.
• Try to keep the number of SObjects to three or fewer.
• In Extract Data Raptors we should have 3-5 Queries with minimal formulas and
output field should not be more than 30.
• In Transform Data Raptors there should not be more than 200 output fields.
• In Load Data Raptors there should not be more than 3 objects.
• Ensure that all filtering and sorting (ORDER BY) operations are on indexed fields.
The Id and Name fields are always indexed.
• Use caching to store frequently accessed, infrequently updated data.
• Make use of Turbo DataRaptors where no transformation is needed and working
on single object.
• Unused DataRaptors need clean up and those should be removed from the org if
required.
• Avoid creating “Uber” DataRaptors to cover as many of the data needs as
possible. Limit it to max 3 objects.
• Use formula fields whenever possible to pull data from other objects.
o SOQL is the fastest way to get the related data into DataRaptor output.
o

Integration Procedures Best Practices
To maximize the benefits of Integration Procedures, follow these best practices whenever
possible:
• Use Integration Procedures in case of multiple subsequent data calls to Salesforce

from OmniScript. Performance is greatly improved on Omniscripts/cards.
• Use a Response Action in Integration Procedure to trim the response data and only
return what is needed. Please check it out how to trim data.
• Use multiple Response Actions with different Execution Conditional Formulas to
allow an Integration Procedure to exit early under appropriate conditions.
• You can combine multiple Actions in a single server call like
o DataRaptors Extraction
o Post Action
o Transformation Action
o HTTP Actions
o Remote Actions

• Can read data from Salesforce and from External System using REST Calls.
• Call Apex code directly.
• Only Return the Data needed through response.
• You should merge only 1-2 DataRaptors ideally in Integration Procedures.
• Its recommended to have no / moderate calculation on the Integration
Procedures.
• Using Integration Procedures, allows the project team to enable Vlocity Event
Tracking for performance telemetry.
• Cache a block in an IP to increase the performance in case of frequent data
retrieval operations. A Cache Block saves the output of the steps within it to a
session or org cache. You can determine how long data remains in the cache.
The minimum value is 5 minutes.
• Use Batch Action in Integration Procedure to run a Vlocity Scheduled Job with a
Data Source Type of Data Input or Query. Only active jobs can be chosen to run.
• Response time should be reduced match the Salesforce default callout time of
10S for callout or implement continuation
To run data operations asynchronously, call Integration Procedures using these settings:
• Use Future — Use when the calling OmniScript or Integration Procedure doesn't
need a response and completion time is not critical.
• Invoke Mode: Fire and Forget — Use instead of Use Future when the calling
OmniScript must invoke the Integration Procedure immediately.
• Invoke Mode: Non-Blocking — Use to run the Integration Procedure immediately
while continuing the user interaction of the calling OmniScript. A response is
returned when the Integration Procedure is complete.
• It can be called from
o an OmniScript
o Vlocity Layouts and Cards
o an API
o Apex code
o Salesforce Flow
• Using VIPs as the primary process allows the developer to ‘Future Proof” their
designs
• Using VIPs allows the project team to enable Vlocity Event Tracking for
performance telemetry

Cards Best Practices
Use session variables to store specific variables and set default values for these variables,
these variables can be set with values from a data source or with “hard-coded” values.
• Use “zones” to make complex layouts with nested layouts and card groups easier
to administrate.
• Use the event framework to communicate between different layouts and cards,
with events you can:
o Refresh data sources
o Update data sources
o Add/Remove cards
o Set records
o Set loading status
• Use “Integration Procedures” over all data sources when handling complex tasks,
as it allows for the most flexibility over retrieving and handling data.
• Use the “Order By” and “Reverse Order” options in the data source to order your
records on the client side.
• Use the “Result JSON Path” option to select a JSON node from the result, the
layout/card will only use that node and discard the rest.
• Always try to Use one-time binding (using::) in your templates to keep the number
of watchers down to a minimum.
• Reuse base templates or existing templates
• Create a base mixin template with all your variables to have a central location in
which to change your style
• Use debugMode=true page parameter while developing to view console logs
and keep track of the number of watchers on your app.
• Application factors & levers that impact performance:
o Understand Browser Performance factors
o External System Call performance (SFDC Governors)
o Take advantage of Vlocity Stackable Layout structure

Naming convention
Use meaningful name with lower-case text. Separate and delimit word with hyphen
{-} {prefix}-{type}-{obj}-{style/description}
• {prefix} = console, cpq, mobile, Vlocity-interaction, acuity, community, INS, dx

• {type} = canvas, card, story, list, flyout-grid, flyout-grid-items, action-grid
• {obj} = -member (optional, avoid object specific template design when possible)
• {style/description} = describe the style used for the template i.e. slds, nds.
LWC Cards
• The best practice for card names is:

o Use all lowercase for the prefix
o Title case for the other words
o A space between all words
• You can reuse card titles
• Cards must have a unique name/author.
o The card author defaults to the value set in the Organization Name field in
your org settings (Setup > Company Information).
o When the card author is Vlocity, this means the card is part of the
managed package and you cannot edit it.
Troubleshooting for the Cards Framework
• You cannot:
o Delete an activated card.
o Edit card states without data in the layout.
o Delete a card that is used in another layout.

Console Size and Card Layout Best Practices
When designing Vlocity Consoles, you can adjust the width in pixels to design and
optimize for a screen size. This section outlines a few examples and suggested guidelines.
Console component size is generally driven based on the common size of the screen you
are implementing on. Vlocity recommends that you modify the console size to best fit the
screen size you are implementing to and try different column sizes and the number of
card layouts to see which works best for your implementation.
General Recommendations
• Screen Size: 24 Inches or Higher
• Resolution Minimum: 1440x936
• Recommended Resolution: 1920x1080
• VDO sidebar component defaults to 350px but shouldn't go below 220px
• Card Layouts can be between 1-3 cards long, but 2 Card Layouts are most
common (screen shot examples of each Card Layout are attached)
Naming Conventions
Layout names are unique. Use meaningful names and lower-case text and separate and
delimit words with hyphen { - }, no spaces. {prefix}-{primary obj or record type}-{#x}-
{related object}-{description}-{version}
• {prefix} = VPL, vdo, health, INS, mobile, myapp

• {primaryobj} = account, campaign
• {recordtype} = individual-family, commercial, agency, health
• {related obj} = parties, policies, claims, producers, contacts
• {description} = highlight, list, summary, detail
Example Names:
• myapp-home-product
• myapp-home-kitchen-sink
• health-individual-family-plans
Layout Data Sources
• Use “Integration Procedures” over all data sources when handling complex tasks,
as it allows for the most flexibility over retrieving and handling data.
• If Field Level Security is a concern, use “Integration Procedure” as a data source
instead of “SOQL”, as FLS will be enforced.

• Use the “timeout” option to avoid keeping your UI waiting for data to be fetched
after a certain period.
• Use the “interval” option to keep your data refreshed but be aware to avoid
aggressive timings, anything below 1000 ms should be used only in special
scenarios.
• You can use the “Order By” and “Reverse Order” options in the data source to
order your records on the client side.
Tips:
• When debugging your Layout/Card for performance, check the

data source in the Card Designer first and sample the time it takes to
fetch the data, usually this is the biggest bottleneck.
Bad Practices of Card Layouts to Avoid
• Avoid too many levels of nested layouts as it decreases performance overall.

• Avoid fetching data inside of a template unless necessary.
• Avoid data source calls on multiple cards and consolidate to one API call on
layout.
• Avoid serialized(sync) calls.

Templates and UI Best Practices
Templates consist of HTML, JS and CSS. Let see best practices of all of them.
Note: LWC OmniScripts do not support Vlocity Templates
General Best Practices
• Make sure your template is Mobile first and accessibility ready.

• Always check the browser compatibility chart when creating a template.
• Avoid setting global variables on the $rootScope, use Services.
• Use debugMode=true page parameter while developing to view console logs and
keep track of the number of watchers on your app.
• Use one-time binding in your templates to keep the number of watchers down to
a minimum.
• Always try to reuse base templates or existing templates.
• Create a base “mixin template” with all your variables to have a central location
in which to change your style.
JavaScript Best Practices
• Use AngularJS in the Card Template.

• Use promises ($q) instead of callbacks.
• It will make your code look elegant and clean. It will save you from callback hell.
• Use:
o $timeout instead of setTimeout
o $interval instead of setInterval
o $window instead of window
o $document instead of document
o $http instead of $.ajax
o $location instead of window.location or $window.location
o $cookies instead of document.cookie
• Use Moment.js to manipulate dates.
• Use lodash.js for utility functions
• Keep the event loop free
• There should error handling mechanism in place.
• Keep a check on the un-used code in the JS File.
Bad JS Practices to Avoid

• Do not use $ prefix for the names of variables, properties and methods. This prefix
is reserved for AngularJS usage.
• Don’t use JQUERY.

HTML / CSS Best Practices
• Use Salesforce Lightning Design System as much as possible.

• Combine CSS Elements that share properties.
• Use mixins.
• Use shorthand properties and values.
• Use lower-case and shorthand hex values.
• Use classes in selectors. ID selectors are not reusable.
• Use SVGs for things like logos and icons.
• Use CSS preprocessor SASS/SCSS.
• Use rem units as primary unit type. This includes:
o Positioning (top, right, bottom, left)
o Dimensions (Such as width, height, margin, padding)
o Font size
• Use px units as primary unit type for the following properties:
o Border widths (border: 1px solid #bada55;)
• Use % units only if necessary, where rem will not suffice:
o Positioning (top, right, bottom, left)
o Dimensions (width, height)
• Add media query breakpoints when necessary.
• Separate your code into logical sections using standard comment blocks.
• Commented code needs to be removed before sending the page to production.
• Use SMACSS : Encapsulate styles
• Always use the unique template name as the css class name for the root element.
Bad UI Practices to Avoid

• Avoid mix quotation marks in HTML.
• Avoid at all costs embedding CSS in <style> tags or using inline CSS.
• Avoid using HTML tags in CSS selectors.
• Avoid all use of magic numbers. Re-think the problem.
• Avoid browser-specific hacks.
• Avoid !important. !important greatly increases the power of a CSS declaration,
making it extremely tough to override in the future.
• Not encapsulating styles
Naming Conventions
• Use a consistent CSS naming style.
• Don’t use underscores or “camelCase” to name classes or IDs. Instead, use dashes
to separate words.
• Use simple nouns as names in CSS like .global-alert and .badge

Actions Best Practices
Vlocity Actions are automatically generated URLS that launch Vlocity OmniScripts,
Vlocity Cards components, web pages, or external applications. Actions are typically
specific to a given object type, such as Account, Contact, Policy, or Asset.
• Vlocity Actions are typically specific to a given object type, such as Account,
Contact, Policy, or Asset.
• While Creating an Action Record, If a field is missing in the layout, confirm that the
field is available in the Vlocity Action Layout page layout for the Vlocity
Action object.
• Create Action with a proper naming convention and try to keep it as concise as
possible because there is 80-character limit for an Action Name.
• Use Applicable User Profile picklist field while creating an Action, to restrict the
Action for a Particular User Profile.
• Use Applicable Permission Name field to specify what actions display based on
whether permission is granted to the user's profile or one or more of the user's
permission sets, enter the name of a standard Custom Permission object.
• Use Display On feature to filter where the action displays, select All, Web Client,
or Mobile from the list.
• Use Vlocity provided icons for action icon through the class names in the Vlocity
Icons section of the action details page. In-case you have to use a custom Icon,
Upload a custom icon as an attachment from the Related tab. The latest
attached image loaded (with a size less than 50 KB) is used as the custom image.
If both the Vlocity icon and the custom icon (attachment) are set, the custom icon
is used. When the custom icon is not uploaded, the Vlocity icon is used.
• No Hardcoded or Empty Action URL.

Calculation Matrix Best Practices
• It's more important than ever that you plan out your calculation matrix structure
before you start creating your matrices in Vlocity. Once you choose the Type of a
calculation matrix, you can't change it.
• You can let people modify calculation matrices based on user profiles. In your
Vlocity sandbox and development orgs, it may be useful to let several user profile
groups modify calculation matrices. But, modifying calculation matrices in a
production environment can have severe consequences on the rates you get for
insurance products. It is recommended that you limit the number of people who
can modify production calculation matrices to only essential administrators.
• You can have multiple versions of the same calculation matrix enabled at the
same time. Vlocity uses the start date/time, end date/time, and priority (highest
number is highest priority) to determine which version of the matrix to use.
• Starting in Winter '20 release, calculation procedures and other Vlocity features
that call calculation matrices can use a wildcard in place of a value for one
column. Wild card field definition allows to define a generic value and preventing
to repeat information, hence a more efficient use of storage space.
• Vlocity offers three styles of calculation matrices you can use based on your
business needs:
o Standard Calculation Matrix
o Grouped Calculation Matrices
o Row-Versioned Calculation Matrices
• Grouped calculation matrices are designed to work best for insurance carriers
that have lots of matrices which are almost exactly alike. Same input headers and
same output headers. Grouped calculation matrices improve management and
reduce size requirements.
• If you're wrangling large calculation matrices that can't be sectioned cleanly into
groups and subgroups, you can create calculation matrices that are versioned by
row. For example, you've got a matrix that creates a rating factor per ZIP (postal)
code, which includes all ZIP codes in the United States. You want to be able to
update ZIP codes individually or in small groups. This situation calls for a row-
versioned calculation matrix.
• Use CSV files to create a calculation matrix with a lot of data. This saves time and
reduce errors when configuring complex matrices. For a simple matrix with a small
amount of data, enter the data manually.
• Also, whenever possible, create a new version of an existing matrix, and change
its data manually or by uploading a CSV file containing revised data. This
recommended way of creating a calculation matrix.

Matrix Version Best Practices
• You can only enable a matrix version once. If you need to make changes, you
will have to create a new version.
• A Matrix will only run if the current date and time is between the Start
Date/Time and End Date/Time.
• Only one version of a matrix can be accessed at a time, based on both of these
factors:
o The date/time the matrix was accessed.
o Priority: The highest priority active matrix is the one that runs. (1 is the
lowest priority.)
• Matrices can represent ranges. This keeps them small!
• The previous versions will always be available to allow products with old prices to
still access the proper price tables.

Calculation Procedures Best Practices
A Calculation Procedure allows you to perform multiple mathematical operations and

transformations at the same time. It takes inputs as formatted JSON data, uses lookup
matrices, algebraic operations, and aggregation operations to calculate new data, and
outputs specified data in formatted JSON. It can also have conditional steps.
• Formulas use constant and/or variable values. In Health Insurance Rating, those
often needs to be mapped to product/child specification attributes. Inefficient
related design may lead to lower performances.
• Longer formula in one step performs better than multiple steps with smaller
formulae.
• For each step, make sure to use the ‘Include in Calculation Output’ parameter
only when necessary.
• It is recommended to use a conditional expression in a step only when required as
it creates a second calculation for each step. Also, note that numeric expressions
execute much faster than alphanumeric (i.e. > 10 is faster than <> “Texas”)
• Reduce number of Steps in Calculation Procedures. Avoid transformations in the
Calculation Procedures as every step in the Calculation Procedure will fire the
Calculation Formula Framework, this will badly affect the processing time of the
calculation procedure. Instead, Use DataRaptors either before or after the step.
• At maximum, have only 10-20 steps & 10 matrices call in Calculation Procedures.
• Aggregation steps allow the procedure to aggregate multiple input sets. Using
Vlocity Integration Procedure simulation helps troubleshoot aggregation/multi
input calculation procedure.
• In the context of Health Insurance rating it is to be noted that, As part of Winter
2020, a change was made to both InsProductService : getEligibleProducts (get
eligible products’ Id) and InsProductService : getRatedProducts APIs to allow
them to be called in parallel greatly enhancing the performance of the rating
process.
• Calculation Procedures require an explicit save! Save your work before you go to
the simulation!

Recommended Tool Set for Vlocity
• CI/ CD: Vlocity DX

• User Story / Issue Tracking: JIRA
• Repository: Bitbucket
• Automated Testing: Fusion System and Services
• Vlocity Success Community Online Training: DevOps Administration
Vlocity Testing Strategy
It is key for testing teams to align their test design, test automation, and test case
development with an agile and DevOps centric process
Build, Measure and Improve:
Build
• You cannot improve what you do not measure

• Embed performance measurement/tuning steps into project plan
Measure
• Automated system generated click stream testing

• Reusable tests
Improve
• Finding performance issues early reduce cost of overall project

• Boosts End User confidence in the solution
• Convert PSR testing phase to validation rather than break/fix

Org Assessment – By Vlocity Expert Services
Scope
• Provides an overview on Vlocity and Salesforce objects configured in an org.

• Provides a high to mid-level analysis of Vlocity artefacts.
• Analyses overall compliance with Vlocity Best Practices.
• Identifies potential sources of performance impact.
• Identifies areas for further investigations.
Deliverables
• Detailed report on Vlocity and Salesforce artefacts

• Recommendations on potential enhancements of Vlocity and Salesforce objects
Duration
• Typically, 5 days

Issues resolutions in OmniScripts:
Issue Solution
Upon launching an Resolution:Add a parameter to the target url in the Vlocity action i.e
Omniscript flow and loadWithPage=false. By adding this parameter, the OS is loaded on
proceeding with a the client side rather than the default server side.
few steps, getting the Target URL:
below error message: /apex/vlocity_ins__OmniScriptUniversalPage?id={0}&OmniScriptTyp
e=TEST%20Library&OmniScriptSubType=PS-
Maximum view state TEST&OmniScriptLang=English&PrefillDataRaptorBundle=&scriptMo
size limit (170KB) de=vertical&layout=newport&ContextId={0}&loadWithPage=false
exceeded. Actual
view state size for this
page was >170 KB
Cancel Operation Cancel Button Issue:

guided flow
1. Use the below target url in VLocity Action-
navigating to Home
Page rather than /apex/vlocity_ins__OmniScriptUniversalPage?id={0}&OmniScriptTyp
context of record. e=ANA%20Library&OmniScriptSubType=LG_Attach_H%26W_Packa
ges&OmniScriptLang
=English&PrefillDataRaptorBundle=&scriptMode=vertical&layout=n
ewport&ContextId={0}&omniCancelAction=asdf
2. Under Omniscript --> Script COnfiguration--> Cancel Button

Properties--> Cancel Source--> Replace “ContextId” with
“QuoteId” (the exact id in that OS context)
Data raptor results Resolution

are not fetched for
the related objects Correct way of adding a null filter in extract data raptor
when filter in the is vlocity_cmt_parentItemId__c = '$Vlocity.NULL'
query is compared to
null

Clear or Reset a Field DataRaptor will not remove data from a record by default. You can override this
behavior using the "Overwrite All Null Values" setting in a DataRaptor's options.
Value Using
DataRaptor Resolution
To ensure that the sObject field is cleared if the corresponding JSON field
is empty, enable the "Overwrite All Null Values" option in the DataRaptor.
Clearing OmniScript Description

Fields Based Upon A
Field Change If you have a need to clear fields based upon the change of a field it is
possible using a set values field.
Resolution
To enable field clearing:
1. Add a set values element to the step where you want to clear the
information.
2. In the custom javascript section of the Script Configuration add
code that auto-clicks the set values.
Query Example:
jQuery(function() {
$("#Select1").change(function() $("#SetValues1").click()
});
});
Select 1 is element or field – By change of this field to clear other

fields dependent & dependent2 should get nullified.
Use attached sample OS for better understanding.

Adding Parameters Description
to a Done Action
To add parameters to a Done Action in OmniScript, you can list them as
either hardcoded key/value pairs or use a merge field to make it
dynamic.
Resolution
For example, MyTestPage?userId=%userId%&source=omniscript would
pass the extra parameter userId, dynamically filling the current user's Id,
and a static source parameter.
Description
This article describes how to pass multiple parameters in OmniScript's
Done Action URL.
**************************************************************************
Resolution
If you're trying to pass parameters in an OmniScript's Done Action, they
should be before the # character and separated by the & character.
For Example:
../../apex/[OmniScriptName]?ContextId=%AccountId%&value1=%value1
%&value2=%value2%#/OmniScriptType/[Type]/OmniScriptSubType/[SubTy
pe]/OmniScriptLang/[Language]/PrefillDataRaptorBundle//true

Data is not pre-
populating from an
Omniscript Action
Applying CSS Do inspect and take the element name- example- .via-slds .slds-form-
Changes element and put the code in OS—Script Configuration Custom HTML Templates
<style>
#ELEMENTNAME {
font-weight: bold;
}
</style>
Changing the Resolution
Default OmniScript
Validation Error To do this:
1. From Setup, navigate to Custom Labels.
Message
2. Search for the 'OmniStepValidationError' Custom Label.
3. Click ‘New Local Translations / Overrides’ or edit the existing
translation/override
4. Select the language and enter the error message you wish to display.

Hiding the Previous or Resolution
Next buttons on a
step in OmniScript To hide these buttons:
1. Open the element Properties for the Step element.

2. Open the Button Properties section.
3. Under Previous Width or Next Width, drag the slider all the way to
the left, so that it reads 0. If you want to hide both buttons, do this
for both sliders.
Age of DOB field You have DOB field of type date and you need age to be displayed
based on the entered DOB
Create a formula field and put
AGE(%DOB%) ---DOB element name
Reduce whitespace Resolution

at the bottom of an
OmniScript Step The standard CSS for OmniScript puts a lot of whitespace below your last
element, above the Previous and Next buttons. You can fix this with a bit
of CSS:
Put this in the Script Configuration | Custom HTML Templates in your

OmniScript.
<style>
.via-slds form[stepForm] {
display: table;}</style>
Determine if a Resolution
specific value was
picked in multiselect 1. Add a Set Values component after the Selectable Items component.
2. In the Set Values, the function will look similar to:
picklist
=CONTAINS(%Step:SelectableItems|n:FirstName%, Value)
Note:
• Step = Step Element Name

• SelectableItems = Selectable Items Element Name
• FirstName = The field in the Selectable Items that you're looking
for.
• Value = The value that you're matching against.
If any of the selected FirstNames matches the value, the equation will
return true.

"ContextID": "",
"Person": {
"FirstName": "John",
"LastName": "Smith"
},
"Product": [
"Name": "Lorem Ipsum",
"ProductId": 1234
},
"Name": "Lorem Ipsum",
"ProductId": 5678
%Person:FirstName%
%Product|1:ProductID%
Required fields in Description
Omniscript no longer
preventing users from If you have required fields but can still proceed the problem most likely
that you don't have validation required checkbox checked
continuing
Resolution
To check look under the template for the step make sure the checkbox
for validation required is checked
Unable to display Description

value in OmniScript
after extracting from Problem: The values successfully extracted by DataRaptor are not
displayed in OmniScript.
DataRaptor
Resolution
Solution: Edit the OmniScript in JSON mode and enable
the "accessibleInFutureSteps" property for all required fields. For more
information, please see the documentation.

Customizing the Put this in the Script Configuration | Custom HTML Templates in your
Loading Spinner in OmniScript.
OmniScript
<style>
.via-nds .nds-spinner {
width: 15rem;
text-align: center;
.nds-spinner_brand.nds-spinner svg { width: 50%; }
.nds-spinner_brand.nds-spinner:before {
content: "Please Wait...";
font-size: 2rem;
</style>
Google Map API https://success.vlocity.com/s/article/OmniScript-Google-address-

lookup-and-map-integration

References
• Vlocity University : https://vlocity-university.litmos.com/home/dashboard

• Vlocity Success Community : https://success.vlocity.com/s/
• Vlocity Platform Best Practices - Shared by Vlocity Expert Services
• Vlocity University Modules
o Vlocity LWC Best Practices and Patterns : https://vlocity-
university.litmos.com/course/4180290
o Vlocity Platform Essentials : https://vlocity-
university.litmos.com/home/LearningPath/104370
o Vlocity Platform Foundations : https://vlocity-
o Vlocity UI Developer Training : https://vlocity-
o Vlocity Best Practices : https://vlocity-

2020 - 09 Vlocity Design Principles and Best Practices

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

2020 - 09 Vlocity Design Principles and Best Practices

Uploaded by

Copyright:

Available Formats

Vlocity Design Principles and Best

© 2020 Deloitte Development LLC. All rights reserved.

Document Name Design Principles and Best Practices for

Document Author Praveen Singh

Document Version V 1.0

Date Releases September 2020

Document Edit History

Document Review/Approval History

© 2020 Deloitte Development LLC. All rights reserved.

Revision History ......................................................................................................................... 2

© 2020 Deloitte Development LLC. All rights reserved.

© 2020 Deloitte Development LLC. All rights reserved.

Tools offered as part of Managed package are:

© 2020 Deloitte Development LLC. All rights reserved.

Application factors & levels that impact performance:

• Use Configuration is stead of code.

© 2020 Deloitte Development LLC. All rights reserved.

General Best Practices

For ease of maintenance

For best performance

Business Process & Logic Best Practices

© 2020 Deloitte Development LLC. All rights reserved.

Client-side & Server-Side Best Practices

© 2020 Deloitte Development LLC. All rights reserved.

© 2020 Deloitte Development LLC. All rights reserved.

Optimizing Omniscript For Good Performance

Update your Version of Vlocity

Reduce Extraneous Elements:

Platform Cache and Its Importance

© 2020 Deloitte Development LLC. All rights reserved.

Some recommended partitions are:

• CPQ Partition: Product Definitions and Rules

Use Reusable Omni Scripts Where Applicable

© 2020 Deloitte Development LLC. All rights reserved.

Use "Out of the Box" Functionality Whenever Possible

Perform Calls Asynchronously

Hiding fields in OmniScript while still allowing them to be prefilled

• Reference the following documentation to hide the element.

Hiding OmniScript Elements

© 2020 Deloitte Development LLC. All rights reserved.

Vlocity Lightning Web Components provide four compelling business benefits:

© 2020 Deloitte Development LLC. All rights reserved.

• Update XML metadata file in your LWC component with below

• Extend the Base Mixin- Update JavaScript file as below

LWC Limitations over AngularJS

• We cannot use expressions in LWC.

© 2020 Deloitte Development LLC. All rights reserved.

• LWC OmniScripts may begin with an uppercase letter.

Changes in Functionalities Exclusive to Vlocity Cards Lightning Web Component

Functionality Description Reference

© 2020 Deloitte Development LLC. All rights reserved.

Configure the Configure metadata properties on an LWC Configuring the

Download LWC In the Card Designer, download Custom Downloading Custom

Error Handling in LWC

• Error handling is very crucial in LWC.

Parallel Action Block

© 2020 Deloitte Development LLC. All rights reserved.

UI Control Decisions and Patterns

• Leverage Standard LWC toolkit and can use available slots

Lightning & Newport Themes are available OOTB

The following functionalities are available OOTB:

© 2020 Deloitte Development LLC. All rights reserved.

© 2020 Deloitte Development LLC. All rights reserved.