Professional Documents
Culture Documents
2020 - 09 Vlocity Design Principles and Best Practices
2020 - 09 Vlocity Design Principles and Best Practices
Practices
September’ 2020
Document Information
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.
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.
• 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.
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.
• 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.
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.
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.
• 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.
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.
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.
• 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.
HTML
CSS
JS
Best Practice: Maintain a single global branding style sheet using Newport
Design System to unify and have a consistent look & feel across pages.
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
To maximize the benefits of Integration Procedures, follow these best practices whenever
possible:
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
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
Use meaningful name with lower-case text. Separate and delimit word with hyphen
{-} {prefix}-{type}-{obj}-{style/description}
LWC Cards
• 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.
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}
Example Names:
• myapp-home-product
• myapp-home-kitchen-sink
• health-individual-family-plans
• 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.
Tips:
Templates consist of HTML, JS and CSS. Let see best practices of all of them.
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
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.
• 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.
• 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.
• 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!
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
Improve
Scope
Deliverables
Duration
• Typically, 5 days
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
=English&PrefillDataRaptorBundle=&scriptMode=vertical&layout=n
ewport&ContextId={0}&omniCancelAction=asdf
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()
});
});
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
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.
Age of DOB field You have DOB field of type date and you need age to be displayed
based on the entered DOB
<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:
If any of the selected FirstNames matches the value, the equation will
return true.
"Person": {
"FirstName": "John",
"LastName": "Smith"
},
"Product": [
"ProductId": 1234
},
"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
.via-nds .nds-spinner {
width: 15rem;
text-align: center;
.nds-spinner_brand.nds-spinner:before {
font-size: 2rem;
</style>