OmniStudio Documentation
OmniStudio Documentation
Copyright 2021 Vlocity LLC, a Salesforce company. All rights reserved. Information in this document is subject to change without
notice. This documentation and the software, tools, templates and other material described in this document (“Vlocity Materials”) are
furnished exclusively under a subscription services agreement or nondisclosure agreement. The Vlocity Materials may be used or
copied only in accordance with the terms of those agreements. No part of the Vlocity Materials may be reproduced, stored in a
retrieval system, or transmitted in any form or any means electronic or mechanical, including photocopying or recording for any
purpose other than the licensee’s personal use as set forth in the applicable agreement without the prior written permission of Vlocity
LLC. Vlocity is a trademark of Vlocity LLC, a Salesforce company, as are other names and marks. Other marks appearing herein may
be trademarks of their respective owners.
OmniStudio Foundation
Table of Contents
OmniStudio ................................................................................................................................ 1
OmniScripts .............................................................................................................................. 10
OmniScript Best Practices .................................................................................................. 10
Business Process and Logic ....................................................................................... 10
User Interface ............................................................................................................ 10
User Experience Design Principles ............................................................................. 10
Performance Factors ................................................................................................. 11
OmniScript Designer Overview ........................................................................................... 11
OmniScript Designer Highlights .................................................................................. 12
Header (1) ................................................................................................................. 12
Navigation Panel (2) .................................................................................................. 12
Canvas (3) ................................................................................................................ 13
Build panel (4) ........................................................................................................... 13
Properties panel (5) ................................................................................................... 14
Setup panel (6) .......................................................................................................... 14
In-Product Help ......................................................................................................... 14
Preview (7) ................................................................................................................ 15
Access OmniScript Designer ...................................................................................... 15
Create an OmniScript ................................................................................................. 16
Set Up an OmniScript ................................................................................................ 16
Creating the Script Structure ....................................................................................... 16
Build an OmniScript with Elements in the OmniScript Designer ..................................... 17
Configure Elements in the OmniScript Designer ........................................................... 20
Add the Vlocity Actions Toolbar to a Community Record Page .................................... 764
Configure the Vlocity Action Toolbar .......................................................................... 764
OmniStudio
OmniStudio provides a suite of services, components, and data model objects that combine to create
Industry Cloud applications. Create guided interactions using data from your Salesforce org and external
sources.
OmniStudio Basics
Build Service Consoles and Industry Cloud Apps with the basic building blocks of OmniStudio.
OmniScript Basics
A Vlocity OmniScript guides users through complex processes with fast, personalized, and consistent
responses. For example, you can create an OmniScript to guide:
You can create a guided interaction to match the flow of your process. OmniScript is a declarative scripting
tool, meaning you create it with clicks, not code. To create the structure of an OmniScript, you drag and
drop different types of elements to:
Templates control both the style and appearance of OmniScripts. You can customize whether your guided
interaction has a horizontal or vertical mode, branding, and any other aspects you wish to change.
• An action button such as the one shown here on the account page
• An action link on a card
FlexCards Basics
FlexCards provide tools for building customer-centric, industry-specific UI components and applications on
the Salesforce platform. FlexCards are rich in information and actions relevant to the customer's context.
Create your FlexCards in a declarative design tool and add them to your Lightning or Community pages.
Customer Context
Each customer is linked to multiple aspects of your company's products and services. Customers have
accounts, preferred methods to receive bills, preferred means of contact, and a history of the products they
have purchased as well as their interactions with the company. When agents must use different systems to
gather contextual information about the customer, it affects customer service. Use FlexCards to streamline
customer engagement.
Designer
The FlexCard Designer is a declarative tool to create UI components. Build dynamic customer-centric UIs
without code from a drag interface with WYSIWYG editing. See OmniStudio FlexCards.
FlexCards
A FlexCard is a block that contains a combination of pertinent information and links to processes within a
specific context. For example, an account card can include unique account information, such as:
• Status
• Priority or service level agreement
• Creation date
• Closing a case
• Opening a new case
• Creating a new task
In the FlexCard Designer, you can create an action that launches or updates an OmniScript, navigates to a
web page or application, displays a flyout, fires an event, update field values, and more. See Add an Action
to a FlexCard.
Data Sources
Select from multiple data source options to retrieve data to display on your FlexCards. For a list of data
sources available in the FlexCard Designer, see FlexCards Data Source Reference.
• You need to read data from SObjects or write data to SObjects, but not both.
• The SObjects you need to read from or write to have a defined relationship. For example, Accounts and
Contacts have a relationship because a Contact can have an AccountId value.
• You only need to work with JSON or XML data. No SObjects are involved.
• You can perform any needed filtering, calculation, or reformatting of data values using one or a series of
formulas.
• You can make any needed changes to the data structure by mapping input JSON nodes to output JSON
nodes.
• You need to both read from and write to one or more SObjects, which means you need to call at least two
DataRaptors.
• The SObjects you need to read from and/or write to have no defined relationship.
• Transforming your data can't be done using formulas alone. For example, different conditions determine
whether some filtering or calculations are performed at all.
• JSON node mappings aren't straightforward and/or require a series of steps.
• You need to read from or write to multiple data source types, such as SObjects, CSV files, external
objects, Apex classes, and so on.
• You need to perform actions such as calling a REST API, sending an email, merging lists, handling
errors, and so on.
See Also
• DataRaptor Best Practices
• Integration Procedure Best Practices
The agent views order-related information and actions contained in the card. When the agent clicks the new
order link on the card, an OmniScript launches to begin a guided process for purchasing products.
OmniScript uses a DataRaptor to get a list of products for display. Then the agent can choose one or more
products for purchase. When the purchasing process ends, the OmniScript returns the agent to the view
that includes the Orders card.
Designers
Use the new Design System [beta release] to review all the components and download a Sketch library to
accelerate the design.
Developers
Go to the Vlocity Github repository to help you customize and rebrand all the Vlocity Newport based
templates in one place.
Callable Implementations
Vlocity Apex classes and the Remote Actions of OmniScripts and Integration Procedures support the
Callable interface.
In addition, Remote Actions of OmniScripts and Integration Procedures can invoke any class that
implements Callable, regardless of whether it implements VlocityOpenInterface or
VlocityOpenInterface2. You specify the Remote Class, Remote Method, and Additional Input
properties in the same way for classes that implement any of these interfaces.
For a full example, see Make a Long-Running Remote Call Using OmniStudio.OmniContinuation.
1. Go to Setup.
2. In the Quick Find box, enter Installed Packages and click Installed Packages.
3. Verify that the latest version of the package is listed on the Installed Packages page.
4. On the Installed Packages page, click your current OmniStudio Vlocity package.
The resulting page displays the OmniStudio Vlocity package details including namespace, version
number, and license information.
See Also
Overview of Packages in the Salesforce help.
OmniScripts
An OmniScript is an omnichannel customer engagement and a business tool built on the Salesforce
platform. OmniScripts allow you to craft dynamic customer interactions without code and deploy to multiple
channels and devices. Administrators can define a script once and then deploy the script within a
Salesforce application or on a web page.
Create OmniScripts to guide users through sales and service processes with fast, personalized responses,
and seamless integration to enterprise applications and data.
User Interface
OmniScripts use Lightning Web Components to define the styling for both individual elements and the
OmniScript itself.
• Create custom Lightning web components that extend an OmniScript element's component to apply
styling changes. For more information, see Extend an OmniScript Element's Lightning Web Component
• Apply global branding by using the Newport Design System. For more information, see Apply Global
Branding to OmniScripts.
• Reduce the number of fields the user must input information into by prefilling the fields using contextual
data. For more information, see Prefill OmniScript Elements using DataRaptor.
• Avoid confusing the user by breaking processes up into shorter steps that contain a minimal amount of
elements.
• Guide the user by creating contextual help text and logically ordering input fields.
Performance Factors
A set of best practices exists for both Client-side performance and Server-side performance.
• Cut down the payload size of a request by trimming the JSON request. For more information, see
Manipulate JSON with the Send/Response Transformations Properties.
• Reduce server roundtrips by using Integration Procedures whenever multiple actions run between steps.
Run Integration Procedures asynchronously by enabling the fire and forget property.
• Remove unnecessary data by trimming the DataRaptor extract output.
While building your script, preview elements inside steps, view property changes live, and access
contextual guidance with in-product help to discover and learn about functionality without leaving your
script. To access the OmniScript Designer, see Access OmniScript Designer.
NOTE
The OmniScript Designer is optimized for use in the Google Chrome browser.
Header (1), Navigation Panel (2), Canvas (3), Build panel (4), Properties panel (5), Setup panel (6),
Preview (7)
• Building your scripts on a wide and adjustable Canvas and instantly view changes made to element
properties.
• Repositioning, cloning, and adjusting the width of step elements along a 12-column horizontal grid.
• Accessing inactive elements and navigating between elements in high-level and detailed views from the
Navigation Panel.
• Configuring elements from the Properties panel.
• Searching for and dragging elements onto the Canvas from the Build panel.
• Configuring script-wide settings from the Setup panel.
• Viewing contextual In-Product Help to discover and learn about elements and properties without leaving
your script.
• Previewing, testing, and debugging your script in Preview.
Header (1)
In the Header, view metadata and perform actions related to your script.
View high-level metadata about your OmniScript such as Type, SubType, Version, Language, and
Activation status.
In the actions navigation, toggle between design and preview mode, create a new version, activate or
deactivate the current version, edit basic settings, download your OmniScript, and get launch instructions.
The Slide View tab provides a high-level view of the structure of large and complex scripts. Click on a slide to
open the Properties panel for a step or action.
The Tree View tab provides a detailed view of the script's structure. Click on a branch to open the Properties
panel for a step, element, or action.
Canvas (3)
(A) Build your scripts by dragging elements from the Build panel onto the Canvas.
(D) Expand Steps to preview and configure elements. Adjust the width of elements on a 12-column grid,
and drag elements next to each other to automatically take up the remaining width of the grid.
(E) See how your scripts look with a Newport or Lightning theme without switching to Preview.
Configure basic settings, Step Chart Options, Save Options, Knowledge Options, Error Messages,
Messaging Framework, and Lightning Design System Tokens in the UI, or edit properties as JSON.
In-Product Help
In the Build, Properties, and Setup panels, access In-Product Help to view contextual information and
instruction about elements and properties without leaving your script.
(B) View detailed documentation about element functionality with slide-out help panels.
Preview (7)
Preview
(A) Preview your script in real-time with real data.
(B) Enter a record Id into the Context Id field and click refresh to preview your form with test data.
(C) Preview how an OmniScript appears on different devices, such as mobile, desktop, and tablet, with the
Preview Device feature.
(D) With the Theme dropdown, see how your OmniScript looks with a Lightning or Newport theme. If a
custom Newport style sheet is in the org, it overrides the out-of-the-box Newport style sheet.
(E) Reload the Canvas to reset data, and update the Data JSON and Action Debugger.
(F) The Data JSON provides an easy-to-read JSON format, which updates when you enter values in data
fields on the Canvas. Also, copy the entire JSON with just one click.
Debug
(G) The Action Debugger enables you to debug action requests and response data. Search for actions,
copy specific nodes in one click, and clear the console logs.
Create an OmniScript
Create a new OmniScript to build a form in the OmniScript Designer.
IMPORTANT
When using an existing OmniScript in the OmniScript Designer, create a new version of
the OmniScript to update the OmniScript's property set. Without a new version, errors may
appear in the designer. See Upgrade an OmniScript's Property Set.
Set Up an OmniScript
Configure optional settings for your OmniScript in the Setup panel of the OmniScript Designer, such as
making your OmniScript reusable or enabling tracking.
What's Next
Next steps, build your script. See Build an OmniScript with Elements in the OmniScript Designer.
See Also
• Configure Elements in the OmniScript Designer
• OmniScript Designer Overview
Actions outside steps perform actions for the entire script, such as getting, posting, evaluating, and
transforming data. Steps typically include Block, Input, and Display elements, but can also include Actions
as buttons and Functions specific to the step. Learn more about OmniScript Script Structure Definitions.
Each page of an OmniScript is called a Step and can contain Group elements, such as Blocks, Input
elements, such as Checkboxes, Actions, such as Email Actions, and Functions, such as Formulas.
Follow the hierarchical structure of Actions and Steps to build your script. Actions outside steps perform
actions for the entire script, such as getting, posting, evaluating, and transforming data. Steps typically
include Block, Input, and Display elements, but can also include Actions as buttons and Functions specific
to the step. Learn more about OmniScript Script Structure Definitions.
2. (Optional) Populate data fields in your OmniScript. To populate the script's data fields, click Actions,
and drag the DataRaptor Extract Action onto the canvas.
a. Enter a name in the Name field.
b. From the DataRaptor Extract Action dropdown, select a DataRaptor that retrieves data from one
or more related Salesforce objects.
c. (Optional) To configure other DataRaptor Extract Action properties, see DataRaptor Extract Action
Properties.
NOTE
To execute more than one server call to fetch data, use an Integration Procedure or an
Action Block.
3. (Optional) Configure Cancel Options to navigate users that cancel out of an OmniScript to a different
Salesforce experience. See Configure OmniScript Cancel Options.
4. To create a page for your form:
a. Click Groups, and drag Step on to the canvas.
b. To populate your form with data fields and other elements, click the down arrow on the step, and
drag elements from the Build panel into the step. See Steps.
NOTE
Actions placed inside a step render as buttons.
NOTE
To execute more than one server call to fetch data, use an Integration Procedure or an
Action Block.
6. To end the OmniScript and return the user either to where the script was launched or a custom URL:
1. Click Actions, and drag a Navigate Action onto the canvas.
2. To configure the Navigate Action, click the help icon (?) next to the Navigate Action Properties title
in the Properties panel, or see Navigate Action.
What's Next
Next steps, configure your elements. See Configure Elements in the OmniScript Designer.
See Also
• Preview an OmniScript
• Test Data in the OmniScript Designer
1. From your OmniScript, click an element on the canvas or the Navigation Panel to open the Properties
panel.
2. Enter values for any required fields marked with an asterisk (*), such as the Name field of a Text input
element.
3. (Optional) To view an inactive element, see Activate Elements in the OmniScript Designer.
4. (Optional) Enter values for optional fields, such as the Placeholder and Label fields of a Text input
element.
5. (Optional) To learn more about a specific property, hover over the tooltip icon (i) next to the name of the
property.
6. (Optional) For detailed documentation about your selected element, select the help icon (?) next to the
name of the property. See also OmniScript Element Reference.
What's Next
Next steps, preview the look and functionality of your OmniScript. See Preview an OmniScript.
See Also
• Test Data in the OmniScript Designer
• Launch an OmniScript with LWC OmniScript Wrapper
When an element is deactivated, it disappears from the canvas. View inactive and active steps and actions
placed outside of steps in the Slide View of the Navigation Panel. View all inactive and active elements,
including those inside steps, in the Tree View of the Navigation Panel.
1. From OmniScript, In the Navigation panel, click the Slide View icon or the Tree View icon.
2. Click the step or action you want to activate.
3. In the Properties panel, click Activate.
1. From OmniScript, in the Navigation panel, click the Tree View icon.
2. Click a step, and click the element you want to activate.
3. In the Properties panel, click Activate.
See Also
• Create an OmniScript
• Configure Elements in the OmniScript Designer
Preview an OmniScript
View the OmniScript's appearance and functionality by previewing the OmniScript in the OmniScript
Designer.
IMPORTANT
Using Set Values Action to set the context ID only works in preview.
NOTE
Confirm that a Context Id is defined in your data source. For example, if you have a
DataRaptor Extract Action that gets account records, you must have an Input
Parameter whose Data Source is ContextId, and whose Filter Value is the
DataRaptor Extract's output name, such as AccountId.
• Preview Device: To preview how your OmniScript appears on different devices, select Mobile,
Tablet, or Desktop.
• Theme: Preview your OmniScript with a Lightning or Newport theme.
• To reset data fields in your OmniScript after making changes, click the reload icon.
3. (Optional) Hide the Data JSON and Action Debugger by clicking X. Display the Data JSON and Action
again by clicking the debug panel button that appears when the panel closes.
What's Next
Next steps, test your OmniScript. See Test Data in the OmniScript Designer.
See Also
• Launch an OmniScript with LWC OmniScript Wrapper
• OmniScript Designer Overview
NOTE
Confirm that a ContextId is defined in your data source. For example, if you have a
DataRaptor Extract Action that gets account records, you must have an Input
Parameter whose Data Source is ContextId, and whose Filter Value is the
DataRaptor Extract's output name, such as AccountId.
Next Steps
Next steps, launch your OmniScript on a Lightning or Community page. See Activate and Deploy
OmniScripts.
See Also
• Configure Elements in the OmniScript Designer
• OmniScript Designer Overview
• Script: The script is the master container for all the controls. Scripts can be versioned, ported to different
languages, embedded into parent scripts, exported to other orgs, and activated into production.
• Step: A script can contain one or more Steps. The user navigates through the Steps using Next and
Previous buttons. Logic to enforce field validation or required fields can be optionally enforced for each
Step.
• Inputs: Inputs are HTML controls that form the input content of the script.
• Functions: Functions enable you to evaluate data, provide messaging, and obtain a User's location.
• Groups: Elements can be combined into Groups. For example, street, city, state and postal code input
elements may be combined into an address block. Groups are contained within Steps, and may be
repeated to capture an array of data.
• Actions: Action Elements trigger a variety of user-defined actions including remote or REST to
communicate with external sources and Integration Procedure, DataRaptor Extract, or DataRaptor Post
to move data between the script and Salesforce objects. Action Elements can be launched as a button on
the script or run remotely in between Steps.
• Display: Display elements present information to the user.
• OmniScripts: An entire OmniScript can be embedded into another script, allowing you to reuse smaller
scripts across multiple larger scripts.
Example Error
1. From your OmniScript, click New Version to trigger a class that adds any missing JSON properties.
2. Repeat the process for any older or imported OmniScripts.
See Also
• Configure Elements in the OmniScript Designer
• OmniScript Designer Overview
By default, OmniScript uses an org's default currency in single currency orgs and a user's currency in multi-
currency orgs. Use one of the options in this table to override the default Currency Code.
Multi-Currency Dynamically pass in the Currency Code from a URL using &c__OmniScriptCurrencyCode=JPY
the OmniScriptCurrencyCode parameter.
Property Description
Step Chart Placement Display the Step Chart on either side of the OmniScript or above the OmniScript by selecting Right, Left, or
Top.
Hide Hides the Step Chart from users.
See Also
OmniScript's cancel functionality enables users to cancel out of an OmniScript from a Step by clicking a
cancel link. The cancel option directs the user to a Salesforce experience set in the cancel options. Cancel
Options are built on top of the Navigate Action and use the same PageReference types to navigate to
different experiences.
NOTE
Restart OmniScript is not supported as a Cancel Option. See Restart an OmniScript.
1. From OmniScript's Setup panel, expand Cancel Options, and click Enable Cancel.
2. In Field Label, enter the Cancel option's display text. The text displays as a clickable link in every Step
element.
3. (Optional) Check Show prompt before cancel? and enter text into Cancel Message to display a
prompt message. The prompt enables users to return to the OmniScript or confirm the cancellation.
4. (Optional) Replace the existing entry in the browser history by setting the Replace? property to Yes. If
Replace? is set to Yes, users cannot navigate back to the OmniScript.
5. Determine the Salesforce experience that the cancel link will direct to by clicking and selecting a
PageReference type. This page contains further instructions for each PageReference Type that
Cancel Options supports. For information on PageReference Types, see PageReference Types.
What's Next
Deploy the OmniScript and add it to a page to test the cancel functionality. See Activate and Deploy
OmniScripts.
See Also
• Navigate Action Properties
• Navigate Action
Next Steps
Configure Save Options
1. From the OmniScript's Setup panel, expand the Save Options section.
2. Click Allow Save For Later to enable the Save For Later feature.
3. (Optional) Enable steps to automatically save an instance when a user clicks the Next button on a Step
by checking Auto Save on Step Next.
4. In the Save Name Template field, enter a name for the OmniScript instance. This field supports merge
fields—for example, %LastName%, %FirstName% - Application. If this field is left blank, the default
is Saved-OmniScript Name-[RowId]."
5. In the Save Expire In Days field, enter a number to enable the OmniScript instance to remain usable
for a number of days. If a user attempts to resume the script after it expires, the script will start over.
6. Set the Save Object ID field to attach the Saved OmniScript instance to a record. The default value is
%ContextId%. This field supports merge fields. For more information, see Access OmniScript Data
JSON with Merge Fields.
7. (Optional) Enable users to merge data into an updated OmniScript by checking Merge Saved Data
JSON into updated OmniScript. If the option is not enabled, users opening a saved instance will start
from the beginning of the updated version of the OmniScript.
User Message:
NOTE
When an OmniScript is Activated, it generates a unique LWC making saved
OmniScript instances of the previous version unusable. If Merge Saved Data JSON
into updated OmniScript is enabled, when a saved instance launches, the
OmniScript merges the data from the saved instance into the updated OmniScript.
8. In the Save URL Patterns section, map the OmniScript instance URL to a custom field in an Object.
See Map Saved Instance URLs to Custom Fields.
9. (Optional) To enable Allow Save For Later on a per-step basis:
a. From a Step element, expand the Save Options section.
b. Check, or uncheck, Allow Save For Later to enable or disable Save For Later on the Step.
What's Next
Map Saved Instance URLs to Custom Fields
See Also
• Customize the Save for Later Error Message
• Conditionally Display Elements in Saved OmniScripts for Different User Profiles
• View In-Progress and Completed OmniScripts
• Specify a Resume Link in a Visualforce Page
Configure Save URL Patterns to control the URL format that maps to any custom fields. You must create a
custom field in the Saved OmniScript object for every additional URL that you save to an OmniScript
instance.
1. From Salesforce Setup, open the Object Manager, and select the Saved OmniScript object.
2. Add a new custom field that accepts URLs.
3. Copy the field's API name.
4. In the Save URL Patterns section, in the Field API Name field, paste the field API name.
5. In the URL Pattern field, enter a URL using these syntax patterns:
NOTE
OmniScripts must use the LWC OmniScript Wrapper URL patterns to launch saved
OmniScript instance URLs.
• Community Pages:
Using the Community LWC OmniScript Wrapper URL pattern, add the parameter c__instanceId ,
and set it to {0}. Set the c__target parameter to {1}.
https://myDomain.force.com/CommunityName/s/CommunityPage/
c__layout=lightning&c__instanceId={0}&c__target={1}
NOTE
The Community page that opens the saved instance must have the LWC
OmniScript Wrapper component present. See Launch an OmniScript with LWC
OmniScript Wrapper.
• Lightning Pages:
Using the Lightning LWC OmniScript Wrapper URL pattern, add the parameter c__instanceId
and set it to {0}. Set the c__target parameter to {1}.
https://myDomain.force.com/lightning/cmp/namespace__vlocityLWCOmniWrapper?
c__layout=lightning&c__instanceId={0}&c__target={1}
6. (Optional) Test the OmniScript by taking these steps:
a. Save and Activate the OmniScript.
b. Preview the OmniScript and save the instance.
c. Copy the saved OmniScript link.
d. Paste the link into your browser to view the saved instance.
NOTE
If the link does not work, ensure your URL format and any Community page
names are correct.
What's Next
Customize the Save for Later Error Message
See Also
• Configure Save Options
• Conditionally Display Elements in Saved OmniScripts for Different User Profiles
• View In-Progress and Completed OmniScripts
• Specify a Resume Link in a Visualforce Page
When multiple users are updating the same saved OmniScript instance, the first user that saves the
OmniScript becomes the owner of that instance. The user that is unable to save the OmniScript receives an
error that informs them that they need to refresh the OmniScript. Customize the error message users
receive by using the Error Messages property. For more information, see Customize OmniScript Error
Messages.
See Also
When the OmniScript resumes, it uses the profile of the current user. Conditions on elements can
determine whether the user has access to the element. For example, an agent may see data that does not
display to customers.
See Also
• Configure Save Options
• Map Saved Instance URLs to Custom Fields
• Customize the Save for Later Error Message
• View In-Progress and Completed OmniScripts
• Specify a Resume Link in a Visualforce Page
Use prebuilt Visualforce pages for Accounts and Contacts, create custom Visualforce pages for additional
records, or view all records in the Vlocity OmniScript Workbench.
NOTE
If an OmniScript launches from the context of a Contact or Account record, you can view
all in progress or completed OmniScripts for that specific Account or Contact under the
Customer Story section.
<NS:OmniScriptInstanceComponent standardController="{!stdController}"/>
</apex:page>
3. Replace these variables in the code with the appropriate values:
• ObjectName Enter the API name of the standard or custom object.
• NS : Enter the Namespace of the package. For more information, see Viewing the Namespace and
Version of the OmniStudio Vlocity Package.
See Also
Create a new Visual ForcePage and enter the code below. Replace the FieldAPIName variable with the
Field API Name specified under the Save URL Patterns. For more information, see Configure Save
Options.
See Also
IMPORTANT
Your organization must have Salesforce Knowledge enabled to use this feature.
From the OmniScript Designer Preview, you can open the article in a new console or browser tab. Or you
can view the article inside the OmniScript Step or in a modal window.
IMPORTANT
Before enabling Lightning Knowledge, see Lightning Knowledge Limitations.
1. From the Setup panel, expand the Knowledge Options section and check Enable Knowledge.
2. (Optional) To integrate Lightning Knowledge with OmniScript check Use Lightning Knowledge.
Lightning Knowledge must be enabled in your org.
3. (Optional) Select Display Outside OmniScript to launch Knowledge base articles outside of an
OmniScript using the Vlocity OmniScript Knowledge Base component in a Community or Lightning
page. For information on configuring this option, see Open Knowledge Base Articles Outside an
OmniScript.
4. In the Knowledge Article Type Query Fields Map section:
a. In Article/Record Type API Name, enter the Article Type API name for Classic Knowledge or
enter the Record Type API name when Use Lightning Knowledge is enabled.
5. To query additional Article or Record types, click + Add New Knowledge Type Field Map and repeat
Step 4.
6. If Use Lightning Knowledge is enabled, enter the Lightning Knowledge object's API name into
the Lightning Knowledge Object API Name field, such as namespace__Knowledge__kav.
7. (Optional) In Label, enter the text displayed above the Knowledge component, such as Suggested
Articles.
See Also
1. From the OmniScripts Designer, click the Step you want to display the Knowledge component.
2. In the Properties panel, expand the Knowledge Options section, and click Enable Knowledge.
3. Update Language from the default English to your preferred language.
4. Update Public Status from the default is Online to Archive or Draft.
5. In the Keyword field, enter the text to search for. This can be literal text, such as Service
Disconnect. Or, you can use merge fields for variable data. For example, enter %RouterType% to
enable your users to enter keywords to search for in a Text element whose Name is RouterType. For
information on merge fields see, Access OmniScript Data JSON with Merge Fields.
6. To filter articles by their Data Category, enter a SOQL query in the Data Category Criteria field. For
example, enter Troubleshooting__c AT (Router__c) to show articles from the sub-category
Router under the parent category Troubleshooting. For more information on building queries for
Data Categories, see With Data Category filtering Expression
NOTE
You do not need to enter WITH DATA CATEGORY in your query.
7. (Optional) When Lightning Knowledge is enabled, to filter the record types queried by the Step, enter
the Record Type's API name into the Record Type Filter field. For multiple Record Types, enter a
comma-separated list with no spaces, such as FAQ,INFO.
See Also
The Vlocity OmniScript Knowledge Base component renders Knowledge base articles side-by-side with an
OmniScript or as a standalone component. When opening Knowledge Base articles from an OmniScript,
OmniScript passes specific information into the component to search the Knowledge base and render
articles.
1. In your OmniScript's Setup panel, expand Knowledge options, and select Enable Knowledge.
2. Select Lightning Knowledge, and configure the remaining fields using the instructions in Setup
OmniScript to Work with Salesforce Knowledge.
3. Confirm Display Outside OmniScript is enabled.
4. (Optional) Configure Knowledge Options on the Step level. See Configure Knowledge for Individual
Steps in the OmniScript.
5. Deploy the OmniScript by clicking the Activate Version.
6. Open the Lightning App Builder and create a new page with a layout containing at least two regions.
See Lightning App Builder.
7. From the Lightning page, drag the deployed LWC OmniScript component into the page. See Add an
OmniScript to a Community or Lightning Page.
8. From the Components section, drag the Vlocity OmniScript Knowledge Base component to where
you want it displayed.
9. In the omniscriptKey field, enter the name of the LWC OmniScript component using the syntax
type_SubType_Language.
10. (Optional) In the layout field, enter newport to render the Knowledge base article with the Newport
Design System styling.
11. Save the Lightning page and test the OmniScript on the Lightning page to preview the behavior.
See Also
Property Definition
Enable Knowledge Integrate Salescorce Knowledge with OmniScript. You must enable this property in the Properties panel for
each Step that displays the Knowledge component and in the Setup panel.
Setup panel
These properties are unique to the Knowledge Options section in the Setup panel.
Property Description
Display Outside OmniScript Enables launching Knowledge base articles outside of an OmniScript using the Vlocity
OmniScript Knowledge Base component in a Community or Lightning page.
Use Lightning Knowledge Integrates Lightning Knowledge with OmniScript. Lightning Knowledge must be enabled in
your org.
Article/Record Type API Name The Article Type API name for Classic Knowledge or the Record Type API name when Use
Lightning Knowledge is enabled.
Field API Name The API name of the field to search in, such as Title. For multiple fields, enter a comma-
separated list with no spaces, such as Title, namespace__richText__c,Summary.
Lightning Knowledge Object API If Use Lightning Knowledge is enabled, enter the Lightning Knowledge object's API name,
Name such as namespace__Knowledge__kav.
Label The text displayed above the Knowledge component, such as Suggested Articles.
Properties panel
These properties are unique to the Knowledge Options section in the Properties panel when you select a
Step.
Property Description
Language Select the language to display the articles.
Public Status The type of article to display. Enter Online, Archived or Draft.
Keyword The text to search for. This can be literal text, such as Service Disconnect. Or enter
merge fields for variable data. For example, enter %RouterType% to use the input value of a
Text element whose Name is RouterType.
Data Category Criteria Filter Knowledge articles by their data category in a SOQL query. For example, enter
Troubleshooting__c AT (Router__c) to show articles from the sub-category Router
under the parent category Troubleshooting. The WITH DATA CATEGORY clause is not
required in the query.
Record Type Filter If Use Lightning Knowledge is enabled, enter the Record Type's API name to filter the
record types queried by the Step. For multiple Record Types, enter a comma-separated list
with no spaces, such as FAQ,INFO.
See Also
The Seed Data JSON property should be used with static values that seed during the initial load of the
OmniScript. In order to set values using formulas or with information entered into the OmniScript after the
initial load, see Set Values in an OmniScript.
1. In the OmniScript's Setup, find Seed Data JSON section and click +Add New Key/Value Pair.
2. Enter the name of the element to prefill in the left text field. Enter the desired value of the element in
the right text field. If the element has multiple responses, such as a multi-select, you can prefill more
than one value by separating the entries with a semicolon.
3. When the user launches the script, the elements specified in the Seed Data JSON section contain the
static values from the Script Configurations.
4. You can also use the Seed Data JSON property to add hidden nodes to the Data JSON of the
OmniScript. For example, an OmniScript used for troubleshooting may create a case. You could use
the default values from hidden nodes to prefill values. For example, you may want the OmniScript to
create a Case with Type, Status, and Origin defined in the Data JSON of the OmniScript. Using this
method, you can have multiple OmniScripts associated with one DataRaptor interface that creates the
Case.
See Also
• Set Values in an OmniScript
• Prefill OmniScript Elements using DataRaptor
Messaging Framework
Communicate between an OmniScript, windows, Lightning web components, and OmniScript elements
using window post messages, session storage messages, and PubSub messaging.
Determine which object or component needs to handle and use data, and use the corresponding property
from this table:
For information on communicating with an LWC from an embedded LWC OmniScript, see Embed an
OmniScript Lightning Web Component in a Lightning Web Component.
See Also
• Embed an OmniScript Lightning Web Component in a Lightning Web Component
• Make Remote Calls from Lightning Web Components using the OmniScript Action Framework
SEO OmniScripts store the state of an OmniScript in the URL by setting the c__step parameter to the name
of an active Step automatically. Direct users to a specific step in the OmniScript by setting the c__step
parameter in SEO URLs to a Step name in the OmniScript. Refreshing the page does not cause the
OmniScript to begin at the first Step because the Step is stored in the c__step parameter. Include additional
parameters to store the state of elements, insert data into the OmniScript's data JSON, prefill elements, or
conditionally fire OmniScript Actions. Storing the state enables a user to navigate to previous or next steps
using their browser's back and forward buttons.
NOTE
SEO is automatically disabled when running Inline OmniScripts. See Display Inline
OmniScripts on Lightning and Community Pages.
NOTE
It is possible to create OmniScripts that store the state in the c__step parameter without
using the OmniScript for SEO purposes. See Create Stateful OmniScripts.
1. In the OmniScript's Setup section, check Enable SEO. The OmniScript automatically adds the c__step
parameter to store the state of a Step.
2. (Optional) Store the state of elements in your OmniScript, prefill elements, or pass data into the
OmniScript's data JSON using Additional SEO URL Parameters.
a. In the Additional SEO URL Parameters field, enter a parameter with the prefix c__. When
storing an element's state or prefilling an element, use the name of the element as your
parameter. For example, the parameter for an element named Text1 is c__Text1.
b. Set the parameter equal to an element in the OmniScript using merge field syntax or a static
value. If there is more than one parameter present, separate the parameters with an & symbol.
See Access OmniScript Data JSON with Merge Fields. For example, to store the state of the Text1
element, set the c__Text1 parameter equal to %Text1%.
3. Activate the OmniScript, and add it to a Community. See Add an OmniScript to a Community or
Lightning Page.
4. Grant guest user access in your Community.
5. Add the OmniScript URL to the Community's sitemap.xml file. See Set Up SEO for Your Community.
6. Use a search engine, such as Google, to test the SEO functionality.
7. (Optional) Test the OmniScript's forward and backward navigation using a browser's forward and back
buttons.
See Also
• Launch an OmniScript with LWC OmniScript Wrapper
• Create Stateful OmniScripts
OmniScripts store the state of an OmniScript in the URL by setting the c__step parameter to the name of
an active Step automatically. Direct users to a specific step in the OmniScript by setting the c__Step
parameter in the URL to a Step name in the OmniScript. Refreshing the page does not cause the
OmniScript to begin at the first step because the Step is stored in the c__step parameter. Include additional
parameters to store the state of elements, insert data into the OmniScript's data JSON, prefill elements, or
conditionally fire OmniScript Actions. Storing the state enables a user to navigate to previous or next steps
using their browser's back and forward buttons.
NOTE
To make a stateful LWC appear in online searches, see Enable SEO for OmniScripts.
1. In the OmniScript's Setup section, check Enable SEO. The OmniScript automatically adds the c__step
parameter to store the state of a Step.
2. (Optional) Store the state of elements in your OmniScript, prefill elements, or pass data into the
OmniScript's data JSON using Additional SEO URL Parameters.
a. In the Additional SEO URL Parameters field, enter a parameter with the prefix c__. When
storing an element's state or prefilling an element, use the name of the element as your
parameter. For example, the parameter for an element named Text1 is c__Text1.
b. Set the parameter equal to an element in the OmniScript using merge field syntax or a static
value. If there is more than one parameter present, separate the parameters with an & symbol.
See Access OmniScript Data JSON with Merge Fields. For example, to store the state of the Text1
element, set the c__Text1 parameter equal to %Text1%.
3. Activate the OmniScript, and add it to a Lightning or Community Page. See Add an OmniScript to a
Community or Lightning Page.
4. (Optional) Test the OmniScript's forward and backward navigation by using a browser's forward and
back buttons.
See Also
• Launch an OmniScript with LWC OmniScript Wrapper
• Save and Resume an OmniScript
NOTE
Error Messages set in the Setup properties apply to any matching error returned by an
element, while Error Messages set in an Action’s properties only render for that Action.
• Path: A merge field path that locates the original default value inside an error object.
• Value: The original error message, including spaces, that will be replaced by the text defined in the Message
field. This value must match the original error exactly.
• Message: The custom message that will replace the error text defined in the Value field.
1. Open the Error Messages property in the element that renders the error.
2. In the Default Error Message field, enter your custom message.
3. Preview the error to ensure the message renders.
See Also
See Also
See Also
Non-Blocking: The Action runs asynchronously, and the response is applied to the UI. Pre
and Post DataRaptor transforms, and large attachments are not supported.
Fire and Forget: The Action runs asynchronously with no callback to the UI. Pre and Post
DataRaptor transforms, and large attachments are not supported. A response will still appear
in the debug console but will not be applied to the Data JSON.
Conditional View All Action elements support conditional view. Conditionally
Display
Elements
Using the
Conditional
View
Property
Pub/Sub Communicate with OmniScript from a custom LWC by sending key-value pairs. Use the Communicate
events passed in the key-value pairs to trigger custom behavior in a component. with
OmniScript
from a
Lightning
Web
Component
Session Storage Send information to a Session Storage object using key-value pairs. A session storage object Message with
clears when a page session ends. Window Post
Messages
and Session
Storage
Messages
Window Post Message Send information from an element to a window object in key-value pairs. Message with
Window Post
Messages
and Session
Storage
Messages
Tracking Business Category Define a business category for a tracking entry. For example, eCommerce. Enable
Tracking for
OmniStudio
Components
Tracking Business Event Define a business tracking event for a tracking entry. For example, Payment Plan. Enable
Tracking for
OmniStudio
Components
Property Description
Enable Action Message Enables an input of custom action messages.
Enable Default Abort Enables the Abort functionality to override the default Go Back functionality. Users will then
only be able to abort the OmniScript if the Action fails.
Property Description
Failure NextLabel Label of the continue button if the Action fails, and the Enable Default Abort checkbox is
checked.
Failure Abort Label Label of the abort button if the Action fails, and the Enable Default Abort checkbox is checked.
Failure Abort Message Confirmation message displayed after user clicks abort button.
Failure Go Back Label Label of the Go Back button if the Action fails. The default behavior enables users to return to
the previous Step unless there are no previous steps, or the Enable Default Abort checkbox
has been checked.
In Progress Message: Message displayed while the Action is being executed. This property is exclusive to Angular
OmniScripts.
Post Message Message displayed upon success.
Redirect Next Label Label of the next button on the redirect page.
Redirect Next Width Width of the next button on the redirect page.
Validation Required Whether to check the validation of the script before the Action is invoked. Default is Submit.
Leave blank to bypass validation.
Redirect Properties
Actions that are placed in Steps and render as buttons contain these common elements.
Property Description
Control Width Controls the width of the button.
Redirect Previous Label The label of the previous button on the redirect page.
Redirect Previous Width The width of the previous button on the redirect page.
Property Description
Send JSON Path This property enables one node of the OmniScript Data JSON to be sent, rather than the
entire JSON. Specify the node name in this property.
Send JSON Node This property allows you to specify the root node name in the outgoing response. For
example, if your OmniScript had a Customer node at the root, you could relabel the node to
CustomerAccount.
Pre-Transform DataRaptor In situations where a more complete transformation of the JSON is required, you can specify a
DataRaptor transform interface. The service will run on the server, and then return the request
body to the client for sending.
Post-Transform DataRaptor Works identically to the Pre-Transform, except the transformation is applied to the response
body before merging into the Data JSON.
Response JSON Path This property allows you to trim the incoming JSON. For example, if the response has a three-
level hierarchy, and you only want one of the nodes, you can specific the path you like to
extract. The syntax is node:node:node (colon-separated).
Response JSON Node This property allows you to reparent the incoming JSON to a node within the OmniScript
JSON. Specific the OmniScript element name which will be the new root node for the
response JSON.
Available in:
• Remote Action
• Integration Procedure Action
Property Description
Default The Action blocks the UI with a loading spinner.
Non-Blocking The Action runs asynchronously, and the response is applied to the UI. Pre and Post DataRaptor transforms, and
large attachments are not supported.
Fire and Forget The Action runs asynchronously with no callback to the UI. Pre and Post DataRaptor transforms, and large
attachments are not supported. A response will still appear in the debug console but will not be applied to the Data
JSON.
Extra Payload
ExtraPayload is an additional property available for the actions listed below. The script configurator can set
up extra payload to be sent while making the call. This property supports merge fields.
• Remote Action
• Integration Procedure Action
• HTTP Action
See Also
Messaging Framework
Communicate between an OmniScript, windows, Lightning web components, and OmniScript elements
using window post messages, session storage messages, and PubSub messaging.
Determine which object or component needs to handle and use data, and use the corresponding property
from this table:
For information on communicating with an LWC from an embedded LWC OmniScript, see Embed an
OmniScript Lightning Web Component in a Lightning Web Component.
See Also
The Pub/Sub property enables Action elements and Step elements to send data in Key-Value pairs to other
LWCs. LWCs must register the OmniScript component's event name and add code to handle the data sent
from the event.
1. In an OmniScript Action or Step, select the Messaging Framework and check Pub/Sub.
2. In the Key and Value fields, configure which data to pass to another LWC.
a. In the Key field, enter a name to store the value.
b. In the Value field, enter data to pass to the LWC. The field accepts merge syntax.
handleOmniAction(data) { handleOmniStepLoadData(data) {
switch(data.name) { switch(data.name) {
case 'SomeNameForAction': case 'FirstStep':
this.handleSomeNameForAction(data);
break; this.handleOmniFirstStepLoadData(data);
case 'SomeNameForAction2': break;
this.handleSomeNameForAction2(data); case 'SecondStep':
break;
default: this.handleOmniSecondStepLoadData(data);
// handle default case break;
} default:
} // handle default case
}
handleSomeNameForAction(data) { }
// perform some logic specific to
SomeNameForAction action handleOmniFirstStepLoadData(data) {
// that has element name = // perform some logic specific when a
"SomeNameForAction" Step element which name is
} // FirstStep is loaded
}
handleSomeNameForAction2(data) {
// perform some logic specific to handleOmniSecondStepLoadData(data) {
SomeNameForAction2 action // perform some logic specific when a
// that has element name = Step element which name is
"SomeNameForAction2" // SecondStep is loaded
} }
Access the Action's Element Type using data.type. n/a
handleOmniAction(data) {
switch(data.type) {
case 'Integration Procedure Action':
this.handleIPActionPubsubEvents(data);
break;
case 'Remote Action':
this.handleRemoteActionPubsubEvents(data);
break;
default:
// handle default case
}
}
handleIPActionPubsubEvents(data) {
// perform some logic specific to
Integration Procedure Actions
}
handleRemoteActionPubsubEvents(data) {
// perform some logic specific to Remote
Actions
}
See Also
Pass element information and data JSON from OmniScript elements containing the window post message,
session storage message, and LWC Pub/Sub message. For information on using the pub/sub message in
OmniScript, see Communicate with OmniScript from a Lightning Web Component.
1. In the element, check the Window Post Message checkbox or the Session Storage Message
checkbox. Once enabled, the default messaging sends the name of the element and the type of the
element.
Default Messaging:
{
Type: <element_type>,
OmniEleName: <element_name>
}
2. (Optional) In the Messages property, add additional messaging to the node by entering a Key/Value
pair. The Value field accepts merge syntax. For information on merge fields, see Access OmniScript
Data JSON with Merge Fields.
3. (Optional) Beginning with Vlocity Insurance and Health and Vlocity CME Summer '20, pass a value in
the c__messagingKey URL parameter to change the node that stores the messaging payload for
window.postMessage and session storage message.
Beginning with Vlocity CME Spring '20, Step elements support the use of window post messages, session
storage messages, and messages. However, the properties do not appear in the properties section of the
element.
NOTE
Beginning with Vlocity Insurance and Health Spring '20, the wpm, ssm, and message
properties appear in the Step element's default properties.
"wpm": false,
"ssm": false,
"message": {}
"wpm": true
4. Add additional key/value pairs inside the message object.
What's Next
Preview the OmniScript and test the messaging behavior by inspecting the browser.
See Also
If the DataRaptor Extract doesn't already exist, you can create it by clicking Create New DataRaptor
immediately after dragging the DataRaptor Extract Action into the OmniScript structure panel
1. Drag the DataRaptor Extract Action into the OmniScript's structure panel.
2. To select the DataRaptor Extract to be called, click in the DataRaptor Interface field and select from
the list. You can type in the field to filter the list.
3. Provide any input parameters the DataRaptor Extract requires. Each Data Source field must match a
DataRaptor Extract input parameter. Each Filter Value must match values in the sObject field to which
the input parameter refers.
4. Use the Response Transformations properties to trim or rename the output JSON. See Manipulate
JSON with the Send/Response Transformations Properties.
See Also
Property Description
DataRaptor Interface Name of the DataRaptor Extract being called.
Data Source Name of a JSON node that provides input for the DataRaptor Extract.
Filter Value Value of the JSON node that provides input for the DataRaptor Extract.
Related Topics
If the DataRaptor Load doesn't already exist, you can create it by clicking Create New DataRaptor
immediately after dragging the DataRaptor Post Action into the OmniScript structure panel.
1. Drag the DataRaptor Post Action into the OmniScript's structure panel.
2. To select the DataRaptor Load to be called, click in the DataRaptor Interface field and select from the
list. You can type in the field to filter the list.
3. Use the Send Transformations properties to trim or rename the input JSON so it has the structure the
DataRaptor Load expects. See Manipulate JSON with the Send/Response Transformations Properties.
See Also
Property Description
DataRaptor Interface Name of the DataRaptor Load being called.
Related Topics
If the DataRaptor Transform doesn't already exist, you can create it by clicking Create New DataRaptor
immediately after dragging the DataRaptor Transform into the OmniScript structure panel.
1. Drag the DataRaptor Transform Action into the OmniScript's structure panel.
2. To select the DataRaptor Transform to be called, click in the DataRaptor Interface field and select
from the list. You can type in the field to filter the list.
3. Use the Send/Response Transformations properties to trim or rename the input JSON so it has the
structure the DataRaptor Transform expects. Or you can trim or rename the output JSON for a
subsequent OmniScript step. See Manipulate JSON with the Send/Response Transformations
Properties.
Related Topics
Property Description
DataRaptor Interface Name of the DataRaptor Transform being called.
Related Topics
If the DataRaptor Turbo Extract doesn't already exist, you can create it by clicking Create New DataRaptor
immediately after dragging the DataRaptor Turbo Action into the OmniScript structure panel.
1. Drag the DataRaptor Turbo Action into the OmniScript's structure panel.
2. To select the DataRaptor Turbo Extract to be called, click in the DataRaptor Interface field and select
from the list. You can type in the field to filter the list.
3. Provide any input parameters the DataRaptor Turbo Extract requires. Each Data Source field must
match a DataRaptor Turbo Extract input parameter. Each Filter Value must match values in the
sObject field to which the input parameter refers.
NOTE
DataRaptor Turbo Extracts return objects in a nested array format.
4. (Optional) In the Response JSON Path field, enter the name of the object returned in the Action's
response. Append a | delimiter and a number to access the correct instance in the nested array. This
enables OmniScripts to prefill elements.
See Also
Property Description
DataRaptor Interface Name of the DataRaptor Turbo Extract being called.
Data Source Name of a JSON node that provides input for the DataRaptor Turbo Extract.
Filter Value Value of the JSON node that provides input for the DataRaptor Turbo Extract.
Related Topics
Delete Action
Enable users to delete one or more sObject records by using the Delete Action. Use an Object's Record Id
to determine which record to delete. Vlocity recommends using a merge field in the Path to Id field that
refers to an Id or a list of Ids in the data JSON.
1. Preview the OmniScript and identify the JSON path for the record. For example, this data JSON
contains a list of Accounts:
For Integration Procedure examples that include a Delete Action, see Process Arrays Using Loop Blocks
and Handle Errors Using Try-Catch Blocks.
• Entity Is Deleted Message: Enter a message that displays when a record is deleted.
• Delete Failed Message: Enter a message that displays when the action fails to delete a record.
• Invalid Id Message: Enter a message that displays when an invalid Id is sent to the Delete Action.
• Configuration Error Message: Enter a message that displays when the Delete Action has a
configuration error.
Property Description
Type Type of sObject record to delete. For example, Account is a Type of sObject.
Path to Id Path to the JSON node that contains the Id or list of Ids of the records to delete. Supports merge
syntax.
All Or None When checked, the operation fails if any of the records are not deleted.
Entity Is Deleted Message Message that displays when a record is deleted.
Delete Failed Message Message that displays when the action fails to delete a record.
Invalid Id Message Message that displays when an invalid Id is sent to the Delete Action.
Configuration Error Message Message that displays when the Delete Action has a configuration error.
Confirm Controls whether the modal displays.
Confirmation Dialog Message The Confirmation Modal's message text. The default message text is Are you sure? This
action cannot be undone.
Confirm Label Button label for the Confirmation Modal's confirm action.
Cancel Label Button label for the Confirmation Modal's cancel action.
Related Topics
Property Description
DocuSign Templates Templates for the documents that you want signed.
Email Subject Subject line for the email requesting signatures.
Email Body Body text for the email requesting signatures.
Date Format Format for display of date values.
Date Time Format Format for display of datetime values.
Time Format Format for display of time values.
Related Topics
Property Description
DocuSign Templates Templates for the documents that you want signed.
Email Subject Subject line for the email requesting signatures.
DocuSign Return Url URL to which the user is redirected after signing completion. Leave blank to display default redirect page.
Date Format Format for display of date values.
Date Time Format Format for display of datetime values.
Signer Email The email of the signer. Supports merge syntax.
Signer Name The name of the signer. Supports merge syntax.
Time Format Format for display of time values.
Related Topics
Email Action
The OmniScript Email Action uses the Salesforce Email API to either send an email template to the email
address of a User, Lead, or Contact or to send an email body defined in the action configuration to any
email address.
The Use Template checkbox determines whether using an email template or a defined email body.
• If the Use Template checkbox is checked, the email will send a template to a user, lead, or contact.
• Select Email Template: The ID of the email template that should be used.
• Email Target Object ID: The object ID of the Contact, Lead, or User the email should be sent to.
• What Id: If you specify a contact for the targetObjectId field, a What Id can be used to further ensure
that merge fields in the template contain the correct data. See the Salesforce Email API documentation
for more information.
• Save as Activity: If this option is checked, the email is saved as an activity record on the recipient’s
page in Salesforce.
• Org Wide Email Address: Allows the email to be sent by an Salesforce organization-wide email
address. For more information on organization-wide email addresses, see Organization-Wide Email
Addresses,
• Content Versions: Accepts the ID of a ContentDocument that is sent as an attachment with the Email
Action.
• If Use Template checkbox is unchecked, an email body defined in the action configuration can be sent to
any email address.
• TO: — An array of email addresses or object IDs of the contacts, leads, or users you’re sending the
email to. The maximum number of toAddresses is 100.
• CC: — An array of carbon copy (CC) addresses or object IDs of the contacts, leads, and users you’re
sending the email to. The maximum number of ccAddresses is 25.
• BCC: — An array of blind carbon copy (BCC) addresses or object IDs of the contacts, leads, and users
you’re sending the email to. The maximum number of bccAddresses is 25.
• Email Subject — The subject of the email.
• Email Body — The body of the email.
• Set HTML Body — Determines if the Email Body should be read as plain text or HTML.
• Attachment List — Supports attachment IDs merged from Data JSON. For example, %DocGenId%. When
the email is sent, the attachment will be added to the email.
Property Description
Use Template If checked, uses a Salesforce email template. Also determines which other properties are available.
To Email Address List Specifies the recipients in the TO field of the email. Can accept an array of up to 100 addresses.
Property Description
Document Attachments Specifies the OmniScript JSON node that contains a single or list of Salesforce Document sObject Ids.
from OmniScript
Content Versions Specifies the Id of a ContentVersion sObject that is included as an attachment.
Select Document Specifies the Attachment sObjects to add to the email.
Attachments
Attachment List Specifies a node in the data JSON that contains a list of attachment Ids.
HTTP Action
Call internal and external web services from OmniScript without coding or making Salesforce API calls
using the HTTP Action.
NOTE
You must add the Salesforce org's domain into a Remote Site's Remote Site URL field.
For more information, see Adding Remote Site Settings.
Settings:
• HTTP Path: The request URL of the API. For example, /NS/v1/application. NS = namespace of the
Apex REST API. The path can contain merge fields. For example, to pass a UserId node from the data
JSON, add the node name with percentage signs on either side, i.e., %UserId%.
NOTE
Beginning with Vlocity Summer '19, you can pass percentage signs in the URL by
replacing the percentage sign in the URL with the variable $Vlocity.Percent.
• HTTP Method: The method name, which has two parameters. For example, doPost(String fullJSON,
String filesMap).
• Option Source: The type of HTTP Action.
• Use Named Credentials (OAuth via Salesforce).
Property Description
HTTP Path URL to call. For Apex REST actions, you can use merge fields to set this property.
Beginning with Vlocity Spring '19, you can pass percentage signs in the URL by replacing the percentage sign
in the Path with the variable $Vlocity.Percent.
HTTP Method GET, POST, PUT, or DELETE.
Endpoint Type Specifies the endpoint type:
• Apex — Invokes Apex REST. You must add the Salesforce org's domain to a Remote Site's Remote Site
URL field.
• Named Credential — Access Salesforce Named Credential (OAuth) identity services.
• SOAP/XML — Send requests to standard REST endpoints using XML format for the request and response
bodies.
• Web — Send requests to standard REST endpoints (unauthenticated or credentials in HTTP headers).
Named Credential Salesforce named credential. For Named Credential and optionally SOAP/XML endpoint types.
HTTP Headers HTTP headers specified as Key/Value pairs. Supports merge field syntax.
Parameters URL parameters specified as Key/Value pairs. Supports merge field syntax.
Encode URI Uses HTML escape codes in the URI.
Cache Caches the response.
With Credentials Requires security credentials such as a username and password.
Extra Payload Sends additional Key/Value pairs. Supports merge field syntax.
Send Body Sends the Extra Payload as the request body for a POST action.
Send Only Extra Enables the action to send Extra Payload's Key/Value pairs without including the OmniScript's data JSON.
Payload
Related Topics
• Adding Remote Site Settings in Apex Developer Guide
1. Drag the Integration Procedure Action into the OmniScript's structure panel.
2. To select the Integration Procedure to be called, click in the Integration Procedure field, and select
from the list. You can type in the field to filter the list.
3. Use the Response Transformations properties to specify the input and to trim or rename the output
JSON.
• Send JSON Path — Specifies the JSON node that contains the input for the Integration Procedure.
This is typically the name of a previous element in the OmniScript.
• Send JSON Node — Renames the JSON node that contains the input for the Integration Procedure.
This is typically the name of one of the Integration Procedure's input parameters.
• Response JSON Path — Specifies the JSON node that contains the output to return to the
OmniScript. By default, all Integration Procedure data is returned.
• Response JSON Node — Renames the JSON node that contains the output to return to the
OmniScript. This is typically the name of a subsequent element in the OmniScript.
See Manipulate JSON with the Send/Response Transformations Properties.
4. (Optional) Use the Extra Payload property to send additional key/value pairs to the Integration
Procedure as input data.
5. Specify any additional Integration Procedure Action properties you need.
6. (Optional) Enable the Integration Procedure's Queueable Chainable settings by taking these steps:
1. Click the Is Queueable Chainable? checkbox to enable the settings.
2. In Remote Options, add this Key-Value pair:
Key Value
useQueueableApexRemoting true
7. (Optional) When Invoke Mode is set to non-blocking, elements using default values will not receive the
response because the element loads before the response returns. You must configure these properties
to map the response to an element:
Property Value
Response JSON Node VlocityNoRootNode
Response JSON Path The name of the OmniScript Element receiving the value.
See Also
Property Description
Integration Specifies the Integration Procedure to be run in the format Type_Subtype.
Procedure
Remote Options Specifies additional properties for the Integration Procedure as key/value pairs.
Property Description
Send Only Extra Enables the action to send Extra Payload's Key/Value pairs without including the OmniScript's data JSON.
Payload
Use Future Specifies that the Integration Procedure runs asynchronously, as a Salesforce future method, which can
return no data to the calling OmniScript.
Is Chainable Enables the Chainable settings of the subordinate Integration Procedure.
Use Continuation Enables a subordinate Integration Procedure that calls long-running actions to use Apex continuations.
Use Queueable Enables chainable steps in the subordinate Integration Procedure to start queueable jobs.
Is Queueable Enables the Queueable Chainable settings of the Integration Procedure.
Chainable
Invoke Mode Configures the response behavior of the action:
See Also
Navigate Action
Navigate to various Salesforce experiences from OmniScript using the Navigate Action element. For more
information on Salesforce experiences, see PageReference Types.
1. Drag the Navigate Action into the OmniScript's structure panel. If the Navigate Action renders in a
Step, it becomes a clickable button. If the Navigate Action is between steps, it will fire automatically.
2. (Optional) If the Navigate Action renders in a Step, determine the style of the button by clicking the
Button Variant dropdown and selecting an SLDS Button variant. In addition to the SLDS Button
variants, you can select Link to render the Navigate Action as an HTML anchor tag.
3. (Optional) If the Navigate Action renders in a Step, display an SLDS Icon in the button by entering the
Icon name into the Icon Name field. For example, to add the standard_account Icon, enter
Standard:Account.
4. (Optional) Replace the existing entry in the browser history by setting the Replace? property to Yes. If
Replace? is set to Yes, users cannot navigate back to the OmniScript.
NOTE
By default, a Navigate Action in a Console App opens the PageReference type in a
new subtab. Replace the current tab in a Console App by setting Replace? to Yes.
5. (Optional) Enable the LWC OmniScript to send messages to separate Lightning web components by
checking LWC PubSub Message? and adding a Message key-value pair. For more information, see
Communicate with OmniScript from a Lightning Web Component.
6. (Optional) Fire events from the Navigate Action by passing an event to the OmniScript in the URL
parameter c__vlocEvents. The Navigate Action element must have the checkbox property LWC
PubSub Message? enabled to fire the event. For more information on passing parameters into an
OmniScript, see Launch an OmniScript with LWC OmniScript Wrapper.
7. Determine the Salesforce experience that the Navigate Action will direct to by clicking and selecting a
PageReference type. This page contains further instructions for each PageReference Type that
Navigate Action supports. For information on PageReference Types, see PageReference Types.
See Also
Navigate to an App
Direct users from an OmniScript to a standard App, custom App, or a page within an App using Navigate
Action's App PageReference Type.
Property Description
appId The AppDefinition object's DurableId.
appDeveloperName The concatenation of the app’s namespace and developer name. The app's namespace is standard,
custom, or a managed package namespace. The Developer name is viewable in the App Manager. For
more information on appDeveloperName, see PageReference Type
Syntax Examples:
• Standard: standard__Account
• Custom: c__CustomAccountApp
• Managed: vloc_ps_OmniScriptDesigner
3. (Optional) In the Target Page field, enter JSON to specify the app page and additional attributes. The
Target Page field represents the App's pageRef property.
See Also
See Also
Navigate to a Component
Navigate to Aura components and Lightning web components from an OmniScript by using the Component
PageReference Type.
NOTE
The Aura component must implement the lightning:isUrlAddressable interface. For
more information, see Is Url Addressable.
3. (Optional) Pass parameters by using a URL query string format in the Target Params property.
Parameters must have a c__ prefix. This field supports Merge fields.
4. (Optional) When navigating to a component in a console app, add a Console Tab Icon and a Console
Tab Label by setting the c__tabIcon and c__tabLabel parameters. The c__tabIcon accepts and SLDS
Icon and c__tabLabel accepts plain text. For example, &c__tabLabel=Custom
Label&c__tabIcon=standard:account renders the console tab shown in this example image.
See Also
See Also
NOTE
Communities ignore articleType.
See Also
Navigate to an OmniScript
Navigate to an OmniScript by using the Vlocity OmniScript PageReference Type. OmniScripts on
Community Pages must be accessed using the Community Named Page PageReference Type. See
Navigate to a Named Page or Community Named Page.
1. Enter the name of the OmniScript with a prefix of c: into the LWC OmniScript field. The name of the
OmniScript is defined by the OmniScript's Type, SubType, and Language, using the syntax
typeSubTypeLanguage. For example, an OmniScript with the properties Type=myType,
SubType=Example, and Language=English appears as a component using the syntax
myTypeExampleEnglish.
2. Select the layout the OmniScript uses to render by clicking the OmniScript Layout property.
3. (Optional) Prefill the target OmniScript by passing parameters using a URL query string format in the
OmniScript Prefill property. Parameters must have a c__ prefix. This field supports Merge fields.
4. (Optional) When navigating to an OmniScript in a console app, add a Console Tab Icon and a Console
Tab Label by setting the c__tabIcon and c__tabLabel parameters. The c__tabIcon accepts an SLDS
Icon , and c__tabLabel accepts plain text. For example, &c__tabLabel=Custom
Label&c__tabIcon=standard:account renders the console tab shown in this example image.
See Also
1. Set the PageReference type property to Named Page , or if the page exists in a Community, select
Community Named Page.
2. In the Page Name field, enter the API for the page name. API Names for custom pages must include
__c in the API Name. This field supports Merge fields.
3. Activate and preview the OmniScript to test the behavior of the navigation.
See Also
• Navigate Action
1. Set the PageReference type property to Navigation Item. This field supports Merge fields.
2. Find the Custom Tab's Tab Name and Namespace prefix, and enter it into the Tab Name field using the
format NS__TabName, where NS is the namespace of the Tab. For more information on Tabs, see
Create Lightning Page Tabs. This field supports Merge fields.
See Also
NOTE
The New action opens a modal dialogue.
4. (Optional) Enter the Id of the Object page into the Filter Name field. Filter Name defaults to
Recent. This field supports Merge fields.
See Also
NOTE
Clone and Edit actions open a modal dialogue.
4. (Optional) Enter the API name of the object into the Object API Name field. Custom objects from a
managed package require a namespace prefix using the syntax NS__APIName, where NS is the
namespace prefix of the object. This field supports Merge fields.
See Also
See Also
See Also
Restart an OmniScript
Navigate a user to a new instance of the same OmniScript using the Navigate Action.
See Also
Property Description
Button Variant If the Navigate Action renders in a Step, determines the style of the button:
Property Description
Page Reference Select the PageReference sObject type:
Type
• App — Navigates to an App page.
• Component — Navigates to a Lightning Web Component.
• Community Named Page — Navigates to a Community Named Page.
• Current Page — Performs an action on the current page.
• Knowledge Article — Navigates to a knowledge article.
• Login — Navigates to a Login or Logout.
• Named Page — Navigates to the page with the specified name.
• Navigation Item — Navigates to a Custom Tab. Visualforce tabs, web tabs, Lightning Pages, and Lightning
Component tabs are supported.
• Object — Navigates to an sObject page.
• Record — Navigates to an sObject record page.
• Record Relationship — Navigates to a list of records related to the specified record.
• Web Page — Navigates to an external web page.
• Vlocity OmniScript — Navigates to a Vlocity OmniScript.
Replace Existing Specifies that the page to which this action navigates replaces the current page in the browser history. If this is
Page in Browser checked, users cannot navigate back to the OmniScript.
History
Component Name Name of the Lightning Web Component.
Target Parameters Additional parameters for the page.
Article URL URL of the Knowledge Article.
Article Type Type of the Knowledge Article.
Page Name Name of the Named Page.
Tab Name Name of the Custom Tab.
Object API Name Name of the sObject. For custom objects, include the namespace, for example
vlocity_ins__PartyRelationship__c.
Object Action Page for the action to perform on the sObject:
Property Description
Pub/Sub Enables the OmniScript to send messages to separate Lightning web components. After checking this, specify
a Message key-value pair.
Related Topics
• Navigate Action
• Buttons in Salesforce Lightning Design System
• Icons in Salesforce Lightning Design System
Remote Action
Call Apex classes from OmniScript using the Remote Action element.
1. Add a Remote Action before a Step, in a Step, or after a Step to load data or send data in the
OmniScript. The OmniScript's data JSON is sent as the input.
2. In the Remote Class field, enter the name of the Apex class that the action calls.
NOTE
The Apex Class must implement NS.VlocityOpenInterface. NS = the namespace of the
Apex class. For information on namespace, see Viewing the Namespace and Version
of the OmniStudio Vlocity Package.
3. In the Remote Method field, enter a method of the class that the Action calls. For example—
validateAddress.
4. (Optional) In the Pre- and Post-Transform DataRaptor Interface—optionally select a DataRaptor
Transform interface to run before or after the Remote Action. See DataRaptor Transform Overview.
5. (Optional) Change the amount of time before the Action times out using the Remote Timeout property.
In the element, click Edit Properties as JSON, and in the remoteTimeout property, set a time in
milliseconds. The default timeout is 30,000, or 30 seconds. The maximum is 120,000, or 120
seconds.
6. (Optional) Configure additional properties in the Remote Action. See Remote Action Properties.
7. (Optional) When Invoke Mode is set to non-blocking, elements using default values will not receive the
response because the element loads before the response returns. You must configure these properties
to map the response to an element:
• Response JSON Node: VlocityNoRootNode
• Response JSON Path: The name of the OmniScript Element receiving the value.
Example
NOTE
This example references the Troubleshooting OmniScript and the OmniCallout and
DataObjectService Apex classes.
In the Troubleshooting OmniScript, the callOut1 Remote Action element calls an external system to check if
the asset is still under warranty.
The callOut2 Remote Action calls the returnItemOrder method, which in turn calls the
DataObjectService class that calls out to a Heroku instance to return an order number:
global CustomClassName() {}
try{
if(methodName.equals('customMethodName')){
else if(methodName.equals('customMethodName2')){
} catch(Exception e){
result = false;
return result;
See Also
Properties Description
Remote Class Vlocity Open Interface class.
Remote Method Vlocity Open Interface method.
Remote Options Additional class invocation options.
Extra Payload Sends additional Key/Value pairs. Supports merge field syntax.
Invoke Mode Configures the response behavior of the action:
Property Description
Element Name The OmniScript element for which an error is to be set.
Value The error message. Options:
Related Topics
Property Description
Element Name The JSON node for which a value is to be set.
Value The value to assign to the JSON node. Options:
Related Topics
Newport Aggregate:
Newport Formula:
Messaging The Messaging element Display To view the different Message types, see
displays comments, Messaging in Displaying Messaging in OmniScripts.
requirements, success, and OmniScripts
warning messaging
depending on whether the
validate expression is true or
false.
Newport Block:
Edit Block The Edit Block element groups Use OmniScript See Configuring an Edit Block.
together inputs to allow users Edit Block
to add, edit, and delete records.
Radio The Radio Group element Setting up a Lightning Radio Group:
Group allows users to quickly answer questionnaire
a large volume of multiple with Radio Group
choice questions in one step.
Newport Step:
Type The Type Ahead Block displays Configure Type Lightning Type Ahead:
Ahead as a text input field; the field Ahead Blocks
Block auto completes results based
on the user's input.
Action Block
Beginning with Vlocity Insurance and Health Spring '20, run multiple OmniScript Actions asynchronously by
grouping them in an Action Block.
Actions within the Action Block run in parallel and inherit the Action Block's settings.
1. Drag the Action Block from the element palette into the designer. Place the Action Block inside of a
Step, before the first Step, or between Steps.
2. Drag up to four Actions into the Action Block.
3. Select an Invoke Mode to control how actions inside the Action Block run.
Property Description
Default The Action blocks the UI with a loading spinner.
Non-Blocking The Action runs asynchronously, and the response applies to the UI. Pre and Post DataRaptor transforms,
and large attachments are not supported.
Fire and Forget The Action runs asynchronously with no callback to the UI. Pre and Post DataRaptor transforms, and large
attachments are not supported. A response still appears in the debug console but does not apply to the Data
JSON.
4. (Optional) When Invoke Mode is set to non-blocking, elements using default values will not receive the
response because the element loads before the response returns. You must configure these properties
to map the response to an element:
• Response JSON Node: VlocityNoRootNode
• Response JSON Path: The name of the OmniScript Element receiving the value.
5. (Optional) Check Apply if error to enable actions that run successfully to apply their responses to the
OmniScript's data JSON even when other actions in the Action Block fail. When Apply if error is
unchecked, successful actions do not apply their responses to the data JSON when another action in
the block fails.
6. (Optional) When the Action Block is inside of a Step, set Validation Required to Step to prevent the
Action Block from running when errors exist in the Step.
7. Preview the OmniScript to test the Action Block behavior.
NOTE
In Vlocity Insurance and Health Spring '20, Action Block's Conditional View property is
not available in the LWC Designer. To edit the Conditional View property, temporarily
switch to the Classic Designer and configure the Conditional View properties. Once the
conditional view is configured, save the OmniScript and switch back to the LWC
OmniScript Designer.
See Also
Property Description
Apply If Error Enables actions that run successfully to apply their responses to the OmniScript's data JSON even when other
actions in the Action Block fail.
Property Description
Default An Invoke Mode option, Default blocks the UI with a loading spinner until the Action finishes executing.
Non-Blocking An Invoke Mode option, Non-Blocking runs the action asynchronously, and the response is applied to the UI. Pre
and Post DataRaptor transforms, and large attachments are not supported. When Invoke Mode is set to non-
blocking, elements using default values will not receive the response because the element loads before the
response returns. To map the response to an element, you must set Response JSON Node to VlocityNoRootNode
and Response JSON Path to the name of the element.
Fire and Forget An Invoke Mode option, Fire and Forget runs the action asynchronously with no callback to the UI. Pre and Post
DataRaptor transforms, and large attachments are not supported. A response appears in the debug console but is
not applied to the Data JSON.
Validation When set to Step, Validation Required prevents the Action Block from running when errors exist in the Step.
Required
See Also
• Action Block
• Common OmniScript Element Properties Definitions
Block
Combine logical groups of elements in an OmniScript Step using a Block element.
Blocks help to group information to create nested JSON data. Blocks are contained within Steps and may
repeat to capture an array of data. For example, street, city, state, and postal code elements may be
combined into an address block.
NOTE
Blocks do not support the Custom LWC Element. See Custom LWC Element.
1. Drag a Block element into the OmniScript canvas and name the element.
2. In Field Label, enter a label that displays to users.
4. (Optional) In Repeat Settings, check Enable Repeat to enable users to add multiple block entries.
Repeatable blocks store data in an array format, where each block entry is indexed in an array under
the Block's element name. If you plan to access data from an element in a repeatable Block, see
Evaluating Elements in Repeatable Blocks. For information on prefilling blocks, see Prefill Repeatable
Blocks.
5. (Optional) Check Clone When Repeating to clone values when a Block is repeated.
6. (Optional) In the Limit Repeat field, enter a number to set the number of times a Block can be
repeated.
7. Preview the OmniScript and test the functionality.
8. Note the data JSON output format based on your configuration to map data JSON from Blocks.
No Block JSON Example Block JSON Example Repeatable Block JSON Example
See Also
• Edit Block
• Type Ahead Block
Edit Block
Beginning with Vlocity Insurance and Health Winter '20 and Vlocity CME Winter '20, LWC OmniScript
supports Edit Blocks.
Create, edit, and delete multiple Salesforce or external records on one page using Edit Block.
For example, if you are collecting an Account's Contact information, you can add an Edit Block to your
OmniScript to enable users to add a record for each Contact.
NOTE
In the Summer '17 version, the first three fields of the Edit Block display by default. In
Winter '18, the display fields must be chosen by the user when configuring the Edit Block
in the OmniScript Designer. When you disable an active OmniScript with an Edit Block
created before Winter '18, you must determine which fields you want to display on the Edit
Block before reactivating the OmniScript.
What's Next
Select an Edit Mode and configure the Edit Block to display elements. See Configuring an Edit Block.
See Also
• Adding, Editing, and Deleting Records with Edit Block Actions
• Overriding an LWC Edit Block
• Working with Formulas in Edit Block
• Setting a Select Mode in Edit Block
• Displaying Sprites in Edit Block
• Edit Block Properties
NOTE
Edit Blocks do not support the Custom LWC element. For more information, see Custom
LWC Element.
Edit Blocks enable a user to add and edit multiple entries in a single array. For example, you can use an
Edit Block to list and edit an Account's list of Contacts. Edit Blocks are repeatable blocks by default.
Prefilling repeatable blocks with data is possible using an array format. For more information, see Prefill
Repeatable Blocks.
• To display an element in the Edit Block's default view, check the checkbox next to the element in the
structure panel. This element also appears when editing an entry.
• To only display elements when a user edits an entry, leave the checkbox next to the element in the
structure panel unchecked.
Example Edit View:
• To hide an element in the Edit Block, in the element, click Edit as JSON, and set Hide equal to true.
For more information, see Hide OmniScript Elements.
• To only display an element in the Edit Block's default view:
LWC Modes
Select a Mode in the Edit Block's Edit Block Mode field to change the display and functionality of the Edit
Block.
Table n/a
NOTE
Available beginning in
Vlocity Insurance and
Health Spring '20
Angular Templates
Add a template to the EditBlock's HTML Template Id field to modify the display and functionality of the Edit
Block.
Cards - vlcEditBlockCards.html
Financial Statement -
vlcEditBlockFS.html
Inline - vlcEditBlockInline.html
Long cards -
vlcEditBlockLongCards.html
Compatible Elements
The following elements are compatible with Edit Block:
• Aggregate
• Checkbox
• Currency
• Date
• Date/Time
• Disclosure
• Email
• File
• Formula
• Headline
• HTTP Action
• Image
• Integration Procedure Action
• Line Break
• Lookup
• Matrix Action
• Multi-select
• Number
• Password
• Radio
• Radio Group
• Range
• Remote Action
• Select
• Signature
• Telephone
• Text
• Text Area
• Text Block
• Type Ahead Block
• Time
• URL
What's Next
Add actions to an Edit Block or use SObject mapping to create, edit, and delete records. See Adding,
Editing, and Deleting Records with Edit Block Actions.
See Also
• HTTP Action
Creating, Editing, and Deleting Records with Default Actions and sObject Mapping
Add sObject Mapping functionality by adding Remote Actions to the Edit Block for each option you want to
make available to the User. These Remote actions will access Apex classes built for the Edit Block and the
sObject Mapping tool. The Default Actions use the sObject mapping property to determine how the entries
map to an sObject.
NOTE
In the LWC OmniScript Designer, the SObject Mapping section does not work. To edit the
SObject mapping, use the classic designer. Once the edits are complete, switch back to
the LWC OmniScript Designer to test the mapping.
Map the Edit Block entries to Salesforce objects by using the SOBJECT MAPPING property. Fields hidden
from the user, such as an Id, remain available for mapping.
NOTE
By default, new entries are added, and existing entries are updated. To create a new
record instead of updating an existing one, check the Duplicate Key checkbox.
5. In the sObject field, select an sObject field. The element will map to this field.
NOTE
You must add a Text Element to store the Id of the record in the Edit Block. The
element containing the record Id must map to the sObject's Id field in the SOBJECT
MAPPING section. To hide the element from displaying in the UI, see Using the Hide
Property on OmniScript Components.
See Also
1. Search for an SLDS icon, and note the category and the icon name.
2. In the Default SVG Sprite field, enter the icon's category.
3. In the Default SVG Icon field, enter the name of the icon.
4. Preview the OmniScript to view the new default SVG icon.
1. In the Edit Block's SVG Controlling Element, enter the name of an Element in the Edit Block.
2. In the Svg Controlling Element Map, click Add SVG Icon.
3. In the SVG Icon's Value field, enter a possible value for the SVG Controlling Element.
4. Search for an SLDS icon, and note the category and the icon name.
5. In the Svg Sprite field, enter the icon's category.
6. In the Svg Icon field, enter the name of the icon.
7. Preview the OmniScript and enter the value for the SVG Controlling Element to test the functionality.
8. (Optional) Repeat the steps for additional element values.
See Also
NOTE
Select Mode is only available for Cards, LongCards, and Table.
1. Add a Checkbox element into the Edit Block and name the element. For example, Element Name =
PaidInFull.
2. (Optional) Hide the element from the Edit Block by clicking Edit as JSON, and setting Hide equal to
true.
3. In the Edit Block, set Select Mode equal to Single or Multi.
4. Enter the Checkbox element name in the Checkbox Element Name field.
5. Preview the OmniScript, create Edit Block entries, and select the entries.
6. Click { Data } to open the data panel and view the boolean values for the Edit Block entry.
See Also
See Also
Edit Blocks contain up to three LWC override fields based on the Edit Block's Edit mode. For information on
Edit Modes, see Configuring an Edit Block.
See Also
The Edit Block LWC overrides the entire Edit Block LWC unless the Edit Mode is Cards or Long Cards.
Cards and Long Cards include additional extendable LWCs. For information on Cards and Long Cards
LWC options, see Overriding an LWC Edit Block.
1. In VisualStudio, create a custom LWC or download a custom Edit Block LWC example by clicking here.
The code in the custom LWC example changes the background of the Edit Block card to green.
2. In the LWC's JavaScript file, extend the Edit Block LWC. Using this code example, replace the NS with
the namespace of the package. For information on finding the namespace, see Viewing the
Namespace and Version of the OmniStudio Vlocity Package.
Example:
render()
{
if (this.jsonDef) {
this._hasChildren = this.jsonDef.children.length > 0;
this._isFirstIndex = this.jsonDef.index === 0;
See Also
Exclusive to Cards and Long Cards edit mode, the Edit Block Label LWC overrides the original labels,
including global actions. For information on additional Long Cards LWC options, see Overriding an LWC
Edit Block.
1. In VisualStudio, create a custom LWC or download a custom Edit Block LWC example by clicking here.
The code in the custom LWC example changes the label of a global action to green.
2. In the LWC's JavaScript file, extend the Edit Block Label LWC. Using this code example, replace the
NS with the namespace of the package. For information on finding the namespace, see Viewing the
Namespace and Version of the OmniStudio Vlocity Package.
Example:
render()
{
return template;
}
}
See Also
Exclusive to the Card Edit Mode, the Edit Block New LWC overrides the new entry card. For information on
additional Cards LWC options, see Overriding an LWC Edit Block.
1. In VisualStudio, create a custom LWC or download a custom Edit Block New LWC example by clicking
here. The code in the custom LWC example changes the text color to green.
Original Edit Block New Card Custom Edit Block New Example
2. In the LWC's JavaScript file, extend the Edit Block New LWC. Using this code example, replace the NS
with the namespace of the package. For information on finding the namespace, see Viewing the
Namespace and Version of the OmniStudio Vlocity Package.
Example:
See Also
Property Description
Allow Delete Enables users to access an Action that deletes an entry.
Allow Edit Enables users to access an Action that edits an entry.
Allow New Enables users to access an Action that creates a new entry in the Edit Block.
Delete Label The text label that appears for the Delete Action.
Edit Block Mode Exclusive to LWC OmniScripts; sets the styling for Edit Block entries.
Edit Label The text label that appears for the Edit Action.
New Label The text label that appears for the New Action.
Default SVG Sprite The name of the Default SVG Sprite category. By default, this field is set to the utility category.
Default SVG Icon The name of the Default SVG Icon that is within the Default SVG Sprite's category. By default, this field is
set to the user icon.
SVG Controlling Element The name of an element in the Edit Block that's value dynamically controls whether an alternate SVG Icon
displays.
Sum Element The Sum Element displays the value for a Formula placed outside of the Edit Block.
Property Description
Select Mode Exclusive to LWC OmniScript, Select Mode enables users to set a Checkbox's boolean value to true by
selecting Edit Block entries. Select Mode is only available for Cards, LongCards, and Table Edit Blocks.
Checkbox Element Enter the name of a Checkbox element in the Edit Block. This element enables Select Mode to function.
Name
sObject Mapping Enables users to use Vlocity's default actions to map Edit Block entries to Salesforce records.
For information on common properties, see Common OmniScript Element Properties Definitions.
See Also
NOTE
Radio Group provides the same options for each question. To provide different options for
each question, see Add Options for Selects, Multi-Selects, and Radio Buttons.
NOTE
Using a value from a Radio Group as a conditional in another element requires adding
the Radio Group's element name as the parent node. The image below displays an
example of how to reference a Radio Group value in a conditional:
3. (Optional) Select the Set All button next to an option to check all of the fields at once when the option
is selected.
4. Under Radio Group Questions, add questions into the Label field and enter Values to store the
user's response. The Labels represent the questions that display to the left of the selectable options.
5. (Optional) Set the Radio Labels Width. Changing the Width of Radio Group Labels changes the width
of the Options Labels.
6. Preview the OmniScript to test the questionnaire.
Steps
When Creating the Script Structure for an OmniScript, Steps should be used to create each "page" of the
form. Users can navigate through Steps using Next and Previous buttons. You can enable field validation
for a Step, which means that all required fields on the Step must be completed in order to move forward.
Conditionally Display Elements Using the Conditional View Property can be done by applying conditional
views to steps. This enables you to create one OmniScript that offers different experiences based on the
user's responses.
Step Example
In the example OmniScript pictured below, the first Step is called Agent Information:
The Instruction field on the Step element configuration appears in Horizontal mode and is HTML-rich:
The OmniScript's Step Chart can be hidden by checking Hide Step Chart in the Script Configuration:
The Step Chart Label property enables you to text that is separate from the Step's main display label:
In the OmniScript Designer, the Type Ahead Block is located under the Groups section of Available
Components.
See Also
NOTE
If a Type Ahead Block exists in a Block element, only one Block element is permitted.
Adding multiple nested Blocks will result in errors.
2. Add an Action element into the Type Ahead Block to retrieve data or seed the Type Ahead Block with
data. Type Ahead Blocks only support using a single action.
See Also
• Make an HTTP Call from a Type Ahead Block
• Using Google Maps Autocomplete in OmniScripts
• Using Type Ahead Block With Data JSON
• Use Type Ahead Block with DataRaptor
• Type Ahead Block
• Type Ahead Block Properties
By default, user input will be filtered against a LIKE match. To return unfiltered results check the Disable
Data Filter checkbox in the Type Ahead Block's properties.
See Also
For example, you might want to use a Data JSON with an array containing a list of your coverage plan
names. As your agent begins typing, a list of plan names is displayed, enabling the agent to choose one.
To use a Data JSON as the source for your Type Ahead Block:
NOTE
The Data JSON Path only accepts data at the root level of the JSON.
By default, user input is filtered using a LIKE match. To return unfiltered results, check Disable Data Filter
in the Type Ahead Block's properties.
To make the Type Ahead Block behave like the Lookup element, check the Lookup Mode checkbox.
Instead of typing to return a set of values, users select from a set of values.
See Also
3. Check the Enable Google Maps Autocomplete checkbox to display the Google Maps
Autocomplete section.
4. In the Google Maps API Key field, enter your Google Maps JavaScript API key. If you don't have a
Google Maps JavaScript API Key, obtain one from Google.
5. (Optional) To hide the Google Map widget, check Hide Map.
6. Click the Country Filter field and select a Country.
7. Preview the OmniScript to run a search and return a Google response.
8. Open the Action Debugger to view the response.
Refer to the Action debugger's response, and map these additional nested data types by entering the
correct notation in the Google Response Node field:
12. Save the OmniScript and run it in preview to view your mappings.
See Also
See Also
Property Description
Type Ahead Key Where to apply the data returned by the action. To invoke JavaScript for parsing, set Data Process
Function.
Edit Mode Check to display the fields in the Type Ahead Block automatically. If Edit Mode is not checked, users can
click the edit button to display fields. Displaying the field enables users to enter information into the fields
without using type-ahead.
Google Map Api Key Enter a Google Maps API Key.
New Item Label Permits users to add a new entry when using the Type Ahead Block. By default, users can only choose
from the list of values.
Hide Edit Button Prevents the Edit button from displaying. If Edit Mode is checked, the Type Ahead Block fields still display
to the user.
Hide Map Hides the Google Maps widget in the OmniScript.
Google Response The name of the google response node. Preview the OmniScript to run the Google search and view all the
Node available response nodes in the action debugger.
See Also
Newport Checkbox:
Newport Currency:
Newport Date:
Date/Time The Date element is used for input fields that should Lightning Date/Time:
contain a date and time. Displays two fields. The
timezone property provides the option of setting the
timezone to either the User object's time or the browser's
local time.
Newport Date/Time:
Disclosure Displays Disclosure text and has a checkbox for user to Lightning Disclosure:
select whether or not they agree with the disclosure.
Newport Disclosure:
Email The Email element is used for input fields that should Lightning Email:
contain an e-mail address.
Newport Email:
File The File element allows the user to upload a file from Lightning File:
their computer so that it is accessible by OmniScript.
Newport File:
Newport Image:
Lookup The Lookup element calls the DataRaptor Output service Lightning Lookup:
to query SFDC tables and populate the element with the
results of the query. s
Newport Lookup:
Newport Multi-select:
Newport Number:
Newport Password:
Radio Radio buttons let a user select one of a limited number of Lightning Radio Display Mode Options:
options. Options are displayed in a vertical list.
Horizontal:
Image:
Vertical:
Horizontal:
Image:
Segment:
Vertical:
Range The Range element is used for input fields that should Lightning Range:
contain a value within a range.
Newport Range:
Newport Select:
Newport Signature:
Telephone The Telephone element is used for input fields that Lightning Telephone:
should contain a telephone number.
Newport Telephone:
Text The Text element is a one-line text input field. Lightning Text:
Newport Text:
Text Area The Text Area element is a multiple-line text input field. Lightning TextArea:
Newport TextArea:
Time The Time element allows users to input a time into the Lightning Time:
field.
Newport Time:
URL The URL element is used for input fields that should Lightning URL:
contain a URL address.
Newport URL:
1. Drag a Checkbox element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) Select Default Value to enable the checkbox by default. The value is true or false in the
Data JSON.
5. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag a Currency element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) To override the default allowable format, select Custom Mask, and then enter a new mask
in the Format Override: Custom Mask field. For example, the mask ###,### transforms an input of
123456 into 123,456. See Pattern Mask.
5. (Optional) In Format Override: Decimal Places, enter a number to change the default number of
decimal places to display.
6. (Optional) In Minimum Currency Value, enter the minimum value that a user can enter, such as 1.
7. (Optional) In Maximum Currency Value, enter the maximum value that a user can enter, such as
10,000.
8. (Optional) Select Allow Negative Numbers to allow users to enter negative values, such as -15.
9. (Optional) Select Hide Comma Separators to hide commas for values greater than three digits. For
example, display 1000 instead of 1,000.
10. (Optional) Select Display Currency Code to display a currency code based on the logged-in user's
locale. For example, if the user locale is en-US, the currency code is USD.
11. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
Property Description
LWC Name Enter the name of the custom component to render it in an active OmniScript.
Property Name Enter a property name using the HTML attribute format to pass it into the custom component. For example, the
property recordId converts to the HTML attribute record-id.
Property Source Enter a value to pass in the property. Values may use merge field syntax to pass a JSON node. For example, to
pass the JSON node ContextId, enter %ContextId%.
Standalone LWC A checkbox that enables the use of a Standalone LWC.
See Also
• Custom LWC Element
• Common OmniScript Element Properties Definitions
1. Drag a Date element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. In Minimum Date, enter the earliest date the user can select from the date picker, such as
01-01-1950.
NOTE
The format entered must be the same as in the Date Format field. For example, to set
the minimum date to January 1, 1950, if the Date Format is MM-DD-YYYY, you must
enter 01-01-1950.
5. In Maximum Date, enter the latest date the user can select from the date picker, such as
12-31-2019.
NOTE
The format entered must be the same as in the Date Format field. For example, to set
the maximum date to December 31, 2019, if the Date Format is MM-DD-YYYY, you
must enter 12-31-2019.
6. In Date Format, enter the format to display the date. For example, if the format is MM-DD-YYYY, and
the user selects January 3, 2020 from the date picker, the date displays as 01-03-2020. For
more format options, see Day.js.
7. (Optional) In the Advanced Options section, update values for the following properties:
• Data Type: Specifies how to display the date in the Data JSON.
• If set to String, the Model Date Format is applied. String is the default data type.
• If set to Date, the date is encoded as an ISO 8601 date/time, such as
2018-01-28T05:00:00.000Z.
• Model Date Format: Specifies how the date is formatted in the Data JSON when Data Type is set to
String. For example, YYYY-MM-DD. For more format options, see Day.js.
8. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag a Text element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. In Minimum Date, enter the earliest date the user can select from the date picker, such as
01-01-1950.
NOTE
The format entered must be the same as in the Date Format field. For example, to set
the minimum date to January 1, 1950, if the Date Format is MM-DD-YYYY, you must
enter 01-01-1950.
5. In Maximum Date, enter the latest date the user can select from the date picker, such as
12-31-2019.
NOTE
The format entered must be the same as in the Date Format field. For example, to set
the maximum date to December 31, 2019, if the Date Format is MM-DD-YYYY, you
must enter 12-31-2019.
6. In Date Format, enter the format to display the date. For example, if the format is MM-DD-YYYY, and
the user selects January 3, 2020 from the date picker, the date displays as 01-03-2020. For
more format options, see Day.js.
7. In Time Format, enter the format to display the time, such as hh:mm a, which is the default.
NOTE
Enter h or hh for hour, m or mm for minute, s or ss for seconds, and a for am/pm. A
single letter, such as h or m, has no leading zero. Remove the a to display 24 hour
time. For example, hh:mm a displays 03:30 pm, h:mm a displays 3:30 pm, and
hh:mm:ss. displays 15:30 01. For more format options, see Day.js.
8. In Time Interval, enter the intervals within an hour the user can select from the time dropdown. For
example, enter 15 for 15 minute periods within the hour such as 12:00, 12:15, 12:30, 12:45, and so on.
The default interval is 30.
9. In the Advanced Options section, select a Time Zone:
• Select Local Timezone to use the timezone of the browser.
• Select User Timezone to use the timezone set in the logged-in user's profile.
10. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag a Disclosure element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) Select the Required field to make selecting the checkbox next to the statement required.
5. (Optional) Click the Text field to enter the text for your disclosure statement.
6. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag an Email element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
See Also
1. Drag a Multi-select element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) In Display Mode, select how to display the radio buttons. The following list options
available:
• Horizontal: (Default) Display radio buttons next to each other.
• Vertical: Display radio buttons stacked.
• Image: Display each radio button as an image.
5. (Optional) If you select Image in Display Mode, the following are additional properties you can
configure:
• Width: Sets the image width.
• Height: Sets the image height.
• Image Count In Row: Sets how many images per row to display.
• Enable Caption: Displays a caption below the image.
6. In Option Source, select where the list of options come from. Select from one of the following:
• Manual: (Default) Manually enter value/label pairs. Available when Display Mode is not Image.
• Custom: Enter the Apex class and method that returns the options. Use the format
ClassName.method. See Populating Picklist Values From Apex.
• SObject: Retrieves the picklist values from the Salesforce object and field. Use the format
ObjectAPIName.FieldAPIName.
• Image: When Image is selected as Display Mode, manually enter value/label pairs and upload
images to display. If no image is uploaded, the label displays in the image box.
7. If you select Manual or Image as an Option Source, for each option follow these steps:
a. Click + Add New Option.
b. Enter the Value and visible Label.
c. If your option is an image, select an image available from the Choose existing image dropdown.
Or upload an image from your computer from the Or upload new image section.
d. (Optional) Check Use as Default to make the option selected by default.
8. If you select Custom as an Option Source, in the Source, enter the name of a method to call on a
class in the format class.method.
9. If you select SObject as an Option Source, in the Source, enter the name of a field on an object in
the format SObject.field.
10. (Optional) To display options based on the selection of another value, configure Controlling Field
Type by following these steps:
a. To define the source of the controlling field:
• To retrieve picklist options from an Apex class, select Custom.
• To retrieve dependent picklist values from a Salesforce object, select SObject.
b. In Controlling Field Source, enter an Apex class.
c. In Controlling Field Element, enter an OmniScript element name.
11. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag a Number element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. In Mask, set the allowable format the user can enter. See Pattern Mask.
NOTE
The # symbol and the integers 1-9 represent a digit in the field. You can separate the
integers by using commas and a single decimal. The decimal is only applied if a user
enters it into the field. For example, the mask ###,###.## transforms an input of
123456.78 into 123,456.78. Enter a + or - symbol to return a positive or negative
integer.
5. (Optional) For Validation Options and other additional properties, see Common OmniScript Element
Properties Definitions.
See Also
1. Drag a Password element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. In Minimum Password Length, enter the minimum number of characters the user must enter for a
valid password.
5. In Maximum Password Length, set the maximum number of characters the user can enter for a valid
password.
6. (Optional) For Validation Options and other additional properties, see Common OmniScript Element
Properties Definitions.
See Also
• OmniScript Input Elements
• OmniScript Element Reference
1. Drag a Radio element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) In Display Mode, select how to display the radio buttons. The following list options
available:
• Horizontal: (Default) Display radio buttons next to each other.
• Vertical: Display radio buttons stacked.
• Image: Display each radio button as an image.
• Segmented (Newport only): Display each radio button as a stylized link based on the Newport
Design System. See Customizing OmniScripts and Cards with Vlocity Newport Design System.
5. (Optional) If you select Image in Display Mode, the following are additional properties you can
configure:
• Width: Sets the image width.
• Height: Sets the image height.
• Image Count In Row: Sets how many images per row to display.
• Enable Caption: Displays a caption below the image.
6. In Option Source, select where the list of options come from. Select from one of the following:
• Manual: (Default) Manually enter value/label pairs. Available when Display Mode is not Image.
• Custom: Enter the Apex class and method that returns the options. Use the format
ClassName.method. See Populating Picklist Values From Apex.
• SObject: Retrieves the picklist values from the Salesforce object and field. Use the format
ObjectAPIName.FieldAPIName.
• Image: When Image is selected as Display Mode, manually enter value/label pairs and upload
images to display. If no image is uploaded, the label displays in the image box.
7. If you select Manual or Image as an Option Source, for each option follow these steps:
a. Click + Add New Option.
b. Enter the Value and visible Label.
c. If your option is an image, select an image available from the Choose existing image dropdown.
Or upload an image from your computer from the Or upload new image section.
d. (Optional) Check Use as Default to make the option selected by default.
e. (Optional) Check Auto Advance to advance the user to the next step when they click this option.
8. If you select Custom as an Option Source, in the Source, enter the name of a method to call on a
class in the format class.method.
9. If you select SObject as an Option Source, in the Source, enter the name of a field on an object in
the format SObject.field.
10. (Optional) To display options based on the selection of another value, configure Controlling Field
Type by following these steps:
a. To define the source of the controlling field:
• To retrieve picklist options from an Apex class, select Custom.
• To retrieve dependent picklist values from a Salesforce object, select SObject.
b. In Controlling Field Source, enter an Apex class.
c. In Controlling Field Element, enter an OmniScript element name.
11. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag a Range element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. In Step, enter an increment value of the input range. For example, enter 2 so the user can select 2, 4,
6, 8, and 10 from a range of 2 to 10, or 4.5, 6.5, 8.5, and 10.5 from a range of 4.5 to 10.5. Default Step
is 1.
5. To create a selectable range configure the following properties:
• Minimum Value: Sets the lowest selectable number in the range.
• Maximum Value: Sets the highest selectable number in the range.
NOTE
Both fields accept dynamic and static values. Dynamic values are set using merge
fields. For example, to use a Number element value, whose element name is
Number1, to dynamically set your minimum or maximum value, enter %Number1%.
Acceptable static values include whole, negative, and decimal numbers, such as 1,
-5, and .5.
6. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag a Select element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. In Option Source, select where the list of options come from. Select from one of the following:
• Manual: (Default) Manually enter value/label pairs.
• Custom: Enter the Apex class and method that returns the options. Use the format
ClassName.method. See Populating Picklist Values From Apex.
• SObject: Retrieves the picklist values from the Salesforce object and field. Use the format
ObjectAPIName.FieldAPIName.
5. If you select Manual as an Option Source, for each option follow these steps:
a. Click + Add New Option.
b. Enter the Value and visible Label.
c. (Optional) Check Use as Default to make the option selected by default.
d. (Optional) Check Auto Advance to advance the user to the next step when they click this option.
6. If you select Custom as an Option Source, in the Source, enter the name of a method to call on a
class in the format class.method.
7. If you select SObject as an Option Source, in the Source, enter the name of a field on an object in
the format SObject.field.
8. (Optional) To display options based on the selection of another value, configure Controlling Field
Type by following these steps:
a. To define the source of the controlling field:
• To retrieve picklist options from an Apex class, select Custom.
• To retrieve dependent picklist values from a Salesforce object, select SObject.
b. In Controlling Field Source, enter an Apex class.
See Also
1. Drag a Telephone element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) In Mask, update the allowable format by entering a custom pattern. The default is (999)
999-9999. See Pattern Mask.
5. (Optional) In Minimum Length, update the minimum number of characters the user must enter.
6. (Optional) In Maximum length, update the maximum number of characters the user can enter.
7. (Optional) For Validation Options and other additional properties, see Common OmniScript Element
Properties Definitions.
See Also
1. Drag a Text Area element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) In Minimum Length, enter the minimum number of characters the user must enter.
5. (Optional) In Maximum Length, enter the maximum number of characters the user can enter.
6. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag a Text element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) To set the type of information and its format, enter a Mask such as (999)
999-9999[x9999], which accepts a North American phone number with an optional extension. See
Pattern Mask.
5. (Optional) In Minimum Length, set the minimum length of the text allowed, such as 1.
6. (Optional) In Maximum Length, set the maximum length of text allowed, such as 300.
7. (Optional) For Validation Options and other additional properties, see Common OmniScript Element
Properties Definitions.
See Also
Text Properties
Text properties are configurable from the Properties panel when you select a Text element. With the Text
element, enable users to enter a line of text in your OmniScript.
Property Description
Mask Specifies the allowable input and sets the input's format. Use A for any letter, 9 for any number, * for any
character, and [ ] to enclose optional characters. For additional pattern information, visit https://
imask.js.org/guide.html#masked-pattern, and review Pattern Mask.
Minimum Length The minimum number of characters the user must enter.
Maximum Length The maximum number of characters the user can enter.
See Also
1. Drag a Time element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
NOTE
The format entered must be the same as in the Time Format field. For example, to
set the minimum time to midnight, if the Time Format is hh:mm a, you must enter
12:00 am.
5. In Maximum Time, enter the latest time the user can select, such as 08:00 pm.
NOTE
The format entered must be the same as in the Time Format field. For example, to
set the maximum time to 8pm, if the Time Format is hh:mm a, you must enter 08:00
pm.
6. In Time Format, enter the format to display the time, such as hh:mm a, which is the default.
NOTE
Enter h or hh for hour, m or mm for minute, s or ss for seconds, and a for am/pm. A
single letter, such as h or m, has no leading zero. Remove the a to display 24 hour
time. For example, hh:mm a displays 03:30 pm, h:mm a displays 3:30 pm, and
hh:mm:ss. displays 15:30 01. For more format options, see Day.js.
7. In Time Interval, enter the intervals within an hour the user can select from the time dropdown. For
example, enter 15 for 15 minute periods within the hour such as 12:00, 12:15, 12:30, 12:45, and so on.
The default interval is 30.
8. (Optional) In the Advanced Options section, update values for the following properties:
• Data Type: Specifies how to display the time in the Data JSON.
• If set to String, the Model Time Format is applied. String is the default data type.
• If set to Date, the time is encoded as an ISO 8601 time.
• Model Time Format: Specifies how the time is formatted in the Data JSON when Data Type is set
to String. The default format is HH:mm:ss.sss'Z'. For more format options, see Day.js.
9. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
1. Drag a URL element from the Build panel onto the canvas.
2. In the Properties panel, give the element a name in the Name field.
3. In Field Label, enter a label visible to the user.
4. (Optional) In the Error Text field of the Validation Options section, enter text to override the default
message displayed when the user does not enter the URL correctly.
5. (Optional) For additional properties, see Common OmniScript Element Properties Definitions.
See Also
NOTE
Before previewing an 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.
Requirements
To make the custom Lightning web component compatible with Vlocity Lightning web components, you
must set two metadata tags in your XML configuration file:
• runtimeNamespace: You must add the namespace of your Vlocity package to the XML metadata file in
your component by using the runtimeNamespace metadata tag. Replace the NS variable in the code
example with the namespace of your Vlocity package. For more information on finding the namespace of
your package, see Viewing the Namespace and Version of the OmniStudio Vlocity Package.
<runtimeNamespace>NS</runtimenamespace>
• Custom Lightning web components built outside of the package cannot use any Salesforce Lightning web
component that uses resources or affects the component at runtime. For more information, see
Salesforce Modules.
<isExposed>True</isExposed>
For more information on extending Vlocity Lightning web components, see Extend Vlocity Lightning Web
Components.
NOTE
Custom Lightning Web Components will not throw errors unless Debug Mode is enabled.
For more information, see Debug Lightning Web Components.
For information on adding a custom Lightning web component to an OmniScript, see Add Custom Lightning
Web Components to an OmniScript.
NOTE
Use Custom LWC Elements in a Step and a non-repeatable Block element that is not
nested.
• Components that extend the OmniScriptBaseMixin component. For more information, see Extend the OmniScriptBaseMixin
Component.
• Standalone components that run independently from OmniScript. For more information, see Create a Standalone Custom Lightning
Web Component.
Property Description
Property Name Enter a property name using the HTML attribute format to pass it into the custom component. For example,
the property recordId converts to the HTML attribute record-id.
Property Enter a value to pass in the property. Values may use merge field syntax to pass a JSON node. For
Source example, to pass the JSON node ContextId, enter %ContextId%.
6. (Optional) Activate and preview the OmniScript to view your custom Lightning web component.
See Also
• Extend the OmniScriptBaseMixin Component
• Create a Standalone Custom Lightning Web Component
Lightning web components in OmniScript provide the HTML, JavaScript, and CSS for an OmniScript
element. For example, a Text element has an extendable component named OmniScriptText. For
information on creating custom Lightning web components that do not extend an OmniScript element's
Lightning web component, see Create a Custom Lightning Web Component for OmniScript.
NOTE
Custom Lightning web components built outside of the package cannot use any Salesforce
Lightning web component that uses Salesforce resources or affects the component at run
time. For more information, see Salesforce Modules.
1. Ensure you have set up IDX Workbench or Salesforce DX locally. For information on setting up IDX
Workbench or Salesforce DX, see Set Up Lightning Web Components.
2. Locate the name of the OmniScript element's Lightning web component. Information about OmniScript
element Lightning web components is available in the OmniScript ReadMe Reference.
NOTE
LWC compatible elements display a Lightning icon in the Available Components panel
of an OmniScript.
3. Create a custom component and extend the OmniScript element's Lightning web component.
4. To make the custom Lightning web component compatible with Vlocity Lightning web components, you
must set two metadata tags in your XML configuration file:
• runtimeNamespace: You must add the namespace of your Vlocity package to the XML metadata
file in your component by using the runtimeNamespace metadata tag. Replace the NS variable in
the code example with the namespace of your Vlocity package. For more information on finding the
namespace of your package, see Viewing the Namespace and Version of the OmniStudio Vlocity
Package.
<runtimeNamespace>NS</runtimenamespace>
• isExposed : Set the isExposed metadata tag to true.
<isExposed>True</isExposed>
For more information on extending Vlocity Lightning web components, see Extend Vlocity Lightning
Web Components.
5. Once customizations are complete, deploy the custom component to your Salesforce org. For more
information on deploying Lightning web components, see Deploy Lightning Web Components.
6. Add the custom component to an OmniScript by overriding an individual element or mapping all the
elements of one type to the custom component. For more information on adding custom lightning web
components to an OmniScript, see Add Custom Lightning Web Components to an OmniScript.
Example
In this code example, a custom Lightning web component is extending the OmniScriptText component.
Replace the NS variable in the code example with the namespace of the Vlocity package you are using. For
more information on finding the namespace of your package, see Viewing the Namespace and Version of
the OmniStudio Vlocity Package.
render() {
return tmpl;
}
}
Requirements
• Custom Lightning web components extending the OmniScriptBaseMixin component cannot also
extend or override an OmniScript element Lightning web component. For more information on extending
an OmniScript element's Lightning web component, see Extend an OmniScript Element's Lightning Web
Component.
• Custom Lightning web components extending the OmniScriptBaseMixin must use the Custom LWC
element in OmniScript. For more information on using the Custom LWC element, see Add Custom
Lightning Web Components to an OmniScript.
• Custom Lightning web components built outside of the package cannot use any Salesforce Lightning web
component that uses resources or affects the component at runtime. For more information, see
Salesforce Modules.
• To make the custom Lightning web component compatible with Vlocity Lightning web components, you
must set two metadata tags in your XML configuration file:
• runtimeNamespace: You must add the namespace of your Vlocity package to the XML metadata file
in your component by using the runtimeNamespace metadata tag. Replace the NS variable in the
code example with the namespace of your Vlocity package. For more information on finding the
namespace of your package, see Viewing the Namespace and Version of the OmniStudio Vlocity
Package.
<runtimeNamespace>NS</runtimenamespace>
• isExposed : Set the isExposed metadata tag to true.
<isExposed>True</isExposed>
For more information on extending Vlocity Lightning web components, see Extend Vlocity Lightning Web
Components.
OmniScriptBaseMixin ReadMe
View all of the component's properties, attributes, and methods in the ReadMe. See OmniScript ReadMe
Reference.
render() {
return tmpl;
}
}
This code example contains a checkValidity() function that returns false when the sum is less than
zero. Replace the NS variable in the code example with the namespace of the Vlocity package you are
using.
Navigating to a Step
Enable users to navigate to different steps in the OmniScript using these three mixins:
nextButton(evt) {
if (evt) {
this.omniNextStep();
}
}
HTML Example
prevButton(evt) {
if (evt) {
this.omniPrevStep();
}
}
HTML Example
NOTE
Auto advancing to a step more than one step ahead is not permitted.
JS Example
goToStep(evt) {
if (evt) {
this.omniNavigateTo(this.omniScriptHeaderDef.asIndex - 2);
}
}
HTML Example
Method: omniSaveState(input,key,usePubSub=false):
Arguments:
Optionally save the state within a disconnected callback. Saving the state within a disconnected callback
enables the state of the element to save when users leave the element automatically. In disconnected
callbacks, the usePubSub argument must be set to true. Events in disconnected callbacks can only be
passed using pubsub.
disconnectedCallback() {
let mySaveState = {"my":"data", "here" : 8};
let key = 'customLwcKey';
let usePubSub = true;
this.omniSaveState(mySaveState, key, usePubSub);
}
1. In OmniScript, determine the Step that clears the Custom LWCs saved state.
2. In the Step's properties, click Edit as JSON.
3. Enter the property "omniClearSaveState": [ ].
4. In the omniClearSaveState property, enter the name of one or more custom LWC elements
"omniClearSaveState": [ "CustomLWC1"]. The Step sends data to the Custom LWC enabling
the Custom LWC to determine if the Step rendered.
5. In your Custom LWC's code, retrieve the current state.
this.getAttribute('data-omni-layout')
Arguments:
• The first argument must be an object with the properties input, sClassName, sMethodName, and options.
The values of each of the properties must be in String data type.
NOTE
Methods called within a package must have the namespace prepended with ${this._ns}.
For example, `${this._ns}IntegrationProcedureService`.
const params = {
input: JSON.stringify(this.omniJsonData),
sClassName: 'SomeApexClass',
sMethodName: 'someApexMethod',
options: '{}',
};
• The second argument for omniRemoteCall is an optional boolean value that links a tracked property
called omniSpinnerEnabled. The HTML must have some code to check the boolean's value.
HTML Example
<template if:true={omniSpinnerEnabled}>
<div class="slds-spinner-container__wrapper">
<c-spinner variant="brand"
alternative-text="Loading.."
size="medium">
</c-spinner>
</div>
</template>
After omniRemoteCall executes, the response callback returns an object containing the two properties
result and error.
• result: The result property contains a raw response from the server.
• error: The error property stores an error value from the Vlocity's GenericInvoke2 class.
Vlocity provides properties that, when passed in the options, enable jobs to be queuable, future, chainable,
and continuable.
const params = {
input: this.omniJsonDataS,
sClassName: 'SomeApexClass',
sMethodName: 'someApexMethod',
options: '{}',
};
}).catch(error => {
window.console.log(error, 'error');
});
• Example Integration Procedure call. For information on Integration Procedures, see OmniStudio
Integration Procedures.
const params = {
input: this.omniJsonDataStr,
sClassName: `${this._ns}IntegrationProcedureService`,
sMethodName: 'test_RemoteAction', this will need to match the VIP ->
type_subtype
options: '{}',
};
const options = {
chainable: true,
};
const params = {
input: this.omniJsonDataStr,
sClassName: `${this._ns}IntegrationProcedureService`,
sMethodName: 'test_RemoteAction', this will need to match the VIP ->
type_subtype
options: JSON.stringify(options),
};
const options = {
input: this.omniJsonDataStr,
vlcClass: 'SomeApexClass',
vlcMethod: 'someApexMethod',
useQueueableApexRemoting: true,
};
const params = {
input: this.omniJsonDataStr,
sClassName: `$
{this._ns}VFActionFunctionController.VFActionFunctionControllerOpen`,
sMethodName: 'runActionFunction',
options: JSON.stringify(options),
};
const options = {
useFuture: true,
};
const params = {
input: this.omniJsonDataStr,
sClassName: 'SomeApexClass',
sMethodName: 'someApexMethod',
options: JSON.stringify(options),
};
const options = {
input: this.omniJsonDataStr,
vlcClass: 'SomeApexClass',
vlcMethod: 'someApexMethod',
useContinuation: true,
};
const params = {
input: this.omniJsonDataStr,
sClassName: 'SomeApexClass',
sMethodName: 'someApexMethod',
options: JSON.stringify(options),
};
Arguments:
• input: The first argument, input, accepts data in an object or primitive data type. Undefined is not
accepted. The input data either replaces the current value or merges with the existing data depending on
the setting of the second argument, aggregateOverride.
• aggregateOverride: The second argument, aggregrateOverride, controls how the data saves to the data
JSON. It is an optional argument that is set to false by default. When set to false, the input data merges
with the existing data. If the data is not an object it does not merge into the data JSON. When set to true,
the input data overrides any existing data in the Custom LWC element.
Examples:
• An example passing the input argument with the default aggregrateOverride behavior.
let myData = "myvalue" // any kind of data that is a string, object, number,
etc
this.omniUpdateDataJson(this.myData);
• An example passing the input argument with the aggregateOverride argument set to false.
"CustomLWC1" : {
"prop1": "data1"
}
}
The method accepts an object that it passes into the OmniScript's data JSON. If the root data node name in
the response matches an element name in the OmniScript, that data prefills the element, and any nested
elements, when it renders in the OmniScript. If the root node name does not match an element in the data
JSON, the node inserts into the data JSON immediately. Applying the response works similar to the Send/
Response property. For information, see Manipulate JSON with the Send/Response Transformations
Properties.
Arguments:
• response: The first argument, response, is an object that merges into the data JSON.
• usePubSub: The second argument, usePubSub, controls how the response passes up to the
OmniScript header to merge into the data JSON. This boolean is set to false by default. When set to
false, response is sent to the OmniScript header via javascript events. When set to true, response is
sent to the OmniScript header by the pubsub module.
The usePubSub argument enables users to call omniApplyCallResp asynchronously. When running
asynchronously, the UI is not blocked waiting for the response.
Optionally perform a remote call by using the omniNextStep() method and calling the
omniApplyCallResp() method asynchronously.
This example demonstrates how the omniApplyCallResp() method updates Data JSON.
{
"Step1" : {
"Currency1" : 12345,
"Text1" : "data1"
},
"Step2" : {
"Text3": "data3"
}
}
2. Call omniApplyCallResp and pass data as an argument.
let myData = {
"Step1" : {
"CustomLWC1" : "newprop"
},
"Anotherprop" : {
"prop1" : "anothervalue"
}
}
this.omniApplyCallResp(myData);
3. View the updated data JSON.
{
"Step1" : {
"Currency1" : 12345,
"Text1" : "data1",
"CustomLWC1" : "newprop"
},
"Step2" : {
"Text3": "data3"
},
"Anotherprop" : {
"prop1" : "anothervalue"
}
}
Event: omniaggregate
1. Create a custom aggregate function and set the omniaggregate event to a variable.
Example:
customAggregate() {
const eventName = 'omniaggregate'
}
2. Create a variable to store the LWC element's input data.
Example:
customAggregate() {
const eventName = 'omniaggregate'
const data = {
anyKeyName : 'myElementData'
};
}
3. Construct an object by mapping the data to the key data, and an element name to the key elementId.
customAggregate() {
const eventName = 'omniaggregate'
const data = {
anyKeyName : 'myElementData'
};
const detail = {
data: data,
elementId: 'elementName2'
};
}
4. (Optional) In the detail object, include the key-value pair aggregateOverride: true to override all
existing data in the Custom LWC element.
customAggregate() {
const eventName = 'omniaggregate'
const data = {
anyKeyName : 'myElementData'
};
const detail = {
data: data,
elementId: 'elementName2',
aggregateOverride: true
};
}
5. Create a new event object that passes the omniaggregate event and an object containing these four
properties:
• bubbles: A boolean that determines if the event bubbles up to the DOM.
• cancelable: A boolean that determines if the event is cancelable.
• composed: A boolean that determines if the event can pass through the shadow boundary.
omniAggregate() {
const eventName = 'omniaggregate'
const data = {
anyKeyName : 'myElementData'
};
const detail = {
data: data,
elementId: 'elementName2'
};
const myEvent = new CustomEvent(eventName, {
bubbles: true,
cancelable: true,
composed: true,
detail: detail,
});
}
6. Call this.dispatchEvent() and pass in the event object as a parameter.
What's Next
Add a Custom Lightning Web Component to a Custom LWC Element
See Also
• Create a Custom Lightning Web Component for OmniScript
• Create a Standalone Custom Lightning Web Component
Requirements
• The component cannot extend an OmniScript element's Lightning web component.
• The component cannot extend the OmniScriptBaseMixin component.
• The component can only interact with OmniScript through the omniscriptaggregate event.
• Custom Lightning web components built outside of the package cannot use any Salesforce Lightning web
component that uses resources or affects the component at runtime. For more information, see
Salesforce Modules.
• To make the custom Lightning web component compatible with Vlocity Lightning web components, you
must set two metadata tags in your XML configuration file:
• runtimeNamespace: You must add the namespace of your Vlocity package to the XML metadata file
in your component by using the runtimeNamespace metadata tag. Replace the NS variable in the
code example with the namespace of your Vlocity package. For more information on finding the
namespace of your package, see Viewing the Namespace and Version of the OmniStudio Vlocity
Package.
<runtimeNamespace>NS</runtimeNamespace>
• isExposed : Set the isExposed metadata tag to true.
<isExposed>True</isExposed>
For more information on extending Vlocity Lightning web components, see Extend Vlocity Lightning Web
Components.
Event: omniaggregate
1. Create a custom aggregate function and set the omniaggregate event to a variable.
Example:
customAggregate() {
const eventName = 'omniaggregate'
}
2. Create a variable to store the LWC element's input data.
Example:
customAggregate() {
const eventName = 'omniaggregate'
const data = {
anyKeyName : 'myElementData'
};
}
3. Construct an object by mapping the data to the key data, and an element name to the key elementId.
customAggregate() {
const eventName = 'omniaggregate'
const data = {
anyKeyName : 'myElementData'
};
const detail = {
data: data,
elementId: 'elementName2'
};
}
4. (Optional) In the detail object, include the key-value pair aggregateOverride: true to override all
existing data in the Custom LWC element.
customAggregate() {
const eventName = 'omniaggregate'
const data = {
anyKeyName : 'myElementData'
};
const detail = {
data: data,
elementId: 'elementName2',
aggregateOverride: true
};
}
5. Create a new event object that passes the omniaggregate event and an object containing these four
properties:
• bubbles: A boolean that determines if the event bubbles up to the DOM.
• cancelable: A boolean that determines if the event is cancelable.
• composed: A boolean that determines if the event can pass through the shadow boundary.
• detail: Data passed in the event.
Example:
omniAggregate() {
const eventName = 'omniaggregate'
const data = {
anyKeyName : 'myElementData'
};
const detail = {
data: data,
elementId: 'elementName2'
};
const myEvent = new CustomEvent(eventName, {
bubbles: true,
cancelable: true,
composed: true,
detail: detail,
});
}
6. Call this.dispatchEvent() and pass in the event object as a parameter.
What's Next
Add a Custom Lightning Web Component to a Custom LWC Element
See Also
• Communicate with OmniScript from a Lightning Web Component
• Custom LWC Element
• Extend the OmniScriptBaseMixin Component
The Pub/Sub property enables Action elements and Step elements to send data in Key-Value pairs to other
LWCs. LWCs must register the OmniScript component's event name and add code to handle the data sent
from the event.
1. In an OmniScript Action or Step, select the Messaging Framework and check Pub/Sub.
2. In the Key and Value fields, configure which data to pass to another LWC.
a. In the Key field, enter a name to store the value.
b. In the Value field, enter data to pass to the LWC. The field accepts merge syntax.
handleOmniAction(data) { handleOmniStepLoadData(data) {
switch(data.name) { switch(data.name) {
case 'SomeNameForAction': case 'FirstStep':
this.handleSomeNameForAction(data);
break; this.handleOmniFirstStepLoadData(data);
case 'SomeNameForAction2': break;
this.handleSomeNameForAction2(data); case 'SecondStep':
break;
default: this.handleOmniSecondStepLoadData(data);
// handle default case break;
} default:
} // handle default case
}
handleSomeNameForAction(data) { }
// perform some logic specific to
SomeNameForAction action handleOmniFirstStepLoadData(data) {
// that has element name = // perform some logic specific when a
"SomeNameForAction" Step element which name is
} // FirstStep is loaded
}
handleSomeNameForAction2(data) {
// perform some logic specific to handleOmniSecondStepLoadData(data) {
SomeNameForAction2 action // perform some logic specific when a
// that has element name = Step element which name is
"SomeNameForAction2" // SecondStep is loaded
} }
Access the Action's Element Type using data.type. n/a
handleOmniAction(data) {
switch(data.type) {
case 'Integration Procedure Action':
this.handleIPActionPubsubEvents(data);
break;
case 'Remote Action':
this.handleRemoteActionPubsubEvents(data);
break;
default:
// handle default case
}
}
handleIPActionPubsubEvents(data) {
// perform some logic specific to
Integration Procedure Actions
}
handleRemoteActionPubsubEvents(data) {
// perform some logic specific to Remote
Actions
}
See Also
• Message with Window Post Messages and Session Storage Messages
• Create a Custom Lightning Web Component for OmniScript
Make Remote Calls from Lightning Web Components using the OmniScript
Action Framework
OmniScripts make remote calls using a new action framework built with JavaScript classes. The Action
framework is available to all custom LWCs in your Salesforce org. Enable an LWC to make remote calls
using specific functionalities by importing the Common Action Utility class into the LWC.
NOTE
Custom LWCs extending the OmniScript Base Mixin must use the omniRemoteCall()
function. For more information, see Extend the OmniScriptBaseMixin Component.
Requirements
To make the custom Lightning web component compatible with Vlocity Lightning web components, you
must set two metadata tags in your XML configuration file:
• runtimeNamespace: You must add the namespace of your Vlocity package to the XML metadata file in
your component by using the runtimeNamespace metadata tag. Replace the NS variable in the code
example with the namespace of your Vlocity package. For more information on finding the namespace of
your package, see Viewing the Namespace and Version of the OmniStudio Vlocity Package.
<runtimeNamespace>NS</runtimenamespace>
• Custom Lightning web components built outside of the package cannot use any Salesforce Lightning web
component that uses resources or affects the component at runtime. For more information, see
Salesforce Modules.
• isExposed : Set the isExposed metadata tag to true.
<isExposed>True</isExposed>
For more information on extending Vlocity Lightning web components, see Extend Vlocity Lightning Web
Components.
NOTE
Custom Lightning Web Components will not throw errors unless Debug Mode is enabled.
For more information, see Debug Lightning Web Components.
Best Practice
When making remote calls, start the flow with the executeAction method. Do not start the flow with the
invokeAction method. To standardize the action flow and use the built-in logic of the action framework,
Vlocity recommends that all action flows begin with executeAction.
NOTE
The invokeAction method's purpose is to make the remote call with request parameters
processed by the preProcess method. The preProcess method, by default, supports
queueable and chainable process flows. The postProcess method standardizes the
response in a predictable format.
Utility: omniscriptActionUtils
Defined Methods
Available Variables
1. Obtain the dot notation format of the namespace in your LWC by importing
getNamespaceDotNotation from omniscriptInternalUtils. Replace NS in the first line of
code with the namespace of your package. For information on finding the namespace of your package,
see Viewing the Namespace and Version of the OmniStudio Vlocity Package.
NOTE
Remote calls made to Apex classes inside a vlocity managed package must include
the namespace in the sClassName parameter sent into the executeAction.
NOTE
Each key requires a stringified value.
• If the LWC displays in the Omniscript Designer, it is possible to send events to the Debug Console.
Send events to the Debug Console by including the sendDataToDebugConsole method in your
LWC. The method provides logic on sending events to the Debug Console.
sendDataToDebugConsole accepts these arguments:
• params
• resp
• label
Examples
To use the Common Action Utility, refer to these examples:
connectedCallback() {
this._actionUtilClass = new OmniscriptActionCommonUtil();
}
triggerRemote() {
const params = {
input: '{}',
sClassName: 'LwcTest',
sMethodName: 'lwctest',
options: '{}',
};
this._actionUtilClass
.executeAction(params, null, this, null, null)
.then(response => {
window.console.log(response);
})
.catch(error => {
window.console.log(error);
});
}
• Sample sendDataToDebugConsole method:
params: sendParams,
response: sendResp,
element: { label: label },
},
});
this.dispatchEvent(debugEvent);
}
• Sample queueable remote call using executeAction:
connectedCallback() {
this._actionUtilClass = new OmniscriptActionCommonUtil();
}
triggerQueueable() {
const options = {
input: '{}',
vlcClass: 'LwcTest',
vlcMethod: 'lwctest',
useQueueableApexRemoting: true,
};
const params = {
input: '{}',
sClassName: `$
{this._ns}VFActionFunctionController.VFActionFunctionControllerOpen`,
sMethodName: 'runActionFunction',
options: JSON.stringify(options),
};
this._actionUtilClass
.executeAction(params, null, this, null, null)
.then(response => {
window.console.log(response);
})
.catch(error => {
window.console.log(error, 'error');
});
}
• Sample continuation remote call using executeAction:
connectedCallback() {
this._actionUtilClass = new OmniscriptActionCommonUtil();
}
triggerContinuation() {
const options = {
input: '{}',
vlcClass: 'QeRemoteAction2',
vlcMethod: 'populateElements',
useContinuation: true,
};
const params = {
input: JSON.stringify(this.omniJsonData),
sClassName: 'QeRemoteAction2',
sMethodName: 'populateElements',
options: JSON.stringify(options),
};
this._actionUtilClass
.executeAction(params, null, this, null, null)
.then(response => {
window.console.log(response);
})
.catch(error => {
window.console.log(error, 'error');
});
}
• Sample future remote call using executeAction:
connectedCallback() {
this._actionUtilClass = new OmniscriptActionCommonUtil();
}
triggerFuture() {
const options = {
useFuture: true,
};
const params = {
input: '{}',
sClassName: `${this._ns}IntegrationProcedureService`,
sMethodName: 'Test_Chainable',
options: JSON.stringify(options),
};
this._actionUtilClass
.executeAction(params, null, this, null, null)
.then(response => {
window.console.log(response);
})
.catch(error => {
window.console.log(error, 'error');
});
}
• Sample chainable remote call using executeAction:
connectedCallback() {
this._actionUtilClass = new OmniscriptActionCommonUtil();
}
triggerChainable() {
const options = {
chainable: true,
};
const params = {
input: '{}',
sClassName: `${this._ns}IntegrationProcedureService`,
sMethodName: 'Test_Chainable',
options: JSON.stringify(options),
};
this._actionUtilClass
.executeAction(params, null, this, null, null)
.then(response => {
window.console.log(response);
})
.catch(error => {
window.console.log(error, 'error');
});
}
• Sample parameters for a remote call from inside a Vlocity package:
const params = {
input: '{}',
sClassName: `${this._ns}IntegrationProcedureService`,
sMethodName: 'Test_Chainable',
options: '{chainable: true}',
};
The omniscriptValidation component provides the OmniScript element's component with the functions to
enable validation. For information on using validation in custom components that do not extend an
OmniScript element's component, see Extend the OmniScriptBaseMixin Component.
The stepChartItems Lightning web component contains logic that determines the different step statuses the
step chart and its labels display. For information on extending OmniScript Lightning web components, see
Extend an OmniScript Element's Lightning Web Component.
1. Create a custom Step Chart Lightning web component that extends the stepChart Lightning web
component. For more information, download the ReadMe OmniScript ReadMe Reference.
2. Extend the stepChartItems Lightning web component in one of two ways:
• Customize the stepChartItems LWC by creating an additional custom component that extends the
stepChartItems LWC. For more information, download the ReadMe OmniScript ReadMe Reference.
• Extend the stepChartItems LWC directly in your custom Step Chart LWC. The default behavior and
styling of the stepChartItems LWC will display in your custom Step Chart LWC.
3. (Optional) If a custom Step Chart Items LWC exists, extend that component in your custom Step Chart
component.
4. After deploying custom LWCs to Salesforce, open an OmniScript.
5. In the OmniScript's Script Configuration properties, go to Element Type To LWC Component
Mapping, and click Add New Mapping.
6. In the Element Type field, enter StepChart.
7. In the Lightning Web Component field, enter the name of your custom Lightning web component.
8. Activate the OmniScript, and Preview your changes.
See Also
1. Create a custom LWC that extends the omniscriptModal LWC and add it to your Salesforce org.
See Extend an OmniScript Element's Lightning Web Component.
2. The custom modal LWC must have these three slots for OmniScript to insert content into the modal:
<slot name="header></slot>
<slot name="content></slot>
<slot name="footer"></slot>
3. In OmniScript Setup , scroll to the Element Type to LWC Component Mapping property.
4. In the Element Type field, enter Modal.
5. In the Lightning Web Component field, enter the name of the custom LWC.
6. Activate and preview the OmniScript to view your modal changes.
See Also
• Customize the Step Chart Component
• Deploy Lightning Web Components
Extend and Override the Save for Later Acknowledge Lightning Web
Component
Customize the Save for Later messaging modal in OmniScript by extending and overriding the Save for
later Acknowledge LWC.
1. Create a custom LWC that extends the omniscriptSaveForLaterAcknowledge LWC and add it to
your Salesforce org. See Extend an OmniScript Element's Lightning Web Component.
2. From OmniScript Setup, scroll to the Element Type to LWC Component Mapping property.
3. In the Element Type field, enter SaveForLaterAcknowledge.
4. In the Lightning Web Component field, enter the name of the custom LWC.
See Also
• Customize the Step Chart Component
• Deploy Lightning Web Components
Use the custom component to override an individual OmniScript element's component, override all
OmniScript element components of one element type, or to add an entirely custom component that does
not extend an element's component.
NOTE
Before previewing an 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.
See Also
• Create a Custom Lightning Web Component for OmniScript
• Style OmniScripts
The custom LWC must extend the element's component because OmniScript passes in properties specific
to the original component that the custom component is overriding. For more information on extending
OmniScript element components, see Extend an OmniScript Element's Lightning Web Component.
1. From the element's properties pane, in the LWC Component Override field, enter the name of a
custom Lightning web component.
2. Save and Activate the OmniScript.
3. Activate the OmniScript and click the Preview tab to preview the OmniScript.
What's Next
Deploy your OmniScript to preview the Custom LWC's design and behavior. See Activate and Deploy
OmniScripts.
See Also
• Add Custom Lightning Web Components to an OmniScript
• Create a Custom Lightning Web Component for OmniScript
The custom Lightning web component must extend the Element Type's Lighting web component. For
example, to override all of the Text elements in the OmniScript, the custom component must extend the
OmniScriptText component.
1. From the OmniScript's Script Configuration, locate the property Element Type To LWC Component
Mapping, and click New Mapping.
2. In the Element Type field, enter the Element type that the custom component overrides.
3. In the Lightning Web Component field, enter the name of the custom component that overrides the
element type.
4. Save and Activate the OmniScript.
5. Click Preview to preview the OmniScript.
What's Next
Deploy your OmniScript to preview the Custom LWC's design and behavior. See Activate and Deploy
OmniScripts.
See Also
• Add Custom Lightning Web Components to an OmniScript
• Create a Custom Lightning Web Component for OmniScript
The Custom LWC element enables custom components to either interact with the OmniScript or to act as a
standalone component. Standalone components do not interact with the OmniScript or the OmniScript's
data JSON.
NOTE
Enable custom Lightning web components to interact with OmniScript by extending the
OmniScriptBaseMixin component. Custom Lightning web components extending the
OmniScriptBaseMixin cannot extend an OmniScript element's component. For more
information on the OmniScriptBaseMixin, see Extend the OmniScriptBaseMixin
Component
NOTE
Standalone custom Lightning web components cannot extend any OmniScript element
component or the OmniScriptBaseMixin component. The standalone component supports
custom functionalities but cannot interact with an OmniScript. For more information on the
standalone components, see Create a Standalone Custom Lightning Web Component.
What's Next
Deploy your OmniScript to preview the Custom LWC's design and behavior. See Activate and Deploy
OmniScripts.
See Also
• Add Custom Lightning Web Components to an OmniScript
• Create a Custom Lightning Web Component for OmniScript
Style OmniScripts
Add custom styling to OmniScripts by using static resources, extending an Element's Lightning web
component, overriding global stylesheets, or using SLDS design tokens.
View the behavior of each customization option in this page's table, and choose the solution that meets
your requirements.
See Also
• Customize the Step Chart Component
• Extend and Override an OmniScript Modal Lightning Web Component
• Extend and Override the Save for Later Acknowledge Lightning Web Component
NOTE
Multi-Language OmniScripts provide beta support for right-to-left languages. See Create
Multi-Language OmniScripts.
3. (Optional) Display custom styling for right-to-left languages by taking these steps:
a. In Setup, click Edit as JSON.
b. Add the name of the static resource as a value to newportRtl or lightningRtl to display the
styling for right-to-left languages. If you are updating an existing OmniScript, add newportRTL
and lightningRtl manually.
"stylesheet": {
"newport": "",
"lightning": "",
"newportRtl": "myRtlNewportStyles",
"lightningRtl": ""
}
4. Activate and preview the OmniScript to view your custom styling.
See Also
• Style OmniScripts
• Apply Global Branding to OmniScripts
• Create Multi-Language OmniScripts
NOTE
Multi-Language OmniScripts provide beta support for right-to-left languages.
"stylesheet": {
"newport": "",
"lightning": ""
}
3. Add the name of the static resource as a value to newport or lightning.
"stylesheet": {
"newport": "",
"lightning": "myCustomOmniScriptStyles"
}
4. (Optional) Add the name of the static resource as a value to newportRtl or lightningRtl to
display the styling for right-to-left languages. If you are updating an existing OmniScript, add
newportRTL and lightningRtl manually.
"stylesheet": {
"newport": "",
"lightning": "",
"newportRtl": "myRtlNewportStyles",
"lightningRtl": ""
}
5. Activate and preview the OmniScript to view your custom styling.
See Also
• Style OmniScripts
• Apply Global Branding to OmniScripts
• Create Multi-Language OmniScripts
OmniScript elements use SLDS Design Tokens for styling. Override tokens that have global access to
modify the appearance of your OmniScript.
NOTE
Design Tokens are not supported in Safari browsers and Community pages.
1. In your OmniScript's Setup panel, click the Styling Options section or Lightning Design System
Design Tokens section.
2. In the Lightning Design System Design Tokens field, enter tokens by applying these changes:
a. Remove the dashes and apply camelcase to the token. For example, the token $spacing-xx-
small must be $spacingXxSmall.
b. Replace the token's $ symbol with --lwc-.
--lwc-spacingXxSmall
c. Set the token's value, and end the line for each token using a ;.
--lwc-spacingXxSmall: 10rem;
--lwc-spacingSmall: 5rem;
--lwc-spacingMedium: 2rem;
See Also
• Apply Global Branding to OmniScripts
• OmniScript Designer Overview
Line Break
The Line Break element creates a line break in the OmniScript wherever it exists.
Elements placed after a line break start on the next line regardless of an other element's width. Place the
Line break element directly above the element that should begin on a new line.
Results
The Line Break ensures that a line separates the elements surrounding the Line Break element. For
example, this image displays a Line Break element that separates a person's First and Last Name from
their phone and email in the UI.
See Also
• Modify OmniScript UI Behavior
• Style OmniScripts
System Requirements:
1. Ensure that Node and NPM are installed on your local computer using the commands NPM outlines in
their documentation https://www.npmjs.com/get-npm. If you do not have Node or NPM, download them
from https://nodejs.org/en/download/.
2. Clone vlocityinc/newport-design-system from https://github.com/vlocityinc/newport-design-system
using a command-line interface. To see which components are provided by Newport, look at the UI/
components directory.
3. From the GitHub page, perform the latest steps to install the correct dependencies.
4. After installation is complete, launch the Storybook.js preview by issuing the command npm start.
5. Review the documentation in the Storybook preview.
6. Add customizations to your theme. See Customizing OmniScripts and Cards with Vlocity Newport
Design System.
7. Apply the OmniScript to individual OmniScripts or override the Newport theme for the entire org. See
Deploy and Apply Global Styling Changes using the Newport Design System.
8. Preview the changes in your Salesforce org by using the Newport Player in the OmniScript Designer
Preview.
See Also
Themes are stored in the design-tokens folder. To create a new theme for your OmniScripts or Cards,
copy the vlocity-newport-skin folder to a new folder and edit the files in it as required. To change the color
scheme of a theme, edit the skin's *color.yml files. Some colors are specified using hex RGB codes,
others are specified using tokens that resolve to hex RGB colors. These tokens are defined in the
aliases/color.yml file. To change colors for a specific component, examine its definition to find the
source of its color properties, and trace it to the definition.
When you change colors, the Newport components are recompiled, so there is a slight delay before your
changes are reflected in the Previewer.
Simple Example: Using the Previewer, look at the definition for the input element, noting the orange
underline. To change the color of the line, edit design-tokens/vlocity-newport-skin/
background-color.yml and change the setting for COLOR_BORDER_INPUT_ACTIVE to a different
color token defined in /aliases/color.yml . To verify your change, view the input component using the
Previewer.
For an optimal appearance on all viewing platforms, set control width to 6. Smaller widths might not render
well on every platform.
The Newport Previewer enables you to view the definition, appearance, and behavior of Newport
components and utilities. You can see how the component will render on desktops, tablets, and
smartphones.
To preview an element or utility, choose it from the lists in the left pane. To view the code behind it, click
</>.
The restriction tree displays the hierarchy of element definitions, from the base implementation through all
the derived ones. To view a specific definition, click the corresponding node in the restriction tree.
Deploy and Apply Global Styling Changes using the Newport Design System
Apply modifications to the Newport design system by adding a Static Resource that overrides the Newport
theme wherever it is available. Once uploaded, the Newport changes will apply to any OmniScripts using
Newport.
1. In your Salesforce org, go to Setup and, in the Quick Find box, enter Omni Interaction
Configuration.
2. ClickManage, click New and configure the following settings:
• Label: You must name this newportZipUrl for the changes to be applied.
• Name: Enter any name.
• Value: The relative URL for the static resource that contains your custom styles. To obtain the
relative URL, go to the Static Resource (see 4 in the Before You Begin section), hover over the View
File link, right-click and copy the URL. Enter the relative URL after the domain name, removing the
question mark at the end. For example, the bold text would be copied in this URL: https://salesforce-
org-test.na75.visual.force.com/resource/16679825000/vloc_customNewport?
3. Preview your OmniScript and select the Newport page from the drop-down in the upper right-hand
corner to preview your changes.
See Also
Elements contain up to three conditional view options depending on the Type of element. For example, an
Action outside of a Step does not have a Read Only option since the action is not visible.
1. From the Properties section on the element, go to the Conditional View section.
2. Select a Condition Type from the drop-down menu.
NOTE
If the element is repeatable, enter the name of the element followed by |x, where x is
the xth repeated element. For example, if Age is repeated, Age|2 refers to the second
instance of the repeated element.
• If the element type is Select or Radio, type in the name of the option in plain text—for example, Yes
or No.
• If the element type is Multi-Select, enter a semicolon-separated string—for example Ind;Small.
• If the element type is Date, Time, or Date/Time, the value should be in ISO format:
• Date—2014-10-01T07:00:00.000Z (Wed Oct 01 2014 00:00:00 GMT-0700 (PDT)
• Date/Time—1970-01-02T06:19:00.000Z (Tue Feb 17 2015 22:20:03 GMT-0800 (PST))
7. In the canvas, click the Hide Conditional Elements checkbox to hide all of the conditional elements in
the OmniScript. The conditional elements are marked with a yellow eye icon.
NOTE
In LWC OmniScripts, the onChange behavior runs after a half-second delay.
See Also
• Hide OmniScript Elements
• Access OmniScript Data JSON with Merge Fields
See Also
• Creating Dynamic Forms Using the Conditional View Property
• Prefill OmniScript Elements using DataRaptor
1. From the OmniScript Designer, drag a Messaging element into the structure panel where the message
must appear.
2. For Validate Expression enter the expression that should be validated. You can evaluate any element
or elements, including Formula and Aggregate. For more information about formulas, see Create
Formula Fields in an OmniScript. For more information about setting up expressions, see Dynamic
Forms Using the Conditional View Property.
3. In the Messages section, select message types for when the expression evaluates as true or false and
then enter messages. True and False messaging can be deactivated and messaging is optional.
In OmniScripts, validation runs when a user clicks out of a field by using the onBlur function.
NOTE
In LWC OmniScripts, the onChange behavior runs after a half-second delay.
Messaging Example
In this example, a Requirement message displays when a user is under the age of eighteen:
• The Messaging element's Validation Expression fails when the Birthdate field has a value, and the
AgeFormula element is less than eighteen:
• The Formula element uses the AGE function to return the age of the user based on the date entered into
the Birthdate element:
Message Types
OmniScript messages use pure SLDS styling. This table provides examples of OmniScript messages.
Messages will remain until a user enters a valid value.
Requirement
Warning
Comment
To verify that your platform event was fired correctly, use one of the programmatic methods described in the
related Salesforce developer documentation.
For example, on an application, an email address may not be required during the initial intake step, and in a
future step, the user states that they wish to be contacted by email.
The Set Errors element runs after the step and returns the user to the initial intake step with custom error
messaging:
NOTE
The Set Errors action does not support these elements: File, Image, Messaging, and
Formula.
Generate the OmniScript's Lightning web component by deploying your OmniScript. Add the generated
LWC to Lightning pages, Community pages, third-party applications, and custom LWCs to launch your
OmniScripts.
1. From OmniScript, click Activate to activate the OmniScript and deploy the OmniScript automatically.
2. (Optional) Click Deactivate, and then Activate to redeploy the OmniScript and apply updates.
3. After deploying your OmniScript, launch your OmniScript from one of these experiences:
6. (Optional) Click the dropdown arrow, and click Download LWC to view the metadata for the
OmniScript.
What's Next
Add an OmniScript to a Community or Lightning Page
See Also
• Launch an OmniScript with LWC OmniScript Wrapper
• Embed an OmniScript Lightning Web Component in a Lightning Web Component
• OmniOut
How to Launch
Once activated, enable OmniScript access in one of three ways: standalone, embedded, or Vlocity Aura
Wrapper.
Standalone
Once Activated, the OmniScript is compiled and deployed as a standalone Lightning Web Component.
Access the LWC in the Salesforce Lightning App Builder in the Custom section and drag it onto the page.
Embedded
Once Activated, you can embed the component into any Aura or LWC component using the component tag.
The component attribute "prefill" accepts string or javascript object.
Examples
<c-type--sub-type-english prefill='\{"ContextId":"abc","otherParam":"FAQ"}'
layout="newport"></c-type--sub-type-english>
Since Lightning Web Components are not yet URL addressable, you can use this method to pass additional
parameters into the OmniScript.
Example
this[NavigationMixin.Navigate]({
type: 'standard__component',
attributes: {
componentName: '__vlocityLWCOmniWrapper'
},
state: {
c__target: 'c:testSubTypeEnglish',
c__layout: 'lightning', // or 'newport'
c__tabIcon: 'custom:custom18'
}
})
https://my_org.force.com/lightning/cmp/my_org__vlocityLWCOmniWrapper?
c__target=my_org:typeSubTypeEnglish&c__layout=lightning&c__tabIcon=custom:custo
m18
https://my_org.force.com/lightning/cmp/my_org__vlocityLWCOmniWrapper?
c__target=my_org:typeSubTypeEnglish&c__layout=newport&c__tabIcon=custom:custom1
8
2. Search for the name of your OmniScript by entering the OmniScript's unique Type, SubType, and
Language. Use the syntax Type/SubType/Language to search as the search does not ignore forward
slashes.
5. (Optional) Configure the inline options. See Display Inline OmniScripts on Lightning and Community
Pages.
6. (Optional) Control how right-to-left languages display. OmniScript provides beta support for right-to-left
languages. In the dir field, select whether the OmniScript displays ltr or rtl..
7. (Optional) Change the device view in the Community Builder to Phone or Tablet to see how the
OmniScript displays on a mobile or tablet device.
1. In a Lightning Page's App Builder, search for the name of your OmniScript by entering the OmniScript's
unique Type, SubType, and Language. Use the syntax Type/SubType/Language to search as the
search does not ignore forward slashes.
4. (Optional) Configure the inline options. See Display Inline OmniScripts on Lightning and Community
Pages.
5. (Optional) Control how right-to-left languages display. OmniScript provides beta support for right-to-left
languages. In the dir field, select whether the OmniScript displays ltr or rtl.
6. (Optional) Modify the component's visibility by adding filters. For more information, see Dynamic
Pages.
7. (Optional) Change the device view of the App Builder to Phone to see how the OmniScript displays on
a mobile device.
See Also
The wrapper component makes the OmniScript URL addressable to enable the passing of additional
parameters to the OmniScript. The Vlocity LWC OmniScript Wrapper component and the
vlocityLWCOmniWrapper are Aura components that wrap an OmniScript to make the OmniScript URL
addressable.
NOTE
If the LWC OmniScript Wrapper component exists on a record page, the record Id passes
into the OmniScript as the Context Id automatically.
2. Search for the Vlocity LWC OmniScript Wrapper component, and drag it onto the page.
3. Leave the fields in the component blank.
4. (Optional) To test an OmniScript using the LWC OmniScript Wrapper in the Community Builder:
1. In the LWC OmniScript Wrapper, check the Stand Alone Mode checkbox.
2. In the OmniScript Name field, enter the component name of your OmniScript with the prefix c:.
The OmniScript's component name is a combination of the Type, SubType, and Language of your
OmniScript without spaces.
c:customTestEnglish
To configure the URL to access the Vlocity LWC OmniScript Wrapper component:
1. Configure the URL for the Community page in a URL field, such as a URL in a Card Action or text
editor.
Example URL for a Community named AccountCommunity that has a page named AccountPage:
https://exampleURL.force.com/AccountCommunity/s/AccountPage?
2. In your OmniScript, click the How to Launch Activated Script button.
3. In the How to Launch modal, click the LWC tab.
4. In the Vlocity Aura Wrapper section of the LWC tab, copy the text appearing after the question mark.
https://exampleURL.na130.visual.force.com/lightning/cmp/
namespace__vlocityLWCOmniWrapper?
c__target=namespace:myLWCTestEnglish&c__layout=lightning
• The c__target parameter is set to a component indicated by c:. The component is the Name of your
OmniScript combined with the Type, SubType, and Language. This component passes into the LWC
OmniScript Name field of the Vlocity LWC OmniScript Wrapper.
• The c__layout parameter passes the layout to the Layout field of the Vlocity LWC OmniScript
Wrapper.
5. In the c__target parameter of the URL, replace the namespace with c.
c__target=c:myLWCTestEnglish&c__layout=lightning
6. Paste the copied text to the end of the Community Page URL.
https://exampleURL.force.com/AccountCommunity/s/AccountPage?
c__target=c:myLWCTestEnglish&c__layout=lightning
7. (Optional) Pass additional parameters by separating them with an ampersand, &. Parameters must use
the c__ prefix. For example, to pass "AccountName": "Acme" into the OmniScript's data JSON,the
syntax must be &c__AccountName=Acme.
8. (Optional) Fire events from the Navigate Action by passing an event to the OmniScript in the URL
parameter c__vlocEvents. The Navigate Action element must have the checkbox property LWC
PubSub Message? enabled to fire the event.
1. In your LWC OmniScript, click the How to Launch Activated Script button.
2. In the How to Launch modal, click the LWC tab.
3. In the Vlocity Aura Wrapper section of the LWC tab, copy the relative path of the URL.
https://exampleURL.na130.visual.force.com/lightning/cmp/
namespace__vlocityLWCOmniWrapper?
c__target=namespace:myLWCTestEnglish&c__layout=lightning
4. (Optional) Launch the OmniScript using a Newport layout by clicking Newport and copying the relative
path.
5. (Optional) When using the URL path in a production org, you must replace the namespace of your
component. In the c__target parameter of the URL, replace the namespace with c.
c__target=c:myLWCTestEnglish&c__layout=lightning
6. (Optional) Prefill an OmniScript by assigning prefill values with the prefix &c__ placed before the key.
For example, to pass "AccountName": "Acme" into an OmniScript's data JSON, add the parameter
using the syntax &c__AccountName=Acme. For more information on prefilling data, see Load Data
into OmniScript Elements.
lightning/cmp/NS__vlocityLWCOmniWrapper?
c__target=c:myTypeExampleEnglish&c__AccountName=Acme
7. (Optional) When using the wrapper in a console app, add a Console Tab Icon and a Console Tab Label
by setting the c__tabIcon and c__tabLabel parameters. The c__tabIcon accepts an SLDS Icon , and
c__tabLabel accepts plain text. For example, &c__tabLabel=Custom
Label&c__tabIcon=standard:account renders the console tab shown in this example image.
8. (Optional) To view additional parameters for the vlocityLWCOmniWrapper, see Launch Lightning Web
Component URLs with vlocityLWCWrapper.
9. (Optional) Fire events from the Navigate Action by passing an event to the OmniScript in the URL
parameter c__vlocEvents. The Navigate Action element must have the checkbox property LWC
PubSub Message? enabled to fire the event.
10. Paste the URL wherever you plan to invoke the OmniScript from and preview the functionality.
1. From Setup, enter Object Manager into the Quick Find search.
2. Select an Object, and click Buttons, Links, and Actions.
3. Click New Button or Link.
4. Set Display Type to Detail Page Button.
5. Set Content Source to URL.
6. Configure the URL value to equal the relative path of the vlocityLWCOmniWrapper. For information on
obtaining the relative path, see Launching an OmniScript in Lightning.
namespace__vlocityLWCOmniWrapper?
c__target=c:myLWCTestEnglish&c__layout=lightning
An inline OmniScript renders as a button that, when clicked, launches the OmniScript inline. The record id
of a page passes into an inline OmniScript as a Context Id automatically. You can render more than one
inline OmniScript on a page .
NOTE
Running OmniScripts in inline mode disables SEO Enabled and Save For Later.
1. From the Community or App Builder, add an activated OmniScript to a page. For information on adding
OmniScripts to a Lightning page, see Add an OmniScript to a Community or Lightning Page.
2. In the OmniScript component, check the inline checkbox.
See Also
OmniOut enables OmniScripts to create, read, update, and delete Salesforce data from a third-party
website.
What's Next
Configure OmniOut. See OmniOut.
1. From Setup, click Develop, and then click Sites, and then click New.
2. Enter values for Site Label, Site Name, and other fields.
3. In the Active Site Home Page field, lookup and select the Visualforce OmniScript page created above.
4. Record the site's URL for future reference.
5. Click Public Access Settings, and then click Edit, and set the following values:
• Custom Object Permissions
• Vlocity OmniScripts: Read
• Elements: Read
• Applications: Read, Create
• Field Level Security
• Vlocity OmniScript: Make All Fields Visible
• Element: Make All Fields Visible
• Application: Make All Fields Visible
• Enabled Apex Class Access
• [NameSpace] .ApplicationResource
6. Embed the URL from Step 4 in the external site's iFrame.
NOTE
When passing data from an LWC into an embedded LWC OmniScript's prefill property, the
string values "true" and "false" will convert to boolean values. To avoid this issue,
stringify your values by adding additional quotation marks escaped by backslashes. For
example, to convert this prefill object prefill = { "Multi-select1":"true"} the
new syntax must be prefill = { "Multi-select1":"\"true\""}.
1. In the OmniScript Designer, click the dropdown menu, click How To Launch, and copy the component
tag.
2. In your component's HTML file, enter the component tag to embed the OmniScript component.
<template>
<c-doc-example-english layout="lightning"></c-doc-example-english>
</template>
this.template.addEventListener( 'omniaggregate');
2. Create a separate function that handles the response of the event and assigns the value to a variable.
omniUpdateHandler(event) {
if(event.detail) {
this.omniDataJSON = event.detail;
// do something with the data JSON
}
3. Add the function that handles the response as an argument to the event listener so that it fires
whenever the OmniScript data JSON updates.
this.template.addEventListener( 'omniaggregate',
this.omniUpdateHandler.bind(this));
NOTE
A reusable OmniScript cannot contain another reusable OmniScript. Additionally, no
element in a reusable OmniScript can have the same name as an element in the parent
script. Reusable OmniScripts adopt the script configuration of the parent script.
1. In the OmniScript you want to reuse, click Setup, and check the Reusable checkbox.
2. Activate the reusable OmniScript.
3. Navigate to the OmniScript that will host the reusable OmniScript.
4. In your OmniScript's Build panel, expand the OmniScripts section.
5. Locate the reusable OmniScript and drag it into the canvas.
6. Preview your OmniScript to test the behavior.
What's Next
Activate and Deactivate Embedded OmniScripts
See Also
• Embed an OmniScript Lightning Web Component in a Lightning Web Component
• Embed FlexCards in an OmniScript
1. From the Setup section of the embedded script, click Activate Version or Deactivate Version.
2. Verify the Affected OmniScripts (any Active OmniScript that this form is embedded in), and click
Proceed.
See Also
• Embed an OmniScript Lightning Web Component in a Lightning Web Component
• Embed FlexCards in an OmniScript
For example, after creating a Force.com site, publicly available APIs are enabled for the Site User profile
based on the profile's Apex class access to RestResource Apex classes. Adding an Apex class
permissions checker ensures that unauthorized users, such as a guest user, can't access classes through
the Vlocity/V1/GenericInvoke/ API.
5. Click New.
Multi-language OmniScripts provide beta support for right-to-left languages. When using RTL languages,
some styling may result in functional limitations.
NOTE
Due to a known Salesforce issue, multi-language OmniScripts do not display correctly in
Community Builder.
1. Enable multi-language support for OmniScripts. See Enable Multi-Language OmniScript Support
2. Define custom labels and translations. See Define Custom Label Translations in Multi-Language
OmniScripts.
3. Test your OmniScript translations. See Test a Multi-Language OmniScript.
4. Launch the multi-language OmniScript. See Launch a Multi-Language OmniScript.
5. Deploy multi-language OmniScripts to other orgs using DataPacks. DataPacks do not include custom
labels. You must deploy custom labels manually from your org.
See Also
• Access Custom Labels in an OmniScript Custom Lightning Web Component
• OmniScript Custom Label Reference
NOTE
Beginning with Vlocity Insurance and Health Summer '20, the LWC OmniScript Designer
supports multi-language OmniScripts.
What's Next
Define Custom Label Translations in Multi-Language OmniScripts
See Also
3. In the Edit Your OmniScript Translations modal, click the Settings gear icon and select a language.
4. Choose a custom label or create a new custom label. For information on creating custom labels in
Salesforce, see Creating and Editing Custom Labels.
NOTE
Use naming conventions when creating custom labels in an org with multiple
developers to avoid duplications and improve querying. Example syntax:
jSmithCustomTextLabel.
NOTE
• Custom labels must have values. If the value for a custom label does not exist, the
following error message displays when previewing an OmniScript:
Error: Field $Label.<stepName> does not exist. Check spelling
• For elements that support rich text (text blocks, step instructions, and headline
labels), you can include HTML markup in the text and translations.
6. Click Save.
7. Repeat the translation process for each language that requires translations.
What's Next
View required OmniScript custom label translations and apply translations for each label. See OmniScript
Custom Label Reference.
See Also
• Translate Custom Labels for Date and Time Components
• Access Custom Labels in an OmniScript Custom Lightning Web Component
Custom Lightning web components that extend the OmniScript Base Mixin component or an OmniScript
element's Lightning web component can access both OmniScript custom labels and Salesforce custom
labels. For information on custom LWCs in OmniScript, see Create a Custom Lightning Web Component for
OmniScript.
"moreCustomLabels" : ["myCustomLabel1","orgCustomLabel2"]
3. In your custom LWC's code, add a line of code to access a map of all the custom labels using the
allCustomLabels attribute. Each component type requires a different attribute name to access the
allCustomLabels attribute.
See Also
• Define Custom Label Translations in Multi-Language OmniScripts
• Custom LWC Element
You must use custom labels to add help text in multi-language OmniScripts. If a custom label is not defined
for a help text tooltip, an error renders.
NOTE
Custom labels do not render in design mode. You must preview the OmniScript to
render the custom labels correctly.
See Also
• Test a Multi-Language OmniScript
• Create Multi-Language OmniScripts
3. Open a window console or JavaScript editor and paste in the locale object.
NOTE
Custom labels accept valid JSON strings only.
6. Choose a custom label that meets your requirements and open it in Salesforce.
9. (Optional) Use the JSON as an example and create custom translations in a JSON string format.
10. Save the custom label and preview your component.
See Also
• Extend Vlocity Lightning Web Components
• Define Custom Label Translations in Multi-Language OmniScripts
• Configure options manually: In Salesforce, define a set of custom labels and configure translations for
them. In OmniScript Designer, use the custom labels to specify the options for the Select elements.
• Use a translated Salesforce picklist: In Salesforce, create a picklist and use Translation Workbench to
define translations for it. In OmniScript Designer, define a Select element that is bound to the Salesforce
picklist.
• Use Apex: Create an Apex method that returns a set of options that are translated according to the
language code in effect when the method is called.
The following sections describe these approaches in detail, using the Select element. Use the same
approach to create multi-language Radio and Multi-select elements.
1. In SalesForce, define a set of custom labels and specify the translations for each one.
2. In OmniScript designer, add a Select element configured as follows:
For example, for a list of animals, you might define three custom labels with translations in Salesforce:
In OmniScript Designer, specify the Options for the Select element, for example:
Value Label
1 Animal_Bear
2 Animal_Dog
Value Label
3 Animal_Cat
1. Create a class and method that returns a map of options translated according to the language code in
effect when the method is called. See the sample code below.
2. Add a Select element to your OmniScript, configured as follows:
NOTE
For dependent Select elements that are populated programmatically (custom), configure a
controlling field by specifying the name of an OmniScript element that contains the value
that determines the options in the dependent Select element. (For example, a list of cities
might depend on a state specified in another element.) For the dependent element, specify
its CONTROLLING FIELD settings as follows:
The Apex method that returns the values that populate the Select element must contain
logic that uses the value of the controlling element and the language code to determine
what values to return to populate the dependent element.
Example Method
For example, if you define a custom object named "Multi_Language_Picklist" and define a picklist field
named "Animal_Type", specify source as follows:
Multi_Language_Picklist__c.Animal_Type__c
5. For each option. specify the translated value, then save your changes.
1. Click Preview. If the OmniScript contains custom Lightning web components, activate the OmniScript
before previewing.
2. From preview, select a language.
3. View the custom label translations for every OmniScript element to ensure they display correctly.
4. Repeat the testing process for every translated language.
What's Next
Launch a Multi-Language OmniScript
See Also
1. From the OmniScript, click How to launch activated script. The HOW TO LAUNCH modal displays.
2. Copy the URL you want to use to launch your script. For information on OmniScript URLs, see Launch
an OmniScript with LWC OmniScript Wrapper.
3. Determine which language code to use in Salesforce. See Supported Languages
4. Edit the URL to add the c__LanguageCode parameter and set the parameter equal to the Salesforce
language code.
https://exampleURL.force.com/AccountCommunity/s/AccountPage?
c__target=c:docLWCTestEnglish&c__layout=lightning&c__LanguageCode=es
NOTE
Resume saved OmniScripts in other languages by using a different language code
parameter.
See Also
• Test a Multi-Language OmniScript
• Access Custom Labels in an OmniScript Custom Lightning Web Component
NOTE
If you are converting an OmniScript from single- to multi-language, specify valid custom
label names or clear all translatable properties. If there is literal text in the property and no
custom label exists, a Missing label error is displayed when you attempt to preview the
script.
The following table lists the properties for which Vlocity provides custom labels with default translations.
See Also
• Define Custom Label Translations in Multi-Language OmniScripts
• Create Multi-Language OmniScripts
Each option has a Value/Label pair. The Value is the language-independent data that gets passed in and
out of the OmniScript remotely, either through DataRaptor or Remote/Rest actions. It is also referenced
when setting up Conditional View.
The Label is displayed on the form. The Value and Label can be identical or different.
For example, the ethernetLink element shown in the image below has four options:
The value of one of these options is "EN" and its label is "No Link To An Ethernet Device". If a user clicks
No Link To An Ethernet Device, the data returned is "EN".
For Multi-Select elements, if the user selects multiple options, a semicolon-delimited list of data is returned.
For example, selecting No Link To An Ethernet Device and Hardware Crashes returns EN;HW.
NOTE
If the values change frequently, enable the "Fetch Picklist Values at Script Load" to ensure
that the OmniScript elements contain the most up-to-date set of values. Salesforce
sources include picklists and custom classes.
Date Range
To create a selectable Date range for the Date or Date/Time element, configure the following properties:
The minDate and maxDate fields accept both dynamic and static values.
• today + 1 day
• today - 5 days
• today + 2 months
• today - 1 month
• 2018/10/21
• 10-21-2018
Time Range
NOTE
OmniScripts do not allow the DateTime format to be included in the minTime or maxTime
fields.
To create a selectable Time range for the Time element, configure the following properties:
The minTime and maxTime fields accept static values that must include four digits formatted as HH:mm in
the 12-hour clock or 24-hour clock syntax.
• 01:00 AM
• 01:00 PM
• T07:30:00.000Z
• 01:00
• 13:00
• T19:30:00.000Z
For example, anUpdate Case OmniScript requires the Status element to dynamically populate based on
these values from the Status field on the Case object:
To do this, select SObject as the Option Source type and type Case.Status:
Now the form will retrieve and dynamically populate the list with values from Case.Status:
NOTE
If the object or field name are custom, they must be preceded with the NameSpace of the
package—for example, vlocity_cmt__Party__c.vlocity_cmt__Location__c or
Case.vlocity_cmt__Amount__c.
You can also use a custom class to populate lists in OmniScripts. See the sample code for instructions on
implementation.
If the values of the list are dependent on another field, add the information for that field in the Controlling
Field section. Follow the instructions above to define the controlling field and also enter the element name
for the field on the form.
To populate the options of an element, a List<Map<String, String>> is returned from the Custom
Implementation. The Map Options are 'Name' the Language Independent Option and 'Value' the UI Display
value.
if (methodName.equals('PopulatePicklist')) {
PopulatePicklist(input, outMap, options);
}
return true;
}
// Get All Relationship Types for Account when the Omniscript is compiled.
public void PopulatePicklist(Map < String, Object > input, Map < String,
Object > outMap, Map < String, Object > options) {
List < Map < String, String >> options = new List < Map < String,
String >> ();
for (vlocity_namespace__PartyRelationshipType__c rel: [Select
vlocity_namespace__TargetRole__c, Id FROM
vlocity_namespace__PartyRelationshipType__c where
vlocity_namespace__SourcePartyType__c = 'Account']) {
Map < String, String > tempMap = new Map < String, String > ();
tempMap.put('name', rel.Id);
// Language Independent
tempMap.put('value', rel.vlocity_namespace__TargetRole__c);
// Displayed in Picklist
UIoptions.add(tempMap);
}
outMap.put('options', options);
}
}
NOTE
Prior to Spring '17, there were two Source fields in the Designer when creating
Hierarchical Picklists (Controlling Field). Any OmniScripts setup prior to Spring '17 will still
work; the new OmniScripts will only have one Source field in the Options which will set the
dependency for Hierarchical Picklists as shown in the instructions above.
When populating a Dependent Picklist through Apex, the returned Picklist Options are a Map<String,
List<Map<String, String>>. The keys to the initial Map are the Language Independent ('name') options
from the Controlling field. The List<Map> Options are 'Name' the Language Independent Option and 'Value'
the UI Display value. For information on populating a picklist with no dependencies, see Populating Picklist
Values From Apex.
// Displayed in Picklist
UIdependency.get(rel.vlocity_namespace__SourcePartyType__c).add(tempMap);
}
outMap.put('dependency', dependency);
}
}
NOTE
OmniScript does not check to see if the dependent picklist value is valid when passed.
Invalid values are discarded when the controlling picklist is changed.
Lookup Element
Run a query using text input to retrieve Salesforce data using the Lookup element. The retrieved data is
returned in Value/Label pairs and becomes available for selection in a dropdown list.
The Lookup element calls the DataRaptor Output service to query SFDC tables based on the parameters
configured in the Properties section. To avoid performance issues, it is recommended to keep the number
of value results under 150. Select the Custom type to run a custom Apex class. Lookup elements display
values from Salesforce based on a standard SOQL query built using the parameters of the Lookup
elements.
SObject Type
To query for SObject data:
4. In the Populate Lookup Element with Query Results section, set a label and a value for the Lookup
results by configuring these fields:
• Label: Set the label for a Lookup Element's dropdown list to a JSON Value returned by the query.
Because the query returns the values in the Lookup Element's JSON Path, you must set the full
path. For example, to display an Account Name as a label in a Lookup Element named Company,
the full path is Company:Name.
• Value: Set the Value to an Object field that populates the Lookup Element's JSON Node using the
full path. When a user selects a label, the value populates the Lookup element's JSON Node. For
example, to use an Account Id for a JSON value when a user selects an Account Name from the
Lookup element, the full path is Company:Id.
5. Preview the OmniScript to ensure the query is working and the value is being set correctly.
Custom Type
Use the Custom type to call a custom Apex class which implements NS.VlocityOpenInterface, where NS is
the Name Space of the package. The source is NS.ClassName.MethodName.
For more details on query configurations, see Working with Lookup Query Configurations.
Before using the Record Type filter, set up a Remote Site to enable the options to load into the OmniScript
preview Visualforce page.
https://doc-demo-vlocity.visualforce.com/apex/OmniScriptHome?
sfdc.tabName=01rlu000001A3aC
3. From Setup, enter Remote Site into the quick find box, and click Remote Site Settings.
4. Click New Remote Site.
5. For the Remote Site Name, enter vlocity.
6. For the Remote Site URL, paste the URL from Step 2.
7. Click Save.
1. In the Picklist Object and Field property, enter the picklist in the following format:
ObjectAPIName.FieldAPIName.
2. Filter the picklist by Record Type by entering the Record Type into the Record Type property. This
property supports %MergeFields%.
When using the Lookup Element in OmniScript, the filtering of results is performed by the Lookup Query
Configuration properties section. There are three main types of queries that can be built using this the
Lookup Query Configuration properties section: AND join, OR join, and Deep query.
AND Join
To create AND Join and filter results on two or more fields set the sequence field value to the same value
as the fields you want to join together in the query.
In this example, we search for Leads that have Country = "USA" AND City = "San Francisco". This is done
by selecting the same Lookup order and populating the JSON Path with the same value.
NOTE
The JSON path can be any text but a best practice is to name the JSON Path the object
being referenced.
Deep Query
To create a Deep query, the Lookup Order is put in sequential order. OmniScript builds smaller query sets
at each order set.
In the example Deep query we are search for Leads that have Country = "USA" AND City = "San
Francisco".
The from that data set we also only display Leads that have Industry = "Government". Since we are
performing a Deep Query the JSON Path Field Name needs to be updated to populate Accordingly.
NOTE
The JSON path in the Field Population property section must match the text used in the
JSON Path. A best practice is to separate the JSON Path with a colon to indicate the
nested JSON Path.
OR Join
OR Joins are not currently supported from within the OmniScript editor so a workaround must be used to
accomplish this functionality. To perform an OR Join, a custom formula field on the object can be
implemented to accomplish the OR portion of the query such that the formula will return either a TRUE
value if the OR query is met and FALSE if not.
),
"TRUE",
"FALSE")
This effectively allows for an OR join even though the OmniScript element doesn't support this functionality
directly.
NOTE
In all instances, Filter Values must be text and wrapped in double quotations.
Dependency setup between one another via Salesforce Field Dependency feature. For more information,
see Define Dependent Picklist in the Salesforce Help.
When the OmniScript runs, the childAge formula element evaluates only the childBirthday element in the
same block:
• Upload files and images to Salesforce Documents (up to 1 MB). Files upload to the public Vlocity
Document Uploads folder and are set to Externally Available.
• Link to files and images from Documents.
The following Text Block example contains an Image, two merge fields, and a URL.
To use the Rich Text Editor, drag a Text Block or Headline element into the OmniScript structure.
Additionally, you can use it in the Step properties to edit the Instruction text in horizontal mode.
To get data from Salesforce into OmniScript elements, create a DataRaptor Extract, as follows.
On the Extract tab, map data from sObjects to an intermediate structure called the Extraction Step JSON.
For each sObject from which your OmniScript requires data, perform the following steps:
To make mapping easier, edit the OmniScript using the OmniScript Designer and copy its Data JSON to the
Expected JSON Output pane of the DataRaptor Designer, which populates the Output Data Type field
with a list of valid output fields.
Additionally, you can use DataRaptor to extract data from Salesforce based on data already entered in an
OmniScript. For example, if you enter the first and last name of a contact, DataRaptor can use this
information to retrieve and fill additional fields for that contact.
1. Create a DataRaptor Extract (JSON) Interface. For more information, see DataRaptor Extract
Overview.
2. Create one or more Extract Data Mappings to generate an Extraction Step JSON. For more
information, see Load Salesforce Data into OmniScript Using DataRaptor.
3. Create one or more Transform Data Mappings to map fields from the Extraction Step JSON into
elements on the script. For more information, see Create a DataRaptor Extract.
4. Preview the OmniScript.
For example, you might want to create an OmniScript for troubleshooting common customer issues. For
this OmniScript, you will want to prefill six elements on the OmniScript: AccountName, AccountId,
CaseNumber, CaseDescription, CaseStatus, and CaseSubject. Since the form is being launched from a
Case record, the Id of the Case will get passed into the ContextId element of the OmniScript. Using that Id,
DataRaptor queries the Case and Account table to retrieve the requested rows.
The data's root node name must match the name of the block element. The fields within each array
instance of the data JSON node must match the name of an element within the block. Prefill data into
repeatable blocks with Actions by returning data that matches the block's element name and the element's
within the block using an array format.
"EditBlock1": [
{
"FirstName": "John",
"LastName": "Smith"
},
{
"FirstName": "Jane",
"LastName": "Smith"
}
]
NOTE
Edit Blocks are inherently repeatable because they store entry values in an array
format.
8. In the elementValueMap JSON node, locate the block element's JSON node, and enter an array of
data. For example, to prefill two Text input elements in an Edit Block element, add an array that maps
to the elements in the block.
Edit Block Element configuration:
JSON Array:
"EditBlock1": [
{
"FirstName": "John",
"LastName": "Smith"
},
{
"FirstName": "Jane",
"LastName": "Smith"
}
]
9. Click Edit in Property Editor to convert back to the default view of the Set Values Action.
10. Preview the OmniScript to view the nested data in the OmniScript's data JSON.
For more information on prefilling elements, see Prefill OmniScript Elements using DataRaptor.
The Seed Data JSON property should be used with static values that seed during the initial load of the
OmniScript. In order to set values using formulas or with information entered into the OmniScript after the
initial load, see Set Values in an OmniScript.
1. In the OmniScript's Setup, find Seed Data JSON section and click +Add New Key/Value Pair.
2. Enter the name of the element to prefill in the left text field. Enter the desired value of the element in
the right text field. If the element has multiple responses, such as a multi-select, you can prefill more
than one value by separating the entries with a semicolon.
3. When the user launches the script, the elements specified in the Seed Data JSON section contain the
static values from the Script Configurations.
4. You can also use the Seed Data JSON property to add hidden nodes to the Data JSON of the
OmniScript. For example, an OmniScript used for troubleshooting may create a case. You could use
the default values from hidden nodes to prefill values. For example, you may want the OmniScript to
create a Case with Type, Status, and Origin defined in the Data JSON of the OmniScript. Using this
method, you can have multiple OmniScripts associated with one DataRaptor interface that creates the
Case.
See Also
1. From the OmniScript’s Script Configuration panel, click the Element to open its properties panel.
2. From the Element’s properties panel, click the Default Value field, and enter a value. The default value
field accepts merge field syntax. See Access OmniScript Data JSON with Merge Fields.
3. Preview the OmniScript to view the default value in the Data JSON.
Merge fields access data JSON using syntax to indicate to an OmniScript Element that a merge field is
present. The syntax requires you to wrap a full JSON path with a percent sign on both ends.
NOTE
Only certain element properties support merge fields.
• Setting Values to rename elements, access JSON nodes, run formulas, and populate elements. For more
information, see Set Values in an OmniScript
• Access data stored in OmniScript elements in a formula or in a future step.
• Access data returned from an Action. For example, an HTTP Action or DataRaptor Action returns data
from Salesforce or an external source. For more information on Actions, see OmniScript Action
Elements.
• Access data passed in as a parameter from a page.
1. Locate the name of the JSON node in the OmniScript's data JSON.
2. Enter the name of the JSON node and wrap the name in percentage signs to indicate it is a merge
field. For example, a merge field accessing a JSON node named firstName must use the syntax
%firstName%.
Additional Syntax
This table provides additional syntax examples for nested JSON.
• Set values sent into the data JSON from a response or parameter
• Create values determined by OmniScript Functions and Supported Formula Operators
Download this datapack and test the behaviors the examples on this page provide.
To rename a node:
8. Preview the OmniScript and view the new JSON node name.
Populate Elements
Populate future elements with values from data JSON, formula operators, functions, concatenations, and
static values. Prefill an element directly from a DataRaptor or Action response whenever possible. See
Prefill OmniScript Elements using DataRaptor for more information.
NOTE
When populating an element using Set Values, data types must match. For example, you
cannot set a Text element with the value from a Number element.
To populate an element:
NOTE
When the Element Name maps to an existing element in the OmniScript, the
element's Type appears between the Element Name field and the Value field.
5. In the Value field, enter the name of the JSON node using merge syntax to map it to the new JSON
node.
Concatenate Values
Create dynamic values by concatenating JSON nodes.
NOTE
There must be a space on either side of an operator for the operation to run correctly.
6. Click Edit in Property Editor to convert back to the default view of the Set Values Action.
7. Preview the OmniScript to view the nested data in the OmniScript's data JSON.
See Also
1. Set the Path to the node you are drilling down on.
2. Enter the new node name into the JSON Node field.
1. Set the Path to the node you are drilling down on.
2. Enter the new node name into the JSON Node field, and enter a colon (:).
3. After the colon, without leaving a space, enter the second JSON node name.
1. Set the Path to the node you are drilling down on.
2. In the JSON Node field, enter a merge field that represents the new name, for example %NewNode%.
3. Use a SetValues action or an input parameter on the Preview tab to test the merge field.
For example, on the Preview tab, enter a Key of NewNode and a Value of MightyNode, click Execute
and then look for MightyNode in the output JSON.
1. In the Response JSON Node field of a step, enter the path to the list node followed by a pipe
character (|) and a merge field that represents the list item number, for example, ListNode|%item%.
2. Use a SetValues action or an input parameter on the Preview tab to test the merge field.
For example, on the Preview tab, enter a Key of item and a Value of 2, click Execute, and watch the
step output appear as the second item in the list.
If the step output node and the existing list item node match, the list item value is replaced. If they don't
match, the step output node is added as a peer of the existing list item node.
1. Set your Path to the node you are drilling down on.
2. Set the Node to VlocityNoRootNode.
1. Set the Path to the node you are drilling down on.
2. Leave the JSON Node field blank.
1. Preview the OmniScript in the OmniScript Designer and enter input that you need to transform.
2. After the action containing the JSON transformation has run, click Debug to open the Debug console.
3. In the Debug console, expand the action that is sending or receiving the transformed JSON.
4. Expand the Request to see JSON that has been transformed by the Send JSON Path and Send
JSON Node, or expand the Response to see JSON that has been transformed by the Response
JSON Path and Response JSON Node.
Formula and Aggregate elements support the following constants and types:
• OmniScript elements and JSON nodes, passed in as merge fields—for example, %Element1% or
%JSONnode1%
• Numbers and integers—for example, 5 + 3.145
• String literals wrapped in quotes—for example, ' "ABC" + "DEF" '
• Booleans—for example, true || false
• Arrays—for example, "[1,2, 3, 4, 5]"
• Null
See Also
• OmniScript Functions
• Create a Formula or Aggregate in an OmniScript
Operator Meaning
+ Addition
- Subtraction
* Multiplication
/ Division
^ Power
= Equals
<> Not equals
> Greater than
< Less than
>= Greater than or equal to
<= Less than or equal to
&& And
|| Or
() Parentheses
For information on supported functions in OmniScript, see OmniScript Functions. For information on adding
a Formula field to an OmniScript, see Create a Formula or Aggregate in an OmniScript.
OmniScript Functions
You can add functions to the Aggregate and Formula elements. For information on adding Formula or
Aggregate elements to your OmniScript, see Create a Formula or Aggregate in an OmniScript. To view a
list of supported formula operators that can be used with the Formula element, see Supported Formula
Operators.
The tables below detail the different available functions and how they work.
"Then Result",
"Else Result"
)
IF(EXPRESSION,THEN, ELSE) IF((%reset%="Yes" || %reboot%="Yes"), If EXPRESSION evaluates to True, THEN is
"Closed", "Escalated") returned, otherwise ELSE is returned.
OR() IF((%reset%="Yes" OR( %reboot
%="Yes")), "Closed", "Escalated")
SUMIF(values, SUMIF(%MyArray%, >5) Returns the sum of all comma-separated
expression_or_value) elements and value if a condition is met.
The elements behave similarly in an OmniScript. However, the Aggregate element should be used for
aggregation purposes, such as averaging or summing elements. Formula elements can use both
Supported Formula Operators and OmniScript Functions . For example, you may want to determine a
contract end date by adding 365 days to a date element. You could do this by using the example formula
below:
If you would like to set a date one week from today's date, you could do so by using the example formula
below:
The instructions below explain how to add and configure Formula or Aggregate element to your OmniScript.
1. From the OmniScript Designer, drag a Formula or Aggregate element onto the script structure.
2. You can add OmniScript Functions by clicking on the function name; the function will pre-populate in
the Expression section. Add the OmniScript elements inside of the function using merge field notation
by enclosing the element in percentage (%) signs.
3. If you plan to use this element in a repeatable block, see Evaluate Elements in Repeatable Blocks.
4. If you are using a Formula element, you can continue to build the formula using Supported Formula
Operators in the Expression text box.
5. If the element should not appear on the script UI, Click Hide.
6. You can also create additional elements that depend on the results of the Formula. For example, the
step shown in the image below appears when the Total Income formula is less than 1,000. For more
information, see Create Dynamic Forms Using the Conditional View Property and Display Messaging
in OmniScripts.
7. You can test the Formula or Aggregate by clicking the Preview link.
See Also
The DataRaptor Post Action sends data from the script to a DataRaptor Load that performs the update or
upsert. (When multiple upsert keys are used, the record must match all keys to be considered a
match.)When you define the DataRaptor Load, you map data from the OmniScript's Output JSON to fields
in sObjects. For details, see Object Field Mapping.
See Also
Required Items:
PDF Requirements:
• PDF must be a Linearized PDF, Version 1.5 or above. You can save a PDF as Linearized Version 1.7 by
clicking Save as Other, and then Reduced Size PDF, and then Acrobat 10.0 and later.
• Vlocity does not support the List Box PDF Form field type (Multi-Select fields) in the PDF.
• The PDF Form Field Values for Radio Buttons and Dropdowns must be logically mappable. For example,
a Radio Button on a PDF form may not have two options with the same name.
NOTE
Firefox and Safari browsers cannot fill some fields without taking additional steps. To use
Firefox and Safari, see Configuring your browser to use the Adobe PDF plug-in.
What's Next
Create a DataRaptor Interface to Map OmniScript Data to a PDF
1. From OmniScript, click Preview and fill in test data to populate the JSON of the OmniScript.
2. Copy the OmniScript's JSON data.
3. From the DataRaptor tab, click New.
4. For Interface Type, select Transform.
5. Enter an Interface name.
6. In the Input Type field, select JSON.
7. In the Output Type field, select PDF.
8. In the Target PDF field, select an existing PDF, and click Save.
What's Next
Map Fields From the OmniScript to the PDF
See Also
What's Next
Add a PDF Action to the OmniScript
See Also
NOTE
The PDF Action is not supported in IE 11 browsers.
1. From the OmniScript Designer, drag the PDF Action to the OmniScript.
2. From the Properties pane, in Document, select your PDF document.
3. (Optional) Attach the PDF to a parent record by taking these steps:
a. Fill the Attachment Name field to name the attachment.
b. Fill the Attachment Parent Id field with the id of the attachment's parent record id.
4. In the Send Transformations section, from the PreTransform DataRaptor Interface picklist, select the
DataRaptor that you created in Create a DataRaptor Interface to Map an OmniScript to a PDF.
5. Check the Read Only checkbox to make the filled PDFs read-only.
6. If necessary, change the default date and time formats.
NOTE
Use moment.js formatting. If left blank, the defaults are Time Format: h:mma, Date
Format: MM/DD/YYYY, Date Time Format: MM/DD/YYYY h:mma.
7. Launch the form in Preview mode and fill out each field that should map to the PDF.
8. Check the PDF to confirm the mappings are correct.
See Also
By default, files are uploaded to Salesforce Content Documents directly. To associate one or more
Salesforce objects with the uploaded file, specify a comma-separated list of object Ids in the Content
Parent Id field. In Salesforce, the uploaded files are listed in the sObject detail page's Content section.
To specify a Vlocity Open Interface to be run after the file or image is uploaded, set the Remote Action
section's Remote Class and Remote Method fields. As input, the specified method receives a Map<String,
Object> list containing the File data from the Data JSON. The options contain the remoteOptions and the
filesMap, which contains the Ids of any Content documents that were created.
NOTE
The Image and File elements do not work in preview because they use SFDC
components. When Image and File elements are required in a Step, the Preview cannot
advance past the Step. Vlocity recommends marking File and Image elements as
Required only before activating the OmniScript.
1. From OmniScript, under Available Components, drag the File or Image element from the Inputs
section into a Step in the Structure panel.
2. In the Content Parent Id field, enter an object Id, or comma-separated list of object ids, to attach the
Content Document to a parent record. When left blank, the Content Document does not attach to a
parent record.
3. (Optional) When configuring the Image element, allow uploads of multiple images by checking Allow
Multiple Images.
4. (Optional) Use one of the JSON node names from Image and File to apply a condition to another
element:
"yourFileElementName": [
{
"data": "0693g000000T1ZFAA0",
"filename": "isolated-on-png.png",
"vId": "0683g000000T11iAAC",
"size": 8234
}
]
File Properties
This page contains information on File element Properties.
Property Description
Content Parent Id Enter a comma-separated list of object ids to attach the Content Document to Parent Records. When left blank,
the Content Document does not attach to a parent record. Note: Image and File uploads do not work in Preview.
Extra Payload Sends additional Key/Value pairs. Supports merge field syntax.
Remote Class Specify a Vlocity Open Interface Class.
Remote Method Specify a Vlocity Open Interface Method.
Remote Options Key/value pairs that specify additional class invocation options.
See Also
Image Properties
This page contains information on Image element Properties.
Property Description
Allow Multiple Images Enables users to upload multiple images at once.
Content Parent Id Enter a comma-separated list of object ids to attach the Content Document to Parent Records. When left
blank, the Content Document does not attach to a parent record. Note: Image and File uploads do not work
in Preview.
Extra Payload Sends additional Key/Value pairs. Supports merge field syntax.
Remote Class Specify a Vlocity Open Interface Class.
Remote Method Specify a Vlocity Open Interface Method.
Remote Options Key/value pairs that specify additional class invocation options.
See Also
These features require an active DocuSign account but do not require DocuSign for Salesforce or
DocuSign Connect. For optimal integration between DocuSign and Salesforce, Vlocity recommends one of
these products.
To prepare a DocuSign template for OmniScript, you must have the following items:
• DocuSign account
• DocuSign for Salesforce account
1. From the Vlocity DocuSign Setup tab, click Modify DocuSign Configuration.
2. Add your Account Name, Account Id, and select the org type, either Demo or Production.
3. Click Save.
4. From Setup | Security | Remote Site Settings, add the correct DocuSign endpoint. Endpoints could
include:
• https://www.docusign.net
• https://na2.docusign.net
• Contact DocuSign if these endpoints are incorrect for your account.
After completing this step, you can create either a DocuSign Envelope Action or DocuSign Signature Action
(v12 only) in your OmniScript.
NOTE
If you have updated your DocuSign template, you must Fetch the DocuSign templates
to update the input fields. For more information on fetching templates, see Linking
DocuSign Template to Vlocity.
NOTE
To use a DocuSign Signature Action with OmniScript in a Community, add this Visualforce
page permission to any profiles using the OmniScript: OmniScriptLwcDocuSignViewPdf.
When the modal opens, a node is written to the Data JSON of the OmniScript in this format:
"DocuSignElementName": [
{
"status": Declined",
"envelopeId":"xyz123"
},
{
"status": Completed",
"envelopeId":"xyz123"
}
]
A new status and envelopeId generate every time the modal launches. Statuses include Completed,
Declined, and In Process.
1. From the OmniScript Designer, drag a DocuSign Signature Action element from the Actions section
onto a step or block of the form, where it renders as a button.
2. From the element properties, select a DocuSign Template.
3. Enter a signer name, email, and template role. Template roles are configured during the template
setup. Signer Name and Signer Email support merge fields. For example %firstName% %lastName%
would merge the contents of the firstName and lastName fields into the Signer Name field during
runtime.
4. Add an Email Subject that recipients receive after signing.
5. (Optional) Enter a DocuSign Return Url that will display in the modal after signing is complete.
6. Expand the Send/Response Transformations section and select the DataRaptor Interface that was
created to map the OmniScript fields to the DocuSign Template.
7. (Optional) OmniScripts use window.parent.postMessage to post the status to the Omniscript from the
Docusign Return Page. If you are overriding OmniScriptDocuSignReturnPage in your OmniScript, post
the docusign status back to OmniScript using window.parent.postMessage. For more information, see
Example:
window.addEventListener('DOMContentLoaded', function(event){
var domClass = '';
var searchStr = event.currentTarget.location.search;
searchStr = searchStr.substring(searchStr.indexOf('&event='),
searchStr.length);
searchStr = searchStr.substring(searchStr.indexOf('=') +
1,searchStr.length);
1. From the OmniScript Designer, drag a DocuSign Envelope Action element from the Actions section
onto the palette. To run the action automatically, place it between steps. To run the action when the
user clicks a button, place it in a step.
2. From the element properties, select a DocuSign Template.
3. Click Add Recipient and enter a signer name, email, and template role.
Template roles are configured during the template setup. The Signer Name and Signer Email roles
support merge fields. For example %firstName% %lastName% would merge the contents of the
firstName and lastName fields into the Signer Name field during runtime.
4. If you have more than one recipient, you can override the routing order set on the template by entering
a new order in the Routing Order field. Leave the field blank to use the default routing order.
5. Add an Email Subject and Body that recipients receive along with the envelope.
6. Expand the Send/Response Transformations section and select the DataRaptor Interface that was
created to map the OmniScript fields to the DocuSign Template.
Managing OmniScripts
The following topics tell you how to manage your OmniScripts.
Export OmniScripts
Export OmniScripts in a DataPack to share them with other Salesforce orgs.
1. From the OmniScripts home tab or directly from your OmniScript, click the menu dropdown arrow.
2. Click Export.
3. Click Next and follow any steps that appear. A DataPack file will download to your computer.
What's Next
Import your OmniScript. See Import OmniScripts.
See Also
• Create a DataPack
• Import a DataPack
Import OmniScripts
Add existing OmniScripts to an org by importing them with a DataPack.
See Also
• Create a DataPack
• Import a DataPack
Version OmniScripts
Create multiple versions of an OmniScript to develop and test scripts in preview mode before activating
scripts for production deployment. Vlocity recommends not making any changes to a production
OmniScript. Any time you plan to alter a production script, create a new, inactive version and make all
updates in the latest version before activating.
See Also
• Create an OmniScript
• Access OmniScript Designer
• OmniScript Designer Overview
• Set Up an OmniScript
Emailing an OmniScript
To email a link to an OmniScript to a Contact, Lead, or User, you create an Integration Procedure that uses
a remote action to send the email and call the Integration Procedure from an OmniScript or from Apex
code.
For example, an insurance agent who requires details about a prospect can email an OmniScript link to the
prospect. When the recipient of the email clicks the link, their browser displays the OmniScript, containing
whatever data the sender has entered. The recipient fills in the required information, enabling the agent to
create a quote for them.
The recipient does not need to have a Salesforce account to access the OmniScript but must have a
Contact, Lead, or User record containing their email address and the permissions required to view the
script. The recipient might be required to log in to view the email.
The following sections provide details about creating the required components.
In the Remote Options section, define the following required key/value pairs, plus any merge fields
required by the email template:
• Language : OmniScript language. For multi-language OmniScripts, set to "Multi-Language" and set the
LanguageCode parameter to the Salesforce language code .
• Type : OmniScript type.
• Subtype: OmniScript subtype.
• emailTargetObjectId: The Id of the recipient (contact, lead, or user).
• emailTemplateName : The Salesforce Unique Template Name.
• saveAsActivity: Set to true if you want an activity record created when the email is sent.
• LanguageCode : For multi-language OmniScripts, the Salesforce language code.
This remote action creates an OmniScript record with the specified Type, Subtype and Language. Before
the OmniScript is saved, all actions prior to the first step are run, which enables you to prefill information
about the Contact, Lead, or User. The Remote Action merges the data into the email template and sends
the email.
To test the Integration Procedure, go to the Preview tab and define an input parameter named "contextId"
that contains the Id of a valid Contact, Lead, or User who has a valid email address. When you are satisfied
that the Integration Procedure works as desired, activate it.
The OmniScript must provide the contact Id in the contextId node of the JSON payload that is sent to the
Integration Procedure.
To verify that you have configured all settings correctly, preview the OmniScript and check the resulting
email.
https://<instance>/apex/OmniScriptUniversalPage?layout=lightning#/OS/
%OmniScriptInstanceId%/scriptState/saveAndResume/true/true
In the email template, use Salesforce-style merge fields (formatted as {!object.field}) to incorporate
Salesforce data, and Vlocity-style merge fields (formatted as %fieldname%) to incorporate data that is
provided by the Integration Procedure.
For example:
Hi, {!Name}:
Here's a link to the OmniScript you requested:
https:///myorg.visual.force.com/apex/OmniScriptUniversalPage?
layout=newport&AccountId=%accId%&OmniScriptInstanceId=%instanceId
%&scriptMode=vertical&loadWithPage=false&LanguageCode=%LanguageCode%#/
Thanks,
%SenderName% %Name%
3. In Property Name, enter a property that the FlexCard expects to receive by converting the property to
an HTML attribute format. Three options enable you to pass data into the FlexCard from your
OmniScript. Each data option requires you to pass data as an HTML attribute. For example, if a
FlexCard receives the property recordId, you must enter record-id in the property name field to
pass the property correctly.
AND Set records equal to an object containing a record or an array of records. FlexCards parses over these
records and maps the nodes to FlexCard fields.
records
5. (Optional) Rerender and refresh the FlexCards save state whenever a user navigates to the step by
taking these actions:
a. In the FlexCards Designer, disable OmniScript support.
b. In the OmniScript Designer, open the Custom LWC element and check Standalone Mode. For
information on Standalone Custom LWCs, see Create a Standalone Custom Lightning Web
Component.
6. (Optional) Beginning with Summer '21, provide Selectable Items in your OmniScript using FlexCards.
See Select Items on a FlexCard to Update an OmniScript.
7. Save and Activate the Script.
8. Preview the OmniScript.
NOTE
OmniScripts using custom Lightning web components must be active to preview the
OmniScript.
See Also
• Pass Data from an LWC OmniScript to an Embedded FlexCard
• Pass the RecordId from an OmniScript to Run a Query on a FlexCard
Download the HTML, CSS, and ReadMe files for every available Lightning web component in one file.
LWC Description
OmniScript Atomic Element The base component for OmniScript Input elements.
OmniScript Base Action The base component for OmniScript Action elements.
OmniScript Base Element The base component for LWC OmniScript.
OmniScript Group Element The base component for OmniScript Group elements.
Mixin ReadMes
LWC Description
OmniScript Base Mixin Enables custom LWCs that do not override an OmniScript element's LWC to interact with OmniScript
through the Custom LWC element. See Extend the OmniScriptBaseMixin Component.
OmniScript Options Mixin Provides options logic for any LWC in OmniScript.
OmniScript Validation Provides validation options to any LWC in OmniScript.
OmniStudio FlexCards
Build customer-centric, industry-specific UI components and applications on the Salesforce platform with
OmniStudio FlexCards. Display Salesforce object information along with distinct, clickable actions that
change according to the context in which they appear and based on the information that they contain.
Create and design FlexCards with the FlexCard Designer, a declarative tool with a drag interface,
WYSIWYG editing, and graphic user interfaces to style individual elements. See FlexCard Designer.
FlexCards are built with the Lightning Web Components programming model. See OmniStudio Lightning
Web Components.
Creating UI components with FlexCards is all about sourcing the data and displaying and organizing the
returned information in a meaningful way.
Cards
The FlexCard component contains a combination of pertinent information and links to processes within a
specific context based on the data source provided.
By default, a FlexCard loops through records returned from its data source and displays the list of records
in containers called cards. These rendered cards are visible at run time in the FlexCard Designer in
Preview and on an active FlexCard component published on a Lightning or Community page.
An account card, for example, can include unique account information, such as:
• Status
• Priority or service level agreement
• Creation date
• Company logo
• Closing a case
• Opening a new case
• Creating a task
Each action can launch an OmniScript. Depending on the action type, an action can also update an
OmniScript, fire an event, open a web address or web app, display a flyout, or update a field value. See
Add an Action to a FlexCard.
Flyouts
You can design a card to launch an action that when clicked, opens a child card, Custom LWC, or an
OmniScript embedded in a popover or window. A card flyout contains additional information and actions
related to the parent card. See Launch a Flyout from an Action on a FlexCard.
Data Sources
Choose from a number of data source options to retrieve data to display data from a Salesforce object or
API on your FlexCard. For a list of possible data source types, see FlexCards Data Source Reference.
Update the look of each element with the graphic user interfaces available in the Style panel when an
element is clicked. For example, to update the text for a data field, you can enter the name of a font, and
change the text color with a color picker interface. See Style FlexCard Elements.
Make your FlexCard responsive by setting widths for available viewport breakpoints. See Create
Responsive Elements on a FlexCard.
Publish Options
After activating your FlexCard, which generates a Lightning web component to add to a Lightning or
Community page, you can configure publishing options. For example, configure your component's icon, and
where your component is allowed to be published. See Configure Publish Options on a FlexCard.
Deploy FlexCards
After activating a FlexCard, you can add the generated LWC to a Lightning or Community page. See Add a
FlexCard to a Lightning Page. See Add a FlexCard to a Community Page.
Beginning Summer '21, deploy FlexCards off-platform with OmniOut for FlexCards. See OmniOut.
FlexCard Designer
The FlexCard Designer is a declarative tool with a drag interface and WYSIWYG editing that makes it easy
to build user interface (UI) Lightning web components without code. Build interfaces rich in information and
with actions relevant to your customer's context. You can also create the look and feel of your FlexCard by
styling individual elements from graphic user interfaces (GUIs) built into the designer.
Header (1), Canvas (2), Build panel (3), Properties panel (4), Style panel (5), Setup panel (6), Preview (7),
In-Product Help (8), Publish Options (9)
What's Next
Explore the FlexCard Designer. See Get to Know the FlexCard Designer.
Header (1), Canvas (2), Build panel (3), Properties panel (4), Style panel (5), Setup panel (6), Preview (7),
In-Product Help (8), Publish Options (9)
Header (1)
In the Header, view basic metadata about your FlexCard such as Author, Current Version, and Status.
Perform actions related to your FlexCard, such as Preview, Clone, Activate, Export, Add Custom CSS,
create a New Version, and access a list of resources from a Help link. When the FlexCard is active,
Deactivate, and configure Publish Options. Also, download a version of the FlexCard to use on-platform
(within in Salesforce) and off-platform (outside of Salesforce).
Publish Options (9) enables you to configure your generated FlexCard LWC's metadata values, such as
where the component can be published, API version, description, and more. Also add your own custom
component SVG icon to identify your generated LWC in the Experience Builder for Communities and
Lightning App Builder for Lightning pages. See Configure Publish Options on a FlexCard.
Canvas (2)
Build your card by dragging elements from the Build panel into a state on the Canvas. Rearrange, clone,
delete, and adjust the widths of your elements as needed.
Test the responsiveness of your FlexCard with the Viewport Dropdown. See how elements are positioned at
different viewport breakpoints. See View a FlexCard at Different Viewport Breakpoints.
Drag elements from the Build panel onto the Canvas to build the layout of your FlexCard. Drag all available
fields from a configured data source from the Fields list into a State. You can also add states to your
FlexCard, and embed Custom LWCs and reusable child FlexCards. See Add Elements to a FlexCard.
Configure element properties from the Properties panel when an element is selected on the Canvas. For
example, when a Field element is selected, you can update the Label, choose the data field value to
display, select the type of field it is, and more.
Style your FlexCard elements from the Style panel using a GUI that updates the look of elements in real-
time. Configure backgrounds, sizes, borders, padding, margins, height, fonts, and responsiveness. See
Style FlexCard Elements.
For custom design needs, create and apply custom CSS. Create CSS classes with an in-product code
editor with Intellisense features such as code completion, contextual prompts, and a color picker. Apply
custom classes created from the editor or from any style sheet accessible to the FlexCard, or apply inline
CSS styles. See FlexCard Elements Custom CSS.
Save style settings on an element to use on multiple elements on the FlexCard. See Create a Custom Style
for a FlexCard Element.
Add conditional styles based on the value of a data field. See Add Conditional Styles to a FlexCard
Element.
Configure global options from the Setup panel. See Set Up a FlexCard in the FlexCard Designer.
Update your data source. Apply custom permissions to limit access to your FlexCard. Track Custom Data
on elements with tracking enabled.
Enable Multi-Language and OmniScript Support, set Session Variables, create Event Listeners, and
configure Repeat Options.
Preview (7)
(A) Preview your FlexCard in real-time to test its design and functionality. See FlexCard Designer Preview.
(B) Preview how a FlexCard appears on different devices, such as mobile, desktop, and tablet with
the Viewport Dropdown. See View a FlexCard at Different Viewport Breakpoints.
(C) Add Test Parameters to preview your FlexCard with different parameters, such as record Ids, and
pagination limits. See FlexCards Preview 'Add Test Params' Properties.
(D) Debug your FlexCard. View your FlexCard's data JSON with the Data JSON panel. Debug action and
event requests and responses with the Action Debugger. See FlexCard Designer Data JSON. See
FlexCard Designer Action Debugger.
Find context-sensitive help specific to an element or property using the FlexCard Designer's in-product help
feature.
(A) Access in-line information about specific properties by hovering over tooltip icons.
(B) View detailed documentation about an element's or feature's purpose and functionality with slide-out
help trays.
What's Next
Get started building FlexCards with the FlexCard Designer. See Get Started with FlexCards. Then, Create
a New FlexCard.
• FlexCard Designer
Use a drag UI with WYSIWYG editing to build dynamic, context-aware user interfaces.
• Download FlexCard Sample DataPacks
Download sample DataPacks with configured FlexCard elements and feature implementations.
• FlexCards Context Variables
Provide context to data sources, actions, and other components on your FlexCard with global and local
context variables.
• FlexCard Setup Reference
Configure optional settings for your FlexCard in the Setup panel of the FlexCard Designer, such as
updating a data source, creating an event listener, adding session variables, and more.
• FlexCards Data Source Reference
Configure a data source on your FlexCard to retrieve data from a Salesforce object or an external
database.
• FlexCards Elements Reference
Add elements such as actions, states, data fields, and more to build your FlexCard.
• FlexCards Actions Reference
Add an action to your FlexCard to launch or update an OmniScript, navigate to a web page or
application, display a flyout, fire an event, and more.
• Style FlexCard Elements
Configure the look and feel of your FlexCard by styling individual elements and entire states.
• FlexCard Designer Preview
Preview your FlexCard before publishing. Add test parameters. Use the Data JSON and Action Debugger
panels to debug.
• Configure Publish Options on a FlexCard
Define metadata values and update the SVG resource for your generated LWC from the FlexCard
Designer
• FlexCards Troubleshooting Considerations
Review troubleshooting tips for FlexCards.
• Add and configure elements, such as fields, states, actions, and other components on a FlexCard. See
Add Elements to a FlexCard.
• Add styles for each element such as background color and image, border, padding, and margin. Set an
element's height. Update the look of supported text fields by adding custom classes. Create and apply
custom classes and inline styles. And more. See Style FlexCard Elements.
• Enable an element's width to change when the viewport updates. See Create Responsive Elements on a
FlexCard.
Preview FlexCard
Preview your FlexCard's appearance and functionality before publishing it to a Lightning or Community
page. See Preview a FlexCard.
Activate FlexCard
Activate your FlexCard to publish it to a Lightning or Community page. See Activate a FlexCard.
What's Next
Deploy your generated FlexCard LWC from the Lightning App Builder to a Lightning page or from the
Experience Builder to a Community page. See Add a FlexCard to a Lightning Page. See Add a FlexCard to
a Community Page.
NOTE
You cannot change the theme once set. You will need to clone the FlexCard to change
the theme.
NOTE
You cannot change the author once set. You will need to clone the FlexCard to
change the author.
5. (Optional) Update the Title. The title is used to find your generated FlexCard LWC after activation in
the Lightning App Builder and Community Builder.
6. (Optional) Enable Is Child Card to embed the FlexCard inside another FlexCard. See Embed a Child
FlexCard Inside a FlexCard.
7. (Optional) Enter the Description visible on the FlexCards home page.
8. Click Next.
What's Next
Configure additional options. See FlexCard Setup Reference.
See Also
• Add Elements to a FlexCard
• Preview a FlexCard
• Activate a FlexCard
• Configure Publish Options on a FlexCard
• Add a FlexCard to a Lightning Page
• Add a FlexCard to a Community Page
1. In the FlexCard Designer, drag the Action element from the Build panel into a state on the canvas.
2. (Optional) From the Properties panel, update the element name in the Element Name field.
3. Select the type of action to execute from the Action Type dropdown. For example, to launch an
OmniScript, select OmniScript. See FlexCards Actions Reference.
4. To configure settings specific to the type of action selected, see FlexCards Action Properties.
5. To disable tracking events through OmniAnalytics, unselect Enable Tracking.
6. (Optional) To update the visible label for the action, enter a new label in the Label field.
NOTE
Beginning Summer '21, Label supports concatenated strings. Combine plain text and
supported merge fields. For example, Update {AccountName}.
7. (Optional) To update the action icon, from the Icon field, perform one of these tasks:
• Enter the name of the icon, such as utility:arrowdown. See Salesforce Lightning Design
System.
• Click the search icon in the input field, and perform one of the following tasks:
• Click to select an icon from the list available, and click Save.
• Search for an icon in the search field, click an icon to select it, and click Save.
8. (Optional) To show an icon without text, check Show Only Icon.
9. (Optional) To show a label without an icon, check Hide Icon.
10. (Optional) To display the action link as a button:
a. Check Display As Button.
b. Select a style option from the Variant dropdown. For a description of each variant, see Variations.
11. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
What's Next
(Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
1. From the FlexCard Designer, select a supported element on the canvas to add an action to. Or, drag a
supported element from the Build panel into a state on the canvas
2. From the Properties panel, click + Add Action.
3. Select the type of action to execute from the Action Type dropdown. For example, to launch an
OmniScript, select OmniScript. See FlexCards Actions Reference.
4. To configure settings specific to the type of action selected, see FlexCards Action Properties.
5. Click Save.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• FlexCards Action Properties
• FlexCards Action Style Properties
NOTE
Beginning Summer '21, the Action element supports concatenated strings. Combine plain
text and supported merge fields, such as {Parent.prodType} > {Name}, in the
following fields:
Card Action
These properties are unique to the Card Action.
Property Description
Selectable Field Select a data field with a boolean (true or false) value, that when true, preselects the card record.
Selectable Mode Select whether a user can select a Single record or Multiple records.
Selected Cards List Name Enter the name of the array to add or remove selected cards from.
Type Select the type of action to launch.
Type Description
Reload Reloads the FlexCard.
Remove Removes a card from the FlexCard component. For example, use for notifications and alerts.
Select Cards Enables users to update an OmniScript from a list of selectable items on a FlexCard. When the user clicks a
Select Cards action, it fires the selectcards_ event and the selected card is added or removed from an array.
Set Values Updates field values.
Update Data Source Changes the data source, or updates parameters of an existing data source.
Event Action
These properties are unique to the Event Action. See Trigger a Custom Event from an Action on a
FlexCard. See Trigger a Pubsub Event from an Action on a FlexCard.
Property Description
Bubbles Check to enable the event to bubble up through the DOM.
Channel Name Enter a channel name for the pubsub event.
Composed Check to enable the event to pass through the shadow boundary.
Event Name Enter the name of the custom event.
Event Type Select an event type.
Input Parameters Enter parameters to pass contextual data to the event as key/value pairs.
Flyout Action
These properties are unique to the Flyout Action. See Launch a Flyout from an Action on a FlexCard.
Property Description
Attributes Set attributes available from the flyout's component. For example, if an OmniScript requires a ContextId
be set, enter ContextId as Key and {recordId} as Value.
Data Node To pass parent data to the Child FlexCard, select a data node.
Flyout Select the component to display in the flyout.
Flyout Type Select the type of component to display.
Layout Type Select a theme for the flyout.
Property Description
Open Flyout In Select the flyout's container type. When enabling a flyout as a clickable event on an element such as a
Block or Menu element, this feature defaults to modal and is disabled because popover positioning
cannot be controlled.
Preload Flyout Enable the Flyout component to load before it is clicked.
Component
Reset Component On Resets the component to its on load state when the flyout closes.
Close
Navigate Action
These properties are unique to the Navigate Action. See Navigate from a FlexCard with the Navigate
Action. See PageReference Types.
OmniScript Action
These properties are unique to the OmniScript Action. See Launch an OmniScript from a FlexCard.
Property Description
Context ID Select a data field to use as the ContextId, such as {'AccountId'}.
Input Parameters Enter parameters to pass contextual data to the action as key/value pairs.
Layout Type Select a theme for the layout.
OmniScript Select the OmniScript to launch.
Open Target In Select whether to open the target page in the current window or a new tab/window.
Visualforce Page Override the default Visualforce Page that displays the OmniScript.
Property Description
Input Parameters Enter the OmniScript data fields to update.
Parent Node Point to a specific data node in the OmniScript JSON to update. Select from the merge fields available from the
data source or enter a data node manually.
NOTE
To create an email link, see Create an Email Link from a FlexCard Navigation Action.
What's Next
To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
What's Next
To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
CAUTION
When embedding a component, confirm that it isn’t called multiple times. See Fix Cyclic
Redundancy When Embedding FlexCard Components.
NOTE
The component must be active to select it from the list of available components.
5. (Optional) To use the data source from the parent FlexCard, click into Data Node and select what data
to send to the child.
Node Description
{records} Send all data.
{records[#]} Send all the data of a specific record. {records[0]} = first record. {records[1]} = second record. And so on.
{record} Send just the current record's data, such as when Repeat Records is disabled in the Setup panel or only
one record is requested from a query.
{record.FieldName} Send the record object that belongs to the State. For example, if {record.Product} is an object or array
with additional data, select it. But, if you want to send a data field, use the Attributes property.
{record.attributes} Send all Attributes for the current record.
6. (Optional) To set attributes available from the flyout's component to use on the child component, click +
Add New next to Attributes.
a. Enter the name of an attribute in the Key field, such as ContextId from an OmniScript
component whose ConetxtId must be passed to the FlexCard.
b. Click into the Value field, and select a merge field, such as {Id}. You can also enter a supported
context variable, or plain text.
c. To access the attribute in the child component, use the {Parent} context variable in supported
fields. For example, enter {Parent.Id} in the child component's data source Input Map Value
field to use the parent's Account Id as the child's contextId.
NOTE
Beginning with Summer '21, Value supports concatenated strings. Combine plain text
and supported merge fields. For example, {Parent.type} > {Name}.
7. (Optional) Select whether to display the flyout as a window or popover from the Open Flyout In
dropdown.
NOTE
When enabling a flyout as a clickable event on an element, this feature defaults to
Modal and is disabled because popover positioning can’t be controlled.
8. (Optional) Beginning with Summer '21, to reset the component to its load state when the flyout closes,
select Reset Component On Close.
9. (Optional) Beginning with Summer '21, enable the component to load before it's clicked by checking
Preload Flyout Component.
10. (Optional) To configure other options common among all Action properties, see FlexCards Action
Properties.
What's Next
To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
8. (Optional) If you selected an LWC OmniScript, from Console Tab Icon, select an icon to display in the
subtab of a console after the OmniScript Action link is clicked. For example, select
standard:account for an OmniScript that updates account information.
9. (Optional) To pass contextual data as a key/value pair, click + Add New next to Input Parameters,
and perform the following tasks:
a. Enter a variable name in the Key field. Prefix your variable name with c__, such as c__name.
b. Enter the variable value in the Value field.
10. (Optional) Select whether to open the OmniScript in the current tab or a new tab, select from the Open
Target In dropdown.
11. (Optional) To configure other options common among all Action properties, see FlexCards Action
Properties.
What's Next
To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
1. Add and configure the OmniScript Action element on a FlexCard. See Launch an OmniScript from a
FlexCard.
2. Add the FlexCard to a Lightning page. See Add a FlexCard to a Lightning Page.
See Also
1. Create a community page with the URL /lwcos. Enter any name as the Community page name. See
Creating Custom Pages with Community Builder.
2. Add a Vlocity LWC OmniScript Wrapper component to the /lwcos Community page. See Launch
an OmniScript with LWC OmniScript Wrapper.
3. Add the card to the Community page that launches the action, such as the Home page or Record
Detail page. See Add a FlexCard to a Community Page.
Create the FlexCard that displays the customer's available devices. Add a Toggle element that lets them
select a device. Configure an Update OmniScript action on the Toggle element to pass the value of the
action (true or false) to the OmniScript.
Then, build the OmniScript that walks a customer through the process of selecting the device and
suspension date range, before submitting the request.
What's Next
Embed the FlexCard inside an LWC OmniScript. See Embed FlexCards in an OmniScript.
See Also
• Preview a FlexCard
The sample DataPack demonstrates how to prefill data in an OmniScript when a user clicks an Update
OmniScript action from a FlexCard embedded in the OmniScript. The FlexCard action element passes data
to the OmniScript.
What's Included
• A demoPrefillUpdateOSActionFlexCard FlexCard with an Update OmniScript action that passes data
source values for Id and Name to an OmniScript in a data node.
• A demoPrefillUpdateOmniScriptOS LWC OmniScript with the embedded FlexCard and a text block
with merge fields to display the incoming data.
NOTE
Download the DataPack for OmniStudio for Vlocity (formerly Digital Interaction
Platform) for an org with a Vlocity Health and Insurance, Communication, Media and
Energy, or Public Sector package installed.
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio
for Vlocity objects.
NOTE
Download the OmniStudio DataPack for an org with the OmniStudio package
installed.
If you import DataPacks with OmniStudio for Vlocity (formerly Digital Interaction
Platform) objects into an org with the OmniStudio package, the objects are converted
into OmniStudio objects.
See Also
Use the Select Cards action to enable users to add and remove objects from a list. For example, add and
remove multiple items to and from a cart, or select and unselect one or more cases from a list.
Required Versions
Available beginning Summer '21.
1. In FlexCard Designer, drag an Action element from the Build panel into a state.
NOTE
To use a toggle element to select items, drag the Toggle element into a state and add
an action to the element. See Add a Click Event to a FlexCard Element.
NOTE
When creating an event listener to listen for the selectcards_ event, the list name
must be all lowercase, alphanumeric, and not have spaces, such as
selectedcases. See step 7.
5. In Selectable Mode, select whether users can select a Single card record or Multiple card records.
6. (Optional) To preselect a card record, click into the Selectable Field and select a data field. The data
field must have a boolean value of true or false. When the value of that data field is true, then that card
record is selected by default.
For example, let's say you want to send a list of escalated case records to an OmniScript. To preselect
escalated Cases, enter the IsEscalated case in the Selectable Field. In preview, you see that all
card records where IsEscalated is true is selected.
7. To create the custom event listener that executes the Update OmniScript action that passes the
selected card records array to the OmniScript, perform these tasks:
a. In Setup panel, click + Add New next to Event Listener, and select Custom as the Event Type.
See Add an Event Listener to a FlexCard.
b. In the Event Name field, enter the event selectcards_ followed by the name entered in Selected
Cards List Name. For example, selectcards_selectectedcaseslist.
c. Select Update OmniScript as the Action Type. See Update an OmniScript from a FlexCard.
d. In the Input Parameters section, click + Add New. In the Key field, enter a name of the data node
to pass to the OmniScript. For example, selected.
e. In Value, enter the name entered in Selected Cards List Name as a merge field. For example,
{selectedcaseslist}.
8. (Optional) To configure other options common among all Action properties, see FlexCards Action
Properties.
9. In the Setup panel, select OmniScript Support.
10. To preview and test your action before publishing the FlexCard, click the Preview tab.
When you click the select card action in on the canvas, look for isSelected: true under _flex in the
cards object of the Data JSON.
What's Next
Style your action element. See FlexCards Action Style Properties.
For example, add an action on an embedded child FlexCard that, when clicked, updates a Field element
value on the parent FlexCard. Or, add an action on an Image element that when clicked, updates a merge
field value in a Text element.
IMPORTANT
Don’t use these reserved names: reload, updatedatasource, remove.
5. (Optional) To enable the event to pass through the shadow DOM boundary, select Compose. See
Configure Event Propagation.
6. (Optional) To enable the event to bubble up through the DOM, select Bubbles. See Configure Event
Propagation.
7. (Optional) To pass contextual data as a key/value pair, click + Add New next to Input Parameters,
and perform the following tasks:
a. Enter a variable name in the Key field.
b. Enter the variable value in the Value field.
NOTE
Beginning Summer '21, you can pass a session variable as a value using the
{Session.var} context variable. See Add Session Variables to a FlexCard.
8. (Optional) To configure other options common among all Action properties, see FlexCards Action
Properties.
9. Configure the event listener that performs an action when the event is fired. See Add an Event Listener
to a FlexCard.
The sample DataPack demonstrates how to update a data field on a parent FlexCard from an Action
element in an embedded child FlexCard.
What's Included
NOTE
Activate the child FlexCard to see it in the parent.
Import DataPack
NOTE
Download the DataPack for OmniStudio for Vlocity (formerly Digital Interaction
Platform) for an org with a Vlocity Health and Insurance, Communication, Media and
Energy, or Public Sector package installed.
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio
for Vlocity objects.
NOTE
Download the OmniStudio DataPack for an org with the OmniStudio package
installed.
If you import DataPacks with OmniStudio for Vlocity (formerly Digital Interaction
Platform) objects into an org with the OmniStudio package, the objects are converted
into OmniStudio objects.
See Also
update the product information and has actions that send events. Your Product List FlexCard displays
product information and has an event listener that listens for actions performed on the Filter Card. The
Filter FlexCard displays the filters, and has an Apply button that when clicked sends an event.
When a user selects a filter, such as <$2000, and clicks the Apply button from the Filter FlexCard, only
products that cost less than $2000 are visible in the Product List FlexCard.
IMPORTANT
Don’t use these reserved names: reload, updatedatasource, remove.
6. (Optional) To pass contextual data as a key/value pair, click + Add New next to Input Parameters,
and perform the following tasks:
a. Enter a variable name in the Key field.
b. Enter the variable value in the Value field.
7. (Optional) To configure other options common among all Action properties, see FlexCards Action
Properties.
8. Configure the event listener that performs an action when the event is fired. See Add an Event Listener
to a FlexCard.
The sample DataPack demonstrates how to trigger events that update the values of data fields.
What's Included
• A demoPubSubEvent FlexCard with the following elements and features:
• An Action element configured to trigger a Pubsub Event named setvalue that passes a new value for
the Field element to the FlexCard.
• An Icon element configured to trigger a Pubsub Event named setvalue that passes a new value for
the Field element to the FlexCard.
• An Event Listener configured in the Setup panel that listens for the setvalue event and updates the
Field value based on parameters passed from the event.
NOTE
The Record Index is set to 1 so that only the Field value in the second record
returned from the custom data source is updated.
NOTE
Download the DataPack for OmniStudio for Vlocity (formerly Digital Interaction
Platform) for an org with a Vlocity Health and Insurance, Communication, Media and
Energy, or Public Sector package installed.
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio
for Vlocity objects.
NOTE
Download the OmniStudio DataPack for an org with the OmniStudio package
installed.
If you import DataPacks with OmniStudio for Vlocity (formerly Digital Interaction
Platform) objects into an org with the OmniStudio package, the objects are converted
into OmniStudio objects.
See Also
IMPORTANT
If you select SOQL Query and SOSL Search, you can’t change the data source for
security reasons. However, you can update the parameters.
What's Next
To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
What's Next
To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
What's Next
To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
What's Next
To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
3. To add an element to a state from the Build panel, perform one of these tasks:
a. To add an element from a search:
i. In the search field, enter the name of an element, such as Action, or a Field element, such as
Email.
ii. Drag the element from search results into a state on the canvas.
b. To add an element from the lists of available elements:
• To add data fields, perform one of these tasks:
• Click Fields, to reveal a list of data fields available from the data source, and drag one or
more fields into a state on the canvas.
• From the Elements list, drag the Field element into a state onto the canvas.
• To add other components such as an action, data table, menu, icon, and a custom LWC, drag
the element from the Elements list into a state on the canvas. See FlexCards Elements
Reference.
NOTE
When you drag an element next to another element, it takes up the remaining with of
the container. For example, if you drag an Icon element next to a Field element whose
width is 10 parts of the 12-column grid, the Icon element takes up the remaining 2
columns. See FlexCards Element Responsiveness.
4. To configure the element, click the element to update its properties from the Properties panel.
TIP
To easily distinguish between elements, update the Element Name. When you hover
over or click an element on the canvas, the element name is viewable in a blue tab
with white text.
Beginning with the Summer '21 release, hover over the element to see its name.
5. (Optional) To adjust the width of the element, hover over the square box on the right border until your
mouse pointer icon becomes a drag icon. Click and slide the square box right or left to increase or
decrease the width.
NOTE
To make the width of the element responsive to the viewport, see Create Responsive
Elements on a FlexCard.
6. (Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
7. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
8. (Optional) To add another state, drag the State element from the Elements list of the Build panel onto
the canvas, and follow steps 4 through 7. See Add a State to a FlexCard.
NOTE
Each FlexCard has a default state that can’t be deleted.
9. To rearrange, duplicate, or delete elements, see Arrange, Duplicate, and Remove Elements on a
FlexCard.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• Activate a FlexCard
• Define Metadata Values from the FlexCard Designer
1. From the FlexCard Designer, drag a Block element from the Build panel into a state on the canvas.
2. (Optional) From the Properties panel, update the element name in the Element Name field.
3. (Optional) To enable the ability to collapse the block, check Collapsible.
• (Optional) To display a visible label for the collapsible block element, enter text in the Label field.
NOTE
Beginning Summer '21, Label supports concatenated strings. Combine plain text
and supported merge fields. For example, Update {AccountName}.
NOTE
The Element Name of any new element added to a block is prepended with the word
Block until you update the name in the Properties panel.
2. To add an element into a block element from a state, click, hold, and drag the element into the block
element.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• FlexCards Block Properties
See Also
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. Drag a Chart element from the Build panel into a state on the canvas.
3. (Optional) From the Properties panel, update the element name in the Element Name field.
4. (Optional) To display a title at the top of the chart, which is hidden by default, update these properties:
• In the Title field, enter a title.
• Deselect Hide Header.
5. From the Type dropdown, select the type of chart to display.
6. (Optional) To adjust your chart's proportions, update the Aspect Ratio. See FlexCard Chart Element
Aspect Ratio.
7. (Optional) To manually set the height, overriding the Aspect Ratio, enter a number in the Chart
Height field. The height is in pixels, such as 300px. You can enter just the number without the 'px'
suffix, such as 300.
NOTE
This feature is visible when the Maintain Aspect Ratio feature is disabled.
8. From the Label Node dropdown, select the field whose values are used to categorize the data, such
as Name to display Account names.
9. From the Value Node dropdown, select the field whose values are used to populate the chart, such as
AnnualRevenue.
IMPORTANT
The values must be numbers and have the same count as the field selected in Label
Node.
10. Select the color scheme for your chart from the Color Palette dropdown.
NOTE
Each color palette has up to 6 unique colors. If there are more than 6 values in your
chart, the colors repeat from the beginning.
11. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
12. (Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• FlexCards Chart Properties
The Aspect Ratio is the chart's width to height ratio. By default, the aspect ratio is 1, such as 1:1. The chart
width is always the maximum width available given the number of columns it spans on the 12-column grid
of the canvas in the designer. The height is proportionate to the chart's width. Adjusting the ratio adjusts the
height.
To make the chart shorter, given the width of the element, increase the number of the Aspect Ratio. For
example, if the ratio is at the default 1, enter 2 to make the height about half the default height. In other
words, if the original width and height of a 7 column Chart element are 600px and 300px, and the aspect
ratio is 2 then the height is 150px, and the width remains the same.
To make the chart taller, given the width of the element, decrease the number of the Aspect Ratio. For
example, if the ratio is at the default 1, decrease it to .5 to make the height twice the default height. In other
words, if the original width and height of a 7 column Chart element are 600px and 300px, and the aspect
ratio is .5, the height is 600px and the width remains the same.
To set fixed proportions, you can enable the Maintain Aspect Ratio feature. When this feature is enabled,
given the width, the height becomes exactly X times the width. For example, if the Aspect Ratio is 1, the
width and height are exactly the same so that your chart is a square. If the Aspect Ratio is 2, the height is
half of the width. In other words, if the width of a 7-column Chart element is 600px, and the aspect ratio is 2,
then the height is 300px.
To override the Aspect Ratio, manually set the height for your chart with the Chart Height feature. This
feature is visible when Maintain Aspect Ratio is disabled. The height is in pixels, such as 300px.
Here is a summary of how width and height are determined with each feature:
See Also
See Also
CAUTION
When embedding a component, confirm that it isn’t called multiple times. See Fix Cyclic
Redundancy When Embedding FlexCard Components.
1. In the FlexCard Designer, drag the FlexCard element from the Build panel into a state on the canvas.
2. (Optional) From the Properties panel, update the element name in the Element Name field.
3. Click into the Card Name field, and select a reusable FlexCard to embed. That is, a FlexCard where Is
Child Card is enabled.
IMPORTANT
If your parent FlexCard is OmniScript Support enabled, only an OmniScript
Support enabled child FlexCard can be embedded. See Enable OmniScript Support
on a FlexCard.
4. (Optional) Beginning Summer '21, if your FlexCard is a child FlexCard with hierarchical data, to add it
to itself recursively, select Is Recursive. See Add a Child FlexCard to Itself Recursively.
5. (Optional) To use the data source from the parent FlexCard instead of the child's data source, perform
the following tasks:
a. Confirm that the fields you want to populate in the child FlexCard are also available in the parent
FlexCard's datasource.
For example, if your child FlexCard displays Case information such as Status and Priority, your
parent data source must have these same fields available to send to the child.
b. Click into the Data Node field and select a data set to pass to the child FlexCard.
Node Description
{records} Send all data.
{records[#]} Send all the data of a specific record. {records[0]} = first record. {records[1]} = second record. And
so on.
{record} Send just the current record's data, such as when Repeat Records is disabled in the Setup panel
or only one record is requested from a query.
{record.FieldName} Send the record object that belongs to the State. For example, if {record.Product} is an object or
array with additional data, select it. But, if you want to send a data field, use the Attributes
property.
{record.attributes} Send all Attributes for the current record.
In your child FlexCard, uncheck the Repeat Records property in the Setup panel so that only one
datatable displays. Then, drag the Datatable element onto the canvas from the Build panel. To see how
the datatable looks with real data, configure the datasource to get Case information. Activate the child
FlexCard.
In the parent FlexCard, configure the datasource to get case basic Account information and information
from all cases associated with the account. For example:
[
{
"PrimaryContactEmail": "[email protected]",
"Revenue": 139000000,
"Website": "http://edgecomm.com",
"Phone": "(512) 757-6000",
"Name": "Edge Communications",
"Id": "0013g00000AeI9fAAF",
"Cases": [
{
"Type": "Mechanical",
"CaseId": "5003g000007WQHRAA4",
"Created": "2020-11-23T20:51:20.000Z",
"Priority": "High",
"Status": "Escalated",
"Subject": "The watchamacallit is too high"
},
{
"Type": "Structural",
"CaseId": "5003g000007WQHQAA4",
"Created": "2020-11-23T20:50:32.000Z",
"Priority": "Medium",
"Status": "New",
"Subject": "The doodat wasn't properly set up",
"CaseId": "5003g000007WQHQAA4"
}
]
}
]
Add the FlexCard element onto the canvas. From FlexChild Name, select the activated child. In Data
Node, select {records[0].Cases}.
The child datasource is ignored. The parent datasource populates the child FlexCard datatable.
6. (Optional) To pass attributes from the parent FlexCard to a child FlexCard, in the Attributes section:
a. Click + Add New.
b. In the Attribute field, enter a name for the attribute to pass, such as contactId.
c. Click into the Value field and select a merge field, such as {contactId}.You can also enter a
supported context variable, or plain text.
NOTE
Beginning Summer '21, pass concatenated strings. Combine plain text and
supported merge fields. For example, pass a breadcrumbs path like
{Parent.parentPath}>{Parent.type}>{Name}.
d. Open the child FlexCard selected in the FlexCard Name field, and enter the
{Parent.attribute} context variable in a supported field, such as {Parent.contactId}.
In the child FlexCard, use the SQL Query datasource to get basic contact information. For
example:
Select
Id,Name,Email,Phone,MailingStreet,MailingCity,MailingState,MailingPostal
Code,MailingCountry
from Contact where Id = '{Parent.contactId}'
In the parent FlexCard, confirgure the datasource to get basic account information, including the
primary Contact Id.
Then, pass the primary Contact Id as an Attribute to the child FlexCard, where Attribute =
contactId and Value = {namespace__PrimaryContactId__c}.
7. (Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
NOTE
If your child FlexCard displays multiple records and you want to show them side by
side instead of stacked, see Display Records Side-By-Side on a FlexCard.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• FlexCards Child FlexCard Properties
• Download a Sample Child FlexCard DataPack
• ???
For example, let's say your hierarchical data JSON has a products data field that lists products within a
product. You can display the products, their child products, and grand-child products by embedding the
child FlexCard once inside itself, and passing the products data field to itself. The Is Recursive features
loops through each products node and displays the product information based on the elements added to
the FlexCard. See the example in Step 5 on this page.
Required Versions
Available beginning Summer '21.
1. From the OmniStudio FlexCards home tab, create a child FlexCard. See Embed a Child FlexCard
Inside a FlexCard.
2. Add data fields and other elements to the child FlexCard. See Add Elements to a FlexCard.
3. From the Build panel, drag a FlexCard element into a state on the canvas.
4. From the Properties panel, select Is Recursive.
5. Pass data to the children:
• To pass specific attributes, follow these tasks:
a. In the Attribute field, enter a name for the attribute, such as AccountId.
b. In the Value field, select a data merge field, such as {Id}
Child FlexCard recursively displays the records of Accounts whose Parent Account Id is
{Parent.AccountId}.
• To return objects within a specific data set from the data source, enter the repeating child node in the
Data Node field. For example, if your data source has a similar JSON structure as seen in this code
sample, enter {record.Products} to display a card for each Products object.
[
{
"Id": "5123",
"Name": "Exit Communications",
"Account Number": "QHT123456789",
"Phone": "415-987-6543",
"Website": "http://www.exitcomm.org",
"Contact": "Melrose Oduke",
"Contact Phone": "415-333-1234",
"Products": [
{
"Id": "1",
"Name": "Product1",
"Products": [
{
"Id": "1_1",
"Name": "Product1_1"
},
{
"Id": "1_2",
"Name": "Product1_2",
"Products": [
{
"Id": "2",
"Name": "Product2",
"Products": [
{
"Id": "2_1",
"Name": "Product2_1"
},
{
"Id": "2_1_2",
"Name": "Product2_1_2"
}
]
}
]
}
]
}
]
}
]
Child FlexCard recursively displays Product information from the Products node of its data source.
6. (Optional) To conditionally show the recursive child FlexCard, click +Add New next to Conditions in
the Properties panel. See Add Conditions to a FlexCard Element.
NOTE
Conditions applied to a recursive child FlexCard, apply to all recursively repeating
records. If one record condition returns false, nested records don't show.
IMPORTANT
Activate the child FlexCard to embed it into a parent FlexCard.
See Also
What's Included
The demoEmbedChildCFCpassAttribute child FlexCard in the DataPack includes the following features:
• A list of Contacts based on the Account Id of the parent FlexCard it's embedded into.
• A data source that uses the {Parent.AccountId} context variable as the context Id to get the list of
Contacts.
The demoEmbedChildPFCpassRecords parent FlexCard in the DataPack includes the following features:
• The Repeat Records feature is disabled in the Setup panel to use the parent card only as a container for
the child card. See Disable Record Looping on a FlexCard.
• A SOQL Query data source gets a list of an Account's Cases.
• A FlexCard element passes all parent records through the {records} Data Node to the child FlexCard.
The demoEmbedChildFCpassRecords child FlexCard in the DataPack includes the following features:
NOTE
Download the DataPack for OmniStudio for Vlocity (formerly Digital Interaction
Platform) for an org with a Vlocity Health and Insurance, Communication, Media and
Energy, or Public Sector package installed.
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio
for Vlocity objects.
NOTE
Download the OmniStudio DataPack for an org with the OmniStudio package
installed.
If you import DataPacks with OmniStudio for Vlocity (formerly Digital Interaction
Platform) objects into an org with the OmniStudio package, the objects are converted
into OmniStudio objects.
See Also
See Also
For example, if you have a carousel with custom styling and functionality, you can embed it in a FlexCard
state. Then, configure the component's custom attributes, such as thumbnaillimit and mode.
CAUTION
When embedding a component, confirm that it isn’t called multiple times. See Fix Cyclic
Redundancy When Embedding FlexCard Components.
1. In the FlexCard Designer, drag a Custom LWC element from the Build panel into a state on the canvas.
2. (Optional) From the Properties panel, update the element name in the Element Name field.
3. Click into the Custom LWC Name field, and select a custom LWC to embed.
NOTE
The Custom LWC is rendered in Preview only.
NOTE
The names of Custom LWCs created in the FlexCard Designer are appended with cf.
For example, if your Child FlexCard name is AccountCases, the Custom LWC name
is cfAccountCases.
IMPORTANT
The Name of a custom LWC attribute must match the custom LWC attribute's
markup name. For example, the targetType attribute from the NavigateAction
LWC must be written as target-type.
c. Click into the Value field and select a merge field such as {Number}. You can also enter a
supported context variable, such as {Session.number}, or text, such as 5.
NOTE
Beginning Summer '21, pass concatenated strings. Combine plain text and
supported merge fields. For example, pass a breadcrumbs path like
{Parent.parentPath}>{Parent.type}>{Name}.
5. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
6. (Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• FlexCards Custom LWC Properties
See Also
• Extend Vlocity Lightning Web Components
• Add Elements to a FlexCard
• Add Conditions to a FlexCard Element
Configured Datatable
1. In the FlexCard Designer, drag a Datatable element from the Build panel into a state on the canvas.
2. (Optional) From the Properties panel, update the element name in the Element Name field.
3. (Optional) To add an aria-label for accessibility users, enter a name in the Datatable Name field. The
text isn’t visible on screen and only visible to assistive technologies.
4. To update columns, click the pencil icon next to Column to launch the Add DataTable Columns
modal.
• To add an available data field column, click Add Column.
• To delete a data field column, click the trash icon of the data field to remove.
• To update data field column labels, click into a field under Field Label.
• To update the ability to sort a specific data field column, change the value for Is Sortable to false or
true. Is Sortable must be selected under Attributes in the Properties panel.
• To update the ability to search a specific data field, change the value for Is Searchable to true or
false. Is Searchable must be selected under Attributes in the Properties panel.
• To update the type of data for a specific data field column, such as currency, date, number, and so
on, update Type.
• To update the ability to edit the value of a data field, change the value for Is Editable to true or false.
Cell Level Edit must be checked under Attributes in the Properties panel.
• To update the ability for a user to hide or show specific data field columns, change the value for Is
User Selectable to true or false. User Selectable Column must be checked under Attributes in the
Properties panel.
• To update whether a data field is hidden or shown by default, change the value for Is Visible to true
or false. If this property is set to false and Is User Selectable is set to true, the user can make the
column visible.
5. Click Save to save updates and close modal.
6. (Optional) To add pagination to the data table:
1. To set how many records per page to display, enter a number in the Page Size field.
2. To set a max number of pagination links to display, enter a number in the Page Limit field.
7. (Optional) To enable the ability to delete a row based on a data field value returning as false, enter the
name of the data field column in the Row Delete Dependent Column.
For example, let's say your table is a list of account cases and has a record field IsEscalated whose
value is either true or false. When a record's IsEscalated value is false, a user can delete the record. If
true, the trash icon is disabled and a user cannot delete the record.
IMPORTANT
Row Delete must be enabled, and the column must have a boolean (true or false)
value.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• FlexCards Datatable Properties
Attributes
Property Description
Cell Level Edit Enable support for cell-level inline-editing. Select which columns are editable from the Column property.
Draggable Enable the ability to rearrange rows by dragging them up or down.
Extra Class Enter a class appended to the container of the element. Select from a class defined in the Add Custom
CSS feature of the FlexCard Designer or any style sheet available to the FlexCard.
Fire Event On Delete Enable to fire a delete custom event when a row is deleted.
Confirm
Hide Table Header Enable to hide the table header.
Is Searchable Enable the ability to search all column values. Limit which columns are searchable from the Column
Property.
Is Sortable Enable support for sorting all columns. Limit which columns are sortable from the Column Property.
Page Limit Specify the number of page navigation links to add to pagination. The Page Size property must be
enabled.
Page Size Enable pagination by specifying how many records to display on each page. If using Group By, the
Page Size is determined by the number of groups instead of the number of rows.
Row Delete Enable the ability to delete a row from the FlexCard. The record isn’t deleted in the database.
Property Description
Row Delete Dependent Enable the ability to delete a row based on a data field value returning as false. The field must have a
Column boolean (true or false) value and Row Delete must be enabled.
Row Level Edit Enable support for row-level inline-editing.
Show Confirm Modal Enable to display a confirmation window before a row gets deleted.
Before Row Delete
User Selectable Column Allow users to select which columns are visible. Select specific columns from the Column property.
User Selectable Row Make row selectable by adding a checkbox at the beginning of each row.
Group Attributes
Property Description
Active Groups Enable to expand all groups.
Group By Group table rows by a data field.
Group Order Sort groups in ascending or descending order.
Group Wrapper Class Add a class to the wrapper surrounding each group name.
Hide Extra Column Enable to remove the space below and above the group name.
Sort Across Groups Sorts both the groups and the rows within each group when a column head is clicked. By default, sorting
happens within each group when a column head is clicked. View functionality in Preview.
Column Properties
These properties are visible in the Add DataTable Columns window when you click the Column property.
Property Description
Field Label Update the name of the field column. By default, the field label is the Field Name.
Field Name Select the field column to display.
Is Sortable Select which fields are sortable. Enable Is Sortable under Attributes in the Properties panel.
Is Searchable Select which fields are searchable from the search form. Enable Is Searchable under Attributes in the
Properties panel.
Type Select the type of data the field column displays. For example, if an Account field name is AnnualRevenue,
select Currency.
Is Editable Select which field column a user can edit. Enable Cell Level Edit under Attributes in the Properties panel.
Is User Selectable Select which field columns a user can hide or show. Enable User Selectable Column under Attributes in the
Properties panel.
Is Visible Select which field columns are hidden or visible by default. Use with Is User Selectable to enable users to
display hidden field columns.
See Also
• Download a Sample Datatable DataPack
• Add Elements to a FlexCard
• Add Conditions to a FlexCard Element
The sample DataPack demonstrates how to configure a data table with common settings, such as
searchability, sortability, and more. The data table is automatically populated with the data from the
configured data source once the element is dragged onto the canvas.
What's Included
A FlexCard with a Datatable element with the following features:
NOTE
Download the DataPack for OmniStudio for Vlocity (formerly Digital Interaction
Platform) for an org with a Vlocity Health and Insurance, Communication, Media and
Energy, or Public Sector package installed.
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio
for Vlocity objects.
NOTE
Download the OmniStudio DataPack for an org with the OmniStudio package
installed.
If you import DataPacks with OmniStudio for Vlocity (formerly Digital Interaction
Platform) objects into an org with the OmniStudio package, the objects are converted
into OmniStudio objects.
See Also
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. To add a data field, from the Build panel, perform one of these tasks:
• Click Fields to view the list of available data fields, and drag a data field into a state on the canvas.
• Drag the Field element from the Elements list into a state on the canvas.
3. (Optional) From the Properties panel, update the element name in the Element Name field.
4. (Optional) Enter a visible label in the Label field.
NOTE
Beginning with Summer '21, Label supports concatenated strings. Combine plain text
and supported merge fields. For example, {Label.AccountName}>{Name}.
6. (Optional) To set a data type, such as text and currency, select one from the Field Type dropdown.
The default is Text.
NOTE
To configure additional properties for your selected Field Type, see FlexCards Field
Properties.
IMPORTANT
If you select Date as a Field Type, and the field element is a string that represents a
date, make sure that the date value matches the user locale format. For example, if
your date value comes from a Custom data source such as is [{"DOB" :
"28-03-2015"}, and your locale is en_US, which has an M/D/YYYY format,
because months only go up to 12, the number 28 won’t read properly. The final date is
displayed incorrectly. Instead, if your application doesn’t require localization, update
the format to match the string output, such as DD/MM/YYYY. Or select Text as a
Field Type.
7. If you dragged the Field element from the Build panel, in the Output field, click into the field and select
from the available data fields returned from the data source.
NOTE
Beginning with Summer '21, Output supports concatenated strings, such as {Name}
+ {Id}.
8. (Optional) When Date is selected for Field Type, you can enable Use Absolute Date to prevent
converting the date based on the timezone when Format is updated.
NOTE
When this feature isn’t enabled, the date may display one day ahead or behind, such
as 12/16/2020 or 12/14/2020 instead of 12/15/2020 if the logged-in user's timezone
isn’t the same as the timezone where the record was created.
IMPORTANT
Don’t enable if Date is the Field Type and your field element returns a date as a
string, such as data from a Custom data source that looks like [{"DOB" :
"28-03-2015"}], and doesn’t match the defined format. This throws an error. See
the notice in Step 6.
9. (Optional) If your FlexCard is used on an application accessible across different locales, enable Use
User Locale For Formatting to use the logged-in user's locale to determine the format of your date,
time, and currency.
NOTE
By default, the FlexCard Author's user locale determines the format.
IMPORTANT
Don’t enable if Date is the Field Type and your field element returns a date as a
string, such as data from a Custom data source that looks like [{"DOB" :
"28-03-2015"}], and doesn’t match the defined format. This throws an error. See
the notice in Step 6.
10. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
11. (Optional) To style your element, click Style to open the Style panel, and see FlexCards Field Style
Properties.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
1. From the FlexCard Designer, drag an Icon element from the Build panel into a state on the canvas.
2. (Optional) From the Properties panel, update the element name in the Element Name field.
3. From the Type dropdown, select an icon type.
4. To configure a Custom icon, enter the source of the icon in the Source field.
5. To configure Salesforce SVG icon properties:
a. To select the icon, from the Icon field, perform one of the following tasks:
• Enter the name of the icon, such as utility:arrowdown. See Salesforce Lightning Design
System.
• Click the search icon in the input field, and perform one of the following tasks:
• Click to select an icon from the list available, and click Save.
• Search for an icon in the search field, click an icon to select it, and click Save.
b. (Optional) Select a style variant from the Variant dropdown.
6. (Optional) To update the size of the icon, select a new size from the Size dropdown.
7. To link the icon to an action, click + Add Action. To configure action properties, see FlexCards Action
Properties.
8. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
9. (Optional) To style your icon element, click Style to open the Style panel, and see FlexCards Icon Style
Properties.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• FlexCards Icon Properties
See Also
NOTE
All labels in the Properties panel have Custom Label support.
1. From the FlexCard Designer, drag an Image element from the Build panel into a state on the canvas.
2. (Optional) From the Properties panel, update the element name in the Element Name field.
3. Select the Image Source from one of these options:
• To display an image from an external source, enter the absolute URL of the image
IMPORTANT
If your image doesn't show, add the URL of the image to the CSP Trusted Sites list
in your org. If you're adding your FlexCard to a Community, you must add the URL
to the CSP Trusted Sites list. See Content Security Policy (CSP).
NOTE
Uploaded files are saved to your org's library of documents for reuse.
• To use a file from a library in your Salesforce CRM Content or Salesforce Files:
a. Click the search icon.
b. Select an image from the Select an Image from Content Document dropdown.
c. Click Save.
4. (Optional) To adjust the size of the image relative to the canvas size, select an option from the Size
dropdown.
NOTE
By default, Fit Content is selected, enabling the image to fill the container of the
Image element, or the container of a Block element that it's inside.
On the canvas, adjust the element size to fit your image as needed.
5. For accessibility, in the Alternative Text field, enter text describing the image.
6. (Optional) Enter a Newport, SLDS, or custom CSS class in the Extra Class field.
NOTE
By default, slds-image--card slds-align_absolute-center populate the
field.
NOTE
Beginning with Summer '21, Title supports concatenated strings. Combine plain text
and supported merge fields. For example, {Label.AccountName}>{Name}.
8. (Optional) To style the image caption, enter a class in the Title Class field.
9. (Optional) To launch an action on click of the element, see Add a Click Event to a FlexCard Element.
10. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
11. (Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
See Also
1. From the FlexCard Designer, drag a Menu element into a state on the canvas.
2. (Optional) From the Properties panel, update the element name in the Element Name field.
3. To add an action to the menu, see Add Actions.
4. (Optional) In the Label field, enter the visible label of the menu button.
NOTE
Beginning Summer '21, Label supports concatenated strings. Combine plain text and
supported merge fields. For example, Update {AccountName}.
5. (Optional) To change the default menu button icon, from the Icon field perform one of the following
tasks:
• Enter the name of the icon, such as utility:arrowdown. See Salesforce Lightning Design
System.
• Click the search icon in the input field, and perform one of the following tasks:
• Click to select an icon from the list available, and click Save.
• Search for an icon in the search field, click an icon to select it, and click Save.
6. (Optional) To disable scrolling in the dropdown when there are more than 5 menu items, uncheck
Enable Overflow.
7. (Optional) To change the position of the dropdown menu, select a new position from the Dropdown
Position dropdown. The default is left.
8. (Optional) To change the size of the dropdown menu, select a new size from the Dropdown Size
dropdown.
9. (Optional) To select a style variant, select a new style from the Variant dropdown.
10. (Optional) To change the position of the icon in the menu button relative to the label, select a new
position from the Icon Position dropdown.
11. (Optional) To adjust the size of the icon in the menu button, select a new size from the Icon Size
dropdown.
12. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
13. (Optional) To style your menu element, click Style to open the Style panel, and see FlexCards Menu
Style Properties.
Add Actions
For each new action item, perform these tasks:
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• FlexCards Menu Properties
See Also
• Add Elements to a FlexCard
• Add Conditions to a FlexCard Element
The Text element's rich text editor adds an HTML div for each text section to build the layout of the
element. Add SDLS and NDS classes and other formatting options to each div to style your text.
Add Text
1. In the FlexCard Designer, drag the Text element from the Build panel into a state on the canvas.
2. To update the default text, from the Properties panel, click into the rich text editor to override the
content.
3. (Optional) To add a new block of text, click return to create a new div.
4. (Optional) To add data field values, select from the Fields list in the rich text editor. You can also
manually add the field by entering the field name surrounded by single curly braces, such as {Type}.
5. (Optional) To add custom labels, enter the {Label.customLabelName} merge field anywhere in the rich
text editor. For example, to add a custom label for AccountName, enter {Label.AccountName}. See
Add Custom Labels to Supported Fields on a FlexCard.
6. (Optional) To add a context variable as a merge field, enter it any div. For example, enter
{User.userProfileName} to add the logged-in user's profile name. See FlexCards Context
Variables.
NOTE
The rendered User global context variable is visible at run time only, such as in
Preview or when FlexCard is published to a page.
What's Next
(Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
See Also
See Also
You can also update the data source with the selected value of the Toggle element for all toggle types
except Checkbox Group and Checkbox Group Button.
NOTE
The merge field must have a boolean (true or false) value. If the value is a string,
Disabled returns false.
6. To configure the action triggered on click of the element, see Add an Action below.
7.
8. (Optional) To add a class to the element's container, enter a class in the Extra Class field.
9. (Optional) To add conditions that must be met for the element to display, see Add Conditions to a
FlexCard Element.
10. (Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
NOTE
If the selected Toggle Type is a Checkbox Button, see FlexCards Toggle Style
Properties.
Add an Action
To configure the action that gets triggered when the element is clicked:
NOTE
To pass the value to an action without Input Parameters, such as a Navigate action
whose target is a Web Page, enter the key/value pair as URL parameters. For
example, /apex?keyname={element.value}.
What's Next
Preview your FlexCard. See Preview a FlexCard.
Dual Stateful Diplays an icon button that enables switching between two options. Each state can display
Button a unique icon.
Stateful Button Displays an icon button that enables switching between selected and unselected options
when clicked, and a hover state on focus. Configurable options include adding a label and
unique icons for all three states, and adding a style variant, such as Brand.
Stateful Icon Displays an icon button that enables switching between two options. The same icon
displays for both states.
See Also
The sample DataPack demonstrates how the different toggle types look, and how to update data fields with
new values passed from the elements.
What's Included
The demoToggleDisplayActionUpdate FlexCard in the DataPack includes the following features:
• Displays all Toggle Types. See FlexCard Toggle Element Type Reference.
• Enables and configures the Checkbox Group, Checkbox Button, and Checkbox Toggle elements to
update the data source with new values. See FlexCards Toggle Properties.
• A Checkbox Group Button Toggle element with a Card action that updates a Field value. See Add an
Action to Update Field Values on a FlexCard.
NOTE
Download the DataPack for OmniStudio for Vlocity (formerly Digital Interaction
Platform) for an org with a Vlocity Health and Insurance, Communication, Media and
Energy, or Public Sector package installed.
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio
for Vlocity objects.
NOTE
Download the OmniStudio DataPack for an org with the OmniStudio package
installed.
If you import DataPacks with OmniStudio for Vlocity (formerly Digital Interaction
Platform) objects into an org with the OmniStudio package, the objects are converted
into OmniStudio objects.
See Also
See Also
IMPORTANT
Applied conditions are visible in Preview only.
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. Select an element to add conditions to, such as an Icon element.
3. In the Properties panel, click +Add New next to Conditions.
4. Click + Add Condition.
5. To create basic conditions:
a. Click into Data Field, from the list of data fields, select a data field to filter. For example, select
Status for a Case record.
b. To define the relationship between the data field and a value, select the Operator from the
dropdown, such as =.
c. In the Value field, enter the value to check against. For example, enter Escalated.
NOTE
To check against an empty value, enter undefined as the Value.
d. If adding another condition, click + Add Condition and select AND or OR from the dropdown
between conditions:
• Select AND if all conditions must be met.
For example, Status is Escalated and Priority is High.
NOTE
If there’s only one condition, that condition must be met to display cards.
NOTE
If there’s only one condition, that condition doesn’t need to be met to display
cards.
Property Description
Add Condition Add a condition that must be met based on data field values.
Add Group Create complex expressions by grouping conditions. A group is similar to enclosing a series of tests in parenthesis in
a programming language. For example, to add a condition for high priority cases that are either escalated or have an
account whose revenue is above a certain number, create two condition groups connected by an OR operator, such
as [Priority = High AND IsEscalated = true] OR [Priority = High AND AnnualRevenue >
500000].
Data Field Select the data field to evaluate.
Operator Select the equality or relational operator that evaluates the data field against the value, such as =, !=, >, and so on.
Value Enter the value to check against.
FlexCard States
FlexCards have states. Each state displays a list of fields a data source and one or more actions. You can
also associate a state with one or more flyouts, which shows supplemental data displayed as a modal or
popover.
FlexCard states enable the presentation of different CRM interactions per state. For example, closed cases
have reopen actions, while escalated cases are styled differently have an action to view the case.
FlexCards with different states present different data.
In addition to adding different elements depending on the state, you can also set conditions to determine if,
when, and how data displays on a FlexCard. The FlexCard selects the first state with true conditions to
display. See Add Conditions to a FlexCard State.
You can enable a Blank Card State to display information when no data is returned from the configured
data source.
You can customize each card by its state to display various clickable actions, information, and optional
visual cues. For example:
• If a Case is escalated, the Case FlexCard (via its state) could display with a red border, red text, and an
action, such as View Case.
• A FlexCard for a closed case could display the text as greyed out and an action to Reopen Case.
NOTE
The state Name is for internal use and does not appear on the generated LWC or in
Preview.
4. To add data fields and other elements, see Add Elements to a FlexCard.
5. To add conditions that must be met for the state to display, see Add Conditions to a FlexCard State.
6. (Optional) To style your state, click Style to open the Style panel, and see Style FlexCard Elements.
Clone a State
1. Click the double square plus icon on a selected state. The cloned state appears below the original
state.
2. (Optional) To create a state to display when there are no records available, select the Blank Card
State checkbox. For example, when a data source returns no records from the Policy object, create a
state with an OmniScript action to add a Policy.
3. In the Name field, enter a descriptive name for the state, such as No Data.
NOTE
The Name is for reference only and does not appear on the generated LWC or in
Preview.
4. To add data fields and other elements, see Add Elements to a FlexCard.
5. To add conditions that must be met for the state to display, see Add Conditions to a FlexCard State.
What's Next
Style your element. See Style FlexCard Elements.
See Also
• FlexCard States
• FlexCards State Properties
• Preview a FlexCard
NOTE
When arranging the order of your states on the canvas, place the states in a logical order,
where the first condition is checked against the next, and so on. Typically, states with
complex conditions precede states with simple ones, followed by a state with no
conditions, and then a Blank Card State. The FlexCard selects the first state with true
conditions to display.
For example, the order of the states for the previous example would be:
IMPORTANT
Applied conditions are visible in Preview only.
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. Select a state, and click the pencil icon next Conditions in the Properties panel.
3. Click + Add Condition.
4. To create basic conditions:
a. Click into the Data Field, from the list of data fields, select a data field to filter, such as
DaysToExpiration.
b. To define the relationship between the data field and a value, select an operator from Operator
dropdown, such as <.
c. In the Value field, enter the value to check against the data field, such as 31.
NOTE
Beginning Summer '21, if your FlexCard is a child FlexCard, use the
{Parent.attributeName} to check against the value of an attribute passed to
the child from the parent FlexCard. See FlexCards Context Variables.
d. If adding another condition, click + Add Condition and select AND or OR from the dropdown
between conditions:
• Select AND if all conditions must be met.
• For example, the policy status is purchased AND the expiration date is less than 31 days.
NOTE
If there’s only one condition, that condition must be met to display cards.
NOTE
If there’s only one condition, that condition doesn’t need to be met to display
cards.
See Also
• FlexCard States
• FlexCards State Properties
• Preview a FlexCard
See Also
• FlexCard States
• Add Elements to a FlexCard
Configure a data source when creating a FlexCard by using the configuration wizard. Or, configure a data
source from the Setup panel in the FlexCard Designer. See Set Up a FlexCard in the FlexCard Designer.
NOTE
For optimal flexibility and easier implementation, use an Integration Procedure as a data
source to execute multiple actions in a single server call. See Configure an Integration
Procedure Data Source on a FlexCard.
NOTE
Administrators can enable or disable data sources for an org, profile, and user level. See
Enable and Disable Data Sources.
See Also
• FlexCards Data Source Reference
• FlexCards Data Source Properties
• Embed a Child FlexCard Inside a FlexCard
NOTE
If security is a concern, use a DataRaptor instead of a
SOQL query, because DataRaptors fully support field-level
security.
SOSL Search Uses a Salesforce Object Search Language (SOSL) to construct text-based Configure a SOSL Search
search queries against the search index. Data Source on a FlexCard
Streaming Uses the Salesforce Streaming API to send notifications of general events that Configure a Streaming
Channel aren’t tied to Salesforce data changes. Channel Data Source on a
FlexCard
See Also
• FlexCards Data Source Properties
Property Description
Data Source Type Select the data source type.
Delay(ms) To prevent bundling this data source call with other server requests and to emphasize its priority, enter a delay
time in milliseconds.
Fetch Timeout(ms) Set an appropriate timeout value to enable the application and users to react accordingly to long wait times.
The timeout value controls the time that the framework waits for the designated data source to return a
response.
Input Map When required, pass variables from the FlexCard to the data source.
Key Enter the variable to pass. For example, pass the contextId AccountId.
Order By Order the records by a specified field.
Refresh Interval(ms) Set an interval to enable recursive updates of records. The data source refreshes continuously at the given
interval and checks for changes in data source records. If changes are found, the FlexCard reloads.
Result JSON Path To drill down to a specific dataset enter a JSON path, such as ['Cases']. If your entire JSON is an array,
such as [{ "Cases": [{...},{...}]}], enter the index with the path. For example, enter [0]
['Cases'].
Reverse Order Reverse the order of the returned records.
Test Parameters Preview a FlexCard using real data by adding test variables that the query can use to return live data.
Value Enter the value for the variable. For example, enter a merge field, such as {recordId} or a static value, such
as the alpha-numeric Account Id found in the URL of an Account record page.
Property Description
Asynchronous Calls the Apex class asynchronously using the long-polling method.
Options Map Send additional key/value pairs to the Input Map passed to the remote method. Enter a key in the first field, and its
value in the second field. The value supports merge field syntax such as {Name}.
Poll Interval Specifies the polling interval in milliseconds to check the response status.
Remote Class The Apex remote class to invoke.
Remote Method The Apex method to call.
Property Description
Apex Endpoint The URL of the Apex REST endpoint.
JSON Payload Enter the JSON formatted response.
Method Specifies what type of call to make: GET or POST.
Property Description
Interface Name Select the DataRaptor to fetch the data from.
Property Description
Name Select the Integration Procedure to fetch the data from.
Property Description
Endpoint Enter the relative path to get what you need from the API, such as My_Payroll_System/paystubs?
format=json.
Headers Pass additional information from an HTTP request or response with an HTTP header.
JSON Payload Enter the JSON formatted response.
Method Select a GET or POST method.
Named Credential Select a Named Credential created from Setup > Named Credential in your org.
REST type Select the type of REST endpoint to access.
SDK Properties
These properties are unique to the SDK data source. The SDK data source is available beginning Summer
'21. See FlexCard SDK Data Source.
Property Description
Edit as JSON Add or modify Input Parameters as JSON.
SDK Select from the list of available SDKs to fetch data from.
SDK Method Select the SDK function to provide data for the FlexCard.
Property Description
Query Enter an SOQL expression to search for specific information from an org's Salesforce database. For example, SELECT
Id, FirstName, LastName Email, Phone, Title FROM Contact WHERE Phone != Null.
Property Description
In Select which fields to search in.
Limit to Limit the maximum number of rows to return.
Returning sObject & Fields Select at least one sObject and field to search.
Search For Enter the search term to search for.
Property Description
Channel Enter the URL of the app you created.
Get All Messages Select whether to get all messages from the last 24 hours or get the latest data update.
Operations Select the type of operation to perform. Select Replace to overwrite the FlexCard with new data or Append to
add new data to the FlexCard.
Type Select a Streaming API type.
NOTE
For optimal flexibility and easier implementation, use an Integration Procedure as a data
source to execute multiple actions in a single server call. See Configure an Integration
Procedure Data Source on a FlexCard.
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select DataRaptor, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
DataRaptor from the Data Source Type dropdown.
3. Click into the Interface Name field, and select a DataRaptor Extract.
4. To pass a variable to the DataRaptor, click + Add New next to Input Map.
1. In a new tab, go to the Vlocity DataRaptor Designer tab, open the DataRaptor Extract selected
from the Interface Name, and click the Preview tab to view the Input Parameters.
2. In the Key field of the Input Map, enter the variable representing the ContextId, such as
AccountId.
3. In the Value field of the Input Map, enter {recordId} as the value.
5. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
6. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
• FlexCards Data Source Properties
NOTE
An Integration Procedure doesn’t support the following data sources:
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select Integration Procedures, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
Integration Procedures from the Data Source Type dropdown.
3. Click into the Name field and select an Integration Procedure to use.
4. To pass a variable to the Integration Procedure, click + Add New next to Input Map.
1. In a new tab, go to the Vlocity Integration Procedures tab, open the Integration Procedure selected
from the Name, and click the Preview tab to view the Input Parameters.
2. In the Key field of the Input Map, enter the variable representing the ContextId, such as
AccountId.
3. In the Value field of the Input Map, enter {recordId} as the value.
5. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
6. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
3. (Optional) If the Integration Procedure has other data sources, to return only the dummy data, select
the checkbox next to the Return Only Additional Output label.
4. In your FlexCard's Setup panel, confirm that the Integration Procedure with the dummy data is chosen
in the Name field.
5. To view your dummy data, click Save & Fetch.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
• FlexCards Data Source Properties
NOTE
When mapping fields, only fields in the field picker that have non-null values for the
specific record in the test query are visible. Use a test record that you know has non-null
values for all the fields you want to map. Or use custom fields if the test record doesn't
have the fields that you want to map.
NOTE
For optimal flexibility and easier implementation, use an Integration Procedure as a data
source to execute multiple actions in a single server call. See Configure an Integration
Procedure Data Source on a FlexCard.
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select SOQL Query, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
SOQL Query from the Data Source Type dropdown.
3. Enter a SOQL expression in the Query field.
For example, enter the following to get fields from the Contact object, limit it to 10 and return only
records that have an email address:
SELECT Id, Name, Email, Phone, Title FROM Contact WHERE Email != Null
LIMIT 10
4. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
5. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
• FlexCards Data Source Properties
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select SOSL Search, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
SOSL Search from the Data Source Type dropdown.
3. Enter the search term in the Search For field.
4. Select which fields to search in from the In dropdown.
5. From the Returning sObject & Fields section, select at least one sObject to search:
a. Click into the sObject field and select an object, such as Account.
b. Select one or more data fields from the Field dropdown.
c. (Optional) To add additional objects and fields, click + Add sObject.
6. (Optional) To limit the maximum number of rows to return, enter a number in the Limit to field.
7. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
8. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
• FlexCards Data Source Properties
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select Custom, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
Custom from the Data Source Type dropdown.
3. Enter custom JSON in the Custom JSON field.
},
"Name": "Robert0 Taylor",
"Id": "0033700000TOB6mAAH",
"Phone": "(888) 888-8888",
"AccountId": "00137000007D63JAAS",
"MailingAddress": {
"city": "SF",
"country": "US",
"geocodeAccuracy": null,
"latitude": null,
"longitude": null,
"postalCode": "99999",
"state": "CA",
"street": "50 Santa Rita St"
},
"CreatedDate": "2017-06-13T21:08:25.000+0000"
},
{
"attributes": {
"type": "Contact",
"url": "/services/data/v49.0/sobjects/Contact/
0033700000TNvK0AAL"
},
"Name": "c1",
"Id": "0033700000TNvK0AAL",
"AccountId": "0013700000NVE4tAAH",
"MailingAddress": null,
"CreatedDate": "2017-06-08T20:13:41.000+0000"
},
{
"attributes": {
"type": "Contact",
"url": "/services/data/v49.0/sobjects/Contact/
0033700000TNvKKAA1"
},
"Name": "c2",
"Id": "0033700000TNvKKAA1",
"AccountId": "0013700000NVE4tAAH",
"MailingAddress": null,
"CreatedDate": "2017-06-08T20:13:50.000+0000"
},
{
"attributes": {
"type": "Contact",
"url": "/services/data/v49.0/sobjects/Contact/
0033700000Vs6RzAAJ"
},
"Name": "Smith",
"Id": "0033700000Vs6RzAAJ",
"Phone": "(300) 333-3763",
"AccountId": "001370000098i8mAAA",
"MailingAddress": {
"city": "SF",
"country": "US",
"geocodeAccuracy": null,
"latitude": null,
"longitude": null,
"postalCode": "99999",
"state": "CA",
"street": "50 Fremont St"
},
"CreatedDate": "2017-08-16T20:26:07.000+0000"
}
]
4. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
5. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
• FlexCards Data Source Properties
NOTE
For optimal flexibility and easier implementation, use an Integration Procedure as a data
source to execute multiple actions in a single server call. See Configure an Integration
Procedure Data Source on a FlexCard.
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select Apex Rest, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
Apex Rest from the Data Source Type dropdown.
3. Enter the endpoint URL in the Endpoint field. For example, /services/apexrest/{namespace}/
CardTestApexRestResource/{recordId}
4. Select a method type from the Method dropdown:
• Select GET to requests data specified by the parameters of the URL.
• Select POST to send JSON data.
• Enter the JSON data to send in the JSON Payload field.
NOTE
You can use Context Variables to pass inherited values with either method. See
FlexCards Context Variables.
5. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
6. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
• FlexCards Data Source Properties
NOTE
For optimal flexibility and easier implementation, use an Integration Procedure as a data
source to execute multiple actions in a single server call. See Configure an Integration
Procedure Data Source on a FlexCard.
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select Apex Remote, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
Apex Remote from the Data Source Type dropdown.
3. Enter the name of the remote class in the Remote Class field.
IMPORTANT
The Apex Class must implement the Vlocity Open Interface otherwise an error
message displays.
4. Enter the name of the remote method in the Remote Method field.
For example, you can access the remote Apex method getStories from the remote Apex class
StoryListHandler.
5. (Optional) To pass a variable from the FlexCard to the remote class method, click + Add New next to
Input Map and perform the following tasks:
a. In the Key field, enter the variable to pass. For example, pass the ContextId AccountId.
b. In the Value field, enter the value of the variable. For example, enter a merge field, such as
{recordId} or a static value, such as the alpha-numeric Account Id found in the URL of an
Account record page.
6. (Optional) To send additional key/value pairs to the Input Map passed to the remote method, click
+Add New next to Options Map. Enter a key in the first field, and its value in the second field. The
value supports merge field syntax such as {Name}.
NOTE
By default the NS.IntegrationProcedureService continuation object is set for
you to use asynchronous callouts to make long-running requests from a Visualforce
page to an external Web service and process responses in callback methods. NS
represents your org's Namespace, such as vlocity_ins or vlocity_cmt, as in
vlocity_ins.IntegrationProcedureService.
10. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
NOTE
For optimal flexibility and easier implementation, use an Integration Procedure as a data
source to execute multiple actions in a single server call. See Configure an Integration
Procedure Data Source on a FlexCard.
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select REST, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
REST from the Data Source Type dropdown.
3. Select Named Credential from the REST type dropdown.
4. From the Named Credential dropdown, select a Named Credential created from Setup > Named
Credential in your org.
5. Enter a relative path in the Endpoint field to get what you need from the API, such as
My_Payroll_System/paystubs?format=json.
6. Select a method type from the Method dropdown:
• Select GET to requests data specified by the parameters of the URL.
• Select POST to send JSON data.
• Enter the JSON data to send in the JSON Payload field.
NOTE
You can use Context Variables to pass inherited values with either method. See
FlexCards Context Variables.
7. (Optional) To add any request headers, click + Add New next to Headers to add any request headers.
NOTE
Most third-party APIs expect various headers such as tokens, public keys, and
content-type.
8. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
9. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
• FlexCards Data Source Properties
To configure a REST data source with Named Credentials to authenticate Apex callouts, see Configure a
REST Data Source Using Named Credentials on a FlexCard.
NOTE
For optimal flexibility and easier implementation, use an Integration Procedure as a data
source to execute multiple actions in a single server call. See Configure an Integration
Procedure Data Source on a FlexCard.
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select REST, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
REST from the Data Source Type dropdown.
http://api.weatherstack.com/current?
access_key={Session.weatherAPIkey}&query={BillingCity}
5. Select a method type from the Method dropdown:
• Select GET to requests data specified by the parameters of the URL.
• Select POST to send JSON data.
• Enter the JSON data to send in the JSON Payload field.
NOTE
You can use Context Variables to pass inherited values with either method. See
FlexCards Context Variables.
6. (Optional) To add any request headers, click + Add New next to Headers to add any request headers.
NOTE
Most third-party APIs expect various headers such as tokens, public keys, and
content-type.
7. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
8. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
• FlexCards Data Source Properties
Polling is the most traditional way to get data from a data source that produces the stream of events and
updates. The client makes requests periodically, and the server sends data if there’s a response. In case
there's no data to be sent by the server, an empty response is returned.
Streaming API uses push technology, which is a publish and subscribe model that transfers information that
is initiated from a server to the client. Push technology transfers information that is initiated from a server to
the client. This type of communication is the opposite of polling where a request for information is made
from a client to the server. The main benefits of using the Streaming API are a reduced number of API calls
and improved performance.
For details about the Streaming API, see Use Streaming API and Streaming API Developer Guide.
This illustration shows the difference between Polling and Streaming API:
A PushTopic is a SOQL query that returns a result that notifies listeners of changes to records in a
Salesforce organization. The PushTopic defines a Streaming API channel. For instance, if you want to get
notified when a case is created for a particular type or status or both, use a PushTopic.
The following example code creates a PushTopic that pushes data if a case of type Problem is created:
If you also need Status, you can simply add another condition:
You cannot use GROUP BY or ORDER BY clauses in a PushTopic. See Creating a PushTopic.
For another example, you could create an app that notifies a user any time a new task is created for that
user.
What's Next
Configure a PushTopic data source on your FlexCard. See Configure a PushTopic Data Source on a
FlexCard.
See Also
1. To configure a data source from the FlexCard configuration wizard, navigate to the Select Data
Source Type step, select Streaming API, and click Next.
2. To configure a data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
Streaming API from the Data Source Type dropdown.
3. Select PushTopic from the Type dropdown.
4. In the Channel field, enter the URL of the PushTopic that you created.
5. From the Operation picklist, select Replace or Append.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
The architecture is suitable for large distributed systems because it decouples event producers from event
consumers, simplifying the communication model in connected systems.
For details, see Delivering Custom Notifications with Platform Events in Salesforce Help.
For example, you can create a card that uses a Platform Event as a data source to display the current ink
level for a printer. To see a detailed demo, see End-to-End Example: Printer Supply Automation in
Salesforce Help.
What's Next
Configure a Platform Event data source on your FlexCard. See Configure a Platform Event Data Source on
a FlexCard.
See Also
1. To configure a data source from the FlexCard configuration wizard, navigate to the Select Data
Source Type step, select Streaming API, and click Next.
2. To configure a data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
Streaming API from the Data Source Type dropdown.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
For example, use the Streaming Channel data source for a Chat application for the users in your org.
What's Next
Configure a Streaming Channel data source on your FlexCard. See Configure a Streaming Channel Data
Source on a FlexCard.
See Also
1. To configure a data source from the FlexCard configuration wizard, navigate to the Select Data
Source Type step, select Streaming API, and click Next.
2. To configure a data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
Streaming API from the Data Source Type dropdown.
3. Select Streaming Channel from the Type dropdown.
4. In the Channel field, enter the URL of the app that you created.
5. From the Operation picklist, select Replace or Append.
• Select Replace to overwrite the Card with new data.
• Select Append to add new data to the Card.
6. From the Get All Messages picklist, select True or False.
• Select True to get all data from the last 24 hours.
• Select False to get the latest data update.
7. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
8. To test data source settings, add test variables that the query can use to return live data, see Test Data
Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
1. Create and Upload the Static Resource for the SDK to appear in the FlexCard as a data source option.
See Create the Static Resource for an SDK Data Source on a FlexCard.
2. Configure the SDK data source for your FlexCard in the FlexCard Designer. See Configure an SDK
Data Source on a FlexCard.
1. To upload the SDK file to your org, see Create a new static resource.
If you're a first time user, create a file named OmniStudioActionRegistry with the below JSON schema
and then upload it to static resource.
[{
"type": "SDK",
"name" : "SDK",
"description" : "This JS SDK is intended to be used on client side for
interacting with API",
"value": {
"sdkObject": "datasource",
"sdkPath": "/latest/datasource/datasource.sdk.js",
"staticResourceName": "vlocitysdk",
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
"contextVariables": []
},{
"type": "SDK",
"name" : "UPC JS SDK",
"description" : "This JS SDK is intended to be used on client side for
interacting with V3 API",
"value": {
"sdkObject": "productconsole",
"sdkPath": "/latest/productconsole/productconsole.sdk.js",
"staticResourceName": "vlocityupcsdk",
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
"contextVariables": []
},
{
"type": "SDK",
"name" : "Digitalcommerce JS SDK",
"description" : "This JS SDK is intended to be used on client side for
interacting with V3 API",
"value": {
"sdkObject": "digitalcommerce",
"sdkPath": "/latest/digitalcommerce/digitalcommerce.sdk.js",
"staticResourceName": "vlocitydcsdk",
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
"contextVariables": []
},
{
"type": "SDK",
"name" : "b2b JS SDK",
"description" : "This JS SDK is intended to be used on client side for
interacting with API",
"value": {
"sdkObject": "b2bexpress",
"sdkPath": "/latest/b2bexpress/b2bexpress.sdk.js",
"staticResourceName": "vlocityb2bexpresssdk",
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
"contextVariables": []
},{
"type": "SDK",
"name" : "datasource SDK",
"description" : "This JS SDK is intended to be used on client side for
interacting with API",
"value": {
"sdkObject": "datasource",
"sdkPath": "/latest/datasource/datasource.sdk.js",
"staticResourceName": "vlocitysdk",
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
"contextVariables": []
}
]
You can add new sections to this file with an array of objects. Each section in the Registry.json file
appears as an available option for the SDK in the UI. You can change the value for any of the
parameters in each section, such as type, name, and description. The value parameter has
additional properties such as sdkPath, sdkObject, and staticResourceName. These parameters
and values contain information about the SDK that you want to expose. Once the SDK is loaded, it
exposes the sdkObject as the primary access point to the SDK.
2. Ensure Cache Control is set to Public.
3. Click Save.
What's Next
Store SDK configurations in your org. See Configure an SDK Data Source on a FlexCard.
Required Versions
Available beginning Summer '21.
1. To configure the data source when creating a FlexCard, navigate to the Select Data Source Type
step, select SDK, and click Next.
2. To configure the data source from the SetUp Panel in the FlexCard Designer, click Setup, and select
SDK from the Data Source Type dropdown.
3. From the SDK dropdown, select the SDK from the drop list.
This should be the name of the SDK as given in the static resource file, such as Digitalcommerce
JS SDK. Once you select that name, the Description field populates. The FlexCard finds the static
resource name and loads the file specified in sdkPath.
4. From the SDK Method dropdown, select from a list of functions available from your chosen SDK, such
as getOffers method. For a list of Digital Commerce SDK methods, see the SDK Core Class
Structure and Methods documentation.
5. (Optional) To pass data from the FlexCard to the SDK method, from the Input Parameters section
select from one of these options:
• Click + Add New:
a. In the Key field enter the name of a variable to pass to the method. Or, if a list of available
parameters appears when you click into the Key field, select one, such as catalogCode.
b. In the Value field, enter the value of the variable as a merge field, such as Phones.
• Click Edit as JSON to add variables as JSON, such as {"catalogCode":"Phones"}.
6. (Optional) To configure other options common among all data sources, see FlexCards Data Source
Properties.
7. (Optional) If an input parameter has merge fields, such as {recordId}, add test variables in the Test
Parameters section so that the query returns live data. See Test Data Source Settings on a FlexCard.
8. Click Save + Fetch. The FlexCard Designer makes the API call and returns a response. You can test
the response in the Test Response field. See Test Data Source Settings on a FlexCard.
What's Next
Add elements to the FlexCard. See Add Elements to a FlexCard.
See Also
1. Click the FlexCards home tab, click a version of a FlexCard to open the FlexCard Designer.
2. In the Setup panel, to configure test parameters, click + Add New in the Test Parameters section.
3. In the Key field, enter a test variable name. For example, enter the variable from the Input Map
representing a contextId such as recordId. See FlexCards Context Variables.
4. In the Value field, enter a test variable value. For example, enter a record Id, such as the one found in
the URL of an Account page.
5. (Optional) If your returned data has multiple arrays, to return a specific dataset enter its JSON path in
the Results JSON. For example, to return just the Cases dataset, enter [0]['Cases'] if your JSON
looks like this:
{
[
"Cases": [
{
"Priority": "High",
"IsEscalated": false,
"CaseId": "5006g00000FpEz5AAF",
"Created": "2020-07-22T00:22:42.000Z",
"Type": "Mechanical",
"Subject": "Generator won't start",
"Status": "New",
"Origin": "Web",
"Description": "Despite turn the power on and off several times, the
generator wouldn't start",
"CaseNumber": "00001028"
},
{
"Priority": "Medium",
"IsEscalated": false,
"CaseId": "5006g00000BsfKkAAJ",
"Created": "2020-02-27T22:28:20.000Z",
"Type": "Mechanical",
"Subject": "Shutting down of generator",
"Status": "Closed",
"Origin": "Web",
"CaseNumber": "00001017"
}
],
"Account": {
"Type": "Customer - Direct",
"Name": "Edge Communications",
"Street": "312 Constitution Place\nAustin, TX 78767\nUSA",
"State/Province": "TX",
"City": "Austin",
"Revenue": 139000000
}
]
}
6. Click Save & Fetch to view the Test Results.
See Also
• FlexCards Data Source Properties
1. From the FlexCard Designer, click Setup to open the Setup panel.
2. To configure specific options, see FlexCard Setup Reference.
What's Next
Build your FlexCard. See Add Elements to a FlexCard.
See Also
• Style FlexCard Elements
• Preview a FlexCard
• Activate a FlexCard
• Configure Publish Options on a FlexCard
A FlexCard with multiple Field elements and an Action element. Repeat Records enabled.
Improve the performance on rerendered elements when a FlexCard with repeating records updates. Only
rerender the affected card record in the FlexCard component by entering a unique Render Key that
identifies it. The FlexCard LWC uses the key to find which element in the Document Object Model (DOM),
the rendered HTML, to update.
To display data that doesn't need repeating, disable the Repeat Records feature. For example, disable the
feature to display one Account record, a Chart element that displays data from multiple Accounts, a
Datatable element that lists Account Cases, a Custom LWC element that serves as a header for a Console
app, or a child FlexCard that has it's own looped data source.
Repeatable Modes
This table displays how the Repeat Records feature works for an Active State and a Blank Card State
when records are available and not available:
See Also
Required Versions
Available beginning Summer '21.
1. In the Setup panel, click Repeat Options, and confirm that Repeat Records is enabled.
2. In the Render Key field, enter a data field with a unique value such as Id.
See Also
IMPORTANT
You can’t use data source values as session variables.
5. Apply the session variable as a merge field to an element field. For example, enter
{Session.APIkey} to a REST data source Endpoint URL.
See Also
• FlexCard Setup Reference
When a user selects a filter, such as <$2000, and clicks the Apply button from the Filter FlexCard, only
products that cost less than $2000 are visible in the Product List FlexCard.
See Also
• FlexCards Event Listener Properties
The sample DataPack demonstrates how to enable a FlexCard to listen for an event from another
FlexCard, and to listen for an event from an action on the same FlexCard. When you click on an action
element, an event is fired, and the event listeners perform other actions based on the event fired, such as
reloading the FlexCard, updating the data source, and updating data field values.
What's Included
• A demoUpdateDataSourceEvent FlexCard with two actions that when clicked, updates the data source
on another FlexCard.
• A demoEventListener FlexCard that listens for events and performs actions based on the event. This
FlexCard has the following elements and properties:
• Merge fields to display data from an SOQL Query data source.
• Merge fields to display data from a DataRaptor Extract data source.
• Event listeners that set values, updates the data source to an SOQL Query data source, updates the
data source to a DataRaptor, and reloads the FlexCard.
NOTE
To save and fetch test data from the getAccountCases DataRaptor Extract, update the
value of the action.setId in the Test Parameters of the PubsubUpdateDS:dataraptor
event listener.
• Two action elements that when clicked, fires an event to update values with new data.
• An action element that when clicked, reloads the FlexCard.
• A getAccountCases DataRaptor Extract to populate merge fields when the related event is triggered.
NOTE
To return data, check that you have Account Case records in your org.
See Also
What's Next
Add custom labels to supported fields. See Add Custom Labels to Supported Fields on a FlexCard.
See Also
• Update an OmniScript from a FlexCard
• Launch an OmniScript from a FlexCard
• FlexCard Setup Reference
1. From the FlexCard Designer, click Setup to open the Setup panel.
2. Enter a comma-separated list of custom permissions in the Required Permissions field. For example,
if you created custom permissions named Can_Edit_Policy and Can_View_Policy, enter them
as Can_Edit_Policy,Can_View_Policy.
NOTE
If this field is left empty, any user can see the FlexCard.
3. For the managed package in your org, confirm that the VlocityRequiredPermissionCheck Apex
Class exists at Setup > Apex Classes. If it doesn't exist, add it as follows:
a. From Setup, in the Quick Find menu, enter apex.
b. Click Apex Classes.
c. Click New
d. Enter the following Apex code in the Apex Class tab:
e. Click Save.
See Also
• FlexCard Setup Reference
Save style settings on an element to use on multiple elements on the FlexCard. Create custom classes
from a code editor in the FlexCard Designer and apply them to individual elements. On supported
elements, add classes to specific fields inside the element, such as the label and value of a Text element.
Conditionally apply styles based on the value of a data field.
Required Versions
Available beginning Summer '21.
1. Select the element on a state in your FlexCard, and click + Add Conditional Style from the Style
panel.
2. In Conditional Style Name, enter a unique name for the visible label for your conditional style. The
name must be different than any other conditional style name on the same element.
3. To add a condition based on the value of a data field, click + Add Condition. See Add Conditions to a
FlexCard Element on how to configure conditions.
4. Click Save.
5. Your new condition appears below the Default.
When you add a conditional style, a Default section is added to the top of the Style panel. When your
conditions aren’t met, the default styles apply.
6. (Optional) To determine what conditions are applied, hover over the tooltip "i" icon next to the
conditional style name.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• Style FlexCard Elements
See Also
Configure the height, minimum height, and maximum height of the element using CSS supported values.
See Adjust the Height of an Element on a FlexCard.
Enable responsiveness on one or more elements to set the width to change as the width of the visable area
of a page, called the viewport, changes. See Create Responsive Elements on a FlexCard.
The responsive sizing of elements is mobile-first. Sizing starts at the smallest visible viewport breakpoint
and is continuously applied upwards until the next wider breakpoint overrides it. When responsiveness is
enabled, the default width becomes the width of the smallest viewport breakpoint. See FlexCards Element
Responsiveness.
See Also
See Also
IMPORTANT
Percentage (%) is not supported for height.
1. In the FlexCard Designer, click an element on the canvas, and click Style to open the Style panel.
2. To update the height of your element, open the Dimensions section, and enter a CSS supported value
for one or more of the following properties:
NOTE
For example, enter 20, 150px, or calc(2em * 5), auto, and so on. If you enter
just a number, the length unit defaults to px.
• To set a fixed height, enter a CSS supported value in the Height field.
• To set a minimum height, enter a CSS supported value in the Minimum Height field.
• To set a maximum height, enter a CSS supported value in the Maximum Height field.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
When an element is dragged next to another element that is less than 12 columns wide, the new element
takes up the remaining width of the horizontal space available. And when the width of an element is
adjusted from less than 12 to 12 columns wide, any elements next to it will move below it.
3. To adjust the width from the Style panel for any element, including a state, perform these tasks:
a. Click Style to open the Style panel
b. In the Dimensions section, under Default, move the slider left or right to adjust the element width.
NOTE
Only Child FlexCards enable you to adjust the width of a State element, and only
from the Style panel. When you adjust the width of the state, if the width is less
than 6 columns wide, records display side by side, mimicking the behavior of
elements inside states. See Display Records Side-By-Side on a FlexCard.
See Also
• Create Responsive Elements on a FlexCard
• Adjust the Height of an Element on a FlexCard
• Style FlexCard Elements
When the Responsive feature is enabled in the Style panel of a FlexCard, the responsive sizing of
elements is mobile-first. Sizing starts at the smallest viewport breakpoint and is continuously applied
upwards until the next wider breakpoint overrides it. When responsiveness is enabled, the default width
becomes the width of the smallest viewport breakpoint.
TIP
Build with a mobile-first approach if most or all of your elements are responsive. Build your
FlexCard at the smallest canvas size by selecting Mobile L/S from the Viewport
Dropdown. After setting widths for all breakpoints for each element from the Style panel,
view your layout at different viewports by toggling through the Viewport Dropdown. See
View a FlexCard at Different Viewport Breakpoints
• Set the Subject field to 12 for Smaller and Small, and 10 for Medium and Large.
• Set the CaseId field to 12 for Smaller and Small, and 2 for Medium and Large.
Available Breakpoints
Viewport Breakpoint Device
Large (>=1024px) Laptop and desktop
Medium (>=768px) Large tablet
Small (>= 480px) Small or medium tablet, and large mobile device
Smaller (< 480px) Small or medium mobile device
See Also
• Create Responsive Elements on a FlexCard
• Adjust the Height of an Element on a FlexCard
• Style FlexCard Elements
By default, the width of an element is the same no matter the width of the viewport of the device your user
views the FlexCard. When responsiveness is enabled, the width of an element changes to the width set at
each viewport breakpoint. The default width becomes the width on the smallest viewport breakpoint for a
mobile-first approach. See FlexCards Element Responsiveness.
TIP
Build with a mobile-first approach if most or all of your elements are responsive. Build your
FlexCard at the smallest canvas size by selecting Mobile L/S from the Viewport
Dropdown. After setting widths for all breakpoints for each element from the Style panel,
view your layout at different viewports by toggling through the Viewport Dropdown. See
View a FlexCard at Different Viewport Breakpoints
1. In the FlexCard Designer, click an element on the canvas, and click Style to open the Style panel.
2. From the Dimensions section, enable Responsive.
NOTE
Easily identify responsive elements by selecting or hovering over the element. A
device icon displays next to the Component Name.
• Set the Subject field to 12 for Smaller and Small, and 10 for Medium and Large.
• Set the CaseId field to 12 for Smaller and Small, and 2 for Medium and Large.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
See Also
• Style FlexCard Elements
Property Description
Background Color Select a background color. Enter a Hex color code, such as #ff0000. Or click the colored box to select from a
color picker.
Background Image Enter the URL of the image to display as the background of your element. The image must be accessible.
Url
Background Position Set the position of the background image. Enter any value allowed by the background-position CSS
property, such as right bottom, center, 10px 30px, and so on.
Background Repeat Set how the background image repeats itself. Enter any value allowed by the background-repeat CSS
property, such as no-repeat, repeat, repeat-x, and so on.
Background Size Set the size of the background image. Enter a value allowed by the background-size CSS property, such
as cover, contain, and so on.
Border Color Select a border color. Enter a Hex color code, such as #ff0000. Or click the colored box to select from a color
picker.
Border Radius To round the edges of the element border, set a border radius. Enter a value allowed by the border-radius
CSS property, such as 25px, 25px 50px, and so on.
Border Style Select the type of border to display. Enter a value allowed by the border-style CSS property, such as solid,
dashed, inset, and so on. Default is solid.
Border Type Select one or more border locations such as top, bottom, right, and left. To remove a border location,
select it again from the dropdown.
Border Width Enter a number for the thickness of the border in pixels.
Salesforce Theme Select a predefined color scheme for your element.
Text Color Update the element's text color. Enter a Hex color code, such as #ff0000. Or click the colored box to select
from a color picker.
See Also
See Also
• Style FlexCard Elements
Property Description
Margin Size Select the size of the margins.
Margin Type Select where to add margins to your element, such as the bottom, both vertical spaces, both horizontal positions,
around the entire element, and so on.
Padding Size Select the size of the padding.
Padding Type Select where to add padding to your element, such as the bottom, both vertical spaces, both horizontal positions,
around the entire element, and so on.
Text Align Select text alignment, such as center, to update the alignment of the content within the element's container.
See Also
1. In the FlexCard Designer, click on an element in a state, and click Style to open the Style panel.
2. From the Padding Type dropdown, select where to add your padding. For example, to add padding on
all sides of the content, select Around. To add padding to both the top and the bottom, select
Horizontal.
3. From the Padding Size dropdown, select how much padding to add, such as Medium, x-Small, and
so on. See SLDS Padding.
4. Click the plus icon.
5. Repeat steps 1 through 3 to add more padding.
See Also
1. In the FlexCard Designer, click on an element in a state, and click Style to open the Style panel.
2. From the Margin Type dropdown, select where to add your margin. For example, to add space around
the entire element, select Around. To add space above and below your element, select Horizontal.
3. From the Margin Size dropdown, select how much spacing to add, such as Medium, x-Small, and so
on. See SLDS Padding.
4. Click the plus icon.
5. Repeat steps 1 through 3 to add more margins.
See Also
See Also
• Style FlexCard Elements
Property Description
Container Class Add a class to the container of your element.
Custom Class Add a class directly to the element.
Inline CSS Styles Apply inline CSS styles to your element, such as font-variant: small-caps;.
See Also
The custom CSS is a Salesforce attachment. When the FlexCard is saved, the attachment is updated.
A .css file is also packaged with the generated LWC.
1. In the FlexCard Designer, click an element on the canvas, and click Style to open the Style panel.
2. In the FlexCard Designer submenu, click the down arrow next to Activate, and select Add Custom
CSS.
NOTE
Your FlexCard must be inactive to use this feature.
4. (Optional) Enable Load as Global CSS. These custom styles are loaded as a stylesheet in the header
of the page when this feature is enabled. And when not enabled, it's loaded as internal styles inside the
header of the FlexCard only.
5. Click Save.
What's Next
Apply custom CSS classes to elements. See Apply Custom CSS to a FlexCard Element.
See Also
Property Description
Add Custom CSS Create and edit custom CSS classes. The custom CSS is a Salesforce attachment. When the FlexCard is
saved, the attachment is updated. A .css is also packaged with the generated LWC.
Load as Global CSS Enable to apply your CSS classes at run time, such as in Preview.
See Also
Apply classes from style sheets available to the FlexCard, such as the global SLDS and Newport style
sheets. Or, apply classes that you create inside the FlexCard Designer with the Add Custom CSS feature.
See Create Custom CSS Within the FlexCard Designer.
Apply the alt-table-rows class to the element and the alt-bg-group-wrapper class to the group
heading.
See Also
Property Description
Add Custom CSS Create and edit custom CSS classes. The custom CSS is a Salesforce attachment. When the FlexCard is
saved, the attachment is updated. A .css is also packaged with the generated LWC.
Load as Global CSS Enable to apply your CSS classes at run time, such as in Preview.
See Also
TIP
Use this feature as needed and sparingly to optimize performance.
1. In the FlexCard Designer, click an element on the canvas, and click Style to open the Style panel.
2. In the Inline CSS Styles field of the Custom section, enter CSS properties and their values. For
example, font-variant: small-caps; word-spacing: 30px;.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
Property Description
Color Enter a Hex color code or click the colored square to select a color from the color picker.
Font Family Enter one or more web-safe, SLDS, or Newport Design System fonts. Supports the font-family CSS property
options. For example, enter a specific font, such as Courier New; a general font, such as serif; or a fallback list,
such Times New Roman, Courier New, serif.
Font Size Select a font-size. Enter any value allowed by the font-size CSS property, such as 1em, 6px, large or
calc(). If you enter just a number, the default unit used is px.
Size Select the size of the entire element, such as Medium.
Text Align Select text alignment, such as center. To align a Flyout content's text, select Text Align in the Alignment section
of the Style panel.
Text Decoration Set the appearance of decorative lines on the text. Enter a value allowed by the text-decoration CSS property,
such as underline and overline.
See Also
• FlexCard Elements Custom CSS
See Also
• FlexCard Elements Custom CSS
• Create Custom CSS Within the FlexCard Designer
See Also
• FlexCard Elements Custom CSS
• Create Custom CSS Within the FlexCard Designer
See Also
• FlexCard Elements Custom CSS
• Create Custom CSS Within the FlexCard Designer
Property Description
Color Enter a Hex color code or click the colored square to select a color from the color picker.
Font Family Enter one or more web-safe, SLDS, or Newport Design System fonts. Supports the font-family CSS property
options. For example, enter a specific font, such as Courier New; a general font, such as serif; or a fallback list,
such Times New Roman, Courier New, serif.
Font Size Select a font-size. Enter any value allowed by the font-size CSS property, such as 1em, 6px, large or
calc(). If you enter just a number, the default unit used is px.
Size Select the size of the entire element, such as Medium.
Text Decoration Set the appearance of decorative lines on the text. Enter a value allowed by the text-decoration CSS property,
such as underline and overline.
See Also
• FlexCard Elements Custom CSS
Property Description
Font Family Enter one or more web-safe, SLDS, or Newport Design System fonts. Supports the font-family CSS property
options. For example, enter a specific font, such as Courier New; a general font, such as serif; or a fallback list,
such Times New Roman, Courier New, serif.
Font Size Select a font-size. Enter any value allowed by the font-size CSS property, such as 1em, 6px, large or
calc(). If you enter just a number, the default unit used is px.
Text Align Select text alignment, such as center.
Text Decoration Set the appearance of decorative lines on the text. Enter a value allowed by the text-decoration CSS property,
such as underline and overline.
IMPORTANT
The Font Size property isn’t available for the Checkbox Toggle and Checkbox Button
toggle types in the Vlocity Health and Insurance Spring '21 release.
Property Description
Checked Label Select the display color of the label when the toggle element is selected. Enter a Hex color code or click the
colored box to select a color from the color picker.
Unchecked Label Select the display color of the label when the toggle element isn’t selected. Enter a Hex color code or click the
colored box to select a color from the color picker.
Property Description
Checked Icon Select the display color when the toggle element is selected. Enter a Hex color code or click the colored box to
select a color from the color picker.
Unchecked Icon Select the display color when the toggle element isn’t selected. Enter a Hex color code or click the colored box to
select a color from the color picker.
Property Description
Color Select a label color. Enter a Hex color code or click the colored box to select a color from the color picker.
See Also
• FlexCard Elements Custom CSS
• Create Custom CSS Within the FlexCard Designer
• FlexCard Toggle Element Type Reference
The Custom Style feature saves any settings configured in the Style panel including classes, inline styles,
widths, and responsiveness.
1. In the FlexCard Designer, select an element on the canvas, and click Style to open the Style panel.
2. Click the Select Saved Style search icon in the Custom Styles section.
3. In the Select Saved Styles modal, click on the name of a style under Select Style.
4. View how your applied style will look in the Preview section of the modal.
5. Click Save.
What's Next
Preview your FlexCard. See Preview a FlexCard.
See Also
• Create Responsive Elements on a FlexCard
Property Description
Clear Styles Clear all styles configured from the Style panel including applied classes and responsiveness.
Create New Style Create a new Custom Style based on the current styles set.
Enter Style Name Enter the name of a new Custom Style.
Remove Default Removes the default style for the selected element type. For example, if the current style for a selected Action
element is Red Action, and you click Remove Default, the default style for any new Action element added to
the FlexCard will not have a default style.
Reset Changes Reset the changes to a saved Custom Style. Removes any styles applied to an element that is not part of the
applied Custom Style. For example, if you add a background image to an Action element whose Custom Style is
Red Action, clicking Reset Changes removes the background image but retains any settings that are part of
the Red Action Custom Style.
Save As Save current style settings as a Custom Style.
Search For Style Search from the list of saved Custom Styles.
Select Saved Style Apply a saved Custom Style to the element.
Set As Default Set the current Custom Style as the default for the selected element type. For example, if the current style for a
selected Action element is Red Action, and you click Set As Default, the default style for any new Action
element added to the FlexCard will be Red Action.
See Also
To display records next to each other, embed a Child FlexCard whose width is at most 6 columns (50%)
wide. See Adjust the Width of an Element on a FlexCard.
TIP
Consider enabling responsiveness so that when your FlexCard is viewed on mobile
devices, your content looks good. For example, make the records full width when on
mobile devices, but 6 columns wide on tablets, and 3 columns wide on desktops. See
Create Responsive Elements on a FlexCard.
4. If your parent data does not need to be looped over, click Setup, and uncheck Repeat Records. This
will display just one record on the parent FlexCard. See Disable Record Looping on a FlexCard.
5. Click Preview to see your records displayed next to each other.
6. Click Activate.
What's Next
Configure Publish Options to define metadata values and add a custom component SVG icon for your
generated LWC. See Configure Publish Options on a FlexCard.
1. To rearrange an element inside a state, or move an element between states, click and hold down the
element, then drag it to the desired position. Wait for the position indicator to appear at the desired
position before letting go.
2. To rearrange a state, click and hold down the state and move it up or down to the desired position.
3. To duplicate an element, click the element, and click the double square icon.
State
See Also
• Adjust the Width of an Element on a FlexCard
• Create Responsive Elements on a FlexCard
• Adjust the Height of an Element on a FlexCard
• Style FlexCard Elements
Required Versions
Available beginning Summer '21.
By default, the Enable Tracking feature is enabled on a FlexCard that is not a Child FlexCard. For
example, on a parent FlexCard which has a Child FlexCard embedded, tracking is enabled on the parent by
default.
To track events on a Child FlexCard, you must enable the Enable Tracking feature, which is disabled by
default. To enable tracking on all nested Child FlexCards, you must enable the tracking feature on all parent
FlexCards.
On the Action element, the Enable Tracking feature is enabled by default. When disabled, the UI Action
event is not fired. Action click tracking is independent of Child FlexCard tracking.
1. In the FlexCard Designer, select an action on the canvas or drag a supported element, such as Action,
into a state on the canvas.
2. In the Properties panel, if the Enable Tracking feature is disabled, click to enable.
See Also
• Cards Framework Event Tracking
• Enable Tracking for OmniStudio Components
IMPORTANT
If you don't see your content in the Preview canvas, check that you have granted access to
your org domains in Remote Site Settings. See Update Remote Site Settings to Preview
Your FlexCard.
NOTE
The Navigate and OmniScript actions don’t work in Preview. Add them to a Lightning or
Community page to view them.
Preview a FlexCard
Preview your FlexCard's appearance and functionality before publishing it to a Lightning or Community
page. In Preview, test how your FlexCard looks on multiple devices and test the functionality of action links
and other interactive elements.
NOTE
The Navigate and OmniScript actions don’t work in Preview. Add them to a Lightning or
Community page to view them.
IMPORTANT
If you don't see your content in the Preview canvas, check that you have granted
access to your org domains in Remote Site Settings. See Update Remote Site
Settings to Preview Your FlexCard.
2. (Optional) To add test parameters, click Add Test Params, and perform these tasks:
• In Key, enter a variable to test how and what data displays on your FlexCard. For example, enter
pagelimit to update how many pages display for a Datatable element. See FlexCards Context
Variables.
• In Value, enter a test value. For example, if the Key is pagelimit, enter 2 to limit the number of
pages to display on a Datatable element to 2.
• Click Add to enter another parameter as a key/value pair.
3. (Optional) To see how your FlexCard looks on different devices, select from the Viewport Dropdown.
NOTE
To enable elements to change widths in response to the width of the viewport, see
Create Responsive Elements on a FlexCard.
4. (Optional) Beginning Summer '21, view your FlexCard's data JSON from the Data JSON panel. See
View a FlexCard's Data JSON.
5. (Optional) Beginning Summer '21, debug action and event requests and responses from the Action
Debugger panel. See Debug FlexCard Action and Event Requests and Responses.
6. (Optional) Beginning in Summer '21, to preview your FlexCard at full-width, click the toggle icon ( ) to
close the Debug Panel.
What's Next
Activate your FlexCard. See Activate a FlexCard.
See Also
• Configure Publish Options on a FlexCard
• Add a FlexCard to a Lightning Page
• Add a FlexCard to a Community Page
Property Description
Key Enter a variable to test how and what data displays on your FlexCard. For example, enter pagelimit to update how
many pages display for a datatable.
Value Enter a test value. For example, if the Key is pagelimit, enter 2 to limit the number of pages to display on a datatable to
2.
Required Versions
Available beginning Summer '21.
The following table lists the Data JSON's available objects and the information each object provides:
Object Description
cards Displays information about rendered cards based on the data displayed and state conditions applied. For example, if
your FlexCard displays information about an Account and the data source returns 3 accounts with no conditions
applied, then the cards object shows 3 card objects. Each card object displays the card's state name, data fields,
attributes, and child FlexCards. The uniqueKey distinguishes the card objects from each other.
NOTE
If your FlexCard has a child FlexCard, only its name appears in the Data JSON panel.
dataSource Displays the array of records returned from the data source and the settings configured in the Setup panel, such as the
data source type and delay time. Displays additional settings depending on your data source type. See Configure a
Data Source on a FlexCard.
Label Displays custom labels fetched for the FlexCard. See Add Custom Labels to Supported Fields on a FlexCard.
Params Displays Salesforce page parameters, such as namespace.
recordId Displays the Id of the FlexCard page as seen in the URL when you are in the FlexCard Designer.
Session Displays the Session Variables defined in the Setup panel. See Add Session Variables to a FlexCard.
Object Description
TestParams Displays test parameters defined in the Add Test Params feature. See FlexCards Preview 'Add Test Params'
Properties.
theme Displays the FlexCard theme as selected when the FlexCard was created.
title Displays the FlexCard name as defined when the FlexCard was created.
User Displays logged-in user information. See FlexCard Context Variables.
See Also
• Debug FlexCard Action and Event Requests and Responses
NOTE
If your FlexCard has a child FlexCard, only its name appears in the Data JSON panel.
Required Versions
Available beginning Summer '21.
See Also
• FlexCard Designer Data JSON
Required Versions
Available beginning Summer '21.
View the configuration, status, and responses of parent and child data sources. View data source type and
relevant settings, such as delay time from the config property. See if the data source successfully returns
data in the status field. View the returned data in the response field.
View the response of each action or event executed on your FlexCard. For example, let's say your
FlexCard has a pubsub event that passes data with the fired event. An event listener on the same FlexCard
updates a data field with the value passed to it from the pubsub event. Clicking the Pubsub Event action
link on your FlexCard in Preview, displays both the Pubsub Event action and the Set Values action logs in
the Action Debugger.
Action logs display data relevant to the action type. For example, a Pubsub Event action log displays
channel, event, and inputMap. A Set Values action log displays fields and response.
See Also
• View a FlexCard's Data JSON
Required Versions
Available beginning Summer '21.
See Also
• FlexCard Designer Action Debugger
• View a FlexCard's Data JSON
The viewport size is saved when changed. After navigating away from the FlexCard Designer, toggling
between Design view and Preview, or reloading the page, the viewport size remains the same until you
change it.
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. To test responsiveness in Design view, select a breakpoint from the Viewport Dropdown.
3. To test responsiveness in Preview, click the Preview tab and select a breakpoint from the Viewport
Dropdown.
What's Next
Enable elements to respond to different viewport widths. See Create Responsive Elements on a FlexCard.
See Also
• Style FlexCard Elements
• Activate a FlexCard
Activate a FlexCard
Activate a FlexCard to generate an LWC and publish it to a Lightning or Community page. Activating a
FlexCard disables editing capabilities. You cannot add or edit elements on an active FlexCard.
What's Next
Configure Publish Options to define metadata values and add a custom component SVG icon for your
generated LWC. See Configure Publish Options on a FlexCard.
See Also
• Add a FlexCard to a Lightning Page
• Add a FlexCard to a Community Page
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. From the FlexCard Designer submenu, click the down arrow next to Activate, and click Publish
Options.
3. To configure metadata values, see Define Metadata Values from the FlexCard Designer.
4. To update the SVG resource with a custom icon, see Add a Custom Component SVG Icon to a
FlexCard.
What's Next
Publish your FlexCard to a Lightning or Community page. See Add a FlexCard to a Lightning Page. See
Add a FlexCard to a Community Page.
See Also
• Add a FlexCard to a Lightning Page
• Add a FlexCard to a Community Page
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. From the FlexCard Designer submenu, click the down arrow next to Activate, and click Publish
Options.
3. Enter or update values for these properties:
Property Description
Master Label Update the visible name of generated LWC as you want it to appear in the Lightning App Builder and
Community Builder. The default is the Name you used to create the FlexCard and, which is visible in the
Setup panel.
Description Enter a description for your generated LWC.
API Version Defines the API version of your generated LWC. The default is the API version used when creating the
FlexCard. When creating a new FlexCard, the default value is the current API version.
Runtime (Read-Only) Defines the Vlocity package namespace.
Namespace
Is Exposed When enabled, your card component is public. By default, this feature is enabled.
Targets Select where your generated LWC is accessible. By default, HomePage, RecordPage, and AppPage are
selected to enable use on a custom home page, a record page, and an app home page.
To enable the use of your LWC on a Community Page, select CommunityPage. To enable the use of your
generated LWC on a Community Page with configurable properties, select CommunityDefault.
What's Next
Add a custom component SVG icon to your generated FlexCard LWC. See Add a Custom Component SVG
Icon to a FlexCard.
See Also
• Add a FlexCard to a Lightning Page
• Add a FlexCard to a Community Page
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. From the FlexCard Designer submenu, click the down arrow next to Activate, and click Publish
Options.
3. To upload a custom SVG resource, under Add SVG resource / Drop it here, click Choose File or
drag a file from your computer inside the dashed box.
4. Click Save.
What's Next
Configure metadata values for your generated FlexCard LWC. See Define Metadata Values from the
FlexCard Designer.
See Also
• Add a FlexCard to a Lightning Page
• Add a FlexCard to a Community Page
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. Select a supported element, such as the Field element.
3. From the Properties panel, enter {Label.customLabelName} in a supported field. For example, to
display the AccountName custom label as the Label for a Field element that displays the name of an
Account, enter {Label.AccountName}.
What's Next
Enable multi-language support. See Enable Multi-Language Support on a FlexCard.
There are three ways to pass data from the LWC OmniScript to the embedded FlexCard:
The data fields on the LWC OmniScript must exist in the FlexCard even if the values are empty. For
example, if your OmniScript data JSON has Id, Name, Email, and Phone fields, these field names must
exist even if the value of Email or any other fields are empty in the data source of the embedded FlexCard.
1. In your org, go to the FlexCards tab and click a version of a FlexCard to open the FlexCard Designer.
Or, create a new FlexCard. See Create a New FlexCard.
2. In the Setup panel, select and configure the data source with data fields you want the OmniScript to
map.
For example, if your data source is a DataRaptor that gets a list of Accounts, confirm that the
DataRaptor Output fields selected include those your OmniScript data JSON maps to. If your
OmniScript data JSON has a Name field, so should the Output from the DataRaptor, and so on.
3. Click Save & Fetch.
4. From the Build panel, add elements such as Fields, Datatables, and so on onto the canvas. See Add
Elements to a FlexCard.
5. In the Setup panel, check OmniScript Support.
6. Click Activate.
7. Embed your FlexCard in an LWC OmniScript with the Custom LWC element in the LWC OmniScript
Designer. See Embed FlexCards in an OmniScript.
8. In the Custom Lightning Web Component Properties section of the Properties panel, add parent-
data as the Property Name, and set the Property Source value to true.
9. Click + Add New Property.
10. Enter records as the Property Name, and in the Property Source field, enter the object in the data
JSON that lists records that map to those in your FlexCard. Enter the object as a merge field using
OmniScript merge field syntax, such as %objectname%.
For example, if your list of records is stored in a JSON object called accounts, enter %accounts%.
11. Click Activate.
12. Click Preview to preview the FlexCard inside the LWC OmniScript.
See Also
• Pass Data from an LWC OmniScript to an Embedded FlexCard
For example, if your FlexCard has a DataRaptor that gets Account Cases, the fields and actions get
updated based on the value of the recordId set in the LWC OmniScript data JSON. If you use the {recordId}
merge field in your FlexCard such as in an SOQL query or a Text element, that data that relies on that
merge field is also updated based on the recordId coming from the LWC OmniScript data JSON.
1. In your org, go to the FlexCards tab and click a version of a FlexCard to open the FlexCard Designer.
Or, create a new FlexCard. See Create a New FlexCard.
2. Configure your data source if you haven't already. See Configure a Data Source on a FlexCard.
3. Add data elements such as Fields, Actions, and so on, from the Build panel onto the canvas. See Add
Elements to a FlexCard.
4. In the Setup panel, check OmniScript Support.
5. Click Activate.
6. Embed your FlexCard in an LWC OmniScript with the Custom LWC element in the LWC OmniScript
Designer. See Embed FlexCards in an OmniScript.
7. In the Custom Lightning Web Component Properties section of the Properties panel, add record-
id as the Property Name.
NOTE
Because the Property Name is an HTML attribute, it must be written in kebab case,
with words separated by a dash. See Property and Attribute Names.
8. Set the Property Source to a JSON node that contains a recordId. Use OmniScript merge field syntax,
such as %nodename%, to enter the node as a merge field.
For example, if your recordId is stored in a JSON node called ContextId, enter %ContextId%.
9. Click Activate.
10. Click Preview to preview the FlexCard inside the OmniScript.
See Also
• Pass Data from an LWC OmniScript to an Embedded FlexCard
The parent object in the OmniScript data JSON can be named anything as long as it is an object with fields
that match the name of the parent attribute that you want the OmniScript to look for in the FlexCard. For
example, the JSON object name can be parent or account, such as "parent" : {"Id" :
"1234567"} or "account" : {"Id" : "1234567"}.
1. In your org, go to the FlexCards tab and click a version of a FlexCard to open the FlexCard Designer.
Or, create a new FlexCard. See Create a New FlexCard.
2. Configure your data source if you haven't already in Step 1. See Configure a Data Source on a
FlexCard.
3. Add data elements such as Fields, Datatables, and so on, from the Build panel onto the Canvas. See
Add Elements to a FlexCard.
4. Add a {Parent} merge field, such as {Parent.Id}, in your FlexCard where merge fields are
supported such as in an SOQL query, a Text element, an Input Parameter, and so forth.
5. In the Setup panel, check OmniScript Support.
6. Click Activate.
7. Embed your FlexCard in an LWC OmniScript with the Custom LWC element in the LWC OmniScript
Designer. See Embed FlexCards in an OmniScript.
8. In the Custom Lightning Web Component Properties section of the Properties panel, add parent-
attribute as the Property Name, and set the Property Source to the parent JSON object that
contains parent attributes. Use OmniScript merge field syntax, such as %objectname%, to enter the
node as a merge field.
For example, if your parent object is stored in a JSON object called account, enter %account%.
9. Click Activate.
10. Click Preview to preview the FlexCard inside the OmniScript.
See Also
The sample DataPack demonstrates how to pass a recordId, a Parent object, and a set of records from the
LWC OmniScript to the embedded FlexCards. After configuring and activating FlexCards and the
OmniScript, view the OmniScript to see how four different FlexCards (embedded as Custom LWCs) pass
data to the OmniScript.
What's Included
• A demoPassDataParentAttributeFC FlexCard displays Account data, whose SOQL Query data source
uses the {Parent.Id} merge field to determine the contextId.
• A demoPassDataRecordIdFC FlexCard displays Account data, whose SOQL Query data source uses
the {recordId} merge field to determine the contextId.
• A demoPassDataRecordIdDRFC FlexCard displays Account Case data, whose DataRaptor data source
uses the {recordId} merge field to determine the contextId.
• A demoPassDataParentDataRecordsFC FlexCard displays a list of accounts as a data table. The data
source is a basic SOQL Query.
• A demoPassDataLWCOStoFC LWC OmniScript with the following features:
• A Set Values Action with three element values: one that defines a ContextId; one that defines a Parent
object; and one that displays a list of records.
• A Step with 4 Custom LWC elements that display 4 FlexCards.
NOTE
Download the DataPack for OmniStudio for Vlocity (formerly Digital Interaction
Platform) for an org with a Vlocity Health and Insurance, Communication, Media and
Energy, or Public Sector package installed.
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio
for Vlocity objects.
NOTE
Download the OmniStudio DataPack for an org with the OmniStudio package
installed.
If you import DataPacks with OmniStudio for Vlocity (formerly Digital Interaction
Platform) objects into an org with the OmniStudio package, the objects are converted
into OmniStudio objects.
IMPORTANT
Do not activate yet.
3. Open the demoPassDataParentAttributeFC FlexCard, click Setup, and update the Parent.Id
under Test Parameters with the Id of an Account record in your org.
4. Open the demoPassDataRecordIdDRFC and demoPassDataRecordIdFC FlexCards, click Setup,
and update the recordId under Test Parameters with the Id of an Account record in your org.
5. Open the demoPassDataLWCOStoFC OmniScript, click SetValues1, click Properties, and click Edit
Properties as JSON. Replace the values of ContextId and parentObj:Id with an Ids of Account
records in your org.
6. Activate all four FlexCards.
7. To Preview the FlexCards in the LWC OmniScript, activate the LWC OmniScript, and click Preview.
See Also
• Pass Data from an LWC OmniScript to an Embedded FlexCard
1. Go to FlexCards home tab in your org and open a FlexCard in the FlexCard Designer. Or to create a
new one, see Create a New FlexCard.
2. To embed the LWC OmniScript in a flyout, drag an Action element from the Build panel onto the
canvas.
3. Select Flyout as the Action Type.
4. Click + Add New next to Attributes and enter the values for these settings as follows:
• Key: vlocEvents
• Value: Enter the name of the pubusb channel. This is typically the FlexCard you want to refresh. For
example, if the name of the FlexCard to refresh is AccountPolicy, enter that here.
5. If the FlexCard you want to refresh is different from this FlexCard, open that FlexCard from the
FlexCards home tab.
6. From the Setup panel click + Add New next to Event Listener, and enter the values for the settings as
follows:
• Event Type: Pubsub
• Channel Name: Enter the same of the vlocEvents attribute you entered in step 5. For example, if
your vlocEvents value is AccountPolicy, enter that here.
• Event Name: data
• Action Type: Card
• Type: Reload
1. In your org, go to Setup > Lightning App Builder and click Edit for an existing Lightning app to open the
Lightning App Builder. Or, on a Lightning record page, from the Setup menu, click Edit Page.
2. From the Components pane, find your generated FlexCard Lightning web component from the list of
Custom components, and drag it to the canvas area.
IMPORTANT
If you don’t see your component listed, confirm that the appropriate Target is checked
in Publish Options. See Define Metadata Values from the FlexCard Designer
3. (Optional) In the properties panel, set Component Visibility. See Dynamic Lightning Pages.
4. To configure activation options, click Activation. See Activate Your Lightning App Page.
IMPORTANT
If you don't see your FlexCard, confirm that it is active and available to Community
pages. See Define Metadata Values from the FlexCard Designer.
4. (Optional) In the properties pane, set Component Visibility. See Dynamic Lightning Pages.
5. Click Preview. See Preview Your Experience Builder Site.
6. Click Publish.
See OmniOut.
Required Versions
Available beginning Summer '21.
must add and configure a recordId property. Add the recordId property in your FlexCard's configuration file,
then configure the property on the Community page.
1. From an active FlexCard in the FlexCard Designer, click the down arrow next to Activate in the
submenu, and click Publish Options.
2. Under Targets, select the CommunityDefault checkbox.
3. Click the Editor tab.
4. Inside the targetConfig tag, add a property tag with the name recordId and the type String.
<targetConfig targets="lightningCommunity__Default">
<property name="recordId" type="String" ></property>
</targetConfig>
5. Add your FlexCard to your Community page. See Add a FlexCard to a Community Page.
6. In the recordId property field, enter {!recordId}.
1. Ensure that you are using the Original Profile Interface by disabling the Enhanced Profile User
Interface. See Disable Enhanced Profile User Interface.
2. Complete the following tasks in any order:
• Grant access to the necessary custom objects. See Configure Custom Object Permissions for
Community Profiles.
• Grant access to the necessary Apex classes. See Grant Apex Class Access to a Community Profile.
1. From Setup, type User in the Quick Find box and click User Management Settings.
2. Set the Enhanced Profile User Interface option to Disabled.
What's Next
• Configure Custom Object Permissions for Community Profiles
• Grant Apex Class Access to a Community Profile
1. From Setup, type Users in the Quick Find box and click Profiles.
2. Find the profile for the users who will be accessing the Community site and click Edit.
3. Scroll to the Custom Object Permissions section.
4. Check View All for the following objects:
• OmniUiCard
NOTE
You can't change Custom Object Permissions for any of the default profiles. For these
profiles, the checkboxes in this section are not selectable.
5. Click Save.
What's Next
If you haven't already, Grant Apex Class Access to a Community Profile.
1. From Setup, type Users in the Quick Find box and click Profiles.
2. Find the profile for the users who will be accessing the Community site and click the profile name.
If you click Edit, you won't see the Enabled Apex Class Access settings.
3. Scroll to the Enabled Apex Class Access section and click Edit.
4. If namespace.CardCanvasController is not in the Enabled Apex Classes list, select it from the list
of Available Apex Classes and click Add.
For namespace see Viewing the Namespace and Version of the OmniStudio Vlocity Package.
5. Click Save.
What's Next
If you haven't already, Configure Custom Object Permissions for Community Profiles.
Versioning Vs Cloning
FlexCards Versioning
FlexCards supports versioning. You can create an identical copy of a FlexCard by creating a new version
and keeping other versions with the same name, and author, but with a new version number. Create a new
version when you want to make slight modifications to a FlexCard already published to Lighting or
Community pages, and elsewhere.
The name, author, and version combination must be unique for each component in an org. Only one
version of a component can be active at a time. When you create a new version of a FlexCard in the
FlexCard Designer, the version number increases by 1 and the Status is inactive. See Create a New
Version of a FlexCard.
Versioning Workflow
When you create a new version of a FlexCard in the FlexCard Designer, a new version is created
dynamically. You can't choose the author or name of the new version. To create a new FlexCard based on a
current FlexCard, and to update the Author and/or Name, you must clone your FlexCard. See Clone a
FlexCard.
The following table describes the fields involved in the versioning process:
Field Description
Name FlexCards are requested by name.
Author Specifies the user organization that created the FlexCard. Use author names that describe the team creating the content.
Version An integer that increases by one with every new version.
Active Indicates whether a record is active for run time use. One active record per name is allowed in an org. Activating a
component deactivates all other versions of the component with the same name. Only active records are exported when a
DataPack is created.
See Also
• FlexCards Versioning and Cloning
• FlexCards Cloning
• FlexCard Naming Conventions
NOTE
To create a copy of a FlexCard with a new Name, or Author, or both, you must clone the
FlexCard. See Clone a FlexCard.
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. Click New Version in the submenu.
3. The new version of your FlexCard opens in a new tab and the Current Version is updated to the
previous version number plus one.
See Also
• FlexCards Versioning
FlexCards Cloning
FlexCards supports cloning. You can create a new FlexCard by cloning a current one to update the Author
and/or Name, and copy over layout and/or settings. See Clone a FlexCard.
The name, author, and version combination must be unique for each component in an org.
Cloning Workflow
If you need to create a new version of a FlexCard with the same Name and Author, and want to make slight
modifications to test behavior and layout between versions, version the FlexCard instead. See Create a
New Version of a FlexCard.
See Also
• FlexCards Versioning and Cloning
• FlexCards Versioning
• FlexCard Naming Conventions
Clone a FlexCard
Create an identical copy of a FlexCard with the Clone feature in the FlexCard Designer. Cloning an existing
FlexCard creates a new FlexCard with a new Name, or Author, or both. The Name and Author must be
unique. See FlexCards Cloning.
NOTE
To create a new version of a FlexCard with the same name and author, make minor
modifications, and compare between versions, see Create a New Version of a FlexCard.
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. Click Clone in the submenu.
3. If you're not changing the author, enter a new Name. Either the Name, or Author, or both must change.
4. If you're not changing the name, enter a new Author. Either the Name, or Author, or both must
change.
5. (Optional) Update the following properties:
• Update the Theme to Lightning (SLDS) or Newport.
• Update the Title of the rendered component visible in the component lists in the Lightning App
Builder and Community Builder.
• If disabled, enable Child Card to embed it inside another FlexCard.
• Update the Description that displays on the FlexCards tab.
6. Click Clone.
See Also
Create an identical copy of a FlexCard with the Clone feature in the FlexCard Designer. See Clone a
FlexCard.
Not acceptable:
• address block
• View Account
• $account revenue!
See Also
• FlexCards Versioning and Cloning
Delete a FlexCard
Delete a FlexCard from the FlexCards home tab in your org. Once deleted it cannot be retrieved.
1. From the FlexCards home tab, click a FlexCard to display available versions.
2. Click the checkbox next to the version to delete.
NOTE
You can delete an inactive version of a FlexCard added to a Lightning or Community
page if there is more than one version.
NOTE
If the trash icon is disabled, check that the FlexCard is deactivated.
Import a FlexCard
Import a FlexCard as a DataPack from another environment into your org.
NOTE
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio for
Vlocity (formerly Digital Interaction Platform) objects. However, if you import DataPacks
with OmniStudio for Vlocity objects into an org with the OmniStudio package, the objects
are converted into OmniStudio objects.
See Also
NOTE
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio for
Vlocity (formerly Digital Interaction Platform) objects. However, if you import DataPacks
with OmniStudio for Vlocity objects into an org with the OmniStudio package, the objects
are converted into OmniStudio objects.
See Also
• Data Migration with OmniStudio DataPacks
Export a FlexCard
Export a FlexCard as a DataPack to import to other environments. You can export one or more FlexCards
from the FlexCards home tab or from within the FlexCard Designer.
NOTE
DataPacks with the OmniStudio objects can't be imported into an org with OmniStudio for
Vlocity (formerly Digital Interaction Platform) objects. However, if you import DataPacks
with OmniStudio for Vlocity objects into an org with the OmniStudio package, the objects
are converted into OmniStudio objects.
What's Next
Import a FlexCard to another environment. See Import a FlexCard.
See Also
• Data Migration with OmniStudio DataPacks
WARNING
Do not redeploy the LWC back into your org.
NOTE
To download an off-platform version of your FlexCard LWC, see Download an Off-Platform
FlexCard LWC from the FlexCard Designer. Beginning Summer '21, run FlexCards off-
platform on third-party websites with OmniOut for FlexCards. See OmniOut.
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. From the FlexCard Designer submenu, click the down arrow next to Activate, and click Download
LWC.
3. Click Done.
See Also
• Extend Vlocity Lightning Web Components
WARNING
Do not redeploy the LWC back into an org.
NOTE
Beginning Summer '21, run FlexCards off-platform on third-party websites with OmniOut
for FlexCards. See OmniOut.
1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. From the FlexCard Designer submenu, click the down arrow next to Activate, and click Download
Off-Platform LWC.
3. Click Done.
See Also
• Extend Vlocity Lightning Web Components
Global Variables
Name Description Merge Field
Label Salesforce Custom Labels. See Add Custom Labels to {Label.mylabel}
Supported Fields on a FlexCard.
For example, {Label.AccountName} gets a
custom label named AccountName.
Params The page parameters passed to the URL. {Params.fieldName}
NOTE
Rendered User context variable is
viewable at run time only. View in Preview.
Available properties:
Local Variables
Name Description Merge Field
action The parameters received by an event listener and sent to an {action.parameter}
action.
For example, if your event is sending you a contextId
parameter, then use {action.contextId}.
1. Click the Warnings button in the OmniStudio FlexCards home tab and copy the visualforce.com
URL.
2. In a new browser tab, go to Setup > Security > Remote Site Settings.
3. Click New Remote Site.
4. Enter a Remote Site Name without spaces for the visualforce.com domain. For example, enter
LWC_VF.
5. Enter your copied visualforce.com URL in Remote Site URL. For example, enter https://
whitmanco--vlocity-ins.visualforce.com.
6. Confirm that the Active checkbox is enabled.
7. Click Save.
8. In your original browser tab, copy the lightning.force.com URL from the Warnings popup on the
OmniStudio FlexCards home tab.
9. Go to Setup > Security > Remote Site Settings and click New Remote Site.
10. Enter a Remote Site Name without spaces for the lightning.force.com domain. For example, enter
LWC_LF.
11. Enter the copied lightning.force.com URL. For example, enter https://
whitmanco.lightning.force.com.
12. Repeat steps 6 and 7.
Update the Card Object's Lightning Record Page to Access the FlexCard
Designer
When you click on a FlexCard in the OmniStudio FlexCards home tab, and see a record detail page instead
of the FlexCard Designer, you must update the Lightning record page of the Omni UI Card object. Set the
Lightning record page to Vlocity Card Designer.
Solution
1. In your org, Go to Setup > Object Manager
2. In Quick Find, enter Omni UI Card, an click the Omni UI Card label
3. Click Lightning Records Pages.
4. Confirm that Vlocity Card Designer is the Org Default. If not, follow these steps:
a. Click Vlocity Card Designer.
b. Click View to open the Lightning App Builder.
c. Click Activation.
d. Click Assign as Org Default.
e. Select the form factors, click Next, and click Save.
See Activate Lightning Experience Record Pages.
Solution
Confirm what components are called inside an embedded component before adding it to a FlexCard. Update the components that might
cause cyclic redundancy.
OmniOut
Run OmniScripts and FlexCards off-platform on third-party websites with OmniOut for OmniScripts and
OmniOut for FlexCards. Display OmniScripts and FlexCards and connect to Salesforce from a content
management system's (CMS) external website. Run an OmniScript or FlexCard on your external site by
adding the component to the OmniOut project, integrating OmniOut into your application, and deploying
your application to your CMS.
Required Versions
• OmniOut for FlexCards is available beginning Summer '21.
NOTE
CMS configuration is separate from OmniOut. Complete your CMS configuration before
using OmniOut.
1. Download the OmniOut static resource from Salesforce and open it in Visual Studio Code. See
Download the OmniOut Static Resource.
2. Install dependencies for the OmniOut project. See Install OmniOut Dependencies.
3. (Optional for OmniScripts only) Add any nested custom LWCs that exist in your OmniScript before
adding an OmniScript to OmniOut. See Include Nested Custom LWCs in Your OmniOut OmniScript.
4. Download and add your component to the OmniOut project. To add an OmniScript, see Add an
OmniScript Lightning Web Component to OmniOut. To add a FlexCard, see Add a FlexCard LWC to
OmniOut.
5. Create a Connected App to enable a Salesforce API connection. See Create a Connected App for
OmniOut.
6. (Optional for OmniScripts only) Configure OmniOut to use multi-language OmniScripts. See Configure
Multi-Language in OmniOut for OmniScripts.
7. Run OmniOut in development mode to view and test your component. See Run OmniOut in
Development Mode.
8. (Optional) Control where your component directs users by using the Navigate Action on a FlexCard or
OmniScript. For OmniScripts, see Navigate to a URL from an OmniScript in an OmniOut App. For
FlexCards, see Navigate to a URL from a FlexCard in an OmniOut App.
9. Deploy your OmniOut application by performing one of the following tasks:
• If you are not deploying to Adobe Experience Manager, see Move OmniOut into Your App.
• (OmniScripts only) To add OmniOut for OmniScripts to an Adobe Experience Manager application,
see Add OmniScripts to Adobe Experience Manager.
10. (Optional) Include custom style sheets in your OmniOut project. See Add Custom Style Sheets to Your
OmniOut Application.
11. Build a connection in your application. See Connect Your OmniOut App.
1. In your Salesforce Org, navigate to Setup, and in the quick find box, enter Static Resources.
2. In the Static Resources page, locate and select the vlocityomnioutlwc resource.
3. Click View File to download the static resource.
4. Open the uncompressed downloaded file in Visual Studio Code.
What's Next
Install OmniOut Dependencies
See Also
• OmniOut
• Create a Connected App for OmniOut
_auth=Authentication_Key
3. In a new terminal shell, install the npm packages by running the command npm install.
4. Run the command npm run watch in the terminal console to run the development server.
5. Access the local development server at localhost:4002 to view the demo application.
What's Next
For OmniScripts, Add an OmniScript Lightning Web Component to OmniOut
See Also
• OmniOut
• (For OmniScripts only) Include Nested Custom LWCs in Your OmniOut OmniScript
• (For OmniScripts only) Configure Multi-Language in OmniOut for OmniScripts
Nested custom Lightning web components referenced by a custom Lightning web component in the
OmniScript are not included by default. To include nested custom LWCs, map them to a dummy element in
the Element Type To LWC Component Mapping section.
1. From OmniScript Setup, scroll to the Element Type To LWC Component Mapping section.
2. In the Element Type field, enter a fake element type. For example, nestedElement.
3. In the Lightning Web Component field, enter the name of your nested custom Lightning web
component. For example, nestedElement.
What's Next
Add an OmniScript Lightning Web Component to OmniOut
See Also
• OmniOut
• Navigate to a URL from an OmniScript in an OmniOut App
NOTE
If your OmniScript includes Custom LWCs from a managed package, the Custom
LWCs may not work. Custom LWCs that exist in a managed package only work if
they’re off-platform compatible.
3. Copy the component in the lwc folder of your downloaded component into the ./src/modules/
vlocityomniscript folder of your OmniOut LWC project.
4. In the OmniScript Designer, click the dropdown menu, click How To Launch, and copy the component
tag.
5. In Visual Studio Code, open the ./src/index.html file and replace the component tag with your
OmniScript component tag.
6. Edit your component tag by replacing c-- with vlocityomniscript- and save the file.
7. Open the ./src/index.js file and take these steps to import and define your component:
a. Replace the sample component import with your component's file path.
b. Replace the sample component tag with your modified component tag and remove the closing tag
and angle brackets.
customElements.define('vlocityomniscript-type-example-subtype-example-
english', buildCustomElementConstructor(VlocApp));
NOTE
When running a multi-language OmniScript, the run-mode="localScriptDef"
attribute forces the OmniScript to use the locally defined custom labels. If run-mode
isn’t present, a connection is made to retrieve the custom labels.
9. (Optional) In the OmniScript component tag, add dir="rtl" to force the OmniScript styles to load
right-to-left regardless of the OmniScript language. Without this attribute, right-to-left languages still
load with right-to-left styling. OmniScript provides beta support for right-to-left styling.
<vlocityomniscript-type-example-subtype-example-english run-
mode="localScriptDef" dir="rtl"> </vlocityomniscript-type-example-
subtype-example-english>
10. (Optional) In Index.html, uncomment the Newport style sheets to apply Newport styling.
What's Next
Create a Connected App for OmniOut
See Also
• OmniOut
• Run OmniOut in Development Mode
• Configure Multi-Language in OmniOut for OmniScripts
1. Open a FlexCard from OmniStudio FlexCards home tab in your Salesforce org, and click Activate from
the submenu.
2. Click the down arrow next to Activate, and click Download Off-Platform LWC.
3. Click Done.
4. Copy the component in the c folder of your downloaded file into the ./src/modules folder of your
OmniOut project, or subdirectory such as ./src/modules/flexcards.
5. In Visual Studio Code, open the ./src/index.html file add the FlexCard component tag. For example, if
the name of your component folder is flexaccountproducts and is placed inside the ./src/modules/
flexcards directory, your component tag may look like <flexcards-accountproducts run-
mode="localScriptDef"></flexcards-accountproducts>.
6. Open the ./src/index.js file and take these steps to import and define your component:
a. Import your component from your component's file path.
customElements.define('flexcards-accountproducts',
buildCustomElementConstructor(FlexCardProducts));
7. (Optional) In the FlexCard component tag, remove the run-mode="localScriptDef" attribute to
check if the FlexCard is active in Salesforce.
NOTE
If run-mode isn’t present, a connection is made to retrieve the custom labels.
8. (Optional) In Index.html, uncomment the Newport style sheets to apply Newport styling.
1. From Salesforce Setup, search for Apps in the Quick Find box, and click App Manager.
2. Click New Connected App.
3. In the Connected App Name field, enter a Name for your Connected App.
4. Enter an API name that is used to refer to the Connected App from your program.
5. Enter a contact email.
6. Check Enable OAuth Settings.
7. Enter a callback URL. The callback URL is the URL for the App's public site.
8. Move the Fullaccess (full) scope or Access and manage your data (api) into Selected OAuth
Scopes.
9. Save your Connected App.
10. From your Connected App page, click Edit Policies.
11. In the Permitted Users field, select All users may self-authorize, and save the Connected App.
12. Copy the Consumer Key and Consumer Secret. These values populate the client_id and
client_secret.
13. Open the OmniOut project in Visual Studio Code, and in the terminal, perform these tasks:
a. Enter this command without running it.
Value Description
USERNAME Replace with your Salesforce username.
PASSWORD Replace with your Salesforce password.
CLIENTID Replace with your Connected App's Consumer Key.
CLIENTSECRET Replace with your Connected App's Consumer Secret.
c. (Optional) In the command, enter the appropriate URL for your Salesforce environment. By
default, the URL is configured for a Sandbox org.
Environment URL
Developer Org https://login.salesforce.com/services/oauth2/token
Sandbox Org https://test.salesforce.com/services/oauth2/token
d. Run the command, and copy the Access Token and Instance URL.
What's Next
Run OmniOut in Development Mode
See Also
• OmniOut
• (For OmniScripts) Configure Multi-Language in OmniOut for OmniScripts
The language code searches locally defined language files or a Salesforce connection to access a
language's custom labels. If the OmniScript component tag's run-mode attribute is present and set to
localScriptDef, the OmniScript uses the locally defined custom labels. If run-mode isn’t present, the
OmniScript accesses the custom labels through a Salesforce connection.
1. After adding your multi-language OmniScript to OmniOut, in the VSCode command line, enter this
command, and replace LANGCODE with a Salesforce language code:
NOTE
If both options are present, the component tag property overrides the URL parameter.
export const es = {
"New": "Nuevo"
}
7. (Optional) Test the multi-language OmniScript In the command line:
a. In the command line, enter and run the command npm run watch.
b. Click the localhost link that appears in the command line.
c. In your browser, edit the URL to include a language code.
localhost:4002/myOmniScript?LanguageCode=en_US
What's Next
Run OmniOut in Development Mode
See Also
• OmniOut
• Navigate to a URL from an OmniScript in an OmniOut App
2. In the const connection object, enter the Salesforce Connected App's access token and instance
URL. See Access Token.
3. Set this.namespace equal to the namespace of your package namespace. To find your namespace,
see Viewing the Namespace and Version of the OmniStudio Vlocity Package.
4. Save your file.
5. In the terminal, enter and run the command npm run watch.
What's Next
Move OmniOut into Your App
See Also
• OmniOut
• Navigate to a URL from an OmniScript in an OmniOut App
• Connect Your OmniOut App
1. View the generated URL format for each of these Navigate Action page reference types:
OR
/logout
Named Page /{pageName}?{...targetParameters} /home
Navigation Navigation items, such as tabs, transform the item /my-custom-tab
Item name into kebab-case.
Object Page /o/{sObjectApiName}/home? /o/case/home
{...targetParameters}
Record /r/{sObjectApiName}?id={objectId} /r/account?id=0012E00001qF0l2QAC
Page {...targetParameters}
]);
What's Next
If you’re deploying your OmniOut app to Adobe Experience Manager application, see Add OmniScripts to
Adobe Experience Manager.
If you're not deploying to Adobe Experience Manager, see Move OmniOut into Your App.
See Also
• OmniOut
• Create a Connected App for OmniOut
• Add Custom Style Sheets to Your OmniOut Application
NOTE
To navigate to a URL from an OmniScript in an OmniOut app, see Navigate to a URL from
an OmniScript in an OmniOut App.
What's Next
Move OmniOut into Your App
See Also
1. In your OmniOut project, run the command npm run build in your Visual Studio Code terminal. The
command compiles OmniOut into a dist folder.
2. In the dist folder, copy the required OmniScript and FlexCard files from the OmniOut project to your
App.
4. In the index.html file, select and copy your OmniScript or FlexCard component tag into your app's
index.html file.
<vlocityomniscript-doc-example-english run-mode="localScriptDef"></
vlocityomniscript-doc-example-english>
<flexcards-accountproducts run-mode="localScriptDef"></flexcards-
accountproducts>
What's Next
Connect Your OmniOut App
See Also
• OmniOut
• Add Custom Style Sheets to Your OmniOut Application
1. Create a Salesforce connection in AEM. See Integrate Salesforce Cloud Services into Adobe
Experience Manager.
2. Set resource paths in OmniOut to load Lightning and Newport styles into your app. See Set the
OmniOut Resource Path.
3. Deploy OmniOut to AEM. See Deploy OmniOut to Adobe Experience Manager.
4. Add the OmniOut component to an AEM page. See Add the Vlocity LWC OmniOut Component to
Adobe Experience Manager.
1. Open your AEM instance and click the main logo in the top left corner.
2. Click the Tools icon, and select Deployment.
3. Select the Cloud Services card and scroll down to the Salesforce section. Click Show Configurations.
4. Click the [+] link next to Available Configurations and enter the necessary information and click Create.
This opens a new page and modal for the Cloud Services Configuration.
5. To create consistency across platforms, enter the name of the Connected App that you created in
Salesforce into the Title and Name fields of the AEM Configuration modal. Leave the modal open.
6. Navigate back to the Connected App page in Salesforce.
7. In Callback URL, enter the AEM URL with Administrator Access: http://localhost:4502/etc/
cloudservices/salesforce/testsalesforceconnect.html where testsalesforceconnect is
the title of your Cloud Services connection.
8. Navigate back to the Connected App page and paste the URL into the Callback URL field.
9. Click Save.
10. From the Connected App record page, copy the Consumer Key.
11. Return to the AEM modal and paste the Consumer Key into the Customer Key field.
12. From the Connected App record page, copy the Consumer Secret.
13. Return to the AEM modal and paste the Consumer Secret into the Customer Secret field.
14. Click Connect to Salesforce. This brings you to a login screen for Salesforce. Log in to the
appropriate org and click Allow. A modal window will pop up indicating that the connection was
successful. If you receive an error, wait 10 minutes and attempt to connect again.
15. Click Ok to save the settings.
What's Next
Deploy OmniOut to Adobe Experience Manager
See Also
• Add the Vlocity LWC OmniOut Component to Adobe Experience Manager
• OmniOut
What's Next
Deploy OmniOut to Adobe Experience Manager
See Also
• OmniOut
• Add OmniScripts to Adobe Experience Manager
1. In VisualStudio, open the OmniOut resource and locate the ./aem.ui.apps/pom.xml file.
2. In the ./aem.ui.apps/pom.xml file, enter your AEM server username, password, host, and port in
these tags:
• <crx.host></crx.host>: Enter your AEM server host.
• <crx.port></crx.port>: Enter your AEM server port.
• <crx.username></crx.username>: Enter your AEM server username.
• <crx.password></crx.password>: Enter your AEM server password.
• <publish.crx.host></publish.crx.host>: Enter your AEM server host.
• <publsh.crx.port></publish.crx.port>: Enter your AEM server port.
• <publish.crx.username></publish.crx.username>: Enter your AEM server username.
• <publish.crx.password></publish.crx.password>: Enter your AEM server password.
Example Syntax: <crx.port>4502</crx.port>
3. Deploy the application by running this command:
What's Next
Add the Vlocity LWC OmniOut Component to Adobe Experience Manager
See Also
• OmniOut
• Integrate Salesforce Cloud Services into Adobe Experience Manager
1. From an AEM page, click on the + symbol to add a component. This opens a modal with a list of
components.
2. Select the Vlocity LWC OmniOut component.
3. From the component, click the configure icon, a wrench symbol, to open the component's Edit Dialog.
4. From the Vlocity LWC OmniOut Edit Dialog, configure these Vlocity LWC OmniOut component
options:
a. In Configuration, select the Salesforce cloud connection that connects your Salesforce
Connected App.
b. In Namespace, enter the namespace of your Vlocity package. See Viewing the Namespace and
Version of the OmniStudio Vlocity Package.
c. In LWC Element Name, enter the name of your OmniScript using the component tag name
without brackets.
For example, if your OmniScript had these properties:
• Type: doc
• SubType: Test
• Language: English
The correct syntax to use is vlocityomniscript-doc-test-english.
d. In Layout, select the Lightning or Newport design system.
e. (Optional) In Prefill Attribute, enter serialized JSON data to prefill elements.
f. (Optional) In Google Maps API Key, enter a Google Maps API Key if one is used in your
OmniScript.
g. (Optional) Check Use Proxy if your application is using a proxy to connect to your Salesforce
instance.
h. (Optional) In Proxy URL, enter your proxy URL.
i. (Optional) Check Use Local Definition to use the local OmniScript definition. The component will
not verify if the OmniScript is active in your Salesforce org.
j. (Optional) Check Load SLDS Resources to load SLDS styles, images, and icons into your
OmniScript. This option is required if you use File or Image in your OmniScript.
k. (Optional) Check Load Newport Resources to load Newport styles into your OmniScript.
l. (Optional) Check Load PDF Resources if you are using a PDF Action in your OmniScript.
5. Save your component and publish your AEM application.
6. Test your AEM application and run the OmniScript.
See Also
• OmniOut
• Run OmniOut in Development Mode
Custom styling done within the OmniScript Designer for a custom LWC or within the FlexCard designer on
any element is included in the downloaded off-platform LWC.
1. In Salesforce Setup's Quick Find box, enter Static Resources, and click Static Resources.
2. Locate and click the static resource that contains your CSS style sheet.
3. Click View File to download the static resource.
4. Copy the downloaded file into your app's primary styles folder.
5. Add a reference to that file in your app's index.html file to load the custom style sheet.
Example
What's Next
Connect Your OmniOut App
See Also
• OmniOut
• Create a Connected App for OmniOut
View the connection object template and sample apps in this section to see examples of how to configure a
connection.
1. (Optional) Download, run, and modify sample OmniOut apps. See Sample OmniOut Apps.
2. Create a Connection Object in OmniOut
1. Select a sample app from the table on this page to download and run the connection example.
What's Next
Create a Connection Object in OmniOut. If your OmniOut project has FlexCards only, see Create a
Connection Object in OmniOut for FlexCards.
npm install
4. Open ./src/App.js, and in the jsforce.browser.init object, locate these keys and set them equal
to the appropriate values:
Key Value
clientId The Connected App's Consumer Key. See Create a Connected App for OmniOut.
redirectUri The Connected App's redirect URL. See Create a Connected App for OmniOut.
5. Open ./src/connection.js, locate the namespace key, and enter your package namespace as the
value. For information on finding your namespace, see Viewing the Namespace and Version of the
OmniStudio Vlocity Package.
6. In the Visual Studio Code terminal, run this command to run the sample application at localhost:3000:
npm start
7. From the navigation bar, click the Login button, enter your credentials, and click Allow to log in to the
org.
8. After logging in, from the navigation bar, click the Quote link to view an example OmniScript.
9. From the navigation bar, click the Contact link to view an inline OmniScript example.
What's Next
Modify a Sample OmniOut for OmniScripts React App
See Also
1. From Salesforce Setup, enter Static Resources into the Quick Find box, and click Static
Resources.
2. From Static Resources, click vlocityomnioutlwcsample.
3. Click View File to download the sample app.
4. Uncompress the downloaded file and open it in Visual Studio Code.
5. Locate the README.MD file, click it, and follow the README's instructions.
Download and Run the OmniOut for FlexCards LWC Sample App
View a sample OmniOut with a FlexCard that uses only Lightning web components to run a single page
app off-platform.
For a sample OmniOut with an OmniScript, see Download and Run the OmniOut LWC Sample App.
1. From Salesforce Setup, enter Static Resources into the Quick Find box, and click Static
Resources.
2. From Static Resources, click vlocityomnioutflexcardslwcsample.
3. Click View File to download the sample app.
4. Uncompress the downloaded file and open it in Visual Studio Code.
5. Locate the README.MD file, click it, and follow the README's instructions.
The React app acts as the frontend of your website while the express app handles the backend calls. Each
sample application has separate dependencies you need to install to run them both together.
npm install
4. Open the ./app.js file, locate these keys, and set them equal to the appropriate values:
Key Value
namespace The namespace of your Vlocity managed package. See Viewing the Namespace and Version of the
OmniStudio Vlocity Package.
instanceUrl The instanceUrl retrieved from your Connected App. See Create a Connected App for OmniOut.
accessToken The accessToken retrieved from your Connected App. See Create a Connected App for OmniOut.
5. In the Visual Studio Code terminal, run this command to start the application:
npm start
6. In a browser, go to localhost:3001 to view the application.
npm install
3. Open the ./src/connection.js file, locate these keys, and set them equal to the appropriate values:
Key Value
_proxyUrl http://localhost:3001/api. This is the URL where your express backend is located.
instanceUrl The instanceUrl retrieved from your Connected App. See Create a Connected App for OmniOut.
namespace The namespace of your Vlocity managed package. See Viewing the Namespace and Version of the
OmniStudio Vlocity Package.
4. In the Visual Studio Code terminal, run this command to start the application:
npm start
5. In a browser, go to localhost:3000 to view the application.
6. From the navigation bar, click the Quote link to view an example OmniScript.
7. From the navigation bar, click the Contact link to view an inline OmniScript example.
What's Next
Modify a Sample OmniOut for OmniScripts React App
See Also
NOTE
The instructions on this page don’t apply to the LWC Sample App because the LWC
Sample app is a standalone app. See Download and Run the OmniOut LWC Sample App.
1. In your OmniOut project, run the command npm run build in your Visual Studio Code terminal. The
command compiles OmniOut into a dist folder.
2. In the dist folder, copy the files your OmniScript requires to run from the OmniOut project to the
sample app's ./public folder.
4. In the dist folder's index.html file, copy your OmniScript component tag.
<vlocityomniscript-doc-example-english run-mode="localScriptDef"></
vlocityomniscript-doc-example-english>
5. In the sample app's ./src/pages/Quote.js or ./src/pages/Contact.js files, replace the existing sample
component tag with your OmniScript component tag.
npm start
See Also
If your OmniOut project has OmniScripts in it, you must create an event handler to pass the connection
object after receiving OmniOut's omnioutcomponentready event. Follow the directions on this page.
If your OmniOut project has FlexCards only, use the initializeDatasourceSdk method to connect your app.
See Create a Connection Object in OmniOut for FlexCards.
The templates on this page are examples that developers can use for reference material when building a
connection.
NOTE
The connection process is unique to each application and must be done outside the scope
of OmniOut.
/**
* Once the component is ready, an event is dispatched to let the DOM
knows that a connection is expected.
**/
document.addEventListener('omnioutcomponentready', evt => {
if (evt.detail && evt.detail.omnioutcomponent) {
evt.srcElement.connection = new YourOmniOutConnection();
}
});
2. Create a connection object.
Example Connection Object
function BaseConnectionExample() {
/**
* Expose the request method
**/
this.request = request;
/**
* @type {string} The namespace of the package
**/
this.namespace = '';
/**
* @type {string} The instance URL of your org
**/
this.instanceUrl = '';
/**
* A function that executes the HTTP requests.
* @type {string} The target URL.
* @type {Object} The data that is sent to the target URL.
* @returns {Promise} A promise with the
**/
function request(url, data) {
return connection.requestPost(url, data);
}
}
3. Configure additional connection options outside of OmniOut.
See Also
• OmniOut
• Connect Your OmniOut App
• Create a Connected App for OmniOut
If your OmniOut project has OmniScripts only, or OmniScripts and FlexCards, create an event handler to
pass the connection object after receiving OmniOut's omnioutcomponentready event. See Create a
Connection Object in OmniOut.
If your OmniOut project has FlexCards, you must use the initializeDatasourceSdk method to connect your
app. Follow the directions on this page.
The template on this page is an example that developers can use for reference material when building a
connection.
NOTE
The connection process is unique to each application and must be done outside the scope
of OmniOut.
setConnection();
function setConnection() {
initializeDatasourceSdk({
jsforceConnection: connection,
instanceUrl: "https://login.salesforce.com",
namespace: "acme"
});
}
2. Configure additional connection options outside of OmniOut.
See Also
• OmniOut
• Connect Your OmniOut App
• Create a Connected App for OmniOut
OmniStudio DataRaptors
A DataRaptor is a mapping tool that enables you to read, transform, and write Salesforce data. There are
four types of DataRaptor: Turbo Extract, Extract, Transform, and Load.
• Turbo Extract: Read data from a single Salesforce object type, with support for fields from related
objects. Then select the fields to include. Formulas and complex field mappings aren’t supported. See
DataRaptor Turbo Extract Overview.
• Extract: Read data from Salesforce objects and output JSON or XML with complex field mappings.
Formulas are supported. See DataRaptor Extract Overview.
• Transform: Perform intermediate data transformations without reading from or writing to Salesforce.
Formulas are supported. See DataRaptor Transform Overview.
• Load: Update Salesforce data from JSON or XML input. Formulas are supported. See DataRaptor Load
Overview.
DataRaptors typically supply data to OmniScripts, Integration Procedures, and Cards, and write updates
from OmniScripts, Integration Procedures, and Cards to Salesforce. A typical data flow is as follows:
Both Extract and Load DataRaptors can handle custom data formats. DataRaptors can access external
objects and custom metadata as well as sObjects. No special syntax or additional configuration is required.
NOTE
Although Apex classes can read, write, and transform data, they take longer to create and
are harder to maintain than DataRaptors. Therefore, use of DataRaptors is a best practice.
A DataRaptor Turbo Extract has two advantages over a standard DataRaptor Extract:
• Simpler configuration
• Better performance at runtime
1. Go to the OmniStudio DataRaptor tab and click New. The Create DataRaptor Interface dialog is
displayed.
2. Specify configuration settings as follows:
• DataRaptor Interface Name: Descriptive name, displayed on the OmniStudio DataRaptor tab's list
of DataRaptors.
• Interface Type: Turbo Extract
• Input Type: JSON (for OmniScripts), XML, or Custom
• Output Type: JSON (for OmniScripts) or Custom
• Required Permission (Optional): Specifies an optional comma-separated list of Custom
Permission names. To run this DataRaptor, a user must have one of these permissions. If this setting
is blank, any user can run this DataRaptor unless a DefaultRequiredPermission is set.
If specified, this setting overrides the DefaultRequiredPermission setting, which provides a default if
no Required Permissions value is set. See Security for DataRaptors and Integration Procedures.
Custom Permissions for users are defined in Salesforce Profiles or Permission Sets.
• Description: Optional high-level overview of the DataRaptor.
3. Click Save. The designer page is displayed.
1. On the Extract tab, in the topmost field, select the source Salesforce object type, for example, Contact.
2. In the next field, specify the Extract Output Path.
This value is typically the same as the source object name. It specifies the top-level JSON node in the
output.
3. Specify at least one Filter, which determines the data to be read. The item on the left is a field of the
source object type. The item in the middle is a comparison operator. The item on the right can be a
quoted literal value, an input parameter, or another field of the same source object. To filter for null
values, use the $Vlocity.NULL variable.
You can use fields in related objects in filters, such as Parent.Name, but you have to enter them
manually. For details about the notation, see Relationship Notation versus Multiple Extract Steps.
The most basic filter is Id = Id, which sets the Id of the object to an input parameter named Id.
The INCLUDES and EXCLUDES operators apply only to multi-select picklist fields. See Querying
Multi-Select Picklists in Salesforce Help.
Turbo extracts have an operator option no other DataRaptors have: IN. The IN operator lets you match
values to items in an array. For example, if the filter is LastName IN Names, and the JSON input is
{"Names": ["Miller", "Torres"]}, records with Miller or Torres in their LastName fields are
retrieved.
To download a DataPack of this example, click here.
4. Configure optional additional filter settings by clicking the down arrow to the right of the first filter:
• AND - Add another filter and specify that both filters must be true.
• OR - Add another filter and specify that either filter can be true.
• LIMIT - Specify the maximum number of records returned. Allowed values are 1 through 2000.
For more information, see Workaround for offset 2000 limit on SOQL query in the Salesforce
knowledge base.
• OFFSET - Use with LIMIT to specify the first record on a page in a multi-page retrieval. For example,
a LIMIT of 5 requires OFFSET values of 0, 5, 10, and so on.
• ORDER BY - Sort the results by the specified field. To sort by multiple fields, specify a comma-
separated list of field names in order of precedence, for example LastName,FirstName.
You can optionally specify ASC or DESC for an ascending or descending sort. You can optionally
specify NULLS FIRST or NULLS LAST to place blank values at the beginning or end. For example,
you can sort Accounts by the number of employees, listing the companies of unknown size first and
the largest employers last. Specify the ORDER BY value NumberOfEmployees ASC NULLS
FIRST.
5. Select the fields to extract by moving them from the left list to the right list. You can enter a search
value to filter the left list. The Id field is always included in the output.
To select fields in related objects, see the next section.
6. Configure optional additional settings on the Options tab:
• Check Field Level Security: Checks the user's access permissions for the fields before executing
the DataRaptor. Enabling this setting disables the Org Cache but not the Session Cache.
• Time To Live In Minutes: If data caching is enabled, determines how long data remains in the
cache. The minimum value is 5.
• Salesforce Platform Cache Type: Enables data caching. Set to Session Cache for data related to
users and their login sessions, or to Org Cache for all other types of data. See Cache for
DataRaptors and Integration Procedures.
7. To observe the effects of caching when testing the DataRaptor Turbo Extract, go to the Preview tab
and deselect the Ignore Cache checkbox. See Cache for DataRaptors and Integration Procedures.
For more information about relationship names and other relevant topics, see Relationship Queries in
Salesforce Help. DataRaptors support only child-to-parent relationship queries.
When you click the Related Objects dropdown list, relationships to other objects appear, for example:
If you select one of those relationships and click the list again, second-level relationships to other objects
appear, for example:
To back up a level, click the list and select the previous level, for example:
After you’ve selected a relationship with another object, fields in that object appear in the left field-selection
list. You can enter a search value and move the fields to the right list as you would the base object fields.
The Response panel displays the resulting data, and the Debug Log panel displays the results of the
Salesforce queries issued by the DataRaptor.
For example, if the DataRaptor filters Accounts based on an Id, a Key/Value pair like this lets you test the
DataRaptor using a specific Account Id.
8. Go to the Preview tab. If you see an Edit as Params link, click it.
9. Click Add New Key/Value Pair. Specify AccountId as the Key and an Account Id from your org as
the Value.
10. Click Execute. Note that FirstName, LastName, and Id are retrieved for each Contact.
3. Determine whether you need multiple extract steps or relationship notation. See When to Use Multiple
Extract Steps and Relationship Notation versus Multiple Extract Steps.
4. (Optional) Add data using formulas. See Use Formulas in DataRaptors.
5. Compose the output. See Defining the Output of an Extract.
6. Test the DataRaptor. See Test a DataRaptor Extract.
1. Go to the OmniStudio DataRaptor tab and click New. The Create: DataRaptor Interface dialog is
displayed.
2. Specify configuration settings:
• DataRaptor Interface Name: Descriptive name, displayed on the OmniStudio DataRaptor tab's list
of DataRaptors.
• Interface Type: Extract
• Input Type: JSON (for OmniScripts), XML or Custom
• Output Type: JSON (for OmniScripts), XML or Custom
• Required Permission: Specifies an optional comma-separated list of Custom Permission names. To
run this DataRaptor, a user must have one of these permissions. If this setting is blank, any user can
run this DataRaptor unless a DefaultRequiredPermission is set.
If specified, this setting overrides the DefaultRequiredPermission setting, which provides a default if
no Required Permissions value is set. See Security for DataRaptors and Integration Procedures.
Custom Permissions for users are defined in Salesforce Profiles or Permission Sets.
When an Integration Procedure calls a DataRaptor, the Required Permission setting of the
Integration Procedure overrides the Required Permission setting of the DataRaptor.
• Description: Optional high-level overview of the DataRaptor.
3. Click Save. The Extract tab of the designer page is displayed.
What's Next
Define the Initial Extraction
1. Click Add Extract Step and choose the source object from the drop-down list of objects.
2. Configure settings for the source object:
• Extract Output Path: The top-level node in the extraction step JSON where you want the data to
reside.
Best practice: When possible, name the Extract Output Path for the Salesforce object that is its
data source. This defines the first node of the Extract JSON Path field values on the Output tab.
• Filter: The comparison used to determine what data is to be read. The item on the left is a field of
the source object. The item in the middle is a comparison operator. The item on the right can be a
quoted literal value, an input parameter, another field of the same source object, or a field of a
source object in a previous extract step. To filter for null values, use the $Vlocity.NULL variable.
You can use fields in related objects in filters, such as Parent.Name, but you have to enter them
manually. For details about the notation, see Relationship Notation versus Multiple Extract Steps.
The most basic filter is Id = Id, which sets the Id of the object to an input parameter named Id.
The INCLUDES and EXCLUDES operators apply only to multi-select picklist fields. See Querying
Multi-Select Picklists in the Salesforce help.
3. Configure optional additional filter settings by clicking the down arrow to the right of the first filter:
• AND: Add an additional filter and specify that both filters must be true.
• OR: Add an additional filter and specify that either filter can be true.
• LIMIT: Specify the maximum number of records returned. Allowed values are 1 to 2000.
For more information, see Workaround for offset 2000 limit on SOQL query in the Salesforce
knowledge base.
• OFFSET: Use with LIMIT to specify the first record on a page in a multi-page retrieval. For example,
if the LIMIT is 5, the OFFSET values for successive pages would be 0, 5, 10, and so on.
• ORDER BY: Sort the results by the specified field. To sort by multiple fields, specify a comma-
separated list of field names in order of precedence, for example LastName,FirstName.
You can optionally specify ASC or DESC for an ascending or descending sort. You can optionally
specify NULLS FIRST or NULLS LAST to place blank values at the beginning or end. For example,
to sort Accounts by the number of employees, listing the companies of unknown size first and the
largest employers last, specify the ORDER BY value NumberOfEmployees ASC NULLS FIRST.
NOTE
If you need to implement paging logic for your application, you can use the filter
OFFSET setting to specify where record retrieval starts. Choose OFFSET from the
drop-down list and specify the name of a node in the input payload where the caller
maintains the offset. The offset must be an integer. Note that Salesforce imposes a
2000-record limit on queries. For details, see the Salesforce OFFSET documentation.
What's Next
When to Use Multiple Extract Steps
1. Extracting data from a single object type, for example, Cases, requires only one extract step.
2. Extracting data from a primary object and one or more parent objects also requires only one extract
step. An example is extracting Cases with some Account data for each Case. See Relationship
Notation versus Multiple Extract Steps.
3. Extracting data from a primary object and one or more child objects requires at least two extract steps,
one for each object type. An example is extracting an Account and all the Cases associated with that
Account.
For example, to find Cases by Case Number, you can use a filter such as CaseNumber = Number in the
extract step:
The objects are queried in the order that you specify them in extract steps, which is important for the third
scenario, when you need to use data from a previously-read object to filter a subsequent object.
For example, to find all the cases associated with a specific account, you can read the account with a basic
filter such as Id = Id in the first extract step, then read the cases with a filter such as AccountId = Acct:Id in
the second extract step. (The AccountId is a Case field; the Acct:Id is a reference to the Id field of the
Account.)
This data is read into the extraction step JSON, and the Extract Step JSON pane on the right shows the
top-level hierarchy defined by the output paths that you specify on this tab.
By default, if a value is null, no node is created for the field in the output JSON. To ensure that a node is
created, regardless of whether the field is null, go to the Options tab and check Overwrite Target For All
Null Inputs.
What's Next
Relationship Notation versus Multiple Extract Steps
Relationship notation in DataRaptors is based on relationship queries in Salesforce. For more information
about relationship names and other relevant topics, see Relationship Queries in the Salesforce help.
DataRaptors support only child-to-parent relationship queries.
Suppose you want to retrieve Contact data that includes the name of the Account with which the Contact is
associated. (Account is a parent object of Contact.) You can use multiple extract steps or relationship
notation.
To use multiple extract steps, first define extraction steps for Contact and Account objects on the
DataRaptor's Extract tab.
Then define Extract JSON Paths for the Contact and Account fields on the DataRaptor's Output tab.
To use relationship notation, first define an extraction step for the Contact object on the DataRaptor's
Extract tab.
Then Define Extract JSON Paths for the Contact and Account fields on the DataRaptor's Output tab.
Note that the Extract JSON Path for the Name field of the Account object is Account.Name. Account is
the name of the relationship that the Contact object has with the parent Account object. The relationship
name is different from the name of the field that references the parent object, which is AccountId. Most
relationship names for standard objects follow this convention and omit the Id suffix.
If you supply a Contact Id on the Preview tab, you get the same Response for that Contact for both
DataRaptors:
{
"CompanyName": "Acme",
"LastName": "Tomlin",
"FirstName": "Leanne"
}
However, if you look in the Debug Log, you see two SOQL queries for the DataRaptor that uses multiple
extract steps:
SELECT id, accountid, firstname, lastname, name FROM Contact WHERE (Id =
'0031U00000HUob9QAD')
SELECT id, name FROM Account WHERE (Id = '0011U00000KbYZAQA3')
You see only one SOQL query for the DataRaptor that uses relationship notation:
IMPORTANT
Running only one SOQL query per primary object is always noticeably faster than running
two. A DataRaptor performs processing steps for each SOQL query that it runs, and
Salesforce contributes overhead for each SOQL query as well. With one query rather than
two, you have half the overhead.
What's Next
Defining the Output of a DataRaptor Extract
The Current JSON Output pane displays the structure that your output mappings specify.
Best practice: When possible, name the Extract Output Path on the Extract tab for the Salesforce object
that is its data source. This defines the first node of the Extract JSON Path field values.
You can improve DataRaptor performance for some use cases by using relationship notation in the Extract
JSON Path field. See Relationship Notation versus Multiple Extract Steps.
You can also use formulas to add output data. For details, see Use Formulas in DataRaptors and Function
Reference.
• Drag and drop: Drag the source sObject field from the left column to the target output field in the middle
column, or vice-versa. For an output that has no source sObject field, drag the output mapping to the
Matched Mappings column.
• Pair: Select an input field and an output field and click Pair.
• Auto Match: Click Auto Match. Fields with matching names are matched automatically.
To redefine values after they are read from Salesforce, go to the Transform Map Values section and add
key/value pairs that specify the input and output values. For example, to transform an input value of TRUE
to an output value of Y (for yes), specify KEY = TRUE and VALUE = Y.
TIP
To make mapping a large number of fields easier, paste the data JSON from the calling
OmniScript or Integration Procedure into the Expected JSON Output pane, which
populates the list of paths in the Output JSON Path field.
Null Values
To specify a value to be output when the field is null, set the Default Value property. To override the default
data type, specify Output Data Type. To prevent data loss, choose compatible data types.
For example, if a text value always contains numeric data, a numeric output type is fine. If it might contain
alphabetic characters, you must choose a textual output data type.
By default, if a value is null, no node is created for the field in the output JSON. To ensure that a node is
created, regardless of whether the field is null, go to the Options tab and check Overwrite Target For All
Null Inputs.
Object:JsonField__c:JsonNode:ChildJsonNode
Translations
To configure the DataRaptor to retrieve translated Product data, go to the Options tab and check Use
Translations.
When this option is enabled, the DataRaptor returns string translations for the user's locale. If no string
translations are defined for the locale, the product data defined in the base language is returned. For
example, if the base product data is entered in English and no French string translations are defined, users
with a French locale see English product data.
• Check Field Level Security: Checks the user's access permissions for the fields before executing the
DataRaptor. Enabling this setting disables the Org Cache but not the Session Cache.
• Overwrite Target For All Null Inputs: Ensures that an output node is created regardless of whether a
field is null.
• Use Translations: Configures a DataRaptor to retrieve translated Product data.
• Time To Live In Minutes: If data caching is enabled, determines how long data remains in the cache.
The minimum value is 5.
• Salesforce Platform Cache Type: Enables data caching. Set to Session Cache for data related to
users and their login sessions, or to Org Cache for all other types of data. See Cache for DataRaptors
and Integration Procedures.
List Maps
To map data into a list in the output, use the listname|# syntax.
The listname specifies the key of the output node and the # specifies the position in the list where the
output resides. Note the pipe (|) symbol separator. The following example illustrates how to map a flat set
of input nodes to an output list.
For more about lists in DataRaptors, see List Input for DataRaptors.
What's Next
Test a DataRaptor Extract
The Response panel displays the resulting data, and the Debug Log panel displays the results of the
Salesforce queries issued by the DataRaptor.
For example, if the DataRaptor filters Accounts based on an Id provided by an OmniScript, a Key/Value pair
such as the following enables you to test the DataRaptor using a specific Account Id.
For additional examples that show how you can improve DataRaptor performance for some use cases
using relationship notation, see Relationship Notation versus Multiple Extract Steps.
{
"Account": {
NOTE
In this example, it’s especially important to specify the complete object hierarchy in the
Extract Output Path, filter, and Extract JSON Path values. Accounts and Contacts are
directly related and related through Cases. This example uses the latter relationship. The
object hierarchy tells the DataRaptor which relationship to use.
1. Go the OmniStudio DataRaptor tab and click New. The Create dialog is displayed.
2. Specify a name for the DataRaptor and configure its settings:
• Interface Type — Extract
• Input Type — JSON
• Output Type — JSON
3. Click Save. The DataRaptor Interface page is displayed.
4. On the Extract tab, add three extract steps:
{
"Account": {
"Case": {
"CaseNumber": "Text",
"Contact": {
"Name": "Text"
},
"Subject": "Text"
},
"Name": "Text"
}
}
{
"Account": {
"Case": [
{
"Contact": {
"Name": "Edward Stamos"
},
"Subject": "Cannot track our order",
"CaseNumber": "00001004"
},
{
"Contact": {
"Name": "Leanne Tomlin"
},
"Subject": "Wrong size widgets",
"CaseNumber": "00001003"
},
{
"Contact": {
"Name": "Jeff Hunt"
},
"Subject": "Update account phone number",
"CaseNumber": "00001005"
},
{
"Contact": {
"Name": "Edward Stamos"
},
"Subject": "Billing status",
"CaseNumber": "00001006"
}
],
"Name": "Acme"
}
}
• Use the ORDER BY setting to sort the data based on a specific field.
• Use the LIMIT setting to specify how many records to retrieve at a time.
• After retrieving each set of records, use the sort field value from the last record retrieved to retrieve the
next set.
1. Go the OmniStudio DataRaptor tab and click New. The Create dialog is displayed.
2. Specify a name for the DataRaptor and configure its settings as follows:
• Interface Type: Extract
• Input Type: JSON
• Output Type: JSON
3. Click Save. The DataRaptor Interface page is displayed.
4. On the Extract tab, specify Account as the object and Id > lastAccountId as the filter. Use the
down arrow on the right to add Id as the ORDER BY field and a LIMIT value of 2.
6. Go to the Preview tab. If you see an Edit as Params link, click it.
7. In the Input Parameters pane, click Add New Key/Value Pair. Enter lastAccountId as the Key and
001000000000000 as the Value. Click Execute.
The second page of Account records is retrieved. Repeat this step to retrieve the next page.
• Use the LIMIT setting to specify how many records to retrieve at a time.
• Use the OFFSET setting to specify a multiple of the LIMIT value.
• Optional but recommended for predictable results: use the ORDER BY setting to sort the data based on
a specific field.
1. Go the OmniStudio DataRaptor tab and click New. The Create dialog is displayed.
2. Specify a name for the DataRaptor and configure its settings as follows:
• Interface Type: Extract
• Input Type: JSON
• Output Type: JSON
3. Click Save. The DataRaptor Interface page is displayed.
4. On the Extract tab, specify Contact as the object and DoNotCall = "false" as the filter. Use the
down arrow on the right to add LastName as the ORDER BY field, a LIMIT value of 3, and an OFFSET
value of AfterRecord.
5. On the Output tab, map the name and phone fields as shown.
6. Go to the Preview tab. If you see an Edit as Params link, click it.
7. In the Input Parameters pane, click Add New Key/Value Pair. Enter AfterRecord as the Key and 0
(zero) as the Value. Click Execute.
The second page of Contact records is retrieved. Repeat this step, incrementing the AfterRecord
value by 3 each time, to retrieve the remaining pages.
You can traverse up to five levels of relationships using relationship notation. For example, the syntax for
going up two levels is parent.grandparent.field, and for three levels, parent.grandparent.great-
grandparent.field.
For custom fields, the relationship name matches the name of the field that references the parent object,
except that the relationship name ends with __r instead of __c.
1. Define an extraction step for the Contract object on the DataRaptor's Extract tab as follows:
2. Define Extract JSON Paths for the Contract Number, Active Contract Version Name, and Created By
Name fields on the DataRaptor's Output tab as follows:
Note that the Extract JSON Path for the Name field of the vlocity_cmt__ContractVersion__c object is
vlocity_cmt__ActiveContractVersionId__r.Name. The name of the relationship that the
Contract object has with the parent vlocity_cmt__ContractVersion__c object is
vlocity_cmt__ActiveContractVersionId__r. The second-level relationship name is
CreatedBy. Depending on your industry, the namespace might be vlocity_cmt, vlocity_ins, or
vlocity_ps.
3. Supply a Contract Number on the Preview tab. You get a Response such as this one:
{
"Creator": "Vlocity Admin",
"Version": "Version 1",
"Number": "00000105"
}
4. See the SOQL query in the Debug Log. It looks like this:
DataRaptor Transforms are essential for OmniScripts that must populate a DocuSign template (see
Creating a DataRaptor Interface to Map an OmniScript to DocuSign ) or fill fields in a PDF document (see
Creating a DataRaptor Interface to Map an OmniScript to a PDF).
You can also transform data in many ways using Set Values components in Integration Procedures. See
Set Values for Integration Procedures.
1. Go to the OmniStudio DataRaptor tab and click New. The Create: DataRaptor Interface dialog is
displayed.
2. Specify configuration settings as follows:
• DataRaptor Interface Name: Descriptive name, displayed on the OmniStudio DataRaptor tab's list
of DataRaptors.
• Interface Type: Transform
• Input Type: JSON (for OmniScripts), XML or Custom
• Output Type: JSON (for OmniScripts), XML, PDF, DocuSign, Document Template, or Custom
• Required Permission: Specifies an optional comma-separated list of Custom Permission names. To
run this DataRaptor, a user must have one of these permissions. If this setting is blank, any user can
run this DataRaptor unless a DefaultRequiredPermission is set.
If specified, this setting overrides the DefaultRequiredPermission setting, which provides a default if
no Required Permissions value is set. See Security for DataRaptors and Integration Procedures.
Custom Permissions for users are defined in Salesforce Profiles or Permission Sets.
When an Integration Procedure calls a DataRaptor, the Required Permission setting of the
Integration Procedure overrides the Required Permission setting of the DataRaptor.
• Description: Optional high-level overview of the DataRaptor.
3. Click Save. The Transforms tab of the designer page is displayed.
What's Next
DataRaptor Transform Data Mappings
You can map data on the Transforms tab in one of two ways:
• If the input and output names match, Use Quick Match to Map Data.
• Specify each mapping individually.
Both ways apply to JSON input and output and to other input and output types.
The following example shows JSON input being mapped to XML output. All incoming fields are renamed.
The incoming top case fields, which are all top-level fields, are reparented under an XML node named
XCASEDETAILS. The list of contacts is unchanged. Note the difference between the representation of a list
in JSON and in XML. For details about converting between JSON and XML, see XML in DataRaptors.
For the PDF, DocuSign, and Document Template output types, output mappings are generated based on
the fields in the Target Output file you selected when you created the DataRaptor Transform.
By default, if a value is null, no node is created for the field in the output JSON. To ensure that a node is
created, regardless of whether the field is null, go to the Options tab and check Overwrite Target For All
Null Inputs.
To replace one value with another, open the mapping and create entries in the Transform Map Values list.
For example, if the incoming field contains TRUE or FALSE and your OmniScript requires a Y or N value,
create the following entries:
Data Caching
You can configure optional caching settings on the Options tab:
• Time To Live In Minutes: If data caching is enabled, determines how long data remains in the cache.
The minimum value is 5.
• Salesforce Platform Cache Type: Enables data caching. Set to Session Cache for data related to
users and their login sessions, or to Org Cache for all other types of data. See Cache for DataRaptors
and Integration Procedures.
What's Next
Test a DataRaptor Transform
NOTE
Some transforms are too complex for Quick Match. For example, see List Input for
DataRaptors.
1. Expand the Input JSON pane and paste the input data structure into it.
2. Expand the Expected JSON Output pane and paste the desired output structure into it.
3. Click Quick Match. The Quick Match window opens.
4. Click Auto Match, or drag each Input Mapping onto the desired Output Mapping.
Another option is to select an Input Mapping and an Output Mapping, then click Pair.
5. Click Save. The Quick Match window closes and the Transforms tab shows the individual mappings.
6. Look at the structure in the Current JSON Output pane. Make sure it matches the structure in the
Expected JSON Output pane.
XML in DataRaptors
In addition to JSON, DataRaptors can have XML input and output. The XML format in DataRaptors is an
unordered key/value, JSON-like structure.
To specify the order in which the elements of the XML output are serialized, populate the Expected XML
Output pane with an XML structure that is composed in the desired order.
JSON
{
"Root": {
"#text": "rootValue",
"@attribute1": "attVal1",
"#ns": "http://namespace1",
"#ns#a": "http://namespace2",
"Child": [{
"@attribute2": "attval2"
},
{
"#text": "childValue"
}
]
}
}
XML
DataRaptors that transform XML to JSON use the following conventions to handle the differences between
the formats.
For additional DataRaptor Transform examples, see List Input for DataRaptors and Create a DataRaptor
Example with a Formula.
1. Go the OmniStudio DataRaptor tab and click New. The Create dialog is displayed.
2. Specify a name for the DataRaptor and configure its settings as follows:
{
"Contact": {
"Id": "0036100000423z8AAA",
"FirstName": "Amy",
"LastName": "Smith"
}
}
5. Click the + icon and add the following mapping:
• Input JSON Path — Contact
• Output JSON Path — Contacts
• Output Data Type — List<Map>
Note that you only have to create a mapping for the top-level node.
6. Expand the Current JSON Output pane. Its contents should look like this:
{
"Contacts": [
{}
]
}
7. Go to the Preview tab and click Execute. The Response should look like this:
{
"Contacts": [
{
"LastName": "Smith",
"FirstName": "Amy",
"Id": "0036100000423z8AAA"
}
]
}
1. Go the OmniStudio DataRaptor tab and click New. The Create dialog is displayed.
2. Specify a name for the DataRaptor and configure its settings as follows:
• Interface Type — Transform
• Input Type — JSON
• Output Type — JSON
3. Click Save. The Transforms tab of the DataRaptor Interface page is displayed.
4. Go to the Formulas tab. In the Formula field, enter ObjectList:Property. In the Formula Result
Path field, enter FormulaList.
5. Go to the Transforms tab. Expand the Input JSON pane and paste the following JSON data into it:
{
"ObjectList": [
{
"Property": "P9034"
}
]
}
6. Expand the Expected JSON Output pane and paste the following JSON data into it:
{
"PropertyValueList": [
"P9034"
]
}
7. Click the + icon and add the following mapping:
• Input JSON Path — FormulaList
• Output JSON Path — PropertyValueList
Note that you only have to create a mapping between the top-level nodes.
8. Expand the Current JSON Output pane. Its contents should look like this:
{
"PropertyValueList": "Text"
}
9. Go to the Preview tab and paste the following JSON data into the Input pane:
{
"ObjectList": [
{
"Property": "P9034"
},
{
"Property": "P6538"
},
{
"Property": "P1234"
},
{
"Property": "P5678"
},
{
"Property": "P2345"
},
{
"Property": "P7654"
}
]
}
{
"PropertyValueList": [
"P9034",
"P6538",
"P1234",
"P5678",
"P2345",
"P7654"
]
}
11. Add or subtract list items in the JSON data in the Input pane and click Execute again. Note that the
output changes accordingly.
For example, when a user running a case-handling OmniScript finishes entering data and clicks Save, the
script calls a DataRaptor Load to record the data entered.
A DataRaptor Load can obtain its input data in the following ways:
To modify the input data, you can define formulas, transform values, and change the output data type. (See
Use Formulas in DataRaptors.) To specify how the resulting data is to be written to Salesforce objects, you
map fields from the output JSON to fields in Salesforce objects. (See Object Field Mapping.) When
invoked, the DataRaptor Load applies its mappings and formulas to the input data to create the output data.
Then it loads the output data into Salesforce objects according to the mappings.
• Use Assignment Rules: Use assignment rules for sObjects such as Cases that have user
assignment fields. For more information, see Set Up Assignment Rules in the Salesforce
documentation.
If emails are configured in Case assignment rules, checking this option automatically sends emails to
users when Cases are assigned.
• Overwrite Target For All Null Inputs: If an input doesn't have a value, set the corresponding output
value to NULL.
What's Next
Object Field Mapping
Object:JsonField__c:JsonNode:ChildJsonNode
4. Repeat these steps for each field.
If you are updating multiple Salesforce objects, the designer displays a separate tab for the mappings of
each target object. See Multiple Related Object Loads (Link Mappings).
Mapping Options
To control how the update is performed, you can configure the following optional settings:
• Default Value: Value to be loaded if the field in the DataRaptor output JSON is null. To specify an empty
string for string fields that are null, enter a pair of double quotes (""). Omit if Is Required for Upsert is
enabled.
What's Next
Test a DataRaptor Load
To link the Account to its Contact, the DataRaptor must perform the following sequence of operations:
To handle this type of relationship, link the objects in the DataRaptor Designer as follows:
1. On the Objects tab, navigate to the source object (Contact in the preceding example) and click Add
Link.
2. For each field you want to link, configure settings as follows:
• Domain object field: The source field from this object (AccountId in the preceding example).
• Linked object: Another object in the sequence (Account in the preceding example).
• Field list: The target field in the linked object (Id in the preceding example).
For example, to create a Case with a new Account and Contact associated, link the objects as shown in the
following figure. The Contact is associated with the account by AccountId, and the case is associated with
the contact by ContactId.
For an example that uses link mapping, see Create a Contact for an Existing Account.
The Objects Created panel lists the resulting objects, which are saved permanently. The Debug Log panel
displays the results of the Salesforce queries issued by the DataRaptor.
The input JSON for this DataRaptor Load contains the Contact details, for example:
{
"ContactDetails": {
"Birthdate": "10/10/1954",
"LastName": "Singh",
"Telephone": "5106345789",
"FirstName": "Sanjay"
}
}
1. If your org Contact object does not have an Authorized field, add one (checkbox). In the following
example, the authorized field is called Authorized__c. Depending on your industry, you might need to
add a vlocity_cmt__, vlocity_ins__, or vlocity_ps__ namespace prefix.
2. Navigate to the OmniStudio DataRaptor tab and click New. The Create: DataRaptor Interface dialog
is displayed.
3. Enter settings as follows and click Save:
• DataRaptor Interface Name: A descriptive name of your choice
• Interface Type: Load
• Input Type: JSON
• Output Type: SObject
4. On the Objects tab, click Add Object and choose Contact.
5. On the Fields tab, map fields from the JSON input to fields in the Salesforce Contact object as shown
in the following table.
Depending on your industry, you might need to add a vlocity_cmt__, vlocity_ins__, or vlocity_ps__
namespace prefix.
ContactDetails:Birthdate Birthdate
ContactDetails:FirstName FirstName
ContactDetails:LastName LastName
ContactDetails:Telephone Phone
6. On the Formulas tab, click Add Formula and enter a Formula of
IF(AGE(ContactDetails:Birthdate) > 18, "true", "false") and a Formula Result Path
of ContactDetails:Authorized as shown in the following figure.
{
"ContactDetails": {
"Birthdate": "10/10/1954",
"LastName": "MyLastName",
"Telephone": "5106345789",
"FirstName": "MyFirstName"
}
}
9. Click Execute. If the load succeeds, a link to the object is displayed in the Objects Created pane, as
shown in the following figure.
10. Click the link and verify that the Authorized checkbox is checked only if the contact is over 18 years
old.
The input JSON for this DataRaptor Load contains the Account Id and the Contact name, for example:
{
"AccountId": "0016100001BKL4uAAH",
"Name": {
"First": "Jane",
"Last": "Doe"
}
}
1. Navigate to the OmniStudio DataRaptor tab and click New. The Create: DataRaptor Interface dialog
is displayed.
2. Enter settings as follows and click Save:
• DataRaptor Interface Name: A descriptive name of your choice
• Interface Type: Load
• Input Type: JSON
• Output Type: SObject
3. On the Objects tab, click Add Object and choose Account.
4. Click Add Object again and choose Contact.
• 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 Relationship Notation versus Multiple Extract Steps.
• Try to keep the number of SObjects to three or fewer.
• Ensure that all filtering and sorting (ORDER BY) operations are on indexed fields. The Id and Name
fields are always indexed. For more information, see Indexes in Salesforce Help.
• Use caching to store frequently accessed, infrequently updated data. See Cache for DataRaptors and
Integration Procedures.
To determine whether a DataRaptor or an Integration Procedure is best for your use case, see DataRaptor
or Integration Procedure?.
For example, the following lists are valid, and each can be converted to the other.
List 1:
{
"Oldest": "Huey",
"Middle": "Dewey",
"Youngest": "Louie"
}
List 2:
{
"Nephews": [
{
"Name": "Huey"
},
{
"Name": "Dewey"
},
{
"Name": "Louie"
}
]
}
List 1 lacks a JSON node for the list as a whole, and each value has a different key. List 2 has its own
JSON node, and each list item has the same key.
NOTE
Loop Block components in Integration Procedures require input that is structured like List
2. The list-item key itself can contain key-value pairs. For examples, see Process Arrays
Using Loop Blocks.
To convert List 1 to List 2, use the following mappings on the Transforms tab of a DataRaptor Transform.
The |1, |2, and |3 are list position indexes.
To download DataPacks of DataRaptor Transforms for these mappings, click these links:
List 3:
{
"Nephews": [
"Huey",
"Dewey",
"Louie"
]
}
To convert List 2 to List 3, and to perform such conversions of lists of any length, see Convert a List of
Objects to a List of Values.
See Also
• AVG, FILTER, IF, LIST, LISTMERGE, LISTMERGEPRIMARY, LISTSIZE, MAX, MIN, SORTBY, and SUM
functions in the Function Reference
• Process Arrays Using Loop Blocks in Integration Procedures
• List Action for Integration Procedures in Integration Procedures
• Integration Procedure Action for Integration Procedures in Integration Procedures (the example
transforms a list)
For details about the operators and functions that you can use in formulas, see Function Reference.
To create a formula:
NOTE
If a variable name contains spaces or non-alphanumeric characters, enclose the variable
name in double quotes and precede it with var: in formulas. For example, if the JSON
node name is Primary Guardian, specify it in formulas as var:"Primary
Guardian".
If the name of a custom field includes special characters, sometimes you can't reference
the field in a formula.
See Also
• Create a DataRaptor Example with a Formula
1. Go the OmniStudio DataRaptor Designer tab and click New. The Create dialog is displayed.
2. Specify a name for the DataRaptor and configure its settings as follows:
• Interface Type: Transform
• Input Type: JSON
• Output Type: JSON
3. Click Save. The DataRaptor Interface page is displayed.
4. Go to the Formulas tab and click Add Formula.
5. In the Formula field, enter SUM(Products:Price).
6. In the Formula Result Path field, enter TotalPrice.
7. On the Transforms tab, expand the Input JSON pane and paste this JSON structure into it:
{
"CustomerName": "Bob Smith",
"Products": [
{
"Name": "iPhone",
"Price": 600
},
{
"Name": "iPhone Case",
"Price": 30
},
{
"Name": "Ear Buds",
"Price": 200
}
]
}
8. Expand the Expected JSON Output pane and paste this JSON structure into it:
{
"CustomerName": "Bob Smith",
"TotalPrice": 830,
"Products": [
{
"Name": "iPhone",
"Price": 600
},
{
"Name": "iPhone Case",
"Price": 30
},
{
"Name": "Ear Buds",
"Price": 200
}
]
}
9. Click Quick Match. In the Quick Match window, click Auto Match, then click Save.
10. On the Preview tab, click Execute.
If you have built the example correctly, the JSON structure in the Response pane matches the
Expected JSON Output except for the order of the top-level nodes.
11. In the Input pane, change one or more of the prices, then click Execute again.
Note how the TotalPrice value changes.
See Also
• Use Formulas in DataRaptors
• Boolean
• Currency: Converts to Currency using the Salesforce org's currency code.
• CurrencyRounded: Converts to Currency, rounds the number, and removes the decimals.
• Double
• Integer
• JSON: Serialize as JSON. Omit if the transform output type is JSON unless you must embed JSON in
JSON (unlikely)
• List<Double>
• List<Integer>
• List<Map>: Converts Map<String,Object> to List<Map<String, Object>>
• List<String>
• Number
• Number(3): Converts to a number with decimals where the decimal precision is specified in parentheses.
For example, the output type Number(3) would output a number with three decimals.
• Object: Deserializes a String as Map<String, Object> or List<Object>
• String
• Multi-Select: Convert to Salesforce multi-select string (semicolon-delimited list)
• Date: Details in the following table.
NOTE
If you cast a list of values to a primitive type like Double, Integer, String, or Boolean, only
the first element of the list is output.
To format output date-time values, use the date-time templates supported by Oracle Java. The format of the
input date must be ISO-compliant (YYYY-MM-DD hh:mm:ss) and the time must be GMT. Specify the format
as a string argument to the DATE() output data type, for example:
Here are examples of different output formats for the same date-time value.
Format Output
Date(MM/dd/YYYY) (default) 07/04/2001
Date("yyyy.MMMMM.dd GGG hh:mm aaa") 2001.July.04 AD 12:08 PM
Date("EEE, d MMM yyyy HH:mm:ss Z") Wed, 4 Jul 2001 12:08:56 +0000
NOTE
The Salesforce Workbench REST Explorer is a useful testing tool.
Example
POST Data
{
"bundleName" : "AccountUpload",
"objectList" : {
"Agency Information": {
"Agency Name": "Vlocity",
"Agency Address": "50 Fremont",
"Agency City": "San Francisco",
"Agency State": "CA",
"Agency Zip": "94110",
}
},
"bulkUpload" : false
}
Result
{
"createdObjectsByOrder": {
"Open Account": {
"1": [
"a10o00000022xVEAAY" ]
}
},
"createdObjectsByType": {
"Open Account": {
"Account": [
"a10o00000022xVEAAY" ]
}
},
"errors": {},
"returnResultsData": []
}
/services/apexrest/myOrgNamespace/v2/DataRaptor/DataRaptorName/Id
Example Request
The following request uses the Id of a Contact to retrieve all open Cases for the Contact. Note that the %20
HTML URL encoding represents a space in the DataRaptor name.
GET /services/apexrest/vlocity_cmt/v2/DataRaptor/Open%20Cases/a10o00000022xVE
Example Result
{
"Contact": {
"Contact Name" : "Dennis Reynolds",
"Case Information": [
{
"Title": "Wrong widget shipped..."},
{
"Title": "Overcharged for gizmo..."},
{
"Title": "Damaged item..."}
]
}
}
GET /services/apexrest/<myOrgNamespace>/v2/DataRaptor/<DataRaptorName>/?$
{Param1}=${Val1}&${Param2}=${Val2}...
Example Request
The following request passes the first and last name of a contact as input parameters to a DataRaptor
extract, which uses them to query for the cases opened by the contact.
GET /services/apexrest/vlocity_cmt/v2/DataRaptor/Open_Cases/?
FirstName=Dennis&LastName=Reynolds
/services/apexrest/vlocityNamespace/v2/DataRaptor/
• For a JSON object, use Map<String, Object>. Set the String to the JSON key and the Object to the
JSON value.
• For an array of JSON objects, use List<Map<String, Object>>. Set the String to the JSON key and
the Object to the JSON value.
• As an alternative, you can specify the input as a string containing the JSON input required by the
DataRaptor.
For details about the methods of the DRGlobal class, which offer multiple ways to call DataRaptors, see
DRGlobal Class and Methods.
To process the results returned by a DataRaptor extract or transform in Apex, use the toJsonList()
method to deserialize the output to a Map<String, Object> or List<Map<String, Object>>. To
determine which type to use, check the data type of the response.
DataRaptor loads return JSON containing data about the Salesforce objects that were created or updated
by the operation. To process the results returned by a DataRaptor load, deserialize the output to a map.
From the resulting map, you can extract data about the objects that were created and any errors that
occurred. The DataRaptor load example below shows how to access this data from the result map.
Object>)createdObjectsByType.get('Create Contracts');
Map<String, Object> createdObjectsByOrder = (Map<String,
Object>)resultMap.get('createdObjectsByOrder');
Map<String, Object> errors = (Map<String, Object>)resultMap.get('errors');
Map<String, Object> errorsByField = (Map<String,
Object>)resultMap.get('errorsByField');
Map<String, Object> errorsAsJson = (Map<String,
Object>)resultMap.get('errorsAsJson'); // Returns input JSON plus per-node
errors
In all the method signatures shown below, the namespace is vlocity_cmt, vlocity_ins, or
vlocity_ps. The bundleName is the DataRaptor name.
Method Names
processObjectsJSON
Signature:
processObjects
Signatures:
String bundleName)
static namespace.DRProcessResult processObjects(List<SObject> objectList,
String bundleName, Map<String, Object> additionalInfo)
static namespace.DRProcessResult processObjects(List<SObject> objectList,
String bundleName, Map<String, Object> additionalInfo, Map<String, Object>
filesMap)
The first signature, which doesn't require a DRName, is only for a DataRaptor Load.
The additionalInfo is a Map that applies to every SObject, such as extra data for processing.
pprocessString
Signature:
processFromApex
Signatures:
These methods ignore Sharing Rules, which ensures that the DataRaptor being invoked is private. See
Sharing Rules in the Salesforce help.
process
Signatures:
processPost
Signature:
This method can only call a DataRaptor Load. No other Apex method can pass the bulkUpload
parameter to a DataRaptor. See DataRaptor Calls From Apex.
clearCacheForDataRaptor, clearCacheForAllDataRaptor
For details about these methods, see Cache for DataRaptors and Integration Procedures.
For example, the following filter extracts the Cases created in the last 30 days.
If you are using an environment variable as a Filter value, you must double-quote it.
To configure a DataRaptor to use a custom input or output, set its type to Custom and specify the class that
contains the serialize and/or deserialize methods that perform the operation. The following figure shows a
DataRaptor Transform configured with a custom input and output.
For ease of mapping, you can paste sample input into the Expected Input and Expected Output fields.
The following example shows the basic structure of a customer serialization/deserialization class.
/*
Serializes Apex objects into JSON content. return String json
Example Input:
[
{
"Column1Test": "value1.0",
"Column2Test": "value0"
},
{
"Column1Test": "value1.1sl",
"Column2Test": "value0.1"
}
]
Example Output: 'Column2,Column1\nvalue0,value1.0\nvalue0.1,value1.1';
*/
global Boolean serialize(Map<String, Object> input, Map<String, Object>
output)
{
Object inputValue = input.get('input');
String returnValue = '';
if (inputValue == null)
{
return false;
}
if (inputValue InstanceOf Map<String, Object>)
{
inputValue = new List<Object>{inputValue};
}
if (inputValue InstanceOf List<Object> &&
((List<Object>)inputValue).isEmpty())
{
List<Object> rows = (List<Object>)inputValue;
if (!rows.isEmpty())
{
Set<String> columns = ((Map<String,
Object>)rows[0]).keySet();
for (String col : columns)
{
if (String.isNotBlank(returnValue))
{
returnValue = returnValue + ',' + col;
}
else
{
returnValue = returnValue + col;
}
}
if (!columns.isEmpty())
{
returnValue = returnValue + '\n';
}
for (Integer i = 0; i < rows.size(); i++)
{
for (String col : ((Map<String,
Object>)rows[i]).keySet())
{
if (String.isNotBlank(returnValue) && !
(returnValue.length()-1 == returnValue.lastIndexOf('\n')))
{
returnValue = returnValue + ',' + ((Map<String,
Object>)rows[i]).get(col);
}
else
{
returnValue = returnValue + ((Map<String,
Object>)rows[i]).get(col);
}
}
returnValue = returnValue + '\n';
}
output.put('output', returnValue);
return true;
}
}
return false;
}
/*
Deserializes the specified JSON string into collections of primitive data
types. return Object ((Map<String, Object>))
Input: 'Column2,Column1\nvalue0,value1.0\nvalue0.1,value1.1';
Output:
[
{
"Column1Test": "value1.0",
"Column2Test": "value0"
},
{
"Column1Test": "value1.1sl",
"Column2Test": "value0.1"
}
]
*/
• DataRaptor metadata is automatically cached unless you turn off the Scale Cache.
• You can configure data caching on the Options tab of DataRaptor Extracts, Turbo Extracts, and
Transforms.
• If you call a DataRaptor from an Integration Procedure that uses caching, the DataRaptor data is cached
along with the Integration Procedure data.
You can also perform a record-level security check for cached data. See Security for DataRaptors and
Integration Procedures.
To disable metadata caching for an Integration Procedure, go to the Procedure Configuration and check the
Disable Definition Cache checkbox.
TIP
To test the performance benefit of metadata caching, execute the Integration Procedure in
the Preview tab with Disable Definition Cache checked and then unchecked. Compare
the Browser, Server, and Apex CPU values.
Behind this checkbox is the DisableDefinitionCache__c boolean field, which defaults to false.
namespace.DRGlobal.clearCacheForDataRaptor('DataRaptorName');
vlocity.cmt.DRGlobal.clearCacheForAllDataRaptor();
You can clear Integration Procedure metadata from the cache. Follow the instructions in this topic, but
execute this line of code instead, specifying the Integration Procedure's Type and Subtype:
IntegrationProcedureService.clearMetadataCache('Type_Subtype');
You can clear all cached data for an Integration Procedure, including session cache data, org cache data,
and metadata. Follow the instructions in this topic, but execute this line of code instead, specifying the
Integration Procedure's Type and Subtype:
IntegrationProcedureService.clearAllCache('Type_Subtype');
If you must clear DataRaptor data from the Scale Cache, follow the instructions in this topic, but execute a
line of code in this form instead:
namespace.ScaleCacheService.invalidateCacheValue(new Map<String,
String>{'DataRaptorId' =>
DataRaptor_Name});
For example, to clear data from a DataRaptor named ExtractContactName, use this line of code:
omnistudio.ScaleCacheService.invalidateCacheValue(new Map<String,
String>{'DataRaptorId' =>
'ExtractContactName'});
If you must clear Integration Procedure data from the Scale Cache, follow the instructions in this topic, but
execute a line of code in this form instead:
namespace.ScaleCacheService.invalidateCacheValue(new Map<String,
String>{'VIPId' =>
Type_SubType});
omnistudio.ScaleCacheService.invalidateCacheValue(new Map<String,
String>{'VIPId' =>
'LoopList_ContactNames'});
See Also
• Turn Off the Scale Cache
IMPORTANT
Guest Users, also called anonymous users, cannot access any records by default. Criteria-
based Sharing Rules grant them read-only access. This affects all Salesforce orgs. For
details, see Guest User Record Access Development Best Practices.
Vlocity allows guest users to create and update the records to which Sharing Rules grant
access. No additional configuration is necessary for this expanded access.
You can use Salesforce Sharing Settings to secure access to DataRaptors and Integration Procedures. If
you use caching, you must set CheckCachedMetadataRecordSecurity to true as described here.
You can allow access to a DataRaptor or Integration Procedure based on the Custom Permissions enabled
in a user's Salesforce Profiles or Permission Sets. An Apex class added to your Salesforce Org allows the
Vlocity Managed Package to check user Custom Permissions. The custom settings described here are
related to this approach. Vlocity recommends using Custom Permissions in Profiles or Permission Sets for
ease of use and better performance.
For Salesforce access basics, see Control Who Sees What, Who Sees What — Overview Video, and
Salesforce Data Security Model — Explained Visually.
Sharing Settings, Sharing Sets, Profiles, and Permission Sets control access to DataRaptors and
Integration Procedures as object records. To enforce field-level security in the data that DataRaptors
access, go to the DataRaptor's Options tab and select Check Field Level Security.
IMPORTANT
A user's access to a DataRaptor or Integration Procedure includes more than the ability to
run it directly. Access also applies if an application the user is using calls the DataRaptor
or Integration Procedure.
If a user has access to a parent Integration Procedure, the parent can invoke child
Integration Procedures and DataRaptors to which the user doesn’t have direct access.
For a list of settings, see DataRaptor and Integration Procedure Security Settings.
1. Go to Setup.
• In Lightning Experience, click the gear icon and select Setup from the menu.
• In Salesforce Classic, click the user menu and select Setup from the menu.
2. In the Quick Find box, type omni, then select Omni Interaction Configuration.
3. Click New Omni Interaction Configuration.
4. In the Label field, type the name of the setting.
5. In the Value field, type a valid value for the setting.
6. Click Save.
To configure these settings, see Configure DataRaptor and Integration Procedure Security Settings.
For DefaultRequiredPermission details, see DataRaptor and Integration Procedure Security Settings.
OmniStudio Integration Procedures are declarative, server-side processes that execute multiple actions in a
single server call. Integration procedures can read and write data from Salesforce and from external
systems (using REST calls) and can call Apex code. An Integration Procedure can be called from an
OmniScript, an API, or an Apex method, and can be a data source for a FlexCard.
Integration Procedures are optimal when you need to access and transform data from third-party sources
and no user interaction is required, and moving the workload from client to server is desirable.
Integration Procedures can do some things that OmniScripts can't, the most important of which is list
processing with Loop Blocks and List Actions. Integration Procedures can perform more data processing
steps than DataRaptors can, and they're more flexible than Calculation Procedures.
TIP
You can watch a video that shows how to create an Integration Procedure.
The following diagram shows the relationship between an OmniScript and an Integration Procedure that it
calls.
See Also
• Integration Procedure Best Practices
• DataRaptor or Integration Procedure?
• OmniScript Action Elements Reference
For step-by-step details of how to build Integration Procedure examples, see the block and action topics
under Group Integration Procedure Steps Using Blocks and Integration Procedure Actions.
TIP
You can watch a video that shows how to create an Integration Procedure.
• chainable: Enable or disable chaining during execution, to prevent a long-running procedure from
exceeding Salesforce governor limits. For details about chaining, see Settings for Long-Running
Integration Procedures.
• resetCache and ignoreCache: Enable or disable caching features. For details about caching, see
Cache for DataRaptors and Integration Procedures.
Merge fields access data JSON using syntax to indicate to an Integration Procedure element that a merge
field is present. The syntax requires you to wrap a full JSON path with a percent sign on both ends.
NOTE
Only certain element properties support merge fields.
1. Locate the name of the JSON node in the Integration Procedure's data JSON.
2. Enter the name of the JSON node and wrap the name in percentage signs to indicate it's a merge field.
For example, a merge field accessing a JSON node named firstName must use the syntax
%firstName%.
3. Preview the Integration Procedure to ensure the merge field works correctly.
Additional Syntax
This table provides additional syntax examples for nested JSON.
• Conditional Block — Executes the block if a specified condition is true, or treats the steps within it as a
series of mutually exclusive alternatives. This is the most basic block type.
• Cache Block — Saves the output of the steps within it to a session or org cache for quick retrieval.
• Loop Block — Repeats the steps within it for each item in an array.
• Try-Catch Block — Returns specified output or calls an Apex class if a step within it fails.
You can nest blocks within other blocks. For example, you can nest a Loop Block within a Try-Catch Block
or a Cache Block.
All blocks have one property in common: Execution Conditional Formula. If this formula evaluates to true
or is not defined, the block is executed. If it evaluates to false, the block is skipped.
To control whether an individual action executes, you set its Execution Conditional Formula to an
expression that can be evaluated as True or False. If the expression evaluates to True at run time, the step
is executed.
To conditionalize the execution of a group of actions, place them inside any block and set the Execution
Conditional Formula of the block. If the formula evaluates to True at run time, the actions in the block are
executed. If an action in a block has its own Execution Conditional Formula, it is executed only if its
formula evaluates to True at run time.
The Conditional Block is the simplest block type. Unless you check Is If Else Block, it has no inner logic. It
either executes or it doesn't according to its Execution Conditional Formula.
See Also
• Conditional Block Properties
• Create a Conditional Block Example with If-Elseif-Else Logic
Property Description
Execution Conditional Specifies that the entire Conditional Block runs only if this formula evaluates to true.
Formula
Is If Else Block Specifies that all actions within the block except optionally the last have mutually exclusive Execution
Conditional Formula values. If the last action has a blank Execution Conditional Formula, it runs only if
the Execution Conditional Formula values of all the other actions evaluate to false.
See Also
4. Drag a Set Values component into the Conditional Block and give it the following settings:
a. Set its Element Name to IfCA.
b. Under Element Value Map, click Add Value. Set the Element Name to CASalesTax and the
Value to 0.0866.
c. Set the Response JSON Path to CASalesTax.
d. Set the Response JSON Node to SalesTax.
These Response settings copy the CASalesTax value to a top-level JSON node named
SalesTax. A top-level node isn't tied to a particular step. This allows any step to set its value. It
also allows any step to access its value using the same path, regardless of which step set its
value.
e. Set the Execution Conditional Formula to State == "CA".
5. Repeat the previous step to configure four more Set Values components inside the Conditional Block
with the following settings:
"elementValueMap": {
"Output": {
"Price": "%Price%",
"State": "%State%",
"Tax": "%CalculateTax:Tax%",
"TaxRate": "%CalculateTax:TaxRate%",
"Total": "%CalculateTax:Total%"
}
},
8. Drag a Response Action after the previous component and give it the following settings:
a. Set its Element Name to Response.
b. Set the Send JSON Path to AssembleOutput:Output.
c. Set the Send JSON Node to Output.
{
"Price": "250",
"State": "CA"
}
11. Click Execute. The output data has the following structure:
{
"Output": {
"Price": "250",
"State": "CA",
"Tax": 21.65,
"TaxRate": 8.66,
"Total": 271.65
}
}
12. Change Price and State values, click Execute, and see how the Output values change.
See Also
It's important to understand how top-level Integration Procedure caching interacts with Cache Blocks. See
Cache for DataRaptors and Integration Procedures.
A Cache Block saves the output of the steps within it to a session or org cache in the VlocityAPIResponse
cache partition for quick retrieval.
• ignoreCache — Doesn't clear or save data to the cache. The default value is true. Use this setting to
test Integration Procedure steps without the possible interference of caching effects.
• resetCache — Forces data to be saved to the cache. The default value is false. Use this setting as
part of testing caching itself.
NOTE
To test caching, be sure to set ignoreCache to false. See Create a Cache Block
Example.
You can pass ignoreCache and resetCache as parameters when you invoke an Integration Procedure that
uses caching using a REST API. For example, you can include ?resetCache=true in the URL to force
caching. See Integration Procedure Invocation Using POST.
These nodes are under the Info node for the Cache Block. For example, if the Cache Block is named
CacheBlock1, these nodes are under the CacheBlock1Info node. For example:
IntegrationProcedureService.clearSessionCache('vlcCacheKey');
IntegrationProcedureService.clearOrgCache('vlcCacheKey');
You can clear all cached data for an Integration Procedure, including session cache data, org cache data,
and metadata. Follow the instructions in this topic, but execute this line of code instead, specifying the
Integration Procedure's Type and Subtype:
IntegrationProcedureService.clearAllCache('Type_Subtype');
IntegrationProcedureService.clearOrgCache('LastNames_Cached', 'CacheContacts',
new Map<String, Object>{'ContactLastName' => 'Smith'});
The following example clears the session cache using a vlcCacheKey value:
IntegrationProcedureService.clearSessionCache('2032076016a1745801061oc');
See Also
• Cache Block Properties
• Create a Cache Block Example
Property Description
Salesforce Platform Specifies the cache type:
Cache Type
• Session Cache — For data related to users and their login sessions
• Org Cache — For all other types of data
Time To Live In Determines how long data remains in the cache. The minimum value is 5. Default and maximum values
Minutes depend on the cache type:
• Session Cache — The default value is 5. The maximum value is 480, equivalent to 8 hours. However, the
cache is cleared when the user's session expires.
• Org Cache — The default value is 5. The maximum value is 2880, equivalent to 48 hours.
Top-level caching overrides Cache Block caching for the duration of the top-level Time To Live In Minutes
value.
Cache Keys Configurable Key/Value pairs to be stored in the cache. Enter a Key and set the Value to the response of an
Action within the Cache Block. The value can use merge field syntax, percentage signs on either side of the
node name, to access that response. Cache keys are available, or scoped, only within the Cache Block.
Cache Block Output Configurable Key/Value pairs to be available to subsequent Integration Procedure steps. Enter a Key and set
the Value to the response of an Action within the Cache Block. The value can use merge field syntax,
percentage signs on either side of the node name, to access that response.
Refresh Cache If the formula evaluates to true, forces data to be saved to the cache.
Conditional Formula
Ignore Cache If the formula evaluates to true, neither clears nor saves data to the cache.
Conditional Formula
Add to Cache If the formula evaluates to true, saves data to the cache. If false, does not cache data.
Conditional Formula
Fail On Step Error If this box is checked in a step within the Cache Block and that step fails, no data is cached.
See Also
• Enhance Performance Using Cache Blocks
• Create a Cache Block Example
This Integration Procedure also includes a Loop Block; see Process Arrays Using Loop Blocks.
Property Value
Salesforce Platform Cache Type Org Cache
Time To Live In Minutes 5
Cache Keys contactId set to %ExtractContact:Contact:Id%
Property Value
Loop List names
Additional Loop Output ExtractContact set to %ExtractContact%
5. Create the DataRaptor Extract that the DataRaptor Extract Action calls, name it ExtractContactName,
and give it the following settings:
Tab Settings
Extract A Contact extract step set to Contact Name LIKE name
Output A mapping from Contact:Id to Contact:Id
If you aren't sure how to create a DataRaptor Extract, see the examples in DataRaptor Extract
Examples.
6. Drag a DataRaptor Extract Action inside the Loop Block and give it the following settings:
Property Value
Element Name ExtractContact
DataRaptor Interface ExtractContactName
Data Source names:name
Filter Value name
7. Drag a Response Action below the Loop Block and give it the following settings:
Property Value
Send JSON Path CacheBlock1
8. To test this Integration Procedure, on the Preview Tab, click Edit as JSON and provide input with the
following structure:
{
"names": [
{
"name": "Miller"
},
{
"name": "Torres"
}
]
}
11. Click Execute again. This step populates the cache, so the resulting Browser, Server, and Apex CPU
values should be similar to the previous values.
12. Click Execute a third time. This step uses the cached values, so the resulting Browser, Server, and
Apex CPU values should be noticeably less than the previous values.
13. To see the vlcCacheKey and vlcCacheResult nodes, open the Debug Log and scroll to the
CacheBlock1Info node.
See Also
The array input to the Loop Block is processed so that each iteration receives only one item in the array.
For example, suppose the array input looks like this:
{
"Products": {
"Ids": [
{
"Id": 1
},
{
"Id": 2
}
]
}
}
Each iteration of the Loop Block would receive input that looks like this:
{
"Products": {
"Ids": {
"Id": 1
}
}
}
The iteration input is the data to which Actions within the Loop Block have access.
NOTE
The Integration Procedure stops running and returns a response of { "Success":
"False" } if an Action that has Fail on Step Error checked fails.
4. Under the Loop Block property field labeled Loop Output, click Add Key/Value Pair to add Key-Value
pairs to set the response. The value field uses merge field syntax, meaning the node name of the
response set between two percentage signs, for example, %ResponseData:Names%.
5. (Optional) Add Conditional Logic to define when the Loop Block runs. For more information on
Conditional Logic, see Define Execution Logic Using Conditional Blocks.
For additional Loop Block examples, see Integration Procedure Action for Integration Procedures, Enhance
Performance Using Cache Blocks, and Cache for Top-Level Integration Procedure Data.
See Also
• Loop Block Properties
• Create a Loop Block Example that Retrieves Names
• Create a Loop Block Example that Creates Contacts
• Create a Loop Block Example that Concatenates List Items
Property Description
Loop List Accepts a JSON node containing an array.
Loop Output Configurable Key/Value pairs to be available to subsequent Integration Procedure steps. Enter a Key and set the
Value to the response of an Action within the Loop Block. The value can use merge field syntax, percentage signs
on either side of the node name, to access that response. By default, if no Key/Value pairs are specified, a
response of { "success": "OK" } is returned for each item processed in the array.
Use this property with care. It returns the data you request for every iteration. If the Loop Block iterates 1000
times, it returns 1000 responses. This property is most useful for debugging or returning a limited dataset.
Execution Controls whether the Loop Block executes based on an expression that evaluates to true or false.
Conditional
Formula
See Also
• A DataRaptor Extract that uses the LIKE operator to find names similar to those in the input, named
ExtractFirstNames
• A Response Action, named ResponseAction1
{
"names": [
{
"Name": "Miller"
},
{
"Name": "Torres"
}
]
}
You can provide this input to the Integration Procedure in one of two ways:
• In the Preview tab. Click Edit as JSON and paste it into the Input Parameters area.
• In a SetValues component that you drag into the Structure panel. Click Edit as JSON and paste it
into the elementValueMap node, replacing the default node value of {}.
4. Drag a Loop Block into the Structure panel and give it the following settings:
Property Description
Loop List Set this value to names if the input is in the Preview tab, or to SetValues1:names if the input is in a
SetValues component.
Additional Loop Set the Key to DataRaptorExtractAction1 and the Value to %DataRaptorExtractAction1% to
Output return all iterations of data generated by the DataRaptor Extract Action component.
5. Create the DataRaptor Extract that the DataRaptor Extract Action calls, name it ExtractFirstName, and
give it the following settings:
Tab Settings
Extract A Contact extract step set to Contact LastName LIKE Name
Output A mapping from Contact:FirstName to Name:First
If you aren't sure how to create a DataRaptor Extract, see the examples in DataRaptor Extract
Examples.
6. Drag a DataRaptor Extract Action component within the Loop Block and give it the following settings:
Property Description
DataRaptor Interface Set this value to ExtractFirstName.
Input Parameters: Set this value to names:Name if the input is in the Preview tab, or to SetValues1:names:Name if the
input is in a SetValues component.
Data Source
Input Parameters: Set this value to Name.
Filter Value
7. Drag a Response Action below the Loop Block and check Return Full Data JSON.
8. Click Execute on the Preview tab. The output should look something like this:
{
"response": {},
"ResponseAction1Status": true,
"LoopBlock1": [
{
"DataRaptorExtractAction1": {
"Name": [
{
"Last": "Miller",
"First": “Tom”
},
{
"Last": "Miller",
"First": “Sally”
}
]
},
"DataRaptorExtractAction1Status": true,
"LoopBlockIterationStatus": true,
"LoopBlockIterationIndex": 1
},
{
"DataRaptorExtractAction1": {
"Name": [
{
"Last": "Torres",
"First": “Maria”
},
{
"Last": "Torres",
"First": “Ricardo”
}
]
},
"DataRaptorExtractAction1Status": true,
"LoopBlockIterationStatus": true,
"LoopBlockIterationIndex": 2
}
],
"LoopBlock1Status": true,
"options": {
"chainable": false
},
"names": [
{
"Name": "Miller"
},
{
"Name": "Torres"
}
]
}
See Also
{
"AccountId": "0016100001BKL4uAAH",
"Contacts": [
{
"Name": {
"First": "John",
"Last": "Doe"
}
},
{
"Name": {
"First": "June",
"Last": "Doe"
}
}
]
}
You can provide this input to the Integration Procedure in one of two ways:
• In the Preview tab. Click Edit as JSON and paste it into the Input Parameters area.
• In a SetValues component that you drag into the Structure panel. Click Edit as JSON and paste it
into the elementValueMap node, replacing the default node value of {}.
4. Drag a Loop Block into the Structure panel and give it the following settings:
Property Description
Loop List Set this value to Contacts if the input is in the Preview tab, or to SetValues1:Contacts if the input is
in a SetValues component.
Additional Loop Set the Key to CreateContact and the Value to %CreateContact% to return all iterations of data
Output generated by the DataRaptor Post Action component.
5. To create the DataRaptor Load that the DataRaptor Post Action calls, create the second example in
DataRaptor Load Examples and name it NewContactForAccount.
6. Drag a DataRaptor Post Action component within the Loop Block and give it the following settings:
Property Description
Name Set this value to CreateContact.
DataRaptor Set this value to NewContactForAccount.
Interface
Additional Input Set the first Key to AccountId and its value to %AccountId%, or to %SetValues1:AccountId% if the
input is in a SetValues component.
Set the second Key to Name and its value to %Contacts:Name%, or to %SetValues1:Contacts:Name%
if the input is in a SetValues component.
7. Drag a Delete Action component within the Loop Block and give it the following settings:
Property Description
Name Set this value to DeleteContact.
Delete SObject: Set this value to Contact.
Type
Delete SObject: Set this value to %CreateContact:Contact_1:Id%.
Path To Id
8. Drag a Response Action below the Loop Block and check Return Full Data JSON.
9. Click Execute on the Preview tab. The output should look something like this:
{
"response": {},
"ResponseAction1Status": true,
"LoopBlock1": [
{
"CreateContact": {
"ActualTime": 793,
"CpuTime": 537,
"Contact_2": [
{
"UpsertSuccess": true,
"Id": "0034N00001qh5hVQAQ",
"AccountId": "0016100001BKL4uAAH",
"LastName": "Doe",
"FirstName": "John"
}
],
"Account_1": [
{
"UpsertSuccess": true,
"Id": "0016100001BKL4uAAH"
}
],
"error": "OK",
"responseType": "SObject"
},
"DeleteContactStatus": true,
"CreateContactStatus": true,
"LoopBlockIterationStatus": true,
"LoopBlockIterationIndex": 1
},
{
"CreateContact": {
"ActualTime": 1262,
"CpuTime": 799,
"Contact_2": [
{
"UpsertSuccess": true,
"Id": "0034N00001qh5hWQAQ",
"AccountId": "0016100001BKL4uAAH",
"LastName": "Doe",
"FirstName": "June"
}
],
"Account_1": [
{
"UpsertSuccess": true,
"Id": "0016100001BKL4uAAH"
}
],
"error": "OK",
"responseType": "SObject"
},
"DeleteContactStatus": true,
"CreateContactStatus": true,
"LoopBlockIterationStatus": true,
"LoopBlockIterationIndex": 2
}
],
"LoopBlock1Status": true,
"SetValues1": {
"Contacts": [
{
"Name": {
"Last": "Doe",
"First": "John"
}
},
{
"Name": {
"Last": "Doe",
"First": "June"
}
}
],
"AccountId": "0016100001BKL4uAAH"
},
"SetValues1Status": true,
"options": {
"chainable": false
}
}
See Also
To watch a video that shows how to create this Integration Procedure, click here.
{
"QuoteLineItems": {
"Ids": [
{
"Id": "0QL3h000000VF04GAG"
},
{
"Id": "0QL3h000000VEvlGAG"
}
]
}
}
{
"Output": "0QL3h000000VF04GAG_0QL3h000000VEvlGAG"
}
Property Description
Element Name Set this value to InitString.
Element Value Map, Element Name Click Add New Value and assign an Element Name of Blank.
Element Value Map, Value Leave this property blank.
Response JSON Path Set this value to Blank.
Response JSON Node Set this value to ConcatString.
This component creates an initially empty top-level JSON node named ConcatString. A top-level
node isn't tied to a particular step. This allows any step to set its value. It also allows any step to
access its value using the same path, regardless of which step set its value.
4. Drag a Loop Block into the Structure panel and give it a Loop List value of QuoteLineItems:Ids.
5. Drag a Set Values component into the Loop Block and give it the following settings:
Property Description
Element Name Set this value to ConcatListItem.
Element Value Map, Click Add New Value and assign an Element Name of Concat.
Element Name
Property Description
Element Value Map, Assign the following Value:
Value
=%ConcatString% + "_" + %QuoteLineItems:Ids:Id%
This formula concatenates the top-level ConcatString node and the current list value.
Response JSON Path Set this value to Concat.
Response JSON Node Set this value to ConcatString.
In combination with the Value formula, this adds the current list value to the top-level
ConcatString node.
6. Drag a Set Values component below the Loop Block and give it the following settings:
Property Description
Element Name Set this value to TrimUnderscore.
Element Value Map, Element Name Click Add New Value and assign an Element Name of Trim.
Element Value Map, Value Assign a Value of =SUBSTRING(ConcatString,1).
7. Drag a Response Action below the last Set Values component and give it the following settings:
Property Description
Send JSON Path Set this value to TrimUnderscore:Trim.
Send JSON Node Set this value to Output.
{
"QuoteLineItems": {
"Ids": [
{
"Id": "0QL3h000000VF04GAG"
},
{
"Id": "0QL3h000000VEvlGAG"
}
]
}
}
10. Click Execute. The output should look something like this:
{
"Output": "0QL3h000000VF04GAG_0QL3h000000VEvlGAG"
}
See Also
1. Drag a Try-Catch Block into the Structure panel and make sure its Fail on Block Error checkbox is
checked.
2. Configure the "catch" behavior — what the Try-Catch Block will do if a failure occurs. You can choose
one or both of these options:
• Under Failure Response, specify a key-value pair to return as the response. The value can be a
formula. In Spring '20 and later releases, the value can include merge fields.
• Under Custom Failure Response, specify a Remote Class and a Remote Method to execute an
Apex class. The Apex class must implement VlocityOpenInterface.
3. Drag substeps into the Try-Catch Block, and make sure the Fail on Step Error checkbox is checked
for each step that must trigger the "catch" behavior if it fails.
You can optionally specify a Failure Condition Formula, which evaluates to TRUE if a specific step
has failed to execute successfully.
See Also
Property Description
Fail on Block Error Specifies that if the Try-Catch Block fails, the entire Integration Procedure fails.
Failure Response A response to return if the Try-Catch Block fails. The value can be a formula.
A Try-Catch Block can have both a Failure Response and a Custom Failure Response.
Custom Failure A Remote Class and Remote Method of an Apex class to execute if the Try-Catch Block fails. The Apex class
Response must implement VlocityOpenInterface.
See Also
c. On the Fields tab, click the + icon and enter LastName as both the Input JSON Path and the
Domain Object Field.
If you aren't sure how to create a DataRaptor Load, see the examples in DataRaptor Load Examples.
5. Drag a DataRaptor Post Action component into the Try-Catch Block and give it the following settings:
a. Set the DataRaptor Interface to CreateContact.
b. Make sure the Fail on Step Error checkbox is checked.
6. Drag a Delete Action component after the Try-Catch Block. Under Delete SObject, set the Type to
Contact and the Path To Id to %DataRaptorPostAction1:Contact_1:Id%.
7. Drag a Response Action into the Structure panel as the last component and check the Return Full
Data JSON checkbox.
8. Go to the Preview tab and test the Integration Procedure:
a. Under Input Parameters, click Add New Key/Value Pair.
b. Set the Key to LastName and the Value to any name you like.
c. Click Execute.
The output should look something like this:
{
"response": {},
"ResponseAction1Status": true,
"DeleteAction1": [
{
"errors": [],
"success": true,
"id": "0034N00001rNgqqQAC"
}
],
"DeleteAction1Status": true,
"TryCatchBlock1": null,
"TryCatchBlock1Status": true,
"DataRaptorPostAction1": {
"ActualTime": 626,
"CpuTime": 345,
"Contact_1": [
{
"UpsertSuccess": true,
"Id": "0034N00001rNgqqQAC",
"LastName": "Aristotle"
}
],
"error": "OK",
"responseType": "SObject"
},
"DataRaptorPostAction1Status": true,
"options": {
"queueableChainable": false,
"ignoreCache": true,
"resetCache": false,
"chainable": false
},
"LastName": "Aristotle"
}
9. Make the Value blank and click Execute again. The output should look something like this:
{
"result": {
"failureResponse": "You must provide a last name."
},
"success": false
}
See Also
{
"response": {},
"ResponseAction1Status": true,
"TryCatchBlock1": null,
"TryCatchBlock1Status": true,
"DataRaptorExtractAction1": [
{
"ContactName": "Amy Argent"
},
{
"ContactName": "Amy Smith"
}
],
"DataRaptorExtractAction1Status": true,
"options": {
"queueableChainable": false,
"ignoreCache": true,
"resetCache": false,
"chainable": false
},
"Name": "Amy"
}
8. Change the Value to an uncommon name (or make it blank) and click Execute again. The output
should look something like this:
{
"result": {
"failureResponse": "Name Murgatroyd not found."
},
"success": false
}
See Also
To add an action, drag it from the palette into the Structure panel, then configure its properties. You can
edit, rename, move, and delete actions. You can also use blocks to group actions for conditional execution,
caching, list processing, and error handling.
For details about specific Integration Procedure actions, see the topics for the actions.
See Also
• Create an Integration Procedure
• Group Integration Procedure Steps Using Blocks
For details about the properties of specific actions, see the topics for the actions.
Property Description
Element Name Label of script element
Send JSON Path Trims the incoming JSON to the specified path before the action is executed. See Manipulate JSON with the
Send/Response Transformations Properties.
Send JSON Node Reparents the incoming JSON under the specified node. See Manipulate JSON with the Send/Response
Transformations Properties.
Response JSON After the action is executed, trims the output JSON to the specified path. See Manipulate JSON with the
Path Send/Response Transformations Properties.
Response JSON Reparents the output JSON under the specified node. To delimit the path, use colons; for example -
Node level1:level2:level3. See Manipulate JSON with the Send/Response Transformations Properties.
Send Only Additional If checked, accepts only the data in the Additional Input property.
Input
Additional Input Additional key/value pairs to be included in the input data JSON. Values can include formulas and merge
fields.
Return Only If checked, returns only the data in the Additional Output property.
Additional Output
Additional Output Additional key/value pairs to be returned in the output data JSON. Values can include formulas and merge
fields.
Send Only Failure If checked, returns only the Failure Response if the action fails.
Response
Failure Response Key/value pairs to be returned in the output data JSON if the action fails. Values can include formulas and
merge fields.
Execution Specifies a formula that runs before the step is executed. If the formula returns TRUE, the step is executed. If
Conditional Formula the formula returns FALSE, the step is not executed. If no formula is specified, the step is executed.
Property Description
Failure Conditional Specifies a custom failure condition that runs after the step is executed.
Formula
For example, if a DataRaptor Extract Action doesn't find any records, this isn't normally considered an error,
but you can use a Failure Conditional Formula to specify this condition. See the second example under
Handle Errors Using Try-Catch Blocks.
If the formula returns TRUE, execution of the step has failed and any key/value pairs configured in the Failure
Response list are added to the data JSON. For example, if the following JSON is returned:
{
"Result": {
"ErrorCode": "ERR-123",
"Success": "FALSE"
}
}
...the following settings catch the error and add the error code to the data JSON:
To create the Integration Procedure, go to the OmniStudio Integration Procedures tab and click New.
Provide an Integration Procedure Name, a Type, and a SubType, and click Save.
To create each component, drag a Set Values instance into the Structure panel and edit its first Element
Name property. For the last component, drag in a Response Action instead.
{
"Name": {
"FirstName": "John",
"LastName": "Smith"
},
"Finances": {
"GrossIncome": "100000",
"Expenses": "60000"
}
}
Note that the %LocationData:Code% merge field retrieves data from the previous component,
LocationData.
"elementValueMap": {
"Departments": [
"Sales",
"Development",
"Support",
"Training"
]
},
This component assigns a Department value of Development to anyone named John and a Department
value of Support to anyone not named John. Note that the second equal sign has spaces before and after
it.
"elementValueMap": {
"Output": {
"FullName": "%ConcatName:FullName%",
"Department": "%RetrieveDept:Department%",
"AfterTaxIncome": "%AfterTax:AfterTaxIncome%",
"NetIncome": "%CalculateNet:NetIncome%",
"Location": "%LocationData:Location%",
"LocationCode": "%TextWithCode:LocationCode%",
"FirstOfThisMonth": "%CalcFirstOfThisMonth:FirstOfThisMonth%"
}
},
What's Next
Test the Integration Procedure that Sets Values
See Also
• Set Values Properties for Integration Procedures
Property Description
Element Value Map: Element Name The JSON node for which value is to be set.
Element Value Map: Value The value to assign to the JSON node. Options:
See Also
• Set Values for Integration Procedures
• Common Integration Procedure Action Properties
{
"Name": {
"FirstName": "John",
"LastName": "Smith"
},
"Finances": {
"GrossIncome": "100000",
"Expenses": "60000"
}
}
4. Click Execute. The output data has the following structure:
{
"Output": {
"FullName": "John Smith",
"Department": "Development",
"AfterTaxIncome": 70000,
"NetIncome": 10000,
"Location": "San Francisco",
"LocationCode": "Code is 2345",
"FirstOfThisMonth": "2020-02-01"
}
}
See Also
See Also
• Assert Action Properties for Integration Procedures
• Test Procedures: Integration Procedures for Unit Testing
• Environment Variables in DataRaptors and Integration Procedures
Property Description
Assert Conditional Expression that tests results of previous steps and evaluates to true or false. If the result is false, the
Formula assertResult for the Assert Action is set to false. This sets the testResult for the Test Procedure to
failed.
Property Description
Assert Failure Message that explains why the test failed.
Message
Fail Test On Assert If checked, the Test Procedure stops and returns the result of the transaction if the Assert Conditional
Formula evaluates to false.
If not checked, the Test Procedure continues running even if the Assert Conditional Formula evaluates to
false.
See Also
See Also
• Chatter Action Properties for Integration Procedures
• Find the Id of a Community
• Workflow for Chatter Action Example
To obtain the Id for the Mentioned User Id, Subject Id, Image Id, or File Id property, go to the object's
record page and select the Id from the URL.
Property Description
Community Id Id of the Community to which to post.
Mentioned User Id User Id to mention in the post. Can be a single value or a JSON list.
Markup Type Leave blank or select Bold, Italic, or Underline to determine the style of the Text property.
Subject Id (Required) Id of the object that has the Chatter feed. Can be any object that supports Chatter feeds, such as
Account, Contact, User, or Group.
Image Id Id of a File object to be used as an image for the post. Can be a single value or a JSON list.
File Id Id of a File object to be included as an attachment to the post. Can be a single value or a JSON list.
Text Text of the post. Can include merge fields and HTML markup.
See Also
1. In Lightning Experience, click the gear icon. In Salesforce Classic, click the user menu. In either case,
select Developer Console from the menu.
2. Click the Query Editor tab near the bottom of the Developer Console window.
3. Enter the following query in the Query Editor pane:
The Ids and Names of all the Communities in the org are listed.
4. Find the Name of the Community, then copy its Id.
See Also
What's Next
Create the Integration Procedure with the Chatter Action
See Also
Property Value
Subject Id %SubjectId%
Mentioned User Id %UserIdList%
Image Id %ImageId%
Markup Type Italic
Text Here is the picture I mentioned. It has the Id %ImageId%.
4. Drag a Response Action into the Structure panel and check Return Full Data JSON.
5. Go to the Preview tab. Click Edit as JSON.
6. Paste JSON with this structure into the Input Parameters pane, substituting the Ids you collected in the
first set of steps:
{
"ImageId": "06961000005R9q1AAC",
"UserIdList": [
"0054N0000041jEvQAI",
"0054N0000041qUlQAI"
],
"SubjectId": "00561000000hjm3AAA"
}
7. Click Execute.
8. Go back to the People tab, then to the record page of the user you chose to receive the Chatter post.
9. Scroll down to the Chatter pane and click the Refresh icon to see the latest Chatter post.
See Also
For Integration Procedure examples that include at least one DataRaptor Extract Action, see Process
Arrays Using Loop Blocks and Handle Errors Using Try-Catch Blocks.
See Also
• DataRaptor Extract Action Properties for Integration Procedures
• DataRaptor Extract Overview
Property Description
DataRaptor Interface Name of DataRaptor Extract to run
DataRaptor Input Parameters: Data Source Name of data JSON node containing value to filter on
DataRaptor Input Parameters: Filter Value Value to match to qualify as an input parameter
Ignore Cache Disables caching in the DataRaptor Extract.
See Also
For Integration Procedure examples that include at least one DataRaptor Post Action, see Process Arrays
Using Loop Blocks and Handle Errors Using Try-Catch Blocks.
Although a DataRaptor post action primarily creates or updates sObjects, it also produces JSON output,
which you can view in the Debug log on the Preview tab. This is important when subsequent Integration
Procedure steps need to reference the sObjects.
In the JSON response returned by a DataRaptor post, node names are appended with the sequence
number of the DataRaptor step that created them. For example:
{
"Contact_1": [{
"Id": "0036A000002PeaAQAS",
"LastName": "Smith",
"UpsertSuccess": true
}],
"Attachment_2": [{
"Id": "00P6A000000EJ3RUAW",
"Name": "angular-route.min.js",
"ParentId": "0036A000002PeaAQAS",
"UpsertSuccess": true
}]
}
If the DataRaptor name is CreateContact, you can reference the Id of Contact_1 in the example using the
merge field %CreateContact:Contact_1:Id%.
See Also
Property Description
DataRaptor Interface Name of DataRaptor post to run.
See Also
See Also
Property Description
DataRaptor Interface Name of the DataRaptor transform to run.
Ignore Cache Disables caching in the DataRaptor Transform.
See Also
1. Create the DataRaptor Transform example described in Use Formulas in DataRaptors and name it
DRFormula1.
2. From the OmniStudio Integration Procedures tab, click New.
3. Provide an Integration Procedure Name, a Type, and a SubType, and click Save.
4. Drag a DataRaptor Transform Action component into the Structure panel and give it the following
settings:
Property Value
DataRaptor Interface DRFormula1
Send JSON Path Input
5. Drag a Response Action component into the Structure panel below the DataRaptor Transform Action
and give it the following settings:
Property Value
Send JSON Path DataRaptorTransformAction1:TotalPrice
{
"Input": {
"CustomerName": "Bob Smith",
"Products": [
{
"Name": "iPhone",
"Price": 600
},
{
Note that this is the same as the input for the DataRaptor Transform except that the entire structure is
wrapped in an Input node, which matches the Send JSON Path value of the DataRaptor Transform
Action.
8. Click Execute. The output should look like this:
{
"TotalPrice": 830
}
9. In the Input pane, change one or more of the prices, then click Execute again.
Note how the TotalPrice value changes.
See Also
The DataRaptor Turbo Action is exactly the same as the DataRaptor Extract Action in how it works. The
only difference is the type of DataRaptors the DataRaptor Interface property lists. For Integration
Procedure examples that include at least one DataRaptor Extract Action, see Process Arrays Using Loop
Blocks and Handle Errors Using Try-Catch Blocks.
See Also
Property Description
DataRaptor Interface Name of DataRaptor Turbo Extract to run
DataRaptor Input Parameters: Data Source Name of data JSON node containing value to filter on
DataRaptor Input Parameters: Filter Value Value to match to qualify as an input parameter
Ignore Cache Disables caching in the DataRaptor Turbo Extract.
See Also
Delete Action
Enable users to delete one or more sObject records by using the Delete Action. Use an Object's Record Id
to determine which record to delete. Vlocity recommends using a merge field in the Path to Id field that
refers to an Id or a list of Ids in the data JSON.
1. Preview the OmniScript and identify the JSON path for the record. For example, this data JSON
contains a list of Accounts:
For Integration Procedure examples that include a Delete Action, see Process Arrays Using Loop Blocks
and Handle Errors Using Try-Catch Blocks.
Property Description
Type Type of sObject record to delete. For example, Account is a Type of sObject.
Path to Id Path to the JSON node that contains the Id or list of Ids of the records to delete. Supports merge
syntax.
All Or None When checked, the operation fails if any of the records are not deleted.
Entity Is Deleted Message Message that displays when a record is deleted.
Delete Failed Message Message that displays when the action fails to delete a record.
Invalid Id Message Message that displays when an invalid Id is sent to the Delete Action.
Configuration Error Message Message that displays when the Delete Action has a configuration error.
Confirm Controls whether the modal displays.
Confirmation Dialog Message The Confirmation Modal's message text. The default message text is Are you sure? This
action cannot be undone.
Confirm Label Button label for the Confirmation Modal's confirm action.
Cancel Label Button label for the Confirmation Modal's cancel action.
Related Topics
See Also
• DocuSign Envelope Action Properties for Integration Procedures
• Integrating DocuSign with OmniScript
• Using the DocuSign Envelope Action to Email Documents for Signature
Property Description
DocuSign Templates Templates for the documents you want signed. See Preparing a DocuSign Template for OmniScript.
Recipients After you add a template, specify the Signer Name, Signer Email, and Template Role for each recipient.
Signer Name and Signer Email support merge fields. Template roles are configured during template setup.
Email Subject Subject line for the email requesting signatures.
Email Body Body text for the email requesting signatures.
Date and Time Formats Specify the format for display of date and time values. (More information)
See Also
See Also
• Email Action Properties for Integration Procedures
• Create an Email Action Example with Specified Fields
• Workflow for Email Action Example with Template
Many of the properties support either literal values or merge fields, which let you pass in an input or a value
from another step.
Property Description
Use Template If checked, uses a Salesforce email template. Also determines which other properties are available.
To Email Address List Specifies the recipients in the TO field of the email. Click Add Recipient to add each email address. Can
accept an array of up to 100 addresses.
Property Description
Attachment List Specifies a node in the data JSON that contains a list of attachment Ids.
See Also
Property Value
TO EMAIL ADDRESS LIST %email%
Email Subject %subject%
Email Body %message%
6. Go to the Preview tab and click Add New Key/Value Pair three times. Specify the following input
parameters:
Key Value
email (your email address)
subject Test Email
message This is a test.
If you prefer to specify JSON input, click Edit as JSON and paste in this code, substituting your email:
{
"email": "[email protected]",
"subject": "Test Email",
"message": "This is a test."
}
7. Click Execute. You should receive a Test Email from your org in a few minutes.
See Also
See Also
What's Next
Select an Email Recipient
See Also
What's Next
Create the Integration Procedure with the Email Action
See Also
What's Next
Test the Integration Procedure with the Email Action
See Also
5. If the Contact record page doesn't include an Activities component, you can add one:
a. If you're using Salesforce Classic, click Switch to Lightning Experience.
b. Click the gear icon and select Edit Page.
c. Drag an Activities component from the list on the left onto the page canvas.
d. Click Save, then click Back to return to the Contact's page.
The Activities component appears on the Contact's page and lists the email you sent.
See Also
See Also
Property Description
HTTP Path URL to call. For Apex REST actions, you can use merge fields to set this property. You can pass
percentage signs in the URL by replacing the percentage sign in the Path with the variable
$Vlocity.Percent.
HTTP Method GET, POST, PUT, or DELETE
Named Credential Salesforce named credential required for endpoint
REST Options: Header HTML header settings specified as key/value pairs
REST Options: Params URL parameters specified as key/value pairs
Encode URI Enable to HTML-encode the URL
Send Body Enable to send Body contents for a POST action
Timeout How long in milliseconds to wait for a response
Client Certificate Name For two-factor authentication, the name of the client certificate to be used.
Debug Logging: Specifies information to be added to the Preview tab's Debug Output pane before or after the action is
attempted. You can log values from PropertySetMap and the following merge fields:
Pre Action Logging and
Post Action Logging • Pre-action: %endpoint% and %body%
• Post-action: %stepName + 'Info'% and %stepName + 'Info:Content-Type'%
For example:
%stepName + 'Status'%
Retry Count Number of times to retry action when it fails
XML Escape Response Enable to remove XML escapes from an XML response.
See Also
See Also
• HTTP Action for Integration Procedures
• HTTP Action Properties for Integration Procedures
1. From Setup, in the Quick Find box, type remote, then click Remote Site Settings.
2. Click New Remote Site.
3. For the Remote Site Name, enter NASA.
4. For the Remote Site URL, enter https://api.nasa.gov.
5. Click Save.
What's Next
Get an API Key from NASA
See Also
• HTTP Action for Integration Procedures
• HTTP Action Properties for Integration Procedures
• Workflow for HTTP Action Example
1. Go to https://api.nasa.gov.
2. Enter your First Name, Last Name, and Email, then click Signup.
3. Copy the the response and save it to a text file. It looks something like this:
You can start using this key to make web service requests. Simply pass
your key in the URL when making a web request. Here's an example:
https://api.nasa.gov/planetary/apod?
api_key=YbbMNWeWX2BqxoPKXEiWWcKMgNlUHhHXgqWG5XBt
For additional support, please contact us. When contacting us, please tell
us what API you're accessing and provide the following account details so
we can quickly find you:
You will need your API key to run the Integration Procedure.
4. (Optional) To see the types of data you can retrieve from NASA, click Browse APIs.
What's Next
Create the Integration Procedure with the HTTP Action
See Also
• HTTP Action for Integration Procedures
• HTTP Action Properties for Integration Procedures
• Workflow for HTTP Action Example
{
"PictureInfo": {
"url": "https://apod.nasa.gov/apod/image/2006/Eclipse-under-
bamboos1024c.jpg",
"title": "Eclipse under the Bamboo",
"service_version": "v1",
"media_type": "image",
"hdurl": "https://apod.nasa.gov/apod/image/2006/Eclipse-under-
bamboos.jpg",
"explanation": "Want to watch a solar eclipse safely? Try looking down
instead of up, though you might discover you have a plethora of images to
choose from. For example, during the June 21st solar eclipse this
confusing display appeared under a shady bamboo grove in Pune, India.
Small gaps between close knit leaves on the tall plants effectively
created a network of randomly placed pinholes. Each one projected a
separate image of the eclipsed Sun. The snapshot was taken close to the
time of maximum eclipse in Pune when the Moon covered about 60 percent of
the Sun's diameter. But an annular eclipse, the Moon in silhouette
completely surrounded by a bright solar disk at maximum, could be seen
along a narrow path where the Moon's dark shadow crossed central Africa,
south Asia, and Ch",
"date": "2020-06-26",
"copyright": "Somak Raychaudhury"
}
}
8. (Optional) Paste the url or hdurl value into your browser and view the picture.
See Also
To specify that the subordinate Integration Procedure runs asynchronously, as a Salesforce future method
(which can return no data to the calling Integration Procedure), select Remote Options and enter
useFuture: as a key and true as its value. When you run the Integration Procedure, you can see the future
call in the debug log. To pass in data as key/value pairs, use the Additional Input property.
See Also
• Integration Procedure Action Properties for Integration Procedures
• Workflow for Integration Procedure Action Example
Property Description
Integration Procedure Specifies the Integration Procedure to be run in the format Type_Subtype.
Disable Chainable If checked, disables the Chainable settings of the subordinate Integration Procedure. Doesn't affect the
Queueable settings. Unchecked by default.
Remote Options Specifies additional properties for the Integration Procedure as key/value pairs.
Additional Input Specifies additional data for the Integration Procedure as key/value pairs.
See Also
Together the parent and child Integration Procedures transform this input:
{
"InputList": [
{
"Key": "serial_number",
"Value": "ABC1234"
},
{
"Key": "install_date",
"Value": "20200101"
}
]
}
To this output:
{
"OutputList": [
{
"serial_number": "ABC1234"
},
{
"install_date": "20200101"
}
]
}
See Also
Setting Value
Integration Procedure Name ValueToKey
Type Documentation
SubType ValueToKey
3. Click Save.
4. Drag a Response Action into the Structure panel and give it the following settings:
Setting Value
Send JSON Path Value
Send JSON Node %Key%
5. Click Procedure Configuration, then click Activate Version.
What's Next
Create the Parent Integration Procedure
See Also
Setting Value
Loop List InputList
Additional Loop Output IntegrationProcedureAction1 set to %IntegrationProcedureAction1%
4. Drag an Integration Procedure Action within the Loop Block and give it the following settings:
Setting Value
Integration Procedure Documentation_ValueToKey
Send JSON Path InputList
5. Drag a Response Action below the Loop Block and give it the following settings:
Setting Value
Send JSON Path LoopBlock1:IntegrationProcedureAction1
Send JSON Node OutputList
6. Go to the Preview tab.
7. Click Edit as JSON.
8. In the Input Parameters panel, provide input with the following structure:
{
"InputList": [
{
"Key": "serial_number",
"Value": "ABC1234"
},
{
"Key": "install_date",
"Value": "20200101"
}
]
}
9. Click Execute. The output should look something like this:
{
"OutputList": [
{
"serial_number": "ABC1234"
},
{
"install_date": "20200101"
}
]
}
See Also
TIP
The inputs to a List Action must each be in list format even if the list contains only one
item. DataRaptor Extracts that return a list with one item often convert it to a single object.
To convert a single object back into a list, you can use the first example in DataRaptor
Transform Examples.
For more list processing options, see List Input for DataRaptors and the AVG, FILTER, IF, LIST,
LISTMERGE, LISTMERGEPRIMARY, LISTSIZE, MAX, MIN, SORTBY, and SUM functions in the Function
Reference.
To match nodes that have different names and/or reside at different levels in the incoming lists, click
Advanced Merge and specify settings for the nodes to be matched, as follows:
• List Key: Enter the name of the JSON list node where the node to be matched resides.
• Matching Path: Enter the path within the list to the node to be matched.
• Matching Group: Specify the same number for all nodes you want to match.
For example, the following figure shows how to match first and last names from two incoming lists in which
the nodes have different names.
See Also
• List Action Properties for Integration Procedures
• Workflow for List Action Examples
Property Description
Merge Lists Specifies the order in which lists are merged. If a list contains a value for a key that was populated by an earlier
Order list, the later entry overwrites the earlier one.
Property Description
Merge Fields The name of the JSON nodes that must match for entries to be merged. To specify nodes below the top level of the
JSON structure, use colon-delimited paths. By default, the nodes in both lists are assumed to have identical names
and reside at the same level. If you do not specify merge fields, the lists are merged into a single list but nodes with
matching keys are not merged. To match a value that resides in a JSON list, append |index to its path. For
example, to match value1 in the list2 list below, specify list1:node1:node2:list2|1 as the merge field.
{
"list1": {
"node1": {
"node2": {
"list2": [
"value1",
"value2"
]
}
}
}
}
Advanced Matches nodes that have different names and/or reside at different levels in the incoming lists. See List Action for
Merge Integration Procedures.
NULL is a Valid When merge fields are all null, specifies whether to treat them as matching.
Matching Value
when Merging
Has Primary Lets you specify an allowlist of keys to be retained in the output.
Primary List (Optional) Allows the list of entries to be retained after the merge is performed. If you specify a primary list, only
Key entries from that list are retained in the output.
Filter List Specifies a formula that is run on each node of the list to determine if it remains in the list. If FormulaResult returns
Formula TRUE after evaluating a node, the node is retained; otherwise the node is removed. For example, you can specify
nodename != "" to remove null values from a list.
Dynamic Output By default, all nodes are returned. To return a specified subset of the result nodes, add a node to the input JSON
Fields and set its value to a comma-separated list of the desired node names. Do not use spaces in this list. Set this
property to the name of the node containing this list of node names.
Sort By Specifies one or more keys on which the output list is sorted.
Update Field Enables you to assign a value or specify a formula that can evaluate and conditionally replace values in the output
Value list. To specify a formula, precede the expression with "=". For example, to replace blank first or last names with
"None Specified," add the entries shown in the following figure.
See Also
See Also
• List Action for Integration Procedures
• List Action Properties for Integration Procedures
1. Create the DataRaptor Extract that the DRExtractAddresses component calls. Name it GetAddresses
and give it the following settings:
Tab Settings
Extract A Contact extract step set to contact AccountId = id
Output The following mappings:
• contact:Id to contact:id
• contact:FirstName to contact:firstName
• contact:LastName to contact:lastName
• contact:MailingStreet to contact:street
• contact:MailingCity to contact:city
• contact:MailingState to contact:state
If you aren't sure how to create a DataRaptor Extract, see the examples in DataRaptor Extract
Examples.
2. Create the DataRaptor Extract that the DRExtractBirthdates component calls:
a. Clone the GetAddresses DataRaptor and name the clone GetBirthdates.
b. On the Output tab, delete the city, state, and street mappings.
c. Add a mapping from contact:Birthdate to contact:birthdate.
3. From the OmniStudio Integration Procedures tab, click New.
4. Provide an Integration Procedure Name, a Type, and a SubType, and click Save.
5. Drag the first DataRaptor Extract Action component into the Structure panel. Give it an Element Name
of DRExtractAddresses and a DataRaptor Interface of GetAddresses.
6. Drag the second DataRaptor Extract Action component into the Structure panel below the first. Give it
an Element Name of DRExtractBirthdates and a DataRaptor Interface of GetBirthdates.
7. Drag a List Action component into the Structure panel below the second DataRaptor Extract Action
component. Give it the following settings:
Setting Values
MERGE LISTS ORDER DRExtractAddresses:contact
DRExtractBirthdates:contact
MERGE FIELDS id
SORT BY lastName
firstName
8. Drag a Response Action component below all the others. Give it a Send JSON Path of ListAction1
and a Send JSON Node of contactMerge.
9. On the Preview tab, in the Input Parameters pane, click Add New Key/Value Pair. Enter id as
the Key and an Account Id from your org as the Value.
10. Click Execute. The output should look something like this:
{
"contactMerge": [
{
"birthdate": "1975-10-03",
"street": "300 Broadway",
"state": "FL",
"city": "Orlando",
"lastName": "Jones",
"id": "0036100001E5xrWAAR",
"firstName": "Cathy"
},
{
"birthdate": "1976-10-04",
"street": "400 Washington Blvd",
"state": "AZ",
"city": "Phoenix",
"lastName": "Jones",
"id": "0036100001E5xrvAAB",
"firstName": "Doug"
},
{
"birthdate": "1973-10-01",
"street": "100 Main Street",
"state": "CA",
"city": "San Francisco",
"lastName": "Smith",
"id": "0036100001E5xqnAAB",
"firstName": "Albert"
},
{
"birthdate": "1974-10-02",
"street": "200 Second Street",
"state": "OR",
"city": "Portland",
"lastName": "Smith",
"id": "0036100001E5xr2AAB",
"firstName": "Ben"
}
]
}
What's Next
Create an Advanced List Merge Example
See Also
{
"contactMerge": [
{
"LN": "Jones",
"FN": "Cathy",
"birthdate": "1975-10-03",
"street": "300 Broadway",
"state": "FL",
"city": "Orlando",
"lastName": "Jones",
"id": "0036100001E5xrWAAR",
"firstName": "Cathy"
},
{
"LN": "Jones",
"FN": "Doug",
"birthdate": "1976-10-04",
"street": "400 Washington Blvd",
"state": "AZ",
"city": "Phoenix",
"lastName": "Jones",
"id": "0036100001E5xrvAAB",
"firstName": "Doug"
},
{
"LN": "Smith",
"FN": "Albert",
"birthdate": "1973-10-01",
"street": "100 Main Street",
"state": "CA",
"city": "San Francisco",
"lastName": "Smith",
"id": "0036100001E5xqnAAB",
"firstName": "Albert"
},
{
"LN": "Smith",
"FN": "Ben",
"birthdate": "1974-10-02",
"street": "200 Second Street",
"state": "OR",
"city": "Portland",
"lastName": "Smith",
"id": "0036100001E5xr2AAB",
"firstName": "Ben"
}
]
}
What's Next
Create a List Merge Example with Dynamic Output Fields
See Also
{
"contactMerge": [
{
"birthdate": "1975-10-03",
"street": "300 Broadway",
"state": "FL",
"city": "Orlando",
"lastName": "Jones",
"id": "0036100001E5xrWAAR",
"firstName": "Cathy"
},
{
"birthdate": "1976-10-04",
"street": "400 Washington Blvd",
"state": "AZ",
"city": "Phoenix",
"lastName": "Jones",
"id": "0036100001E5xrvAAB",
"firstName": "Doug"
},
{
"birthdate": "1973-10-01",
"street": "100 Main Street",
"state": "CA",
"city": "San Francisco",
"lastName": "Smith",
"id": "0036100001E5xqnAAB",
"firstName": "Albert"
},
{
"birthdate": "1974-10-02",
"street": "200 Second Street",
"state": "OR",
"city": "Portland",
"lastName": "Smith",
"id": "0036100001E5xr2AAB",
"firstName": "Ben"
}
]
}
See Also
If the data a Remote Action returns isn't in Map<String, Object> format, an Integration Procedure or
DataRaptor might not be able to process it. You can convert the data in one of these ways:
• In the Remote Action, under Remote Options, add a Key named reserialize with a Value of true.
• In a subsequent Set Values step, use the RESERIALIZE function on the Remote Action's output.
For information about related functions such as DESERIALIZE and SERIALIZE, see the Function
Reference.
An error message that begins with Invalid conversion from runtime type String often
indicates a need to reserialize data.
See Also
• Remote Action Properties for Integration Procedures
• Workflow for Remote Action Example
Property Description
Remote Class Vlocity Open Interface Class
Remote Method Vlocity Open Interface Method
Remote Options Additional class invocation options
Additional Input Data passed to the method
See Also
To download a DataPack of this example, click here. The DataPack does not include the Apex class.
See Also
• Remote Action for Integration Procedures
• Remote Action Properties for Integration Procedures
@JsonAccess(serializable='always')
global with sharing class TestReserializeApex implements
vlocity_ins.VlocityOpenInterface2 {
global Object invokeMethod(String methodName, Map<String,Object> input,
Map<String,Object> output, Map<String,Object> options) {
return output.put('result', new TestReserialize());
}
@JsonAccess(serializable='always')
global public class TestReserialize {
global public String name = 'Dave Smith';
}
}
Replace vlocity_ins with the namespace for your org if necessary. Depending on your industry, the
namespace is vlocity_ins, vlocity_cmt, or vlocity_ps.
Also note the use of the JsonAccess annotation on the class and method.
5. Click Save.
What's Next
Create the Integration Procedure with the Remote Action
See Also
Property Value
Element Name ReserializeApex
Remote Class TestReserializeApex
Property Value
Remote Method random
Remote Options, Key reserialize
Remote Options, Value false
A Remote Method value is required, but it can be anything, because this Integration Procedure
doesn't invoke a method.
A step in the test of this Integration Procedure will ask you to change the Remote Options Value.
4. Drag a Set Values component into the Structure panel and give it the following settings:
Property Value
Element Name ReserializeApexFunction
Element Value Map, Element Name result
Element Value Map, Value =RESERIALIZE(%ReserializeApex%)
Response JSON Path result
Response JSON Node ReserializeApex
5. Drag another Set Values component into the Structure panel and give it the following settings:
Property Value
Element Name MyName
Element Value Map, Element Name Full Name
Element Value Map, Value %ReserializeApex:result:name%
6. Drag a Response Action component into the Structure panel and check the Return Full Data JSON
checkbox.
What's Next
Test the Integration Procedure with the Remote Action
See Also
1. Go to the Preview tab and click Execute. The output should look like this:
{
"response": {},
"vlcchainableStepDepth": 0,
"ResponseAction1Status": true,
"MyName": {
"Full Name": "Dave Smith"
},
"MyNameStatus": true,
"ReserializeApexFunctionStatus": true,
"ReserializeApex": {
"result": {
"name": "Dave Smith"
},
"errorCode": "INVOKE-200",
"error": "OK"
},
"ReserializeApexStatus": true,
"options": {
"queueableChainable": false,
"ignoreCache": true,
"resetCache": false,
"chainable": false
}
}
Note that this Integration Procedure successfully passes the value of the name variable in the Apex
class to its Full Name node.
2. Go to the Properties tab, select the ReserializeApexFunction component, and click Active to remove
the check. This turns off reserialization.
3. Go to the Preview tab and click Execute again. The output should look like this:
{
"response": {},
"vlcchainableStepDepth": 0,
"ResponseAction1Status": true,
"MyName": {
"Full Name": ""
},
"MyNameStatus": true,
"ReserializeApex": {
"result": {
"name": "Dave Smith"
},
"errorCode": "INVOKE-200",
"error": "OK"
},
"ReserializeApexStatus": true,
"options": {
"queueableChainable": false,
"ignoreCache": true,
"resetCache": false,
"chainable": false
}
}
{
"response": {},
"vlcchainableStepDepth": 0,
"ResponseAction1Status": true,
"MyName": {
"Full Name": "Dave Smith"
},
"MyNameStatus": true,
"ReserializeApex": {
"error": "OK",
"errorCode": "INVOKE-200",
"result": {
"name": "Dave Smith"
}
},
"ReserializeApexStatus": true,
"options": {
"queueableChainable": false,
"ignoreCache": true,
"resetCache": false,
"chainable": false
}
}
See Also
• Remote Action for Integration Procedures
• Remote Action Properties for Integration Procedures
• Workflow for Remote Action Example
Response Actions are also useful for trimming the data response. For specific trimming strategies, see
Manipulate JSON with the Send/Response Transformations Properties.
For Integration Procedure examples that include at least one Response Action, see Process Arrays Using
Loop Blocks, Handle Errors Using Try-Catch Blocks, and Integration Procedure Action for Integration
Procedures.
See Also
• Response Action Properties for Integration Procedures
Property Description
Additional Output Key/value pairs to add to data JSON. Can merge other data. To specify a level below the top level for a key/
value pair, use a colon-delimited path in the Key field. For example:
Resulting JSON:
{
"Key1":
{
"Key2": "Value"
}
}
Return Only Enable to discard data other than the key/value pairs defined as additional output. If you enable this option,
Additional Output disable Return Full Data JSON.
Return Full Data Enable to return entire data JSON. If you enable this option, disable Return Only Additional Output.
JSON
Response Headers To add data to the response header, add key/value pairs to this property. To override the HTTP status code
returned in the header, create a key named StatusCode and assign it a valid HTTP response value.
Execution Conditional Ends the Integration Procedure only if the specified condition is true.
Formula
See Also
• Response Action for Integration Procedures
• Common Integration Procedure Action Properties
• 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.
For more information about these settings, see Common Action Element Properties, Integration
Procedure Action, and Integration Procedure Action for Integration Procedures.
To determine whether a DataRaptor or an Integration Procedure is best for your use case, see DataRaptor
or Integration Procedure?.
• DataRaptor metadata is automatically cached unless you turn off the Scale Cache.
• You can configure data caching on the Options tab of DataRaptor Extracts, Turbo Extracts, and
Transforms.
• If you call a DataRaptor from an Integration Procedure that uses caching, the DataRaptor data is cached
along with the Integration Procedure data.
You can also perform a record-level security check for cached data. See Security for DataRaptors and
Integration Procedures.
To disable metadata caching for an Integration Procedure, go to the Procedure Configuration and check the
Disable Definition Cache checkbox.
TIP
To test the performance benefit of metadata caching, execute the Integration Procedure in
the Preview tab with Disable Definition Cache checked and then unchecked. Compare
the Browser, Server, and Apex CPU values.
Behind this checkbox is the DisableDefinitionCache__c boolean field, which defaults to false.
namespace.DRGlobal.clearCacheForDataRaptor('DataRaptorName');
vlocity.cmt.DRGlobal.clearCacheForAllDataRaptor();
You can clear Integration Procedure metadata from the cache. Follow the instructions in this topic, but
execute this line of code instead, specifying the Integration Procedure's Type and Subtype:
IntegrationProcedureService.clearMetadataCache('Type_Subtype');
You can clear all cached data for an Integration Procedure, including session cache data, org cache data,
and metadata. Follow the instructions in this topic, but execute this line of code instead, specifying the
Integration Procedure's Type and Subtype:
IntegrationProcedureService.clearAllCache('Type_Subtype');
If you must clear DataRaptor data from the Scale Cache, follow the instructions in this topic, but execute a
line of code in this form instead:
namespace.ScaleCacheService.invalidateCacheValue(new Map<String,
String>{'DataRaptorId' =>
DataRaptor_Name});
For example, to clear data from a DataRaptor named ExtractContactName, use this line of code:
omnistudio.ScaleCacheService.invalidateCacheValue(new Map<String,
String>{'DataRaptorId' =>
'ExtractContactName'});
If you must clear Integration Procedure data from the Scale Cache, follow the instructions in this topic, but
execute a line of code in this form instead:
namespace.ScaleCacheService.invalidateCacheValue(new Map<String,
String>{'VIPId' =>
Type_SubType});
omnistudio.ScaleCacheService.invalidateCacheValue(new Map<String,
String>{'VIPId' =>
'LoopList_ContactNames'});
See Also
• Turn Off the Scale Cache
It's important to allocate space in the VlocityAPIResponse cache partition and to understand how top-level
Integration Procedure caching interacts with Cache Blocks. See Cache for DataRaptors and Integration
Procedures.
To configure top-level caching for an Integration Procedure, go to the Procedure Configuration and set the
Salesforce Platform Cache Type and Time To Live In Minutes properties. See Configure Top-Level
Caching for an Integration Procedure.
NOTE
If an Integration Procedure that has top-level caching enabled fails, its data isn’t cached.
• ignoreCache — Doesn't clear or save data to the cache. The default value is true. Use this setting to
test Integration Procedure steps without the possible interference of caching effects.
• resetCache — Forces data to be saved to the cache. The default value is false. Use this setting as
part of testing caching itself.
NOTE
To test caching, be sure to set ignoreCache to false. See Create a Top-Level Caching
Example.
You can pass ignoreCache and resetCache as parameters when you invoke an Integration Procedure that
uses caching using a REST API. For example, you can include ?resetCache=true in the URL to force
caching. See Integration Procedure Invocation Using POST.
These nodes are returned as headers if you invoke an Integration Procedure that uses top-level caching
using a REST API. See Integration Procedure Invocation Using POST.
IntegrationProcedureService.clearSessionCache('vlcCacheKey');
IntegrationProcedureService.clearOrgCache('vlcCacheKey');
You can clear all cached data for an Integration Procedure, including session cache data, org cache data,
and metadata. Follow the instructions in this topic, but execute this line of code instead, specifying the
Integration Procedure's Type and Subtype:
IntegrationProcedureService.clearAllCache('Type_Subtype');
The following example clears the session cache using a vlcCacheKey value:
IntegrationProcedureService.clearSessionCache('2032076016a1745801061oc');
See Also
• Cache for Top-Level Integration Procedure Data
This Integration Procedure also includes a Loop Block; see Process Arrays Using Loop Blocks.
Property Value
Loop List names
Additional Loop Output ExtractContact set to %ExtractContact%
5. Create the DataRaptor Extract that the DataRaptor Extract Action calls, name it ExtractContactName,
and give it the following settings:
Tab Settings
Extract A Contact extract step set to Contact Name LIKE name
Output A mapping from Contact:Id to Contact:Id
If you aren't sure how to create a DataRaptor Extract, see the examples in DataRaptor Extract
Examples.
6. Drag a DataRaptor Extract Action inside the Loop Block and give it the following settings:
Property Value
Element Name ExtractContact
DataRaptor Interface ExtractContactName
Data Source names:name
Filter Value name
7. Create the Response Action below the Loop Block and give it the following settings:
Property Value
Send JSON Path LoopBlock1:ExtractContact
Response JSON Node Contact
8. In the Procedure Configuration, click Activate Version.
9. On the Preview Tab, click Edit as JSON and provide input with the following structure:
{
"names": [
{
"name": "Miller"
},
{
"name": "Torres"
}
]
}
12. Click Execute again. This step populates the cache, so the resulting Browser, Server, and Apex CPU
values are likely to be similar to the previous values.
13. Click Execute a third time. This step uses the cached values, so the resulting Browser, Server, and
Apex CPU values are likely to be noticeably less than the previous values. In addition, Cached
Response: true appears after the performance metrics.
1. Go to Setup.
• In Lightning Experience, click the gear icon and select Setup from the menu.
• In Salesforce Classic, click the user menu and select Setup from the menu.
2. In the Quick Find box, type omni, then select Omni Interaction Configuration.
3. Click New Omni Interaction Configuration.
4. In the Label field, type TurnOffScaleCache.
5. In the Value field, type true.
6. Click Save.
See Also
• Cache for DataRaptors and Integration Procedures
• Failure Conditional Formula: Specify a formula that evaluates to TRUE if the step has failed to execute
successfully. See the second example in Handle Errors Using Try-Catch Blocks.
• Fail On Step Error: Enable this option to terminate the Integration Procedure if the conditional formula
determines that the step has failed.
NOTE
An action that returns a list cannot use returned data in its Failure Conditional Formula.
To configure conditions and behavior for the success and failure of a group of actions, you can use a Try-
Catch Block. See Handle Errors Using Try-Catch Blocks.
To add debugging information to the Data JSON, use Response Actions. For details, see Response Action
for Integration Procedures.
HTTP actions add details about the results of the call to the Data JSON ElementNameInfo node as
follows:
For example, the following filter extracts the Cases created in the last 30 days.
If you are using an environment variable as a Filter value, you must double-quote it.
1. In Salesforce, you perform an operation against the Vlocity external object, for example, in Apex code,
in a report, or by issuing a SOQL query.
2. The Vlocity external object handler calls the Integration Procedure that implements the external object,
passing in a JSON payload that contains details about the request.
3. Based on the contents of the JSON payload, the Integration Procedure accesses the external data
using, for example, REST endpoints or DataRaptor calls, and returns JSON or XML results.
4. The Integration Procedure returns its results to the Vlocity external object handler in an intermediate
format.
5. The Vlocity handler transforms the results into a JSON payload and returns them to the caller.
The advantage of this approach to accessing external data is that it is completely declarative, no code
required. Note that, while the external object functions as a single object, your Integration Procedure can
recruit data from multiple sources.
Upsert: Update a row (if ExternalId is specified) or create a row (if ExternalId is omitted).
To access the external data to handle the query, define HTTP actions that call the REST endpoints that
perform the required operations. If the results returned from the endpoint require further processing, create
and call DataRaptor Transforms that perform the required transformations.
SELECT queries: Return an array of nodes with names that correspond to the table columns defined for
the external object. For example:
[{
"Work": "415-232-6365",
"Mobile": "415-607-9865",
"Email": "[email protected]",
"CreateDate": "2017-10-25T20:50:34.188Z",
"Name": "Davidov Spruth",
"ExternalId": "59f0f91a51280e0012c90584",
"ExternalLookup": "59f0f91a51280e0012c90584",
"AccountIndirectLookup": "123"
},
{
"Email": "[email protected]",
"CreateDate": "2017-10-25T21:49:41.633Z",
"Name": "Mike Wormwood",
"ExternalId": "59f106f5e928870012f2b0a0",
"ExternalLookup": "59f0f91a51280e0012c90584",
"AccountIndirectLookup": "123"
},
{
"Work": "33-555-1212",
"Mobile": "33-879-0610",
"CreateDate": "2017-10-25T20:59:18.657Z",
"Name": "Tom Sor",
"ExternalId": "59f0fb26e928870012f2b09e",
"ExternalLookup": "59f0f91a51280e0012c90584",
"AccountIndirectLookup": "123"
}
]
UPDATE and DELETE queries: Return the external Id of the object affected in a node named "ExternalID";
for example:
{
"ExternalId": "59efa135ba8e960012a3e8a5"
}
If the query does not succeed, return a node named "errorMessage" containing details about the problem
that occurred.
See Also
• Implement an External Object in an Integration Procedure
1. Create an Integration Procedure. For Type, specify VlocityExternalObject. For Subtype, specify the
desired name for the external object.
2. In the Procedure Configuration section, define table and column settings. These are the same settings
you can configure on the Salesforce External Object tab. For detailed information, refer to the
Salesforce documentation: Define External Objects and External Object Relationships.
3. Click Activate.
4. In Salesforce, go to the External Data Source tab and navigate to the VlocityExternalObject data
source. Click Validate and Sync.
If the operation succeeds, your new external object is now listed on the page.
See Also
• External Objects in Integration Procedures
After a Test Procedure finishes, its transaction is rolled back. This lets you run tests that create sObjects
without affecting the database.
How you organize your Test Procedures is up to you. For example, you can test the same DataRaptor
multiple times using different inputs, or you can test several different DataRaptors using the same Test
Procedure.
To mock a component that returns a single value, scroll to the bottom of the Procedure Configuration and
specify a Key/Value pair under Mock Responses Map. The Key must be the Name of a component, and the
Value can be literal text or a merge field.
To mock a component with a more complex response, go to the Procedure Configuration and click Edit as
JSON, then edit the mockResponseMap node. For example, the following JSON code mocks a Set Values
component named IfOtherState that sets a DefaultSalesTax value:
"mockResponseMap": {
"IfOtherState": {
"DefaultSalesTax": 0.06
}
}
The following component types must be mocked in the testing Integration Procedure or the Integration
Procedure being tested. Mocking other component types is permitted but not required.
if (IntegrationProcedureService.isTest == false) {
HttpRequest request = new HttpRequest();
request.setMethod('GET');
request.setEndpoint('http://example.com');
1. Enable the Vlocity Tracking Service for Integration Procedures. See Enable Tracking for OmniStudio
Components and Add Debugging Data to Test Procedure Event Tracking.
2. Create the Integration Procedure to be tested. See Create a Conditional Block Example with If-Elseif-
Else Logic.
3. Mock a Response in the Tested Integration Procedure.
4. Create an Example Test Procedure.
5. Run the Test Procedure from IDX Workbench. See Run Test Procedures.
See Also
• Assert Action for Integration Procedures
• Assert Action Properties for Integration Procedures
• Integration Procedure Action for Integration Procedures
• Integration Procedure Action Properties for Integration Procedures
1. Go to the OmniStudio Integration Procedures tab and open the Integration Procedure to be tested.
2. If the Integration Procedure is active, click Deactivate Version so you can edit it.
3. In the Procedure Configuration, click Edit as JSON.
4. Edit the mockResponseMap node as follows:
"mockResponseMap": {
"IfOtherState": {
"DefaultSalesTax": 0.06
}
}
5. Click Edit in Property Editor.
6. Click Activate Version. The Integration Procedure to be tested must be active.
See Also
A Response Action isn't required, but it's useful for testing the Test Procedure. After you have verified that
the Test Procedure works, you can deactivate or delete it.
Property Value
Element Name IPInput
Element Value Map: Price 250
Element Value Map: State NY
Property Value
Response JSON Node IPInput
5. Drag an Integration Procedure Action component into the Structure panel and give it the following
settings:
Property Value
Element Name TestIP
Integration Procedure Name you gave the Integration Procedure to be tested, described in Define Execution Logic Using
Conditional Blocks.
Send JSON Path IPInput
6. Drag an Assert Action component into the Structure panel and give it the following settings:
Property Value
Element Name AssertTotal
Assert Conditional Formula TestIP:Output:Total == 265
Assert Failure Message Calculation is incorrect.
7. Drag a Response Action component into the Structure panel and give it the following settings:
Property Value
Element Name TestResponse
Return Full Data JSON (checked)
After you have verified that the Test Procedure works, you can deactivate this component.
8. Go to the Preview tab and click Execute. The output should look like this:
{
"response": {
"testResult": "success"
},
"TestResponseStatus": true,
"AssertTotal": {
"assertFailureMessage": "Calculation is incorrect.",
"variableData": {
"TestIP:Output:Total": 265
},
"assertConditionalFormula": "TestIP:Output:Total == 265",
"assertResult": true
},
"AssertTotalStatus": true,
"TestIP": {
"testResult": "success",
"Output": {
"Price": 250,
"State": "NY",
"Tax": 15,
"TaxRate": 6,
"Total": 265
}
},
"TestIPStatus": true,
"IPInput": {
"Price": 250,
"State": "NY"
},
"IPInputStatus": true,
"options": {
"useQueueableApexRemoting": false,
"queueableChainable": false,
"ignoreCache": true,
"resetCache": false,
"chainable": false
}
}
9. (Optional) In the IPInput component, change the Price, or change the State to WA, OR, NV, or CA.
Then return to the Preview tab and click Execute again. Note how the output changes.
10. To prepare for running the Test Procedure:
a. In the TestResponse component, click Active to remove the check.
b. In the Procedure Configuration, click Activate Version. IDX Workbench only runs active Test
Procedures.
See Also
• Workflow for Test Procedure Example
• Test Procedures: Integration Procedures for Unit Testing
/*
VlocityOpenInterface2 implementation:
methodName - the Type_SubType of Procedure or the OmniScript__c.Id -
procedureAPIName above
input - The payload / initial data in the DataJSON for the Procedure
output - will return Response in output.put('result', RESPONSE)
*/
public Object invokeMethod(String methodName, Map<String, Object> input,
Map<String, Object> output, Map<String, Object> options);
}
@isTest(seeAllData=true)
global with sharing class TestVlocityIntergationProcedure
{
static testMethod void testVip()
{
Map<String, Object> response = (Map<String,
Object>)namespace.IntegrationProcedureService.runIntegrationService('Type_Subty
pe',
new Map<String, Object>{
• You must use Salesforce's seeAllData property on the @isTest annotation. This ensures that the unit
test sees the Vlocity SObject data in the org.
• The method that runs the Integration Procedure is
IntegrationProcedureService.runIntegrationService.
• The namespace is vlocity_cmt, vlocity_ins, or vlocity_ps.
• The Type_Subtype parameter specifies the Integration Procedure to test.
Salesforce has specific requirements for testing HTTP callouts. Therefore, HTTP Actions require special
handling.
You can set the mock HTTP response of an Integration Procedure using the following Vlocity global
method:
IntegrationProcedureServiceTest.setMockHttpResponse(HttpResponse response)
This is required because when an Integration Procedure runs, the Vlocity Managed Package makes the
HTTP callout internally.
The following is an example unit test of an Integration Procedure that includes an HTTP Action:
@isTest(seeAllData=true)
global with sharing class TestVlocityIntergationProcedure
{
static testMethod void testVipWithHttpCallout()
{
HttpResponse res = new HttpResponse();
res.setHeader('Content-Type', 'application/json');
res.setBody('{"ContactEmail":"[email protected]"}');
res.setStatusCode(200);
namespace.IntegrationProcedureServiceTest.setMockHttpResponse(res);
System.assertEquals('[email protected]', response.get('ContactEmail'));
}
}
In Winter '20 and later releases, if an Integration Procedure includes more than one HTTP Action, you can
set the mock HTTP responses using the following Vlocity global method:
IntegrationProcedureServiceTest.setMockHttpResponseByUrlOrActionName()
Using the Element Name of the HTTP Action is often easier. However, for some HTTP Actions, such as one
within a Loop Block, you might have to specify the URL. If you specify the URL, it must be the exact URL
you are calling. If it is a NamedCredential, it follows the pattern callout:NamedCredentialName.
The following is an example unit test of an Integration Procedure that includes two HTTP Actions:
@isTest(seeAllData=true)
global with sharing class TestMockHttpIP
{
static testMethod void testVipWithHttpCallout()
{
HttpResponse res1 = new HttpResponse();
res1.setHeader('Content-Type', 'application/json');
res1.setBody('{"ContactEmail":"[email protected]"}');
res1.setStatusCode(200);
namespace.IntegrationProcedureServiceTest.setMockHttpResponseByUrlOrActionName(
'GetContactsHttp', res1);
res2.setBody('{"ContactEmail":"[email protected]"}');
res2.setStatusCode(200);
namespace.IntegrationProcedureServiceTest.setMockHttpResponseByUrlOrActionName(
'callout:MyContactInfo2', res2);
System.assertEquals('[email protected]', response.get('ContactEmail'));
System.assertEquals('[email protected]',
response.get('Action2Response'));
}
}
For an example, see Invoke a Chainable Integration Procedure with REST Calls.
NOTE
In JSON, curly braces are literal, but in REST notation, curly braces represent variables.
/services/apexrest/{namespace}/v1/integrationprocedure/{Type}_{SubType}/
Specify the Type and SubType of the Integration Procedure. You can also send HTTP headers as options.
To pass input data in a GET call, you can specify URL parameters. You can't specify a JSON request body.
If you need to specify a JSON request body, use a POST call instead.
In the following example, an Integration Procedure that creates cases requires a Contact name and returns
the Id of the newly created case. The Contact name is specified in the URL. Note that the HTML code %20
represents the space between the first and last names.
GET
/services/apexrest/vlocity_ins/v1/integrationprocedure/Create_Cases/?
Contact=Dennis%20Reynolds
Example Result:
{
"Case": {
"Id": "0036100001HDn3QAAT"
}
}
There are two ways to pass parameters to the Integration Procedure in the URL:
• Parameter/value pairs
• Inline values in the URL path
/services/apexrest/{namespace}/v1/integrationprocedure/{Type}_{SubType}/
{inlinevalue1}/{inlinevalue2}/?{Param1}={Value1}
/services/apexrest/vlocity_cmt/v1/integrationprocedure/IP_Rest/Apple/Phones/?
product=iPhoneX
{
"options": {
"Path1": "Apple",
"Path2": "Phones",
"product": "iPhoneX",
"isDebug": "true"
}
}
Values passed in the path are added under the options node, with keys named PathN.
You can also set Integration Procedure options such as chainable or queueableChainable using a
REST API. For example:
/services/apexrest/vlocity_ins/v1/integrationprocedure/Create_Cases/?
chainable=true
/services/apexrest/{namespace}/v1/integrationprocedure/{Type}_{SubType}/
Specify the Type and SubType of the Integration Procedure. You can also send HTTP headers as options.
To pass input data in a POST call, you can specify either a JSON request body or URL parameters.
In the following example, an Integration Procedure that creates cases requires a Contact name and returns
the Id of the newly created case. The Contact name is specified in a JSON request body.
POST
/services/apexrest/vlocity_ins/v1/integrationprocedure/Create_Cases/
{
"Contact":"Dennis Reynolds"
}
Example Result:
{
"Case": {
"Id": "0036100001HDn3QAAT"
}
}
There are two ways to pass parameters to the Integration Procedure in the URL:
• Parameter/value pairs
• Inline values in the URL path
/services/apexrest/{namespace}/v1/integrationprocedure/{Type}_{SubType}/
{inlinevalue1}/{inlinevalue2}/?{Param1}={Value1}
/services/apexrest/vlocity_cmt/v1/integrationprocedure/IP_Rest/Apple/Phones/?
product=iPhoneX
{
"options": {
"Path1": "Apple",
"Path2": "Phones",
"product": "iPhoneX",
"isDebug": "true"
}
}
Values passed in the path are added under the options node, with keys named PathN.
You can also set Integration Procedure options such as chainable or queueableChainable using a
REST API. For example:
/services/apexrest/vlocity_ins/v1/integrationprocedure/Create_Cases/?
chainable=true
After defining the class, you can use the resulting flow component in the Salesforce Flow Designer to call
Integration Procedures. Drag the component from the list to the flow and set its properties as follows.
General Settings: Set Name and Unique Name to descriptive names for the instance of the component in
the flow.
Input Settings
• Procedure Name: Specify the Integration Procedure to be run using this format: Type_SubType (note the
underscore).
• Input: For each input variable required by the Integration Procedure, choose Variable and specify the
name of the input variable using the following format: {!variableName}
Output Settings: For each variable that is returned by the Integration Procedure, choose Variable and
specify the name of the output variable using the following format: {!variableName}
By default, all the actions in an Integration Procedure run in a single transaction. If the transaction exceeds
a Salesforce governor limit, Salesforce ends the transaction and the Integration Procedure fails. You cannot
set a limit that exceeds the maximum imposed by Salesforce. For details about governor limits, see the
relevant Salesforce topic.
• Enable chaining from the OmniScript or parent Integration Procedure action that calls the long-running
Integration Procedure.
• Optionally set limits that trigger chaining in the long-running Integration Procedure itself using the settings
described here.
When chaining is enabled and an Integration Procedure step exceeds a governor limit, its interim results
are saved and the step is continued in a separate transaction. Because the step runs in its own transaction,
it does not contend for resources with other steps in the Integration Procedure, so it's less likely to hit
governor limits.
To maximize performance, steps are chained only when they hit governor limits. If no limits are exceeded,
all the steps in the Integration Procedure run in a single transaction. When steps are chained, the
performance of the Integration Procedure can be adversely affected by the need to break up the execution
into chunks that do not exceed the governor limits and the need to store interim results.
You can increase Salesforce governor limits by allowing a chainable step to start a queueable job, which
runs as an Async Apex Job. These jobs have higher CPU, SOQL, and Heap size limits than regular
transactions do. However, while this helps to ensure that governor limits aren't exceeded, it can reduce
performance.
For Developer Edition and Trial orgs, the maximum stack depth for chained jobs is 5, which means that you
can chain jobs four times. This limit of 5 includes the initial parent queueable job. See Queueable Apex in
the Salesforce help.
For an example, see Invoke a Chainable Integration Procedure with REST Calls.
• Chainable Queries Limit: Maximum number of SOQL queries that can be issued. The default maximum
is 100.
• Chainable DML Statements Limit: Maximum number of Data Manipulation Language (DML) statements
that can be issued. The default maximum is 150.
• Chainable CPU Limit: Maximum CPU time on the Salesforce servers. Default maximum is 10,000
milliseconds.
• Chainable Heap Size Limit: Memory used to store data during transaction processing. The default
maximum is 6 MB.
• Chainable DML Rows Limit: Maximum number of records that can be processed as a result of DML
statements, Approval.process, or database.emptyRecycleBin. Default maximum is 10,000.
• Chainable Query Rows Limit: Maximum number of rows that a SOQL query is permitted to retrieve.
The default maximum is 50,000.
• Chainable SOSL Queries Limit: Maximum number of SOSL queries that can be issued. Default
maximum is 20.
• Chainable Actual Time: Number of seconds an Integration Procedure can run before chaining occurs to
avoid reaching the Salesforce Concurrent Request Limit. No default.
NOTE
Chainable Queries Limit, Chainable Query Rows Limit, and Chainable SOSL Queries
Limit work within a managed package but not outside of it. For example, if a Remote
Action runs queries outside the package, these don't count toward the limits.
• Queueable Chainable Heap Size Limit: Memory used to store data during transaction processing. The
default maximum is 12 MB.
• Queueable Chainable CPU Limit: Maximum CPU time on the Salesforce servers. The default maximum
is 60,000 milliseconds.
• Queueable Chainable Queries Limit: Maximum number of SOQL queries that can be issued. Default
maximum is 200.
Queueable Chainable settings override their Chainable equivalents if both are set.
If you are calling an Integration Procedure from a REST API, you can set the chainable or
queueableChainable option to true. See Invoke a Chainable Integration Procedure with REST Calls.
A parent Integration Procedure can disable the Chainable settings of a child Integration Procedure that it
calls. See Integration Procedure Action for Integration Procedures.
Chain On Step is not required for chaining to occur. If no step has Chain On Step applied, chaining occurs
at the step at which the Integration Procedure's resource use approaches governor limits or a chainable or
queueable chainable setting.
If your Integration Procedure has a DataRaptor Post action followed by an HTTP action, enable Chain On
Step for the DataRaptor Post action to avoid the following Salesforce error: You have uncommitted work
pending. Please commit or rollback before calling out.
To see what the intermediate responses look like, see Invoke a Chainable Integration Procedure with REST
Calls.
function runChainable(options) {
options.isDebug = vm.isDebug;
remoteActions.testIntegrationProcedure(ipId, inputData,
options).then(function(response) {
responseHandler(response);
});
}
function responseHandler(response) {
if (typeof(response) === 'string') {
response = JSON.parse(response);
}
if (response &&
response.vlcIPData &&
response.vlcStatus === 'InProgress') {
runChainable(response);
} else {
// handle IP response
}
}
1. Open the Integration Procedure example in your org. If you imported the DataPack, it's listed under
Documentation/IPTryCatch2 or Documentation/IPTryCatchF2.
2. In the Preview tab, try different Name input parameter values until you find one that returns more than
one record but not many. An ideal Name value returns two names.
3. In the Procedure Configuration, click Deactivate Version if the Integration Procedure is active so you
can edit it. Set the Chainable Query Rows Limit to a value low enough to cause chaining.
For example, if the Name value in the previous step returns two records, a Chainable Query Rows
Limit value of 1 results in two transactions. If the Name value in the previous step returns six records,
a Chainable Query Rows Limit value of 2 results in three transactions.
4. Go to the DataRaptorExtractAction1 component and check its Chain on Step property.
5. Go back to the Procedure Configuration and click Activate Version.
6. In a terminal window, enter a curl command in this format, all on one line:
For example, if the Name is Jones, the namespace is vlocity_ins, the Type is Documentation,
and the SubType is IPTryCatchF2, your curl command looks like this:
A session ID is a very long String. In this example, the session ID is truncated for clarity.
TIP
You can assemble the curl command in a text editor and copy it into the terminal
window.
{
"vlcUseQueueableApexRemoting": false,
"vlcMessage": null,
"vlcIPData": "dc3e1986-2f7c-0871-e968-28eb63e11820",
"vlcStatus": "InProgress"
}
NOTE
Integration Procedure Preview handles chaining automatically, so you never see this
type of response.
8. Add a header for the vlcIPData to the curl command and enter it. For example:
{
"response": {},
"ResponseAction1Status": true,
"Name": "Jones",
"options": {
"Accept": "*/*",
"X-B3-SpanId": "ee09609f22d890e1",
This response is an example of what you get when the Integration Procedure is complete.
For OmniScripts that call long-running Integration Procedures, check the Use Continuation setting in the
Integration Procedure Action.
For OmniScripts that call Apex classes using Remote Actions, you have two options:
• Make a Long-Running Remote Call Using VlocityContinuationIntegration — This approach is older, still
supported but deprecated.
• Make a Long-Running Remote Call Using OmniStudio.OmniContinuation — This approach is
recommended because it's namespace-independent.
For more information on the SFDC Continuation object, see the following Salesforce documentation:
To make a remote call using the Salesforce Continuation object and extending the
VlocityContinuationIntegration class:
CustomApexWrapperClass wrap =
(CustomApexWrapperClass)JSON.deserialize(JSON.serialize(state),
CustomApexWrapperClass.class);
This approach permits any data written to the VlocitySetAsyncCallbackState to be retained and
used as its custom Apex class.
{
Boolean result = true;
try
{
// the custom methods can have any customized signature, but
// PLEASE MAKE USRE YOU ALWAYS PASS IN options
if(methodName.equals('Continuation1'))
{
// this returns Continuation Object
return Continuation1(10, inputMap, outMap, options);
}
else if(methodName.equals('Continuation2'))
{
return Continuation2(8, options);
}
else if(methodName.equals('customcallback'))
{
customcallback(inputMap, outMap, options);
}
// other methods to handle normal Remote Call
else
{
result = false;
}
}
catch(System.Exception e)
{
// System.log ...
result = false;
}
return result;
}
// You can have other parameters as well, but make sure you always pass in
Map<String, Object> options
private Object Continuation1(Integer count, Map<String, Object> inputMap,
Map<String, Object> outMap, Map<String, Object> options)
{
// THIS IS A SAMPLE TO CALL HEROKU NODE SERVICE
// Make an HTTPRequest as we normally would
// Remember to configure a Remote Site Setting for the service!
String url = 'https://node-count.herokuapp.com/'+count;
>HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint(url);
// Create a Continuation for the HTTPRequest
Continuation con = new Continuation(60);
//
// Please set up callback method here
// (1) Include this callback method in the above invokeMethod, refer to
// else if(methodName.equals('Continuation2'))
// (2) methodName is CASE SENSITIVE
con.continuationMethod = 'Continuation2';
// The following method MUST BE CALLED
// params:
// (1) first parameter = Continuation Object
// (2) second parameter = WHATEVER YOU WANT TO SET THE state parameter of
the CONTINUAION Object
// https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/
apexcode/apex_continuation_process.htm
// (3) third parameter = options
// what it does:
// restructure the state property of the Continuation Object to be passed
to the next Callback
// con.state is a Map, which contains:
// (a) vlcContinuationCallbackState - the state you want to set, in this
example, con.addHttpRequest(req)
// (b) vlcContinuationCallbackLabels - labels, refer to
// https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/
apexcode/apex_continuation_process.htm
VlocitySetAsyncCallbackState(con, con.addHttpRequest(req), options);
// Return it to the system for processing
return con;
}
// callback for the first Continuation
// Returns Continuation Object
// This is to show you how to serialize multiple long running remote calls
private Object Continuation2(Integer count, Map<String, Object> options)
{
// EXAMPLE
// Make an HTTPRequest as we normally would
// Remember to configure a Remote Site Setting for the service!
String url = 'https://node-count.herokuapp.com/'+count;
HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint(url);
// Create a Continuation for the HTTPRequest
Continuation con = new Continuation(60);
// (1) This callback method should be included in the above invokeMethod,
refer to above
// else if(methodName.equals('customcallback'))
con.continuationMethod = 'customcallback';
// The following line has to be called
For details about the SFDC Continuation object and the Callable interface, see the following Salesforce
documentation:
To make a remote call using the OmniContinuation object and implementing the Callable interface:
3. For the method that returns the OmniContinuation Object, call the OmniStudio.OmniContinuation
constructor.
}
else
{
result = false;
}
}
catch(System.Exception e)
{
result = false;
}
//outMap.put('nothing', methodName);
return result;
}
// You can have other parameters as well, but make sure you always pass in
Map<String, Object> options
private Object populateElements(Integer count, Map<String, Object>
inputMap, Map<String, Object> outMap, Map<String, Object> options)
{
// THIS IS A SAMPLE TO CALL HEROKU NODE SERVICE
//
// Make an HTTPRequest as we normally would
// Remember to configure a Remote Site Setting for the service!
String url = 'https://node-count.herokuapp.com/'+count;
HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint(url);
options.put('continuationState', label);
options.put('continuationCallback', 'continuation2');
options.put('continuationState', label);
options.put('continuationCallback', 'customCallback');
// EXAMPLE
HttpResponse response =
OmniStudio.OmniContinuation.getResponse((String)stateAsMap.get('label'));
Integer statusCode = response.getStatusCode();
return null;
}
}
IMPORTANT
Guest Users, also called anonymous users, cannot access any records by default. Criteria-
based Sharing Rules grant them read-only access. This affects all Salesforce orgs. For
details, see Guest User Record Access Development Best Practices.
Vlocity allows guest users to create and update the records to which Sharing Rules grant
access. No additional configuration is necessary for this expanded access.
You can use Salesforce Sharing Settings to secure access to DataRaptors and Integration Procedures. If
you use caching, you must set CheckCachedMetadataRecordSecurity to true as described here.
You can allow access to a DataRaptor or Integration Procedure based on the Custom Permissions enabled
in a user's Salesforce Profiles or Permission Sets. An Apex class added to your Salesforce Org allows the
Vlocity Managed Package to check user Custom Permissions. The custom settings described here are
related to this approach. Vlocity recommends using Custom Permissions in Profiles or Permission Sets for
ease of use and better performance.
For Salesforce access basics, see Control Who Sees What, Who Sees What — Overview Video, and
Salesforce Data Security Model — Explained Visually.
Sharing Settings, Sharing Sets, Profiles, and Permission Sets control access to DataRaptors and
Integration Procedures as object records. To enforce field-level security in the data that DataRaptors
access, go to the DataRaptor's Options tab and select Check Field Level Security.
IMPORTANT
A user's access to a DataRaptor or Integration Procedure includes more than the ability to
run it directly. Access also applies if an application the user is using calls the DataRaptor
or Integration Procedure.
If a user has access to a parent Integration Procedure, the parent can invoke child
Integration Procedures and DataRaptors to which the user doesn’t have direct access.
For a list of settings, see DataRaptor and Integration Procedure Security Settings.
1. Go to Setup.
• In Lightning Experience, click the gear icon and select Setup from the menu.
• In Salesforce Classic, click the user menu and select Setup from the menu.
2. In the Quick Find box, type omni, then select Omni Interaction Configuration.
3. Click New Omni Interaction Configuration.
4. In the Label field, type the name of the setting.
5. In the Value field, type a valid value for the setting.
6. Click Save.
To configure these settings, see Configure DataRaptor and Integration Procedure Security Settings.
For DefaultRequiredPermission details, see DataRaptor and Integration Procedure Security Settings.
A calculation procedure is a series of calculations performed on matrix lookups and user-defined variables
and constants. A calculation matrix is a table that looks up information using multiple input dimensions and
returns the corresponding output value.
Calculation procedures and matrices can automate the creation of complex quotes. Together these can
guide a customer or agent through a series of questions, pull data from various sources, and present one or
more customized quotes or eligibility determinations. These can be quotes or eligibility determinations for:
Calculation procedures and matrices accept input from a Salesforce form, REST API, and OmniScript (in
the data JSON). Inputs can come from more than one source. The output can be a proposal or PDF, or
data for populating an OmniScript, form, list, JSON structure, or REST API request.
After the first procedural step, the second procedural step runs. This step takes the Rate that is the output
of the first procedural step, divides it by a constant, and outputs the Monthly Rate. Subsequent steps can
perform additional math on the data submitted—Smoker, ZIP, Age—or use inputs from other data sources,
such as policies currently held, or current health status, to perform additional calculations and return a
variety of quotes.
Calculation Matrices
Calculation matrices are one of the key elements of a Vlocity rating engine. Vlocity uses calculation
matrices to look up inputs, match them to outputs, and provide the outputs to calculation procedures.
Vlocity offers three styles of calculation matrices you can use based on your business needs:
• Standard Calculation Matrices — Has characteristics common to all calculation matrices, including input
columns, output columns, and versions.
• Grouped Calculation Matrices — Allows grouping of matrix rows by a key such as geographic region or
age.
• Row-Versioned Calculation Matrices — Allows versions to apply to specific rows rather than the entire
matrix.
IMPORTANT
You can't create calculation matrices that are both grouped and row-versioned.
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.
CAUTION
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.
A calculation matrix is a Vlocity rating table that is structured and stored as follows:
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, so 2 is higher priority than 1)
to determine which version of the matrix to use.
If the start date/time of one version of a calculation matrix overlaps the end date/time of another calculation
matrix, you can set priorities on them to enable Vlocity to determine which one to use. If a call to a
calculation matrix specifies an effective date, Vlocity uses that date to find the correct matrix. If a date isn't
specified, Vlocity uses today as the effective date.
The call to the calculation matrix finds the right hash, matches the input, unpacks the output JSON, finds
the correct output, and returns it.
• 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.
• Vlocity uses only one SOQL query to query a group of matrix versions.
• Insurance carrier staff members who keep the calculation matrix data up to date can create and enable
new versions of a matrix without touching any other versions.
However, grouped matrices have some limitations. Each matrix in a group must have all the same input
and output column headers.
So this carrier creates a different calculation matrix for each state it offers insurance within, using
Jurisdiction as the Group Key.
All the input and output headers are the same, only the values differ. Each state's calculation matrix can be
updated at a different time, and new versions can be activated at different times.
The Group Key for this calculation matrix is ProviderFeeSchedule, and each version of the calculation
matrix is for a specific provider.
At execution time, Vlocity uses the group key to find the correct grouped calculation matrix, and the
provider code to pick the correct version of the matrix.
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.
Each row of this kind of calculation matrix gets assigned a start date when the matrix is created.
At execution time, Standard and Grouped Matrices both pull matrices by version, start date, end date, and
priority at the calculation matrix level. In a row-versioned matrix, this all goes out the window.
At execution time, Vlocity checks the Start Date and End Date of each row in the row-versioned calculation
matrix. If dates overlap on two versions of a row, the calculation uses the version with the highest Priority
specified.
But Vlocity does still use the versions to manage the rows in a row-versioned calculation matrix.
When you update row-versioned calculation matrices, you can include changes to the rows that you need
to update only. Vlocity uploads only the changed rows and shares the unchanged rows with both versions
of the matrix.
What Vlocity does when you update rows is a little bit complicated. Here's how it works.
First Version
The first version of a row-versioned calculation matrix looks almost the same as a standard calculation
matrix. But some data is stored slightly differently by Vlocity. The Start Date / Time you enter is assigned to
each row of the matrix individually.
Second Version
Your second version of the CSV file can be the whole matrix that includes new and changed rows. Or your
CSV can contain only the new and changed rows.
When you upload the second version, you give the new version of the matrix a different Start Date / Time.
Vlocity gives all the new and changed rows in this version the new Start Date / Time.
Vlocity does not copy the unchanged rows to the new version of the calculation matrix. Instead, it shares
the rows from version 1 of the matrix with version 2. That way, the unchanged rows are stored only once,
which saves storage space.
NOTE
Vlocity shares rows only when both versions are enabled.
For example, if version 1 of a calculation matrix is not enabled, its row will not be shared
with version 2.
You still see all the rows, both the rows shared from version 1 and the new and changed rows of version 2
when you view version 2.
You can also create a second version of the calculation matrix and manually change rows rather than
upload them in a CSV. This works best if there are only a couple of changes required.
Vlocity does not copy the unchanged rows from previous versions. Instead, it shares rows from all previous
version with the new version. So if you've uploaded version 3, you will see unchanged rows stored in
version 1, rows changed in version 2 but not version 3 stored in version 2, and new and changed rows
stored in version 3 only.
Deleted Rows
In a scenario where you've got three versions of a row-versioned calculation matrix, here's what happens
when you delete different rows from different versions:
• Action: In version 3, delete a row that you updated in version 3 that first existed in version 2.
Result: Vlocity shares the version 2 row in version 3 of the matrix. The version 3 row is deleted.
• Action: In version 3, delete a row that has existed unchanged since version 1.
Result: The row disappears from version 3 of the matrix. The row remains unchanged in version 1 and
version 2.
CAUTION
Once you've chosen Standard as the record type of a calculation matrix, you can't change
it. Choose wisely.
IMPORTANT
Starting in the CME Summer '18 release, the following limits are supported:
Before you start the upload, follow the guidelines below to make sure that your CSV file is formatted for use
as a calculation matrix.
TIP
When it's time to update a calculation matrix with new data--like every time a
government makes a change to its insurance regulations--you can do it with a CSV
file. Vlocity is smart enough to scan your CSV file for new rows and changed data in
existing row. Only those new and changed rows get uploaded, which vastly reduces
the amount of time an upload takes, especially for huge matrices.
You must make sure that all column header names exactly match those in the current
calculation matrix.
2. Create rows.
Each row must include a unique combination of input values.
Multiple rows can contain the same output value or combination of values for different input values.
When you build ranges, each set of values must have the same range values. For example, if the
following conditions are true:
• Ranges are 1, 20, and 300 for input 1.
• Ranges are a, b, and c for input 2.
Here's how the table is formatted:
Here's a more realistic example showing a CSV file that will become a calculation matrix for car values,
to be used to rate auto policies:
TIP
If you're importing a CSV file into an existing calculation matrix, make sure that
column header names in the CSV file match exactly with the column header names in
the calculation matrix. CSV column header names that don’t match any existing
columns are added to the calculation matrix as new columns.
NOTE
You must map all the Header Types: set each Header Type to Input or Output.
11. Select a Data Type for each column from this list:
• Text
• Number
• Currency
• Percent
• Boolean
• Number Range
• Text Range
The Data Type defaults to Text for all newly-uploaded columns.
12. Click Save Data.
13. To see the data rows, click Edit Data.
14. Review your table in Vlocity to be sure that it's all correct. To learn how to edit headers and data, see
Review and Edit a Calculation Matrix.
To see columns that have errors, click Show Errors Only. (The button toggles to Show All Rows after
you click it.)
15. Click Save Data.
16. If your organization has an approval process set up for calculation matrices, click Submit for
Approval.
17. After the calculation matrix is approved, or if your organization doesn't approvals and you're ready to
use this calculation matrix, enable the calculation matrix.
Click the pencil icon to the right of the Enabled checkbox.
Select Enabled.
IMPORTANT
You can't disable an enabled calculation matrix, and you can't edit headers or data on
an enabled calculation. Be sure before you click Enabled.
• Text Range
IMPORTANT
Do not change the Data Type of an existing header unless you have no other
choice. When you change the Data Type, the data in the column can be corrupted,
requiring you to re-enter all the data.
NOTE
You must enter data in every data field. You cannot enable a calculation matrix that
contains empty data fields.
IMPORTANT
You can't disable an enabled calculation matrix, and you can't edit headers or data on
an enabled calculation. Be sure before you click Enabled.
1. From the Calculation Matrix list page, click the name of the matrix. Then click the version of the matrix
you want to clone.
2. Click the down-arrow at the top right of the calculation matrix detail page and choose Create New
Version.
Vlocity opens the new version of the calculation matrix. It includes the following:
• A unique name composed of matrixName vX where X is the new version number
• A new version number
NOTE
If you create a new version of the matrix with over 1,500 rows, only the row headers
are copied into the new version. You must re-upload the data into the new version.
If there are fewer than 1,500 rows, all data is copied into the new version.
The new version does not include a Priority number, and is not enabled.
3. To update the headers and data in the matrix, Upload a CSV File or Review and Edit the Calculation
Matrix.
4. Set new Start Date/Time and End Date/Time for the new matrix.
a. When you enter a Start Date/Time for the new version of the matrix, set it to the date/time when
the previous version ends.
Or
Set a Start Date/Time before the End Date/Time of the previous version and set Priority numbers
for both matrices so Vlocity can choose the correct matrix when it's called.
b. Enable the new matrix when it's ready, even if the Start Date/Time is in the future. Vlocity won't
use the new enabled matrix until the Start Date/Time is reached.
5. Enter a Priority number.
When Vlocity finds more than one enabled calculation matrix that matches the call being handled, it
chooses the calculation matrix with the highest priority. For example, if two enabled calculation
matrices have Priority set to 1 and 2, Vlocity uses the calculation matrix that's set to Priority 2.
6. If your organization has an approval process set up for calculation matrices, click Submit for
Approval.
7. After the calculation matrix is approved, or if your organization doesn't approvals and you're ready to
use this calculation matrix, enable the calculation matrix.
Click the pencil icon to the right of the Enabled checkbox.
Select Enabled.
NOTE
You can't directly disable an enabled calculation matrix, and you can't edit headers or
data on an enabled calculation. Be sure before you click Enabled!
If you need to modify or replace an enabled calculation matrix, you can create and
enable a new version of the calculation matrix, and assign it a higher priority number
than the old matrix.
1. Make sure your groups of matrices can follow all these rules:
• Identical input and output column headers
• Contain at least one and maximum two common input dimensions
• Input variable ranges must all be the same
• The Group Key and Sub Group Key cannot be range inputs
The Group Value and Sub Group Value are usually text inputs, such as a jurisdiction code or a
product code.
2. Create a Grouped Calculation Matrix.
3. Populate the Rest of the Matrices in the Group.
TIP
We call matrix group members Versions.
Be sure that your CSV file is set up to support row-level versioning. To learn how, see Prepare a CSV File
to Upload to a Calculation Matrix.
IMPORTANT
You can't add row-level versioning to an existing matrix that lacks it, because overlapping
effective dates cause errors.
IMPORTANT
Once you've enabled your calculation matrix version, the headers are locked. You won't be
able to change them again.
1. Make sure the CSV is in good shape. Most importantly, make sure all the column headers in the .csv
file are identical to the headers in the existing calculation matrix.
See Prepare a CSV File to Upload to a Calculation Matrix.
2. On the calculation matrix you're updating, click the Related tab.
3. Under Vlocity Calculation Matrix Versions, click New.
4. Enter the following information:
• Name: Enter a name for this version of this calculation matrix.
TIP
Choose a name that makes it easy to understand the contents of this version of the
calculation matrix. For example, CalcMatrix_ChangedRows12-24 or
CalcMatrix_ChangedRowsForWesternStates2020.
• Version Number: Enter a unique version number for this calculation matrix version. This version
number does not relate to the row versions, but Vlocity needs it as a unique identifier for each matrix
version uploaded.
• Enabled: Select this checkbox to enable this version of the calculation matrix.
• Start Date / Time: Enter the start date for the new and updated rows.
IMPORTANT
The Date field is mandatory for row-versioned calculation matrices.
• End Date / Time: Enter the end date for the new and updated rows.
TIP
If you need to update rows with an end date that's not today, don't delete the rows.
Instead, create a .csv file that includes only the rows you want to set an End Date
for.
• Priority: Enter a unique priority number that calculation procedures can use to prioritize which in
which order to search calculation matrices.
NOTE
Don't enter anything into the End Date / Time fields unless you're updating rows
specifically to give them an end date. In row-versioned calculation matrices, Vlocity
sets end dates behind the scenes. If you enter specific end dates, you may get
unpredictable results.
5. Click Save.
6. Click the name of the matrix version you just created.
7. Click Upload CSV.
8. Choose your new CSV file, then click Upload.
9. Review the matrix.
10. Click Save Data.
TIP
You don't have to delete rows from matrices to make Vlocity's row-versioning work. You
can leave existing rows in place. When the matrix is called, the row with the most recent
Start Date is used.
CAUTION
Don't delete all data from any calculation matrix version unless you're absolutely sure you
need to. This action can cause problems with calculation procedures that use data from
the calculation matrix.
For example, you've got a calculation matrix that contains insurance ratings for thirty of these states in the
United States. Because you don't have separate ratings for the other twenty states but you want your
calculation procedure to find a value for those states, you make the State column into a wildcard-enabled
column.
You set up your wildcard column when you first create your calculation matrix. So you need to know the
exact name of the column and the value of the wildcard.
For the State example, the column name and value can be:
1. Find the column or columns for which you want to restrict values.
2. Enter the value you're looking for into the field next to the magnifying glass.
NOTE
Don't use wildcards when you search in a matrix. Use exact values.
To download all the data, navigate to the version of the calculation matrix that you need to download and
click Download CSV. The CSV file containing the whole calculation matrix downloads to your computer.
1. Navigate to the version of the calculation matrix that you want to download.
2. Find the column or columns for which you want to restrict values.
3. Enter the value you're looking for into the field next to the magnifying glass.
4. Click the Search button above the columns.
5. Click Download CSV.
The CSV file containing the search results downloads to your computer.
NOTE
You can't use a split-limit attribute as an Output in a calculation matrix.
IMPORTANT
Do not change the Data Type of an existing header unless you have no other
choice. When you change the Data Type, the data in the column can be corrupted.
If the data becomes corrupted, reimport the CSV file to overwrite the corrupted data.
1. Open the version of the calculation matrix that you want to disable.
2. In the details section, click the pencil icon to the right of End Date/Time.
3. Set the End Date/Time to the date and time that you want the matrix to be disabled.
4. Click Save.
In the following example, the numeric range is defined in the Input column. The Age Range Band describes
how values are treated: all values below 18 fall into the first band, values that are 18 or higher and below 25
fall into the second band, and so on. For example, for age 48, the matrix returns an Age Range Band of 6.
For age 22, it returns an Age Range Band of 1.
When you have multiple inputs that include range, define identical ranges for each variable value. For
example:
See Also
• ???
• ???
Declarative calculation procedures are associated with DataRaptor mappings. Declarative calculation
procedures use DataRaptors to read and save data from Salesforce objects. You can add variables from
the DataRaptor extract, such as Original Price (Currency) and Quantity (Number). For example, you can
add a currency variable named UnitPrice as a calculation output that can be used in a DataRaptor load to
update a field in a Salesforce object.
• Matrix: If you have enabled Calculation Matrices, a calculation procedure can include a Calculation Matrix
in the calculation steps. For more information about Calculation Matrices, see Calculation Matrices.
• Formula: For example, you can specify the UnitPrice variable as output. If you are using DataRaptor
mappings, the calculation procedure output variable name must match the DataRaptor Load input
variable name
Each step in a Calculation Procedure can have a condition that must be met in order for the step to be
executed. See Conditional Steps For Calculation Procedures.
In the Preprocessor Class Name section of the calculation procedure, you must specify the class that
implements a nameSpace.VlocityOpenInterface calculation method.
To include the output from a calculation step in the final output, select Include in output.
Case 2 — Attribute-based pricing, but no volume-based pricing across multiple line items:
• You cannot specify the input or output DataRaptors in the Calculation Procedure.
• A preprocessor is required to format the input data for use in the Calculation Matrix.
• A postprocessor is required to evaluate the quantities across all lines in the header object.
By default, the new (cloned) calculation procedure does not have any versions set to Enabled. You have to
manually enable one of the versions to use it.
Any calculation matrices used by the calculation procedure are not cloned.
In Salesforce Lightning, you add a Clone button to the Calculation Procedure object, then add the button to
the Calculation Procedure page layout:
1. Go to Setup > Object Manager > Vlocity Calculation Procedure > Buttons, Links, and Actions.
2. Click New Button or Link.
3. Enter a Label and a Name for the button.
4. In Display Type, choose either Detail Page Button or Detail Page Link.
5. Choose a Behavior.
Recommended: Display in existing window with sidebar.
6. In Content Source, choose Visualforce Page.
7. In Content, choose CalculationProcedureCloner.
8. Click Save.
9. Go to Setup > Object Manager > Vlocity Calculation Procedure > Page Layouts.
TIP
If you can't see the Clone button on your screen, click the gray down-arrow at the
top right of the page and select Clone.
c. In the New Vlocity Calculation Procedure window, enter a name for your new calculation
procedure, then click Save.
See Also
• Declarative Calculation Procedures
The following are a few guidelines for using variables in Calculation Procedures:
x = 2
y = 3
variable = 0
variable = 0
See Also
• Add Variables and Constants
To specify a condition, check Conditional Step and enter the condition for the step. If the condition
compares a variable with a constant, the constant must be defined in the Constant section.
Calculation procedures can calculate coverage premiums, insured party premiums, insured item premiums,
and insurance policy premiums. Calculation procedures can calculate attribute-based prices for products.
NOTE
Beginning with the Summer '19 release, declarative calculation procedures support:
• Constants
All the constants you need for each calculation step
• Variables
Input variables, all the variables you need for each calculation step and the group key and subgroup key
if you're calling a group of matrices all the variables in calculation matrices you call in matrix lookup steps
• Calculation steps, including:
• Calculations
Each calculation required to get to the correct result of the whole calculation procedure
• Matrix lookups
Finds one or more variable values in calculation matrices, based on one or more variable inputs
• Aggregation steps (optional)
If this calculation procedure will handle an array of inputs, aggregation steps will perform calculations
over the output sets.
OmniScripts, Integration Procedures, and other Vlocity processes can call a calculation procedure. The
calculation procedure takes a JSON that gives the calculation procedure the ingredients it needs to
complete its calculation.
Calculation procedures can take a single input, a single set of inputs, or multiple arrays of inputs.
{
"input": {
"opMVRPoints": "0",
"opAccidentPoints": "0",
"driverGoodStudent": "N",
"driverMaritalStatus": "M",
"driverGender": "M",
"driverYrsExp": "14",
"driverMileage": "7500",
"driverUse": "Business"
}
}
The calculation procedure runs through all its steps once for a single input or single array of inputs. It
returns a calculation or array of calculations. The output JSON for the calculation procedure that processed
this input is:
{
"output": [
{
"calculationResults": [
{
"driverCCD": 1.11,
"driverCOLL": 0.92,
"driverMED": 0.91,
"driverUM": 0.92,
"driverBIPD": 0.86,
"autoSafeDriver__driverSafe": "Y",
"ID": "input"
}
],
"aggregationResults": {}
}
]
}
Because the calculation procedure did not have any aggregation steps, there are no aggregation results in
the output JSON.
For example, in a simple case, the calculation procedure needs to calculate a group premium based on a
census. Each census member has a set of input values that's passed to the calculation procedure. The
calculation procedure runs all of its calculation steps for each member, resulting in an output (premium) for
each member. So now it's got an array of outputs. To sum the premiums of all the members of the census,
an aggregation step sums all the premium output variables.
NOTE
The aggByKey functionality in the following example is available in Vlocity Insuranceand
Vlocity Health only.
In a more complex scenario, an auto insurance calculation procedure must calculate a premium per
instance of car and driver. For example, a user needs to rate out a policy for two cars—a Toyota Prius and
a Tesla Model S. The Prius is driven by Roger and Amy, and the Model S is driven by Amy and Steve. The
calculation procedure needs to calculate and aggregate results separately for the Prius and for the Model
S.
In this case:
• instanceKey = car+driver
• aggByKey = carModel
To complete this calculation with aggregation, the calculation procedure uses aggByKeys. When the
calculation procedure receives aggByKeys as an input, it runs through the aggregation steps once per
aggByKey. Here's what that looks like:
So for the example above, the calculation procedure groups the results of its four calculation step runs into
two subsets: one for the instances for the Prius and another for the instances for the Model S. Then it runs
the aggregation steps twice: once for the Prius and again for the Model S. The calculation procedure
returns two aggregation results—one for each vehicle.
You don't need to add aggByKeys and instanceKeys to your calculation procedure as variables. As long as
the aggByKey option and includeInputKeys option are set correctly in the services, the
getRatedProduct and repriceProduct services will pass the keys in automatically as part of the input
JSON.
If you think you need to use preprocessor classes or postprocessor classes, please contact your Vlocity
representative to verify that your use case requires that you write these classes. (We have a lot of tools that
are easier and more configurable now, and some of those might work better for you.)
NOTE
You can't use the same name for a variable that you use for a constant. Variables and
constants use the same namespace.
1. Add variables:
a. In the Variables and Constants section, click +Add Variable.
NOTE
Before you enter output variables, check the calculation matrices this calculation
matrix will use.
An input variable that requires a user input cannot be used as an output variable.
2. Add constants:
a. In the Variables and Constants section, click +Add Constant.
b. Enter the constant data:
• Name: A unique name for the constant.
• Data Type: Choose one of the available types.
• Precision: Optional. Enter the level of precision you want Vlocity to adhere to for this constant.
For example, enter 0.25 to make this constant's value precise to the nearest quarter of an
integer. For a dollar value example, enter 10 to make the constant precise to the nearest $10.
Enter 0 if this calculation procedure must use the precise value of this constant, with no
adjustment.
• Value: The value of this constant.
3. Click Save Calculation Procedure.
See Also
1. On the Procedure Calculation tab of the calculation procedure's page, scroll down to the Calculation
Steps section.
2. Click + Add Step
3. Select Calculation.
4. In the first field, enter a constant or a variable, then press Return.
5. Enter an operator and press Return. Choose from the following operators:
• + (plus sign)
• – (minus sign)
• * (asterisk)
• / (backslash)
• ^ (caret)
• ( (open parentheses)
• ) (closed parentheses)
6. Enter the next item and press Return.
7. Keep entering operators and items until you've completed the calculation.
8. To make this calculation step conditional, select Conditional Step.
Enter the condition that will invoke this calculation step.
9. To include the calculation output in the calculation output data, select Include in Calculation Output.
10. Click Save Calculation Procedure.
See Also
1. On the Vlocity Calculation Procedure Version Detail page, scroll down to the Pricing Calculation
section.
TIP
If you tried Simulate Final Step and didn't get the correct result, do Simulate All Steps
then examine the results starting with the first step to see which calculation step isn't
working right.
1. Open the version of the calculation procedure you want to clone, then click Create New Version. You
may have to click the gray down-arrow at the top right of the window to find this link.
The clone includes all the details, variables, constants, and calculation steps (calculations and matrix
lookups) from the previous version. But the new version is not set to enabled.
2. To make changes to the calculation procedure details, click Edit at the top right.
a. Change detail values such as the Start Date/Time and End Date/Time.
b. Click Save.
3. To make changes to the variables and constants:
a. Click into a variable or constant to change its data.
b. To delete a variable or constant, click the trashcan icon to the right of the specific item.
c. Click Save Calculation Procedure.
4. To make changes to calculations and matrix lookups:
a. Click into either calculation field to delete, add, or change items and operators in it.
b. Click into either matrix lookup field to change the matrix or the resulting variable.
c. Click the trashcan icon to the right of any calculation or matrix lookup to delete it.
5. To make changes to aggregation steps:
a. Click into either aggregation field to delete, add, or change items and operators in it.
b. Click the trashcan icon to the right of any aggregation step to delete it.
6. Click Save Calculation Procedure.
Calculation procedures support looping calculations starting in the Vlocity Insurance Winter '18 Major
Release.
For example, you can create a looping calculation procedure for a life insurance policy. The looping
calculation procedure calculates the policy value for each year from the current age of the policy holder to
the policy holder's age at the end of the policy term. The calculation takes a current age (35 years), end
age (65 years), and an interval of 1 to calculate on an annual basis. The calculation runs, looping 30 times.
All input variables remaining constant, but the index starts at 35 and increments by one through 65. The
output shows the user the value of the policy each year from the start date to the end of the term.
Index Variable
The index variable becomes available when you set Enable Looping on the Calculation Procedure
Version. To add it to calculation steps, type index in a calculation step.
When a calculation procedure has looping set up and enabled, it increments index based on the looping
Interval variable (whatever you've named it), from looping start until looping end. You can then use
index to change the calculation on each looping pass. For example, you can add it to an Age to increment
the value of Age for each loop.
NOTE
The system-provided index variable does not show up in the list of variables. You don't
need to create it.
In this example, calculation step 3 is set up to calculate the year of the policy, looping per interval (one
year). Step 4 calculates the age of the policy holder, looping per interval (one), starting with the policy
holder's age at the start of the policy.
PREVIOUS Function
You can use the PREVIOUS function to get the previous looped iteration's result. The calculation step can
use this function to access a previous iteration's variable results and calculate it with other variables.
• Variable name
Usually set up as a constant of type Text
• previousIterator
The index of the previous iteration result set from which to get the value for the variable
• ITERATION
System-provided variable for accumulated results
In this example, the PREVIOUS function uses previous iterations to calculate the cash value of the policy
per iteration (one).
{
"output": [
{
"calculationResults": [
{
"index": 0,
"intervalNumber": 0,
"deathBenefit": 3000,
"deathBenefitGuaranty": 3000,
"cashValue": 0,
"intervalDividend": 0,
"cashInvestment": 2995.83,
"cashInsurance": 4.17,
"deathProbability": 0.00139,
"currentMortality__currentDeathProbability": 0.002402,
"currentAge": 47,
"intervalDate": "2017-12-07",
"endAge": 52,
"ID": "input"
},
{
"index": 1,
"intervalNumber": 1,
"deathBenefit": 5995.83,
"deathBenefitGuaranty": 3000,
"cashValue": 2995.83,
"intervalDividend": 0,
"cashInvestment": 2996.52,
"cashInsurance": 3.48,
"deathProbability": 0.00116,
"currentMortality__currentDeathProbability": 0.002639,
"currentAge": 48,
"intervalDate": "2018-12-07",
"endAge": 52,
"ID": "input"
},
{
"index": 2,
"intervalNumber": 2,
"deathBenefit": 8992.35,
"deathBenefitGuaranty": 3000,
"cashValue": 5992.35,
"intervalDividend": 44.94,
"cashInvestment": 2997.33,
"cashInsurance": 2.67,
"deathProbability": 0.00089,
"currentMortality__currentDeathProbability": 0.002903,
"currentAge": 49,
"intervalDate": "2019-12-07",
"endAge": 52,
"ID": "input"
}
],
"aggregationResults": {}
}
]
}
Example 2: OmniScript
In this example, the looping calculation procedure is added to an OmniScript as a Calculation Action.
The looping calculation creates a list of results. You can display these results in a format of your choice. In
the example below, a custom template displays the results in a table that shows the values of the policy
year over year (incremented by 1).
6. Drag the following items from Fields onto the Vlocity Calculation Procedure Version Detail section:
• Enable Looping
• Loop Specification
7. Click Save.
8. Return to the browser tab for the Calculation Procedure Version you're using and refresh the browser.
9. Click the pencil icon for the Enable Looping field and check the Enable Looping box.
10. In the Loop Specification field, type a JSON value in this format:
{"loopingStart":"StartVariableName","loopingEnd":"TermVariableName","loopin
gInterval":"IntervalVariableName"}
The values must match the names of the variables you will set in the calculation procedure in the next
step.
For example:
return success;
}
Vlocity Actions
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.
The Vlocity Action API returns the actions associated with an object. The icons, links, and display text
enable users to invoke the action from the object context.
NOTE
If a field is missing, confirm that the field is available in the Vlocity Action Layout
page layout for the Vlocity Action object.
To add values to the Applicable Type picklist, use the API name of the object, such as
Household__c. The value can be an sObject name or any string. If the action has a Filter, the
Applicable Type must be the sObject name, such as Policy__c, which is used in an SOQL
query.
Applicable User Profile To choose what action to display for a user profile, select an option from the list. Default value is
All. An admin can add other user profiles to the picklist. For example, if the current login user's
profile is Vlocity Health, only the actions where Applicable User Profile is set to All or
Vlocity Health displays.
Active To make the action visible, check this option.
Display Label Required. Enter a visible label for the action.
Display Sequence Required. Enter the sequence in which the action displays on a sub-tab or component. Lowest
number in the sequence displays first.
Display On Required. To filter where the action displays, select All, Web Client, or Mobile from the list.
Vlocity Icon To display an icon for this action, view the available Vlocity Icons and their associated class
names in the Vlocity Icons section of the action details page. Enter the class name of the icon
to display for this action. Vlocity Icons are not viewable when creating a new action on the New
Vlocity Action page.
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.
Open URL In To set how to open the Target URL, select Current Window or New Tab/Window. Default is
Current Window.
Link Type Required. To specify where the action is launched from, select one of these options:
NOTE
An error message displays when you delete a seed action. A user cannot
delete a seed action or clear the Is Seed Action checkbox, but can set
as inactive.
/apex/TestPolicyOmniPage?id={0}#/OmniScriptType/Policy/
OmniScriptSubType/Auto/OmniScriptLang/English/ContextId/{0}/
PrefillDataRaptorBundle/true.
IMPORTANT
For out-of-the-box Vlocity Actions, such as View Record, the Target
URL/{0} does not work outside of Salesforce Classic. To navigate to a
page in Salesforce Lightning Experience, update the URL to /
lightning/r/[ObjectName]/{0}/view, where ObjectName is the
API name of the sObject such as Account.
The {0} in the target URL represents the indexed position of a parameter in the list of
parameters in the URL Parameter field. See the URL Parameter field description.
To navigate to a Lightning or Lightning Community Page, prefix the relative URL with
ltngpage:. For example, ltngpage:/Home redirects to your community home page.
To open a Visualforce page from Salesforce's Lightning container, prefix the relative URL with
ltng. For example, ltng:/apex/CustomVFPage, redirects to the CustomVFPage.
• /apex/NameSpace__OmniScriptUniversalPageConsole?
id={0}&OmniScriptType=VPL&OmniScriptSubType=GetPolicyAccountAgentDet
ails&OmniScriptLang=English&scriptMode=vertical&layout=lightning&Con
textId={0}&InteractionId={1}&Role={2}
• /apex/NameSpace__OmniScriptUniversalPageWHeader?id={0}#/
OmniScriptType/Policy/OmniScriptSubType/Auto/OmniScriptLang/English/
ContextId/{0}/PrefillDataRaptorBundle/true
• /apex/NameSpace__ConsoleCards?id={0}&layout=lex-layout
• /apex/NameSpace__ConsoleCards?id={0}&layout=Sample-
GetObjectFromInteraction
See Target URL and URL Parameters.
This example specifies that the action shows only for active Policies where policy type is 'Auto'.
The filter condition is applicable for valid Salesforce standard and custom objects. Filter by any
field on the object. Maximum length is 255 characters.
Additional Filter Enter a filter longer than 255 characters.
State Model For contracts, specify the Contract State Model that defines the contract life cycle associated
with this action.
To State For contracts, specify the state associated with this action.
Invocation Class Name Enter Apex invocation class name and method name. The class must implement
VlocityOpenInterface/VlocityOpenInterface2.
Invocation Method Name
Validation Class Name Enter validation class name and method name. The class must implement
VlocityOpenInterface/VlocityOpenInterface2. It is used in the Contract Document
Validation Method Name Management UI Action tool bar to display a warning message.
4. Click Save.
means this action appears only on the Action toolbar for the Policies with policy type ='Auto' and status is
'active'.
4. Click Save.
5. Repeat steps 1 through 4 for the Check Out to Customize and Check Out to Customize Console
actions.
IMPORTANT
For out-of-the-box Vlocity Actions, such as View Record, the Target URL/{0} does not
work outside of Salesforce Classic. To navigate to a page in Salesforce Lightning
Experience, update the URL to /lightning/r/[ObjectName]/{0}/view, where
ObjectName is the API name of the sObject such as Account.
• OmniScriptUniversalPage
• OmniScriptUniversalPageWHeader
• OmniScriptUniversalPageWHeaderSidebar.
• OmniScriptUniversalMobilePage (for use with Mobile only)
• OmniScriptUniveralPageConsole (for use in the Industry Console)
• OmniScriptUniversalCommunitiesPage (for use in Communities)
/apexNS__[PageName]?id={0}#/OmniScriptType/AAA1/OmniScriptSubType/AAA2/
OmniScriptLang/AAA3/layout/[LayoutName]/ContextId/{0}/PrefillDataRaptorBundle/
[BundleName]/[verticalMode]
/apex/NS__[PageName]?id={0}#/layout=[LayoutName]
https://www.domainName.com/?id={0}/
/apexNS__[PageName]?
id={0}&OmniScriptType=AAA1&OmniScriptSubType=AAA2&OmniScriptLang=AAA3&layout=[L
ayoutName]]&PrefillDataRaptorBundle=[BundleName]&scriptMode=[verticalMode]
/apex/NS__[PageName]?id={0}&layout=[LayoutName]
https://www.domainName.com/?id={0}/
NOTE
While both URL patterns are valid, the advantage of the alternative pattern is that it is
mobile-friendly and enables adding additional URL parameters directly into the OmniScript
Data JSON. For example, appending &customerSLALevel=gold to the URL would add a
node to the root of the OmniScript Data JSON, such as "customerSLALevel":"gold".
URL Parameters
In a Target URL, the {0} represents the indexed position of a parameter in the list of parameters in the URL
Parameter field. The parameter is the field API name in the applicable object, such as AccountId, or ID in
Contact.
Specify the parameters as a comma-delimited string, in the sequence in which you want to replace the
parameters in the Target URL. For example, AccountId,vlocity_ins__PrimaryContactId__c, replaces {0}
in the Target URL with the AccountId, and replaces {1} in the Target URL with the
vlocity_ins__PrimaryContactId__c.
You can also use attributes from the User object, such as User.ContactId to get the Id of the current user.
NOTE
Beginning with CME Fall '18, Vlocity supports the Salesforce object edit URL format of /{3
character sobject prefix}/e'.
/apex/vlocity_ins__OmniScriptUniversalPage?
id={0}&OmniScriptType=AppointmentApplication&OmniScriptSubType=IndependentAgent
AppointmentApplication&OmniScriptLang=English&layout=lightning
/apex/NameSpace__ConsoleCards?id={0}&layout=lex-layout
• To use relative URLs in the Lightning Console (LEX), prefix the Target URL with ltng:, and make sure
the Open URL in value is set to New Tab / Window so that the relative URL link will open in a new
window. For example, ltng:/apex/NewLandingPage, will open the New Landing Page in a new
window.
• To redirect to a Lightning or Lightning Community Page, prefix the relative URL with ltngpage:. For
example, ltngpage:/Home will redirect to your community home page.
• To open a Visualforce page from Salesforce's Lightning container, prefix the relative URL with ltng:. For
example, ltng:/apex/CustomVFPage, will redirect to the CustomVFPage.
NOTE
Because Lightning web components, such as LWC Cards and LWC OmniScripts, are not
URL addressable, you can only Angular Vlocity Cards and Angular Vlocity OmniScripts
from the toolbar.
1. In your org, open a record page, such as an Account, click the Set Up icon, and click Edit Page.
2. From the Lightning components pane, drag the Vlocity Action Toolbar component from the list of
Custom - Managed components onto the canvas area where you want your toolbar to display.
3. To update properties in the Properties Pane, see Configure the Vlocity Action Toolbar.
1. In your org, go to Service Setup > All Communities and click Builder next to the name of an existing
Community to open the Community Builder.
2. Click the blue and white lightning bolt icon on the left to open the Components pane.
3. From the list of Custom Components in the Components pane, drag the Vlocity Action Toolbar to
the canvas area where you want your toolbar to display.
4. To update properties in the Properties Pane, see Configure the Vlocity Actions Toolbar on this page.
Property Description
Record Id To enable the toolbar to automatically use the recordId of the record page it's on, leave empty. To display actions
associated with a specific record Id, enter a record Id.
Style Select a horizontal or vertical layout. Default is horizontal.
Object Type Select the objects whose actions have specific Applicable Types. Applicable Types determine the objects from
which you want the action to launch. See Vlocity Actions. For example, enter Account,Policy_c to display
Vlocity Actions that can only launch from an Account or Policy record page. Default is Home.
Display On To limit to Vlocity Actions that only display on specific platforms. Select from one of these options:
Option Description
All For actions that display on both web client and mobile.
Web Client Default. Actions display only on the salesforce web client.
Mobile For actions that display online on the mobile app.
Link Type To specify where the action is launched from, enter a comma-separated list without spaces. For example, to
display actions that launch OmniScripts and specific URLs, enter Other,OmniScript.
Type Description
CommunityURL Launches a Salesforce Community page.
OmniScript Launches an OmniScript.
Other Launches a specific URL.
ConsoleCards Launches a Salesforce Classic card.
LEXConsoleCards Launches a Lightning Experience Console card in a sub-tab.
Document Launches a Contracts Document.
Layout Launches a Card Layout page.
Community If Link Type is CommunityURL, enter the name of the Community page you created to display OmniScripts.
Page
The Expression Engine is an APEX-based formula builder used across multiple areas in OmniStudio,
including OmniScripts, DataRaptors, and Integration Procedures.
The OmniScript formula builder and attribute rules use a client-side JavaScript expression engine that is
evaluated in the browser and allows for fast, real-time applications.
For information on operators, functions, and formula syntax, see Function Reference.
For more information on the syntax of the OmniScript formula builder, see Creating Formula Fields in an
OmniScript.
Function Reference
You can use the following operators and functions in DataRaptors and Integration Procedures.
Supported Operators
Logical operators:
String operators:
• LIKE — True if the left-hand side contains the right-hand side. For example, "ABC" LIKE "A" returns
true.
• NOTLIKE — True if the left-hand side does not contain the right-hand side. For example, "ABC"
NOTLIKE "A" returns false.
• ~= — Performs a case insensitive comparison. For example, "ABC" ~= "abc" returns true.
Supported Functions
Functio Return Example
n s
ABS Absolut ABS(-1) returns 1
e value
of the
specifie
d
number
COUNT Returns COUNTQUERY ( "SELECT COUNT() FROM Case WHERE AccountId = '{0}'" , Id )
QUERY the
number
of rows
that
meet
the
WHER
E
clause
criteria.
Custom Execute CustomFunction('Statistics.calcStdDev',DataPoints)
Functio sa
n('clas custom
s.meth function
od',inp defined
ut) in the
method
of an
Apex
class.
See
Sample
Apex
Code
for a
Custom
Functio
n.
If the
input
includes
a LIST
function
, the
LIST
part of
the
input is
saved
to
a VLOC
ITY-
FORMUL
A-
LIST k
ey. See
List
Input in
Custom
Functio
ns.
FLOOR Returns FLOOR(2.5) returns 2, which is 2.5 rounded down to the nearest integer.
a
number
rounded
down to
the
nearest
integer,
towards
zero if
negativ
e.
• 2019-
02-02
T00:0
0:00
• 2018-
12-30
T00:0
0:00.
0000
00Z
You can
supply
an
optional
output
formatti
ng
paramet
er using
Simple
DateFor
mat
notation
.
Specifyi
ng GMT
times is
recomm
ended.
These
are
convert
ed to
the
user's
time
zone.
The
default
time is
00:00:0
0 GMT.
The
default
date is
01-01-1
970, so
specifyi
ng a
complet
e date
is
strongly
recomm
ended.
If no
time
zone
name
paramet
er is
specifie
d, the
default
is the
current
user’s
time
zone.
For a
list of
time
zone
names,
see the
List of
tz
databas
e time
zones
Wikiped
ia page.
If no
output
format
paramet
er is
specifie
d, the
default
output
format
is yyyy-
MM-
dd'T'HH
:mm:ss.
SSSZ.
HALF_ Use ROUND(2.57, 1, HALF_EVEN) returns 2.6, which is rounded up to the nearest even one-decimal place.
EVEN with
ROUND
to
specify
that the
roundin
g result
is
rounded
rounded
towards
the
nearest
neighbo
r (up or
down)
unless
the
neighbo
rs are
equidist
ant, in
which
case it
rounds
to the
nearest
even
neighbo
r.
Behave
s as for
ROUND
HALF_
UP if
the digit
to the
left of
the
discard
ed
fraction
is odd;
behave
s as for
ROUND
HALF_
DOWN
if it is
even.
You can
use IF
to filter
a list.
The
second
exampl
e filters
an input
list of
phones
to an
output
list of
only
Apple
phones.
The
third
exampl
e
remove
s an
initial
dollar
sign if it
is
present,
leaving
a
number
that can
be used
in
calculati
ons.
The
fourth
exampl
e
demons
trates
nesting
of IF
function
s.
Drivers
under
25
qualify
for a
discoun
t if
they’re
good
student
s, and
drivers
over 25
qualify if
they
refer
two or
more
friends.
Takes
one or
more
INPUT('
Key',Val
ue)
pairs as
inputs
to the
Integrati
on
Proced
ure.
The
'Output
Key' is
the IP
Respon
se
Action
output
JSON
key to
get the
resultin
g value.
ISBLAN Returns ISBLANK('Marty') returns false
K true if
the
argume
nt is
blank,
false if it
is not.
You can
use
NOW to
specify
dates
and
times
relative
to the
current
date
and
time.
Output
Format:
List<Ma
p<Strin
g,Objec
t>>
QUERY Execute QUERY ("SELECT Name FROM Account WHERE BillingState ='CA'")
sa
SOQL You can also pass in values. For example:
query
QUERY( "SELECT AccountId FROM User WHERE Id = '{0}'",$Vlocity.UserId )
that
returns
a JSON
list of
values.
The
query
cannot
retrieve
more
than
one
column.
You can
also
use the
UP,
DOWN,
HALF_
UP,
HALF_
DOWN,
and
HALF_
EVEN
paramet
ers to
refine
the
roundin
g
results.
Syntax:
SORTB
Y(LIS
T(Inpu
tList)
,
'key1'
,
'key2'
...,
[:DSC]
)
SQRT Calculat SQRT(12 * 3) returns 6
es the
square
root of a
value.
You can ADDDAY(EOM(ADDMONTH(TODAY(),-1)),1) returns the first day of the current month
use
ADDDAY(EOM(ADDMONTH(TODAY(),0)),1) returns the first day of next month
TODAY
to CONCAT(YEAR(ADDYEAR(TODAY(),1)),"-01-01") returns the first day of next year
specify
dates
relative
to the
current
date.
TOSTRI Convert TOSTRING(3.0) returns "3.0"
NG(dat s any
a) input to TOSTRING([4,5]) returns "4,5"
a literal
TOSTRING({ "key": "value" }) returns "{key=value}"
String.
Note TOSTRING([ { "key": "value" }, { "key2": "value2" } ])
how it
differs returns "{key=value}, {key2=value2}"
from
SERIAL
IZE in
the way
it
convert
s JSON
data.
UNIXD Given a UNIXDATETOTIME('1480490134000')
ATETO Unix
TIME epoch returns "2016-11-30T07:15:34.000Z"
value,
returns
the
corresp
onding
DateTi
me.
The
StartN
ode
paramet
er must
be a
hard-
coded
node. It
can be
a path
such as
Data:Na
me.
Each
NodeVa
r
paramet
er must
be an
input
node
with the
name of
another
node as
its
value.
If more
than
one
NodeVa
r is
specifie
d, the
previou
s
NodeVa
r
defines
the
starting
node for
the next
NodeVa
r. You
can
retrieve
any
number
of
levels.
YEAR Returns YEAR("1999-01-11") returns 1999
the year
of the
specifie
d date
as an
integer.
*/
else if (methodName == 'split')
{
List<Object> arguments = (List<Object>)inputs.get('arguments');
output.put('result', split(arguments));
}
return true;
}
Double sum(List<Object> arguments)
{
Double result = 0;
for(Object token : arguments)
{
if (token != null)
{
result += (Double)token;
}
}
return result;
}
Map<String, String> split(List<Object> arguments)
{
Map<String, String> result = new Map<String, String>();
String toSplit = (String)arguments[0];
String splitter = (String)arguments[1];
List<String> splitList = toSplit.split(splitter);
for (Integer i = 0; i < splitList.size(); i++)
{
if (arguments.size() > i+2)
{
result.put((String)arguments[i+2], splitList[i]);
}
else
{
result.put('Split'+i, splitList[i]);
}
}
return result;
}
}
For example:
// Rest of Function
}
The OmniStudio Tracking Service is an event-tracking service that captures details of actions that users
perform. You can use the service to track any type of event. For example, you can track the time it takes to
complete the steps in an OmniScript to identify process improvements.
The Tracking Service writes data to the Tracking Entry object: VlocityTrackingEntry__c. OmniStudio
components, including OmniScripts, Cards Framework, and Integration Procedures, can call the Tracking
Service. The Tracking Entry object contains the custom fields to ensure the service works, and you can add
fields to hold additional data you want to track.
The Vlocity Tracking Service class receives JSON data and writes it to the Tracking Entry object. The class
matches JSON keys to Salesforce custom field names and writes the JSON values to the field values. For
example, the class writes the value held in the JSON key ElapsedTime to the custom field
ElapsedTime__c.
This diagram shows how an out-of-box OmniScript would use the Tracking Service.
To configure triggers for custom fields, see Event Tracking for Custom Fields.
1. Go to Setup.
• In Lightning Experience, click the gear icon and select Setup from the menu.
• In Salesforce Classic, click the user menu and select Setup from the menu.
2. In the Quick Find box, type omni, then select Omni Interaction Configuration.
3. Click New Omni Interaction Configuration.
4. Enter one of the following settings in the Label field. (The Name defaults to the same value.)
Track_CardPreview
You can enable tracking for specific events of specific component types. For example, to enable only
StepActionTime events for OmniScripts, create a Track_OmniScript_StepActionTime trigger.
You can enable tracking for specific Integration Procedures using a trigger of the format
Track_Type_SubType. For example, if the Type is CheckContact and the SubType is CreditScore,
the trigger name would be Track_CheckContact_CreditScore. When one Integration Procedure
calls another, and you enable tracking only in the calling Integration Procedure, events in the called
Integration Procedure are also tracked.
5. In the Value field, type true.
6. Click Save.
7. Repeat steps 3 through 6 for each trigger you want to add.
NOTE
If you track a large amount of data, manage space consumption by implementing an
archiving policy for the tracking object.
See Also
• ???
• OmniScript Event Tracking
• Integration Procedure Event Tracking
• Event Tracking Data for Cards Framework
• Event Tracking for Custom Fields
To track events for specific Integration Procedures, see Enable Tracking for OmniStudio Components.
1. Go to Setup.
• In Lightning Experience, click the gear icon and select Setup from the menu.
• In Salesforce Classic, click the user menu and select Setup from the menu.
2. In the Quick Find box, type omni, then select Omni Interaction Configuration.
3. Click New Omni Interaction Configuration.
4. In the Label field, type OmniAnalyticsTrackingDebug.
5. In the Value field, type True.
6. Click Save.
NOTE
If your org doesn’t include the Track_CardPreview trigger, you can create it. See
Enable Tracking for OmniStudio Components.
Track_CardPreview trigger state in Custom Settings Trigger Setup Tracking entries generated for the Card Designer
Preview
Absent No
Present, but off No
Present, but the Track_CardFramework trigger is absent or off No
On, and the Track_CardFramework trigger is also on Yes
The following table lists events and event-specific data logged for user interaction with the Cards
Framework:
selectCard • ID
• Interaction Topic ID
• Name
• Policyholder
performAction • Context ID
• ID
• Interaction ID
• Role
trackField • ElapsedTime
• EntityLabel
• EntityName
• Field Value
Resolution None
(End tracking)
The name of the custom field, minus the trailing __c, must match the key of the corresponding node in the
incoming data JSON. For example:
Add the JSON key/value pairs to the Tracking Custom Data list in the component. This list is located:
NOTE
If space is a concern, be sure to monitor the size of the tracking object and delete
unneeded records as required.
For example:
CustomerInteractionId: %InteractionId%
/apex/DFOmniScriptUniversalPageConsole?id={0}&OmniScriptType=Policy
%20Servicing&OmniScriptSubType=Payment
%20Extension&OmniScriptLang=English&scriptMode=vertical&layout=lightning&Contex
tId={0}&InteractionId={1}&Role={2}
Take advantage of Vlocity's declarative 'clicks not code' approach to building and modifying your
applications with the OmniStudio Vlocity Lightning Web Components. With OmniStudio Vlocity Lightning
Web Components, use standard JavaScript and HTML to modify and extend Vlocity products.
• Fast and Lightweight. Runs natively in browsers and is independent from JavaScript frameworks.
• Reusable. OmniStudio Vlocity Lightning Web Components use web components to create reusable
custom HTML elements. Custom elements wrap functionality, protecting components from other styles
and scripts on the page.
While some OmniStudio Vlocity Lightning web components appear in the Community and App Builders,
they differ from the OmniStudio Vlocity Lightning Components that also appear in the builders. Vlocity
Lightning Web Components follow the same standards as Salesforce's Lightning Web Components. For
more information on Lightning Web Component standards, see Lightning Web Components.
NOTE
OmniStudio FlexCards are built with the Lightning Web Components programming model
and share base components. FlexCards are created in the FlexCard Designer.
• To manage and develop your LWCs with Salesforce DX, see Set Up Your Development Environment.
• To manage and develop your LWCs with IDX Workbench, see IDX Workbench Desktop Application.
NOTE
Custom Lightning web components built outside of the package cannot use any Salesforce
Lightning web component that uses Salesforce resources or affects the component at run
time. For more information, see Salesforce Modules.
NOTE
Custom Lightning web components will not throw errors unless Debug Mode is enabled.
For more information, see Debug Lightning Web Components.
1. Ensure you have IDX Workbench, or Salesforce DX set up locally. For information on setting up IDX
Workbench or Salesforce DX, see Set Up Lightning Web Components.
2. Choose which component you want to extend. For a list of Lightning web components, see OmniStudio
Lightning Web Components.
3. To create a new Lightning web component, navigate to your lwc folder in your project and run the
force:lightning:component:create SFDX command. For example:
To learn more about creating a Lightning web component, see Create Lightning Web Components. For
a complete list of available SFDX commands, see Lightning Commands.
4. In your JavaScript file, import and extend the Lightning web component. See code example on this
page.
5. To make the custom Lightning web component compatible with OmniStudio Vlocity Lightning web
components, you must set two metadata tags in your XML configuration file:
• Add the namespace of your OmniStudio Vlocity package using the runtimeNamespace metadata
tag. See the code example on this page. For more information on finding the namespace of your
package, see Viewing the Namespace and Version of the OmniStudio Vlocity Package.
• Set the isExposed metadata tag to true. See code example on this page.
6. (Optional) Enable a custom Lightning web component to make remote calls by using the Common
Action utility. For more information, see Make Remote Calls from Lightning Web Components using the
OmniScript Action Framework.
Example
In this code example, a custom Lightning web component extends the Button Lightning Web Component.
Replace the NS variable in the code example with the namespace of the OmniStudio Vlocity package you
are using.
//.js
onclickbutton() {
this.label = "Button clicked";
}}
//.js-meta.xml
//.html
<template>
//add HTML here to override the template layout
</template>
//_slds.css
sfdx force:source:push
For more on deploying components to your org with Visual Studio, see Analyze Your Code and Deploy
It to Your Org.
For information on accessing an LWC OmniScript through a URL, see Launch an OmniScript with LWC
OmniScript Wrapper.
lightning/cmp/NS__vlocityLWCWrapper?
2. Target the component by adding c__target= to the URL.
lightning/cmp/NS__vlocityLWCWrapper?c__target=
3. Set the URL to target the component by adding c: to indicate a component and add the component
name without dashes using camelCase. For example, to add a component with the name <c-demo-
button> use the syntax c:demoButton.
lightning/cmp/NS__vlocityLWCWrapper?c__target=c:demoButton
4. (Optional) When using the wrapper in a console app, add a Console Tab Icon and a Console Tab Label
by setting the c__tabIcon and c__tabLabel parameters. The c__tabIcon accepts an SLDS Icon , and
c__tabLabel accepts plain text. For example, &c__tabLabel=Custom
Label&c__tabIcon=standard:account renders the console tab shown in this example image.
5. (Optional) Assign additional attributes by passing parameters that match the attribute names.
Parameters must use the c__ prefix.
Example Button Component Code:
lightning/cmp/NS__vlocityLWCWrapper?
c__target=c:button&c__label=Dynamically Generated&c__variant=outline-brand
Example Image:
lightning/cmp/NS__vlocityLWCWrapper?c__target=c:demoButton
A DataPack is a collection of components and related functionality that are packaged for migration from one
org to another. DataPacks can be used for deployment; that is, to migrate functionality from a sandbox
environment to a production environment.
You can save in a DataPack any object listed in Supported DataPack Object Types.
NOTE
When importing and exporting data, the maximum file size is 2 MB.
Manually created DataPacks are suitable for migrating small numbers of similar objects, for example,
moving OmniScripts from a development org to a production org. However, to bulk export complex
corporate data such as products, use one of these tools:
• IDX Workbench migrates objects and metadata between orgs or between orgs and Git repositories. See
IDX Workbench Desktop Application.
• The Vlocity Build Tool creates DataPacks that preserve object relationships. See the Vlocity Build Tool
gitHub project.
The Vlocity Build tool is available from GitHub. The Build tool is a command-line tool that packages related
objects together as DataPacks, ensuring that dependencies are preserved. For example, to ensure that
data is not inadvertently duplicated, the Build tool requires certain records to have unique IDs assigned to
them. The tool provides facilities for validating data and verifying the success of migration. The GitHub
project provides detailed instructions for migration.
To simplify migration of multiple related objects, you can combine DataPacks into multipacks. To maintain
maximum control over groups of related DataPacks, incorporate version control and continuous integration
tools into your development and migration process. For guidance on how to go about this, read the
Managing Vlocity Releases white paper.
Migration is best performed by Salesforce administrators with a solid understanding of how data is stored in
Salesforce. Success depends on high quality source data.
For training on data migration and deployment, check out the Vlocity DevOps Best Practices course.
NOTE
You can import DataPacks of some older OmniStudio for Vlocity (formerly Digital
Interaction Platform) objects into an OmniStudio org. DataRaptor, Integration Procedure,
and LWC-enabled OmniScript objects are automatically converted to OmniStudio objects.
Importing DataPacks of OmniStudio objects into an OmniStudio for Vlocity org isn't
supported. Importing Cards between OmniStudio and OmniStudio for Vlocity orgs isn't
supported.
See .
Create a DataPack
To migrate data from one org to another, you can create and export DataPacks, which are files that contain
your data in JSON format.
Import a DataPack
After you’ve created a DataPack, you can import it into another org.
CAUTION
The name and version of DataPacks must be unique. If you import a DataPack that has
the same name as an existing DataPack, the existing DataPack is overwritten.
NOTE
You can import DataPacks of some older OmniStudio for Vlocity (formerly Digital
Interaction Platform) objects into an OmniStudio org. DataRaptor, Integration Procedure,
and LWC-enabled OmniScript objects are automatically converted to OmniStudio objects.
Importing DataPacks of OmniStudio objects into an OmniStudio for Vlocity org isn't
supported. Importing Cards between OmniStudio and OmniStudio for Vlocity orgs isn't
supported.
• Attachment
• Attribute Assignment Rule
• Attribute Category
• Attribute Override
• Calculation Matrix
• Calculation Procedure
• Catalog
• Charge Measurement
• Contract Type
• CPQ Custom Settings
• DataRaptor
• Document
• Document Clause
• Document Template
You can also export Vlocity contract document templates in Microsoft Word and Microsoft PowerPoint
created in Vlocity Communications, Media, and Energy.
• Entity Filter
• FlexCard
• Integration Procedure
• Interface Implementation
• Item Implementation
• Manual Queue
• Object Class
• Object Layout
• Offering Procedure
• OmniScript
• Orchestration Dependency Definition
• Orchestration Item Definition
• Orchestration Plan Definition
• Pricebook
• Price List
• Pricing Variable
• Product
• Product Hierarchy Path
• Product Relationship
• Promotion
• Query Builder
• Rule
• Scheduled Jobs
• Spec Template
• Spec Template Mapping
• Story Object
• String Translations
• System
• Time Plan
• Time Policy
• UI Section
• UI Facet
• Vlocity Action
• Vlocity Attachment
• Vlocity Card
• Vlocity Picklist
• Vlocity Interaction Launcher
• Vlocity State Model
• Vlocity UI Layout
• Vlocity UI Template
• Vlocity Intelligence Machine
• Vlocity Intelligence Resource
• Vlocity Tracking Component
• Vlocity Tracking Group
• Vlocity Web Tracking Configuration
• Vlocity Web Tracking Event Type
The solution is to run code in Anonymous Apex. To do that, you must access the Developer Console:
IDX Workbench is a desktop application that enables you to migrate OmniStudio DataPacks and Salesforce
metadata.
Components are packaged as DataPacks, which are optimized for source control and deployment to other
orgs. For example, you can develop apps on a dedicated development org, then use IDX Workbench to
deploy them to a QA org until they’re ready for use in production, and then deploy from your QA org to
production orgs.
NOTE
You can import DataPacks of some older OmniStudio for Vlocity (formerly Digital
Interaction Platform) objects into an OmniStudio org. DataRaptor, Integration Procedure,
and LWC-enabled OmniScript objects are automatically converted to OmniStudio objects.
Importing DataPacks of OmniStudio objects into an OmniStudio for Vlocity org isn't
supported. Importing Cards between OmniStudio and OmniStudio for Vlocity orgs isn't
supported.
When you choose a component for migration, IDX Workbench ensures that its dependent components are
included. For example, if you migrate an OmniScript that requires a DataRaptor, that DataRaptor is
packaged for migration with the OmniScript.
In IDX Workbench, you define the source org or repository, the target org or repository, and the components
to be migrated. You must create this definition before you can perform a migration. Migration is one way,
from source to target. Source components overwrite target components of the same name and type.
If you need a command-line client for scripting deployment, download and use the Vlocity Build Tool.
1. Go to the download site and click the link for your platform.
2. When the IDXWorkbench-release.dmg file finishes downloading, double-click the file.
3. On the Mac operating system, a pop-up window appears. Drag the app into the Applications folder.
4. Open the IDX Workbench application.
When you open IDX Workbench for the first time after installing it, the Configure Workspace dialog
appears. You must configure a workspace and project to continue. See IDX Workbench Configuration
for Migration.
5. On the Mac operating system, you might see a message stating that IDX Workbench can't be opened
because Apple can't check it for malicious software.
To allow IDX Workbench to be opened:
a. Open System Preferences.
b. Click Security & Privacy.
c. Click the General tab.
d. Click the Open Anyway button for the IDX Workbench application.
To configure automatic activation of migrated OmniScripts, Integration Procedures, and FlexCards for a
non-Chrome browser:
IDX Workbench uses the Puppeteer module to automatically activate OmniScripts, Integration
Procedures, and FlexCards in the target org.
See Also
• nodejs.org
You can also save to a JSON file when you migrate. See Save Objects to a JSON File.
NOTE
You can import DataPacks of some older OmniStudio for Vlocity (formerly Digital
Interaction Platform) objects into an OmniStudio org. DataRaptor, Integration Procedure,
and LWC-enabled OmniScript objects are automatically converted to OmniStudio objects.
Importing DataPacks of OmniStudio objects into an OmniStudio for Vlocity org isn't
supported. Importing Cards between OmniStudio and OmniStudio for Vlocity orgs isn't
supported.
1. In the org you plan to use as your Source, make sure the correct versions of Salesforce objects you
want to migrate are active.
Some objects, such as OmniScripts and Integration Procedures, have versions that can be activated
and deactivated. Only active versions of such objects are migrated.
2. Open IDX Workbench. If no projects exist, the Configure Workspace dialog appears.
If other projects exist and you want to create a new project, click the Edit icon on the main IDX
Workbench screen to open the Configure Workspace dialog.
3. From the Repository drop-down list, select New Repository.
You must create a repository for the project even if both your source and target are orgs.
4. In the New Repository dialog, specify a Name and a Repository Folder. If the folder doesn't exist, it's
created. Click Save.
5. From the Source drop-down list, select New Environment. (An environment is an org.)
To configure limited access to an org, see Configure an Org Using a Community User Login.
6. In the New Salesforce Org dialog, specify a Name.
To configure limited access to an org, see Configure an Org Using a Community User Login.
10. From the Project drop-down list, select New Project.
To use a Project object instead of configuring a project, see the next section.
11. In the New Project dialog, specify a Name for your project.
12. Select the types of Vlocity and/or Salesforce objects to migrate. You can use the Search field to filter
the list. Select all the types you need.
15. Move the objects you want to migrate from the All datapacks list to the Selected datapacks list. You
can use the Shift key to select multiple items in either list.
You can click Ignore Dependencies to exclude dependent objects from migration.
16. Click Save. The Configure Workspace dialog reappears.
17. To refresh comparison data whenever you save the workspace, make sure the Force refresh of data
from orgs box is checked.
The green + icons indicate that the objects are new in the Source org.
20. To edit the repository:
a. Click the Edit icon on the main IDX Workbench screen to reopen the Configure Workspace dialog.
b. Click the Edit icon next to the Repository drop-down list to open the Repository Settings.
c.
Edit the Expansion Path if you want to change the subfolder of the repository folder in which
DataPacks are stored.
d. Specify Additional DataPack Query Filters if you want to filter objects of the specified type in all
projects that use the repository. Click Add New Filter to add as many filters as you need.
For example, setting DataPack Type to Product2 and Additional Query Filter to
RecordTypeId != null excludes non-Vlocity products.
e. Click Save.
21. To add objects to the project:
a. Click the Edit icon on the main IDX Workbench screen to reopen the Configure Workspace dialog.
b. Click the Edit icon next to the Project drop-down list to reopen the Project dialog.
c. Repeat steps 12 through 18 above.
You must set up the Community user to have access to all Integration Procedure related objects, the
Tracking Service, and the Apex class ProcedureTestFramework.
1. Configure the Source and Target. See steps 1 through 9 of Configure for Migration Between Orgs.
2. From the Project drop-down list, select Load Projects from Source.
This retrieves active Project objects in the Source org that have a Status of Released.
3. When the Project objects finish loading, select a Project object.
4. To refresh comparison data whenever you save the workspace, make sure the Force refresh of data
from orgs box is checked.
5. Click Save.
1. Follow the instructions for migrating between orgs. See Configure for Migration Between Orgs.
2. In step 5, select Import JSON from the Source drop-down list and browse for the file.
To create a project using the Salesforce Industries Process Library as its Source:
1. Open IDX Workbench. If no projects exist, the Configure Workspace dialog appears.
If other projects exist and you want to create a new project, click the Edit icon on the main IDX
Workbench screen to open the Configure Workspace dialog.
2. Select Vlocity Process Library from the Repository drop-down list.
3. Click Login with different username.
4. Click Continue to open the Vlocity Process Library in a browser tab.
5. In the browser tab, log into the Vlocity Process Library using your Vlocity Success Community
username and password.
6. If you see the Allow Access? window, click Allow.
7. After successful login, return to IDX Workbench and click the Refresh button under Vlocity Process
Listing.
8. From the Process Listing drop-down list, select the desired listing.
9. From the Target drop-down list, select a previously configured org or New Environment.
For a new org, follow steps 5 through 8 in Configure for Migration Between Orgs.
10. Click Save.
Instructions differ depending on the type of repository and whether you use a password or SSH — see the documentation for your
repository. If you use Bitbucket with password access, see Give a Bitbucket Git Repository Access to IDX Workbench.
1. Follow the instructions for migrating between orgs. See Configure for Migration Between Orgs.
2. In step 4, in the New Repository dialog, paste the cloning URL into the Clone from Git Repository
URL field.
3. In step 5, select the repository as the Source, or in step 9, select the repository as the Target.
7. Click Create.
8. Copy the displayed password to a place from which you can copy it again, such as a text file.
https://[email protected]/company/reponame.git
13. Edit the URL to add a colon and the password after the username. For example:
https://username:[email protected]/company/reponame.git
This is the URL you will paste into the Clone from Git Repository URL field when you create the
Repository used as the Source.
14. Click Close.
1. Click the Edit icon on the main IDX Workbench screen to reopen the Configure Workspace dialog.
2. Change the Repository, Source, and Target as needed.
3. For the Project drop-down list, select New Project.
4. Configure the project.
5. In the Configure Workspace dialog, click Save.
See Also
• Configure for Migration Between Orgs
1. Click the Edit icon on the main IDX Workbench screen to reopen the Configure Workspace dialog.
2. From the Repository drop-down list, select the Repository for the project. You must do this even if your
project migrates between orgs and your repository is just a folder.
3. For the Project drop-down list, select the project.
4. Verify that the Source and Target are correct. Change them if necessary.
See Also
• Configure for Migration Between Orgs
1. If the Configure Workspace dialog isn't open, click the Edit icon on the main IDX Workbench screen to
open it.
2. Don't delete the Source or Target org, but select New Environment from the Source or Target drop-
down list.
3. Follow steps 6 through 8 of the instructions for migrating between orgs above.
4. In the Configure Workspace dialog, click Save.
A .vlocityignore file follows all the rules for .gitignore files. For more information, see Ignoring
Files.
1. Place a file named .vlocityignore in the top level of your repository folder.
2. Open this file in a text editor.
3. Add the names of object types and/or objects to ignore, each on a separate line.
For example, the following file ignores all CalculationMatrix objects except the one named Matrix1:
CalculationMatrix
!CalculationMatrix/Matrix1
4. Save the file.
In addition, information about the objects appears in the Comparison and Migration tabs.
• Refresh All — Refreshes information for all objects on the Source and Target orgs.
• Refresh Source — Refreshes information for all objects on the Source only.
• Refresh Target — Refreshes information for all objects on the Target only.
• Refresh Selected — Refreshes information for the selected objects only, on the Source and Target.
• Reset Differences — Reverts local changes without retrieving new information from the Source or
Target.
This is also useful if you have made any changes to the underlying data using the Revert or Edit as
JSON options in individual DataPacks.
If you see a Login Failed ... Please Login Again message, follow the instructions under Handle
a Login Failed Message in IDX Workbench Configuration for Migration.
When the refresh completes, yellow tilde (~) icons indicate objects that are not the same on both orgs.
Green plus (+) icons indicate new objects in the Source.
Related DataPacks lists dependencies of the current object. Where Used lists object of which the current
object is a dependency.
You can click View Source to see additional details about the differences.
• Select the check box next to each object to be migrated and click Actions > Migrate with
Dependencies.
• Go to the Migration tab and click Migrate with Dependencies for each object you want to migrate.
White circles indicate that components are now the same on both orgs.
To delete a component from a DataPack that you are exporting, locate it in the per-element diffs and click
Discard All. For example, you can delete components that you added for debugging but want to remove
for production. Note that your edits are not propagated back to the source org. If you click Discard All by
mistake, use Refresh > Reset Differences to reinstate the component.
• By Keyword — Type part of a name to display items with that part in their names.
• By Selection — Check Selected Items to display items you have selected. Check Unselected Items to
display items you have not selected.
• By Change Type — Check New Items to display items in the Source but not the Target. Check
Changed Items to display items that have been updated in the Source.
• By Status — Check Failed to display components that failed to be migrated.
• By Project — Check Hide Dependencies to hide components that aren't explicitly included in the
project but that are dependencies of components that are included.
10. If new performance data has been generated in the org, click Refresh Data to download it.
For example, when you retrieve OmniScript data, the Process Profiler looks something like this:
8. Click View Source to see additional details about the differences. To delete a component from the
target version, click Discard All.
To create Test Procedures, see Test Procedures: Integration Procedures for Unit Testing.
4. Select the check box next to each Test Procedure to run. To run all Test Procedures, check All Tests.
5. Click Actions > Start Test.
When tests are complete, results appear in the Test Results pane.
If a test fails, the failure message and test expression from the Test Procedure's Assert Action for
Integration Procedures are displayed.
For details about this data, see Integration Procedure Event Tracking.
7. To display a chart of running times for the Test Procedure steps, click View Chart.
If an Assert Action fails, a warning icon (! within a triangle) appears next to the step.
8. To see the running times for an Integration Procedure being tested, expand the Integration Procedure
Action step.
9. To go to a step in the org, right-click the step name, then click Open in Browser.
For example, right-clicking a DataRaptor Extract Action opens the DataRaptor that the step calls.
10. To display data for a specific step in a pop-up window, click the bar for that step in the chart.
11. You can expand Data and scroll down to see the request and response data.
• Repository > Settings — Lets you open the Repository Settings window for the current repository
without having to open the Configure Workspace window first. Includes the following settings:
• Expansion Path — Determines the subfolder of the repository folder in which DataPacks are stored.
• Additional DataPack Query Filters — Filters objects of the specified type in all projects that use the
repository. Click Add New Filter to add as many filters as you need.
For example, setting DataPack Type to Product2 and Additional Query Filter to RecordTypeId !=
null excludes non-Vlocity products.
• Project > Edit Project Details — Lets you open the Edit Project window for the current project without
having to open the Configure Workspace window first.
• Jobs > Ensure Global Keys in Source — Iterates over the data in the Source org and makes sure that
every record that needs it has a Global Key value.
• View > Reload — Reloads the IDX Workbench application.
• View > Force Reload — Forces a reload of the IDX Workbench application.
• View > Toggle Developer Tools — Displays or hides a development environment.
• Debug > Open Logs — Opens the IDX Workbench log file.
It is very important to include log data when submitting a Vlocity Support Case.
• Debug > Reset Repository Data — Resets the IDX Workbench configuration as if it were newly
installed. This clears all projects. However, it doesn't delete project folders.
You can restore a project in the Configure Workspace dialog by selecting New Repository and
referencing the existing Repository Folder for the project.