OmniStudio Documentation

OmniStudio Foundation
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.
Table of Contents
OmniStudio ................................................................................................................................ 1
OmniStudio Basics ..................................................................................................................... 2

OmniScript Basics .............................................................................................................. 2
FlexCards Basics ................................................................................................................ 4
Customer Context ....................................................................................................... 4
Designer .................................................................................................................... 4
FlexCards .................................................................................................................. 4
Design and Layout ...................................................................................................... 5
Data Sources ............................................................................................................. 5
DataRaptor or Integration Procedure? .................................................................................. 5
See Also .................................................................................................................... 6
Use the Applications Together ............................................................................................. 6
Customizable Style Guide for Newport Design System .......................................................... 7
About the Newport Design System ............................................................................... 7
Callable Implementations .................................................................................................... 7
Viewing the Namespace and Version of the OmniStudio Vlocity Package ............................... 8
See Also .................................................................................................................... 9
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
© 2021 Vlocity LLC, a Salesforce

company
Activate Elements in the OmniScript Designer ............................................................. 21

Preview an OmniScript ............................................................................................... 22
Test Data in the OmniScript Designer .......................................................................... 23
OmniScript Script Structure Definitions ........................................................................ 25
Upgrade an OmniScript's Property Set ........................................................................ 27
OmniScript Setup Reference .............................................................................................. 28
Default Setup Properties ............................................................................................ 28
Setup Property Sections ............................................................................................. 28
Configure an OmniScript's Currency Code .................................................................. 29
Step Chart Options .................................................................................................... 29
Configure OmniScript Cancel Options ......................................................................... 30
Save and Resume an OmniScript ............................................................................... 31
Integrate Salesforce Knowledge with OmniScript ......................................................... 36
Seed Data Into an OmniScript .................................................................................... 43
Messaging Framework ............................................................................................... 44
Enable SEO for OmniScripts ...................................................................................... 44
Create Stateful OmniScripts ....................................................................................... 46
Customize OmniScript Error Messages ....................................................................... 48
OmniScript Element Reference ........................................................................................... 50
Common OmniScript Element Properties Definitions .................................................... 51
OmniScript Action Elements ....................................................................................... 53
OmniScript Display Elements ..................................................................................... 91
OmniScript Function Elements .................................................................................... 91
OmniScript Group Elements ....................................................................................... 92
OmniScript Input Elements ....................................................................................... 126
Create a Custom Lightning Web Component for OmniScript ............................................... 152
Requirements .......................................................................................................... 152
Custom OmniScript Lightning Web Components ........................................................ 153
Custom LWC Element .............................................................................................. 153
Extend an OmniScript Element's Lightning Web Component ...................................... 154
Extend the OmniScriptBaseMixin Component ............................................................ 156
Create a Standalone Custom Lightning Web Component ........................................... 169
Communicate with OmniScript from a Lightning Web Component ............................... 171
Make Remote Calls from Lightning Web Components using the OmniScript Action
Framework .............................................................................................................. 174
Add Validation to a Custom Lightning Web Component in OmniScript ......................... 181
Customize the Step Chart Component ...................................................................... 182
Extend and Override an OmniScript Modal Lightning Web Component ........................ 182
Extend and Override the Save for Later Acknowledge Lightning Web Component ....... 183
Add Custom Lightning Web Components to an OmniScript ................................................ 184
See Also ................................................................................................................. 184
Override an Element's Lightning Web Component ..................................................... 184
Map an Element Type to a Custom Lightning Web Component ................................... 185
Add a Custom Lightning Web Component to a Custom LWC Element ......................... 185
Style OmniScripts ............................................................................................................ 187
See Also ................................................................................................................. 187

company
Apply Custom Styling to OmniScripts with Static Resources ....................................... 187

Reference Stylesheet Names in an OmniScript's JSON .............................................. 189
Customize SLDS Design Tokens in OmniScript ......................................................... 190
Use Images for Buttons in OmniScript ....................................................................... 192
Line Break ............................................................................................................... 192
Apply Global Branding to OmniScripts ....................................................................... 193
Modify OmniScript UI Behavior ......................................................................................... 195
Conditionally Display Elements Using the Conditional View Property ........................... 195
Hide OmniScript Elements ....................................................................................... 197
Hide the Next and Previous Buttons .......................................................................... 198
Display Messages in OmniScripts ............................................................................. 198
Fire Platform Events from OmniScripts ...................................................................... 200
Set Errors In an OmniScript ...................................................................................... 201
Deploy, Launch, and Embed OmniScripts .......................................................................... 204
Activate and Deploy OmniScripts .............................................................................. 204
How to Launch ........................................................................................................ 206
Launch OmniScripts from Lightning and Community Pages ........................................ 207
Run OmniScripts Off-Platform with OmniOut ............................................................. 218
Deploy an OmniScript to an External Salesforce Site ................................................. 218
Embed an OmniScript Lightning Web Component in a Lightning Web Component ....... 218
Embed an OmniScript in Another OmniScript ............................................................ 220
Adding an Apex Class Permissions Checker ............................................................. 221
Create Multi-Language OmniScripts .................................................................................. 222
See Also ................................................................................................................. 222
Enable Multi-Language OmniScript Support .............................................................. 222
Define Custom Label Translations in Multi-Language OmniScripts .............................. 223
Access Custom Labels in an OmniScript Custom Lightning Web Component .............. 225
Translate Tooltip Help Text in OmniScripts ................................................................. 225
Translate Custom Labels for Date and Time Components .......................................... 226
Create Multi-Language Select Elements .................................................................... 230
Test a Multi-Language OmniScript ............................................................................ 233
Launch a Multi-Language OmniScript ........................................................................ 233
OmniScript Custom Label Reference ........................................................................ 234
Advanced Configuration for OmniScript Form Elements ..................................................... 236
Add Options for Selects, Multi-Selects, and Radio Buttons ......................................... 236
Set Date and Time Ranges ...................................................................................... 237
Tying a Picklist to Salesforce .................................................................................... 238
Populating Picklist Values From Apex ....................................................................... 240
Populating Dependent Picklist Values with Apex ........................................................ 241
Lookup Element ...................................................................................................... 243
Working with Lookup Query Configurations ............................................................... 247
Controlling Field Property ......................................................................................... 249
Evaluating Elements in Repeatable Blocks ................................................................ 252
Using the Rich Text Editor in the Vlocity OmniScript Designer ..................................... 252
OmniScript Data and External Integrations ........................................................................ 253
Load Data into OmniScript Elements ......................................................................... 254

company
Manage OmniScript Data ......................................................................................... 258

Create and Update Data from OmniScripts ................................................................ 272
Integrating DocuSign with OmniScript ....................................................................... 277
Managing OmniScripts ..................................................................................................... 281
Export OmniScripts .................................................................................................. 281
Import OmniScripts .................................................................................................. 282
Version OmniScripts ................................................................................................ 282
Emailing an OmniScript ............................................................................................ 283
Embed FlexCards in an OmniScript .................................................................................. 284
See Also ................................................................................................................. 286
OmniScript ReadMe Reference ........................................................................................ 286
Base Component ReadMes ...................................................................................... 287
Mixin ReadMes ........................................................................................................ 287
OmniStudio FlexCards ............................................................................................................. 288

Cards .............................................................................................................................. 288
Flyouts ............................................................................................................................ 288
Data Sources .................................................................................................................. 289
Design and Layout ........................................................................................................... 289
Publish Options ............................................................................................................... 289
Deploy FlexCards ............................................................................................................ 289
FlexCard Designer ........................................................................................................... 289
FlexCard Designer Highlights ................................................................................... 290
What's Next ............................................................................................................. 290
Get to Know the FlexCard Designer .......................................................................... 291
Get Started with FlexCards ............................................................................................... 302
Build a FlexCard with the FlexCard Designer ..................................................................... 303
Create a New FlexCard ............................................................................................ 304
Configure Setup Options .......................................................................................... 305
Add, Configure and Style Elements ........................................................................... 305
Preview FlexCard .................................................................................................... 305
Activate FlexCard .................................................................................................... 305
Configure Publish Options ........................................................................................ 305
What's Next ............................................................................................................. 305
Create a New FlexCard .................................................................................................... 305
Configure Basic Settings .......................................................................................... 305
Configure Data Source ............................................................................................. 306
Enter Test Input Parameters ..................................................................................... 306
What's Next ............................................................................................................. 307
See Also ................................................................................................................. 307
Add an Action to a FlexCard ............................................................................................. 307
What's Next ............................................................................................................. 308
Add a Click Event to a FlexCard Element .................................................................. 308
FlexCards Actions Reference ................................................................................... 308

company
FlexCards Action Properties ..................................................................................... 309

Navigate from a FlexCard with the Navigate Action .................................................... 312
Create an Email Link from a FlexCard Navigation Action ............................................ 313
Launch a Flyout from an Action on a FlexCard ........................................................... 313
Launch an OmniScript from a FlexCard ..................................................................... 315
Update an OmniScript from a FlexCard ..................................................................... 317
Select Items on a FlexCard to Update an OmniScript ................................................. 319
Trigger a Custom Event from an Action on a FlexCard ............................................... 322
Trigger a Pubsub Event from an Action on a FlexCard ............................................... 324
Add an Action to Update a Data Source on a FlexCard .............................................. 326
Add an Action to Update Field Values on a FlexCard .................................................. 327
Add a Reload Action to a FlexCard ........................................................................... 327
Add a Remove Action to a FlexCard ......................................................................... 328
Add Elements to a FlexCard ............................................................................................. 328
Add, Configure, and Style an Element ....................................................................... 330
What's Next ............................................................................................................. 332
See Also ................................................................................................................. 332
FlexCards Elements Reference ................................................................................ 333
Group Elements Inside a Block on a FlexCard ........................................................... 333
Add a Chart to a FlexCard ........................................................................................ 335
Embed a Child FlexCard Inside a FlexCard ............................................................... 340
Embed a Custom LWC Inside a FlexCard .................................................................. 351
Add a Datatable to a FlexCard .................................................................................. 353
Add a Field to a FlexCard ......................................................................................... 358
Add an Icon to a FlexCard ........................................................................................ 361
Add an Image to a FlexCard ..................................................................................... 362
Add a Menu to a FlexCard ........................................................................................ 365
Add a Text Element to a FlexCard ............................................................................. 367
Trigger Actions with the Toggle Element on a FlexCard .............................................. 368
Add Conditions to a FlexCard Element ...................................................................... 374
FlexCards Common Element Properties .................................................................... 375
FlexCard States ............................................................................................................... 376
Add a State to a FlexCard ........................................................................................ 376
Add Conditions to a FlexCard State .......................................................................... 378
FlexCards State Properties ....................................................................................... 380
Configure a Data Source on a FlexCard ............................................................................ 381
See Also ................................................................................................................. 381
FlexCards Data Source Reference ............................................................................ 381
FlexCards Data Source Properties ............................................................................ 382
Enable and Disable Data Sources ............................................................................. 385
Configure a DataRaptor Data Source on a FlexCard .................................................. 385
Configure an Integration Procedure Data Source on a FlexCard ................................. 386
Configure a SOQL Query Data Source on a FlexCard ................................................ 390
Configure a SOSL Search Data Source on a FlexCard ............................................... 391
Configure a Custom Data Source on a FlexCard ........................................................ 392
Configure an Apex REST Data Source on a FlexCard ................................................ 394

company
Configure an Apex Remote Data Source on a FlexCard ............................................. 395

Configure a REST Data Source Using Named Credentials on a FlexCard ................... 397
Configure a REST Web Data Source on a FlexCard .................................................. 398
Vlocity Streaming API Data Sources ......................................................................... 399
FlexCard SDK Data Source ...................................................................................... 406
Test Data Source Settings on a FlexCard .................................................................. 412
Set Up a FlexCard in the FlexCard Designer ..................................................................... 414
What's Next ............................................................................................................. 414
See Also ................................................................................................................. 414
FlexCard Setup Reference ....................................................................................... 414
Repeat Options in the FlexCard Designer .................................................................. 415
Add Session Variables to a FlexCard ........................................................................ 418
Add an Event Listener to a FlexCard ......................................................................... 418
Enable Multi-Language Support on a FlexCard .......................................................... 422
Enable OmniScript Support on a FlexCard ................................................................ 422
Limit User Access to a FlexCard with Custom Permissions ......................................... 422
Style FlexCard Elements .................................................................................................. 424
Style Options Available to All Elements ..................................................................... 424
Style Options Available to Specific Elements ............................................................. 424
Add Conditional Styles to a FlexCard Element ........................................................... 425
FlexCards Element Dimensions ................................................................................ 426
FlexCards Element Appearance ............................................................................... 433
FlexCards Element Alignment .................................................................................. 434
FlexCard Elements Custom CSS .............................................................................. 436
FlexCards Action Style Properties ............................................................................. 441
FlexCards Datatable Style Properties ........................................................................ 442
FlexCards Field Style Properties ............................................................................... 443
FlexCards Icon Style Properties ................................................................................ 443
FlexCards Menu Style Properties .............................................................................. 444
FlexCards Toggle Style Properties ............................................................................ 444
Create a Custom Style for a FlexCard Element .......................................................... 445
Display Records Side-By-Side on a FlexCard ............................................................ 447
Arrange, Duplicate, and Remove Elements on a FlexCard .......................................... 449
Pass Concatenated Strings As Values in FlexCards ........................................................... 450
Enable Tracking on a FlexCard ......................................................................................... 451
See Also ................................................................................................................. 451
FlexCard Designer Preview .............................................................................................. 451
Preview a FlexCard ................................................................................................. 452
FlexCards Preview 'Add Test Params' Properties ....................................................... 453
FlexCard Designer Data JSON ................................................................................. 454
View a FlexCard's Data JSON .................................................................................. 455
FlexCard Designer Action Debugger ......................................................................... 456
Debug FlexCard Action and Event Requests and Responses ..................................... 457
View a FlexCard at Different Viewport Breakpoints ............................................................. 457
What's Next ............................................................................................................. 458
See Also ................................................................................................................. 458

company
Activate a FlexCard ......................................................................................................... 458

Activate from the FlexCard Designer ......................................................................... 459
Activate from the FlexCards Home ............................................................................ 459
What's Next ............................................................................................................. 459
See Also ................................................................................................................. 459
Configure Publish Options on a FlexCard .......................................................................... 459
What's Next ............................................................................................................. 459
FlexCards Publish Options Properties ....................................................................... 460
Define Metadata Values from the FlexCard Designer ................................................. 460
Add a Custom Component SVG Icon to a FlexCard ................................................... 462
Add Custom Labels to Supported Fields on a FlexCard ...................................................... 462
What's Next ............................................................................................................. 463
Pass Data from an LWC OmniScript to an Embedded FlexCard .......................................... 463
Download a Sample DataPack ................................................................................. 464
Map Data from an LWC OmniScript to an Embedded FlexCard ................................... 464
Pass the RecordId from an OmniScript to Run a Query on a FlexCard ........................ 464
Pass a Parent Object from an LWC OmniScript to Run a Query on a FlexCard ............ 465
Download a Sample DataPack that Passes Data from an LWC OmniScript to a
FlexCard ................................................................................................................. 466
Reload a FlexCard After Updating an LWC OmniScript in a Flyout ...................................... 468
Add a FlexCard to a Lightning Page .................................................................................. 468
Add a FlexCard to a Community Page .............................................................................. 469
Run FlexCards Outside of Salesforce with OmniOut .......................................................... 469
Access the ContextId of a FlexCard on a Community Page ................................................ 469
Configure Community Profiles for FlexCards ..................................................................... 470
Disable Enhanced Profile User Interface ................................................................... 471
Configure Custom Object Permissions for Community Profiles ................................... 471
Grant Apex Class Access to a Community Profile ...................................................... 471
FlexCards Versioning and Cloning .................................................................................... 472
FlexCards Versioning ............................................................................................... 473
FlexCards Cloning ................................................................................................... 475
FlexCard Naming Conventions ................................................................................. 478
Delete a FlexCard ............................................................................................................ 478
Import a FlexCard ............................................................................................................ 479
See Also ................................................................................................................. 480
Download FlexCard Sample DataPacks ............................................................................ 480
See Also ................................................................................................................. 481
Export a FlexCard ............................................................................................................ 481
What's Next ............................................................................................................. 481
See Also ................................................................................................................. 482
Download a FlexCard LWC from the FlexCard Designer ..................................................... 482
See Also ................................................................................................................. 482
Download an Off-Platform FlexCard LWC from the FlexCard Designer ................................ 482
See Also ................................................................................................................. 483
FlexCards Context Variables ............................................................................................ 483
Global Variables ...................................................................................................... 483

company
Local Variables ........................................................................................................ 484

FlexCards Troubleshooting Considerations ........................................................................ 485
Update Remote Site Settings to Preview Your FlexCard ............................................. 485
Update the Card Object's Lightning Record Page to Access the FlexCard Designer ..... 486
Fix Cyclic Redundancy When Embedding FlexCard Components ............................... 487
OmniOut ................................................................................................................................. 488

Download the OmniOut Static Resource ........................................................................... 489
What's Next ............................................................................................................. 489
See Also ................................................................................................................. 489
Install OmniOut Dependencies ......................................................................................... 489
What's Next ............................................................................................................. 489
See Also ................................................................................................................. 490
Include Nested Custom LWCs in Your OmniOut OmniScript ............................................... 490
What's Next ............................................................................................................. 490
See Also ................................................................................................................. 490
Add an OmniScript Lightning Web Component to OmniOut ................................................ 491
What's Next ............................................................................................................. 494
See Also ................................................................................................................. 494
Add a FlexCard LWC to OmniOut ..................................................................................... 494
Create a Connected App for OmniOut ............................................................................... 495
What's Next ............................................................................................................. 496
See Also ................................................................................................................. 497
Configure Multi-Language in OmniOut for OmniScripts ....................................................... 497
What's Next ............................................................................................................. 498
See Also ................................................................................................................. 498
Run OmniOut in Development Mode ................................................................................. 498
What's Next ............................................................................................................. 500
See Also ................................................................................................................. 500
Navigate to a URL from an OmniScript in an OmniOut App ................................................ 500
What's Next ............................................................................................................. 501
See Also ................................................................................................................. 502
Navigate to a URL from a FlexCard in an OmniOut App ..................................................... 502
What's Next ............................................................................................................. 502
See Also ................................................................................................................. 502
Move OmniOut into Your App ........................................................................................... 502
What's Next ............................................................................................................. 506
See Also ................................................................................................................. 506
Add OmniScripts to Adobe Experience Manager ................................................................ 506
Integrate Salesforce Cloud Services into Adobe Experience Manager ......................... 506
Set the OmniOut Resource Path ............................................................................... 507
Deploy OmniOut to Adobe Experience Manager ........................................................ 507
Add the Vlocity LWC OmniOut Component to Adobe Experience Manager .................. 508
Add Custom Style Sheets to Your OmniOut Application ...................................................... 509

company
What's Next ............................................................................................................. 510

See Also ................................................................................................................. 510
Connect Your OmniOut App ............................................................................................. 510
Sample OmniOut Apps ............................................................................................ 510
Create a Connection Object in OmniOut .................................................................... 519
Create a Connection Object in OmniOut for FlexCards ............................................... 521
OmniStudio DataRaptors .......................................................................................................... 523

DataRaptor Turbo Extract Overview .................................................................................. 523
Create a DataRaptor Turbo Extract ........................................................................... 524
Configure a DataRaptor Turbo Extract ....................................................................... 524
Related Object Fields in DataRaptor Turbo Extracts ................................................... 525
Test a DataRaptor Turbo Extract ............................................................................... 527
Create a DataRaptor Turbo Extract Example ............................................................. 527
DataRaptor Extract Overview ........................................................................................... 529
Create a DataRaptor Extract ..................................................................................... 530
Define the Initial Extraction ....................................................................................... 530
When to Use Multiple Extract Steps .......................................................................... 531
Relationship Notation versus Multiple Extract Steps ................................................... 533
DataRaptor Extract Output ....................................................................................... 535
Test a DataRaptor Extract ........................................................................................ 537
DataRaptor Extract Examples ................................................................................... 538
DataRaptor Transform Overview ....................................................................................... 546
Create a DataRaptor Transform ................................................................................ 547
DataRaptor Transform Data Mappings ...................................................................... 547
Use Quick Match to Map Data .................................................................................. 549
XML in DataRaptors ................................................................................................. 550
Test a DataRaptor Transform .................................................................................... 551
DataRaptor Transform Examples .............................................................................. 551
DataRaptor Load Overview .............................................................................................. 554
Create a DataRaptor Load ....................................................................................... 555
Object Field Mapping ............................................................................................... 556
Multiple Related Object Loads (Link Mappings) ......................................................... 557
Test a DataRaptor Load ........................................................................................... 558
DataRaptor Load Examples ...................................................................................... 558
DataRaptor Best Practices ............................................................................................... 561
List Input for DataRaptors ................................................................................................. 562
See Also ................................................................................................................. 563
Use Formulas in DataRaptors ........................................................................................... 564
See Also ................................................................................................................. 564
Create a DataRaptor Example with a Formula ........................................................... 564
DataRaptor Output Data Types ......................................................................................... 566
DataRaptor Developer Features ....................................................................................... 567
DataRaptor REST API ............................................................................................. 567

company
DataRaptor Calls From Apex .................................................................................... 569

DRGlobal Class and Methods ................................................................................... 571
Environment Variables in DataRaptors and Integration Procedures ............................. 573
Custom Input and Output for DataRaptors ................................................................. 573
Cache for DataRaptors and Integration Procedures ........................................................... 579
Metadata Cache for DataRaptors and Integration Procedures ..................................... 579
Methods to Clear Metadata from Either Cache ........................................................... 580
Methods to Clear Data from the Scale Cache ............................................................ 580
See Also ................................................................................................................. 581
Security for DataRaptors and Integration Procedures ......................................................... 581
Configure DataRaptor and Integration Procedure Security Settings ............................. 582
DataRaptor and Integration Procedure Security Settings ............................................ 582
Implement the VlocityRequiredPermissionCheck Class .............................................. 583
OmniStudio Integration Procedures ........................................................................................... 585

See Also ......................................................................................................................... 586
Create an Integration Procedure ....................................................................................... 586
Access Integration Procedure Data JSON with Merge Fields .............................................. 588
Common Use Cases ................................................................................................ 588
Access the Data JSON ............................................................................................ 588
Additional Syntax ..................................................................................................... 588
Group Integration Procedure Steps Using Blocks ............................................................... 589
Define Execution Logic Using Conditional Blocks ....................................................... 589
Enhance Performance Using Cache Blocks ............................................................... 593
Process Arrays Using Loop Blocks ........................................................................... 600
Handle Errors Using Try-Catch Blocks ...................................................................... 613
Integration Procedure Actions ........................................................................................... 618
See Also ................................................................................................................. 619
Common Integration Procedure Action Properties ...................................................... 619
Set Values for Integration Procedures ....................................................................... 620
Assert Action for Integration Procedures ................................................................... 625
Chatter Action for Integration Procedures .................................................................. 626
DataRaptor Extract Action for Integration Procedures ................................................. 629
DataRaptor Post Action for Integration Procedures .................................................... 629
DataRaptor Transform Action for Integration Procedures ............................................ 630
DataRaptor Turbo Action for Integration Procedures .................................................. 632
Delete Action ........................................................................................................... 633
DocuSign Envelope Action for Integration Procedures ................................................ 634
Email Action for Integration Procedures ..................................................................... 634
HTTP Action for Integration Procedures .................................................................... 639
Integration Procedure Action for Integration Procedures ............................................. 643
List Action for Integration Procedures ........................................................................ 647
Remote Action for Integration Procedures ................................................................. 656
Response Action for Integration Procedures .............................................................. 661

company
Integration Procedure Best Practices ................................................................................ 662

Cache for DataRaptors and Integration Procedures ........................................................... 663
Metadata Cache for DataRaptors and Integration Procedures ..................................... 663
Methods to Clear Metadata from Either Cache ........................................................... 664
Methods to Clear Data from the Scale Cache ............................................................ 664
See Also ................................................................................................................. 665
Cache for Top-Level Integration Procedure Data ........................................................ 665
Configure Top-Level Caching for an Integration Procedure ......................................... 668
Create a Top-Level Caching Example ....................................................................... 668
Turn Off the Scale Cache ......................................................................................... 671
Error Handling in Integration Procedures ........................................................................... 671
Environment Variables in DataRaptors and Integration Procedures ..................................... 672
External Objects in Integration Procedures ........................................................................ 673
Query-Handling Logic in the Integration Procedure .................................................... 674
Query Result Format ................................................................................................ 675
See Also ................................................................................................................. 676
Implement an External Object in an Integration Procedure .......................................... 676
Test Procedures: Integration Procedures for Unit Testing .................................................... 676
When to Mock Integration Procedure Components .................................................... 677
HTTP Callouts in Called Apex Classes ...................................................................... 677
Workflow for Test Procedure Example ....................................................................... 678
Integration Procedure Invocation ...................................................................................... 681
Integration Procedure Invocation from Apex .............................................................. 681
Integration Procedure Unit Testing from Apex ............................................................ 682
Integration Procedure Invocation from REST APIs ..................................................... 685
Integration Procedure Invocation from Salesforce Flow .............................................. 688
Settings for Long-Running Integration Procedures ............................................................. 689
Chainable and Queueable Chainable Settings ........................................................... 690
How to Call a Chainable or Queueable Chainable Integration Procedure ..................... 691
The Chain on Step Setting ....................................................................................... 691
Chainable and Queueable Chainable Settings in Preview ........................................... 691
The Action Message Property in the Calling OmniScript ............................................. 691
JavaScript Code to Call Chainable Integration Procedures ......................................... 692
Invoke a Chainable Integration Procedure with REST Calls ........................................ 693
Continuation in Long-Running Calls .................................................................................. 695
Make a Long-Running Remote Call Using VlocityContinuationIntegration .................... 695
Make a Long-Running Remote Call Using OmniStudio.OmniContinuation ................... 699
Security for DataRaptors and Integration Procedures ......................................................... 703
Configure DataRaptor and Integration Procedure Security Settings ............................. 704
DataRaptor and Integration Procedure Security Settings ............................................ 704
Implement the VlocityRequiredPermissionCheck Class .............................................. 705
Calculation Procedures and Matrices ........................................................................................ 707

Calculation Example for Life Insurance Quote .................................................................... 708

company
Calculation Matrices ......................................................................................................... 709

Standard Calculation Matrices .................................................................................. 710
Grouped Calculation Matrices ................................................................................... 711
Row-Versioned Calculation Matrices ......................................................................... 712
Ways to Create a Standard Calculation Matrix ........................................................... 714
Workflow for Creating a Grouped Calculation Matrix .................................................. 721
Workflow for Creating a Row Versioned Calculation Matrix ......................................... 723
Wildcards in Calculation Matrices ............................................................................. 726
Search in a Calculation Matrix .................................................................................. 726
Download Calculation Matrix Data to a CSV File ........................................................ 727
Edit and Delete Matrix Data ...................................................................................... 727
Edit Matrix Headers ................................................................................................. 727
Disable a Calculation Matrix ..................................................................................... 728
Ranges in Calculation Matrices ................................................................................. 728
Calculation Procedures Overview ..................................................................................... 731
Use Cases for Calculation Procedures ...................................................................... 732
Use Apex to Define Pricing Logic .............................................................................. 733
Clone a Calculation Procedure ................................................................................. 733
Variables and Constants in Calculation Procedures .................................................... 734
Conditional Steps For Calculation Procedures ........................................................... 735
Functions for Calculation Procedures ........................................................................ 735
Declarative Calculation Procedures ................................................................................... 736
What's in a Calculation Procedure ............................................................................ 737
How Calculation Procedures Work in Context ............................................................ 738
How Aggregation Works in Calculation Procedures .................................................... 739
Preprocessor and Postprocessor Classes ................................................................. 741
Workflow for Creating a Calculation Procedure .......................................................... 741
Create a New Version of a Calculation Procedure ...................................................... 745
The Looping Feature in Calculation Procedures ......................................................... 746
Configure a Calculation Procedure for Looping .......................................................... 751
Preprocessor Class Example .................................................................................... 752
Vlocity Actions ......................................................................................................................... 754

Configure a Vlocity Action ................................................................................................ 754
Update Filter Logic for Vlocity Actions ............................................................................... 757
Update Profile Settings for Contract Actions ...................................................................... 758
Update the Link Type for an Action ................................................................................... 759
Target URL and URL Parameters ..................................................................................... 760
Available Visualforce Pages to Launch OmniScripts ................................................... 760
Formatting the Target URL ....................................................................................... 760
URL Parameters ...................................................................................................... 762
Navigating URLs in Lightning and Lightning Community ............................................. 763
Display Vlocity Actions with the Vlocity Action Toolbar ........................................................ 763
Add the Vlocity Action Toolbar to a Lightning Record Page ......................................... 763

company
Add the Vlocity Actions Toolbar to a Community Record Page .................................... 764
Configure the Vlocity Action Toolbar .......................................................................... 764
Formulas and Functions ........................................................................................................... 765

Function Reference ......................................................................................................... 765
Supported Operators ............................................................................................... 765
Supported Functions ................................................................................................ 765
Sample Apex Code for a Custom Function ........................................................................ 797
List Input in Custom Functions .......................................................................................... 798
OmniStudio Tracking Service .................................................................................................... 800

Enable Tracking for OmniStudio Components .................................................................... 801
OmniStudio Components Event Tracking .......................................................................... 802
See Also ................................................................................................................. 802
OmniScript Event Tracking ............................................................................................... 802
Integration Procedure Event Tracking ............................................................................... 803
Add Debugging Data to Test Procedure Event Tracking .............................................. 804
Cards Framework Event Tracking ..................................................................................... 804
Preview Event Tracking in the Cards Designer ........................................................... 805
Event Tracking Data for Cards Framework ................................................................ 805
Event Tracking for Custom Fields ..................................................................................... 806
Tracking Session Interaction Id ......................................................................................... 806
Tracking Data Preprocessor ............................................................................................. 807
OmniStudio Lightning Web Components ................................................................................... 809

OmniStudio Vlocity Lightning Web Components Reference ................................................ 809
Set Up Lightning Web Components .................................................................................. 809
Extend Vlocity Lightning Web Components ....................................................................... 810
Example .................................................................................................................. 811
Deploy Lightning Web Components .................................................................................. 812
Launch Lightning Web Component URLs with vlocityLWCWrapper ..................................... 812
Configuring a URL to launch a Lightning Web Component .......................................... 812
Launching an LWC from a Layout Action ................................................................... 813
Base Vlocity LWC ReadMe Reference .............................................................................. 814
Data Migration with OmniStudio DataPacks ............................................................................... 815

Create a DataPack .......................................................................................................... 816
Import a DataPack ........................................................................................................... 816
Supported DataPack Object Types ................................................................................... 817
Fix the DataPack Import/Export Error: No Configuration Found ........................................... 819

company
IDX Workbench Desktop Application ......................................................................................... 820

Install IDX Workbench ...................................................................................................... 820
Configure LWC OmniScript and FlexCard Activation and Compilation ................................. 821
See Also ................................................................................................................. 821
IDX Workbench Configuration for Migration ....................................................................... 821
Configure for Migration Between Orgs ....................................................................... 822
Configure an Org Using a Community User Login ...................................................... 828
Configure a Project Object ....................................................................................... 828
Configure for Migration from a JSON File .................................................................. 829
Configure for Migration from the Salesforce Industries Process Library ....................... 829
Configure for Migration Between a Repository and an Org .......................................... 829
Give a Bitbucket Git Repository Access to IDX Workbench ......................................... 830
Create Additional Projects ........................................................................................ 833
Switch Between Projects .......................................................................................... 833
Handle a Login Failed Message ................................................................................ 833
Use a .vlocityignore File to Exclude Objects .............................................................. 834
Object Migration and Comparison ..................................................................................... 834
Migrate Objects from the Source to the Target ........................................................... 834
Object Migration and Comparison Options ................................................................. 836
Save Objects to a JSON File .................................................................................... 839
Use the IDX Workbench Process Profiler .......................................................................... 839
Compare OmniScript and Integration Procedure Versions .................................................. 840
Run Test Procedures ....................................................................................................... 842
IDX Workbench Menu Commands .................................................................................... 849

company
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.
With OmniStudio, you can create:
• OmniScripts, which contain the interaction logic

• DataRaptors, which transfer and transform data between Salesforce and the OmniScripts, FlexCards,
and Integration procedures tools.
• Integration Procedures, which bundle server-side operations for efficiency and reuse
• FlexCards, which display data and launch actions

company 1
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:
• A customer service agent to add a new customer

• An insurance agent to update a policy
• An end user to complete a self-service interaction such as troubleshooting
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:
• Add actions such as extract data or send an email

• Group items together by creating a step or displaying a list of items the customer can select from
• Create a function such as a formula
• Add input fields and lookups for the user to enter data
• Refine the display by using a headline or text block
• Create branches that dynamically adjust the controls and enable or disable steps depending on choices
the user makes in the guided process
• Configure calculations and messages that provide immediate feedback and error checking to the user
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.

company 2
You can launch an OmniScript from anywhere, including:
• An action button such as the one shown here on the account page
• An action link on a card

company 3
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
Actions on an account card might include:

company 4
• 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.
Design and Layout

Style individual elements or add custom CSS directly on an element within the FlexCard Designer. You can
also make elements responsive. See Style FlexCard Elements.
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.
DataRaptor or Integration Procedure?

OmniStudio DataRaptors read or write Salesforce SObject data or perform single-step data
transformations. OmniStudio Integration Procedures can interact with many types of data and process it in
multiple steps. For some use cases, a single DataRaptor is sufficient. Integration Procedures usually call
one or more DataRaptors and are more flexible and powerful. Use these guidelines to help you determine
which to build.
Use a single DataRaptor if:
• 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.
Use an Integration Procedure if:
• 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.

company 5
See Also
• DataRaptor Best Practices
• Integration Procedure Best Practices
Use the Applications Together

Use the OmniStudio applications together. Create guided interactions with OmniScripts; get and post data
with DataRaptors and Integration Procedures; and display data and launch actions with FlexCards.
Here's an example of FlexCards, OmniScripts, and DataRaptors used together to:
• Display and provide a context for information and actions

• Complete a guided process
• Retrieve the correct data for the process
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.

company 6
Customizable Style Guide for Newport Design System

Vlocity's customers have their own set of brand guidelines and design specifications, particularly for
customer-facing applications. The Vlocity Omniscript and Cards Designers allow you to choose between
two templates:
• Lightning: This references the Salesforce Lightning Design System.

• Newport: This references Vlocity's style guide.
About the Newport Design System

Newport is the CSS framework that allows customers to re-theme all the Vlocity components in one place.
It is intended as a tool for both designers and web developers to easily re-style all the Vlocity components
in a single place and generate custom, optimized CSS files that can be used consistently across all
components and pages.
The Newport Design System supports two functions:
• Provides an out-of-the-box consumer-grade visual style guide.

• Provides a framework for re-branding and updating Vlocity components globally.
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.
Although the VlocityOpenInterface and VlocityOpenInterface2 interfaces enable flexible

implementations with a uniform signature, they reside in the Vlocity managed package and aren't truly
Salesforce standards. However, classes that implement VlocityOpenInterface or
VlocityOpenInterface2 also implement the Callable Interface, which is a Salesforce standard.
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.
To change custom classes that implement VlocityOpenInterface or VlocityOpenInterface2 to

Callable implementations, convert the signature with a few lines of code:
global with sharing class ClassName implements Callable

{

company 7
public Object call(String action, Map<String, Object> args) {
Map<String, Object> input = (Map<String, Object>)args.get('input');

Map<String, Object> output = (Map<String, Object>)args.get('output');
Map<String, Object> options = (Map<String, Object>)args.get('options');
return invokeMethod(action, input, output, options);

}
private Object invokeMethod(String methodName, Map<String, Object>
inputMap, Map<String, Object> outMap, Map<String, Object> options) {
...
}
...
}
For a full example, see Make a Long-Running Remote Call Using OmniStudio.OmniContinuation.
Viewing the Namespace and Version of the OmniStudio Vlocity

Package
To check the namespace and version of your OmniStudio Vlocity package:
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.

company 8
See Also
Overview of Packages in the Salesforce help.

company 9
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.
OmniScript Best Practices

Enhance the performance and usability of OmniScript by following the OmniScript best practices whenever
possible.
Business Process and Logic

Business Process and Logic best practices include:
• Use one owner for each OmniScript.

• Identify reusable elements by building a skeleton of the entire OmniScript.
• Document the purpose of an element in the element's Internal Notes property.
• Maintain DataRaptors and Apex classes by avoiding element name changes. If the element name must
be updated, apply the name changes to the DataRaptor or Apex class.
• Avoid assigning a ContextId within the OmniScript. OmniScript's ContextId is a reserved key that assigns
a Record Id from the URL.
• When processes are repeatable across multiple OmniScripts, create a reusable OmniScript, and add it to
the appropriate parent OmniScripts. See Embed an OmniScript in Another OmniScript.
User Interface
OmniScripts use Lightning Web Components to define the styling for both individual elements and the
OmniScript itself.
Best practices include:
• 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.
User Experience Design Principles

UX design principles include:
• 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.

company 10
• 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.
Client-side best practices include:
• Reduce Conditional Views, Merge Fields, Formulas where possible.

• Speed up the application of responses by trimming the Response JSON. For more information, see
Manipulate JSON with the Send/Response Transformations Properties.
• Remove spaces from element names to improve the OmniScript's load time.
• Reduce the number of elements in the script. A single OmniScript should not exceed 200 elements.
• Run logic on the server where possible, including conditional logic in Integration Procedures and
formulas in DataRaptors.
• Test performance by enabling time tracking. If time tracking is not used in production, disable the feature
before deploying to production. For more information, see OmniStudio Tracking Service.
Server-side best practices include:
• Cut down the payload size of a request by trimming the JSON request. For more information, see
• 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.
OmniScript Designer Overview

The OmniScript Designer enables you to preview dynamic web forms as you build them using a drag-and-
drop interface with WYSIWYG editing.
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.

company 11
Header (1), Navigation Panel (2), Canvas (3), Build panel (4), Properties panel (5), Setup panel (6),
Preview (7)
OmniScript Designer Highlights

Notable features of the OmniScript Designer include:
• 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.
Navigation Panel (2)

Access and navigate between active and inactive actions, steps, and step elements from the Navigation
Panel.

company 12
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.
(B) Rearrange, clone, and delete elements as needed.
(C) Adjust the width of the Canvas from either side.
(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.
Build panel (4)

Drag action, display, function, group, and input elements, and entire OmniScripts from the Build panel onto
the Canvas to build your scripts.

company 13
Properties panel (5)

In the Properties panel, configure properties for action, display, function, group, input, and embeddable
OmniScript elements in the UI, or edit properties as JSON.
Setup panel (6)

Configure optional script-wide settings in the Setup panel.
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.
(A) Access in-line information about properties with tooltips.
(B) View detailed documentation about element functionality with slide-out help panels.

company 14
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.
Access OmniScript Designer

Access OmniScript Designer through the Salesforce app launcher menu.
1. Click App Launcher.

2. Select the OmniScripts app.
3. From the OmniScripts list page, click New to create an OmniScript, select an existing OmniScript, or
import an OmniScript from another org using a datapack.

company 15
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.
1. From the OmniScripts home page, click New.

2. Enter a Name for your OmniScript.
3. Enter a Type, SubType, and Language. Type, SubType, and Language combine to create a unique
identifier that becomes the name of a compiled OmniScript's Lightning web component. For example,
an OmniScript where Type=account, SubType=Create, and Language=English generates an
LWC named accountCreateEnglish.
4. (Optional) Enter a Description for your OmniScript.
5. Click Save.
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.
Before You Begin

Create an OmniScript. See Create an OmniScript.
1. From your OmniScript, click Setup to view the Setup panel.

2. Configure specific Setup properties. See OmniScript Setup Reference.
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
Creating the Script Structure

Create the logic that executes when the script runs, by building a hierarchical structure of Actions and
Steps.
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

company 16
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.
Build an OmniScript with Elements in the OmniScript Designer

Drag elements and entire OmniScripts from the Build panel onto the canvas to build your scripts in the
OmniScript Designer.
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

company 17
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.
Figure 1. Script Structure
Before You Begin

1. Create an OmniScript. See Create an OmniScript.
2. Set up your OmniScript with optional settings. See Set Up an OmniScript.
1. From OmniScript, click Build to open the Build panel.

company 18
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.
5. To post changes made to data fields:

a. Enter a name in the Name field.
b. From the DataRaptor Post Action dropdown, select a DataRaptor that posts data back to
Salesforce.
c. (Optional) To configure other DataRaptor Post Action properties, see DataRaptor Post Action
Properties.
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.

company 19
See Also
• Preview an OmniScript
• Test Data in the OmniScript Designer
Configure Elements in the OmniScript Designer

Configure elements for your OmniScript in the Properties panel of the designer when an element is
selected, such as the name, label, and instructions for a step element.
Before You Begin

3. Add elements to your OmniScript. See Build an OmniScript with Elements 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.

company 20
7. To activate the element, click Active.
What's Next
Next steps, preview the look and functionality of your OmniScript. See Preview an OmniScript.
See Also
• Launch an OmniScript with LWC OmniScript Wrapper
Activate Elements in the OmniScript Designer

Activate an inactive element by selecting the element in the Navigation Panel of the OmniScript Designer.
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.
Navigation Panel: Slide View (default)

Navigation Panel: Tree View

company 21
Activating Step or Action Elements

To activate an inactive step or action outside of a step:
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.
Activating Elements Inside Steps

To activate an inactive element inside a step:
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
Preview an OmniScript
View the OmniScript's appearance and functionality by previewing the OmniScript in the OmniScript
Designer.
Before You Begin

3. Add elements to your OmniScript. See Build an OmniScript with Elements in the OmniScript Designer.
4. Configure your OmniScript elements. See Configure Elements in the OmniScript Designer.
1. In your OmniScript, click Preview.

2. For additional preview options, select these properties:
• Context ID: If your OmniScript does not have a Set Values Action that defines a ContextId, to
preview the form with test data, enter a record ID.
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.

company 22
• 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
Test Data in the OmniScript Designer

Test your OmniScript in the OmniScript Designer by adding test data, viewing the data JSON, and
debugging action requests and response data.
Before You Begin

Preview the look and functionality of your OmniScript. See Preview an OmniScript.

company 23
Add Test Data
1. From OmniScript, click Preview.

2. If your OmniScript does not have a SetValues action that defines a ContextId, to preview the form with
data, enter a record ID in the Context ID field.
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.
View the Data JSON
1. View the JSON Data in the Data JSON.

2. (Optional) Click the clipboard icon to copy the full JSON.
View and Debug Action Requests and Response Data
1. Click Action Debugger to open the debug console.

2. (Optional) Search for an action name in the Search field.
3. (Optional) To copy a specific node, click the clipboard icon next to the node. For example, copy
Remote Options in a DataRaptor Extract Action.

company 24
4. (Optional) To clear the debug console, click Clear Logs.

5. (Optional) Click the reload icon to repopulate the debug console with new action request and response
data.
Next Steps
Next steps, launch your OmniScript on a Lightning or Community page. See Activate and Deploy
OmniScripts.
See Also
OmniScript Script Structure Definitions

Vlocity OmniScripts are defined by Administrators directly within the Vlocity application.
A script is defined through the following declarative, hierarchical structure:

company 25
• 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.

company 26
• 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.
Upgrade an OmniScript's Property Set

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 could appear in the designer. Prevent
or resolve this error by upgrading the OmniScript's property set.
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

company 27
OmniScript Setup Reference

OmniScript's setup section provides multiple configuration options that enable you to define the appearance
and behavior of the OmniScript.
Default Setup Properties

The default Setup properties apply to your entire OmniScript and are not included in property sections. See
Setup Property Sections.
Property Description Example

Console Tab Icon Applies an icon to the console tab where the OmniScript is embedded. The n/a
Console Tab Label and Console Tab Icon settings in OmniScript will only apply if
the OmniScript owns the entire tab or subtab. The Console Tab Label and
Console Tab Icon settings will not be used if the OmniScript is embedded on a
page with other components.
Console Tab Title Applies text to the console tab where the OmniScript is embedded. The Console n/a
Tab Label and Console Tab Icon settings in OmniScript will only apply if the
OmniScript owns the entire tab or subtab. The Console Tab Label and Console
Tab Icon settings will not be used if the OmniScript is embedded on a page with
other components.
Currency Code By default, OmniScript uses the org default currency in single currency orgs and a Configure an
user's currency in multi-currency orgs. Override the default currency by OmniScript's Currency
configuring the currency code field. Code
Reusable Enables the OmniScript to be embedded into another OmniScript when checked. Embed an OmniScript
in Another OmniScript
Element Type To Enables a custom Lightning web component to override all elements of a specific Add Custom Lightning
LWC Component Element Type. Web Components to
Mapping an OmniScript
Element Type A specific Element Type, such as Text or Edit Block, that is overridden by your Enable SEO for
custom Lightning Web Component. OmniScripts
Enable SEO Make your OmniScript's URL available to search engines. Enable SEO for
OmniScripts
Enable Unload Enables a Leave Site? warning to be triggered by reloading, navigating away, or n/a
Warning closing the window. For modal customization options, see Extend and Override an
OmniScript Modal Lightning Web Component.
Fetch Picklist Enables picklist values to be retrieved at script load when checked. If unchecked, n/a
Values At Script picklists will be fetched at design time.
Load
Lightning Web The target custom Lightning Web Component that you map to your Element Type. Enable SEO for
Component OmniScripts
Seed Data JSON Seed Data JSON enables the OmniScript to be seeded with data on launch. It Seed Data Into an
does not allow for referencing other data with the %element% syntax or use of OmniScript
expressions. For more robust functionality, use the Set Values action.
Tracking Custom Log custom data to the Vlocity Tracking Entry table by adding Key/Value pairs. n/a
Data Requires the Vlocity Tracking Service to be enabled in Custom Settings.
Setup Property Sections

Setup property sections include sets of properties that apply to a specific configuration, such as displaying
Knowledge Base articles in your OmniScript.

company 28
Section Description Configuration

Step Chart Options Hide the step chart or choose where to display it relative to your Step Chart Options
OmniScript.
Cancel Options Enable cancel functionality and configure how the cancel behavior Configure OmniScript Cancel
executes. Options
Save Options Enable users to save an OmniScript for later use. Configure Save Options
Knowledge Options Enable Knowledge Articles to display in or alongside your OmniScript. Integrate Salesforce
Knowledge with OmniScript
Error Messages Set a default error message or simplify error messages for users. Customize OmniScript Error
Messages
Messaging Pass information using Pub/Sub, windowPostMessage, and Session Messaging Framework
Framework Storage.
Styling Options Customize the design of your OmniScript using custom stylesheets, Style OmniScripts
design tokens, and a scroll animation.
Configure an OmniScript's Currency Code

Override an org's default currency in an OmniScript by setting the OmniScript's Currency Code.
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.
Org Currency Option Example

Single Currency From OmniScript Setup, click Currency Code and select Currency Code = JPY
a Currency from the dropdown list.
Multi-Currency Dynamically pass in the Currency Code from a URL using &c__OmniScriptCurrencyCode=JPY
the OmniScriptCurrencyCode parameter.
Step Chart Options

Hide or move an OmniScript's Step Chart using Step Chart Options. To customize the Step Chart, see
Customize the Step Chart Component.
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
• Customize the Step Chart Component

• OmniScript Setup Reference

company 29
Configure OmniScript Cancel Options

Navigate users to different Salesforce experiences after canceling an OmniScript by configuring cancel
options.
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.
PageReference Type Description

App Launch a standard or custom app that is available from the app launcher. Connected apps are not
supported.
Community Named Page Direct users to a Named Page in a Community.
Component Navigate to Aura components and Lightning web components.
Current Page Trigger a page update on the current page once a user completes the OmniScript.
Knowledge Article Display knowledge articles in the OmniScript.
Login Open a Community login page.
LWC OmniScript Launch another LWC OmniScript.
Named Page Open a standard Named page.
Navigation Item A page displaying mapped content on a CustomTab.
Object Direct users to a standard or custom object page.
Record Open a page that interacts with a Salesforce record.
Record Relationship Open a record relationship page.
Vlocity OmniScript Launch a separate OmniScript.
Web Page Open an external URL.
6. In Target Parameters, enter additional parameters to pass to the selected experience.

company 30
7. (Optional) Configure Messaging Framework options. See Messaging Framework.
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
Save and Resume an OmniScript

Enable users to save and resume OmniScripts by using OmniScript's Save Options property. Users can
bookmark links, launch a saved instance from an object page, or email the link. Configure custom URLs to
resume saved OmniScript instances in different domains. For example, a customer can initiate an
OmniScript inside of a Community, and then a customer service representative can resume the OmniScript
inside of the Service Console.
Next Steps
Configure Save Options
Configure Save Options

Enable users to Save and Resume OmniScripts by configuring the Save for Later functionality.
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:

company 31
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
Map Saved Instance URLs to Custom Fields

Configure where a saved OmniScript instance launches in Salesforce by mapping URLs to custom fields on
the Saved OmniScript object.
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.
Before You Begin

When using Community pages to launch saved OmniScript instances, add the Vlocity LWC OmniScript Wrapper component to the
Community page. See Launch an OmniScript with LWC OmniScript Wrapper.
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.

company 32
• 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
Customize the Save for Later Error Message

Create custom error messages with OmniScript's error handling framework.
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

company 33
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.
1. In the OmniScript's Setup panel, expand the Error Messages section.

2. Leave the Path value blank. The error message is in the OmniScript's root path.
3. In the Custom Error Messages section, leave the Path value blank. The error message is in the
OmniScript's root path.
4. In the Value field, enter this default error message text: This saved OmniScript has been
updated since resuming. To see the latest updates, please exit and resume
the saved OmniScript again.
5. In the Message field, enter a custom error message.
6. Save and Activate the OmniScript.
7. (Optional) Test the OmniScript by taking these steps:
a. Open the OmniScript and save an instance.
b. Resume the saved OmniScript instance in two separate tabs.
c. In one of the instances, add additional information and save the OmniScript.
d. In the other instance, try to add information and save the instance to view the custom error.
See Also

• Map Saved Instance URLs to Custom Fields
Conditionally Display Elements in Saved OmniScripts for Different User Profiles

Control which OmniScript elements display to different profile users in a saved OmniScript instance by
using conditions.
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.
1. In an element's Conditional View property, click Add Condition.

2. In the first field, enter userProfile.
3. In the second field, enter the name of a User Profile. For example, System Administrator.
The following figure shows settings for an element that displays only to call center agents.

company 34
See Also
View In-Progress and Completed OmniScripts

Enable users to view in-progress OmniScripts that have been saved for later by using Visualforce pages
and the Vlocity OmniScript Workbench.
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.
Display Saved OmniScript Instances for Accounts and Contacts

Add the provided OmniScriptInstanceAccountPage Visualforce page to the Account layout or the
OmniScriptInstanceContactPage to the Contact layout.
Display Saved OmniScript Instances on ObjectRecord Pages

Display saved OmniScript instances on an object record page by creating a Visualforce page and adding
the component to the object's layout.
1. Create a new Visualforce page.

2. Copy and paste the following code into a new Visualforce page.
<apex:page standardStylesheets="false" showHeader="true"

standardController="ObjectName" extensions="NS.VFPageControllerBase"
sidebar="true" docType="html-5.0" >
<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.

company 35
View All Saved OmniScript Instances

View all Saved OmniScript instances by opening the Vlocity OmniScript Workbench.
To open the Vlocity OmniScript Workbench:
1. Open the Salesforce App Launcher.

2. Click Vlocity OmniScript Workbench.
See Also

Specify a Resume Link in a Visualforce Page

Users can create a VisualForce page that specifies the custom URL used for Save and Resume.
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.
<apex:page standardStylesheets="false" showHeader="true"

standardController="Account" extensions="VFPageControllerBase" sidebar="true"
docType="html-5.0" >
<c:OmniScriptInstanceComponent standardController="{!stdController}"
resumeFieldName="FieldAPIName"/>
</apex:page>
See Also

Integrate Salesforce Knowledge with OmniScript

Enable users to search and view Salesforce Knowledge Articles when using an OmniScript. Configure
OmniScript Knowledge Options to search for articles based on static values and dynamic inputs from
OmniScript fields, or a query from a simple search bar.

company 36
IMPORTANT
Your organization must have Salesforce Knowledge enabled to use this feature.
Figure 2. Simple Search Bar
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.

company 37
Figure 3. Article Open in the OmniScript as a Collapsible Block
Figure 4. Article Open in a Modal Window

company 38
Setup OmniScript to Work with Salesforce Knowledge

Integrate Salesforce Knowledge into your OmniScript to enable users to search and view Salesforce
Knowledge articles in the OmniScript. OmniScript also supports querying Lightning Knowledge.
Before You Begin

1. Enable Salesforce Knowledge. See Enable Salesforce Knowledge.
2. (Optional) Enable Lightning Knowledge. SeeEnable Lighting Knowledge.
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.

company 39
Lightning Knowledge Record Type API name

b. In Field API Name, enter 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 Field API Name

company 40
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
• Configure Knowledge for Individual Steps in the OmniScript
Configure Knowledge for Individual Steps in the OmniScript

After the initial configuration to set up your OmniScript to work with Salesforce Knowledge, integrate
Knowledge in your OmniScript Steps. Configure options on each step to enable Knowledge and filter
results.
Before You Begin

Setup your OmniScript to work with Salesforce Knowledge, see Setup OmniScript to Work with Salesforce Knowledge.
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
• Open Knowledge Base Articles Outside an OmniScript

company 41
Open Knowledge Base Articles Outside an OmniScript

Launch Knowledge base articles outside of an OmniScript using the Vlocity OmniScript Knowledge Base
component in a Community or Lightning page.
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.
Before You Begin

1. Configure the fields that query the Knowledge base. See Setup OmniScript to Work with Salesforce Knowledge.
2. (Optional) Define Knowledge base queries at the step level. See Configure Knowledge for Individual Steps in the OmniScript.
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
• Setup OmniScript to Work with Salesforce Knowledge

Knowledge Options Properties Reference

Knowledge Options properties are configurable from the Setup and Properties panels in the OmniScript
Designer. Enable Knowledge in your OmniScript to allow users to view and search for articles from your
Salesforce Knowledge articles. See Integrate Salesforce Knowledge with OmniScript.
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.

company 42
Setup panel
These properties are unique to the Knowledge Options section in the Setup panel.
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.
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
• Setup OmniScript to Work with Salesforce Knowledge

• Open Knowledge Base Articles Outside an OmniScript
Seed Data Into an OmniScript

Prefill OmniScript fields with data or add hidden nodes to the OmniScript Data JSON using the Seed Data
JSON property in the OmniScript's Setup section.
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.

company 43
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:
Property Description Object or Example

Component
Window Send information from an element to a window Window object Message with Window Post
postMessage object in key-value pairs. Messages and Session
Storage Messages
Pub/Sub Communicate with OmniScript from a custom LWC Lightning Web Communicate with
by sending key-value pairs. Use the events passed Components OmniScript from a Lightning
in the key-value pairs to trigger custom behavior in Web Component
a component.
Session Storage Send information to a Session Storage object using Session Storage Message with Window Post
key-value pairs. A session storage object clears object Messages and Session
when a page session ends. Storage Messages
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
Enable SEO for OmniScripts

Make OmniScripts in Communities appear in online searches by enabling SEO.

company 44
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.
Before You Begin

1. Set Up SEO for Your Community (Salesforce Documentation).
2. Review SEO Best Practices and Considerations for Guest Users (Salesforce Documentation).
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.

company 45
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
• Create Stateful OmniScripts
Create Stateful OmniScripts

Enable LWC OmniScripts to store the state of an OmniScript in the URL.
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

company 46
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%.

company 47
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
• Save and Resume an OmniScript
Customize OmniScript Error Messages

The error message handler enables you to replace default error messages from remote apex calls with
more user-friendly error messages when errors occur in OmniScript. The Error Messages handler property
is available in File elements, Image elements, all Action elements, and Setup.
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.
Error Message Description

Type
Default Error A default message that returns when no Custom Error Messages are matched or defined. The Default Error
Message Message property is not available in Setup.

company 48
Error Message Description

Type
Custom Error Messages that are returned based on the defined path and value. Custom Error Messages are configured using
Messages the following fields:
• 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.
Set the Default Error Message on an OmniScript Element

Replace a Default Error Message with a user-friendly error message when a remote apex call error occurs
in your OmniScript. A default message returns when no Custom Error Messages are matched or defined.
Update the default error messages for Image, Action, and File elements.
Before You Begin

Before configuring Error Messages, preview the errors to determine their format.
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
• Set a Custom Error Message That Returns as an Object

• Set a Custom Error Message That Returns as a String
Set a Custom Error Message That Returns as an Object

Set a Custom Error Message for an error that returns as an object. A Custom Error Message returns based
on a defined path and value. Set custom error messages for File elements, Image elements, all Action
elements, and Setup.
Before You Begin

1. Run the OmniScript to encounter the error.

2. Determine the path to the error. For example, the path for errorCode in the following error
[{"errorCode":"NOT_FOUND","message":"The requested resource does not
exist"}] is 0 : errorCode .
3. Copy the error message text that follows the path. For example, the error message text for errorCode
in the following error: [{"errorCode":"NOT_FOUND","message":"The requested resource
does not exist"}] is NOT_FOUND .
4. Open the Error Messages property in the Action Element that is rendering the error.
5. In the Path field, enter the path determined by Step 2.
6. In the Value field, paste the original error.
7. In the Message field, enter your custom message.

company 49
8. Test to ensure the message is being replaced.
See Also
• Set a Custom Error Message That Returns as a String

• Set the Default Error Message on an OmniScript Element
Set a Custom Error Message That Returns as a String

Set a Custom Error Message for an error that returns as a string. A Custom Error Message returns based
on a defined path and value. Set custom error messages for File elements, Image elements, all Action
elements, and Setup.
Before You Begin

1. Run the OmniScript to encounter the error.

2. Copy the text following the colon after the word Error.
3. Open the Error Messages property in the Action Element that is rendering the error.
4. In the Value field, paste the original error.
5. In the Message field, enter your custom message.
6. Test to ensure the message is being replaced.
See Also
• Set the Default Error Message on an OmniScript Element

• Set a Custom Error Message That Returns as an Object
OmniScript Element Reference

This guide contains explanations of the different elements that can be added to an OmniScript. Each
element uses an extendable Lightning web component.
• Action Block (see Action Block)

• Aggregates (see Creating a Formula or Aggregate in an OmniScript)
• Blocks
• Checkbox (see OmniScript Input Components)
• Currency (see OmniScript Input Components)
• Custom LWC (see Custom LWC Element)
• DataRaptor Extract Action
• DataRaptor Post Action
• DataRaptor Transform Action
• DataRaptor Turbo Action
• Date (see OmniScript Input Components)
• Date/Time (Local) (see OmniScript Input Components)
• Delete Action (see Delete Action )

company 50
• Disclosure (see OmniScript Input Components)

• DocuSign Envelope Action (see Preparing DocuSign Documents)
• DocuSign Signature Action (see Preparing DocuSign Documents)
• Edit Block (see Using OmniScript Edit Blocks)
• Email
• Email Action (see OmniScript Email Action)
• File (see Adding a File Component to the Structure of an OmniScript)
• Formulas (see Creating Formula Fields in an OmniScript)
• Headline (see OmniScript Display Components)
• HTTP Action
• Image (see OmniScript Display Components)
• Integration Procedure Action (see OmniScript Integration Procedure Action)
• Line Break (see OmniScript Display Components)
• Lookup (see Working with Lookup Query Configurations)
• Multi-select (see OmniScript Input Components)
• Navigate Action (see Navigate Action)
• Number (see OmniScript Input Components)
• OmniScript (see OmniScript Action Components)
• Password (see OmniScript Input Components)
• PDF Action (seeAdding a PDF Action to the OmniScript)
• Radio (see OmniScript Input Components)
• Radio Group (see OmniScript Group Component)
• Range (see OmniScript Input Components)
• Remote Action (see OmniScript Remote Action)
• Rest Action (see HTTP Action)
• Select (see OmniScripts Select Element)
• Set Errors (see Setting Errors In an OmniScript)
• Set Values (see Setting Values in an OmniScript)
• Signature (see OmniScript Input Components)
• Step
• Telephone (see OmniScript Input Components)
• Text (see OmniScript Input Components)
• Text Area (see OmniScript Input Components)
• Text Block (see OmniScript Input Components)
• Time (see OmniScript Input Components)
• Type Ahead Block (see Adding a Type Ahead Block)
• URL (see OmniScripts URL Element)
Common OmniScript Element Properties Definitions

Each element also includes an extensible Property set that is specific to the type of element. Use the
Properties pane on the Designer to edit these properties. Some common element properties are not
available in certain elements.

company 51

Add Condition Add additional test conditions to an element's Conditional View. Conditionally Display
Elements Using the
Conditional View
Property.
Add Group Group conditions to create complex expressions. A group enables a set of n/a
conditionals to have a separate AND/OR operator. For example, there can be two
groups ORed together, but inside of each group there can be an AND to ensure
the group tests are true.
Available For Data JSON can prefill the element when it is hidden by a conditional. n/a
Prefill When
Hidden
Conditional View If conditions in this field are met, the element displays, becomes editable, or is Conditionally Display
marked as required. The Value field supports merge syntax. Elements Using the
Conditional View
Property.
Conditional Type Condition types determine whether element shows, disables read only, or Conditionally Display
becomes required when the conditions evaluate to true. Elements Using the
Conditional View
Property
Control Width Display width of the control on the page, using a range of 1-12. n/a
Default Value: Sets a default value for the element. If the element has been prefilled with a Set a Default Value for
value, it will not be overwritten by the default value. Supports merge syntax. an Element
Element Name The unique identifier for the element. Element Names cannot contain spaces and n/a
must be unique in an OmniScript.
Field Width Displayed if the Label outside of field checkbox is checked. Specifies the width n/a
of the input field separate from the Control Width. Useful if the label is longer than
the expected input.
Help Text The text displayed when the user hovers over the help icon. n/a
Help Determines if a help icon is displayed to the user. n/a
Label outside of For input components, specifies whether the label displays outside the field. Valid n/a
field only when using the Lightning Experience.
Label Display label for the control. n/a
Mask Sets the format for user input, for example, (999)999-9999. n/a
Maximum Length Maximum number of characters the user can enter. n/a
Minimum Length Minimum number of characters the user can enter. n/a
Options An array of input selections for drop-down, multi-select, and radio button controls. n/a
Pattern Error Text Message displayed if the input does not match the expression. n/a
Pattern The pattern flag is used to enforce data validation before submitting. Currently, Regular Expressions
complex patterns are not supported, but simple pattern matching works. The
patterns accept regular expressions (regex), and custom error text.
Placeholder Displays placeholder text in empty fields. Placeholder text is not applicable if n/a
masking is enabled.
Read Only If true, the user cannot modify the value in the field. n/a
Repeat If true for an element or block, a user can click + to copy the element or blocks of Prefill Repeatable
elements on the form. Blocks
Repeat Clone If true, any values from the element or block of elements are copied to repeated n/a
instances of the element or block.
Repeat Limit Specifies the number of times this element can be repeated. For example, to set n/a
a maximum of two repetitions, set Repeat Limit to 1.

company 52

Required Specifies whether the user must enter a value in order to submit the form. n/a
Show/Hide Determines whether multiple conditions must be met to render an OS. When set n/a
Operator to All Conditions Are Met an AND operator checks if all conditions are valid.
When set to Any Condition Is Met an OR operator checks if any of the
conditions are valid.
OmniScript Action Elements

This page contains a table explaining the available OmniScript elements listed under the Actions section.
Element Element Description Reference

Name
DataRaptor The DataRaptor Extract Action element makes a DataRaptor Extract Action
Extract Action DataRaptor outbound call to populate an OmniScript
with data from SFDC objects. Inputs DataRaptor
Interface name and input parameters.
DataRaptor The DataRaptor Post Action commits data from DataRaptor Post Action
Post Action OmniScript to SFDC objects. Inputs DataRaptor
Interface name, Data JSON of OmniScript, and
filesMap.
DataRaptor The Data Raptor Transform Action sends the full OmniScript DataRaptor Transform
Transform OmniScript Data JSON to DataRaptor and returns Action
Action the mapping from the DataRaptor.
Delete Deletes specified records from an sObject. Objects If the data JSON contains a list of
are specified by Id, and best practice is to use a accounts like this:
merge field to refer to an Id or a list of Ids in the data
JSON. {
"Account": [
{
"accId":
["001f400000EPQ8o",
"001f400000BAkbn"]
}
]
}
You can delete it by specifying the

following merge field in the Path to Id
field: %Account:accId%
To specify messages to be displayed to

users when the operation succeeds or
fails, set the corresponding fields in the
Error Messages section.
DocuSign The DocuSign Envelope Action element sends an Using the DocuSign Envelope Action to
Envelope email that contains the prefilled documents for Email Documents for Signature
Action signing or reviewing. It can be sent to one or more
recipients.
DocuSign The DocuSign Signature Action element displays a Using the DocuSign Signature Action to
Signature modal containing a DocuSign document. The Sign Documents From Within an
Action OmniScript user can sign the document directly from OmniScript
the modal and download a PDF of the signed
document.

company 53
Element Element Description Reference

Name
Email Action The Email Action uses the Salesforce Email API to OmniScript Email Action
either send an email template to the email address
of a User, Lead or Contact or send an email body
defined in the action configuration to any email
address.
Integration The Integration Procedure Action element allows Integration Procedures
Procedure multiple actions to be run as a headless service
Action (lacking a UI) through JavaScript or Apex Service.
Navigate Navigate to another page or component using the Navigate Action
Action Navigate Action.
PDF Action The PDF Action element inputs Data JSON to Add a PDF Action to the OmniScript
DataRaptor Transform. It returns a filled PDF based
on OmniScript elements.
Remote Action The Remote Action element calls an Apex class that OmniScript Remote Action
implements VlocityOpenInterface. Inputs Data JSON
of the OmniScript.
HTTP Action The HTTP Action calls an HTTP API that allows HTTP Action
Apex, Named Credentials, SOAP/XML, or Web.
Inputs Data JSON of the OmniScript.
Set Errors The Set Errors element handles failures from users Set Errors In an OmniScript
of the OmniScript.
Set Values Set Values handles values of elements on a hidden Set Values in an OmniScript
node, current, or future step.
Common Action Element Properties

Action elements can be either rendered as a button when placed in a Step or Block or run remotely if
placed between steps. In either case, you can specify a redirect page, where the user can proceed to the
next Step or Action, or if a button, back to the source Step.
Common Action Properties

Label The label on the button, or, if running remotely, the heading of the Action block. n/a
Redirect Page Name Custom redirect page name. Upon success, the script navigates to this page. Leave blank to n/a
bypass the redirect page.
Redirect Template URL HTML template of the redirect page. Vlocity provides templates for redirect pages, or you can n/a
create your own.
Validation Required Determines whether validation runs on the script or Step before the Action is invoked. Select n/a
Submit to validate the entire script or Step to validate only the Step that the button is on.
When set to Step, the Action will be clickable once all required fields within the Step contain
valid input. Select None to bypass validation.

company 54

Invoke Mode Configure the response behavior of the action. n/a
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.
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
User Message Properties

Actions that run remotely and between steps, or before the first Step is run, contain these User Message
properties.
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.

company 55
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.
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.
Send and Response Transformations

Send and Response Transformations are properties available on a variety of OmniScript remote actions.
They provide flexibility in trimming and reparenting the request and response JSON. For more information
on how to use Send and Response Transformations, see Manipulating JSON with the Send and Response
Transformations Property.
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.

company 56
Selecting an Invoke Mode

Enable actions to run asynchronously, block users from advancing to a future Step, and modify by selecting
an invoke mode.
Invoke Mode enables you to configure the response behavior of an action.
Available in:
• Remote Action
• Integration Procedure Action
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
• HTTP Action
See Also
• Add an Action Message

• Common OmniScript Element Properties Definitions
• Manipulate JSON with the Send/Response Transformations Properties
Add an Action Message

Display an action message beneath the loading spinner while the action is running.
1. In an Action, expand the User Messages property.

2. Check Enable Action Message.
3. In Action Message, enter a custom message, or leave the default message.
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:

company 57
Property Description Object or Example

Component
Window Send information from an element to a window Window object Message with Window Post
postMessage object in key-value pairs. Messages and Session
Storage Messages
Pub/Sub Communicate with OmniScript from a custom LWC Lightning Web Communicate with
by sending key-value pairs. Use the events passed Components OmniScript from a Lightning
in the key-value pairs to trigger custom behavior in Web Component
a component.
Session Storage Send information to a Session Storage object using Session Storage Message with Window Post
key-value pairs. A session storage object clears object Messages and Session
when a page session ends. Storage Messages
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

• Make Remote Calls from Lightning Web Components using the OmniScript Action Framework
Communicate with OmniScript from a Lightning Web Component

Send data from OmniScript Actions and Steps to other LWCs using the Pub/Sub property.
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.
Before You Begin

Review the Salesforce documentation on using PubSub. See Communicate Between Components.
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.

company 58
Action Example Step Example

Pass data from the Action's response in the value field using Pass data from an element within the Step using
merge syntax. For example, to pass the response node merge syntax. For example, to pass a Text element
"accountId", enter %accountId% in the Value field. named Text1, enter %Text1% in the Value field.
3. Activate the OmniScript.

4. In an LWC that receives data from the Action or Step, import the pubsub module. Using this example,
replace ns with the namespace of your Vlocity package. See Viewing the Namespace and Version of
the OmniStudio Vlocity Package.
import pubsub from 'ns/pubsub';

5. In the LWC, register the pubsub event. The even must register after the component renders.
Action pubsub Event Step pubsub Event

pubsub.register('omniscript_action', { pubsub.register('omniscript_step', {
data: this.handleOmniAction.bind(this), data: this.handleOmniStepLoadData.bind(this),
}); });
6. In the LWC, create a pubsub event handler.
Action Event Handler Example Step Event Handler Example

handleOmniAction(data) { handleOmniStepLoadData(data) {
// perform logic to handle the Action's // perform logic to handle the pubsub data from
response data the Step
} }
7. (Optional) If different Actions or Steps require different logic in the code, use a switch statement to
determine how to handle the event. For information on switch statements, see switch.

company 59

Access the Action's Element Name using data.name. Access the Step's Element Name using data.name.
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) {
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

company 60
Message with Window Post Messages and Session Storage Messages

Communicate between OmniScript, windows, and components with window post messages and session
storage messages.
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.
To add window post messages or session storage messages:
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.
To add messages to a Step:
1. In the Step's properties, click Edit Properties as JSON.

2. Paste in the following JSON before the closing curly bracket:
"wpm": false,
"ssm": false,
"message": {}

company 61
3. Enable WPM or SSM by setting the value equal to true.
"wpm": true
4. Add additional key/value pairs inside the message object.
"message": {"Account":%AccountId%, "Status": %AccountStatus%}
What's Next
Preview the OmniScript and test the messaging behavior by inspecting the browser.
See Also
• Common Action Element Properties

• Tracking Changes for Adobe DTM and Google Analytics
DataRaptor Extract Action

Invoke a DataRaptor Extract to retrieve data from one or more related Salesforce objects. You can also use
formulas and complex field mappings.
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
• Load Salesforce Data into OmniScript Using DataRaptor

• DataRaptor Extract Action Properties
DataRaptor Extract Action Properties

This page contains information on Integration Procedure Action Properties.
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.

company 62
Related Topics
• DataRaptor Extract Overview

• Load Salesforce Data into OmniScript Using DataRaptor
DataRaptor Post Action

Invoke a DataRaptor Load action to write data to one or more Salesforce objects.
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
• Create a DataRaptor Load

• DataRaptor Load Overview
• DataRaptor Post Action Properties
DataRaptor Post Action Properties

This page contains information on DataRaptor Post Action Properties.
DataRaptor Interface Name of the DataRaptor Load being called.
Related Topics
DataRaptor Transform Action

Invoke a DataRaptor Transform to restructure, rename, and convert data. Unlike DataRaptor Extracts and
Loads, Transforms do not read or write Salesforce data.
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

company 63
subsequent OmniScript step. See Manipulate JSON with the Send/Response Transformations
Properties.
Related Topics
• Populating a DocuSign Template Using DataRaptor Transform

• Create a DataRaptor Interface to Map OmniScript Data to a PDF
DataRaptor Transform Action Properties

This page contains information on DataRaptor Transform Action Properties.
DataRaptor Interface Name of the DataRaptor Transform being called.
Related Topics
• DataRaptor Transform Overview
DataRaptor Turbo Action

Invoke a DataRaptor Turbo Extract to retrieve data from a single Salesforce object. Unlike a standard
DataRaptor Extract, a DataRaptor Turbo Extract doesn't support formulas or complex field mappings.
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
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.

company 64
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.
DataRaptor Turbo Extract JSON Example Response JSON Path Example

{ Account|1
"Account": [
{
"RecordTypeId": "0125w000001NgyvAAC",
"Phone": "5105551223",
"Name": "Aileen Lee",
"Id": "0015w00002D8iCAAAZ"
}
]
}
5. (Optional) In the Response JSON Node field, enter VlocityNoRootNode. This ensures the object is
not nested. See Manipulate JSON with the Send/Response Transformations Properties.

company 65
6. Preview the OmniScript to test the DataRaptor Turbo Action.
See Also
• DataRaptor Turbo Extract Overview

• DataRaptor Extract Action

company 66
DataRaptor Turbo Action Properties

This page contains information on DataRaptor Turbo Action Properties.
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.
To delete records with the Delete Action:
1. Preview the OmniScript and identify the JSON path for the record. For example, this data JSON
contains a list of Accounts:
{ "Account": { "accId": ["001f400000EPQ8o", "001f400000BAkbn"] } }

2. In the Delete Action properties, click Add sObject to Delete.
3. In the Type column, select an Object.
4. In the Path to Id field, enter the JSON path for the record id using merge field syntax. Using the
Account example, the path to delete the array of Account ids is: %Account:accId%.
5. Preview the OmniScript and use a test record's id to test the functionality.
For Integration Procedure examples that include a Delete Action, see Process Arrays Using Loop Blocks
and Handle Errors Using Try-Catch Blocks.
Confirming Record Deletion

Enable users to confirm the deletion of a record using the Confirmation Modal.
To change the behavior of the confirmation modal, configure these properties:
• Confirm: Controls whether the modal displays.

• Confirmation Dialog Message: Message asking the user to confirm the deletion.
• Confirm Label: Button label for the confirm action.
• Cancel Label: Button label for the cancel action.
Displaying Messages from a Delete Action

Display messages when the operation succeeds or fails by configuring these fields in the Error Messages
section:

company 67
• 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.
Delete Action Properties

This page contains information on Delete Action Properties.
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
• Confirming Record Deletion

• Displaying Messages from a Delete Action
DocuSign Envelope Action Properties

This page contains information on DocuSign Envelope Action Properties.
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
• Integrating DocuSign with OmniScript

• Display in Moment.js Documentation

company 68
DocuSign Signature Action Properties

This page contains information on DocuSign Signature Action Properties.
DocuSign Templates Templates for the documents that you want signed.
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

• Display in Moment.js Documentation
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.

company 69
• 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.
Email Action Properties

This page contains information on Email Action Properties.
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.
Supports merge fields. Available if Use Template is not checked.

CC Email Address List Specifies the recipients in the CC field of the email. Can accept an array of up to 25 addresses.

BCC Email Address List Specifies the recipients in the BCC field of the email. Can accept an array of up to 25 addresses.

Email Subject Specifies the email subject line.

Email Body Specifies the body of the email.

Set HTML Email Body Processes HTML code in the email body.
Select Email Template Specifies the Salesforce email template. Enter the sObject Id, then select the template from the drop-
down list.
Available if Use Template is checked.

Email Target Object Id Specifies the Id of a Contact, User, or Lead with an email address.

What Id If you specify a Contact in the Email Target Object Id field, this property can 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 checked, saves the email as an activity record on the recipient’s page in Salesforce.

Org Wide Email Address Specifies the sender in the FROM field of the email. This is assumed to be an email that represents the
entire org. If not specified, the default sender is the user that invoked the Integration Procedure. See
Organization-Wide Email Addresses in the Salesforce help.
Supports merge fields.

File Attachments from Specifies the OmniScript JSON node that contains a single or list of Salesforce File sObject Ids.
OmniScript

company 70
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.
To make an external call with an HTTP Action:
Use the HTTP Action to:
• Send GET, POST, PUT, or DELETE requests to standard REST Endpoints.

• Call Apex REST.
• Access Salesforce Named Credential (OAuth) identity services.
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).

company 71
• SOAP/XML (Simple Object Access Protocol)

• Web (Unauthenticated or Credentials in Header)
• Remote Timeout: The timeout for the request, in milliseconds. Defaults to 30,000 (30 seconds. Maximum
12,0000 (120 seconds).
• Pre- and Post-Transform DataRaptor Interface: (Optional) DataRaptor Transform interface to run before
or after the REST Action.
HTTP Action Properties

This page contains information on HTTP Action Properties.
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
Integration Procedure Action

Invoke an Integration Procedure to retrieve Salesforce data and external data.
Before You Begin

Create an Integration Procedure to handle OmniScript data.
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

company 72
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 Manipulate JSON with the Send/Response Transformations Properties.
See Also
• Integration Procedure Action Properties

• OmniStudio Integration Procedures
• Future Methods in Apex Developer Guide
• Settings for Long-Running Integration Procedures
• Continuation in Long-Running Calls
Integration Procedure Action Properties

This page contains information on Integration Procedure Action Properties.
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.

company 73
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:
• Default — Blocks the UI with a loading spinner.

• Non-Blocking — Runs 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 — 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.
Show Toast On Displays a message when the subordinate Integration Procedure completes.
Completion
See Also

• Future Methods in Apex Developer Guide
• Settings for Long-Running Integration Procedures
• Continuation in Long-Running Calls
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.

company 74
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.
PageReference Type Description

App Launch a standard or custom app that is available from the app launcher. Connected apps are not
supported.
Community Named Page Direct users to a Named Page in a Community.
Component Navigate to Aura components and Lightning web components.
Current Page Trigger a page update on the current page once a user completes the OmniScript.
Knowledge Article Display knowledge articles in the OmniScript.
Login Open a Community login page.
Named Page Open a standard Named page.
Navigation Item A page displaying mapped content on a CustomTab.
Object Direct users to a standard, or custom, object page.
Record Open a page that interacts with a Salesforce record.
Record Relationship Open a record relationship page.
Restart OmniScript Return a user to the beginning of an OmniScript and clear the OmniScript data.
Vlocity OmniScript Launch a separate OmniScript.
Web Page Open an external URL.
See Also

• Configure OmniScript Cancel Options
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.

company 75
Before You Begin

1. Configure the Navigate Action's additional properties and view alternative page reference types. See Navigate Action.
2. Ensure the App you're using is available in the Salesforce App Launcher. For more information, see App Launcher.
1. Set the PageReference type property to App.

2. In the App Name field, enter the App's appId or appDeveloperName using the appropriate
namespace.
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.
{"type": "standard__navItemPage","attributes": {"apiName":

"oui_dailylwc__LWCDesigner"}}
4. Activate and preview the OmniScript to test the behavior of the navigation.
See Also

• Navigate Action
Navigate to a Community Login or Logout

Direct users from an OmniScript to a Community Login or Logout page for authentication.
Before You Begin

Configure the Navigate Action's additional properties and view alternative page reference types. For more information, see Navigate
Action.
1. Set the PageReference type property to Login.

2. Set the Login Action property to login to direct the user to a login page or logout to direct the user
to logout.
3. Preview the OmniScript by activating the OmniScript and placing it in a Community. For more
information, see Add an OmniScript to a Community or Lightning Page.
See Also

• Navigate Action

company 76
Navigate to a Component
Navigate to Aura components and Lightning web components from an OmniScript by using the Component
PageReference Type.
Before You Begin

Action.
1. Set the PageReference type property to Component.

2. Enter an Aura component name into the Component Name field using the format
NS__componentName, where NS is the namespace of your Vlocity package. The vlocityLWCWrapper
enables Lightning web components to be URL Addressable. For more information, see Launch
Lightning Web Component URLs with vlocityLWCWrapper. This field supports Merge fields.
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.

company 77
See Also

• Navigate Action
Navigate to the Current Page

Update and navigate to the current page from an OmniScript by using the Current Page PageRefrence
Type in a Navigate Action.
Before You Begin

Action.
1. Set the PageReference type property to Current Page.

2. Apply updates to the current page by passing parameters that use a URL query string format in the
Target Params property. Parameters must have a c__ prefix. This field supports Merge fields.
See Also

• Navigate Action
Navigate to a Knowledge Article

Display a Knowledge Article in an OmniScript by selecting the Navigate Action's Knowledge Article
PageReference Type.

company 78
Before You Begin

Action.
1. Set the PageReference type property to Knowledge Article.

2. Enter the Knowledge Article's urlName into the Article URL field. This field supports Merge fields.
3. Enter the articleType API name into the Article Type field. Find the articleType API Name by
removing __kav from the API Name of the Knowledge Object.
NOTE
Communities ignore articleType.
See Also

• Navigate Action
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.
Before You Begin

Action.
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.

company 79
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
See Also

• Navigate Action
Navigate to a Named Page or Community Named Page

Direct users to a standard or community page by using the Named Page or Community Named Page
PageReference Type.
Before You Begin

Configure the Navigate Action's additional properties and view alternative page reference types. See Navigate Action.
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

company 80
• Navigate Action
Navigate to a Navigation Item

Navigate from an OmniScript to a custom tab displaying mapped content by using the Navigate Action
Navigation Item PageReference Type.
Before You Begin

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

• Navigate Action
Navigate to an Object Page

Navigate from an OmniScript to an Object page by using the Navigate Action's Object PageReference
Type.
Before You Begin

Action.
1. Set the PageReference type property to Object.

2. 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.
3. Click the Action property and select an Action to invoke.
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

• Navigate Action

company 81
Navigate to a Record Page

Navigate from an OmniScript to a Record page by using Navigate Action's Record PageReference Type.
Before You Begin

Action.
1. Set the PageReference type property to Record.

2. Enter a recordId into the Record Id field. This field supports Merge fields.
3. Click the Action property and select an Action to invoke.
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

• Navigate Action
Navigate to a Record Relationship Page

Navigate from an OmniScript to pages interacting with a record relationship by using the Record
Relationship PageReference Type.
Before You Begin

Action.
1. Set the PageReference type property to Record Relationship.

2. Enter a recordId into the Record Id field. This field supports Merge fields.
3. (Optional) Enter the API name of the object defining the Relationship 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.
4. (Optional) Enter the API name of the Relationship into the Relationship API Name field.
See Also

• Navigate Action
Navigate to a Web Page

Navigate to a Web page from an OmniScript by using the Web Page PageReference Type.

company 82
Before You Begin

Action.
1. Set the PageReference type property to Web Page.

2. Enter the full URL for a web page into the Web URL field. For example, to navigate to google, enter
https://google.com.
See Also

• Navigate Action
Restart an OmniScript
Navigate a user to a new instance of the same OmniScript using the Navigate Action.
1. From OmniScript, add a Navigate Action to the canvas.

2. In your Navigate Action's properties, click Edit Properties As JSON.
3. Locate the node "targetType", and set "Restart OmniScript" as the value.
"targetType": "Restart OmniScript"

4. Save your settings and test the functionality.
See Also

• Navigate to the Current Page
Navigate Action Properties

This page contains information on Navigate Action Properties.
Button Variant If the Navigate Action renders in a Step, determines the style of the button:
• brand — Uses a brand-specific fill color to indicate a primary action.

• outline-brand — Uses a brand-specific outline color to indicate a primary action.
• neutral — Generic button.
• success — Uses a green fill to indicate success.
• destructive — Uses a red fill to indicate a destructive action to the user, like permanently erasing data.
• text-destructive — Uses red text to indicate a destructive action to the user, like permanently erasing data.
• inverse — Uses a white outline and text to be visible on a dark background.
• link — Highlighted and underlined to indicate navigation to a page.
Icon Name Name of the icon for the button.

company 83
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:
• Home — Displays sObject information.

• List — Lists sObject records.
• New — Opens the window for creating a new sObject.
Filter Name Text to filter the List of sObject records.
Record Action Page for the action to perform on the sObject record:
• Clone — Opens the window for cloning the record.

• Edit — Opens the window for editing the record.
• View — Displays sObject record information.
Relationship API Name of the relationship. For standard objects, this is usually an Id reference such as AccountId. For custom
Name objects, this is usually the name of the related object with the __c suffix changed to __r.
Replace If checked, the pageReference replaces the existing entry in the browser history, and disables the user from
navigating back to the OmniScript. In a console context, the target replaces the current tab instead of opening
a new tab.
Record ID Id of the sObject record.
Web URL URL of the external Web Page.
LWC OmniScript Name of the OmniScript using the syntax typeSubTypeLanguage.
OmniScript Layout Layout for OmniScript rendering, either Newport for non-LWC or Lightning for LWC.
OmniScript Prefill Parameters to prefill the OmniScript in URL query string format. Parameters must have a c__ prefix. This field
supports Merge fields. For example: c__firstName=%firstName%.

company 84
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.
Before You Begin

Create an Apex class in Salesforce to call from OmniScript.
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.
• Response JSON Node: VlocityNoRootNode
• Response JSON Path: The name of the OmniScript Element receiving the value.

company 85
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.
It implements the OmniCallout class and the checkWarrantyStatus method:

company 86
Since this is a sample OmniScript, the method contains a hard-coded response:

company 87
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:

company 88
Sample Class Structure

The following class structure can be used to call out to an external system:
global with sharing class CustomClassName implements NS.VlocityOpenInterface

{
global CustomClassName() {}
global Boolean invokeMethod(String methodName, Map<String,Object>

inputMap, Map<String,Object> outMap, Map<String,Object> options) {
Boolean result = true;
try{
if(methodName.equals('customMethodName')){
// your implementation, use outMap to send response back to

OmniScript
else if(methodName.equals('customMethodName2')){
// your implementation, use outMap to send response back to

OmniScript
} catch(Exception e){
result = false;
return result;
See Also

company 89
• HTTP Action for Integration Procedures
Remote Action Properties

This page contains information on Remote Action Properties.
Properties Description
Remote Class Vlocity Open Interface class.
Remote Method Vlocity Open Interface method.
Remote Options Additional class invocation options.
Invoke Mode Configures the response behavior of the action:
• Default — Blocks the UI with a loading spinner.

• Non-Blocking — Runs 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 — 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.
Send Only Extra Payload Enables the action to send Extra Payload's Key/Value pairs without including the OmniScript's
data JSON.
Show Toast On Completion Displays a message when the subordinate remote action completes.
Use Continuation Enables a subordinate Integration Procedure that calls long-running actions to use Apex
continuations.
Set Errors Properties

This page contains information on Set Errors Action Properties.
Element Name The OmniScript element for which an error is to be set.
Value The error message. Options:
• Merge fields from a previous step (%elementName%)

• Literal value
• Concatenated values
• Results of formulas and functions
• Expressions that combine the options: "Case Status: %caseStatus%"
Related Topics
• Set Errors In an OmniScript
Set Values Properties

This page contains information on Set Values Properties.

company 90
Element Name The JSON node for which a value is to be set.
Value The value to assign to the JSON node. Options:

• Literal value
Related Topics
OmniScript Display Elements

This page contains a table explaining the available OmniScript elements listed under the Display section.
Element Name Element Description Example

Line Break The Line Break element displays a line break. Use the Line Break Element to Add Line Breaks in an
OmniScript
Text Block The Text Block element displays a block of text to the Use the Rich Text Editor in the Vlocity OmniScript
user. Designer
OmniScript Function Elements

This page contains a table explaining the available OmniScript elements listed under the Function section.
Element Element Description Example Example

Name Image
Aggregate The Aggregate element Create a Formula Lightning Aggregate:
provides a variety of functions or Aggregate in
for aggregation. Unlike the an OmniScript
Formula component, the
Aggregate component
expects input in the form of
an array.
Newport Aggregate:

company 91
Formula The Formula element Create Formula Lightning Formula:

performs calculations that Fields in an
require complex operations. OmniScript
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.
OmniScript Group Elements

This page contains a table explaining the available OmniScript elements listed under the Groups section.
Element Element Description Example Example Image

Name

company 92
Block The Block element groups Blocks Lightning Block:

elements inside of a Step
component into a manageable
structure.
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 Radio Group:

company 93
Step The Step element divides the Steps Lightning Step:

OmniScript into different
sections.
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.
Newport Type Ahead:

company 94
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.
Before you begin

View the Action Block flow chart to understand how actions in the Action Block execute.
Action Block flow chart:
To configure an Action Block:
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.

company 95
3. Select an Invoke Mode to control how actions inside the Action Block run.
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.
• 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
• Common Action Element Properties

• OmniScript Action Elements
• Action Block Properties
Action Block Properties

This page contains information on Action Block properties.
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.

company 96
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
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.
To add and configure a Block:
1. Drag a Block element into the OmniScript canvas and name the element.
2. In Field Label, enter a label that displays to users.

company 97
3. (Optional) Check Collapse to render a collapsed Block in the OmniScript.
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.

company 98
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.

company 99
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
Configuring an Edit Block

Beginning with Vlocity Insurance and Health Winter '20 and Vlocity CME Winter '20 , LWC OmniScript
supports Edit Blocks.
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.
Displaying Elements in an Edit Block

Edit Block displays three elements in the Edit Block's default view and can display additional elements in
the edit view. It is possible to hide elements, hide elements from the edit view.
• 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.

company 100
Example Default View:
• 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:
1. Check the checkbox next to the element in the structure panel.

2. In the Element, click Edit as JSON, and set Hide equal to true. The element displays in the entry's
default view and is hidden when editing the entry.

company 101
Setting Display Modes and Templates

Enable LWC OmniScripts and Angular OmniScripts to display different Edit Block user interfaces by using
LWC Modes and Angular Templates.
LWC Modes
Select a Mode in the Edit Block's Edit Block Mode field to change the display and functionality of the Edit
Block.
Mode Configuration Notes Lightning Newport

Example Example
Inline n/a
Table n/a
Financial Statement (FS) • The total combined width of the elements

must be less than or equal to 12.
• Vlocity recommends displaying less than
twelve elements.
• Hidden elements do not affect the total
display width
Cards n/a
NOTE
Available beginning in
Vlocity Insurance and
Health Spring '20
LongCards In the Winter '20 release, the width of

LongCards must be set to 12.
Angular Templates
Add a template to the EditBlock's HTML Template Id field to modify the display and functionality of the Edit
Block.
Template Name Lightning Example Newport Example

Responsive table -
vlcEditBlock.html
Cards - vlcEditBlockCards.html
Financial Statement -
vlcEditBlockFS.html

company 102
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

company 103
• Formula
• Headline
• HTTP Action
• Image
• Line Break
• Lookup
• Matrix Action
• Multi-select
• Number
• Password
• Radio
• Radio Group
• Range
• Remote Action
• Select
• Signature
• Telephone
• Text
• Text Area
• Text 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

Adding, Editing, and Deleting Records with Edit Block Actions

Enable users to add, edit, and delete records by using Edit Block's default remote actions. Add custom
functionality by configuring additional actions.
Edit Block supports these Actions:
• HTTP Action

company 104

• Remote 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.
To allow a user to create new entries, edit entries, or delete entries:
1. Add a Remote Action to the Edit Block.

2. Configure the Edit Block using the Element naming convention, Class, and Method for each of these
table entries:
Element Name Class Method

(Edit Block Element Name)-New DefaultOmniScriptEditBlock new
(Edit Block Element Name)-Edit DefaultOmniScriptEditBlock edit
(Edit Block Element Name)-Delete DefaultOmniScriptEditBlock delete
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.
To add mapping entries to the Edit Block:
1. Click SOBJECT MAPPING to expand the section.

2. Click Select Object and select a Salesforce object.
3. Click +Add Mapping.
4. In the Edit Block Element field, enter the name of an element that is in the Edit Block.
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.

company 105
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.
Adding Custom Actions

Add custom actions to include additional functionality in your Edit Block.
To add a custom action:
1. Add an Action into the Edit Block.

2. Name the element. Actions in the Edit Block will appear in the dropdown beneath the default actions by
default.
3. (Optional)To have an Action replace the default New, Edit, or Delete Actions in the User Interface,
name the Action element, and append the action type.
Replace Action Example Element Name

New AddUserNew
Edit ChangeAddressEdit
Delete RemoveAccountDelete
4. Add a Label to the Action.
5. Configure the Action.
Adding Global Actions

Run Actions on the entire JSON for the Edit Block by adding global actions. Global actions display outside
of the Edit Block entries.
To add a Global Action:
1. Add an Action into the Edit Block.

2. Name the element and append Global onto the Element Name. For example, to make an action with
the element name DeleteUsers a global Action, the Element Name must be DeleteUsersGlobal.
3. Add a label to the Action.
4. Configure the Action.
See Also
• Configuring an Edit Block


company 106
Displaying Sprites in Edit Block

Display Sprites to indicate information about an Edit Block record entry using the Default Svg Sprite and
Default Svg Icon properties. For example, a User icon may display if the entry is a Contact record. Vlocity
supports the Lightning Design System icons found here . Dynamically display different sprites by mapping
the SVG Controlling Element's possible values to SLDS icons in the SVG Controlling Element Map.
Replacing the Default SVG Sprite and Icon

To replace the Default SVG Sprite and Icon:
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.
Displaying SVG Icons Dynamically

To dynamically display different SVG Icons:
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

Setting a Select Mode in Edit Block

Select modes enable users to change an Edit Block entry's boolean value in the data JSON by clicking on
Edit Block entries.

company 107
NOTE
Select Mode is only available for Cards, LongCards, and Table.
To set a select mode:
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


company 108
Working with Formulas in Edit Block

Perform equations and combine strings by using Formula Elements. Place formulas within an Edit Block to
access element values within a specific Edit Block entry. Place Formula outside of the Edit Block in the
same Step to access an element value for all of the Edit Block entries.
To access data within a specific Edit Block entry:
1. Add a Formula element to the Edit Block.

2. Using the merge field syntax, add the Edit Block's Element Name and the Element Name for the
element you want to access in the Formula. For example, %EditBlock:FirstName%. For more
information on merge fields, see Access OmniScript Data JSON with Merge Fields.
3. Add a |n after the Edit Block element name to set the formula to only access the merge field's value
for its instance. Using the |n syntax is necessary because the Edit Block stores entry values in an array
format. The resulting syntax is %EditBlock|n:FirstName%.
4. Concatenate values by combining them using the |n syntax. For example, %EditBlock|
n:FirstName% + " " + %EditBlock|n:LastName%.
To access each index of an Edit Block array in a formula:
1. Place a Formula outside of the Edit Block.

2. In the Formula editor, add the Element Name using the merge field syntax. For example, to return the
sum of all the entries for a Number element in an Edit Block, you would use the following syntax in the
formula editor: SUM(%EditBlock1:NetIncome%), where NetIncome is the name of a Number
element.
3. (Optional) When using the vlcEditBlockFS.html template, display the formula at the top of the Edit
Block by adding the Formula element's name to the Edit Block's Sum Element property.

company 109
See Also

Overriding an LWC Edit Block

Apply custom code to an Edit Block by extending and overriding the Edit Block's components.
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.
Property Description Compatible Edit Example

Modes
LWC Component Customize the Edit Block component by All Extending the Edit Block
Override extending the Edit Block component. LWC
Edit Block Label LWC Customize the Edit Block's label by overriding Cards, Long Cards Extending the Edit Block
Component Override the label component. Label LWC
Edit Block New LWC Customize the Edit Block Card users click to Cards Extending the Edit Block
Component Override create new entries by overriding the New LWC New LWC
component.
See Also

Extending the Edit Block LWC

Customize an LWC OmniScript's Edit Block by extending the Edit Block LWC.
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.
Before you begin

Ensure you understand the requirements for extending an OmniScript element's Lightning web component.
For more information, see Extend an OmniScript Element's Lightning Web Component.
To extend and customize the Edit Block LWC:
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.

company 110
Original Edit Block Card Custom Edit Block Card Example
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:
import omniscriptEditBlock from "VLOCITYNAMESPACE/omniscriptEditBlock";

import template from "./editblockCardCustomize.html"
export default class editblockCardCustomize extends
omniscriptEditBlock{
// your properties and methods here
render()
{
if (this.jsonDef) {
this._hasChildren = this.jsonDef.children.length > 0;
this._isFirstIndex = this.jsonDef.index === 0;
if (this._isCards && this._isFirstIndex) {

// hides the first short card with no children
if (!this._hasChildren) {
this.classList.add(this._theme + '-hide');
} else {
this.classList.remove(this._theme + '-hide');
}
}
}
return template;
}
}
3. Add code to the custom LWC.
4. Deploy the custom LWC to Salesforce. See Deploy Lightning Web Components.

company 111
5. Go to the OmniScript that contains the Edit Block LWC.

6. In the Edit Block's LWC Component Override field, enter the name of the custom LWC.
7. Activate the OmniScript, and preview your changes.
See Also

Extending the Edit Block Label LWC

Customize an LWC Edit Block's Label for the Cards and Long Cards edit modes by extending the Edit
Block Label LWC.
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.
Before you begin

To extend and customize the Edit Block Label LWC:
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.
Original Edit Block Label Custom Edit Block Label
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
Example:
import omniscriptEditBlockLabel from "NS/omniscriptEditBlockLabel";

import template from "./editblockLabelCustomize.html"
export default class editblockLabelCustomize extends
omniscriptEditBlockLabel{
render()
{
return template;
}
}

company 112

6. In the Edit Block's properties, select Edit Block Mode, and click Cards or LongCards.
7. In the Edit Block's Edit Block Label LWC Component Override field, enter the name of the custom
LWC.
See Also

Extending the Edit Block New LWC

Customize an LWC Edit Block's new entry card by extending the Edit Block New LWC.
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.
Before you begin

To extend and customize the Edit Block New LWC:
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

company 113
Example:
import omniscriptEditBlockNew from "NS/omniscriptEditBlockNew";

import template from "./editblockNewCustomize.html"
export default class editblockNewCustomize extends
omniscriptEditBlockNew{
render()
{
return template;
}
}
6. In the Edit Block's properties, click Edit Block Mode and select Cards.
7. In the Edit Block's Edit Block New LWC Component Override field, enter the name of the custom
LWC.
See Also

Edit Block Properties

This section contains information on the Edit Block properties. For information on configuring these
properties, see Configuring an Edit Block.
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.

company 114
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

Setting up a questionnaire with Radio Group

OmniScript's Radio Group enables you to create and display questions in a questionnaire format.
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.
To set up a questionnaire with Radio Group:
1. Drag a Radio Group into an existing Step in the structure panel.

2. In the Radio Group's Properties, under Options, add Values and Labels. These represent the
user's selectable options.

company 115
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.

company 116
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:

company 117
Here is the same Step rendered on the form:
The Instruction field on the Step element configuration appears in Horizontal mode and is HTML-rich:

company 118
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:

company 119
Type Ahead Block

Display a list of results when a user begins typing in an input field by using the Type Ahead Block. When a
user selects a record, the Type Ahead Block can retrieve additional information related to the record. For
example, a Type Ahead Block can be used with a DataRaptor to list Accounts in the results.
In the OmniScript Designer, the Type Ahead Block is located under the Groups section of Available
Components.
See Also
• Add and Configure a Type Ahead Block

• 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 Properties
Add and Configure a Type Ahead Block

Configure how users can create and edit records in Edit Block.
1. Add the Type Ahead Block element to the OmniScript canvas.

company 120
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.
Supported Data Sources Description Type Ahead Example

Data JSON Accesses an array of data present in the Using Type Ahead Block With Data JSON
OmniScript's data JSON.
DataRaptor Extract Action Retrieves internal or external Salesforce data. Use Type Ahead Block with DataRaptor
Google Maps Auto Calls a Google Maps API to retrieve google Using Google Maps Autocomplete in
Complete maps data. OmniScripts
HTTP Action Retrieves external data. Make an HTTP Call from a Type Ahead
Block
Remote Action Retrieves data from an Apex class. n/a
3. Add Input elements into the Type Ahead Block to map response data.
To hide an element, such as an Id, from the user, prefill it with data from the TypeAhead using these
steps:
a. From the element properties panel, click Edit as JSON. The JSON definition of the element is
displayed.
b. Set the hide property's value to true.
c. Check the box labeled Available for Prefill When Hidden.
4. Configure additional properties in the Edit Block to set a user's data access. See Type Ahead Block
Properties.
5. Add custom styling and behavior by overriding LWC Type Ahead Block components. The LWC
Component Override field only overrides the Type Ahead Component.
Type Ahead Block LWCs Description

omniscriptTypeahead Overrides the Type Ahead component that lists the data results.
omniscriptTypeaheadBlock Overrides the Type Ahead Block component that embeds the Type Ahead component.
progressBar LWC Type Ahead Blocks display a progress-bar when retrieving data results. For information on
customizing the progress-bar, see Base Vlocity LWC ReadMe Reference.
See Also
• Using Google Maps Autocomplete in OmniScripts
Make an HTTP Call from a Type Ahead Block

Retrieve data from a URL in your Type Ahead Block using an HTTP Action.

company 121
1. Add a Type Ahead Block to your OmniScript.

2. Drag the HTTP action into the Type Ahead Block. See OmniScript Script Structure Definitions for more
information.
3. Configure your HTTP Action by entering your HTTP Path and your HTTP Method.
4. Add fields to your Type Ahead Block for the items that are being returned by the HTTP action.
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

Using Type Ahead Block With Data JSON

The Type Ahead Block can use a Data JSON as its source instead of an API, HTTP, or Remote action.
Using a Data JSON enables the response from the Type Ahead Block to be made client-side instead of
needing to make server calls.
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:
1. Check the Use Data JSON checkbox

2. In the Data JSON Path, enter the name of a root level JSON node returned by the response of the
Action.
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


company 122

Using Google Maps Autocomplete in OmniScripts

Retrieve Google Maps data and display a location in the Type Ahead Block using the Google Maps API.
Before You Begin

The Type Ahead Block's Google Maps functionality requires you to use a Google Maps API Key. See Google.

2. In Type Ahead Block's Field Label, enter the text to display in the google maps search field.
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.

company 123
These are the available response nodes:

• Responses return unique sets of data depending on the configuration.
In addition to the default response nodes, this table displays response nodes that may also be
available in the Google response. For detailed information on each response node, see Google
Geocoding API (Google documentation).
Response Node Description

street_address A street address.
route A named route, e.g., I-5.
intersection A major intersection.
political A political entity.
country A national political entity.
geometry An object containing longitude and latitude.
administrative_area_level_1 A first-order civil entity below the country level, e.g., states.
administrative_area_level_2 A second-order civil entity, e.g., counties.
administrative_area_level_3 A third-order civil entity.
administrative_area_level_4 A fourth-order civil entity.
administrative_area_level_5 A fifth-order civil entity.
colloquial_area A common alternative name for the entity.
locality An incorporated city.
sublocality A first-order civil entity below locality. The sublocality may contain additional civil entities in
nodes from sublocality_level_1 to sublocality_level_5.
neighborhood A neighborhood.
premise A location, e.g., a building.
subpremise A first-order entity below a location, e.g., a building.
plus_code An encoded location reference taken from the latitude and longitude.
postal_code A postal code.
natural_feature An important natural feature.
airport An airport.
park A park name.
point_of_interest A point of interest, usually an important local entity, e.g., the Golden Gate Bridge.
types An array containing the response's type. For example, San Francisco is a type of locality.
9. Add an element to the Type Ahead Block to map data from a Google response node. Elements in the
Type Ahead Block appear as a selectable Child Element in the Google Transformation section.

company 124
10. In the Google Transformations section, click Add New Mapping.

11. Select a Child Element and map it to a Google Response Node.
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:
Response Node Data Type Notation Example

geometry Object geometry:location:lat
types Array types|1
12. Save the OmniScript and run it in preview to view your mappings.
See Also

Use Type Ahead Block with DataRaptor

Retrieve data in your Type Ahead Block using DataRaptor

2. Drag a DataRaptor Extract Action component into the structure of the Type Ahead Block. See
OmniScript Script Structure Definitions for more information.
3. To configure your DataRaptor Extract Action, select a DataRaptor Interface and set your input
parameters. To pass the user's input to the DataRaptor, set one input parameter to the Element Name
of the Type Ahead Block.
4. Add fields to your Type Ahead Block.
5. To populate the fields, set the Element names to match the extracted data being returned by the
DataRaptor Extract Action. For more information on populating elements, see Prefill OmniScript
Elements using DataRaptor.
See Also


company 125
Type Ahead Block Properties

This page contains information on Type Ahead Block properties.
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

OmniScript Input Elements

This page contains a table explaining the available OmniScript elements listed under the Inputs section.
Element Element Description Example Image

Name
Checkbox Checkbox is a boolean input control. It returns true or Lightning Checkbox:
false to the Data JSON.
Newport Checkbox:

company 126
Currency The Currency element records a currency amount on a Lightning Currency:

single line. To configure the currency symbol displayed in
the OmniScript, you have the following options:
• In single currency Salesforce orgs, the Currency Code

is set to the org currency by default. No configuration
is necessary.
• In multi-currency Salesforce orgs, the Currency Code
changes to a current user's currency code by default.
No configuration is necessary. For information on
configuring multiple currencies, see Manage Multiple
Currencies.
• Override the currency code with a default value. In the
Script Configuration, set the Currency Code field to a
supported currency code.
• In the URL that launches the script, set the
OmniScriptCurrencyCode parameter. For example:
&OmniScriptCurrencyCode=JPY
• (Exclusive to LWC OmniScripts) Display the Currency
Code by checking the Display Currency Code
checkbox on the Currency element.
• In a VisualForce page that displays an OmniScript, by
setting the strOmniScriptCurrencyCode to a currency
code.
Newport Currency:
Custom Exclusive to LWC OmniScripts, add a custom LWC to an n/a

LWC OmniScript using the Custom LWC element. See Custom
LWC Element.
Date The Date element is used for input fields that should Lightning Date:
contain a date. The Date Type can be set to either String
or Date for a Date element. Setting the Date Type to
String results in the use of the Absolute Date. The model
date format, can be set in the element's configuration.
The default is yyyy-MM-dd.
Newport Date:

company 127
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:

company 128
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:

company 129
Image The Image element defines an image in Omniscript. Lightning Image:
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:

company 130
Multi-select When a value is selected, the language-independent Lightning Multi-select:

"Value" in the Data JSON is populated.
Newport Multi-select:
Number A numeric input field. Lightning Number:
Newport Number:

company 131
Password The Password element is a password field. Lightning Password:
Newport Password:

company 132
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:
Newport Radio Display Mode Options:
Horizontal:

company 133
Image:
Segment:
Vertical:

company 134
Range The Range element is used for input fields that should Lightning Range:
contain a value within a range.
Newport Range:

company 135
Select Displays a dropdown menu of values. When a value is Lightning Select:

selected, the language-independent "value" is populated
in the Data JSON.
Lightning Select Dropdown:
Newport Select:
Newport Select Dropdown:

company 136
Signature The Signature element collects a signature during an Lightning Signature:

OmniScript. This field can be made required.
Newport Signature:
Telephone The Telephone element is used for input fields that Lightning Telephone:
should contain a telephone number.
Newport Telephone:

company 137
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:

company 138
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:

company 139
OmniScripts Checkbox Element

Enable users to select a checkbox by adding the Checkbox element to your OmniScript. For example, map
the user's yes/no answer to a true/false field in a record.
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
• OmniScript Input Elements

• OmniScript Element Reference
OmniScripts Currency Element

Enable users to enter a currency amount by adding the Currency element to your OmniScript. Update
default format options such as the number of decimal places to display, minimum and maximum currency
value, and more.
1. Drag a Currency element from the Build panel onto the canvas.
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.
See Also
• OmniScripts Number Element


company 140
Custom Lightning Web Component Properties

Custom Lightning Web Component element properties are configurable from the Properties panel when
you select the element. With the Custom Lightning Web Component element, embed a custom Lightning
web component into your OmniScript.
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
OmniScripts Date Element

Enable users to select a date from a date picker by adding a Date element to your OmniScript. Set the
minimum and maximum dates, and the date format.
1. Drag a Date element from the Build panel onto the canvas.
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 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.

company 141
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.
See Also
• OmniScripts Date/Time Element

OmniScripts Date/Time Element

Enable users to select a date from a date picker and a time from a list by adding the Date/Time element to
your OmniScript. Set the minimum and maximum dates, and the date and time formats.
1. Drag a Text element from the Build panel onto the canvas.
4. In Minimum Date, enter the earliest date the user can select from the date picker, such as
01-01-1950.
NOTE
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 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.

company 142
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.
See Also
• OmniScripts Date Element

OmniScripts Disclosure Element

Enable users to agree to a disclosure statement by adding a Disclosure element to your OmniScript. Enter
the copy in a rich text editor.
1. Drag a Disclosure element from the Build panel onto the canvas.
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.
See Also

OmniScripts Email Element

Enable users to enter an email address by adding the Email element to your OmniScript. Update the default
allowable format with Validation Options.
1. Drag an Email element from the Build panel onto the canvas.

company 143
4. (Optional) In the Validation Options section, update data validation options:

• In Pattern, enter a pattern to override the default allowable email format. Use simple pattern
matching. Regular expressions (regex) accepted. See Regular Expressions.
• In Pattern Error Text, enter the message displayed if the input does not match the expression in
Pattern.
See Also

OmniScripts Multi-Select Element

Enable users to select from multiple items by adding the Multi-select element to your OmniScript. Display
options vertically, horizontally, or as an image.
1. Drag a Multi-select element from the Build panel onto the canvas.
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.

company 144
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.
See Also
• OmniScripts Select Element

OmniScripts Number Element

Enable users to enter a number by adding the Number element to your OmniScript. Limit what the user can
enter by setting a mask.
1. Drag a Number element from the Build panel onto the canvas.
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
• OmniScripts Currency Element


company 145
OmniScripts Password Element

Enable users to enter a password by adding the Password element to your OmniScript. Set the minimum
and maximum lengths of the password.
1. Drag a Password element from the Build panel onto the canvas.
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.
See Also
OmniScripts Radio Element

Enable users to select one from multiple items by adding the Radio element to your OmniScript. Display
options vertically, horizontally, as an image, or styled based on the Newport Design System.
1. Drag a Radio element from the Build panel onto the canvas.
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.
• Manual: (Default) Manually enter value/label pairs. Available when Display Mode is not Image.

company 146
• 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:
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.
See Also
• OmniScripts Select Element

• Controlling Field Property
OmniScripts Range Element

Enables users to select a number from a specified range by adding the Range element to your OmniScript.
Specify the increment values and use both dynamic and static values to define the minimum and maximum
values for the range.
1. Drag a Range element from the Build panel onto the canvas.
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.

company 147
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.
See Also

OmniScripts Select Element

Enable users to select from a dropdown by adding a Select element to your OmniScript. Manually enter
options or dynamically pull options from an Apex class and method, or for a Salesforce object.
1. Drag a Select element from the Build panel onto the canvas.
• Manual: (Default) Manually enter value/label pairs.
5. If you select Manual as an Option Source, for each option follow these steps:
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.

company 148

See Also
• OmniScripts Multi-Select Element

• Controlling Field Property
• OmniScripts Radio Element
OmniScripts Telephone Element

Enable users to enter a telephone number by adding a Telephone element to your OmniScript. Limit the
length and format of the number the user can enter.
1. Drag a Telephone element from the Build panel onto the canvas.
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.
See Also

OmniScripts Text Area Element

Enable users to enter multiple lines of text by adding a Text Area element to your OmniScript. Limit the
number of characters the user can enter.
1. Drag a Text Area element from the Build panel onto the canvas.
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.
See Also
• OmniScripts Text Element


company 149
OmniScripts Text Element

Enable users to enter a line of text by adding the Text element to your OmniScript. Limit the length of the
text using minimum and maximum values and set allowable information using the mask property.
1. Drag a Text element from the Build panel onto the canvas.
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.
See Also
• OmniScripts Text Area Element

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.
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
• OmniScripts Text Element

OmniScripts Time Element

Enable users to select from a list of times by adding the Time element to your OmniScript. Format the
display and set the time intervals.
1. Drag a Time element from the Build panel onto the canvas.

company 150

4. In Minimum Time, enter the earliest time the user can select, such as 12:00 am.
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.
See Also
• OmniScripts Date/Time Element

• OmniScripts Date Element

company 151
OmniScripts URL Element

Enable users to enter a website address by adding the URL element to your OmniScript. For example, a
user can enter salesforce.com, or www.salesforce.com, and so on.
1. Drag a URL element from the Build panel onto the canvas.
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.
See Also

Create a Custom Lightning Web Component for OmniScript

Add custom HTML, JavaScript, and CSS to an OmniScript by creating a custom Lightning web component.
For information on using the Lightning Web Component framework, see Set Up Lightning Web
Components.
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.

company 152
• 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.
Custom OmniScript Lightning Web Components

To create a custom Lightning web component, review these component types:
Component Type Description Reference

OmniScript Element Customize an OmniScript element by extending the Extend an OmniScript Element's
Lightning web component element's Lightning web component. LWC-compatible Lightning Web Component
elements display a Lightning icon in the Available
Components panel of an OmniScript.
OmniScriptBaseMixin Enable a custom component to interact with an OmniScript Extend the OmniScriptBaseMixin
component by extending the OmniScriptBaseMixin component. Component
Standalone component A custom standalone component. The component cannot Create a Standalone Custom
extend the OmniScriptBaseMixin component or an Lightning Web Component
OmniScript element Lightning web component.
For information on adding a custom Lightning web component to an OmniScript, see Add Custom Lightning
Web Components to an OmniScript.
Custom LWC Element

Add a custom Lightning web component that does not extend an OmniScript element component to an
OmniScript using the Custom LWC element. To extend an OmniScript element's component, see Extend an
OmniScript Element's Lightning Web Component.
NOTE
Use Custom LWC Elements in a Step and a non-repeatable Block element that is not
nested.

company 153
Before You Begin

Create a custom LWC. The Custom LWC element supports these two types of custom Lightning web components:
• 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.
1. In an OmniScript, add the Custom LWC element.

2. In Name and Field Label, enter a name and display name for the Custom LWC element.
3. In the Lightning Web Component Name field, enter the name of your custom Lightning web
component.
4. (Optional) Check Standalone LWC if your custom component does not extend the
OmniScriptBaseMixin component.
5. (Optional) Pass property values into the OmniScript by entering values in these property fields:
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
Extend an OmniScript Element's Lightning Web Component

Add custom behavior and styling to an OmniScript Element while maintaining its core functionality by
extending an OmniScript element's 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.

company 154
To extend an OmniScript element's Lightning web component:
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
• 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.
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
import OmniScriptText from 'NS/omniscriptText';

import tmpl from './omniscriptTextCustom.html';

company 155
export default class OmniscriptTextCustom extends OmniscriptText {

handleBlur(evt) {
this.applyCallResp(evt.target.value);
}
render() {
return tmpl;
}
}
Extend the OmniScriptBaseMixin Component

Enable a custom Lightning web component to interact with an OmniScript by extending the
OmniScriptBaseMixin component. The OmniScriptBaseMixin includes methods to update an OmniScript's
data JSON, pass parameters, and more.
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.
Salesforce Modules.
• To make the custom Lightning web component compatible with Vlocity Lightning web components, you
• 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
Package.
Components.
OmniScriptBaseMixin ReadMe
View all of the component's properties, attributes, and methods in the ReadMe. See OmniScript ReadMe
Reference.

company 156
Extending the Component

In this code example, a custom Lightning web component is extending the OmniScriptBaseMixin
component to wrap a Salesforce Lightning Element. 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.
import tmpl from './customLightningElement.html';

import { LightningElement } from 'lwc';
import { OmniscriptBaseMixin } from 'NS/omniscriptBaseMixin';
export default class customLightningElementWithMixin extends

OmniscriptBaseMixin(LightningElement) {
handleBlur(evt) {
this.omniUpdateDataJson(evt.target.value);
}
render() {
return tmpl;
}
}
Validating the Component

To add validation to a custom component, redefine the checkValidity() function in your component.
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.
import { api } from 'lwc';

import { OmniscriptBaseMixin } from 'NS/omniscriptBaseMixin';
export default class MyCustomLwc extends OmniscriptBaseMixin(LightningElement)
{
sum = 0;
// defining custom validation conditions

@api checkValidity() {
return this.sum < 100;
}
}
Navigating to a Step
Enable users to navigate to different steps in the OmniScript using these three mixins:
• omniNextStep(): Advances users to the next Step in the OmniScript.

JS Example

company 157
nextButton(evt) {
if (evt) {
this.omniNextStep();
}
}
HTML Example
<button onclick={nextButton}>Custom Next Button </button>

• omniPrevStep(): Takes users to the previous step in the OmniScript.
JS Example
prevButton(evt) {
if (evt) {
this.omniPrevStep();
}
}
HTML Example
<button onclick={prevButton}>Custom Prev Button </button>

• omniNavigateTo(step): Takes users to a specific Step in the OmniScript by passing an argument.
The argument passed into the function can be a number that refers to the Step's index in the OmniScript
or a Step's Element name passed as a hardcoded string. The index for the current step is accessible
using the property this.omniScriptHeaderDef.asIndex.
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
<button onclick={goToStep}>Custom Step Button </button>
Saving Data inside of a Custom Component

When the custom component does not exist in the DOM, store the data in a state. To store data in a state,
use the omniSaveState() function. The omniSaveState function accepts three arguments: a data object,
a key, and a boolean.

company 158
Method: omniSaveState(input,key,usePubSub=false):
Arguments:
• input: The data to be saved.
let mySaveState = {"my":"data"};

this.omniSaveState(mySaveState);
• (optional) key: A string value that the obj parameter maps to as a key-value pair. If a key is not sent as a
parameter, the key defaults to the name of the component.
let mySaveState = {"my":"data"};

let key = 'customLwcKey';
this.omniSaveState(mySaveState, key);
• (optional) usePubSub: Set the boolean to true to store data for use in a pubsub pattern. For more
information on pubsub patterns, see pubsub events. When left blank or set to false, the data is usable by
events. For more information on events, see LWC Events. When omniSaveState is in a
disconnectedCallback, usePubSub must be set to true to pass the event in the pubsub instead of
event bubbling.
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.
Example of an omniSaveState being called in a disconnectedCallback:
disconnectedCallback() {
let mySaveState = {"my":"data", "here" : 8};
let usePubSub = true;
this.omniSaveState(mySaveState, key, usePubSub);
}
Retrieving Custom Component Data from an OmniScript

Use the omniGetSaveState() function to retrieve custom component data from an OmniScript.
omniGetSaveState(key): The omniGetSaveState accepts a key as an optional argument. If a key is not

sent, the key defaults to the name of the custom component. The key stores the data from the
omniSaveState() function.
Example with a key argument:

const state = this.omniGetSaveState(key);
Example with no key:

company 159
// assumes the data is inside of the same custom component

const state = this.omniGetSaveState()
Clearing a Saved State from a Previous Step

When a Custom LWC's saved state relies on data from a previous step, you can conditionally clear the
saved state of the Custom LWC whenever a user navigates to a previous step. After configuration, the Step
element passes a boolean flag to the custom LWC. The code in your Custom LWC must use the boolean to
determine whether to instantiate a new saved state or continue using the existing saved state.
To configure the clear saved state functionality:
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.
const state = this.omniGetSaveState()

6. In your Custom LWC's code, set a variable equal to
this.omniGetSaveState(this.omniJsonDef.name + '-$Vlocity.cleared'. The function
evaluates whether the previous Step containing the omniClearSaveState property rendered and
returns a boolean.
let stateCleared = this.omniGetSaveState(this.omniJsonDef.name + '-

$Vlocity.cleared');
7. Modify your code by using the boolean value to determine whether to keep the current saved state or
instantiate a new saved state.
Accessing the Layout of the OmniScript Base Mixin

Call the Layout for your Custom LWC by passing the data-omni-layout parameter to the
getAttribute method.
this.getAttribute('data-omni-layout')
Making Remote Calls

Enable users to make remote calls from a Custom LWC by using the omniRemoteCall() method.
Method: omniRemoteCall(params, boolean)
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.

company 160
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.
Use Case Examples:
• Example remote call invoking an Apex class.
const params = {
input: this.omniJsonDataS,
options: '{}',
};
this.omniRemoteCall(params, true).then(response => {

window.console.log(response, 'response');

company 161
}).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: '{}',
};

}).catch(error => {
});
• Example chainable Integration Procedure call passing the property chainable: true. Use chainable
when an Integration Procedure exceeds the Salesforce CPU Governor limit.
const options = {
chainable: true,
};
const params = {
sMethodName: 'test_RemoteAction', this will need to match the VIP ->
type_subtype
options: JSON.stringify(options),
};

}).catch(error => {
});
• Example queueable remote call passing the property useQueueableApexRemoting: true . For more
information on how queueable works, see Queueable Apex.
const options = {
vlcClass: 'SomeApexClass',
vlcMethod: 'someApexMethod',
useQueueableApexRemoting: true,

company 162
};
const params = {
sClassName: `$
{this._ns}VFActionFunctionController.VFActionFunctionControllerOpen`,
sMethodName: 'runActionFunction',
};

}).catch(error => {
});
• Example future remote call passing the property useFuture: true. For more information on how
Future Methods work, see Future Methods.
const options = {
useFuture: true,
};
const params = {
};

}).catch(error => {
});
• Example continuation remote call passing the parameter useContinuation: true. For more
information on how continuation works, see Continuation Class.
const options = {
vlcClass: 'SomeApexClass',
vlcMethod: 'someApexMethod',
useContinuation: true,
};
const params = {

company 163
};

}).catch(error => {
});
Update the Data JSON

Update the Custom LWC Element's Data
Apply the response of a Custom LWC callout to the Custom LWC element by using the
omniUpdateDataJson method.
Method: omniUpdateDataJson(input, aggregateOverride = false)
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.
// 1. first call to omniUpdateDataJson

// input for omniUpdateDataJson when aggregateOverride = false
{
"prop1" : "data1"
}
// 2. output of data JSON after the first call

//
{
"Step1" : {

company 164
"CustomLWC1" : {
"prop1": "data1"
}
}
// 3. second call to omniUpdateDataJson

// input for omniUpdateDataJson when aggregateOverride = false
{
"prop2" : "data2"
}
// 4. output of data JSON after the second call

// notice that the value of CustomLWC1 contains both prop1 and prop2
// because the data is merged instead of replaced when aggregateOverride is
set to false
{
"Step1" : {
"CustomLWC1" : {
"prop1": "data1",
"prop2": "data2"
}
}
Map Responses to the OmniScript's Data JSON

Apply responses from custom actions using the omniApplyCallResp() method.
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.
Method: omniApplyCallResp(response, usePubsub = false)
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.

company 165
This example demonstrates how the omniApplyCallResp() method updates Data JSON.
1. View the current data JSON before running omniApplyCallResp().
{
"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"
}
}
Create and Map Data Inside the Custom LWC Element

Construct additional data JSON nodes in the Custom LWC element and pass values down from the
element into the new JSON nodes using the omniaggregate event.For more information on events, see
Create and Dispatch Events (Salesforce documentation).
Event: omniaggregate

company 166
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 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 data = {
};
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 data = {
};
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.

company 167
• detail: Data passed in the event.

Example:
omniAggregate() {
const data = {
};
const detail = {
data: data,
};
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.
Code Example Data JSON Result Example

// code to call "CustomLWC12": {
omniAggregate() { "elementName1": {
const eventName = 'omniaggregate' "prop": "prop1"
const data = { },
anyKeyName : 'myElementData' "elementName2": {
}; "anyKeyName": "myElementData"
const detail = { }
data: data, }
};
bubbles: true,
cancelable: true,
composed: true,
detail: detail,
});
this.dispatchEvent(myEvent);
}
What's Next
Add a Custom Lightning Web Component to a Custom LWC Element
See Also
• Create a Standalone Custom Lightning Web Component

company 168
Create a Standalone Custom Lightning Web Component

Enable custom Lightning web components to act independently from an OmniScript by adding it to the
OmniScript as a standalone component. For information on the different ways to create a custom Lightning
web component for OmniScript, see Create a Custom Lightning Web Component for OmniScript.
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.
Salesforce Modules.
• To make the custom Lightning web component compatible with Vlocity Lightning web components, you
• 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
Package.
<runtimeNamespace>NS</runtimeNamespace>
Components.
Create and Map Data Inside the Custom LWC Element

Construct additional data JSON nodes in the Custom LWC element and pass values down from the
element into the new JSON nodes using the omniaggregate event.For more information on events, see
Create and Dispatch Events (Salesforce documentation).
Event: omniaggregate
1. Create a custom aggregate function and set the omniaggregate event to a variable.
Example:
customAggregate() {
}
2. Create a variable to store the LWC element's input data.
Example:
customAggregate() {

company 169
const data = {
};
}
3. Construct an object by mapping the data to the key data, and an element name to the key elementId.
customAggregate() {
const data = {
};
const detail = {
data: data,
};
}
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 data = {
};
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 data = {
};
const detail = {
data: data,

company 170
};
bubbles: true,
cancelable: true,
composed: true,
detail: detail,
});
}
6. Call this.dispatchEvent() and pass in the event object as a parameter.
Code Example Data JSON Result Example

// code to call "CustomLWC12": {
omniAggregate() { "elementName1": {
const eventName = 'omniaggregate' "prop": "prop1"
const data = { },
anyKeyName : 'myElementData' "elementName2": {
}; "anyKeyName": "myElementData"
const detail = { }
data: data, }
};
bubbles: true,
cancelable: true,
composed: true,
detail: detail,
});
this.dispatchEvent(myEvent);
}
What's Next
See Also
• Communicate with OmniScript from a Lightning Web Component
• Extend the OmniScriptBaseMixin Component
Communicate with OmniScript from a Lightning Web Component

Send data from OmniScript Actions and Steps to other LWCs using the Pub/Sub property.
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.
Before You Begin

Review the Salesforce documentation on using PubSub. See Communicate Between Components.
1. In an OmniScript Action or Step, select the Messaging Framework and check Pub/Sub.

company 171
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.

Pass data from the Action's response in the value field using Pass data from an element within the Step using
merge syntax. For example, to pass the response node merge syntax. For example, to pass a Text element
"accountId", enter %accountId% in the Value field. named Text1, enter %Text1% in the Value field.
3. Activate the OmniScript.

4. In an LWC that receives data from the Action or Step, import the pubsub module. Using this example,
replace ns with the namespace of your Vlocity package. See Viewing the Namespace and Version of
import pubsub from 'ns/pubsub';

5. In the LWC, register the pubsub event. The even must register after the component renders.
Action pubsub Event Step pubsub Event

pubsub.register('omniscript_action', { pubsub.register('omniscript_step', {
data: this.handleOmniAction.bind(this), data: this.handleOmniStepLoadData.bind(this),
}); });
6. In the LWC, create a pubsub event handler.
Action Event Handler Example Step Event Handler Example

// perform logic to handle the Action's // perform logic to handle the pubsub data from
response data the Step
} }
7. (Optional) If different Actions or Steps require different logic in the code, use a switch statement to
determine how to handle the event. For information on switch statements, see switch.

company 172

Access the Action's Element Name using data.name. Access the Step's Element Name using data.name.
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) { }
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) {
}
handleRemoteActionPubsubEvents(data) {
// perform some logic specific to Remote
Actions
}
See Also
• Message with Window Post Messages and Session Storage Messages

company 173
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.
Generic Framework Flow Diagram

The Generic Framework Flow diagram illustrates the order that the Common Action Utility methods
execute.
Requirements
To make the custom Lightning web component compatible with Vlocity Lightning web components, you
• 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.

company 174
Salesforce Modules.
Components.
NOTE
Custom Lightning Web Components will not throw errors unless Debug Mode is enabled.
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.
Common Action Utility

Make remote calls from any custom LWC using the Common Action Utility. The Common Action Utility
relies on the Vlocity Action Framework to make remote calls without the dependency of a strict OmniScript
data structure.
Utility: omniscriptActionUtils
Utility Class Name: OmniscriptActionCommonUtil

company 175
Defined Methods
Method Name Description Argument - Data Type Returns

executeAction Begins the execution of an action flow. • params - object promise
• queueableId - string
• comp - component
• payload - object
• vlcParams - object
handleActionEvent Handles action events once the remote call obtains a response. • comp - component void
s It can be configured to send events to the OmniScript Designer • resp - object
Debug console. Configured for sending pubsub events. • params - object
• element - object
In LWC, if sendDataToDebugConsole is defined in the
component, event logs can be sent to the Debug Console in the
Omniscript Designer. If the component is not in OmniScript,
define _debugLabel in the component populate the debug log
event name. If from omniscript, the debug log event name is
populated from the label property in the element's property set.
invokeAction Method that invokes an Apex class or a Promise resolution using • data - object promise
an action transformed request. • comp - component
• (optional) payload -
object
postProcess Post-processes remote call response for both successful and • resp - object object
failed remote calls and returns a post-processed response. The • element - object
return contains an object with the key nodes: • comp - component
• (optional) failure -
• result: stores the remote call's raw response boolean
• error: boolean
preProcess Preprocesses remote call parameters before invoking an action. • params - object object
• queueableRespId -
string
• comp - component
• payload - object
• vlcParams - object
Available Variables
Variable Name Description

_ns Namespace in dot notation
_element (Optional) Omniscript element JSON definition
Implementing the Common Action Utility

To implement the Common Action Utility:
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.

company 176
NOTE
Remote calls made to Apex classes inside a vlocity managed package must include
the namespace in the sClassName parameter sent into the executeAction.
import { getNamespaceDotNotation } from 'NS/omniscriptInternalUtils';

_ns = getNamespaceDotNotation();
2. Import OmniscriptActionCommonUtil into your LWC from the utility
class omniscriptActionUtils. 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
import { OmniscriptActionCommonUtil } from 'NS/omniscriptActionUtils';

3. Create an instance of the OmniscriptActionCommonUtil javascript class.
this._actionUtilClass = new OmniscriptActionCommonUtil();

4. Use the OmniscriptActionCommonUtil methods to execute remote calls to the server.
• The most common flow is to use the executeAction method. This method starts the remote call
flow, and the response callback from executeAction returns an object that has these properties:
• result: Contains the response from the remote call.
• error: Contains a boolean indicating the invoke status of GenericInvoke2.
• Parameters sent into the executeAction must be in an object format. The object must have the
following keys:
• input
• sClassName
• sMethodName
• options
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:

company 177
• Sample remote call using executeAction:
connectedCallback() {
}
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:
sendDataToDebugConsole(params, resp, label) {

let sendParams = JSON.parse(JSON.stringify(params));
if (sendParams && sendParams.options) {
let optionNode = JSON.parse(sendParams.options);
delete optionNode.options;
delete optionNode.input;
sendParams.options = optionNode;
}
let sendResp = JSON.parse(JSON.stringify(resp));
// for queueable support

if (sendResp && sendResp.responseResult) {
sendResp.responseResult = JSON.parse(sendResp.responseResult);
}
// dispatches action data to debug console

const debugEvent = new CustomEvent('omniactiondebug', {
bubbles: true,
cancelable: true,
composed: true,
detail: {

company 178
params: sendParams,
response: sendResp,
element: { label: label },
},
});
this.dispatchEvent(debugEvent);
}
• Sample queueable remote call using executeAction:
}
triggerQueueable() {
const options = {
input: '{}',
vlcClass: 'LwcTest',
vlcMethod: 'lwctest',
useQueueableApexRemoting: true,
};
const params = {
input: '{}',
sClassName: `$
{this._ns}VFActionFunctionController.VFActionFunctionControllerOpen`,
sMethodName: 'runActionFunction',
};
.then(response => {
})
.catch(error => {
});
}
• Sample continuation remote call using executeAction:
}
triggerContinuation() {
const options = {
input: '{}',
vlcClass: 'QeRemoteAction2',

company 179
vlcMethod: 'populateElements',
useContinuation: true,
};
const params = {
input: JSON.stringify(this.omniJsonData),
sClassName: 'QeRemoteAction2',
sMethodName: 'populateElements',
};
.then(response => {
})
.catch(error => {
});
}
• Sample future remote call using executeAction:
}
triggerFuture() {
const options = {
useFuture: true,
};
const params = {
input: '{}',
sMethodName: 'Test_Chainable',
};
.then(response => {
})
.catch(error => {
});
}
• Sample chainable remote call using executeAction:

company 180
}
triggerChainable() {
const options = {
chainable: true,
};
const params = {
input: '{}',
};
.then(response => {
})
.catch(error => {
});
}
• Sample parameters for a remote call from inside a Vlocity package:
const params = {
input: '{}',
options: '{chainable: true}',
};
Add Validation to a Custom Lightning Web Component in OmniScript

Add validation to custom Lightning web components that extend an OmniScript element's component by
using Vlocity's built-in validation methods.
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.
OmniScript Validation ReadMe

View validation examples for custom Lightning web components in the OmniScript Validation ReadMe. See
OmniScript ReadMe Reference.

company 181
Customize the Step Chart Component

Add customizations to your Step Chart by extending the Step Chart Lightning web components, the
StepChart component, and the Step Items 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

• Extend an OmniScript Element's Lightning Web Component
Extend and Override an OmniScript Modal Lightning Web Component

Customize modals in OmniScript by extending and overriding the Modal LWC.
Default Modal Default Error Modal
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:

company 182
<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
• 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.
Default Save for Later Acknowledge message:
To extend and override 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.

company 183
5. In Save Options, check Allow Save For Later.

6. Activate and preview the OmniScript to view the save for later override.
See Also
• Deploy Lightning Web Components
Add Custom Lightning Web Components to an OmniScript

After you Create a Custom Lightning Web Component for OmniScript, apply the component's new behavior
by adding it to an OmniScript.
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.
Mapping Option Description

Override an Element's Lightning Web Component Override an individual element's LWC.
Map an Element Type to a Custom Lightning Web Override the LWC for every element of a specific element Type—for
Component example, override the element Types Text or Currency.
Add a Custom Lightning Web Component to a Custom Add custom LWCs that do not extend an existing OmniScript element using
LWC Element the Custom LWC element.
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
• Style OmniScripts
Override an Element's Lightning Web Component

Override an element's component using the element's LWC Component Override
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.

company 184
1. From the element's properties pane, in the LWC Component Override field, enter the name of a
custom Lightning web component.
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
Map an Element Type to a Custom Lightning Web Component

Override all elements of one type with a custom Lightning web component by mapping the element type to
the Custom LWC.
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.
5. Click Preview to preview the OmniScript.
What's Next
OmniScripts.
See Also

Add custom Lightning web components that do not extend an OmniScript element's component by using
the Custom LWC element.
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.

company 185
Add a Custom LWC that Extends the OmniScript Base Mixin

To add a custom Lightning web component to a Custom LWC element:
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
1. Drag a Custom LWC element from Inputs into the canvas.

2. In the Lightning Web Component Name field, enter the name of a component that extends the
OmnIScriptBaseMixin.
3. (Optional) Expand the Custom Lightning Web Components Properties section and click Add New
Option.
4. (Optional) In the Property Name field, enter the name of a property that is defined in the custom
Lightning web component.
5. (Optional) In the Property Source field, enter a string or a merge field.
Add a Standalone Custom LWC

To add a standalone custom Lightning web component to an OmniScript:
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.
1. Drag a Custom LWC element from Inputs into the canvas.

2. In the Lightning Web Component Name field, enter the name of a Lightning web component.
3. Check the Standalone checkbox.

company 186
What's Next
OmniScripts.
See Also
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.
Styling Option Description Supported Design

Systems
Apply Custom Styling to OmniScripts Add custom styles to OmniScript using a custom style sheet. SLDS, NDS
with Static Resources
Extend an OmniScript Element's Create a custom LWC that extends an OmniScript to add custom SLDS, NDS
Lightning Web Component HTML, JS, and CSS.
Apply Global Branding to OmniScripts Override the Newport Design System with custom styles for an NDS
entire Salesforce org.
Customize SLDS Design Tokens in Add customizations to SLDS Design Tokens that exist in the SLDS
OmniScript OmniScript.
See Also
• Extend and Override an OmniScript Modal Lightning Web Component
• Extend and Override the Save for Later Acknowledge Lightning Web Component
Apply Custom Styling to OmniScripts with Static Resources

Apply CSS changes to an OmniScript using SLDS or Newport styling by referencing a CSS file static
resource in the Styling Options section of the OmniScript Designer. For example, a CSS sheet can change
the text color for every Number element in an OmniScript without using custom Lightning web components
to override the Number element.
NOTE
Multi-Language OmniScripts provide beta support for right-to-left languages. See Create
Multi-Language OmniScripts.

company 187
Before You Begin

1. Choose SLDS or Newport as the OmniScript theme.
2. View the OmniScript's original CSS by inspecting the element's on the page in console tools or by downloading the CSS files for
LWCs in the OmniScript. Download.
3. Create a CSS style sheet with custom CSS.
4. In Salesforce, add the CSS file as a static resource. See Using Static Resources (Salesforce Documentation).
1. In the OmniScript Designer, click Setup, and click Styling Options.

2. In the Custom Lightning Stylesheet File Name or Custom Newport StyleSheet File Name field,
enter the name of that Static Resource that stores your custom Lightning or Newport styling.
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.

company 188
"stylesheet": {
"newport": "",
"lightning": "",
"newportRtl": "myRtlNewportStyles",
"lightningRtl": ""
}
4. Activate and preview the OmniScript to view your custom styling.
See Also
• Apply Global Branding to OmniScripts
• Create Multi-Language OmniScripts
Reference Stylesheet Names in an OmniScript's JSON

Apply CSS changes to an OmniScript using SLDS or Newport styling by referencing a CSS file static
resource in your OmniScript's JSON properties. For example, a CSS sheet can change the text color for
every Number element in an OmniScript without using custom Lightning web components to override the
Number element.
Before You Begin

1. Choose SLDS or Newport as the OmniScript theme.
2. View the OmniScript's original CSS by inspecting the element's on the page in console tools or by downloading the CSS files for
LWCs in the OmniScript. Download.
3. Create a CSS style sheet with custom CSS.
4. In Salesforce, add the CSS file as a static resource. See Using Static Resources (Salesforce Documentation).
NOTE
Multi-Language OmniScripts provide beta support for right-to-left languages.
1. In OmniScript, go to Setup or Script Configuration and click Edit as JSON.

2. In the JSON properties, find the node named style sheet:
"stylesheet": {
"newport": "",
"lightning": ""
}
3. Add the name of the static resource as a value to newport or lightning.
"stylesheet": {
"newport": "",
"lightning": "myCustomOmniScriptStyles"
}

company 189
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
Customize SLDS Design Tokens in OmniScript

Modify the appearance of an OmniScript by overriding Salesforce's SLDS Design tokens.
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.
Before You Begin

1. View the Design Tokens that have global access. See Design Tokens.
2. Preview and inspect an OmniScript in a developer console to view the current tokens present in the OmniScript.
1. In your OmniScript's Setup panel, click the Styling Options section or Lightning Design System
Design Tokens section.

company 190
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;

company 191
See Also
Use Images for Buttons in OmniScript

Use images as buttons for both radio and multi-select options in OmniScript.
1. In an element, scroll down to the Options section for the element.

2. Select Image from the dropdown menus located under the Display Mode and Option Source.
3. Click the + Add button to choose which image to display. When the user selects the image while filling
out the OmniScript, the option's value is added to the Data JSON.
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.
To use the Line Break element:
1. Drag the element into the OmniScript canvas.

2. When editing the Line Break's element properties, you can add additional padding below the line break
by entering a value in Additional Padding (px).
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.

company 192
See Also
• Modify OmniScript UI Behavior
Apply Global Branding to OmniScripts

Apply global style changes to OmniScripts by using the Newport Design System. The Newport Design
System enables you to download, edit, and override the existing Newport CSS styling to apply your
changes.
Before You Begin

If you are unfamiliar with using command-line interfaces, see Command Line 101 (git-tower documentation).
System Requirements:
• Git (git-scm documentation)

• nodeJS v12.0 or higher (Node documentation)
• Gulp CLI: npm install --global gulp-cli
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.

company 193
8. Preview the changes in your Salesforce org by using the Newport Player in the OmniScript Designer
Preview.
See Also
• Apply Custom Styling to OmniScripts with Static Resources

Customizing OmniScripts and Cards with Vlocity Newport Design System

To customize the appearance of your OmniScripts or Cards, edit the CSS and HTML files in the UI
subdirectory of the directory where you cloned Newport.
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.
Previewing Your Changes

To view the effect of Newport styles on an OmniScript, edit its Script Configuration and paste the path to the
top-level CSS file (by default, xxx.css) into the CUSTOM HTML TEMPLATES field.
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.

company 194
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.
Before You Begin

1. Download the Newport Design System. See Apply Global Branding to OmniScripts.
2. Create a distribution folder containing your changes by issuing this command: npm run-script dist
3. In Salesforce, upload the zip file as a static resource.
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

Modify OmniScript UI Behavior

This section explains how to modify UI behaviors in an OmniScript.
Behavior options include:
• Hide or show elements and errors conditionally

• Hide Next and Previous buttons
• Trigger events
Conditionally Display Elements Using the Conditional View Property

Every step, block, or element supports Conditional Viewing. Conditional Views allow you to hide the
element or the group of elements contained in a block or step based on certain conditions.
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.
To set up Conditional Views:

company 195
1. From the Properties section on the element, go to the Conditional View section.
2. Select a Condition Type from the drop-down menu.
LWC OmniScript Designer Description

Conditions
Show Element if True The element renders only if the conditional is true. If the conditional is false, the
element is hidden from the UI.
Disable Read Only if True Disables Read Only on an element if the conditional is true. If the value is false, the
element becomes Read Only.
Set Element to Required if True The element becomes required if the condition is true.
3. Choose the logical operator for the group (AND or OR). The AND operator requires that both
conditions are met; the OR operator requires that one of the other condition is met.
4. Click Add Condition.
5. In the left operand, enter the name of the element in plain text.
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.
6. In the right operand enter one of these syntax types::

• If the element type is Text, enter the string in plain text.
• If the element type is Checkbox or Disclosure, enter true or false.

• If the element type is Number, enter a number.
• 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))

company 196
• Time—2015-02-21T00:09:40.270Z (Thu Jan 01 1970 22:19:00 GMT-0800 (PST))

• The right operand supports merge fields. For example Name = %contactLastName%
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.
Running Validation with onChange

OmniScripts run validation when a user clicks out of a field by using the onBlur function.
1. In the Setup properties, click Edit as JSON.

2. Add the property "commitOnChange": true.
3. Preview the behavior.
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
Hide OmniScript Elements

Hide elements and child elements using the Hide property available on OmniScript Input Components,
Blocks, Steps, Groups, Formulas, and Aggregate elements.
1. From the element properties panel, click Edit as JSON.

company 197
2. Set the "hide" property's value to "true".
See Also
• Creating Dynamic Forms Using the Conditional View Property
Hide the Next and Previous Buttons

Hide a Step's Next and Previous buttons when using auto-advance options or when you do not want the
user to navigate steps.
To hide a Step's Next or Previous button:
1. In the Step's properties, expand the Button Properties section.

2. Drag the Previous or Next Width slider to 0.
3. Save your OmniScript and preview the new behavior.
Display Messages in OmniScripts

Display comments, requirements, success, and warning messaging depending on whether the validate
expression returns true or false. Configure the Messaging element after Creating a Formula or Aggregate in
an OmniScript, or any other element, to display validation messages in the OmniScript. Merge fields are
supported in messages.
To add a Messaging element to an OmniScript:
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.
To enable the OmniScript to run validation when a user types:
1. In the Setup properties, click Edit as JSON.

2. Add the property "commitOnChange": true.
3. Preview the behavior.
NOTE
In LWC OmniScripts, the onChange behavior runs after a half-second delay.

company 198
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:
• The Requirement message displays when the validation fails:
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.

company 199
Message Type OmniScript Lightning Example OmniScript Newport Example

Success
Requirement
Warning
Comment
Fire Platform Events from OmniScripts

Fire Salesforce platform events from the context of an OmniScript.

company 200
1. Go to Setup and, under Develop, click Platform Events.

2. On the Platform Events page, click New Platform Event.
3. On the New Platform Event page, define the platform event, specifying the fields for the data that you
want to associate with the event.
4. To fire the event, create a DataRaptor Load that populates the platform event fields with event-specific
data.
5. In the OmniScript, compose the data JSON containing the data required by the DataRaptor Load.
6. Add a DataRaptor Load action to the OmniScript, specifying the DataRaptor that fires the platform
event.
To verify that your platform event was fired correctly, use one of the programmatic methods described in the
related Salesforce developer documentation.
Set Errors In an OmniScript

Put error or validation messaging on one or more elements in a previous step based on conditions from
future steps using the Set Errors action element. Using required fields and Formula/Messaging elements,
you can only set requirements and conditions on elements in the current step.
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:

company 201
The Set Errors element:

company 202
1. In OmniScript, drag the Set Errors element into the canvas.

2. Add a conditional to control when the Set Errors message displays. Without a conditional the error will
persist in the OmniScript. See Conditionally Display Elements Using the Conditional View Property.
3. In the Element Name field, enter the name of your element.
4. In the Value field, enter the error message that displays to the user.

company 203
NOTE
The Set Errors action does not support these elements: File, Image, Messaging, and
Formula.
Deploy, Launch, and Embed OmniScripts

Deploy your OmniScript and launch it from a Community page, Lightning page, custom LWC, or off-platform
application.
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. Deploy your OmniScript. See Activate and Deploy OmniScripts.

2. After deploying your OmniScript, launch your OmniScript from one of these experiences:
Experience Description Example

Community Pages Launch an OmniScript from a Community page using the Add an OmniScript to a Community
OmniScript's generated LWC or the Vlocity LWC OmniScript or Lightning Page.
Wrapper component.
Embedded inside of a Launch an OmniScript from a custom Lightning web Embed an OmniScript Lightning
custom component component by embedding the OmniScript's LWC. Web Component in a Lightning Web
Component
Off-Platform Run OmniScripts off-platform using OmniOut. OmniOut
Lightning Pages Launch an OmniScript from a Lightning page using the Add an OmniScript to a Community
Wrapper component.
Activate and Deploy OmniScripts

Make OmniScripts available to Communities, Lightning Pages, custom LWCs, and Lightning tabs by
activating and deploying the OmniScript. If an error occurs during deployment the OmniScript will
deactivate.
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:

Community Pages Launch an OmniScript from a Community page using the Add an OmniScript to a Community
Wrapper component.
Embedded inside of a Launch an OmniScript from a custom Lightning web Embed an OmniScript Lightning
custom component component by embedding the OmniScript's LWC. Web Component in a Lightning Web
Component
Off-Platform Run OmniScripts off-platform using OmniOut. OmniOut

company 204

Lightning Pages Launch an OmniScript from a Lightning page using the Add an OmniScript to a Community
Wrapper component.
4. (Optional) If an error occurs on the initial load of an OmniScript, in the OmniScript, click Deactivate,
then click Activate. This redeploys the OmniScript.
5. (Optional) Map deployment errors using the Error Handling Framework. . See Customize OmniScript
Error Messages.
Error Mapping Example:
Original error
Error Message Mapping a Path and Value to a new message
New error message
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

company 205
See Also
• 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={prefill} layout="lightning"></c-type--sub-

type-english>
<c-type--sub-type-english prefill='\{"ContextId":"abc","otherParam":"FAQ"}'
layout="newport"></c-type--sub-type-english>
Vlocity Aura Wrapper

Once Activated, the OmniScript can be accessed using Vlocity’s prebuilt Aura component.
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'
}
})
Lightning URL Example

company 206
https://my_org.force.com/lightning/cmp/my_org__vlocityLWCOmniWrapper?
c__target=my_org:typeSubTypeEnglish&c__layout=lightning&c__tabIcon=custom:custo
m18
Newport URL Example
https://my_org.force.com/lightning/cmp/my_org__vlocityLWCOmniWrapper?
c__target=my_org:typeSubTypeEnglish&c__layout=newport&c__tabIcon=custom:custom1
8
Launch OmniScripts from Lightning and Community Pages

Launch OmniScripts in Communities and Lightning Pages using the generated OmniScript Component or
the LWC OmniScript Wrapper component.
Generated OmniScript Lightning Web Component or LWC OmniScript Wrapper?

Use this table to determine whether the LWC OmniScript Wrapper component or a generated OmniScript
component meets your requirements.
Component Type Capabilities Reference

Generated OmniScript • Automatically passes the RecordId for the page into the Add an
OmniScript's Data JSON in the ContextId node OmniScript
• Displays one layout, Lightning or Newport to a
• Not directly URL addressable Community
• URL addressable through the Community Page or Lightning or
Page URL Lightning
Page
• Cannot accept parameters since it is not directly URL
addressable
Vlocity LWC OmniScript Wrapper • Accepts additional URL parameters Launch an
• Loads in different OmniScripts based on parameters OmniScript
• Accepts prefill information with LWC
• Compatible with LWC Save For Later prefill functionality OmniScript
Wrapper
Add an OmniScript to a Community or Lightning Page

Add an OmniScript to a Community or Lightning page by adding the OmniScript's generated Lightning web
component. The component is generated when you activate the OmniScript.
Before You Begin

1. Deploy an OmniScript to make it available in Community and Lightning App Builders. For more information, see Activate and Deploy
OmniScripts.
2. Review the options for launching an OmniScript from a Lightning or Community Page. See Launch OmniScripts from Lightning and
Community Pages.
Add your OmniScript to a Community Page

Add your OmniScript to a Salesforce Community page.
1. In a Community Builder, click on the Components tab.

company 207
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.
3. Drag the component into the Community page.

4. (Optional) Apply Newport styling by entering newport into the layout field in the component's
properties panel. Lightning styling is the default styling when the layout property is blank.

company 208
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.
Add your OmniScript to a Lightning Page

Add your OmniScript to a Salesforce Lightning page.

company 209
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.
2. Drag the component into the Lightning Page.

3. (Optional) Apply Newport styling by entering newport into the layout field in the component's
properties panel. Lightning styling is the default styling when the layout property is blank.

company 210
4. (Optional) Configure the inline options. See Display Inline OmniScripts on Lightning and Community
Pages.

company 211
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
• Activate and Deploy OmniScripts

Launch an OmniScript with LWC OmniScript Wrapper

Launch Omniscripts on Community and Lightning pages using the Vlocity LWC OmniScript Wrapper
component.
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.
Before You Begin

1. Deploy an OmniScript to make it available in Community and Lightning App Builders. For more information, see Activate and Deploy
OmniScripts.
2. Review the options for launching an OmniScript from a Lightning or Community Page. See Launch OmniScripts from Lightning and
Community Pages.
Launch OmniScripts in Communities from URLs

Launch any OmniScript on a Community Page by sending a URL to the Vlocity LWC OmniScript Wrapper
component on the page.
To add the Vlocity LWC OmniScript Wrapper component to a Community page:
1. On a Community Builder page, click on the Components tab.

company 212
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

company 213
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.

company 214
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.
PubSub Message? enabled to fire the event.
Launching an OmniScript in Lightning

To make an OmniScript URL addressable using the vlocityLWCOmniWrapper:
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/
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.
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

company 215
8. (Optional) To view additional parameters for the vlocityLWCOmniWrapper, see Launch Lightning Web
Component URLs with vlocityLWCWrapper.
PubSub Message? enabled to fire the event.
10. Paste the URL wherever you plan to invoke the OmniScript from and preview the functionality.
Launching an OmniScript from a Layout Action

To launch the OmniScript from a layout action:
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.
Display Inline OmniScripts on Lightning and Community Pages

Enable OmniScripts to run inline without leaving the context of a page.
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 .
Before You Begin

Ensure your OmniScript is active. For more information, see Activate and Deploy OmniScripts.

company 216
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.
3. In the inlineLabel field, enter the text to display on the button.

4. (Optional) Choose an inlineVariant to alter the button's appearance.
5. (Optional) Enable events to fire by enabling Cancel Options. See Configure OmniScript Cancel
Options.
6. Click Save, and preview the OmniScript.
See Also

company 217
Run OmniScripts Off-Platform with OmniOut

Deploy and host OmniScripts on third-party sites by adding OmniOut to your application.
OmniOut enables OmniScripts to create, read, update, and delete Salesforce data from a third-party
website.
What's Next
Configure OmniOut. See OmniOut.
Deploy an OmniScript to an External Salesforce Site

After creating a new Visualforce OmniScript page, you can deploy to an external Salesforce website. Once
embedded within the page, the script can be versioned, modified, and activated without the need to
reconfigure the page.
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.
Embed an OmniScript Lightning Web Component in a Lightning Web

Component
Embed an OmniScript LWC in a Lightning web component by copying the OmniScript component tag and
adding it directly into a component.

company 218
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\""}.
Embed the Component

Copy the OmniScript component tag and embed it in a component.
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>
Detect Data JSON Updates in an Embedded OmniScript

Detect changes in an embedded OmniScript's data JSON by using the omniaggregate event.
1. Add an event listener that accepts the omniaggregate event as an argument.
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) {

company 219
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));
Embed an OmniScript in Another OmniScript

An OmniScript can be reused in one or more existing OmniScripts. Reusing OmniScripts enables you to
build a variety of smaller scripts and then piece them together into one or more parent scripts. Embedded
OmniScripts behave just like other OmniScript elements.
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 FlexCards in an OmniScript
Activate and Deactivate Embedded OmniScripts

When you activate or deactivate an embedded script, Vlocity updates all activated parent scripts to reflect
the change.
Before You Begin

Learn how to embed an OmniScript in other OmniScripts. See Embed an OmniScript in Another OmniScript.

company 220
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.
3. After the parent scripts update, click Done.
See Also
• Embed FlexCards in an OmniScript
Adding an Apex Class Permissions Checker

Enable specific access to Remote Action APIs (Vlocity Open Interface Apex classes) per user or profile.
Configure an Apex class permissions checker to require the user to have explicit access to the Apex class
that administers the remote action called from an Omniscript, FlexCard, Classic Card, or REST API.
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.
1. In your org, go to Setup.

2. Type Custom Settings in the Quick Find search box and click Custom Settings.
3. From the Custom Settings page, click on the custom setting named General Settings.
4. On the General Settings page, click Manage.
5. Click New.
6. Enter ApexClassCheck into the Name field.

7. Enter true into the Value box.

company 221
8. Click Save to complete the process.
Create Multi-Language OmniScripts

Enable a single OmniScript to run in multiple languages using Salesforce custom labels.
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
Enable Multi-Language OmniScript Support

Enable multi-language OmniScript support by modifying the Vlocity OmniScript object in Salesforce's
Setup.
Before You Begin

View the steps necessary to create a multi-language OmniScript. See Create Multi-Language OmniScripts.
NOTE
Beginning with Vlocity Insurance and Health Summer '20, the LWC OmniScript Designer
supports multi-language OmniScripts.
To enable multi-language support for OmniScripts:

company 222
1. From Salesforce's Setup, under Create, choose Objects.

2. Click the Vlocity OmniScript object link. The custom object definition is displayed.
3. In the Custom Fields and Relationships section, edit the Language picklist, and add Multi-
Language to the list of values. Click Save.
4. In your OmniScript, click Edit, and set Language to Multi-Language.
What's Next
Define Custom Label Translations in Multi-Language OmniScripts
See Also

• OmniScript Custom Label Reference
Define Custom Label Translations in Multi-Language OmniScripts

Define translations for custom labels in multi-language OmniScripts using OmniScript's translation modal.
OmniScript provides default custom labels that require translations in addition to Salesforce custom labels.
Before You Begin

Enable multi-language OmniScripts. See Enable Multi-Language OmniScript Support.
1. In an OmniScript's Script Configuration section, set Language to Multi-Language.

2. Next to the Language field, click Edit.
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.

company 223
NOTE
Use naming conventions when creating custom labels in an org with multiple
developers to avoid duplications and improve querying. Example syntax:
jSmithCustomTextLabel.
5. In the Custom Label Value field, enter a translation.
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.

company 224
See Also
• Translate Custom Labels for Date and Time Components
Access Custom Labels in an OmniScript Custom Lightning Web Component

Provide custom Lightning web components access to Salesforce custom labels in your OmniScript.
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.
Before You Begin

View the OmniScript's default custom labels or create custom labels in Salesforce. See OmniScript Custom Label Reference and Create
and Edit Custom Labels.
1. In the OmniScript's Script Configuration, click Edit as JSON.

2. In the JSON, add the node "moreCustomLabels": and set the node's value equal to an array of the
custom labels that do not exist in the OS.
"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.
Component Type Syntax

Component extending the OmniScript Base Mixin component this.omniScriptHeaderDef.allCustomLabels
Component extending an OmniScript element's LWC this.scriptHeaderDef.allCustomLabels
4. Using dot notation, append the name of the attribute the custom LWC requires to access the label.
Component Type Syntax

Component extending the OmniScript Base Mixin this.omniScriptHeaderDef.allCustomLabels.myCustomLabel
component
Component extending an OmniScript element's this.scriptHeaderDef.allCustomLabels.myCustomLabel
LWC
5. Deploy the custom Lightning components to a Salesforce org. See Deploy Lightning Web
Components.
6. Activate and preview the OmniScript to ensure the label displays correctly.
See Also
• Define Custom Label Translations in Multi-Language OmniScripts
Translate Tooltip Help Text in OmniScripts

Display tooltip help text with multiple translations in multi-language OmniScripts.

company 225
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.
Before You Begin

Define custom labels for your help text. See Define Custom Label Translations in Multi-Language OmniScripts.
1. In your OmniScript, select an element that requires help text translation.

2. In the element's properties, click Help Options.
3. Check Activate Help Text.
4. In the Help Text field, enter the custom label.
5. Preview the OmniScript to render the custom labels.
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
Translate Custom Labels for Date and Time Components

Define custom label translations for date and time components using JSON strings and OmniScript custom
labels.
Before You Begin

Learn how to translate custom labels in Salesforce. See Translating Custom Labels.
1. Go to Day.js, click List of supported locales, and choose a language file.

2. In the language's JavaScript file, copy the locale object.

company 226
3. Open a window console or JavaScript editor and paste in the locale object.

company 227
4. Execute the JavaScript, and run JSON.stringify(locale) in the console.
NOTE
Custom labels accept valid JSON strings only.
5. Copy the resulting JSON string.

company 228
6. Choose a custom label that meets your requirements and open it in Salesforce.
Custom Label Description

cmpDayJsLocaleFormats Applies translations to Vlocity LWC date components and OmniScript date elements. The
cmpDayJsLocaleFormats label does not apply translations to OmniScript if the
OmniDayJSLocaleFormats label has translations defined.
OmniDayJsLocaleFormats Applies translations to OmniScript date and time elements only. Overrides the
cmpDayJsLocaleFormats label in OmniScript if both custom labels have translations defined.
7. In the custom label, click New to add a new translation.
8. In the Translation field, paste in the JSON and remove the quotations surrounding the object.

company 229
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
Create Multi-Language Select Elements

To populate Select, Multi-select, and Radio elements for a multi-language OmniScript, you have the
following options:
• 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.
Configure Options Manually

To manually compose a multi-language Select element:
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:
• Option Source: Manual

• Options:
• Value: The value to be written to the data JSON if this option is selected
• Label: The name of the Salesforce custom label from which the text for the option is read.
For example, for a list of animals, you might define three custom labels with translations in Salesforce:
Custom Label Default Value Spanish Translation

Animal_Bear Bear Oso
Animal_Dog Dog Perro
Animal_Cat Cat Gato
In OmniScript Designer, specify the Options for the Select element, for example:
Value Label
1 Animal_Bear
2 Animal_Dog

company 230
Value Label
3 Animal_Cat
Populate the Options Programmatically

To populate options for a Select element using Apex:
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:
• Option Source: Custom

• Source: The class and method that return options
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:
• Option Source: Custom

• Source: Omit
• Element: The OmniScript element containing the value that determines how this
dependent element is populated.
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
global class PicklistPopulation implements VlocityOpenInterface { public

Boolean invokeMethod(String methodName, Map<String, Object> input, Map<String,
Object> outMap, Map<String, Object> options) { try { if
(methodName.equals('PopulatePicklist')) { PopulatePicklist(input, outMap,
options); } else if (methodName.equals('PopulateDependentPicklist'))
{ PopulateDependentPicklist(input, outMap, options); } } catch (Exception e)
{ System.debug(LoggingLevel.ERROR, 'Exception: ' + e.getMessage() + ' ' +
e.getStackTraceString()); } return true; } // Get All Contacts Associated with
the ContextId Account where the Omniscript is Launched public void
PopulatePicklist(Map<String, Object> input, Map<String, Object> outMap,

company 231
Map<String, Object> options) { List<Map<String,String>> plOptions = new

List<Map<String, String>>(); String lang = (String)input.get('LanguageCode');
for(Integer i=0; i<2; i++) { Map<String, String> tempMap = new Map<String,
String>(); tempMap.put('name', 'test'+ String.valueOf(i)); // Language
Independent tempMap.put('value', 'testV'+ String.valueOf(i)); // Displayed in
Picklist UI if(lang == 'zh_CN') tempMap.put('value', 'testV' +
String.valueOf(i) + ' 中'); plOptions.add(tempMap); }
outMap.put('options',plOptions); } // Populate a Dependent Picklist based on
the Contacts ReportsToId Field Selected in the Other Field this field depends
on public void PopulateDependentPicklist(Map<String, Object> input,
Map<String, Object> outMap, Map<String, Object> options) { // Map of List
where the Key is the Potential Values in the Other Picklist Map<String,
List<Map<String, String>>> dependency = new Map<String, List<Map<String,
String>>>(); String lang = (String)input.get('LanguageCode'); String
elementName = (String)input.get('controllingElement'); // itself
Logger.debug('hello1 ' + lang); Logger.debug('hello2 ' + elementName);
List<String> controlValList = new List<String>();
controlValList.add('Licensing & Permitting'); controlValList.add('Contract');
for(Integer i=0; i<2; i++) { List<Map<String, String>> optionList = new
List<Map<String, String>>(); for(Integer j=0; j<2; j++) { Map<String, String>
tempMap = new Map<String, String>(); tempMap.put('name', controlValList[i] +
'Child' + String.valueOf(j)); // Language Independent tempMap.put('value',
controlValList[i] + 'ChildV' + String.valueOf(j)); // Displayed in Picklist UI
if(lang == 'zh_CN') tempMap.put('value', controlValList[i] + 'ChildV' +
String.valueOf(j) + ' 中' ); optionList.add(tempMap); }
dependency.put(controlValList[i], optionList); }
outMap.put('dependency',dependency); } }
Use a Translated SalesForce Picklist

In OmniScript Designer, add a Select element and configure it as follows:
• Options Source: sObject

• Source: <sObjectName>.<fieldName>
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
To translate the picklist options in Salesforce:
1. In Setup, under Administration Setup, choose Translation Workbench.

2. On the Translate screen, choose the target language.
3. From the Setup Component list, choose Picklist Value.
4. From the Object list, choose the object where the picklist field is defined. The picklist and its values are
displayed as a tree.

company 232
5. For each option. specify the translated value, then save your changes.
Test a Multi-Language OmniScript

View custom translations using the OmniScript Designer preview.
Before You Begin

Enable multi-language OmniScripts and define custom labels translations. See Define Custom Label Translations in Multi-Language
OmniScripts.
To test your multi-language OmniScript from OmniScript Designer:
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

• Deploy, Launch, and Embed OmniScripts
Launch a Multi-Language OmniScript

Set the language a multi-language OmniScript renders in by using a language code parameter in a URL.
Before You Begin

Define translations for custom labels and enable multi-language OmniScript. See Enable Multi-Language OmniScript Support.
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.
c__target=c:docLWCTestEnglish&c__layout=lightning&c__LanguageCode=es

company 233
NOTE
Resume saved OmniScripts in other languages by using a different language code
parameter.
See Also
• Test a Multi-Language OmniScript
OmniScript Custom Label Reference

This page contains tables listing the OmniScript element properties for which you must define custom
labels and translations for multi-language OmniScripts. To use a default translation, clear the property.
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.
Required Translations for OmniScripts

Element Properties
All elements label
Calculation Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
Checkbox checkLabel
DataRaptor Extract Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
DataRaptor Post Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
DataRaptor Transform Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
Disclosure checkLabel
DocuSign Envelope Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
DocuSign Signature Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
Edit Block newLabel, editLabel, deleteLabel

company 234
Email Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,

inProgressMessage
Integration Procedure Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
Matrix Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
Multi-Select options[i].value
PDF Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
Radio options[i].value
Remote Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
Rest Action errorMessage.custom[n].message, errorMessage.default, failureNextLabel, failureGoBackLabel,
inProgressMessage
Script Header consoleTabLabel
Select options[i].value
Step cancelLabel, nextLabel, previousLabel, saveLabel, cancelMessage, saveMessage
Type Ahead Block newItemLabel
Validation messages[i].text
The following table lists the properties for which Vlocity provides custom labels with default translations.
Property Default Custom Label

cancelLabel OmnicancelLabel
cancelMessage OmnicancelMessage
consoleTabLabel OmniconsoleTabLabel
editLabel OmnieditLabel
failureGoBackLabel OmnifailureGoBackLabel
failureNextLabel OmnifailureNextLabel
inProgressMessage OmniinProgressMessage
newItemLabel OmninewItemLabel
newLabel OmninewLabel
nextLabel OmninextLabel
postMessage OmnipostMessage
previousLabel OmnipreviousLabel
remoteConfirmMsg OmniremoteConfirmMsg
saveLabel OmnisaveLabel
saveMessage OmnisaveMessage
See Also

company 235
Advanced Configuration for OmniScript Form Elements

This section tells you how to work with elements that enable users to input information, search for record
information, select options, create records, edit records, and delete records. For information on all
OmniScript elements, see OmniScript Element Reference.
Add Options for Selects, Multi-Selects, and Radio Buttons

To add options for Select, Multi-Select, and Radio Buttons, go to the Option Source section of the element
and click +Add new option. If no values are defined for a Select element, an Undefined Value is returned.
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.

company 236
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.
Set Date and Time Ranges

The Date, Date/Time, and Time elements enable users to input dates and times into an OmniScript form.
Each element has different properties that enable you to present a selectable range of dates or times to the
User.
Date Range
To create a selectable Date range for the Date or Date/Time element, configure the following properties:
• minDate: Sets the earliest selectable date in the range.

• maxDate: Sets the latest selectable date in the range.
The minDate and maxDate fields accept both dynamic and static values.
Examples of acceptable dynamic value syntax:
• today + 1 day
• today - 5 days
• today + 2 months
• today - 1 month
Examples of acceptable static value syntax:
• 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:

company 237
• minTime: Sets the earliest selectable time in the range.

• maxTime: Sets the latest selectable time in the range.
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.
Examples of acceptable 12-hour clock values include:
• 01:00 AM
• 01:00 PM
• T07:30:00.000Z
Examples of acceptable 24-hour clock values include:
• 01:00
• 13:00
• T19:30:00.000Z
Tying a Picklist to Salesforce

Using Vlocity OmniScript, you can dynamically populate a Select, Multi-Select, or Radio element with
values from a picklist in your Salesforce org, or using a custom Apex class.
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:

company 238
Now the form will retrieve and dynamically populate the list with values from Case.Status:

company 239
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.
Populating Picklist Values From Apex

You can populate Select, Multi-select, and Radio elements from a Vlocity Open Interface Custom
implementation. The values for the element are obtained during the OmniScript's activation. For information
on populating dependent picklists, see Populating Dependent Picklist Values with Apex.
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.
Apex Code for Populating Picklist:
global class PicklistPopulation implements VlocityOpenInterface {

public Boolean invokeMethod(String methodName, Map < String, Object >
input, Map < String, Object > outMap, Map < String, Object > options) {

company 240
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.
Populating Dependent Picklist Values with Apex

You can populate Select, Multi-select, and Radio elements from a Vlocity Open Interface Custom
implementation. The values for the element are obtained during the OmniScript's activation.
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.

company 241
Sample Apex Code:
global class PicklistPopulation implements VlocityOpenInterface {

public Boolean invokeMethod(String methodName, Map < String, Object >
input, Map < String, Object > outMap, Map < String, Object > options) {
if (methodName.equals('PopulateDependentPicklist')) {
PopulateDependentPicklist(input, outMap, options);
}
return true;
}
// Populate a Dependent Picklist based on the all Party Relationship type
valid for a "Source Party Type" Selected in another field
public void PopulateDependentPicklist(Map < String, Object > input, Map <
String, Object > outMap, Map < String, Object > options) {
// Map of List where the Key is the Potential Values in the Other
Picklist
Map < String, List < Map < String, String >>> dependency = new Map <
String, List < Map < String, String >>> ();
for (vlocity_namespace__PartyRelationshipType__c rel: [Select
vlocity_namespace__TargetRole__c, vlocity_namespace__SourcePartyType__c Id
FROM vlocity_namespace__PartyRelationshipType__c]) {
if (!
dependency.containsKey(rel.vlocity_namespace__SourcePartyType__c)) {
dependency.put(rel.vlocity_namespace__SourcePartyType__c, new
List < Map < String, String >> ());
}
Map < String, String > tempMap = new Map < String, String > ();
tempMap.put('name', rel.Id);
// Language Independent
tempMap.put('value', rel.vlocity_namespace__TargetRole__c);

company 242
// 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:
1. Set the Data Source Type to SObject.

2. Under Input Parameters, configure these fields:
• Data Source: Select an Element Name from the dropdown to send that element's JSON value in the
lookup request.
• Filter Value: Enter a name for the JSON value to use in the lookup query configuration.
This example image sets the path to the CompanyName JSON node from the first step and passes
Company Name as a filter value in the query.

company 243
3. Configure the Lookup Query Configuration:

a. Click + Add New Lookup Configuration.
b. (Optional) In Lookup Priority, enter a number to set priority for the Lookup order if there are
multiple queries.
c. In Lookup Object, select an SObject.
d. In Lookup Object Field, select an SObject field to run the query against.
e. Click Filter Operator to select an operator. For example, to return an exact match, use the =
operator, or to select matches similar to the filter value, select the LIKE operator.
f. In Filter Value, enter the name of a Filter Value used in the Input Paramters section. In the
previous example, this value is Company Name.
g. Set the return path for the filtered values by adding the Element Name of the Lookup element
into the JSON path.

company 244
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.

company 245
5. Preview the OmniScript to ensure the query is working and the value is being set correctly.
The query is structured in this format:
SELECT Lookup Object WHERE Lookup Object.Field Name = Filter Value
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.
Picklist Filter by Record Type

Enables the filtering of picklist options by record type.
Before using the Record Type filter, set up a Remote Site to enable the options to load into the OmniScript
preview Visualforce page.
1. Navigate to the OmniScript Designer home page.

2. Copy the text in the URL bar immediately before /apex.
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.

company 246
7. Click Save.
To filter the options:
1. In the Picklist Object and Field property, enter the picklist in the following format:
2. Filter the picklist by Record Type by entering the Record Type into the Record Type property. This
property supports %MergeFields%.
Working with Lookup Query Configurations

To learn more about looking up values in an OmniScript, see Lookup Element.
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.
Figure 5. Example AND Join
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.

company 247
Deep Query
To create a Deep query, the Lookup Order is put in sequential order. OmniScript builds smaller query sets
at each order set.
Figure 6. Example Deep Query
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.

company 248
Figure 7. Example with an OR Join
The Vlocity_Industry__c formula field example uses this syntax:

IF(
OR(
ISPICKVAL(Industry, "Government"),
ISPICKVAL(Industry, "Insurance"),
ISPICKVAL(Industry, "Communications")
),
"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.
Controlling Field Property

The Controlling Field Property on a Select Element can display Select Field Values based on the selection
of another value from a Controlling Select field. Both the controlling and dependent fields must pull their
field values from a field in Salesforce using the sObject property and those fields must have a Field

company 249
Dependency setup between one another via Salesforce Field Dependency feature. For more information,
see Define Dependent Picklist in the Salesforce Help.
Figure 8. Example Controlling Field Setup
Figure 9. Controlling Field Configuration

company 250
Figure 10. Dependent Field Configuration
Figure 11. Defined Field Dependency in Salesforce
Using Option Source Custom

When using Custom as an option source, you can define an Apex class that will pull in the Picklist values
source. For more information, see Populate Picklist Values From Apex.

company 251
Evaluating Elements in Repeatable Blocks

If the Formula element is in a repeatable block and evaluates an element also in that block, use |n in the
expression builder to denote that the formula should only evaluate the element in the current block. For
example, the childAge formula element converts the childBirthday date element (in the same block) into a
number using the formula AGE(%childBirthday|n%) :
When the OmniScript runs, the childAge formula element evaluates only the childBirthday element in the
same block:
Using the Rich Text Editor in the Vlocity OmniScript Designer

The Text Block and Disclosure element instructions use a Rich Text Editor to display HTML in an
OmniScript. In addition to standard Rich Text Editor features, you can:
• 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.

company 252
• Insert Smart Links to Salesforce Knowledge articles.

• Reference data JSON using merge fields.
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.
OmniScript Data and External Integrations

OmniScript handles data and external integrations through OmniScript Action Elements, OmniScript Group
Elements, and OmniScript Input Elements. Elements use OmniStudio DataRaptors, Integration Procedures,
HTTP Actions, and Apex to load, transform, and post data.

company 253
Load Data into OmniScript Elements

Populate OmniScript elements with data to prefill elements, create selectable options, dynamically display
elements, and test functionality. Load data into your OmniScript using DataRaptors, Integration Procedures,
HTTP Actions, URL parameters, or Apex.
Load Salesforce Data into OmniScript Using DataRaptor

Add Salesforce data into your OmniScript using a DataRaptor Extract Action.
To get data from Salesforce into OmniScript elements, create a DataRaptor Extract, as follows.
1. From the Vlocity DataRaptor page, click New.

2. Choose Extract and specify a Name, Type, and SubType.
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:
1. Click Add Extract Step and choose the source sObject.

2. In the Extract Output Path field, specify the name of the top-level node in the Extraction Step JSON
where you want the data to reside.
3. To filter the incoming data, specify filter settings. Typically you compare the context Id from the sObject
with a merge field containing the context Id from the OmniScript, for example, Id = %caseId%.
4. On the Formulas tab, you can define expressions that add data to the Extraction Step JSON. For
more information, see DataRaptor Operators and Functions.
5. On the Output tab, map data from the Extraction Step JSON to the Current JSON Output, which is
returned to the OmniScript. For each OmniScript element that you want to populate with data, click +
and specify the source - the Extract Step JSON node - and the output path for the data. The name of
the output JSON node must match the OmniScript element that you want to populate using the data in
the node.
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.
Prefill OmniScript Elements using DataRaptor

If you launch an OmniScript from a detail page, you can use DataRaptor to prefill any field from that record
into an OmniScript. For example, if an OmniScript is launched from a contact record, then DataRaptor can
automatically populate the name and address of the contact into the form.
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.

company 254
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.
Prefill Repeatable Blocks

Prefill repeatable blocks with data by passing data to the block in an array format.
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.
Data JSON array format example:
"EditBlock1": [
{
"FirstName": "John",
"LastName": "Smith"
},
{
"FirstName": "Jane",
"LastName": "Smith"
}
]
To map Data JSON to a Repeatable Block with a Set Values action:
1. Add a Block or Edit Block to the OmniScript.

2. (Optional) When using a Block, check the Block's Repeat checkbox property.
NOTE
Edit Blocks are inherently repeatable because they store entry values in an array
format.
3. Add Input elements to the Block.

4. Add a Set Values Action to the OmniScript.
5. In the Set Values Action, click Add New Value.
6. In the Element Name field, enter the name of your block element.
7. Click Edit as JSON in the Set Values Action element to edit the JSON directly.

company 255
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": [
{
"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.

company 256
For more information on prefilling elements, see Prefill OmniScript Elements using DataRaptor.
Seed Data Into an OmniScript

Prefill OmniScript fields with data or add hidden nodes to the OmniScript Data JSON using the Seed Data
JSON property in the OmniScript's Setup section.
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 a Default Value for an Element

The Default Value property enables the JSON value of an element to be set to a static value by default and
exists on certain Elements. The Default Value will be overwritten if the Element is prefilled from a
DataRaptor or JSON response. For more information on dynamically prefilling values, see Prefill
OmniScript Elements using DataRaptor.
1. From the OmniScript’s Script Configuration panel, click the Element to open its properties panel.

company 257
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.
Manage OmniScript Data

This section contains information on how to transform, evaluate, and set data in OmniScript. The data is
maintained in an intermediate structure called the data JSON, which is visible to you, the developer, as you
define the OmniScript. Data JSON is not visible to users who run the OmniScript.
Access OmniScript Data JSON with Merge Fields

Enable OmniScript elements and element properties to access data JSON using merge fields. A merge
field is a variable that references the value of a JSON node. For example, if a JSON node
is "FirstName": "John", then the merge field %FirstName% returns John.
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.
Common Use Cases
• 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.
Access the Data JSON

Use existing data JSON in an element property by indicating the use of a merge field.
1. Locate the name of the JSON node in the OmniScript's data JSON.

company 258
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%.
3. Preview the OmniScript to ensure the Merge field works correctly.

company 259
Additional Syntax
This table provides additional syntax examples for nested JSON.
JSON Node Merge Field Syntax Example

"ContactInfo": { Use a colon symbol : to access a nested JSON node.
"FirstName": "John"
} %ContactInfo:FirstName%
"ParentObject": { Use a colon symbol : to access nested JSON nodes and a pipe symbol | to access the index
"NumberMap": [ of the array that value.
1,
2, %ParentObject:NumberMap|3%
3
]
}
"ContactInfoStep": { When a formula exists within a repeatable block, use |n to access the node in which the
"ContactInfoBlock": [ formula exists. Depending upon which node the formula exists in, it will return the correlating
{ value. For more information, see Evaluating Elements in Repeatable Blocks.
"FirstName": "John"
}, %ContactInfoStep:ContactInfoBlock|n:FirstName%
{
"FirstName": "Adam"
},
{
"FirstName":
"Steve"
}
]
}
Set Values in an OmniScript

Set element values in future steps, rename JSON nodes, create dynamic values, and concatenate data by
using the Set Values Action. Action elements either render as a button when in a Step or run remotely when
between steps. Set Values relies on using merge fields to access the OmniScript's data JSON. For more
information on merge fields, see Access OmniScript Data JSON with Merge Fields
Use the Set Values Action to:
• Access and rename data JSON by using merge fields

• Populate Elements with values
• Concatenate Values

company 260
• 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.
Rename Data JSON Nodes

Simplify and rename JSON node names by accessing the values in an OmniScript's data JSON. Data sent
into the OmniScript's data JSON from a parameter, an action's response data, or an element is accessible
by using merge fields. For more information, see Access OmniScript Data JSON with Merge Fields.
To rename a node:
1. From OmniScript Designer, click Preview.

2. Enter in some information and view the OmniScript's data JSON.
3. Locate the JSON node in the OmniScript's data JSON.
6. In the Element Name field, enter the new JSON node name.
7. In the Value field, enter the name of the JSON node using merge field syntax to map it to the new
JSON 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.

company 261
To populate an element:
1. Locate the JSON node in the OmniScript's data JSON.

4. In the Element Name field, enter the name of an Element in a Step that renders after the Set Values
Action.
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.

company 262
6. Preview the OmniScript to ensure the fields populate correctly
Concatenate Values
Create dynamic values by concatenating JSON nodes.

3. In the Element Name field, enter a JSON node or element name.
4. In the Value field, click fx and enter multiple merge fields or a combination of merge fields and literal
values.
Element Name Example Value Syntax Example

FullName =%FirstName% + " " + %LastName%
FullName =%FirstName% + " " + "Smith"
WelcomeGreeting =("Welcome, %FirstName% %LastName%")
5. Preview the OmniScript to test the concatenation.
Set Data with Formulas and Functions

Generate dynamic values by evaluating data with Formulas and using functions to return specific values.
For more information, see OmniScript Functions and Supported Formula Operators.

4. In the Value field, click fx to open the formula editor.
5. In the functions panel, select a function and add any additional data to the formula editor.

company 263
6. Preview the OmniScript to test the function.
To use a formula operator:

4. In the Value field, click fx to open the formula editor.
5. Add static values, or dynamic values using merge fields, and add an operator.
NOTE
There must be a space on either side of an operator for the operation to run correctly.
Element Name Example Value Formula Syntax

MergeValues = %GrossIncome% - %NetIncome%
MergeAndLiteralValues = %GrossIncome% - 5000
LiteralValues =2-2
6. Preview the OmniScript to ensure the operation performs correctly.
Set and Access Nested Data

Set and access nested data by editing the Set Values JSON directly and using specific syntax.

3. In the Element Name field, enter a new JSON node name or element name.
4. Click Edit as JSON in the Set Values Action element to edit the JSON directly.
5. In the elementValueMap JSON node, add a valid JSON value to the node name created in the
Element Name field.

company 264
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.
To access nested data and set it to an element name or JSON node:

3. In the Element Name field, enter a new JSON node name or element name.
4. In the Value field, apply merge field syntax to access the appropriate value. For more information, see
Access OmniScript Data JSON with Merge Fields.
5. Preview the OmniScript to ensure the value maps to the new JSON node correctly.
See Also
• Load Data into OmniScript Elements

Manipulate JSON with the Send/Response Transformations Properties

Specify and transform the input and output JSON of OmniScripts or Integration Procedures with the Send
and Response Transformation properties. The Send properties transform the input; the Response
properties transform the output.
The following table outlines the different transformation options:
Purpose Send/ Send/Response JSON Node Example Path Example

Response Result
JSON Path
Reparenting the node path node {path:{a:b}} {node: {a:b}}
Reparenting the node and adding path node1:node2 {path:{a:b}} {node1:{node2:
a nested node {a:b}}}
Reparenting the node dynamically path %nodename% {path:{a:b}} {node: {a:b}}
using merge field syntax
where the value of nodename is
node
Removing the parent node of an path VlocityNoRootNode {path:{a:b}} {a:b}
object
(Not supported in Integration
Procedures)
Specifying the root node to drill path {path:{a:b}} {path:{a:b}}
down on instead of sending the
entire JSON
To reparent the node of a JSON object:
1. Set the Path to the node you are drilling down on.
2. Enter the new node name into the JSON Node field.
To reparent the node and add a nested node:

company 265
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.
To reparent the node using merge field syntax:
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.
To write to a list item using merge field syntax:
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.
To remove the parent node of an object:
1. Set your Path to the node you are drilling down on.
2. Set the Node to VlocityNoRootNode.
To specify the root node:
2. Leave the JSON Node field blank.
To test the result of your transformation, open the Debug console:
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.
Create Formula Fields in an OmniScript

Create expressions to set calculated values and evaluate data across multiple fields using a Formula or
Aggregate element . For example, if you are accepting information for a qualifying life event you may want
to create a formula that determines if the date entered for the qualifying life event is within thirty days of
today's date.

company 266
For a list of available functions, see OmniScript Functions.
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
Supported Formula Operators

Formula fields in OmniScript support the following operators:
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.

company 267
Table 1. Conversion Functions

Function Name Example Details
ABS(number) ABS(%Friends%) == 6.52534 Returns the absolute value.
BOOLEAN(value) Returns true or false.
CURRENCY(value) Returns value formatted for currency. 12345 would display as
12,345.
INTEGER(value) INTEGER(%Friends%) == 6 Converts the number given into an integer with no decimal
places. Does not round the number up. Also accepts a string.
INTEGER("12.5") == 12
NULL Renders an object's value null.
NUMBER(value) NUMBER(%Friends%) == 128 Converts a string into a number.
POW(number, exponent) POW(%Friends%, 3) == 274.625 Returns exponent value.
RANDOM() RANDOM() Returns a random number between zero and one. This
function is commonly used in A/B testing. The RANDOM()
function does not accept parameters.
ROUND(number, ROUND(%Friends%, 3) == 6.525 Rounds number to certain defined number of decimal places.
decimalPlaces)
Table 2. Conditional Functions

AND(); IF((%reset%="Yes" AND( %reboot Logical operator that performs a function if all
%="Yes")), "Closed", "Escalated") conditions are both met.
COUNTIF(values, COUNTIF(%MyArray%, >10) Returns a count of the number of repeated
expression_or_value) elements if a condition is met.
EQUALS( Field_Name, IF( The EQUALS function is used when comparing a
'Condition') field to a particular value or another field.
EQUALS(%Department%,'401(k)'),
"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.
Table 3. Text Functions

CASE(value, $CASE) CASE(%Name%, UPPER) == "TONY JONES" Changes case based on $CASE
type. $CASE must be LOWER,
CASE(%Name, LOWER) == "tony jones" UPPER, SENTENCE, or TITLE.
CASE(%Name%, SENTENCE) == "Tony jones"
CASE(%Name%, TITLE) == "Tony Jones"

company 268

CONCATENATE(value1, value2, ..., CONCATENATE(%FirstName%, " ", %LastName Concatenates the elements/
valueN) %) == "Tony Jones" strings together into a single
string.
CONTAINS(input_string,value) CONTAINS(%FirstName%, "Tony") == True Evaluates if a value is contained
within a string.
SPLIT(text, splitToken, limit); SPLIT("Tony Jones", " ", 2) == "Tony", "Jones"
STRING(value) STRING(%Friends%) == "6.5" Converts any value into a
String.
SUBSTRING(text, startIndex, SUBSTRING("Substring!", 3, 9) == "string" Extracts the characters from a
endIndex) string between two specified
indexes and returns the value.
Table 4. Date Functions

AGE(dateOfBirth) AGE(%Birthdate%) == 7 Returns an age (in years) with the given date of birth on
today's date. Use the Date element.
AGEON(dateOfBirth, AGEON(%Birthdate%,"07-09-2024") == The age of someone (in years) with the given date of
futureDate) 16 birth on a future date. Use the Date element.
DATE(value) DATE(%DOB%) == Wed Jul 19 1978 Use a Date element. Returns full JavaScript format.
16:00:00 GMT-0700 (PDT)
DATEDIFF(date1, date2) DATEDIFF(%DOB%,%TODAY%) == The difference between 2 dates in days. The value will
13559 always be a positive integer. Use the Date element.
DAYOFMONTH(date) DAYOFMONTH(%TODAY%) == 2 Returns the day of the month. Use the Date element.
DAYOFWEEK(date) DAYOFWEEK(%TODAY%) == 4 Returns the day of the week as an integer. Monday is 1,
Sunday is 7.
HOUR(date) Return the current hour according to local time.
MINUTE(date) Return the current minute according to local time.
MOMENT() MOMENT(%policyStartDate%).add(1, Returns the moment object of Moment.js
'year').subtract(1, 'day')
This can be used to perform complex date formatting,
calculations, manipulation, comparisons, etc. The
MOMENT() function must contain parameters, for
example, MOMENT(NOW()). Appending .calendar() to
this function is a recommended best practice.
MONTH(date) MONTH(%TODAY%) == 9 The month of the year as an integer. Use the Date
element.
NOW() NOW() == Thu Aug 27 2019 16:32:00 Returns current date and time in full JavaScript format.
GMT -0700 (PDT) Milliseconds are always set to 0.
TODAY() TODAY() == Thu Aug 27 2019 00:00:00 Returns today's date. The time is always set to midnight
GMT -0700 (PDT)
YEAR(date) YEAR(%TODAY%) == 2019 Returns the year of the date as an integer. Use the Date
element.

company 269
Table 5. Aggregate Functions

ARRAY(value1, value2, ..., ARRAY(%Child1%,%Child2%, Returns an array of the value of the elements.
valueN)
%Child3%,%Child4%) == [4,3,1,2]
AVERAGE(array) AVERAGE(%Age%) == 2.5 Aggregate: returns the average mean value of the
numbers provided. Use a repeating element.
AVERAGE(value1, value2, ..., AVERAGE(%Child1%,%Child2%, Returns the average mean value of the numbers
valueN) provided.
%Child3%,%Child4%) == 2.5
COUNT(array) COUNT(%Age%) == 4 Aggregate: Returns a count of the number of
repeated elements.
EXISTS(array_or_value, EXISTS([%FirstName%,%LastName Returns true if the given value exists in one or more
expression_or_value) %], "Tony") == true elements. For Aggregate, enter the name of a
repeating element—for example EXISTS(%FirstName
%,"Tony"), where FirstName is repeatable.
MAX(array) MAX(%AGE%) == 4 Aggregate: Returns the largest value in the numbers
provided. Use a repeating element.
MAX((value1, value2, ..., MAX(%Child1%,%Child2%, Returns the largest value in the group of elements
valueN) provided.
%Child3%,%Child4%) == 4
MIN(array) MIN(%AGE%) == 1 Aggregate: returns the smallest value in the numbers
provided. Use a repeating element.
MIN((value1, value2, ..., MIN(%Child1%,%Child2%, Returns the smallest value in the group of elements
valueN) provided.
SUM(array) SUM(%AGE%) == 10 Aggregate: returns the sum of all values in the
repeatable element.
SUM(value1, value2, ..., SUM(%Child1%,%Child2%, Returns the sum of all comma-separated elements
valueN) and values.
Create a Formula or Aggregate in an OmniScript

Run functions against element data with the Formula and Aggregate elements.
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:
DATE(YEAR(%DateElement%), MONTH(%DateElement%), DAYOFMONTH(%DateElement%) +365)
If you would like to set a date one week from today's date, you could do so by using the example formula
below:
DATE(YEAR(TODAY()), MONTH(TODAY()), DAYOFMONTH(TODAY()) +7)
The instructions below explain how to add and configure Formula or Aggregate element to your OmniScript.

company 270
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.

company 271
7. You can test the Formula or Aggregate by clicking the Preview link.
See Also
• Create Formula Fields in an OmniScript

• OmniScript Functions
Create and Update Data from OmniScripts

OmniScripts post data to Salesforce and external databases using OmniScript Action Elements that
integrate OmniStudio DataRaptors, OmniStudio Integration Procedures, external calls, and Apex.
Post Salesforce Data from OmniScripts

Create and update sObjects and external objects from an OmniScript using the DataRaptor Post Action. If
multiple actions are needed, use an Integration Procedure to host the DataRaptor Post Action and handle
the requests.
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.

company 272
Before You Begin

1. Learn about DataRaptor Loads. See DataRaptor Load Overview.
2. Create a DataRaptor Load. See Create a DataRaptor Load.
1. From OmniScript, click Preview.

2. Enter any data you plan to use into the OmniScript. You can prefill elements for testing using the Set
Values Action, Default Value element property, or the Seed Data JSON functionality.
3. Copy the OmniScript's Data JSON.
4. In your DataRaptor, paste your OmniScript's data JSON into the DataRaptor's Input JSON.
5. Map your data JSON nodes to Object fields.
See Also
• DataRaptor or Integration Procedure?

Fill a PDF From OmniScript Using DataRaptor

You can fill a PDF using elements from an OmniScript.
Required Items:
• Adobe Acrobat Pro

• An existing fillable form (either unsecured or you have the password)
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.

company 273
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.
• The PDF can be launched in a Firefox, Safari, or Chrome browser.
1. Prepare your PDF.

2. Upload the PDF to Salesforce as a Document.
What's Next
Create a DataRaptor Interface to Map OmniScript Data to a PDF

After you create the OmniScript and upload your PDF, you must create a DataRaptor to map the
information from the OmniScript to the PDF. See OmniStudio DataRaptors.
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
• Fill a PDF From OmniScript Using DataRaptor

• Add a PDF Action to the OmniScript
Map OmniScript Fields to a PDF

Populate a PDF with OmniScript data by mapping the OmniScript JSON data to the PDF.
Before You Begin

1. In your DataRaptor Interface, click Transforms.

2. Click Input JSON, and paste in your OmniScript's JSON.
3. Click Quick Match and map nodes in your Input JSON to PDF fields.
4. (Optional) Add mappings one at a time by clicking the + symbol, and mapping an Input JSON Path to
a PDF Output Field.

company 274
What's Next
Add a PDF Action to the OmniScript
See Also

Add a PDF Action to the OmniScript

Populate a PDF with OmniScript data using the PDF Action.
NOTE
The PDF Action is not supported in IE 11 browsers.
Before You Begin

Map OmniScript Fields to a PDF
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


company 275
Upload Files and Images in OmniScripts

To upload files in an OmniScript, add a File input element. To upload an image, add an Image input
element. Details about uploads are added to the Files node of the OmniScript's Data JSON.
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.
By default, File and Image elements accept a file size of up to 2GB.
Add a File or Image to OmniScript

Add and configure a File or Image element to enable the upload of files and images. By default, the File
and Image elements accept a file size of up to 2GB.
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

company 276
}
]
File Properties
This page contains information on File element Properties.
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.
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
• Upload Files and Images in OmniScripts

Image Properties
This page contains information on Image element Properties.
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.
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
• Upload Files and Images in OmniScripts

Integrating DocuSign with OmniScript

As a DocuSign user, you can build OmniScripts that fill DocuSign templates and then allow the user to sign
them directly from the OmniScript (DocuSign Signature Action) or email the user a copy of the document to
sign at their convenience (DocuSign Envelope Action).
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.

company 277
Preparing a DocuSign Template for OmniScript

You can fill a DocuSign document using elements from an OmniScript. The DocuSign document can then
be emailed to one or more signers using the DocuSign Envelope Action. The document can also be signed
within the OmniScript using the DocuSign Signature Action.
To prepare a DocuSign template for OmniScript, you must have the following items:
• DocuSign account
• DocuSign for Salesforce account
Linking Your Salesforce Org to Your DocuSign 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.
Preparing DocuSign Documents

Configure DocuSign documents for use with OmniScript.
1. From the DocuSign Admin tab click DocuSign.

DocuSign opens in a new browser tab or window.
2. Click Templates and then click New Template.
3. Add a document and then add a recipient.
4. Select Placeholder as the recipient type and then add a Role for the Placeholder.
5. Select whether the Placeholder needs to sign, receives a copy, or needs to view the document.
6. Add more Placeholders and set a signing order, if necessary.
7. Edit the default email subject and body and click Next.
8. Prepare the form by dragging fields from the palette onto the form. Vlocity supports mapping fields
from an OmniScript to DocuSign Text, Radio Button, and Checkbox fields.
9. Add a Data Label to each field. This label will appear in DataRaptor when you create the
transformation mappings from the OmniScript to the DocuSign document.
Linking a DocuSign Template to Vlocity

Returning to Salesforce, from the Vlocity DocuSign Setup tab, click Fetch DocuSign Templates. All saved
Templates appear in the DocuSign Template List.
Mapping Fields from the OmniScript to the DocuSign Template

To populate a DocuSign template, you define the output JSON of the OmniScript as input to a DataRaptor
transform, which uses that data to populate the template. To compose the output JSON, map data from the
data JSON to the output JSON as follows:

company 278
1. Click an element in the Data Mappings table.

2. Click the Output Path field.
3. Select the corresponding field name on the DocuSign Template.
4. Repeat for all remaining fields to map.
5. When you are finished, inspect the Output JSON section to make sure all fields on the Template have
been mapped.
After completing this step, you can create either a DocuSign Envelope Action or DocuSign Signature Action
(v12 only) in your OmniScript.
Populating a DocuSign Template Using DataRaptor Transform

After creating an OmniScript that collects the data required by your DocuSign template, define a
DataRaptor Transform that populates the template, as follows:
1. On the Vlocity DataRaptor tab, click New.

2. For Interface Type, select Transform.
3. When prompted, specify a unique name for the transform, and specify settings as follows:
• Interface Type: Transform
• Input Type: JSON
• Output Type: DocuSign
• Target Output DocuSign Template Id: Choose the template that your OmniScript is designed to
populate.
Save your settings.
4. (Optional) For ease of mapping, copy the data JSON from your OmniScript and paste it into the Input
JSON pane in the DataRaptor Designer.
5. On the Outputs tab, map the fields from the output JSON of your OmniScript to the input fields from
the DocuSign template.
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.
Using the DocuSign Signature Action to Sign Documents From Within an

OmniScript
After preparing the DocuSign Template and mapping the fields from the OmniScript to the Template using
DataRaptor, create a DocuSign Signature Action in the OmniScript. When the action runs, a modal opens
containing the prefilled document. The user must take an action on the document before continuing the
OmniScript. They can either sign or decline to sign the document.

company 279
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.
To create a DocuSign Signature Action:
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='),

company 280
searchStr.length);
searchStr = searchStr.substring(searchStr.indexOf('=') +
1,searchStr.length);
if(searchStr === 'signing_complete') {

domClass = document.getElementById('signing_complete');
domClass.style.display = 'block';
} else {
domClass = document.getElementById('signing_failed');
domClass.style.display = 'block';
}
_window.parent.postMessage(searchStr, '');_*
});
Using the DocuSign Envelope Action to Email Documents for Signature

After you finish preparing the DocuSign Template and mapping the fields from the OmniScript to the
Template using DataRaptor, you can create a DocuSign Envelope Action in the OmniScript. When the
action runs, a DocuSign Envelope containing the prefilled document is emailed to one or more recipients for
signing or reviewing.
To create a DocuSign Envelope Action:
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.
Before You Begin

Learn about DataPacks. See Data Migration with OmniStudio DataPacks.

company 281
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.
Before You Begin

1. Learn about DataPacks. See Data Migration with OmniStudio DataPacks.
2. Export OmniScripts from another org. See Export OmniScripts.
1. From the OmniScripts home tab, click Import.

2. Click Browse, and select your DataPack.
3. Click Done, and follow any steps that appear.
4. Open your imported OmniScripts.
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.
1. From your OmniScript, click New Version.

2. Enter your new OmniScript and begin to alter your new version of the script.
See Also
• Create an OmniScript
• Access OmniScript Designer
• Set Up an OmniScript

company 282
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.
To implement this feature, you create the following components:
• An email template containing the required merge fields

• An Integration Procedure containing a remote action that invokes the email-sending method, passing in
the required parameters
• In the OmniScript, an Integration Procedure action that calls the email Integration Procedure
The following sections provide details about creating the required components.
Creating the Email Integration Procedure

To send the email, create an Integration Procedure containing a remote action with the following settings:
• Remote Class: DefaultOmniScriptSendEmail

• Remote Method: emailOmniScriptLink
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.

company 283
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.
Specifying the Integration Procedure Action

In the OmniScript, at the point where you want the email sent, add an Integration Procedure action with the
following settings:
• Integration Procedure Key: Email_Action

• Extra Payload:
• Key: contextId
• Value: the Id of the Contact to whom you want to send the email.
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.
Creating the Email Template

Define an email template containing the desired text. The email template type must be Custom (without
using Letterhead). In the template, specify the URL that links to the OmniScript using the following format:
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%
Embed FlexCards in an OmniScript

Embed a FlexCard Lightning Web Component in an OmniScript by using the Custom LWC Element.
FlexCards can receive data from the OmniScript and perform any action available in the FlexCard.

company 284
Before You Begin

1. Ensure your FlexCard includes OmniScript support. See Enable OmniScript Support on a FlexCard.
2. (Optional) Configure a FlexCard to receive data from OmniScript. See Pass Data from an LWC OmniScript to an Embedded
FlexCard.
1. In an OmniScript, drag the Custom LWC element into a Step.

2. In the Custom LWC's Lightning Web Component Name property, enter the FlexCard component's
name and prepend cf to the beginning of the name. For example, a FlexCard named Account Card
must be entered as cfAccountCard.
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.
Property Description Example FlexCard Configuration

Name Option
record-id Pass a record id into a FlexCard using the record- See Pass the RecordId from an
id property. FlexCards use record ids to perform OmniScript to Run a Query on a
data queries. FlexCard
parent- Pass a parent object containing parent attributes See Pass a Parent Object from an
attribute such as Parent.id into the FlexCard. Use merge LWC OmniScript to Run a Query on
fields in FlexCard queries and fields. a FlexCard

company 285
Property Description Example FlexCard Configuration

Name Option
parent-data Map data to FlexCard fields directly without See Map Data from an LWC
running a query. The parent-data property is a OmniScript to an Embedded
AND boolean that FlexCards uses to determine FlexCard
whether to run a query or parse over a set of
records records.
4. In Property Source, using merge field syntax, enter one of these options based on your property
name:
Property Name Property Source

record-id Enter a JSON node that contains. For example, to pass a record id stored in the ContextId node, enter
%ContextId%.
parent-attribute Enter a JSON node containing an object.
parent-data Set parent-data's property source to true.
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
OmniScript ReadMe Reference

This page lists the Lightning web components ReadMes available for OmniScripts. Extend Lightning web
components to add custom behavior and styling. For information on customizing OmniScript LWCs see
Create a Custom Lightning Web Component for OmniScript. For information on configuring OmniScript
elements, see OmniScript Element Reference.
Download the HTML, CSS, and ReadMe files for every available Lightning web component in one file.

company 286
OmniScripts LWC ReadMes

Download
Base Component ReadMes

LWC OmniScript elements extend the base components in this table.
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.

company 287
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
Actions on an account card might include:
• 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.

company 288
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.
Design and Layout

Build a FlexCard by dragging elements onto its canvas. Add data fields, action, data tables, charts, menus,
icons, images, and more. See Add Elements to a FlexCard.
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.

company 289
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)
FlexCard Designer Highlights

With the FlexCard Designer, you can:
• Build your FlexCard on a wide and adjustable Canvas.

• Drag customizable elements from the Build panel onto the Canvas.
• Adjust the width of any element along a 12-column horizontal grid.
• Use the Action element to launch an OmniScript or Flyout, and trigger Custom or Pubsub Events, and
more.
• From the Style panel, customize the look and feel of your FlexCard. Style elements using a GUI to
choose the colors of texts, borders, and backgrounds, change the size of fonts and entire elements, and
make elements responsive.
• Create a new FlexCard and configure your data source with a step-through wizard.
• Use In-Product Help to learn about a property or an element without leaving the Designer.
• Configure FlexCard-wide settings from the Setup panel, such as required permissions, event listeners,
session variables, and more.
• Configure metadata values for your generated LWC and update its component SVG icon with the
Publish Options feature.
• Download on and off-platform FlexCard LWCs.
• Debug your FlexCard by viewing its data JSON and the response and request logs for its actions and
events.
• Run FlexCards outside of Salesforce with OmniOut for FlexCards.
What's Next
Explore the FlexCard Designer. See Get to Know the FlexCard Designer.

company 290
Get to Know the FlexCard Designer

Get to know how the different parts of the FlexCard Designer work to build rich interfaces relevant to your
customer's context. 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.
See 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

company 291
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.

company 292
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.

company 293
Build Panel (3)

company 294
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.

company 295
Properties Panel (4)

company 296
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.

company 297
Style Panel (5)

company 298
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.

company 299
Setup Panel (6)

company 300
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.

company 301
In-Product Help (8)
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.
Get Started with FlexCards

FlexCards provide a set of components for building UI components and applications on the Salesforce
platform. Here are some key resources to help you navigate the FlexCard Designer and guide you through
common tasks.
• 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

company 302
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.
Build a FlexCard with the FlexCard Designer

With the FlexCard Designer create, build, design, test, and activate a FlexCard before publishing it to a
Lightning or Community page. Use a drag interface with WYSIWYG editing to preview while you build
dynamic context-specific user interfaces for customer interactions.

company 303
FlexCard Designer Workflow Diagram
Create a New FlexCard

• Step through a four-step configuration wizard to create a new FlexCard. See Create a New FlexCard.
• Configure basic settings such as title, name, author, description, and optionally enable the ability to
embed the FlexCard inside another FlexCard.
• Select and configure a data source, and where applicable, add test data to populate fields and preview
the FlexCard at run time.

company 304
Configure Setup Options

Configure card-wide options, such as adding an event listener, adding session variables, disabling record
looping, limiting user access, and updating data source settings, and more. See Set Up a FlexCard in the
FlexCard Designer.
Add, Configure and Style Elements
• 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.
Configure Publish Options

Define metadata values and set a custom component SVG icon for the generated FlexCard LWC. See
Configure Publish Options on 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.
Create a New FlexCard

Configure basic settings and data source options when creating a new FlexCard in the FlexCard Designer.
After creating a new FlexCard you can update additional options and start building your user experience.
Configure Basic Settings
1. From the FlexCards tab, click New.

2. In the New FlexCard step, enter the Name of your FlexCard following required naming conventions.
See FlexCard Naming Conventions.
3. Select a Theme for your FlexCard. Select Lightning to use SLDS (Salesforce Lightning Design
System), or Newport to use the Newport Design System.

company 305
NOTE
You cannot change the theme once set. You will need to clone the FlexCard to change
the theme.
4. Update the Author.
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.
Configure Data Source

1. In the Select Data Source Type step, select a data source type to retrieve data from a Salesforce
object or an external database. See FlexCards Data Source Reference.
2. Click Next.
3. In the Select Data Source step, configure the data source properties. For example, if you selected a
DataRaptor as your data source type, select an active DataRaptor, configure input parameters, and
additional options. See FlexCards Data Source Properties.
4. Click Next.
Enter Test Input Parameters

1. To enter a test parameter as a key/value pair:
• If a Run-Time Variable has been added from the previous Select Data Source Type step, add the
Test Value.
• For each new variable, click + Add, and enter these properties:
a. Enter a Run-Time Variable, such as recordId. See FlexCards Context Variables.
b. Enter a Test Value, such as an Account record Id.
2. To drill down through the JSON data to pass a specific dataset to the FlexCard, enter the JSON path in
the Result JSON Path field. For example, enter Account.Cases to return data from the Cases node
only.
3. Click Fetch.
4. View a Table of the returned Test Response.
5. (Optional) Click JSON to view the returned results as JSON.
6. Click Save.

company 306
What's Next
Configure additional options. See FlexCard Setup Reference.
See Also
• Add Elements to a FlexCard
• Preview a FlexCard
• Activate a FlexCard
• Add a FlexCard to a Lightning Page
• Add a FlexCard to a Community Page
Add an Action to a FlexCard

Add an action to a FlexCard to launch or update an OmniScript, navigate to a web page or application,
display a flyout, fire an event, or update data field values. For example, add an action that when clicked,
displays the contact information, in a window, for the Account page the FlexCard is on.
See FlexCards Actions Reference.
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.

company 307
What's Next
(Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
Add a Click Event to a FlexCard Element

Enable an element on a FlexCard to perform an action when clicked. Supported elements include Image,
Block, Icon, and Toggle.
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.
FlexCards Actions Reference

Select from multiple ways to execute an action from a FlexCard. Create an action to launch an OmniScript,
navigate to a web page or application, display a flyout, fire an event, and more.
See Add an Action to a FlexCard.
Action Type Description Reference

Name
Card Perform Card level actions, such as reload, update • Add an Action to Update a Data Source on a FlexCard
datasource, set values, remove, and select cards. • Add an Action to Update Field Values on a FlexCard
• Add a Reload Action to a FlexCard
• Add a Remove Action to a FlexCard
• Select Items on a FlexCard to Update an OmniScript
Custom Event Fire a Custom Event to notify the parent FlexCard Trigger a Custom Event from an Action on a FlexCard
of an event occurring.
Flyout Display additional information from a Child Card, Launch a Flyout from an Action on a FlexCard
OmniScript, or Custom LWC in a window or
popover.
Navigate Add actions directly on a card by selecting a Target Navigate from a FlexCard with the Navigate Action
URL or a PageReference Type that enables
navigation within Lightning Experience, within
Communities, or to an external web address
OmniScript Launch an OmniScript from a FlexCard. Launch an OmniScript from a FlexCard
PubSub Event Fire a PubSub Event to notify another component Trigger a Pubsub Event from an Action on a FlexCard
on a page or application of an event occurring.
Update Update an OmniScript from a FlexCard embedded Update an OmniScript from a FlexCard
OmniScript as a custom LWC in an OmniScript.

company 308
See Also
• FlexCards Action Properties
• FlexCards Action Style Properties
FlexCards Action Properties

Action element properties are configurable from the Properties panel in the FlexCard Designer when you
select an Action element. With the Action element, create an action to launch an OmniScript, navigate to a
web page or application, display a flyout, fire an event, and more.
See FlexCards Actions Reference. See Add an Action to a FlexCard.
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:
• Action > Label

• Card Action > Set Values > Value
• Event Action > Input Parameters > Value
Common Action Type Properties

These properties are shared by all Action Types.
Property Description Reference

Action Type Select the type of action to execute. FlexCards Actions Reference.
Conditions Add a condition that must be met for the element to display. Add Conditions to a FlexCard
Element
Display As Button Check to display the action as a button. n/a
Element Name The name of the element as seen on the canvas. Used to FlexCard Naming Conventions
distinguish one element from another as you build your FlexCard
in the designer. Is used only within the designer.
Enable Tracking Enable click-based event tracking through OmniAnalytics. Track Enable Tracking on a FlexCard
the UI Action event.
Hide Icon Check to hide the icon and only show the label. n/a
Icon Enter the name of the icon, such as utility:down, or click n/a
into the field to search for an icon.
Label Enter a visible label for the element. n/a
Show Only Icon Select to show an icon without a label. n/a
Variant Select from predefined SLDS styles to change the appearance of n/a
the element.

company 309
Card Action
These properties are unique to the Card Action.
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.
Card Action Types

This table lists descriptions for the available Card Action Types.
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.
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.
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.

company 310
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.
Property Description Target

Action Name Enter the name of the action. App
Api Name Enter the API name of the app. App
App Target The app that you’re navigating to. Pass either the appId or App
appDeveloperName to the appTarget.
App Type The standard or custom app available from the App Launcher. App
Article Url The value of the urlName field on the target Knowledge Article
KnowledgeArticleVersion record. The urlName is the article's
URL.
Community Page Name The unique name of the Lightning community page. The value for Community Named Page
name is the API Name value for a supported page.
Component Name The Lightning component name in the format Component
namespace__componentName.
Custom Tab Name The unique name of the custom tab. Navigation Item
Input Parameters Enter parameters to pass contextual data to the action as key/ Component, Login,
value pairs. Navigation Item
Object API Name The API name of the standard or custom object. For custom Object
objects that are part of a managed package, prefix the custom
object with ns__, where ns is your org's namespace.
Open Target In Select whether to open the target page in the current window or a All
new tab/window.
Page Name The unique name of the page. Named Page
RecordId Enter the record Id of the record to navigate to. App
Record Object API Name The API name of the record’s object. Record
Relationship Object API The API name of the object that defines the relationship. Record Relationship
Name
Target Select the PageReference type. All
Target Action Enter a valid action name to call. Login, Object, Record,
Record Relationship
Target ArticleType Enter the API name of the article type. Knowledge Article
Target Id Select a ContextId from the data source. Record, Record Relationship
Target Relationship The API name of the object’s relationship field. Record Relationship
URL The URL of the page you’re navigating to. Web Page

company 311
OmniScript Action
These properties are unique to the OmniScript Action. See Launch an OmniScript from a FlexCard.
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.
Update OmniScript Action

These properties are unique to the Update OmniScript Action. See Update an OmniScript from a
FlexCard.
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.
Navigate from a FlexCard with the Navigate Action

Navigate to an external web address, or within Lightning Experience, Lightning communities, or the
Salesforce mobile app from a Navigate Action element on a FlexCard. For example, allow a user to
navigate to a Policy record page by clicking an action element on a FlexCard that lists Account Policies.
NOTE
To create an email link, see Create an Email Link from a FlexCard Navigation Action.
1. From the FlexCard Designer, drag an Action element into a state.

2. Select Navigate from the Action Type dropdown.
3. Select a page reference type from the Target dropdown.
4. To configure settings and options unique to your selected Target, see Navigate Action.
5. (Optional) To open the target page in a new tab or window, select New Tab/Window from the Open
Target In dropdown.
6. (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.

company 312
Create an Email Link from a FlexCard Navigation Action

Enable your user to send an email from a link. Create an email link with the Navigate action element to
open your user's default mail program.

2. Select Navigate from the Action Type dropdown.
3. Select Web Page from the Target dropdown.
4. Enter a mailto link in the URL field. For example, enter mailto:janedoe@acme.org. See All
About mailto: Links.
5. To configure settings and options unique to your selected Target, see Navigate Action.
Target In dropdown.
Properties.
What's Next
Properties.
Launch a Flyout from an Action on a FlexCard

Create a flyout to display additional information when a user clicks an action on a FlexCard. For example, a
FlexCard that displays Account information can display the Primary Contact's name and email address in a
flyout.
CAUTION
When embedding a component, confirm that it isn’t called multiple times. See Fix Cyclic
Redundancy When Embedding FlexCard Components.

2. Select Flyout from the Action Type dropdown.
3. From the Flyout Type dropdown, select Child Card, Custom LWC, or OmniScripts as the type of
component to display inside the flyout.
4. Click into the Flyout field and select a component to display in your flyout.
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.

company 313
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.
Properties.
What's Next
Properties.

company 314
Launch an OmniScript from a FlexCard

Launch an Angular or LWC OmniScript from an OmniScript Action element on a FlexCard. For example,
launch a form that updates Account information based on the account Id passed from the FlexCard to the
OmniScript.

2. Select OmniScript from the Action Type dropdown. See FlexCards Actions Reference.
3. Click into OmniScript and select the OmniScript to launch.
4. (Optional) From the VisualForce Page dropdown, select a VisualForce page to display the
OmniScript. For example, if you have a custom template for your OmniScript, select the custom page
you created.
5. (Optional) To update the OmniScript's layout, select Lightning or Newport from the Layout Type
dropdown.
6. In the Context ID field, enter the sObject's context Id associated with your OmniScript. For example, if
your OmniScript updates account information, your context Id is an account record Id variable from the
data source, such as {AccountId}.
7. (Optional) If you selected an LWC OmniScript, from the Console Tab Label field, enter the visible label
of the console tab. For example, Update Account.
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:

company 315
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.
Properties.
What's Next
Properties.
Launch an OmniScript from an OmniScript Action on a FlexCard in Lightning

Experience
On a Lightning Experience page, launch an OmniScript from an OmniScript Action on a FlexCard. Launch
an LWC or an Angular OmniScript.
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
• Reload a FlexCard After Updating an LWC OmniScript in a Flyout
Launch an LWC OmniScript from an OmniScript Action on a FlexCard in a

Community
Launch an LWC OmniScript from an OmniScript Action on a FlexCard in a Community.
Before You Begin

Add and configure the OmniScript Action element on a FlexCard. See Launch an OmniScript from a FlexCard.
1. Create a community page with the URL /lwcos. Enter any name as the Community page name. See
Creating Custom Pages with Community Builder.

company 316
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.
Update an OmniScript from a FlexCard

Create an action that updates an OmniScript's data JSON from the FlexCard embedded in the OmniScript.
You can embed a FlexCard inside an OmniScript as a Custom LWC.
See Embed FlexCards in an OmniScript.
Example 1. Example: Suspend Mobile Device Plan

Let's say you want to build a FlexCard that enables a customer to start the process to suspend their mobile
device plan.
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.
Before You Begin

• Create an OmniScript. See Create an OmniScript.

company 317

2. Select Update OmniScript from the Action Type dropdown.
3. (Optional) To point to a specific data node in the OmniScript JSON, click into the Parent Node field
and a node from the list of merge fields or enter the data node manually.
For example, from the example above enter data to point to the parent node listing all records.
4. To pass the data to update, click + Add New next to Input Parameters.
a. In the Key field, enter the name of the field to update. For example, in the above example, enter
records.
b. In the Value field, enter the new value from the FlexCard's data source. For example, in the above
example, enter the {records} context variable to pass all Asset records. See FlexCards Context
Variables.
Properties.
6. To style your action element, click Style to open the Style panel, and see FlexCards Action Style
Properties.
7. Enable OmniScript Support:
a. Click Setup to open the Setup panel.
b. Select OmniScript Support.
Download a Sample Update OmniScript Action DataPack

Download a sample DataPack that prefills data on an OmniScript when a user clicks the Update Action on
a FlexCard embedded in the OmniScript. See Download a Sample Update OmniScript Action DataPack.
What's Next
Embed the FlexCard inside an LWC OmniScript. See Embed FlexCards in an OmniScript.
See Also
Download a Sample Update OmniScript Action DataPack

Download a sample Update OmniScript DataPack to import into your org. Create an action that updates an
LWC OmniScript's data JSON from the FlexCard embedded in the OmniScript.
See Update an OmniScript from 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.

company 318
Download and Import the DataPack
1. Download the OmniStudio for Vlocity DataPack here: demoPrefillUpdateOmniScriptAction.zip.
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.
Download the OmniStudio DataPack here: demoPrefillUpdateOmniScriptAction-OmniStudio.zip.
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.
2. Import the DataPack. See Import a FlexCard.

3. If you didn't activate the FlexCard or OmniScript during the import process:
1. From the FlexCards home tab, click the demoPrefillUpdateOSActionFlexCard FlexCard, select
the checkbox, and click Activate.
2. From the OmniScripts home tab, click the demoPrefillUpdateOmniScriptOS OmniScript to open
the LWC OmniScript Designer, and click Activate.
4. Click Preview in the OmniScript Designer.
See Also

Select Items on a FlexCard to Update an OmniScript

Enable your users to select from one or more items on your FlexCard with the Select Cards action. When
the user clicks a Select Cards action, it fires the selectcards_{listname} event and the selected card is
added to an array. The card is a record item displayed on the FlexCard. Create an event listener that listens
for the event and executes an Update OmniScript action to update the OmniScript's data JSON with the list
of selected cards.
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.

company 319
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.
2. Select Card from the Action Type dropdown.

3. Select Select Cards from the Type dropdown.
4. In the Selected Cards List Name, enter a name of the array to add the selected card records to.
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.

company 320
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}.
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.

company 321
If you entered a data field in Selectable Field, instead, see Step 6.

11. Click Activate.
12. Embed your FlexCard inside an OmniScript as a Custom LWC. See Embed FlexCards in an
OmniScript.
What's Next
Style your action element. See FlexCards Action Style Properties.
Trigger a Custom Event from an Action on a FlexCard

Trigger a Custom Event from an Action element on a child FlexCard or another element to notify the parent
FlexCard of the event occurring. Custom Events are used to communicate between a child and its parent,
whether it's between a child FlexCard and its parent, or between an element and the FlexCard it's on.
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.
See Communicate with Events.

2. Select Event from the Action Type dropdown.
3. Select Custom from the Event Type dropdown.
4. Enter the name of the event in the Event Name field.
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.

company 322
6. (Optional) To enable the event to bubble up through the DOM, select Bubbles. See Configure Event
Propagation.
a. Enter a variable name in the Key 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.
Properties.
9. Configure the event listener that performs an action when the event is fired. See Add an Event Listener
to a FlexCard.
Download a Sample Custom Event DataPack

Download a sample FlexCard DataPack with a configured Custom Event Action. See Download a Sample
Custom Event DataPack.
Download a Sample Custom Event DataPack

Download a sample Custom Event DataPack to import into your org. Trigger a Custom Event from an
Action element on a child FlexCard or an element to notify the parent FlexCard of the event occurring.
See Trigger a Custom Event from an Action on 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
• A child FlexCard, demoChildFlexCardCustomEvent, with an Action element that triggers a Custom

Event, named triggerparent, that passes a parameter to the parent FlexCard listening for the event.
NOTE
Activate the child FlexCard to see it in the parent.
• A parent FlexCard, demoParentFlexCardCustomEvent, with the following features:

• A Field element populated from an SOQL Query data source.
• An Event Listener configured in the Setup panel listens for the triggerparent custom Event from
the child FlexCard.

company 323
Import DataPack
1. Download the OmniStudio for Vlocity DataPack here: demoParentChildCustomEvent.json.
NOTE
Download the OmniStudio DataPack here: demoParentChildCustomEvent-OmniStudio.json.
NOTE
installed.

3. If you didn't activate the demoChildFlexCardCustomEvent FlexCard during the import process, from
the FlexCards home tab, click the FlexCard name, select the checkbox, and click Activate. The child
FlexCard must be active to view inside a parent.
4. Click the Trigger Parent action element on the demoParentFlexCardCustomEvent FlexCard to see
the Custom Event in action.
See Also

Trigger a Pubsub Event from an Action on a FlexCard

Trigger an event from an action element to notify another component on a page or application of the event
occurring. For example, update a list of products on one FlexCard from a filter on another FlexCard.
See Communicate Across the DOM.
Example 2. Example: Update Product List

Let's say you want to create a Lightning page that displays a filterable list of products. You'll need two
FlexCards: one to display the products and has an event listener, and the other to display the filters that can

company 324
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.

2. Select Event from the Action Type dropdown.
3. Select Pubsub from the Event Type dropdown.
4. To update the channel in which the event posts, enter a Channel Name, By default, the channel name
is the FlexCard name.
5. Enter the name of the event in the Event Name field.
IMPORTANT
Don’t use these reserved names: reload, updatedatasource, remove.
a. Enter a variable name in the Key field.
Properties.
8. Configure the event listener that performs an action when the event is fired. See Add an Event Listener
to a FlexCard.
Download a Sample Pubsub Event DataPack

Download a sample FlexCard DataPack with action elements configured to trigger pubsub events, and an
event listener to listen for the events. See Download a Sample Pubsub Event DataPack.
Download a Sample Pubsub Event DataPack

Download a sample Pubsub Event DataPack to import into your org. Trigger an event from an Action
element to notify another component on a page or application of an event occurring.
See Trigger a Pubsub Event from an Action on 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.

company 325
• 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.
1. Download the OmniStudio for Vlocity DataPack here: demoPubsubEvent.json.
NOTE
Download the OmniStudio DataPack here: demoPubsubEvent-OmniStudio.json.
NOTE
installed.

3. From the FlexCards home tab, click the demoPubSubEvent to open the FlexCard Designer, and click
Preview. From here you can click actions to test events.
See Also

Add an Action to Update a Data Source on a FlexCard

With a Card Action, create an action that changes the data source, or updates parameters of an existing
data source. For example, create an action that updates the pagination limits on a list of returned records.

company 326

3. From the Type dropdown, select Update Data Source.
4. Select a data source type from the Data Source Type dropdown.
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.
5. To configure a new data source, see Configure a Data Source on a FlexCard.

6. To update parameters from an existing data source, enter new Parameters or update values.
For example, in a SOQL Query with a limit set to {Params.limit}, update the Params.limit value
from 10 to a lower number to show fewer records at a time.
Properties.
What's Next
Properties.
Add an Action to Update Field Values on a FlexCard

With a Card Action, create an action that updates specific field values on a FlexCard. For example, allow
your customer service reps to update the status of a case to closed when the case is resolved.

3. From the Type dropdown, select Set Values.
4. To add the fields to update, in the Set Values section, click + Add New.
5. In the Key field, enter the name of a field returned from a data source.
6. In the Value field, enter a new field value as a string or merge field, such as New Value or {Name}.
Properties.
What's Next
Properties.
Add a Reload Action to a FlexCard

With a Card Action, create an action that reloads a FlexCard. For example, create a FLexCard that listens
for an event from another FlexCard and reloads itself when the event is fired.
See Add an Event Listener to a FlexCard.

company 327

3. From the Type dropdown, select Reload.
Properties.
What's Next
Properties.
Add a Remove Action to a FlexCard

With a Card Action, create an action that removes a specific record on a FlexCard or removes the entire
FlexCard. The data record is only removed from the FlexCard and not from the database it's pulled from.
The FlexCard is only removed from the page it's viewed from, and not permanently deleted.

3. From the Type dropdown, select Remove.
4. To remove a specific record, create an Event Listener, and enter a Record Index. See Add an Event
Listener to a FlexCard.
Properties.
What's Next
Properties.
Add Elements to a FlexCard

Build a FlexCard in the FlexCard Designer by dragging data fields, states, actions, and other elements from
the Build panel onto the canvas. Each element can be styled and properties configured within the designer.

company 328
Figure 12. FlexCard Structure Inside FlexCard Designer

company 329
Before You Begin

1. Create a FlexCard, and configure basic settings and a data source. See Create a New FlexCard.
2. Configure Setup options as needed. See FlexCard Setup Reference.
3. Learn how element sizing and responsiveness works in the FlexCard Designer. See FlexCards Element Responsiveness.
Add, Configure, and Style an Element

1. From the FlexCards tab, click a version of a FlexCard to open the FlexCard Designer.
2. (Optional) To adjust the width of the canvas while building your FlexCard, select a size from the canvas
size dropdown. See FlexCards Element Responsiveness.
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.

company 330
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.

company 331
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.
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
See Also
• Define Metadata Values from the FlexCard Designer

company 332
• Add a Custom Component SVG Icon to a FlexCard

FlexCards Elements Reference

Select from a number of elements to add to your FlexCard to build your interactive customer interface. Add
elements such as data fields, actions, states, data tables, and more. See Add Elements to a FlexCard.
Element Element Description Element Properties Reference

Name
Action Renders text or a button that executes an action when clicked. See Add FlexCards Action Properties
an Action to a FlexCard.
Block Enables grouping elements inside a collapsible container. See Group FlexCards Block Properties
Elements Inside a Block on a FlexCard.
Chart Displays data as a chart. See Add a Chart to a FlexCard. FlexCards Chart Properties
Custom LWC Embeds a Custom LWC inside a FlexCard state. See Embed a Custom FlexCards Custom LWC Properties
LWC Inside a FlexCard.
Datatable Creates a tabular structure from the data provided. See Add a Datatable FlexCards Datatable Properties
to a FlexCard.
Field Displays the output from a data field. See Add a Field to a FlexCard. FlexCards Field Properties
FlexCard Embeds a FlexCard inside a state. See Embed a Child FlexCard Inside FlexCards Child FlexCard Properties
a FlexCard.
Icon Displays a custom or Salesforce SVG icon. The icon can be linked to an FlexCards Icon Properties
action. See Add an Icon to a FlexCard.
Image Displays a custom image from a given URL. Upload an image, use an FlexCards Image Properties
image from your org's library, or use an external source. The image can
be linked to an action. See Add an Image to a FlexCard.
Menu Displays a list of actions as a dropdown menu. See Add a Menu to a FlexCards Menu Properties
FlexCard.
State Adds a state to a FlexCard. See Add a State to a FlexCard. FlexCards State Properties
Text Renders text and parses merge fields with a rich text editor. See Add a FlexCards Text Element Properties
Text Element to a FlexCard.
Toggle Trigger an action when a user selects a Toggle element. The value is FlexCards Toggle Properties
sent as a parameter to the action as true or false, or a comma-separated
list of user-selected options. See Trigger Actions with the Toggle
Element on a FlexCard.
Group Elements Inside a Block on a FlexCard

Combine logical groups of elements inside a collapsible container with the Block element on a FlexCard.
For example, group an Account's basic information together, and separately, group the account's Contact
information together.
Add Block Element
1. From the FlexCard Designer, drag a Block element from the Build panel into a state on the canvas.
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.

company 333
NOTE
Beginning Summer '21, Label supports concatenated strings. Combine plain text
and supported merge fields. For example, Update {AccountName}.
• (Optional) To show the block collapsed by default, click Collapsed By Default.

4. (Optional) To enable a click event on the block, click + Add Action. To configure action properties, see
FlexCards Action Properties.
FlexCard Element.
Add Elements Inside the Block

1. To add an element from the Build panel, drag a field from the Fields list, or an element from the
Elements list into the block element.
For example, drag address related Account fields into a block element, such as BillingCity,
BillingCountry.
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
See Also
• FlexCards Block Properties
FlexCards Block Properties

Block element properties are configurable in the Property Panel when you select a Block element in the
FlexCard Designer. With the Block element, combine logical groups of elements in a collapsible container.
See Group Elements Inside a Block on a FlexCard.

Add Action Make the element a clickable action. Add a Click Event to a
FlexCard Element
Collapsed By If selected, the block element is collapsed by default. n/a
Default
Collapsible Makes the block collapsible, hiding its content. n/a

company 334

Element
Element Name The name of the element as seen on the canvas. Used to distinguish one FlexCard Naming Conventions
element from another as you build your FlexCard in the designer. Is used
only within the designer.
Label Displays a visible label for the collapsible block element. n/a
See Also
Add a Chart to a FlexCard

Display data on a FlexCard as a chart with the Chart element. Select from bar, pie, donut, line, and radar
chart types.
Configured Bar Chart
2. Drag a Chart element from the Build panel into a state on the canvas.
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.

company 335
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.
FlexCard Element.
What's Next
See Also
• FlexCards Chart Properties
FlexCard Chart Element Aspect Ratio

You can adjust the proportions of a Chart element with the Aspect Ratio, Maintain Aspect Ratio, and Chart
Height features in the FlexCard Designer. Set the Aspect Ratio to adjust height relative to the width. Set
fixed proportions. Or, override the aspect ratio and set a fixed height.
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.

company 336
Default Aspect Ratio on a 7-column wide chart
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.
Aspect Ratio 2 on a 7-column wide chart
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.

company 337
Aspect Ratio .5 on a 7-column wide chart
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.
Aspect Ratio Maintained on a 7-column wide chart
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.

company 338
Aspect Ratio disabled, fixed height set on a 7-column wide chart
Here is a summary of how width and height are determined with each feature:
Feature Width Height Examples

Aspect Full width of the element container X-times the default • 1 = Default width (full width of the space the
Ratio (as determined by the number of height. X is determined element occupies on the canvas) and
columns the element occupies on by the ratio entered. proportionate height
the canvas in the designer) • 2 = Default width, and about half the default
height
• .5 = Default width, and about twice the
default height
Maintain Full width of the element container X-times the width. X is • If Aspect Ratio is 1, the width and height are
Apect (as determined by the number of determined by the ratio the same.
Ratio columns the element occupies on entered. • If Aspect Ratio is 2, the height is half the
the canvas in the designer) width.
• If Aspect Ratio is .5, the height is twice the
width.
Chart Full width of the element container The number, in pixels, 300, or 300px.
Height (as determined by the number of entered in this field.
columns the element occupies on
the canvas in the designer)
See Also
• Add a Chart to a FlexCard

• FlexCards Chart Properties
FlexCards Chart Properties

Chart element properties are configurable in the Property Panel when you select a Chart element in the
FlexCard Designer. With the Chart element, display data as a chart and enable users to perform actions
within the chart. See Add a Chart to a FlexCard.

company 339

Aspect Ratio Enter a number to set the height relative to the width. For example, if the Aspect FlexCard Chart Element
Ratio is 2, and the default width and height is 600px and 300px, the width remains Aspect Ratio
the same and the height is half the default height at 150px.
Chart Height Manually set the height of the chart, which overrides the Aspect Ratio and is FlexCard Chart Element
visible when the Maintain Aspect Ratio feature is disabled. Aspect Ratio
Color Palette Select a predefined color scheme. n/a
Conditions Add a condition that must be met for the element to display. Add Conditions to a
FlexCard Element
Cutout Enter the size of the donut chart hole by percentage. n/a
Percentage
Element Name The name of the element as seen on the canvas. Used to distinguish one element FlexCard Naming
from another as you build your FlexCard in the designer. Is used only within the Conventions
designer.
Hide Header Show or hide the chart's title. n/a
Label Node Select the field whose values are used to categorize the data, such as Name of n/a
Accounts.
Maintain Aspect Maintain the aspect ratio so that the width and height are a fixed proportion. For FlexCard Chart Element
Ratio example, if the Aspect Ratio is 2, and the width is 600px, then the height is Aspect Ratio
300px.
Title Displays a title above the chart when Hide Header is disabled. n/a
Type Select the type of chart to display. n/a
Value Node Select the values to populate the chart, such as AnnualRevenue for Accounts. n/a
See Also
Embed a Child FlexCard Inside a FlexCard

Embed a reusable FlexCard as a child inside the state of a parent FlexCard. The child FlexCard can have
its own data source. Or, the parent can override the child's data source with its own data source. The
parent can also pass specific data to the child, such as its recordId to use as the child data source's
contextId.
CAUTION
Before You Begin

• Create a child FlexCard. See Create a New FlexCard.
1. In the FlexCard Designer, drag the FlexCard element from the Build panel into a state on the canvas.

company 340
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.
Example 3. Example: Display Account and Case Information

You want to display Account information on a parent FlexCard and Case information on the child
FlexCard using a Datatable element.
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": "sean@edge.com",

company 341
"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}.

company 342
Example 4. Example: Pass Contact Id to Child Flexcard as a ContextId

You have a FlexCard that displays Account information on the parent and the Account's primary
Contact information on a child FlexCard.
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}'
Activate the child FlexCard.
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}.
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
See Also
• FlexCards Child FlexCard Properties
• Download a Sample Child FlexCard DataPack
• ???
Add a Child FlexCard to Itself Recursively

When a child FlexCard has hierarchical data, it can call itself recursively. When the FlexCard element is
embedded in a child FlexCard, use the Is Recursive feature to display the children and grand-children of
parent objects. The child FlexCard can add itself to itself again and again, each time passing the same child
data field (also called a data node) available in each level of the data JSON, until that data field no longer
exists or is empty.
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

company 343
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
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}
c. In the data source, reference the attribute as a contextId. For example,

{Parent.AccountId}.

company 344
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.

company 345
[
{
"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"
}
]
}
]
}
]
}
]
}
]

company 346
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.
7. (Optional) To preview the FlexCard at run time, click Preview.

8. Click Activate.
IMPORTANT
Activate the child FlexCard to embed it into a parent FlexCard.
See Also
Download a Sample Child FlexCard DataPack

Download a sample child FlexCard DataPack. Embed a reusable FlexCard as a child inside the state of a
parent FlexCard to pass data from the parent to the child.
See Embed a Child FlexCard Inside a FlexCard.
What's Included
Pass Parent Attributes to the Child FlexCard

Display Account information on the parent FlexCard and Contact information on the embedded child
FlexCard by passing the parent's contextId to the child as an attribute, where Key = AccountId, and Value
= {recordId}. On the child FlexCard, use {Parent.AccountId} as the contextId of the child
FlexCard's data source.

company 347
The demoEmbedChildPFCpassAttribute parent FlexCard in the DataPack includes the following

features:
• A SOQL Query data source gets Account names.

• An embedded child FlexCard that passes the Account Id from the parent as an attribute named
AccountId.
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.
Pass All Parent Records to the Child FlexCard

Display Account information on the parent FlexCard and Contact information on the embedded child
FlexCard by passing all records from the parent to the child by using the {records} merge field in the
Data Node property.

company 348
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:
• A Text element displays Case information as merge fields.

• The state is 6 columns wide to display cases side-by-side. See Display Records Side-By-Side on a
FlexCard.
Download and Import
1. Download the OmniStudio for Vlocity DataPack here: demoEmbedChildFlexCard-VMP.zip

company 349
NOTE
Download the OmniStudio DataPack here: demoEmbedChildFlexCard-OmniStudio.zip
NOTE
installed.
See Also

• Add a Child FlexCard to Itself Recursively
FlexCards Child FlexCard Properties

FlexCard element properties are configurable in the Property Panel when you select a FlexCard element in
the FlexCard Designer. With the FlexCard element, embed a reusable FlexCard as a child inside the state
of another FlexCard. See Embed a Child FlexCard Inside a FlexCard.

Attribute Define a key that represents an attribute. n/a
Attributes Pass data from the parent to the child FlexCard by creating an attribute and Embed a Child FlexCard
assigning it a value, such as a data merge field. Inside a FlexCard
FlexCard Element
Data Node To use the data source from the parent FlexCard, select a data node. n/a
Element Name The name of the element as seen on the canvas. Used to distinguish one element n/a
from another as you build your FlexCard in the designer. Is used only within the
designer.
Enable Tracking Enable event tracking through OmniAnalytics. Track Card Load, Card Unload and Enable Tracking on a
State Load events. FlexCard
FlexCard Name Select the child FlexCard to display. n/a

company 350

Is Recursive If your child FlexCard has hierarchical data, display the children and grandchildren Add a Child FlexCard to
of parent objects by adding the child FlexCard to itself recursively. Pass a data Itself Recursively
node that appears on multiple data levels, such as products in a list of sub-
products.`
Select State View a state from the FlexCard Name selected. n/a
Value Select the data to pass for the defined Attribute. n/a
See Also

• Add Conditions to a FlexCard Element
Embed a Custom LWC Inside a FlexCard

Embed an LWC OmniScript, a generated FlexCard LWC, or a custom LWC, inside a FlexCard state. A
wrapper encases the Custom LWC element and is fed data from your FlexCard's data source.
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
Before You Begin

• Create and activate a FlexCard, LWC OmniScript, or custom LWC component to generate an LWC to embed.
To create an LWC OmniScript, see Create an OmniScript.
1. In the FlexCard Designer, drag a Custom LWC element from the Build panel into a state on the canvas.
3. Click into the Custom LWC Name field, and select a custom LWC to embed.
NOTE
The Custom LWC is rendered in Preview only.

company 351
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.
4. To set the value of an attribute available to the component:

a. Next to the Attributes label, click +Add.
b. Enter the attribute name in the Attribute field, such as thumbnaillimit.
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}.
FlexCard Element.
What's Next
See Also
• FlexCards Custom LWC Properties
FlexCards Custom LWC Properties

Custom LWC element properties are configurable in the Property Panel when you select a Custom LWC
element in the FlexCard Designer. With Custom LWC element, embed an LWC OmniScript, a generated
FlexCard LWC, or a custom LWC, inside a FlexCard state.
See Embed a Custom LWC Inside a FlexCard.

company 352

Attribute Enter the name of the attribute defined in the selected custom LWC. n/a
FlexCard Element
Custom LWC Select the custom LWC to embed. n/a
Name
Element Name The name of the element as seen on the canvas. Used to distinguish one FlexCard Naming
element from another as you build your FlexCard in the designer. Is used only Conventions
within the designer.
Value Enter the value of the Attribute. n/a
See Also
Add a Datatable to a FlexCard

Display a tabular structure of the data fetched from a data source on a FlexCard. For example, display
Account Cases as a sortable table.
Configured Datatable
1. In the FlexCard Designer, drag a Datatable element from the Build panel into a state on the canvas.
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.

company 353
• 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.
8. (Optional) To configure additional Attributes, see FlexCards Datatable Properties.

9. (Optional) To group a table by a data field type:
a. Enter the name of the data field to group records by in the Group By field. For example, to group
Account Cases by the Status data field, enter Status.
b. (Optional) Configure these properties:
• To sort across all groups, select Sort Across Groups.
By default, sorting happens within each group.
• To remove the space below and above the group name, select Hide Extra Column.
• To collapse or expand the grouped rows by default, select Active Groups.
• To add a class to each group, enter a defined class in the Group Wrapper Class field. See Apply
Custom CSS to an Element on a FlexCard.
• To update the order in which each group is sorted, select from the Group Order dropdown.
FlexCard Element.
11. (Optional) To style your element, click Style to open the Style panel, and see FlexCards Datatable
Style Properties.

company 354
Download a Sample Datatable DataPack

Download a sample FlexCard DataPack with a configured Datatable. See Download a Sample Datatable
DataPack.
What's Next
See Also
• FlexCards Datatable Properties
FlexCards Datatable Properties

Datatable element properties are configurable in the Property Panel when you select a Datatable element
in the FlexCard Designer. With the Datatable element, display a tabular structure of the data fetched from a
data source. See Add a Datatable to a FlexCard.

Column Update the data fields to populate the table and set options for columns, such as n/a
type and selectability.
FlexCard Element
Datatable Name Adds an aria-label for accessibility users. The text isn’t visible on screen and only n/a
visible to assistive technologies.
designer.
Records Specify the record data that populates the table. Defaults to {records}. n/a
Attributes
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.

company 355
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
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.
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
Download a Sample Datatable DataPack

Download a sample Datatable DataPack to import into your org. A Datatable element lets you display a
tabular structure of the data fetched from a data source on a FlexCard. See Add a Datatable to a FlexCard.

company 356
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:
• Grouped by a data field.

• Searchable and sortable.
• Sortable across groups.
• Groups expanded.
• Row and cell-level editing.
• Draggable.
• Deletable row with confirmation upon deletion.
• Pagination.
• Repeat Records in Setup panel disabled.
• Custom data source.
1. Download the OmniStudio for Vlocity DataPack here: demoDatatable.json.

company 357
NOTE
Download the OmniStudio DataPack here: demoDatatable-OmniStudio.json
NOTE
installed.
See Also
• FlexCards Datatable Properties

Add a Field to a FlexCard

Display data fields returned from a data source on a FlexCard. For example, display Policy information for
an Account.
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.
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}.
5. (Optional) Add placeholder text in the Placeholder field.

company 358
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.

company 359
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.
FlexCard Element.
11. (Optional) To style your element, click Style to open the Style panel, and see FlexCards Field Style
Properties.
What's Next
FlexCards Field Properties

Field element properties are configurable in the Property Panel when you select a Field element in the
FlexCard Designer. With the Field element, display data fields returned from a provided data source. See
Add a Field to a FlexCard.

FlexCard Element
Element Name The name of the element as seen on the canvas. Used to distinguish one element from FlexCard Naming
another as you build your FlexCard in the designer. Is used only within the designer. Conventions
Field Type Select the type of Field element to display. If you select Date, make sure the date n/a
value, such as 28/03/2015, matches the format of the user locale, such as DD/MM/
YYYY, otherwise the date displays incorrectly.
Output Select the data field to display. n/a
Placeholder Enter placeholder text. n/a
Field Type Properties

This table lists additional properties available for each Field Type.

company 360
Property Description Field Type Reference

Currency Enter a currency code to update the supported currency. Currency Currency Codes
Format Select a format for the date or date and time if the Field Type is Date, Date Date and Time
either Date or Date Time. By default, the FlexCard Author's user Time Formats
locale determines the format.
Locale Enter a locale code to update the supported language. Currency Supported
Languages
Mask Enter a string expression to limit the user's input. Number n/a
Use Absolute Enable to prevent converting the date based on the timezone. Date n/a
Date
Use User Locale If your FlexCard is used in an application accessible across All n/a
For Formatting multiple locales, enable to use the logged-in user's locale to
determine the format of your date, time, currency, and so on.
See Also

Add an Icon to a FlexCard

Display an SVG Icon on a FlexCard. Select from a Salesforce SVG icon or a custom action. You can also
link the icon to an action.
1. From the FlexCard Designer, drag an Icon element from the Build panel into a state on the canvas.
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:
System.
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.
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

company 361
See Also
• FlexCards Icon Properties
FlexCards Icon Properties

Icon element properties are configurable in the Property Panel when you select an Icon element in the
FlexCard Designer. With the Icon element, display a Salesforce SVG Icon or a custom icon on a FlexCard.
See Add an Icon to a FlexCard.

Add Action Make the element a clickable action. Add a Click Event to a FlexCard
Element
Element
Extra Class Add an additional class to the element. n/a
Icon Enter the name of the Salesforce Icon. n/a
Image Source Enter the URL of a custom icon. n/a
Size Select the size of the icon. n/a
Type Select the type of icon to display. n/a
Variant Select from predefined SLDS styles to change the appearance of the n/a
element.
See Also

Add an Image to a FlexCard

Add an image to a FlexCard in the FlexCard Designer. With the Image element, upload an image from your
computer, use an image from a Salesforce library, enter a URL, or use a merge field from a data source.
Link the image to an action, add classes, and adjust the size of the image relative to the canvas size.
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.
3. Select the Image Source from one of these options:

company 362
• 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).
• To upload a file from your computer:

a. Click the search icon.
b. Click Upload Files and select an image file from your computer. Or drag a file from your
computer and drop it where it says Or drop files.
c. Click Save.
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.
7. (Optional) To display an image caption, enter text in the Title field.

company 363
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.
FlexCard Element.
What's Next
See Also
• FlexCards Image Properties
FlexCards Image Properties

Image element properties are configurable in the Property Panel when you select an Image element in the
FlexCard Designer. With the Image element, display an image on a FlexCard. See Add an Image to a
FlexCard.

Add Action Make the element a clickable action. Add a Click Event to a
FlexCard Element
Alternative Text For accessibility, enter text describing the image, which displays when the image is n/a
not available.
FlexCard Element
designer.
Extra Class Enter a class appended to the container of the element. Select from a class defined n/a
in the Add Custom CSS feature of the FlexCard Designer or any style sheet
available to the FlexCard.
Height Enter a value available to the height CSS property, such as 100px, 4rem, or a n/a
calc() function.
Image Source Enter the image source for the icon. Upload the icon here, select an image from your n/a
org's libraries, or enter a secure absolute URL from an external source.
Size Update the size of the image relative to the canvas size. By default, Fit Content is n/a
selected, enabling the image to fill the container of the Image element.
Title Enter an image caption. n/a
Title Class Enter a class for the image caption. n/a
Width Enter a value available to the width CSS property, such as 100px, 4rem, or a n/a
calc() function.

company 364
See Also

Add a Menu to a FlexCard

Create a menu from a list of actions on a FlexCard. Style the menu button, and each action in the menu's
dropdown. Add any action type available in the FlexCard Designer. See FlexCards Actions Reference.
Add and Configure Menu
1. From the FlexCard Designer, drag a Menu element into a state on the canvas.
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:
System.
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.
FlexCard Element.
13. (Optional) To style your menu element, click Style to open the Style panel, and see FlexCards Menu
Style Properties.

company 365
Add Actions
For each new action item, perform these tasks:
1. Click + Add New Action.

2. Select a type of action to execute from the Action Type dropdown.
3. To configure action properties, see FlexCards Action Properties.
4. To update the position of the action icon relative to the label, select a new position from the Icon
Position dropdown.
5. To enable menu items to reflect status level notifications like Error, Success, and Warning, select the
class from the Status dropdown.
What's Next
See Also
• FlexCards Menu Properties
FlexCards Menu Properties

Menu element properties are configurable in the Property Panel when you select a Menu element in the
FlexCard Designer. With the Menu element, create a menu from a list of actions. See Add a Menu to a
FlexCard.

Add New Action Add actions to populate the menu. n/a
Element
Dropdown Position Select the positon of the dropdown relative to the menu button. n/a
Dropdown Size Select the size of the dropdown. n/a
Enable Overflow To disable scrolling in the dropdown when there are more than 5 menu n/a
items, disable this feature. Enabled by default.
Icon Select the icon to display. n/a
Icon Position Select position of the icon relative to the label. n/a
Icon Size Select the size of the icon. n/a
Status Select an SLDS style for your menu item. Configure from the modal when
you click on the Add New
Action property.
Variant Select from predefined SLDS styles to change the appearance of the n/a
element.

company 366
See Also
Add a Text Element to a FlexCard

Combine plain text and merge fields inside a rich text editor with the Text element in the FlexCard Designer.
Enter a merge field, such as data fields, or context variables, such as session variables. For available
context variables and their corresponding merge fields, see FlexCards Context Variables.
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.
7. (Optional) To undo a change, click the Undo icon.

8. (Optional) To redo an undone change, click the Redo icon.
FlexCard Element.
Style Text With the Rich Text Editor

1. To add NDS or SLDS classes to change the text style:
a. Click into a div in the rich text editor.
b. To adjust the size or style of the text, click the Paragraph dropdown, and select one or more
classes from Headers or Body section.
c. To change the color of the text, click the Paragraph dropdown, and select a class from the Color
section.

company 367
d. To remove a class, select the class again.

For SLDS class descriptions, see SLDS Text documentation.
2. To manually update the text size, weight, style, font, and color, select the text, then select from one of
the rich text editor's formatting options.
For example, to make the text bold, select text, and click the B icon.
3. To create a list, adjust alignment, or set indentation, click into a div, and select from the list, alignment,
or indentation formatting options.
For example, to add indentation, select the text, and select the Increase Indentation icon.
4. To clear formatting, select the text, and click the Clear formatting icon.
What's Next
(Optional) To style your element, click Style to open the Style panel, and see Style FlexCard Elements.
See Also
• FlexCards Text Element Properties

FlexCards Text Element Properties

Text element properties are configurable in the Property Panel when you select a Text element in the
FlexCard Designer. With the Text element, combine plain text and merge fields using a Rich Text Editor.
See Add a Text Element to a FlexCard.

FlexCard Element
designer.
See Also

Trigger Actions with the Toggle Element on a FlexCard

Trigger an action when a user clicks a toggle element on a FlexCard. Let a user pick between two states,
enable or disable an option, or select multiple options. When the element is clicked, its value is sent as a
parameter to the action as true or false, or a comma-separated list of user-selected options with the
{element.value} merge field.
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.

company 368
Add and Configure Toggle Element

1. In the FlexCard Designer, drag a Toggle element from the Build panel into a state on the canvas.
3. From the Toggle Type dropdown, select the type of toggle element to use. See FlexCard Toggle
Element Type Reference.
4. To configure the selected toggle type, see FlexCards Toggle Properties.
5. (Optional) To disable the element, from the Disabled field, select from one of the following options:
• Select true.
• To disable to toggle element based on the boolean (true or false) value of a merge field, select the
merge field from the dropdown.
For example, on a FlexCard whose data source returns Cases, you can disable a toggle element if
the record's IsEscalated field is set to true.
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.
FlexCard Element.
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:
1. Click Add Action.

2. To configure action properties, see FlexCards Action Properties.
3. To pass the toggle element's value as a parameter:
a. Click Input Parameters.
b. Enter any name in the Key field.
c. Enter {element.value} in the Value field.

company 369
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}.
Download a Sample Toggle Element DataPack

Download a sample DataPack with configured Toggle elements. See Download a Sample Toggle
DataPack.
What's Next
FlexCard Toggle Element Type Reference

Select how to trigger an action when a user clicks a Toggle element on a FlexCard. Enable a user to pick
between two states, enable or disable an option, or select multiple options to trigger an action. See Trigger
Actions with the Toggle Element on a FlexCard.
Toggle Type Description Example

Checkbox Button Displays a checkbox styled as an icon that enables switching between two options, where
each state can display a unique icon. Configurable options include adding a visible label
next to the element.
Checkbox Group Displays a group of checkboxes with labels.
Checkbox Group Displays a group of checkboxes styled as clickable textual buttons.

Button
Checkbox Toggle Displays a checkbox styled as an on/off switch that enables switching between disbaled and
enabled. Configurable options include displaying labels for each state.
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.

company 370
See Also
• Download a Sample Toggle DataPack

• FlexCards Toggle Properties
• FlexCards Toggle Style Properties
Download a Sample Toggle DataPack

Download a sample Toggle element FlexCard DataPack into import to your org. Trigger an action when a
user clicks a Toggle element on a FlexCard. See Trigger Actions with the Toggle Element on a FlexCard.
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.

company 371
1. Download the OmniStudio for Vlocity DataPack here: demoToggleDisplayActionUpdate.json. See
NOTE
Download the OmniStudio DataPack here: demoToggleDisplayActionUpdate-OmniStudio.json.
NOTE
installed.
See Also
• FlexCards Toggle Properties

FlexCards Toggle Properties

Toggle element properties are configurable in the Property Panel when you select a Toggle element in the
FlexCard Designer. Trigger an action when a user selects a Toggle element. See Trigger Actions with the
Toggle Element on a FlexCard.
Common Toggle Element Properties

These properties are shared by all Toggle element types.

Add Action Add an action that gets triggered when a user clicks the toggle element. Add a Click Event to a
FlexCard Element
Element

company 372

Element Name The name of the element as seen on the canvas. Used to distinguish one FlexCard Naming
element from another as you build your FlexCard in the designer. Is used only Conventions
within the designer.
Extra Class Enter a class appended to the container of the element. Select from a class n/a
defined in the Add Custom CSS feature of the FlexCard Designer or any style
sheet available to the FlexCard.
Toggle Type Set the type of toggle element to display. FlexCard Toggle Element
Type Reference
Toggle Element Properties
Property Description Type

Alignment Select whether to align each checkbox horizontally or vertically. Checkbox Group
Alternative Text Enter text for accessibility, visible when image is not present. Stateful Icon
Checked Set the toggle element to be checked by default. Stateful Icon, Checkbox Button,
Checkbox Toggle, Stateful Button, Dual
Stateful Button
Checked Icon Select the icon visible when the element is checked. Checkbox Button, Dual Stateful Button,
Name Stateful Button
Checked Label Select the label visible when the element is checked. Stateful Button, Dual Stateful Button,
Checkbox Toggle
Disabled Disable the toggle element. Or disable the toggle element based Stateful Icon, Checkbox Button,
on the value of a data field whose value returns true or false. The Checkbox Toggle, Stateful Button, Dual
field must have a boolean value. If the value returns a string, Stateful Button
Disabled is false.
Help Text Add text visible when user hovers over the help i icon. Stateful Icon, Checkbox Button,
Checkbox Group Button, Checkbox
Group, Checkbox Toggle
Icon Name Select the icon. Stateful Icon
Icon On Hover Select the icon visible on hover of the element. Stateful Button
Label Enter a visible label for the element. Stateful Icon, Checkbox Button,
Label On Hover Select the label visible on hover of the element. Stateful Button
Options Enter a key/value pair for each checkbox option. Checkbox Group, Checkbox Group
Button
Required Make the toggle element a required field. Adds an asterisk next to Checkbox Toggle, Checkbox Group
the element. Button, Checkbox Group
Required Label Add text next to the asterisk when Require is enabled. Stateful Icon, Checkbox Button,
Unchecked Icon Select the icon visible when the element is unchecked Checkbox Button, Dual Stateful Button,
Name Stateful Button
Unchecked Label Select the label visible when the element is unchecked. Stateful Button, Dual Stateful Button,
Checkbox Toggle
Update Data Updates the data source with the value of the selected state of Stateful Icon, Checkbox Button,
Source the toggle element. Checkbox Toggle, Stateful Button, Dual
Stateful Button

company 373
Property Description Type

Value Add default value. For example, set a value as true or enter a Checkbox Group, Checkbox Group
comma-separated list of selected options. Button
Variant Select from predefined SLDS styles to change the appearance of Stateful Button
the element.
See Also
• Download a Sample Toggle DataPack

Add Conditions to a FlexCard Element

Display or hide FlexCard elements based on the value of data fields. For example, display an alert icon or
supplemental text only for Cases whose Status is Escalated.
To apply conditions to a state, see Add Conditions to a FlexCard State.
IMPORTANT
Applied conditions are visible in Preview only.
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.

company 374
NOTE
If there’s only one condition, that condition must be met to display cards.
• Select OR if any condition can be met.

For example, Status is Escalated or Priority is High.
NOTE
If there’s only one condition, that condition doesn’t need to be met to display
cards.
6. To build nested conditions:

a. Click + Add Group after creating a condition.
b. Click + Add Condition and enter values for all fields for each condition.
c. Select AND or OR from the dropdown between conditions.
FlexCards Conditions Properties

Conditions properties are configurable for all elements in the Properties panel in the FlexCard Designer.
Show or hide FlexCard elements based on specified conditions. See Add Conditions to a FlexCard
Element.
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.
FlexCards Common Element Properties

FlexCard elements have properties shared by all FlexCard elements. For example, any element can be
shown or hidden based on conditions set with the Conditions property.

Element
Add Action Make the element a clickable action. Add a Click Event to a FlexCard
Element

company 375
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.
Add a State to a FlexCard

Add an additional state to a FlexCard to present different interactions and layouts based on specified
conditions. Each FlexCard has a default state that cannot be deleted. Add a State element to the canvas of
a FlexCard, or clone a state already on the canvas.

company 376
Add a State Element

1. From the FlexCard Designer, drag a State element from the Build panel onto the canvas.
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 the name of the state, such as Active.
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.

company 377
See Also
• FlexCard States
• FlexCards State Properties
Add Conditions to a FlexCard State

FlexCard states enable the presentation of different CRM interactions for each state. Set conditions to
determine if, when, and how data displays on a FlexCard.
Example 5. Example: Policy Information FlexCard

A FlexCard displays policy information for an Account. If the Policy is up to date, the default state displays
data fields, and an action to update Account information. If the Policy is about to expire, the Policy has a
red border, an alert notification, and an action to renew the Policy.
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:
1. State 1 - Condition: DaysToExpiration < 31 && DaysToExpiration != Null (empty)

2. State 2 - No conditions
3. State 3 - Blank Card State (no records returned)
IMPORTANT
Applied conditions are visible in Preview only.
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.

company 378
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.
• Select OR if any condition can be met.

• For example, the policy status is closed OR the expiration date is less than 31 days.
NOTE
If there’s only one condition, that condition doesn’t need to be met to display
cards.
5. To build nested conditions:

a. Click + Add Group after creating a condition, such as DaysToExpiration < 31.
b. Click + Add Condition and enter values for all fields for each condition.
c. Select AND or OR from the dropdown between conditions.
For example, use the conditions feature to build the conditional expression DaysToExpiration <
31 AND ( PolicyType = Universal Life OR PolicyType = Universal Variable
Life) to filter for policies about to expire, and whose policy type is either Universal Life or Universal
Variable Life.

company 379
See Also
• FlexCard States
• FlexCards State Properties
FlexCards State Properties

This page contains lists of available FlexCards State element properties. Add additional states o a FlexCard
to present different interactions and layouts based on specified conditions. See Add a State to a FlexCard.

Blank Card State Display this state when there is no data returned from a data source. n/a
Name Enter a descriptive name for the state. The state Name is for reference only and n/a
does not appear on the generated LWC or in Preview.

company 380

Conditions Set when and how a state displayed based on specified conditions. Add Conditions to a
FlexCard State
See Also
• FlexCard States
Configure a Data Source on a FlexCard

Configure a data source on a FlexCard to retrieve data from a Salesforce object or an external database. A
Child FlexCard can have a data source independent of the parent FlexCard or use the data source from the
parent 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 Properties
• Embed a Child FlexCard Inside a FlexCard
FlexCards Data Source Reference

Select from multiple data source types to retrieve data from a Salesforce object or an external database.
Select a data source from the Setup panel in the FlexCard Designer, or when creating a FlexCard.
See Configure a Data Source on a FlexCard.

company 381
Data Source Description Reference

Type
Apex Remote Uses an Apex Remote class and method to return data. An Apex Remote class is Configure an Apex Remote
a standard Apex class that implements the VlocityOpenInterface. Data Source on a FlexCard
Apex REST Uses a REST endpoint of an Apex class to return data from a server or post data Configure an Apex REST
to a server. Data Source on a FlexCard
Custom Uses sample JSON to set up a FlexCard with temporary data, allowing you to Configure a Custom Data
embed JSON directly into the layout without depending on external data. Source on a FlexCard
DataRaptor Uses a DataRaptor Extract interface to return data. Field-level security is fully Configure a DataRaptor
supported. See OmniStudio DataRaptors. Data Source on a FlexCard
Integration Uses an Integration Procedure to return data. Integration Procedures are Configure an Integration
Procedures declarative, server-side processes that execute multiple actions in a single server Procedure Data Source on
call. See OmniStudio Integration Procedures. a FlexCard
Platform Event Uses Salesforce's Platform Events enterprise messaging platform, which Configure a Platform Event
combines PushTopic and Streaming Channel to enable apps to communicate Data Source on a FlexCard
inside and outside of Salesforce.
PushTopic Uses a Salesforce Object Query Language (SOQL) query to return a result that Configure a PushTopic
notifies listeners of changes to records in a Salesforce organization. The Data Source on a FlexCard
PushTopic defines a Streaming API channel. See Salesforce Streaming API.
REST: Named Uses the standard REST API call to post data to a server or return data from the Configure a REST Data
Credential URL of a callout endpoint and its required authentication parameters in one Source Using Named
definition. Credentials on a FlexCard
REST: Web Uses the standard REST API call to post data to a server or return data from the Configure a REST Web
URL of a callout endpoint. Data Source on a FlexCard
SDK Uses a method from an SDK to get data to populate fields on a FlexCard. FlexCard SDK Data Source
SOQL Query Uses a Salesforce Object Query Language (SOQL) to search an org's Salesforce Configure a SOQL Query
data for specific information. For example, SELECT Name, Id FROM Account Data Source on a FlexCard
LIMIT 5.
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

FlexCard Data Source properties are configurable for each data source type in the Setup panel of the
FlexCard Designer. Retrieve data from a Salesforce object or an external database. See FlexCards Data
Source Reference.

company 382
Common Data Source Properties

These properties are shared by all data sources. See Configure a Data Source on a FlexCard.
Delay(ms) available beginning Summer '21.
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.
Apex Remote Data Source Properties

These properties are unique to the Apex Remote data source. See Configure an Apex Remote Data
Source on a FlexCard.
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.
Apex REST Data Source Properties

These properties are unique to the Apex REST data source. See Configure an Apex REST Data Source on
a FlexCard.
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.

company 383
DataRaptor Data Source Properties

These properties are unique to the DataRaptor data source. See Configure a DataRaptor Data Source on a
FlexCard.
Interface Name Select the DataRaptor to fetch the data from.
Integration Procedure Data Source Properties

These properties are unique to the Integration Procedure data source. See Configure an Integration
Procedure Data Source on a Flex Card.
Name Select the Integration Procedure to fetch the data from.
REST Data Source Properties

These properties are unique to the REST data source. See Configure a REST Web Data Source on a
FlexCard. See Configure a REST Data Source Using Named Credentials on a FlexCard.
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.
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.
SOQL Query Properties

These properties are unique to the SOQL Query data source. See Configure a SOQL Query Data Source
on a FlexCard.
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.

company 384
SOSL Search Data Source Properties

These properties are unique to the SOSL Search data source. See Configure a SOSL Search Data Source
on a FlexCard.
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.
Streaming API Data Source Properties

These properties are unique to the Streaming API data source. See Vlocity Streaming API Data Sources.
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.
Enable and Disable Data Sources

Enable and disable data source types for an org, profile, or user level from the Card Framework
Configuration custom setting. For example, disable Apex REST, Apex Remote, and other complex data
sources for your entire org, or prevent system admins with limited permissions from using these data
sources.
Configure a DataRaptor Data Source on a FlexCard

Configure a DataRaptor data source to fetch data from a DataRaptor Extract. DataRaptor is a mapping tool
that enables you to read, transform, and write Salesforce data.
See DataRaptor Overview.
NOTE
Before You Begin

• Create a DataRaptor Extract. See Create a DataRaptor Extract.

company 385
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.
Example 6. Pass the ContextId

For example, to use the recordId context variable to dynamically get the ContextId of FlexCard:
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
Configure an Integration Procedure Data Source on a FlexCard

Configure a data source to use a Vlocity Integration Procedure to execute multiple actions in a single server
call. For example, as a Systems Admin, you want your customer service reps to view the weather forecast
of policy holders when on a call. You can use an Integration Procedure with a DataRaptor Extract that
returns an account's ZIP code, and a REST API call that uses the ZIP code to get the current forecast for
the Account's region.
See OmniStudio Integration Procedures.
NOTE
An Integration Procedure doesn’t support the following data sources:
• Salesforce Object Search Language (SOSL)

• Streaming API
• Off-Platform

company 386
Before You Begin

• Create an Integration Procedure. See Create an Integration Procedure.
step, select Integration Procedures, and click Next.
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.
Example 7. Pass the ContextId

For example, to use the recordId context variable as a merge field to dynamically get the ContextId of
a FlexCard:
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.
Properties.
Add Dummy Data From an Integration Procedure

1. In a current or new Integration Procedure add a Response Action step.

company 387
2. Use one of two methods to add dummy JSON data:

• For a small dataset:
a. In the Properties tab, click ADDITIONAL OUTPUT RESPONSE.
b. For each key/value pair, click the Add Key/Value Pair button and add your data.
• For a large dataset:

a. Click the Edit as JSON link at the top right of the Properties tab.
b. In the additionalOutput node, enter your full JSON data as an object.

company 388
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.

company 389
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
See Also
Configure a SOQL Query Data Source on a FlexCard

Configure a data source to use a Salesforce Object Query Language (SOQL) query to search an org's data
for specific information. The SOQL queries are encrypted so that FlexCards don’t display query information
on the client-side. If security is a concern, use a DataRaptor instead of a SOQL query, because
DataRaptors provide field-level security.
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
step, select SOQL Query, and click Next.

company 390
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
Properties.
What's Next
See Also
Configure a SOSL Search Data Source on a FlexCard

Construct text-based search queries against the search index with Salesforce Object Search Language
(SOSL). You can search text, email, and phone fields for multiple objects to which you have access,
including custom objects, in a single query. The SOSL queries are encrypted so that FlexCards don’t
display query information on the client-side.
See SOSL and SOQL Reference
step, select SOSL Search, and click Next.
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.
Properties.
What's Next

company 391
See Also
Configure a Custom Data Source on a FlexCard

Embed custom JSON data directly into FlexCard without depending on any external data source. Configure
the Custom data source for testing with temporary static data. For example, when you're waiting for access
to an API, or if you want to quickly test a concept.
step, select Custom, and click Next.
Custom from the Data Source Type dropdown.
3. Enter custom JSON in the Custom JSON field.
Example 8. Sample Custom JSON

[
{
"attributes": {
"type": "Contact",
"url": "/services/data/v49.0/sobjects/Contact/
0033700000TOF0eAAH"
},
"Name": "Perry",
"Id": "0033700000TOF0eAAH",
"Phone": "(734) 489-5851",
"AccountId": "0013700000NVVLvAAP",
"Email": "perry@vlocity.com",
"MailingAddress": {
"city": "Concord",
"country": "US",
"geocodeAccuracy": null,
"latitude": null,
"longitude": null,
"postalCode": "53813",
"state": "WI",
"street": "856 4th Avenue #76"
},
"CreatedDate": "2017-06-14T18:53:11.000+0000"
},
{
"attributes": {
"type": "Contact",
0033700000TOB6mAAH"

company 392
},
"Name": "Robert0 Taylor",
"Id": "0033700000TOB6mAAH",
"Phone": "(888) 888-8888",
"AccountId": "00137000007D63JAAS",
"MailingAddress": {
"city": "SF",
"country": "US",
"latitude": null,
"longitude": null,
"state": "CA",
"street": "50 Santa Rita St"
},
"CreatedDate": "2017-06-13T21:08:25.000+0000"
},
{
"attributes": {
"type": "Contact",
0033700000TNvK0AAL"
},
"Name": "c1",
"Id": "0033700000TNvK0AAL",
"AccountId": "0013700000NVE4tAAH",
"MailingAddress": null,
"CreatedDate": "2017-06-08T20:13:41.000+0000"
},
{
"attributes": {
"type": "Contact",
0033700000TNvKKAA1"
},
"Name": "c2",
"Id": "0033700000TNvKKAA1",
"AccountId": "0013700000NVE4tAAH",
"MailingAddress": null,
"CreatedDate": "2017-06-08T20:13:50.000+0000"
},
{
"attributes": {
"type": "Contact",
0033700000Vs6RzAAJ"

company 393
},
"Name": "Smith",
"Id": "0033700000Vs6RzAAJ",
"Phone": "(300) 333-3763",
"AccountId": "001370000098i8mAAA",
"MailingAddress": {
"city": "SF",
"country": "US",
"latitude": null,
"longitude": null,
"state": "CA",
"street": "50 Fremont St"
},
"CreatedDate": "2017-08-16T20:26:07.000+0000"
}
]
Properties.
What's Next
See Also
Configure an Apex REST Data Source on a FlexCard

Configure a data source to use an Apex REST call to fetch data to populate fields on a FlexCard with the
Get method. Use the Post method to post data back to the server.
NOTE
step, select Apex Rest, and click Next.

company 394
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.
Properties.
What's Next
See Also
Configure an Apex Remote Data Source on a FlexCard

Configure a data source to invoke an Apex Class and method that fetches data to populate a FlexCard.
Apex remote data sources can run asynchronously through Apex, which increases the CPU time but
ensures that long-running transactions aren’t timed-out.
NOTE

company 395
Before You Begin

1. Know the Apex remote class and method you need to invoke before you can configure a remote data source. Managed packages
can include Apex remote classes and methods.
To see existing Apex classes:
a. In your org, go to Setup, and in the Quick Find box, enter Apex.
b. Click Apex Classes.
2. Add an Apex class permissions checker to ensure only authorized users can access VlocityOpenInterface classes (APIs) from a
remote action on a card. See Adding an Apex Class Permissions Checker.
step, select Apex Remote, and click Next.
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.
7. (Optional) To run asynchronously through Apex, select Is Asynchronous.

8. (Optional) To specify the polling interval to check the response status, enter the time in milliseconds in
the Poll Interval field.
Properties.

company 396
What's Next
See Also
Configure a REST Data Source Using Named Credentials on a FlexCard

Use Named Credentials to authenticate Apex callouts when configuring a REST data source. A named
credential specifies the URL of a callout endpoint and its required authentication parameters in one
definition.
To create a named credential, see Named Credentials as Callout Endpoints.
NOTE
Before You Begin

• Create a Named Credential. See Define a Named Credential.
step, select REST, and click Next.
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.

company 397
NOTE
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.
Properties.
What's Next
See Also
Configure a REST Web Data Source on a FlexCard

Configure a REST Web data source to get or post data from or to a public API. For example, pull in weather
data from a weather API based on a policy holder's postal code.
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
step, select REST, and click Next.
REST from the Data Source Type dropdown.

company 398
3. Select Web from the REST type dropdown.

4. In the Endpoint field, enter the REST endpoint URL. For example:
http://api.weatherstack.com/current?
access_key={Session.weatherAPIkey}&query={BillingCity}
NOTE
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.
Properties.
What's Next
See Also
Vlocity Streaming API Data Sources

Streaming API lets you push a stream of notifications from Salesforce to client apps based on criteria that
you define. It has a persistent connection that continues to deliver new data as it becomes available, rather
than using client polling.
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

company 399
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:
Streaming API Types

The Vlocity Streaming API types include:
Type Description Example

Streaming Channel The Streaming Channel API type uses the Streaming API to send notifications Configure a Streaming
of general events that aren’t tied to Salesforce data changes. Channel Data Source
on a FlexCard
PushTopic A PushTopic is an SOQL query that returns a result that notifies listeners of Configure a
changes to records in a Salesforce organization. The PushTopic defines a PushTopic Data
Streaming API channel. Source on a FlexCard

company 400
Type Description Example

Platform Event Platform Events are part of Salesforce’s enterprise messaging platform. The Configure a Platform
platform provides an event-driven messaging architecture to enable apps to Event Data Source on
communicate inside and outside of Salesforce. A Platform Event combines a FlexCard.
PushTopic and Streaming Channel. Instead of working with an sObject,
Platform Events work with custom objects.
PushTopic Data Source

The Streaming Channel API type uses the Streaming API to send notifications of general events that are
not tied to Salesforce data changes. Use the Streaming Channel API when you want to send and receive
notifications based on custom events that you specify. You can use Streaming Channel API for any
application that sends custom notifications, such as a Chat application.
Streaming API is known as Generic Streaming in Salesforce. See Generic Streaming.
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:
Select Id,CaseNumber,Subject,ContactEmail from Case where Type = 'Problem'
If you also need Status, you can simply add another condition:
Select Id,CaseNumber,Subject,ContactEmail from Case where Type = 'Problem' AND

Status = ‘New’
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.

company 401
What's Next
Configure a PushTopic data source on your FlexCard. See Configure a PushTopic Data Source on a
FlexCard.
See Also
• Vlocity Streaming API Data Sources

Configure a PushTopic Data Source on a FlexCard

Configure a PushTopic data source to run 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
example, get notified when a case is created for a particular type or status or both.
See PushTopic Data Source.
Before You Begin

• Create a PushTopic. See Creating a PushTopic.
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.

company 402
• 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.
Properties.
What's Next
See Also
Platform Event Data Source

Platform Events are part of Salesforce’s enterprise messaging platform. A Platform Event combines
PushTopic and Streaming Channel to enable apps to communicate inside and outside of Salesforce.
Instead of working with an sObject, Platform Events work with custom objects.
• Systems in request-response communication models make a request to a web service or database to

obtain information about a certain state.
• An event-based model obtains information and can react to it in near real time when the event occurs.
• Event producers don’t know the consumers that receive the events. Any number of consumers can
receive and react to the same events.
• The only dependency between producers and consumers is the semantic of the message content.
• Unlike with an sObject, you can’t update or delete event records. You also can’t view event records in the
Salesforce user interface, and Platform Events don’t have page layouts.
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.

company 403
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

Configure a Platform Event Data Source on a FlexCard

Configure a Platform Event data source to enable apps to communicate inside and outside of Salesforce.
Platform Events are part of Salesforce’s enterprise messaging platform. A Platform Event combines
PushTopic and Streaming Channel. Instead of working with an sObject, Platform Events work with custom
objects.
See Platform Event Data Source.
Before You Begin

• Create a Platform Event. See Delivering Custom Notifications with Platform Events.

company 404
3. Select Platform Event from the Type dropdown.

4. In the Channel field, enter the URL of the Platform Event that you created.
Properties.
What's Next
See Also
Streaming Channel Data Source

The Streaming Channel API type uses the Streaming API to send notifications of general events that aren’t
tied to Salesforce data changes. Use the Streaming Channel API when you want to send and receive
notifications based on custom events that you specify. You can use Streaming Channel API for any
application that sends custom notifications, such as a Chat application.
Streaming API is known as Generic Streaming in Salesforce. See Generic Streaming.
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

company 405
Configure a Streaming Channel Data Source on a FlexCard

Enable the Streaming Channel data source to send and receive notifications based on custom events that
you specify. The Streaming Channel API type enables the Streaming API to send notifications of general
events that aren’t tied to Salesforce data changes.
See Streaming Channel Data Source.
Before You Begin

• Create the app that sends and receives notifications. See Generic Streaming.
3. Select Streaming Channel from the Type dropdown.
4. In the Channel field, enter the URL of the app that you created.
Properties.
What's Next
See Also
FlexCard SDK Data Source

You can use a SDK, such as the Salesforce Industries Digital Commerce SDK, which contains all the
business logic necessary for your application and reuse that business logic in other applications. This
allows you to focus on creating the UI for an application without needing to call an API and process the API
response. You only need to call the method of the SDK and the SDK calls the API. The SDK gets the API
response, parses that response, then gives it back to the client. The client then consumes the SDK
response in the UI so you can design your FlexCard based on the response you receive.
See the Salesforce Industries Digital Commerce SDK documentation.

company 406
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.
Create the Static Resource for an SDK Data Source on a FlexCard

Before you configure an SDK as a data source for your FlexCard, you need to add or create a static
resource named OmniStudioActionRegistry that contains the configuration of the SDK that you want to use
as a datasource in the FlexCard. The FlexCard looks for a file with that name in the static resource.
See FlexCard SDK Data Source.
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
},

company 407
"contextVariables": []
},{
"type": "SDK",
"name" : "UPC JS SDK",
interacting with V3 API",
"value": {
"sdkObject": "productconsole",
"sdkPath": "/latest/productconsole/productconsole.sdk.js",
"staticResourceName": "vlocityupcsdk",
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
},
{
"type": "SDK",
"name" : "Digitalcommerce JS SDK",
interacting with V3 API",
"value": {
"sdkObject": "digitalcommerce",
"sdkPath": "/latest/digitalcommerce/digitalcommerce.sdk.js",
"staticResourceName": "vlocitydcsdk",
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
},
{
"type": "SDK",
"name" : "b2b JS SDK",
"value": {
"sdkObject": "b2bexpress",
"sdkPath": "/latest/b2bexpress/b2bexpress.sdk.js",
"staticResourceName": "vlocityb2bexpresssdk",

company 408
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
},{
"type": "SDK",
"name" : "datasource SDK",
"value": {
"sdkObject": "datasource",
"sdkPath": "/latest/datasource/datasource.sdk.js",
"staticResourceName": "vlocitysdk",
"inputMap": {},
"resultVar": ""
},
"orderBy": {
"name": "",
"isReverse": false
},
}
]
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.
Configure an SDK Data Source on a FlexCard

Configure a data source to use methods from an SDK to provide the data for a FlexCard. An SDK allows
you to call multiple data sources, reuse business logic, and control which fields appear on your FlexCard.
See FlexCard SDK Data Source.

company 409
Required Versions
Before You Begin

Create the static resource for the SDK. See Create the Static Resource for an SDK Data Source on a FlexCard.
step, select SDK, and click Next.
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"}.

company 410

company 411
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
See Also
Test Data Source Settings on a FlexCard

Preview a FlexCard with real data by adding test variables that the query can use to return live data. The
variables populate the dynamic fields in a data source, such as a REST endpoint with parameters or from a
DataRaptor that gets data from an sObject.
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",
"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"
},
{

company 412
"Priority": "Medium",
"IsEscalated": false,
"CaseId": "5006g00000BsfKkAAJ",
"Created": "2020-02-27T22:28:20.000Z",
"Subject": "Shutting down of generator",
"Status": "Closed",
"Origin": "Web",
}
],
"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.
7. (Optional) Click JSON to view test results as JSON.

8. (Optional) Click Refresh to see the latest data.
See Also

company 413
Set Up a FlexCard in the FlexCard Designer

Configure optional settings for your FlexCard in the Setup panel of the FlexCard Designer. For example,
update a data source, create an event listener, add session variables, and so on.
Before You Begin

• Create a FlexCard. See Create a New FlexCard.
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
FlexCard Setup Reference

The Setup panel in the FlexCard Designer provides multiple configuration options that enable a user to
define the behavior of the FlexCard further. For example, update the data source and add session
variables. See Set Up a FlexCard in the FlexCard Designer.

Author (Disabled by default) The Author of the FlexCard. To update the Author, FlexCard Naming Conventions
clone the FlexCard.
Data Source Sets a data source for the FlexCard. Configure a Data Source on a
FlexCard
Event Listener Add a listener for a PubSub or Custom event that gets fired when a user Add an Event Listener to a
performs an action. FlexCard
Multi-Language Enable to make Custom Labels update and not cached. Enable Multi-Language Support
Support on a FlexCard, Add Custom
Labels to Supported Fields on a
FlexCard
Name (Disabled by default) The API name of the FlexCard. To update the Name, FlexCard Naming Conventions
clone the FlexCard.
OmniScript Enable when your FlexCard interacts with an LWC OmniScript, such as Enable OmniScript Support on a
Support when embedding a Custom LWC in the OmniScript Designer, or updating FlexCard
an OmniScript from a FlexCard Action element.
Render Key To rerender only the affected card record when the FlexCard updates, Improve Performance on
enter a unique key that identifies the record. Select a data field with a Repeating Records on a
unique value, such as Id. FlexCard
Repeat Records Disable to display content that doesn't need repeating. For example, a Repeat Options in the FlexCard
Chart or Datatable element that displays data for multiple Accounts, or a Designer
Custom LWC used as a header on a page.

company 414

Required Limits user access to a FlexCard by entering a comma-separated list of Limit User Access to a FlexCard
Permission custom permissions. If this field is left empty, any user can see the with Custom Permissions
FlexCard.
Session Set attributes available from a component, or store values from data Add Session Variables to a
Variables sources, external systems, or hardcoded to access globally on a FlexCard. FlexCard
Title The title that displays in the Experience Builder (for Communities) and n/a
Lightning App Builder.
Repeat Options in the FlexCard Designer

By default, a FlexCard loops through records returned from its data source. The FlexCard displays the list
of records in containers called cards. For example, if a data source returns a list of active Cases for an
Account, each card displays the Status, Priority, Subject, and any other data field or element added to a
state.
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.

company 415
A FlexCard with a Datatable element. Repeat Records disabled.
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:
Enabled? Records Active State Blank Card State

Available?
Yes (default) Yes Show a card for each available record. Hidden
Yes (default) Yes When a condition results in no records to show, Show one card, such as to show an
this state is hidden. action link to create a record.
Yes (default) No (or no Data Hidden Show one card, such as to show an
Source) action link to create a record.
No Yes Show one card with all available records inside Hidden
it. For example, to display a Datatable, List,
Chart, or a container, such as a Custom LWC or
child Flex Card that uses the data source
provided by its container.
No Yes When a condition results in no records to show, Show one card, such as to show an
this state is hidden. action link to create a record.
No No (or no Data Hidden Show one card, such as to show an
Source) action link to create a record.
Disable Record Looping on a FlexCard

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.

company 416
A Datatable element listing Account Cases. Repeat Records disabled.
1. In the FlexCard Designer, click Setup to open the Setup panel.

2. To disable looping over records, unselect Repeat Records.
See Also
• Repeat Options in the FlexCard Designer
Improve Performance on Repeating Records on a FlexCard

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.
Required Versions
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.

company 417
See Also
• Repeat Options in the FlexCard Designer
Add Session Variables to a FlexCard

Set attributes available from a component, or store values from data sources or external systems to access
globally on a FlexCard. For example, set an API key or track pagination. Use the merge field
{Session.var} to parse the value.
This table lists the elements that support Session Variables:
Element Supported Input Fields

Action (any) Label
Custom Event Action Beginning Summer '21: Input Parameter > Value
Field Label, Placeholder, and Output
Text Inside the rich text editor

2. Click + Add New next to Session Variables.
3. Enter a Key, such as APIkey.
4. Enter a Value, such as 123456dk489384A1sdjsk.
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
Add an Event Listener to a FlexCard

Add an event listener that listens for an event fired from a component and performs an action in response.
With a Pubsub Event, listen for an event from another component. With a Custom event, listen for an event
fired from a child FlexCard or from an element on the card.
Example 9. Example: Update Product List

Let's say you want to create a Lightning page that displays a filterable list of products. You'll need two
FlexCards: one to display the products and has an event listener, and the other to display the filters that can
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.

company 418
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.
Before You Begin

Create the Custom or Pubsub event. To create the Custom event, see Trigger a Custom Event from an Action on a FlexCard. To create
the Pubsub event, see Trigger a Pubsub Event from an Action on a FlexCard.
Add the Event Listener

2. In the Event Listener section, click + Add New.
3. Select a Custom or Pubsub Event Type.
4. To configure a Custom event, in the Event Name field, enter the name of the event, such as reload.
5. To configure a PubSub event:
a. In the Event Name field, enter the name of the event, such as reload.
b. In the Channel Name field, enter the channel in which the event is posted.
c. If your action type is Card, and type is remove, in the Record Index field, update the index to
indicate which record to remove. For example, enter 0, to remove the first record, or 3 to remove
the fourth record.
6. To create an action, see Create the Action.
Create the Action

1. In the Action Properties section, select an Action Type from the dropdown. See FlexCards Actions
Reference.
2. To configure the selected Action Type, see FlexCards Action Properties.
3. Click Save.
Download a Sample Event Listener DataPack

Download a sample FlexCard DataPack with configured Event Listeners. See Download a Sample Event
Listener DataPack.
See Also
• FlexCards Event Listener Properties
Download a Sample Event Listener DataPack

Download a sample Event Listener DataPack to import to your org. Create an event listener that listens for
an event happening and performs an action in response. See Add an Event Listener to a FlexCard.
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.

company 419
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.

company 420
1. Download the OmniStudio DataPack here: demoEventListener-OmniStudio.zip.

2. Import the Datapack. See Import a FlexCard.
3. If you didn't activate the FlexCards during the import process, from the FlexCards home tab, for each
FlexCard, click the FlexCard name, select the checkbox, and click Activate.
4. Add both FlexCards to a Lightning Page to preview and test the event listening feature. Add the
demoEventListener below the demoUpdateDataSourceEvent. See Add a FlexCard to a Lightning
Page.
See Also
• FlexCards Event Listener Properties

FlexCards Event Listener Properties

Event Listener properties are configurable from the Setup panel in the FlexCard Designer. Add a listener for
a PubSub or Custom event that is triggered when a user performs an action. See Add an Event Listener to
a FlexCard.

company 421

Event Type Select an event type. n/a
Event Name Enter the name of the event. n/a
Channel Name Enter the channel in which the event is posted. n/a
Record Index If your action type is Card, and type is remove, enter the number of the index n/a
that indicates which record to remove. For example, enter 0, to remove the first
record, or 3 to remove the fourth record.
Action Type Select the action that triggers the event. FlexCards Action
Properties
Enable Multi-Language Support on a FlexCard

Enable multi-language support on a FlexCard from the FlexCard Designer. When the Multi-Langauge
Support feature is on, all Custom Labels are updated and not cached. See Custom Labels.

2. Select Multi-language Support.
What's Next
Add custom labels to supported fields. See Add Custom Labels to Supported Fields on a FlexCard.
Enable OmniScript Support on a FlexCard

Enable the OmniScript Support feature when your FlexCard interacts with an LWC OmniScript. For
example, render a FlexCard inside an OmniScript with the OmniScript Designer's Custom LWC element.
See Embed FlexCards in an OmniScript. Or update an OmniScript with the Update OmniScript action
element. See Update an OmniScript from a FlexCard.

2. Select OmniScript Support.
3. Click Activate.
See Also
• Update an OmniScript from a FlexCard
• Launch an OmniScript from a FlexCard
Limit User Access to a FlexCard with Custom Permissions

Limit user access to a FlexCard by assigning custom permissions. Enter a list of custom permissions in the
Setup panel of your FlexCard to specify which users can view your FlexCard.
Before You Begin

Create custom permissions in Setup > Custom Permissions. See Create Custom Permissions.
1. From the FlexCard Designer, click Setup to open the Setup panel.

company 422
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:
global class VlocityRequiredPermissionCheck implements Callable

{
global Boolean call(String action, Map<String, Object> args)
{
if (action == 'checkPermission')
{
return
checkPermission((String)args.get('requiredPermission'));
}
return false;
}
private Boolean checkPermission(String requiredPermission)

{
Boolean hasCustomPermission = false;
List<String> customPermissionsName =
requiredPermission.split(',');
for (String permissionName : customPermissionsName)
{
Boolean hasPermission =
FeatureManagement.checkPermission(permissionName.normalizeSpace());
if (hasPermission == true)
{
hasCustomPermission = true;
break;
}
}
return hasCustomPermission;
}
}

company 423
e. Click Save.
See Also
Style FlexCard Elements

Configure the look and feel of a FlexCard by styling individual elements, fields inside elements, and entire
states. From the Style panel in the FlexCard Designer, design backgrounds, text, and borders; adjust
heights, widths, and spacing inside and between elements; apply classes and inline styles; make your
element responsive; and more.
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.
Style Options Available to All Elements

Style panel Description Reference
Section
Add Conditional Conditionally apply styles to an element. Change style features such as Add Conditional Styles to a
Style text color and responsiveness when a condition based on the value of a FlexCard Element
data field is met.
Alignment Update the padding, margin, and text alignment of an element. FlexCards Element Alignment
Properties
Appearance Configure the color, background, and border of an element. FlexCards Element Appearance
Properties
Custom Create and apply custom classes, and add inline styles to an element. FlexCard Elements Custom
CSS
Custom Styles Save style settings on a FlexCard element as a Custom Style to use on Create a Custom Style for a
multiple elements on a FlexCard.. FlexCard Element
Dimensions Set the height and configure the responsiveness of an element. FlexCards Element Dimensions
Style Options Available to Specific Elements

Style panel Section Reference
Action FlexCards Action Style Properties
Datatable FlexCards Datatable Style Properties
Field FlexCards Field Style Properties
Icon FlexCards Icon Style Properties
Menu FlexCards Menu Style Properties
Toggle FlexCards Toggle Style Properties

company 424
Add Conditional Styles to a FlexCard Element

Conditionally apply styles to a FlexCard element. Change style features such as text color, background
image, and responsiveness when a condition based on the value of a data field is met. For example, add a
red border around a billing FlexCard when the bill status is past due.
Required Versions
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.
7. (Optional) To edit a conditional style, click its pencil ( ) icon.

8. (Optional) To switch between how your element looks when the conditions are applied and not applied,
select the conditional style's toggle button ( ).
9. (Optional) To delete a conditional style, click its trash ( ) icon.

company 425
What's Next
See Also
FlexCards Conditional Style Properties

Add Conditional Style properties are configurable from the Style panel in the FlexCard Designer when you
select an element. Conditionally apply styles to an element depending on the value of a data field.

Conditional Style The name of your conditional style. N/A
Name
Add Conditions Add conditions that style elements based on data field values. Add Conditions to a
FlexCard Element
Add Groups Create complex expressions by grouping conditions. A group is similar to enclosing a Add Conditions to a
series of tests in parenthesis in a programming language. For example, to add a FlexCard Element
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].
Default The default styles apply when no conditions are met. N/A
See Also
FlexCards Element Dimensions

Set the height and width, and configure the responsiveness of a FlexCard element within the FlexCard
Designer. In addition to adjusting the width of an element by clicking and moving its drag markers left and
right on the canvas, use a slider on the Style panel to adjust the width. See Adjust the Width of an Element
on a FlexCard.
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.

company 426
See Also
• FlexCards Element Dimensions Properties

• Create Responsive Elements on a FlexCard
FlexCards Element Dimensions Properties

An element's Dimensions properties are configurable from the Style panel in the FlexCard Designer when
an element is selected. Update the height and width, and configure responsiveness for your element.

Default Set the default width of the element when Responsive is disabled. Adjust the Width of an
Element on a FlexCard
Height Set the height of the element. Enter any value allowed by the height CSS n/a
property, such as 10em, auto or calc(). If you enter just a number, the default
unit used is px. The percentage unit (%) is not supported.
Maximum Set the maximum height of the element. Enter any value allowed by the n/a
Height maximum-height CSS property, such as 10em, auto, or calc(). If you enter
just a number, the default unit used is px. The percentage unit (%) is not
supported.
Minimum Height Set the minimum height of the element. Enter any value allowed by the n/a
minimum-height CSS property, such as 10em, auto, or calc(). If you enter
just a number, the default unit used is px. The percentage unit (%) is not
supported.
Responsive Make your element adjust to the width of the viewport. After enabling, set the FlexCards Element
width of each viewport breakpoint. Responsiveness
See Also
Adjust the Height of an Element on a FlexCard

Update the height of an element on a FlexCard from the Style panel in the FlexCard Designer. Enter any
CSS supported values, such as length units (px, cm, and so on), inherit, auto, and so forth. Or enter a
CSS function, such as calc(2em * 5).
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:

company 427
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
See Also

• FlexCards Element Dimensions
Adjust the Width of an Element on a FlexCard

After dragging an element from the Build panel into a state, adjust its width along a 12-column horizontal
grid. The width of an element is 1 to 12 parts of a 12 column grid. For example, a field element that is 6
columns wide takes up 50% of the available horizontal space.
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.
1. In the FlexCard Designer, click an element in a state.

2. To adjust the width of an element inside a state, perform these tasks:
a. Hover over the square box on the right border until the mouse pointer icon becomes a drag icon.
b. Click and slide the square box right or left to make the element more narrow or wider.

company 428
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
• Adjust the Height of an Element on a FlexCard
FlexCards Element Responsiveness

In the FlexCard Designer, enable responsiveness on one or more elements to set the width to change as
the visible area of a page, called the viewport, changes. By default, the width of an element is the same
regardless of the width of the viewport device on which the user views the FlexCard. The width of an
element is 1 to 12 parts of a 12 column grid. For example, a field element that is 6 columns wide takes up
50% of the available horizontal space. See Adjust the Width of an Element on a FlexCard.
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.

company 429
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
Example 10. Example Responsive Subject and CaseId Field Elements

A user wants the Subject field and a CaseId Field element next to each other on the Medium and Large
viewports, but stacked on Small and Smaller viewports:
• 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.

company 430
Subject and CaseId responsiveness settings.
Subject and Caseid fields on larger and small viewports.
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

Enable an element's width to change when the viewport updates. For example, make the widths of the
fields for First Name and Last Name of a Contact take the full width of the page on smaller devices, but
shrink to 50% on larger devices such as laptops and desktops.
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

company 431
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
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.
3. For each viewport breakpoint, adjust the slider to set a width.

company 432
Example 11. Example Responsive Subject and CaseId Field Elements

A user wants the Subject field and a CaseId Field element next to each other on the Medium and
Large viewports, but stacked on Small and Smaller viewports:
• 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.
Subject and CaseId responsiveness settings.
Subject and Caseid fields on larger and small viewports.

4. To test the responsiveness of your elements, toggle between viewport widths from the Viewport
Dropdown. See View a FlexCard at Different Viewport Breakpoints.
What's Next
See Also

FlexCards Element Appearance

Update the appearance of your FlexCard elements with the Appearance properties in the Style panel of the
FlexCard Designer. Change the text color, background, border, and set a Salesforce theme for your
elements.

company 433
See Also
FlexCards Element Appearance Properties

Appearance properties are configurable in the Style panel of the FlexCard Designer when you select an
element. Update background, text color, border, and theme of your elements.
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
FlexCards Element Alignment

With Alignment properties in the Style panel of the FlexCard Designer, you can create space inside and
around your elements. You can also adjust the position of the text relative to the element's container.
See Also
FlexCards Element Alignment Properties

The Alignment properties of an element are configurable in the Style panel when an element is selected in
the FlexCard Designer. Configuring padding, margin, and text alignment.

company 434
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
• Add Space Inside a FlexCard Element

• Add Space Around Your FlexCard Element
Add Space Inside a FlexCard Element

Create space inside the container of a FlexCard element. Add padding to create space between the
boundary of your element and the contents inside your element.
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
• Add Space Around Your FlexCard Element

Add Space Around Your FlexCard Element

Create space around the container of a FlexCard element. Add margins between adjacent elements on
your FlexCard.
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.

company 435
See Also
• Add Space Inside a FlexCard Element

FlexCard Elements Custom CSS

Create, edit, and apply custom CSS classes and inline styles to your FlexCard elements in the FlexCard
Designer. When styling options available from the design interfaces of the Style panel don't meet your
design needs, create custom CSS classes from a code editor inside the designer, and apply them to
supported fields. Or, add inline styles to a specific element.
• Create and apply custom CSS within the FlexCard Designer:
1. Create Custom CSS Within the FlexCard Designer

2. Apply Custom CSS to a FlexCard Element
• Add Inline Styles to a FlexCard Element
See Also
FlexCards Custom CSS Properties

Custom CSS properties are configurable from the Style panel in the FlexCard Designer when you select an
element. When the design interfaces in the Style panel do not meet your design needs, apply a class from
any style sheet available to the FlexCard, or add inline styles.
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
• Add Inline Styles to a FlexCard Element

• Create Custom CSS Within the FlexCard Designer.
Create Custom CSS Within the FlexCard Designer

Create custom CSS classes within the FlexCard Designer to apply to FlexCard elements or supported
fields inside elements. Create custom CSS classes when the design interfaces in the Style panel do not
meet your design needs. See Style FlexCard Elements.
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.

company 436
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.
3. Enter your custom classes inside the code editor.

company 437
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
FlexCards 'Add Custom CSS' Properties

Add Custom CSS properties are configurable from the submenu of the FlexCard Designer. Create custom
CSS classes and add them to supported fields in the Properties and Style panels. See Create Custom CSS
Within the FlexCard Designer.

company 438
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
• FlexCard Elements Custom CSS

Apply Custom CSS to a FlexCard Element

When the design interfaces available in the Style panel of the FlexCard Designer don't meet your design
needs, apply custom CSS to your elements. Add custom CSS to edit the internal components of an
element or a child element. Use this feature sparingly to optimize performance.
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.
Example 12. Example Grouped Datatable Element with Alternating Background

Colors
You have a Datatable element that displays Account Cases grouped by case Type. You want to show
alternating background colors for all rows and set a different background color for the group heading. There
is no option in the Style panel for alternating row background colors. But you can enter a class for the group
heading. Use the Add Custom CSS feature to create two classes. An alt-table-rows class for the
Datatable element, and an alt-bg-group-wrapper class for the group heading.

company 439
Apply the alt-table-rows class to the element and the alt-bg-group-wrapper class to the group
heading.
1. In the FlexCard Designer, select an element on the canvas.

2. To apply a custom class to an element, click Style to open the Style panel. From the Custom CSS
section, complete one or both of these tasks:
• To append a custom class to the element's container, enter the class name in the Container Class
field, such as branded-tables.
• To append a custom class directly on the element, enter the class name in the Custom Class field,
such as alt-table-rows from the example above.
3. To apply a custom class to a specific field inside an element, in the Properties panel, enter a class in a
field that supports classes.
For example, from the previous grouped datatable example, enter alt-bg-group-wrapper in the
Group Wrapper Class field in the Properties panel of a Datatable element.

company 440
See Also
FlexCards 'Add Custom CSS' Properties

Add Custom CSS properties are configurable from the submenu of the FlexCard Designer. Create custom
CSS classes and add them to supported fields in the Properties and Style panels. See Create Custom CSS
Within the FlexCard Designer.
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

Add Inline Styles to a FlexCard Element

When styling options available from the design interfaces in the FlexCard Designer don't meet your design
needs, add inline CSS styles to an element on a FlexCard. Override classes and target specific elements or
element components.
TIP
Use this feature as needed and sparingly to optimize performance.
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
See Also
FlexCards Action Style Properties

Configure style properties specific to the Action element from the Style panel in the FlexCard Designer. To
configure additional style properties common to all elements, see Style FlexCard Elements.

company 441
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
FlexCards Datatable Style Properties

Configure style properties specific to the Datatable element from the Style panel of the FlexCard Designer.
To configure additional style properties common to all elements, see Style FlexCard Elements.
Property Description Applies To

Background Color Select a background color. Enter a Hex color code, such as #ff0000. Or click the Table, Cells, Table
colored box to select from a color picker. Head, Rows
Border Color Select a border color. Enter a Hex color code, such as #ff0000. Or click the Table, Cells
colored box to select from a color picker.
Border Type Select one or more border locations such as top, bottom, right, and left. Table, Cells
To remove a border location, select it again from the dropdown.
Border Width Enter a number for the thickness of the border in pixels. Table, Cells
Box Shadow Add a box shadow to cells. Enter a value allowed by the box-shadow CSS Cells
property, such as 2px 4px 3px #888888.
Font Family Enter one or more web-safe, SLDS, or Newport Design System fonts. Supports Table Head
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 Weight Enter a value allowed by the font-weight CSS property, such as bold, Table Head
lighter, 600, and so on.
Margin Size Select the size of the margins for all cells. Cells
Margin Type Select where to add margins to your cells, such as the bottom, both vertical Cells
spaces, both horizontal positions, around the entire cell, and so on.
Padding Size Select the size of the padding for all cells. Cells
Padding Type Select where to add padding to your cells, such as bottom, both vertical spaces, Cells
both horizontal positions, or around the entire cell, and so on.
Text Decoration Set the appearance of decorative lines on the text. Enter a value allowed by the Table Head
text-decoration CSS property, such as underline and overline.

company 442
See Also
• Create Custom CSS Within the FlexCard Designer
FlexCards Field Style Properties

Configure style properties specific to the Field element from the Style panel of the FlexCard Designer. To

Color Enter a Hex color code or click the colored square to select a color from the color picker. n/a
Font Family Enter one or more web-safe, SLDS, or Newport Design System fonts. Supports the font- n/a
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 n/a
1em, 6px, large or calc(). If you enter just a number, the default unit used is px.
Label Class Select a class for the field label. Select from a class defined in the Add Custom CSS Create Custom CSS
feature of the FlexCard Designer or any style sheet available to the FlexCard. Within the FlexCard
Designer
Text Align Select text alignment, such as center. n/a
Text Decoration Set the appearance of decorative lines on the text. Enter a value allowed by the text- n/a
decoration CSS property, such as underline and overline.
Value Class Select a class for the field value. Select from a class defined in the Add Custom CSS Create Custom CSS
feature of the FlexCard Designer or any style sheet available to the component. Within the FlexCard
Designer
See Also
FlexCards Icon Style Properties

Configure style properties specific to the Icon element from the Style panel of the FlexCard Designer. To

Extra Class Enter a class appended to the container of the element. Select from a class defined in Create Custom CSS
the Add Custom CSS feature of the FlexCard Designer or any style sheet available to Within the FlexCard
the FlexCard. Designer
Icon Color Enter a Hex color code or click the colored square to select a color from the color picker. n/a
See Also

company 443
FlexCards Menu Style Properties

Configure style properties specific to the Menu element from the Style panel of the FlexCard Designer. To
Color Enter a Hex color code or click the colored square to select a color from the color picker.
Size Select the size of the entire element, such as Medium.
See Also
FlexCards Toggle Style Properties

Configure style properties specific to the Toggle element from the Style panel in the FlexCard Designer. To
Checkbox Toggle, Button, and Group Properties

These properties are unique to the Checkbox Toggle, Checkbox Button, Checkbox Group Button,
Checkbox Group toggle types.
Text Align Select text alignment, such as center.
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.

company 444
Checkbox Button and Toggle Properties

These properties are unique to the Checkbox Toggle and Checkbox Button toggle types.
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.
Checkbox Button Properties

These properties are unique to the Checkbox Button toggle type.
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.
Checkbox Group Properties

These properties are unique to the Checkbox Group Button and Checkbox Group toggle types.
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 Toggle Element Type Reference
Create a Custom Style for a FlexCard Element

Save style settings on a FlexCard element as a Custom Style to use on multiple elements on your
FlexCard. For example, to apply the same font color, font size, text color, and background color to multiple
Field elements on a FlexCard, create a Custom Style called blue-field-scheme on one Field element.
Then apply blue-field-scheme to other Field elements as needed.
The Custom Style feature saves any settings configured in the Style panel including classes, inline styles,
widths, and responsiveness.
Create a Custom Style

1. In the FlexCard Designer, select an element from the canvas, and click Style to open the Style panel.
2. Style the element as needed. See Style FlexCard Elements.
3. To create a new style, from the Custom Styles section, click the down arrow, and select Save As.

company 445
4. Enter a style name in the Enter Style Name field.

5. Click Save.
Apply a Custom Style
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.

company 446
What's Next
See Also
FlexCards Custom Styles Properties

Custom Styles properties are configurable in the Style panel when you select an element in the FlexCard
Designer. Save style settings on a FlexCard element as a Custom Style to use on multiple elements on a
FlexCard. See Create a Custom Style for a FlexCard Element.
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
Display Records Side-By-Side on a FlexCard

Display records side-by-side instead of stacked on top of each other by embedding a child FlexCard and
adjusting the widths of its states. By default, records display one on top of the other regardless of the widths
of individual elements in the FlexCard.
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.
Create the Child FlexCard

1. Create a child FlexCard and add all the elements you want to display on each state. See Embed a
Child FlexCard Inside a FlexCard

company 447
2. Click a state, and click Style to open the Style panel.

3. From the Dimensions section, under Default, use the slider to adjust the width of the state to at most
6.
For example, to display two records next to each other, select 6. To display 3 records next to each
other, select 4. To display 4 records next to each other, select 3.
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. Repeat steps 2 and 3 for each state on your Child FlexCard.

5. Click Activate.
Embed the Child FlexCard in a FlexCard

1. Create a new FlexCard. See Create a New FlexCard. Or open an existing FlexCard from the
FlexCards home tab.
2. From the Build panel, drag a FlexCard element into an active state.
3. Click into Card Name and select the name of the child FlexCard you created in the above steps.

company 448
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.
Arrange, Duplicate, and Remove Elements on a FlexCard

Arrange, duplicate, and delete elements on the canvas of a FlexCard in the FlexCard Designer. Drag
elements onto the canvas, and rearrange them by dragging them below, above, and next to other elements.
Duplicate and remove elements with one click.
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.

company 449
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
Element (not a State)

4. To delete an element, click the element, and click the trash icon.
See Also
• Adjust the Width of an Element on a FlexCard
Pass Concatenated Strings As Values in FlexCards

Pass concatenated strings as the value for supported FlexCard element properties. For example, pass a
breadcrumbs path like {Parent.parentPath}>{Parent.type}>{Name} in the Value property of an
Attribute of a child FlexCard.
Required Versions

company 450
FlexCard Elements Supported Properties

FlexCard (child FlexCard), Custom LWC, Flyout Action Attributes > Value
Action, Menu, Block (when Collapsible is enabled) Label
Action > Action Type > Card Set Values > Value
Action > Action Type > Event Input Parameters > Value
Field Label, Output
Image Title
Enable Tracking on a FlexCard

Enable tracking from a FlexCard Action or Child FlexCard. Parent and Child FlexCards track the Card
Load, Card Unload, and State Load events. The Action tracks the UI Action event.
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
FlexCard Designer Preview

Preview your FlexCard's appearance and test functionality before publishing it to a Lightning or Community
page. Test how your FlexCard looks on multiple devices. Test the functionality of interactive elements such
as actions. Debug your FlexCard's data output, events, and actions.
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.

company 451
NOTE
The Navigate and OmniScript actions don’t work in Preview. Add them to a Lightning or
Community page to view them.
• Add Test Parameters

Enter additional test variables that your data source query can use to update your Preview.
• Viewport Dropdown
Adjust the size of your FlexCard's canvas to test for responsiveness. Use the Viewport Dropdown to
mimic the sizes of a desktop, laptop, and smaller mobile devices.
• FlexCard Designer Data JSON
View your FlexCard's data JSON. Look for potential issues in how your data source populates elements
on your FlexCard before publishing it or sending data to another component such as an OmniScript. The
Data JSON panel updates when you interact with the FlexCard.
• FlexCard Designer Action Debugger
View your FlexCard's action and event requests and responses from the Action Debugger. Click an
actionable item to display its log and associated events.
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.
Before You Begin

• Create a FlexCard and configure its data source. See Create a New FlexCard.
• Add elements to your FlexCard. See Add Elements to a FlexCard.
1. In the FlexCard Designer submenu, click Preview.
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.

company 452
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
FlexCards Preview 'Add Test Params' Properties

FlexCards Add Test Params properties are available when previewing a FlexCard in the FlexCard
Designer. Preview the FlexCard's appearance and functionality before publishing it to a Lightning or
Community page. Enter additional test variables that your data source query can use to update your
Preview.
See Preview a FlexCard.
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.

company 453
FlexCard Designer Data JSON

Use the Data JSON feature in the FlexCard Designer's Preview tab to see how your data source populates
the elements on the rendered cards of your FlexCard component. Detect potential issues at run time. The
Data JSON panel updates when you interact with the FlexCard, such as when entering data in an input field
or clicking an actionable item.
Required Versions
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.

company 454
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
View a FlexCard's Data JSON

View your FlexCard's data JSON from the Preview tab of the FlexCard Designer. Look for potential issues
in how your data source populates elements before publishing your FlexCard or sending data to another
component. The Data JSON panel updates when you interact with the FlexCard, such as when entering
data in an input field or clicking an action.
NOTE
If your FlexCard has a child FlexCard, only its name appears in the Data JSON panel.
Required Versions
1. In the FlexCard Designer, click Preview.

2. In the Data JSON tab, view data applicable your FlexCard visible in the Preview. Click the arrow next
to any object node to see its child nodes.
3. To confirm the records return as expected, click the records object in the dataSource object.
4. To confirm that the Data JSON updates when you interact with the FlexCard:
a. On the canvas, click an action that updates the data.
b. In Data JSON, click a rendered card object in the cards object to see the updated data.
c. If an action updates the data source, click an object in the dataSource config or records object
to view updates.
5. To view the state of the rendered card, see StateName under each cards object.
6. To view session variables created in the Setup Panel, click the Session object. See Add Session
Variables to a FlexCard.
See Also
• FlexCard Designer Data JSON

company 455
• Debug FlexCard Action and Event Requests and Responses
FlexCard Designer Action Debugger

Debug your FlexCard's client and server-side actions and events with the Action Debugger in the FlexCard
Designer's Preview tab. View requests and responses to see when and where errors occur to determine
how to fix them.
Required Versions
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

company 456
Debug FlexCard Action and Event Requests and Responses

View your FlexCard's action and event requests and responses from the Action Debugger in the FlexCard
Designer's Preview tab. Click an actionable item to display its debug log and associated events. Debug
before publishing your FlexCard to a Salesforce page or third-party application.
Required Versions
1. In the FlexCard Designer, click Preview.

2. Click the Action Debugger tab.
3. Click the arrow next to a Datasource to view its log.
4. Click the arrow next to an action or event label to view its log.
5. (Optional) To search for a specific event or action, enter a keyword in the Search input field.
6. (Optional) To copy a log, such as the config in Datasource or the inputMap in a Pubsub Event action,
click the clipboard icon next to the name of the property.
7. (Optional) To clear all logs, click Clear Logs.
See Also
• FlexCard Designer Action Debugger
• View a FlexCard's Data JSON

Adjust the size of your FlexCard's canvas to test for responsiveness. Use the Viewport Dropdown in the
FlexCard Designer to mimic the sizes of a desktop, laptop, and smaller mobile devices.
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.
2. To test responsiveness in Design view, select a breakpoint from the Viewport Dropdown.

company 457
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
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.

company 458
Before Your Begin

Preview your FlexCard's appearance and test functionality before activating it. See Preview a FlexCard.
Activate from the FlexCard Designer

2. Click Activate in the submenu to initiate the activation wizard.
3. Click Done.
Activate from the FlexCards Home

1. In the FlexCards home tab in your org, click on a FlexCard to view available versions.
2. Select the checkbox next to the inactive FlexCard you want to activate.
3. 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.
See Also
Configure Publish Options on a FlexCard

Define metadata values and update the component SVG icon for your generated FlexCard LWC before
publishing your component to a Lighting or Community page. For example, to view your FlexCard on a
Community page you can enable Community Page under Targets in Publish Options. See Add a
FlexCard to a Community Page.
Before You Begin

• You must activate your FlexCard to configure Publish Options. See Activate a FlexCard.
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.

company 459
FlexCards Publish Options Properties

FlexCard Publish Options properties are configurable after activating a FlexCard. Define metadata values
and update the SVG icon for your generated FlexCard LWC from the FlexCard Designer. See Configure
Publish Options on a FlexCard.

Master Label Update the visible name of generated LWC as you want it to appear in the Lightning Configuration File Tags
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. Configuration File Tags
API Version Defines the API version of your generated LWC. The default is the API version used Configuration File Tags
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. Configuration File Tags
Namespace
Is Exposed When enabled, your card component is public. By default, this feature is enabled. Configuration File Tags
Targets Select where your generated LWC is accessible. By default, HomePage, Configuration File Tags
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.
Editor Manually configure meta data values. For example, add properties to a Target. Configuration File Tags
Add SVG Add an SVG resource as a custom icon for your generated LWC to easily identify it Add a Custom
Resource in the Experience Builder for Communities and Lightning App Builder for Lightning Component SVG Icon
pages. to a FlexCard
See Also
Define Metadata Values from the FlexCard Designer

Define the metadata values for the generated FlexCard LWC. With the Publish Options feature in the
FlexCard Designer, configure the metadata values for your generated LWC from a GUI or code editor. See
Configuration File Tags.
Before You Begin

• You must activate your FlexCard to view the Publish Options feature. See Activate a FlexCard.
Options.
3. Enter or update values for these properties:

company 460
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.
Add Properties to a Target

To add properties to a Target, enter them manually from the Publish Options Editor.

company 461
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 Custom Component SVG Icon to a FlexCard

Add an SVG resource as the custom icon for your generated LWC to easily identify it in the Experience
Builder for Communities and Lightning App Builder for Lightning pages. Use the Publish Options feature
on an activated FlexCard to update the default icon with a custom SVG resource.
Before You Begin

• You must activate your FlexCard to view the Publish Options feature. See Activate a FlexCard.
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 Custom Labels to Supported Fields on a FlexCard

Add custom labels to supported FlexCard element fields. For example, add custom labels if your FlexCard
supports multiple languages. Custom labels are custom text values that can be accessed from Apex
classes, Visualforce pages, or Lightning components. The values can be translated into any language
Salesforce supports. See Custom Labels.
FlexCards support the {Label} merge field on the following elements:
Element Supported Fields

Field Label, Placeholder
Text Inside the Rich Text Editor

company 462
Element Supported Fields

Action Label
Before You Begin

1. View FlexCard element fields that support custom labels. See ???.
2. Confirm available custom labels in your org at Setup > Custom Labels. See Custom Labels.
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.
Pass Data from an LWC OmniScript to an Embedded FlexCard

To populate data fields and perform actions on a FlexCard embedded in an LWC OmniScript, you can pass
data from an OmniScript's data JSON to the FlexCard. Embed a FlexCard inside an LWC OmniScript with
the Custom Lighting Web Component element. See Embed FlexCards in an OmniScript.
There are three ways to pass data from the LWC OmniScript to the embedded FlexCard:
Options Description Reference

Pass a set of Use the records global context variable to map data from the LWC Map Data from an LWC OmniScript to
records OmniScript to an emdedded FlexCard. an Embedded FlexCard
Pass the Pass the recordId global context variable from the LWC OmniScript Pass the RecordId from an
recordId to the FlexCard. OmniScript to Run a Query on a
FlexCard
Pass a parent Pass a Parent object containing parent attributes to the FlexCard Pass a Parent Object from an LWC
object from the LWC OmniScript. The OmniScript is the parent of the OmniScript to Run a Query on a
embedded FlexCard. The Parent global context variable, such as FlexCard
{Parent.Id}, must be used in the FlexCard where the merge field
is supported.

company 463
Download a Sample DataPack

Download a sample DataPack that demonstrates how to pass a recordId, a Parent object, and a set of
records from the LWC OmniScript to an embedded FlexCard. See Download a Sample DataPack that
Passes Data from an LWC OmniScript to a FlexCard.
Map Data from an LWC OmniScript to an Embedded FlexCard

After embedding a FlexCard inside an LWC OmniScript, map records from the OmniScript to data fields in
the FlexCard. For example, populate a list of FlexCards from an array in an OmniScript. In this scenario,
the FlexCard uses data from the OmniScript instead of its own data source.
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 the RecordId from an OmniScript to Run a Query on a FlexCard

Pass the recordId context variable from an LWC OmniScript to an embedded FlexCard to run a query on
the FlexCard. The query returns the data that populates the FlexCard data fields and actions.

company 464
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.
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.
5. Click Activate.
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 a Parent Object from an LWC OmniScript to Run a Query on a FlexCard

Pass a Parent object from the LWC OmniScript to the FlexCard. The LWC OmniScript is the parent of the
embedded FlexCard. The Parent context variable must be used in the FlexCard where merge fields are
supported, such as {Parent.Id}. See FlexCards Context Variables.
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"}.
2. Configure your data source if you haven't already in Step 1. See Configure a Data Source on a
FlexCard.

company 465
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.
6. Click Activate.
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
Download a Sample DataPack that Passes Data from an LWC OmniScript to a

FlexCard
Download a sample DataPack that demonstrates how to pass data from an LWC OmniScript to a FlexCard.
Import the DataPack to your org. See Pass Data from an LWC OmniScript to an Embedded FlexCard.
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.

company 466
• A getCases DataRaptor gets a list of Account Cases.

1. Download the OmniStudio for Vlocity DataPack here: demoPassDataLWCOStoFC.zip.
NOTE
Download the OmniStudio DataPack here: demoPassDataLWCOStoFC-OmniStudio.json.
NOTE
installed.
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

company 467

Reload a FlexCard After Updating an LWC OmniScript in a Flyout

Update information on a FlexCard after saving changes to an LWC OmniScript embedded in a flyout. Add a
Flyout action on a FlexCard that triggers an event, and create an event listener on the card to refresh.
When the card you want to refresh "hears" the event, it executes a Card Reload action.
Before You Begin

1. Create an LWC OmniScript, to embed in your FlexCard flyout. See Create an OmniScript.
2. Add a Navigation Action, and select Pub/Sub in the Messaging Framework section of the Properties panel.
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
Add a FlexCard to a Lightning Page

After creating and activating your FlexCard, publish your generated component to a Lightning page with the
Lightning App Builder. See Lightning App Builder.
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.

company 468
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.
Add a FlexCard to a Community Page

Add your FlexCard to a Community page. After activating your FlexCard, publish the generated FlexCard
LWC from the Experience Builder.
See Experience Builder Overview.
Before You Begin

Activate your FlexCard. See Activate a FlexCard.
1. To access the Experience Builder, see Navigate Experience 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, find the name of your generated
FlexCard LWC and drag it to the canvas area.
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.
Run FlexCards Outside of Salesforce with OmniOut

Run FlexCards off-platform on third-party websites with OmniOut for FlexCards. Display FlexCards and
connect to Salesforce from a content management system's (CMS) external website. Run a 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.
See OmniOut.
Required Versions
Access the ContextId of a FlexCard on a Community Page

On a Community page, to view record data on a FlexCard that uses the {recordId} context variable in an
Input Map to pass a ContextId to an Apex Remote, DataRaptor, or Integration Procedure data source, you

company 469
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}.
Configure Community Profiles for FlexCards

Ensure that your users see FlexCards on Community pages by configuring user profile settings. Enable the
appropriate interface first. Then configure custom object permissions and Apex class access.
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.

company 470
Disable Enhanced Profile User Interface

Enable the appropriate interface before configuring Community profile settings that ensure that your users
see FlexCards on Community pages. Use the Original Profile Interface.
See Configure Community Profiles for FlexCards.
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
Configure Custom Object Permissions for Community Profiles

Configure custom object permission to ensure that your users see FlexCards on Community pages. Give
access to the necessary objects.
Before You Begin

• Ensure that you're using the Original Profile Interface. See Disable Enhanced Profile User Interface.
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.
Grant Apex Class Access to a Community Profile

Configure Apex class access to ensure that your users see FlexCards on Community pages. Give access
to the necessary Apex classes.

company 471
Before You Begin

• Ensure that you're using the Original Profile Interface. See Disable Enhanced Profile User Interface.
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.
FlexCards Versioning and Cloning

FlexCards supports versioning and cloning. You can create an identical copy of a FlexCard based on how
you want to use the new version.
Purpose Version or Clone?

To update a FlexCard already published on Lighting or Community pages, and elsewhere. Version
To make slight modifications to an existing FlexCard to test behavior and layout. Version
To create a new FlexCard but copy over layout, settings, or both. Clone

company 472
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.

company 473
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
Create a New Version of a FlexCard

Create a new version of a FlexCard in the FlexCard Designer when you want to make slight modifications
to a current. Creating a version of a FlexCard makes an exact copy with a version number equal to the
latest version number plus one. For example, if you already have two versions, the new version number will
be 3.
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.

company 474
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.
Left: Original FlexCard. Right: New version of FlexCard.
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.

company 475
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
• 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.

company 476
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.
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
• FlexCards Clone Properties
FlexCards Clone Properties

This page lists FlexCards Clone Card properties available when cloning a FlexCard in the FlexCard
Designer.
Create an identical copy of a FlexCard with the Clone feature in the FlexCard Designer. See Clone a
FlexCard.

Card Name Enter the Name of your FlexCard. FlexCard Naming
Conventions
Card Title Enter a title for your FlexCard. The title is used to find your generated FlexCard n/a
LWC after activation in the Lightning App Builder and Community Builder
Theme Select a theme to determine the default design of your FlexCard. n/a
Card Author Enter the author of the FlexCard, such as the name of a department in your n/a
organization.
Is Child Card Enable to embed this FlexCard inside another FlexCard. Embed a Child FlexCard
Inside a FlexCard
Description Enter a description of your FlexCard. n/a

company 477
FlexCard Naming Conventions

Follow requirements when naming FlexCards and FlexCard elements to prevent errors when working with
the FlexCard Designer and importing FlexCards as datapacks. For example, you may run into issues when
importing a FlexCard with the same name as one that already exists in your org.
FlexCard Naming Requirements

Requirements Examples
The combination of the card Name and Author must be unique in your Org. For example, • Name = AccountActive, Author =
if importing a FlexCard with the same name and author of a current FlexCard, you will be CustomerSales
asked if you want overwrite the current FlexCard in your org. • Name = AccountClosed, Author =
CustomerSales
The name and author must only contain underscores and alphanumeric characters. It must Not acceptable:
be unique, begin with a letter, not include spaces, not end with an underscore, and not
contain two consecutive underscores. • account$card!
• 2account__card
• $$account__card_
• account card
If you have multiple versions of a FlexCard, only one version can be active at a time. See N/A
FlexCards Versioning.
FlexCard names cannot be changed. You must clone a FlexCard to change the name. See N/A
Clone a FlexCard.
FlexCard Element Name Requirements

Requirement Examples
• Element Names cannot contain spaces and must be unique in Acceptable:
a FlexCard. It can contain any string combination of
alphanumerical and special characters. • address_block
• View_Account
• $account_revenue!
Not acceptable:
• address block
• View Account
• $account revenue!
See Also
Delete a FlexCard
Delete a FlexCard from the FlexCards home tab in your org. Once deleted it cannot be retrieved.
Before You Begin

• Deactivate the FlexCard you want to delete by clicking the Deactivate link in the submenu of the FlexCard Designer or the FlexCards
home tab.

company 478
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.
3. Click the trash icon.
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.
Before You Begin

Export a FlexCard.
1. From the FlexCards home tab, click Import.

2. Click Upload Files and select a DataPack from your computer to upload. Or, drag the file from the
computer to the Or drop files section.
3. Click Next.
4. Select the items to import.
5. Click Next.

company 479
6. Review the items to import.

7. Click Next.
8. To activate items from the imported FlexCard:
a. Click Activate Now.
b. Select the items to activate.
c. Click Next.
d. Click Done.
9. To activate items from the imported FlexCard later, click Activate Later.
See Also
• Data Migration with OmniStudio DataPacks
Download FlexCard Sample DataPacks

Download sample FlexCard DataPacks with configured FlexCard elements and settings to import into your
org. For example, download a FlexCard DataPack that displays how to pass data from a parent FlexCard to
a child FlexCard.
NOTE
Feature Description Reference

Pass Data from an An LWC OmniScript that passes data to embedded FlexCards in three Download a Sample
LWC OmniScript to ways: by passing an object node with a data set; by passing the recordId; DataPack that Passes Data
an Embedded and by passing a Parent object. from an LWC OmniScript to a
FlexCard FlexCard
Custom Event Action A FlexCard with an Event Listener that listens for a Custom Event from Download a Sample Custom
its embedded child FlexCard. The child FlexCard's Custom Event action Event DataPack
updates a data field value on the parent when clicked.
Datatable A FlexCard that displays a grouped, searchable, and sortable Datatable Download a Sample
element. Datatable DataPack
Event Listener Add an event listener that listens for an event and executes an action in Download a Sample Event
response. Listener DataPack
Pass Data to a Child Embed a reusable FlexCard as a child inside the state of a parent Download a Sample Child
FlexCard FlexCard and pass data from the parent to the child. FlexCard DataPack
Pubsub Event Action A FlexCard with three action elements that trigger events that update Download a Sample Pubsub
data field values. Event DataPack

company 480
Feature Description Reference

Toggle Element A FlexCard displaying all Toggle element types, with Update Data Download a Sample Toggle
Source enabled on two elements and a Set Values Card Action DataPack
configured on one element.
Update OmniScript Prefill an OmniScript when a user clicks an Update OmniScript action Download a Sample Update
Action from a FlexCard embedded in the OmniScript. Includes the FlexCard and OmniScript Action DataPack
the OmniScript.
See Also
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
1. To export from the FlexCards home tab:

a. Click a FlexCard, and select the checkbox for the version to export.
b. Click Export.
2. To export from the FlexCard Designer:
a. From the FlexCards home tab, click a FlexCard, and click a version to open in the FlexCard
Designer.
b. Click the down arrow in the submenu and select Export.
3. Select the items to export.
4. Click Next.
5. Review the items to export.
6. Click Next.
7. (Optional) Update the Name.
8. (Optional) Update the Description.
9. To store the DataPack and access it later from the Vlocity DataPacks tab, select Add to Library.
10. To download the DataPack to your computer, leave Download selected.
11. Click Done.
What's Next
Import a FlexCard to another environment. See Import a FlexCard.

company 481
See Also
Download a FlexCard LWC from the FlexCard Designer

Download your FlexCard LWC from the FlexCard Designer. Download your LWC to debug and inspect
issues.
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.
Before You Begin

• You must activate your FlexCard to download its LWC.
2. From the FlexCard Designer submenu, click the down arrow next to Activate, and click Download
LWC.
3. Click Done.
See Also
Download an Off-Platform FlexCard LWC from the FlexCard

Designer
Download an off-platform FlexCard LWC from the FlexCard Designer. Download your LWC to inspect code.

company 482
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.
Before You Begin

• You must activate your FlexCard to download its generated LWC.
2. From the FlexCard Designer submenu, click the down arrow next to Activate, and click Download
Off-Platform LWC.
3. Click Done.
See Also
FlexCards Context Variables

Global and local context variables are available to a FlexCard to provide context to data sources, actions,
and other components. All variables are case sensitive.
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}
For example, {Params.Id} gets the context Id.

We recommend using {recordId} to get the
ContextId of a record.
Parent Reference attributes from the parent FlexCard on the child {Parent.attributeName}
FlexCard with this variable. Attributes are defined at design time
on the parent FlexCard. See Embed a Child FlexCard Inside a For example, Parent.Id gets the {Id} attribute
FlexCard. defined on the parent FlexCard.

company 483

recordId Gets the context Id of a Salesforce object's data record. Use Test {recordId}
Parameters to verify in Preview. See Test Data Source Settings
on a FlexCard. For example, if using a DataRaptor to get a list of
Account Cases, in the Input Map, enter
AccountId as Key and {recordId} as the
Value. Then add a Test Parameter whose Key is
recordId and Value is 138238279r9ff to
populate your FlexCard with actual data.
records The records object of the FlexCard, which can be passed on to {records}
Child FlexCard, Custom LWC, and Flyout parameters.
For example, {records} gets all records, while
{records [0]} gets the first available record.
Session Variables used to store values from data sources, external {Session.sessionkey}
systems and hardcoded values. Properties are defined at design
time on the FlexCard. See Add Session Variables to a FlexCard. For example, {Session.pageLimit} gets a
session variable named pageLimit.
User User and Contact properties for the logged-in user. {User.property}
For example, {User.userName} gets the logged

in user's username.
NOTE
Rendered User context variable is
viewable at run time only. View in Preview.
Available properties:
• userId: User's Salesforce Id.

• userAnLocale: User's personal locale.
• userSfLocale: Salesforce org's locale.
• userCurrency: User's default currency.
• userLangudge: User's default language.
• userTimeZone: User's timezone.
• userName: User's username.
• userType: User's license type.
• userRole: User's role.
• userProfileName: Profile name from the Profile lookup.
• userProfileId: Salesforce Id from the Profile lookup.
• userAccountId: Salesforce id from the Account lookup.
• userContactId: Salesforce id from the Contact lookup.
Local Variables
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}.

company 484

element The values set by the toggle element and tied to an action. {element.value}, {element.checked}
• Checkbox Toggle type: element.checked

• All other Toggle types: element.value
record The record object that belongs to the State, and passed on {record}, {record.FieldName}
to Child FlexCard, Custom LWC, and Flyout parameters.
For example, {record} gets the entire record, while
{record.Name} gets the Name field from the record.
FlexCards Troubleshooting Considerations

When working within the FlexCard Designer, you may run into issues that require some troubleshooting to
resolve. Before contacting support, consider these troubleshooting articles.
• Update Remote Site Settings to Preview Your FlexCard

Grant access to your org domains to enable LWC features such as Preview. When spinning a new org or
new installation, the Tooling API calls necessary for LWC may fail if the Remote Site Settings page in
your org does not include the URLs required.
• 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 to Vlocity Card Designer.
• Fix Cyclic Redundancy When Embedding FlexCard Components
When you embed components, such as flyouts, Custom LWCs, and Child Cards, check that components
are not called multiple times.
Update Remote Site Settings to Preview Your FlexCard

Grant access to your org domains to enable LWC features such as Preview. When spinning a new org or
new installation, the Tooling API calls necessary for LWC may fail if the Remote Site Settings page in your
org does not include the URLs required. The required URLs are your org's lightning.force.com URL and the
visualforce.com URL of the Visualforce page that contains the FlexCard Designer.
Manually Update Remote Site Settings (URLs Provided)

If you see a Warnings button in your OmniStudio FlexCards home tab, add missing URLs to your Remote
Site Settings.

company 485
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.
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.
Example 13. Example

When you click on the link to a FlexCard called EmployerApplication on the FlexCards home tab, it
displays the record detail page, such as the one in the following image, instead of the FlexCard Designer.

company 486
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.
Fix Cyclic Redundancy When Embedding FlexCard Components

When you embed components, such as flyouts, Custom LWCs, and child FlexCards, check that
components are not called multiple times. If you add components that call themselves or call other
components embedded inside components, you may create cyclic redundancy causing events to
continuously fire in your browser, exceeding your maximum call size stack.
Example 14. Example

Your FlexCard has a child FlexCard that calls an OmniScript that also calls the same parent FlexCard from
a flyout.
Solution
Confirm what components are called inside an embedded component before adding it to a FlexCard. Update the components that might
cause cyclic redundancy.

company 487
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.
Before You Begin

1. Ensure you have a Content Management System built.
2. Install Node and npm. See Installing Node.
3. Download Visual Studio Code. See Visual Studio Code.
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:

company 488
• 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.
Download the OmniOut Static Resource

Download the OmniOut Static Resource from your Salesforce Org. The OmniOut static resource includes
JS, HTML, CSS, and other files necessary for OmniScripts and FlexCards to run outside of Salesforce.
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
Install OmniOut Dependencies

Configure and install the OmniOut dependencies using a command-line-tool. Install the tools necessary to
build your OmniOut app and view it locally.
Before You Begin

1. Download the LWC OmniOut static resource. See Download the OmniOut Static Resource.
2. Request an NPM repository access key from your Vlocity customer representative.
3. Understand how to run commands in a terminal. See Command Line 101 (git-tower documentation).
4. Install npm. See npm (npm documentation).
1. Uncompress the downloaded static resource.

2. In the uncompressed folder, open the .npmrc file and set _auth equal to your NPM repository access
key.
_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

company 489
For FlexCards, Add a FlexCard LWC 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
Include Nested Custom LWCs in Your OmniOut OmniScript

Map nested custom Lightning web components in your OmniScript to include them in your OmniOut project.
Lightning web components that override or map to an OmniScript element are automatically downloaded
with the off-platform OmniScript LWC.
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.
4. Save and Activate your OmniScript.
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

company 490
Add an OmniScript Lightning Web Component to OmniOut

Download and configure an OmniScript to use it off-platform in OmniOut. Download your OmniScript LWC
from the LWC OmniScript Designer, add the component folder to the OmniOut project, and configure files
for HTML and CSS.
Before You Begin

1. Install OmniOut's required dependencies. See Install OmniOut Dependencies
2. (Optional) Configure OmniScript to include nested custom Lightning web components in OmniOut. See Include Nested Custom
LWCs in Your OmniOut OmniScript.
1. Open an OmniScript in your Salesforce org, and click Activate.

2. Click the Download Off Platform LWC button and uncompress the downloaded file.
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.

company 491
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.
import VlocApp from 'vlocityomniscript/

typeExampleSubtypeExampleEnglish';

company 492
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));
8. (Optional) In the OmniScript component tag, remove the run-mode="localScriptDef" attribute to

check if the OmniScript is active in Salesforce.
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.
<link rel="stylesheet" type="text/css" href="/newport/assets/styles/

vlocity-newport-design-system.min.css">
11. In Index.html, uncomment the appropriate Script file for each of these elements that exist in your
OmniScript:

company 493
Element Script File

PDF Action <script src="/vlocityresources/javascript/VlocityPdf.js"></script>
Type Ahead Block Uncomment this file, and in the key parameter, enter your API key.
using Google Maps
<script type="text/javascript" src="https://maps.googleapis.com/
maps/api/js?key={YOUR_API_KEY_HERE}&libraries=places">
</script>
12. In Index.html, include the SLDS styles even when using Newport styles, if these elements exist in your
OmniScript:
Element Style Sheets Note

File  LWC OmniOut supports file
<link rel="stylesheet" type="text/css" href="/slds/assets/ uploads up to 30 MB.
styles/salesforce-lightning-design-system.css">
<link rel="stylesheet" type="text/css" href="/
vlocityresources/slds/styles/OmniLwcUtilsCss.css">
Image  LWC OmniOut supports
<link rel="stylesheet" type="text/css" href="/slds/assets/ image uploads up to 30
styles/salesforce-lightning-design-system.css"> MB.
13. Save your file.
14. Run the command npm run watch in your terminal console to restart the server and view your
OmniScript.
What's Next
Create a Connected App for OmniOut
See Also
• OmniOut
• Run OmniOut in Development Mode
• Configure Multi-Language in OmniOut for OmniScripts
Add a FlexCard LWC to OmniOut

Download and configure a FlexCard to use it off-platform in your OmniOut project. Download your FlexCard
LWC from the FlexCard Designer, add the component folder to the OmniOut project, and configure files for
HTML and CSS.
Before You Begin

1. Install OmniOut's required dependencies. See Install OmniOut Dependencies
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.

company 494
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.
import FlexCardProducts from 'flexcards/accountproducts';

b. Configure the FlexCard for HTML by defining a custom element and connecting it to your
component.
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.
<link rel="stylesheet" type="text/css" href="/newport/assets/styles/

vlocity-newport-design-system.min.css">
9. In Index.html, include the SLDS styles even when using Newport styles, if the Image element exists in
your FlexCard.
Element Style Sheets Note

Image  OmniOut supports image
<link rel="stylesheet" type="text/css" href="/slds/assets/ uploads up to 30 MB.
styles/salesforce-lightning-design-system.css">
10. Save your file.
11. Run the command npm run watch in your terminal console to restart the server and view your
FlexCard locally.
Create a Connected App for OmniOut

Enable the external connection to interact with Salesforce by configuring a Connected App in Salesforce.
Create a Connected App to make external calls from OmniOut. Connected Apps provide OmniOut with an
access token that enables proxies and login authentication to work.
See Connected Apps.

company 495
Before You Begin

• For OmniScripts, add an OmniScript LWC to your OmniOut project. See Add an OmniScript Lightning Web Component to OmniOut.
• For FlexCards, add a FlexCard LWC to your OmniOut project. See Add a FlexCard LWC to OmniOut.
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.
curl -d "username=USERNAME" -d "password=PASSWORD" -d

"client_id=CLIENTID" -d "client_secret=CLIENTSECRET" -v -d
"grant_type=password" https://test.salesforce.com/services/oauth2/token
b. In the command, replace these values:
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

company 496
See Also
• OmniOut
• (For OmniScripts) Configure Multi-Language in OmniOut for OmniScripts
Configure Multi-Language in OmniOut for OmniScripts

Display multi-language OmniScripts in OmniOut using custom labels. Access custom labels in your
OmniScript directly from Salesforce or use custom labels defined in local files. Control which language
displays by using a language code.
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.
Before You Begin

1. Create a multi-language OmniScript. See Create Multi-Language OmniScripts.
2. Add your multi-language OmniScript to an OmniOut LWC. See Add an OmniScript Lightning Web Component to OmniOut.
3. View Salesforce language codes. See Translations (Salesforce documentation).
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:
npm run customlabels LANGCODE

2. View these two generated files:
• LANGCODE.translations.js: contains all of the custom labels, both user-defined and out-of-the-box,
in a single file. The language code replaces the LANGCODE property used in this example file
name.
• translations.js: contains the exports of all different translations for all of the custom labels.
3. In translations.js, uncomment export lines to include them when the OmniScript is running.
export * from "./es.translations.js";

4. Pass the language code using a combination of these two options:
NOTE
If both options are present, the component tag property overrides the URL parameter.
Language Code Description Example

Option
Component Tag Passes the language code in the OmniScript's <my-omniscript prefill='\
Property component tag as a prefill property. {"LanguageCode":"iw"}'> </my-
omniscript>

company 497
Language Code Description Example

Option
URL Parameter Append the LanguageCode parameter to your localhost:4002/myOmniScript?
URL endpoint and enter a Salesforce language LanguageCode=en_US
code.
5. (Optional) In the OmniScript component tag, add the run-mode="localScriptDef" attribute to force the
OmniScript to use the locally defined custom labels. If run-mode isn’t present, a connection is made to
retrieve the custom labels from Salesforce.
6. (Optional) If you’re using run-mode="localScriptDef" in your OmniScript component tag, you must
define custom translations for each language manually.
To define your custom labels:
a. In OmniOut, select a LANGCODE.translations.js file.
b. In your file, locate a key-value pair, and in the value field, enter the translation for that custom
label. Repeat this process for each custom label.
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
See Also
• OmniOut

View and test your OmniScript and FlexCard before adding it to your application by running it in
development mode. Use a jsForce connection to request data from your org.
See jsForce on GitHub.
Before You Begin

1. Download your Lightning web component and add it to OmniOut. For OmniScripts, see Add an OmniScript Lightning Web
Component to OmniOut. For FlexCards, see Add a FlexCard LWC to OmniOut.
2. Create a Salesforce Connected App to enable a Salesforce API connection from your app. See Create a Connected App for
OmniOut.
1. In the .src folder's index.html file, locate function JSForceConnectionExample().

company 498
2. In the const connection object, enter the Salesforce Connected App's access token and instance
URL. See Access Token.
const connection = new jsforce.Connection({ // Set your jsForce

configuration here
accessToken: '',
instanceUrl: ''
});

company 499
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
• Connect Your OmniOut App
Navigate to a URL from an OmniScript in an OmniOut App

Direct users to different URLs from an OmniScript in an OmniOut app using the Navigate Action. Configure
endpoints in the Navigate Action and create redirects for the URLs in your OmniOut app. OmniOut supports
all Navigate Action types, including URL generation and browser location updates. Application authors must
decide how to handle the generated URLs based on the project's unique requirements.
Before You Begin

Configure a Navigate Action. See Navigate Action.
1. View the generated URL format for each of these Navigate Action page reference types:
Page Format URL Example

Reference
Type
App /{appName}/{pageReference} /vlocity-digital-studio/omni-script-
home
Knowledge /{articleType}/{articleURL} /vlocity-ins-knowledge/new-test
Article
Lightning /cmp/{componentName}? /cmp/exampleComponent?
Component {...targetParameters} c__exampleParameter=ABC123
Login Page /login /login
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}

company 500
Page Format URL Example

Reference
Type
Record /r/{sObjectApiName}? /r/case?
Relationship id={objectId}&rel={relationshipApiName} id=0012E00001qF0l2QAC&rel=CaseComments
Page
Vlocity /vlocityomniscript/ /vlocityomniscript/
OmniScript {OmniScriptComponentName} demoNavigateActionEnglish
Web Page A web URL. Navigate Action doesn’t format Web <https://trailhead.salesforce.com>
Page URLs.
2. (Optional) If your application has a predetermined URL structure that doesn’t match the generated
URL, take these steps to redirect the URLs:
a. In the OmniOut project, create this file ./src/modules/vlocityoverride/redirects.js
b. In redirect.js, add a map object to contain your redirect mappings.
const redirects = new Map([
]);
export default redirects;

c. In the redirects object, add a key that maps the generated URL and a value representing the
transformed URL. Each key and value must start with /. For example, map any Navigate action
that generates the URL /home to /my-custom-home.

['/home','/my-custom-home']
]);
export default redirects;

d. (Optional) Include wildcards in your URL to redirect all object pages to a single page. For example,
redirect case object and case record navigate actions to a single page with the endpoint /case.
Each of these generated URLs: /o/case/home, /r/case?id=0012E00001qF0l2QAC, and /r/case?
id=0012E00001qF0l2QAC&rel=CaseComments would point to /case. The URL parameters for
each generated URL is preserved.

['/home','/my-custom-home'],
['/*/case', '/case']
]);
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.

company 501
See Also
• OmniOut
• Add Custom Style Sheets to Your OmniOut Application
Navigate to a URL from a FlexCard in an OmniOut App

Direct users to different URLs from a FlexCard in an OmniOut app using the Navigate action type. OmniOut
for FlexCards supports only the Web Page target type. Application authors must decide how to handle the
generated URLs based on the project's unique requirements.
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.

2. Select Navigate as the Action Type.
3. Select Web Page as the Target Type. See PageReference Types.
4. Enter the URL in the URL field.
Target In dropdown.
Properties.
What's Next
See Also
• Navigate from a FlexCard with the Navigate Action

• OmniOut

Generate a compiled dist folder to move OmniOut into your app project before deploying your app to a
content management system.

company 502
Before You Begin

• For OmniScripts, Add an OmniScript Lightning Web Component to OmniOut.
• For FlexCards, Add a FlexCard LWC to OmniOut.
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.
npm run build

company 503

company 504
2. In the dist folder, copy the required OmniScript and FlexCard files from the OmniOut project to your
App.
File/Folder Required? Description

app.js files, including numbered app.js files, Yes The JavaScript files required for your FlexCard or
such as 0.app.js OmniScript.
vlocityresources Yes The static resources required for your FlexCard or
OmniScript.
index.html Optional A sample index.html file that shows how to run the OmniOut
LWC project.
newport Optional This file is required if you are using the default Newport
theme. If your OmniScript has an Image or File element, or
your FlexCard contains an Image element, you must also
copy over the slds folder.
slds Optional This file is required if you’re using the Lightning theme. If
your OmniScript contains an Image or File element, or your
FlexCard contains an Image element, you must copy over
the slds folder.
OmniScriptDocuSignReturnPage.html Optional This file is required if there’s a DocuSign Action in the
OmniScript.
OmniScriptLwcDocuSignViewPdf.html Optional This file is required if there’s a DocuSign Action in the
OmniScript.
3. In the index.html file, select and copy the script tags that reference app.js files into your app's
index.html file.
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>

company 505
What's Next
Connect Your OmniOut App
See Also
• OmniOut
Add OmniScripts to Adobe Experience Manager

Add OmniScripts to Adobe Experience Manager using OmniOut. OmniScripts hosted in AEM require a
Salesforce connection to send data between servers.
Before You Begin

1. Learn about OmniOut. See OmniOut.
2. Test your OmniScripts in OmniOut's development mode. See Run OmniOut in Development Mode.
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.
Integrate Salesforce Cloud Services into Adobe Experience Manager

Create a Salesforce connection in AEM. The connection setup is not part of the Vlocity package.
Before You Begin

1. View AEM's Salesforce Cloud Connection documentation. See Configuring AEM to integrate with Salesforce (AEM documentation).
2. Create your Connected App. See Create a Connected App for OmniOut.
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.

company 506
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
Set the OmniOut Resource Path

Load your custom styling resources into your Adobe Experience Manager application by setting the correct
resource paths.
Before You Begin

1. Ensure you have run OmniOut in development mode. See Run OmniOut in Development Mode.
2. Create a Salesforce connection in AEM. Integrate Salesforce Cloud Services into Adobe Experience Manager.
1. In VisualStudio, locate and open OmniOut's ./src/index.js file.

2. In the ./src/index.js file, uncomment this line:
import { setSldsResourcesUrl, setNewportResourcesUrl } from 'c/

salesforceUtils'
3. In the same ./src/index.js file, locate the setSldsResourcesUrl function and the
setNewportResourcesUrl function and uncomment each function.
4. Save your file.
What's Next
See Also
• OmniOut
• Add OmniScripts to Adobe Experience Manager

Add your AEM credentials to OmniOut and deploy it to your AEM server. The deployment adds a Vlocity
LWC OmniOut component to AEM. The Vlocity LWC OmniOut component enables you to add your
OmniScripts to an AEM page.

company 507
Before You Begin

1. Create a Connected App. See Create a Connected App for OmniOut
2. Create a Salesforce Connection in AEM. See Integrate Salesforce Cloud Services into Adobe Experience Manager.
3. Set your CSS resources path. See Set the OmniOut Resource Path.
4. Locate and copy your AEM server username, password, host, and port.
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:
npm run deploy:aem:clean:full
What's Next
Add the Vlocity LWC OmniOut Component to Adobe Experience Manager
See Also
• OmniOut
• Integrate Salesforce Cloud Services into Adobe Experience Manager
Add the Vlocity LWC OmniOut Component to Adobe Experience Manager

Launch OmniScripts from an AEM page by adding the Vlocity LWC OmniOut Component. The Vlocity LWC
OmniOut component hosts the OmniScript and uses the Salesforce Cloud Services configuration to make
calls to Salesforce.
Before You Begin

1. Set the OmniOut Resource Path.
2. Integrate Salesforce Cloud Services into Adobe Experience Manager.
3. Deploy OmniOut to 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:

company 508
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
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
Add Custom Style Sheets to Your OmniOut Application

Include custom styling in your OmniOut project by using style sheets. Custom stylesheets aren’t included in
the OmniScript or FlexCard off-platform download metadata. You must add them to your application after
building the dist folder.
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.
Before You Begin

1. For OmniScripts, create, then add a custom style sheet to your OmniScript. See Apply Custom Styling to OmniScripts with Static
Resources.
2. Build an OmniOut dist folder and move the folder's contents into your app. See Move OmniOut into Your App.

company 509
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
<link rel="stylesheet" type="text/css" href=".../styles/my-custom-

styles.css">
What's Next
See Also
• OmniOut

OmniOut connects your CMS to Salesforce through a proxy or directly. Configure a connection object to
connect to the Salesforce Connected App. Connections are unique to your app's requirements and must be
configured outside the scope of OmniOut.
View the connection object template and sample apps in this section to see examples of how to configure a
connection.
Before You Begin

1. Add your OmniScript or FlexCard to OmniOut. For OmniScripts, see Add an OmniScript Lightning Web Component to OmniOut. For
FlexCards, see Add a FlexCard LWC to OmniOut.
2. Create a Connected App for OmniOut
1. (Optional) Download, run, and modify sample OmniOut apps. See Sample OmniOut Apps.
2. Create a Connection Object in OmniOut
Sample OmniOut Apps

Download, configure, and run OmniOut sample apps to view OmniOut app connection examples. After
running the sample app, modify it to host your OmniScripts and FlexCards.
Before You Begin

Add http://localhost:3000 to the Salesforce CORS allowlist. See Perform Cross-Origin Requests.
1. Select a sample app from the table on this page to download and run the connection example.

company 510
Sample App Description Example Product

React, jsForce, A react app that demonstrates login Download and Run the OmniOut OmniScripts
and OAuth2 functionality using OAuth2 and jsForce. React-jsForce-OAuth2 Sample App
LWC A single page app that's built using only Download and Run the OmniOut OmniScripts
Lightning web components. LWC Sample App
LWC A single page app that's built using only Download and Run the OmniOut for FlexCards
Lightning web components. FlexCards LWC Sample App
React, Express A react app that demonstrates how to run an Download and Run the React- OmniScripts
Proxy application using a proxy. Express Proxy Sample App
2. (For OmniScripts only) Modify a Sample OmniOut for OmniScripts React App.
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.
Download and Run the OmniOut React-jsForce-OAuth2 Sample App

The OAuth2 sample is a react app that demonstrates an OmniScript with login authentication using OAuth2
and jsForce.
Before You Begin

Establish a Salesforce connection. See Create a Connected App for OmniOut.
1. Download the sample app by clicking here.

2. Open the file in Visual Studio Code.
3. In the Visual Studio Code terminal, run this command to install the npm dependencies:
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.

company 511
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

• OmniOut
Download and Run the OmniOut LWC Sample App

View a sample OmniOut that uses only Lightning web components to run a single page app off-platform.
Before You Begin

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.

company 512
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.
Before You Begin

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.
Download and Run the React-Express Proxy Sample App

The React Express sample app demonstrates how to use an application as the backend to make requests
and forward them to Salesforce.
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.
Before You Begin

Download, Configure, and Run the Express App (1)

Download the sample app, install the dependencies, and run the express app.
1. Download both the Express and React apps by clicking here.

2. Open the folder in Visual Studio Code.
3. In the Visual Studio Code terminal, cd into the express-proxy folder, and run this command to install
the npm dependencies:
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
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.

company 513
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.
Configure and Run the React App (2)

Install the dependencies for the react app, configure the connection.js file, and run the application.
1. Open a new terminal window in the Visual Studio Code terminal.

2. In the new terminal window, cd into the react-express-proxy-sample folder, and run this command to
install the npm dependencies:
npm install

company 514
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
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
See Also

• OmniOut

Host OmniScripts in your sample app by moving files from a compiled OmniOut project into your sample
app.

company 515
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.
Before You Begin

1. Download one of the react sample apps. See Sample OmniOut Apps.
2. Download the OmniOut static resource from Salesforce and open it in Visual Studio Code. See Download the OmniOut Static
Resource.
3. Install dependencies for the OmniOut project. See Install OmniOut Dependencies.
4. (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.
5. 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.
6. (Optional for OmniScripts only) Configure OmniOut to use multi-language OmniScripts. See Configure Multi-Language in OmniOut
for OmniScripts.
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.
npm run build

company 516

company 517
2. In the dist folder, copy the files your OmniScript requires to run from the OmniOut project to the
sample app's ./public folder.
File/Folder Required? Description

app.js files, including numbered app.js files, Yes The JavaScript files required for your FlexCard or
such as 0.app.js OmniScript.
vlocityresources Yes The static resources required for your FlexCard or
OmniScript.
index.html Optional A sample index.html file that shows how to run the OmniOut
LWC project.
newport Optional This file is required if you are using the default Newport
theme. If your OmniScript has an Image or File element, or
your FlexCard contains an Image element, you must also
copy over the slds folder.
slds Optional This file is required if you’re using the Lightning theme. If
your OmniScript contains an Image or File element, or your
FlexCard contains an Image element, you must copy over
the slds folder.
OmniScriptDocuSignReturnPage.html Optional This file is required if there’s a DocuSign Action in the
OmniScript.
OmniScriptLwcDocuSignViewPdf.html Optional This file is required if there’s a DocuSign Action in the
OmniScript.
3. In the dist folder's index.html file, select and copy the script tags that reference app.js files into the
sample app's ./public/index.html file.
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.

company 518
6. In the terminal, enter this command to run the app on localhost:3000:
npm start
See Also
• Create a Connection Object in OmniOut

• OmniOut
Create a Connection Object in OmniOut

Send and receive data to and from Salesforce by creating a connection object. A connection object must be
present for every type of connection, including when a proxy is present. The connection object exposes the
instance URL, namespace, and request function.
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.
Before You Begin

Add the OmniOut project to your application. See Move OmniOut into Your App.
1. Create an event handler.

Example Event Handler

company 519
/**
* 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

company 520
Create a Connection Object in OmniOut for FlexCards

Send and receive data to and from Salesforce by creating a connection object. A connection object must be
present for every type of connection, including when a proxy is present. The connection object exposes the
instance URL, namespace, and request function.
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.
Before You Begin

Add the OmniOut project to your application. See Move OmniOut into Your App.
1. In the ./src/index.js file, create a connection object:

Example Connection Object
setConnection();
function setConnection() {
const connection = new jsforce.Connection({

instanceUrl: 'https://login.salesforce.com',
proxyUrl: 'https://acme-proxy.herokuapp.com/proxy',
});
const username = 'username@website.com';
const password = 'password987';
connection.login(username, password, (err, userInfo) => {
if (err) {
return console.error(err);
}
});
connection.namespace = "acme";

company 521
initializeDatasourceSdk({
jsforceConnection: connection,
instanceUrl: "https://login.salesforce.com",
namespace: "acme"
});
}
2. Configure additional connection options outside of OmniOut.
See Also
• OmniOut

company 522
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:
1. OmniScript calls DataRaptor Extract to read data from Salesforce.

2. OmniScript interacts with user to capture changed and new data.
3. OmniScript calls DataRaptor Load to write data back to Salesforce.
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.
DataRaptor Turbo Extract Overview

A DataRaptor Turbo Extract retrieves data from a single Salesforce object type, with support for fields from
related objects. You can filter the data and select the fields to return. Unlike a standard DataRaptor Extract,
a DataRaptor Turbo Extract doesn't support formulas. There’s no Output tab, so you can't use mappings to
structure the output. Custom JSON, default values, and translations aren't supported.
A DataRaptor Turbo Extract has two advantages over a standard DataRaptor Extract:
• Simpler configuration
• Better performance at runtime

company 523
Create a DataRaptor Turbo Extract

To create a DataRaptor Turbo Extract, specify its name, input and output types, and permissions.
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.
Configure a DataRaptor Turbo Extract

To configure a DataRaptor Turbo Extract, specify the object type, filters, fields to extract, and options.
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.

company 524
• 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.
Related Object Fields in DataRaptor Turbo Extracts

Although a DataRaptor Turbo Extract retrieves from a single object type, you can select specific fields in
related objects.
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:

company 525
If you select one of those relationships and click the list again, second-level relationships to other objects
appear, for example:
You can traverse up to five relationship levels.
To back up a level, click the list and select the previous level, for example:

company 526
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.
Test a DataRaptor Turbo Extract

You can test the input and output of a DataRaptor Turbo Extract on the Preview tab.
1. Go to the Preview tab.

2. Specify Key/Value pairs in the Input Parameters panel.
As an alternative, you can click Edit as JSON and specify the input in JSON format.
3. To observe the effects of caching when testing the DataRaptor Turbo Extract, deselect the Ignore
Cache checkbox. See Cache for DataRaptors and Integration Procedures.
4. Click Execute.
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.
Create a DataRaptor Turbo Extract Example

A DataRaptor Turbo Extract retrieves Contacts for an Account having the specified Id.
To create this example:

company 527
1. On the OmniStudio DataRaptor tab, click New.

2. Specify a DataRaptor Interface Name.
3. Specify an Interface Type of Turbo Extract.
4. Click Save. The designer page is displayed.

5. Specify Contact as the Salesforce object and the Extract Output Path.
6. For the Filter, specify AccountId = AccountId.
7. Enter Name in the search field, and move FirstName and LastName to the right list.

company 528
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.
DataRaptor Extract Overview

DataRaptor Extracts read Salesforce data and return results in JSON, XML, or custom formats. You can
filter the data and select the fields to return. Formulas, default values, and translations are supported.
Extracts typically provide OmniScripts, Integration Procedures, and Cards with the data they require.
To define a DataRaptor extract:
1. Create the DataRaptor extract. See Creating a DataRaptor Extract

2. Configure the initial extraction. See Define the Initial Extraction.

company 529
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.
Create a DataRaptor Extract

To create a DataRaptor Extract, specify its name, input and output types, and permissions.
1. Go to the OmniStudio DataRaptor tab and click New. The Create: DataRaptor Interface dialog is
displayed.
2. Specify configuration settings:
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.
When an Integration Procedure calls a DataRaptor, the Required Permission setting of the
Integration Procedure overrides the Required Permission setting of the DataRaptor.
3. Click Save. The Extract tab of the designer page is displayed.
What's Next
Define the Initial Extraction
Define the Initial Extraction

On the Extract tab, you specify the Salesforce objects to be queried and the filters that determine the data
to be returned from the object. You can also specify a limit and offset for paging or a field on which to sort.
For each source object:
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

company 530
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
When to Use Multiple Extract Steps

How many extract steps you need depends on how the object types you are extracting from are related.
There are three basic scenarios: single, single with relationship notation, and multiple.
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.

company 531
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.

company 532
What's Next
Relationship Notation versus Multiple Extract Steps
Relationship Notation versus Multiple Extract Steps

Using relationship notation improves the performance of DataRaptors that retrieve data from a parent of the
primary sObject. You use this notation in the Extract JSON Paths for the parent sObject's fields instead of
adding a second sObject in the DataRaptor's Extract tab. Two examples illustrate how to use relationship
notation.
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.

company 533
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.
To download DataPacks of these examples, click here and here.
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:

company 534
{
"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:
SELECT id, firstname, lastname, account.name FROM Contact WHERE (Id =

'0031U00000HUob9QAD')
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
DataRaptor Extract Output

To map data from the extraction step JSON to the output JSON, go to the Output tab. You can also handle
null values, attributes, translations, field-level permissions, caching, and list transforms.
1. Click +. An empty mapping is added to the list.

2. In the Extract JSON Path field, choose the source field from the extraction step JSON.
3. In the Output JSON Path field, specify the desired output path.
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.

company 535
You can also use formulas to add output data. For details, see Use Formulas in DataRaptors and Function
Reference.
Quick Match for Output Maps

To bulk-match, click the Quick Match button. In the Quick Match dialog, you can map fields as follows:
• 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.
Mappings are displayed in the right-hand Matched Mappings column.
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.
Null Inputs.
If the DataRaptor Extract retrieves no records, empty JSON, {}, is returned.
JSON Data in Fields

Some fields contain JSON data. To map this data, use standard notation in the Extract JSON Path, for
example:
Object:JsonField__c:JsonNode:ChildJsonNode

company 536
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.
Permissions, Caching, and Other Options

You can configure additional optional 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.
• 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.
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.
Input JSON Mappings Output JSON

{ Thing1 中 Thinglist|1 {
"Thing1": "1", Thing2 中 Thinglist|2 "Thinglist":
"Thing2": "2", Thing3 中 Thinglist|3 [ "1", "2", "3" ]
"Thing3": "3" }
}
For more about lists in DataRaptors, see List Input for DataRaptors.
What's Next
Test a DataRaptor Extract
Test a DataRaptor Extract

You can test the input and output of a DataRaptor Extract on the Preview tab.

company 537
2. Specify Key/Value pairs in the Input Parameters panel.

As an alternative, you can click Edit as JSON and specify the input in JSON format.
3. To observe the effects of caching when testing the DataRaptor Extract, deselect the Ignore Cache
checkbox. See Cache for DataRaptors and Integration Procedures.
4. Click Execute.
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.
DataRaptor Extract Examples

DataRaptor Extract examples demonstrate object relationships, paging with data values, paging with
offsets, and relationship notation.
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.
Create a Basic DataRaptor Extract Example

A DataRaptor extract accepts an account Id parameter and returns the account name.
1. On the Extract tab, click Add Extract Step.

2. From the list of Salesforce objects, choose Account.
3. Set the Extract Output Path to Account and the filter to Id = InputId.
4. On the Output tab, click +.
5. Set the Extract JSON Path to Account:Name.
6. Set the Output JSON Path to Account:Name.
8. In the Input Parameters pane, click Add New Key/Value Pair.
9. Set the Key to InputId and the Value to a valid Salesforce Account object Id (which looks like this:
0016100001OBpRi).
10. Click Execute.
11. Verify that the Response pane displays a JSON structure containing the desired output. For example:
{
"Account": {

company 538
"Name" "Smith Incorporated"

}
}
Extract Data from Three Related Objects

Create a DataRaptor Extract for use by a Case-handling OmniScript. The agents who handle Cases can
look up an Account, list all the Cases for the Account, and find the Contact for each Case.
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.
To create this DataRaptor Extract:
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:
Object Extract Output Path Filter

Account Account Id = AccountId
Case Account:Case AccountId = Account:Id
Contact Account:Case:Contact Id = Account:Case:ContactId
5. On the Output tab, map fields from the Extraction Step JSON to the Output JSON. To add a mapping,
click the + button. Add four mappings:
Extract JSON Path Output JSON Path

Account:Name Account:Name
Account:Case:CaseNumber Account:Case:CaseNumber
Account:Case:Subject Account:Case:Subject
Account:Case:Contact:Name Account:Case:Contact:Name
6. Verify that the structure displayed in the Current JSON Output panel looks like this:
{
"Account": {

company 539
"Case": {
"CaseNumber": "Text",
"Contact": {
"Name": "Text"
},
"Subject": "Text"
},
"Name": "Text"
}
}
The order of fields in not important, but the structure is.

8. In the Input Parameters pane, specify a Key of AccountId and a Value of an Id such as
0015e000003XlkMAAS.
9. Click Execute. Assuming the Account has associated Cases, the response looks like this:
{
"Account": {
"Case": [
{
"Contact": {
"Name": "Edward Stamos"
},
"Subject": "Cannot track our order",
},
{
"Contact": {
"Name": "Leanne Tomlin"
},
"Subject": "Wrong size widgets",
},
{
"Contact": {
"Name": "Jeff Hunt"
},
"Subject": "Update account phone number",
},
{
"Contact": {
"Name": "Edward Stamos"
},
"Subject": "Billing status",

company 540
}
],
"Name": "Acme"
}
}
Page Through Sorted Data Using Data Values

If a DataRaptor Extract is expected to retrieve a lot of records, you can use paging to retrieve a few at a
time based on field values. For example, you can page through Accounts by Id.
To set up paging based on field values:
• 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.
2. Specify a name for the DataRaptor and configure its settings as follows:
• Output Type: JSON
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.
5. On the Output tab, map the Id and Name fields as shown.

company 541
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 first page of Account records is retrieved.

8. Copy the Id value from the second record in the Response to the Value field in the Input Parameters
pane, then click Execute again.
The second page of Account records is retrieved. Repeat this step to retrieve the next page.
Page Through Sorted Data Using Offsets

If a DataRaptor Extract is expected to retrieve a lot of records, you can use paging to retrieve a few at a
time based on OFFSET values. For example, you can page through Contacts by last name.

company 542
To set up paging based on OFFSET values:
• 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.
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.

company 543
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 first page of Contact records is retrieved.

8. Change the AfterRecord value to 3 and click Execute again.

company 544
The second page of Contact records is retrieved. Repeat this step, incrementing the AfterRecord
value by 3 each time, to retrieve the remaining pages.
Extract Multiple Relationship Levels and Custom Field Values

Suppose you want to retrieve Contract data that includes the Version (parent) and the name of the user
(grandparent) who created the Contract. You can use relationship notation with custom fields.
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.
To use relationship notation:
1. Define an extraction step for the Contract object on the DataRaptor's Extract tab as follows:

company 545
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:
SELECT id, contractnumber, vlocity_cmt__activecontractversionid__r.name,

vlocity_cmt__activecontractversionid__r.createdby.name FROM Contract WHERE
(ContractNumber = '00000105')
DataRaptor Transform Overview

DataRaptor Transforms let you perform intermediate data transformations without reading from or writing to
Salesforce. Formulas are supported.
• Convert JSON input to XML output, and vice versa

• Restructure input data and rename fields

company 546
• Substitute values in fields (all DataRaptors can substitute values)

• Convert data to PDF, DocuSign, or Document Template format
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.
Create a DataRaptor Transform

To create a DataRaptor Transform, specify its name, input and output types, and permissions.
1. Go to the OmniStudio DataRaptor tab and click New. The Create: DataRaptor Interface dialog is
displayed.
2. Specify configuration settings as follows:
of DataRaptors.
• Input Type: JSON (for OmniScripts), XML or Custom
• Output Type: JSON (for OmniScripts), XML, PDF, DocuSign, Document Template, or Custom
3. Click Save. The Transforms tab of the designer page is displayed.
What's Next
DataRaptor Transform Data Mappings
DataRaptor Transform Data Mappings

To map data from the input to the output, go to the Output tab. You can also handle null values, data types,
caching, and list transforms.
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.

company 547
To specify individual mappings:
1. Click +. An empty mapping is added to the list.

2. In the Input JSON Path field, specify the input path.
3. In the Output JSON Path field, specify the desired output path.
Use colons to separate path levels, for example Contact:LastName.
Data Restructuring and Renaming

All types of DataRaptors can restructure data and rename fields using mappings. To restructure and/or
rename a field, you map the input path to the desired output path.
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.
Null Inputs.
Input Value to Output Value Mappings

To verify that your mappings create the desired structure, go to the Preview tab, paste sample input into the
Input pane on the left side of the screen, and click Execute. The results are displayed in the Response
pane.
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:

company 548
Output Data Types

On the Output tab, you can specify the data type of the output data. If you change the type, be sure to
choose a compatible output type. (For example, changing a numeric type to a string is fine, but changing a
string to a numeric is risky, because a string can contain non-numeric characters.) See DataRaptor Output
Data Types.
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.
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
Use Quick Match to Map Data

Quick Match is a handy way to map input and output data in a DataRaptor Transform when the names
match.
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.

company 549
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.
The following example compares equivalent structures in JSON and XML.
JSON
{
"Root": {
"#text": "rootValue",
"@attribute1": "attVal1",
"#ns": "http://namespace1",
"#ns#a": "http://namespace2",
"Child": [{
"@attribute2": "attval2"
},
{
"#text": "childValue"
}
]
}
}
XML
<Root attribute1="attVal1" xmlns="http://namespace1" xmlns:a="http://

namespace2">
rootValue
<Child attribute2="attval2"></Child>
<Child>childValue</Child>
</Root>
DataRaptors that transform XML to JSON use the following conventions to handle the differences between
the formats.
Description XML JSON

company 550
Values in an input XML node are translated to <Root>rootValue</Root> {

output JSON with the key #text. "Root": {
"#text": "rootValue"
}
}
Values in an input XML node are translated to <Root attribute1="attVal1"></ {
output JSON with a key that is preceded by an Root> "Root": {
at sign (@). "@attribute1": "attVal1"
}
}
Namespaces in an input XML node are <Root xmlns="http:// {
prepended with #ns in the output JSON. namespace1" xmlns:a="http:// "Root": {
namespace2"> "#ns":"http://namespace1",
</Root> "#ns#a":"http://namespace2,
}
}
Colons, which are reserved characters in <Root:Data>data</Root:Data> {
DataRaptor mappings, are replaced by #. "Root#Data": {
"#text":"data",
}
}
Test a DataRaptor Transform

You can test the input and output of a DataRaptor Transform on the Preview tab.

2. Specify JSON or XML input in the Input panel.
3. To observe the effects of caching when testing the DataRaptor Transform, deselect the Ignore Cache
checkbox. See Cache for DataRaptors and Integration Procedures.
4. Click Execute. The Response panel displays the resulting data.
DataRaptor Transform Examples

DataRaptor Transform examples demonstrate how to convert a single item into a list with one item and how
to convert a list of objects to a list of values.
For additional DataRaptor Transform examples, see List Input for DataRaptors and Create a DataRaptor
Example with a Formula.
Convert a Single Item to a List with One Item

In some cases, a component's output that isn't in list format must pass to another component that only
accepts a list. You can use the Output Data Type setting in a DataRaptor Transform to perform this
conversion.
To create a DataRaptor Transform that puts an item in a list:

company 551
• Interface Type — Transform

3. Click Save. The Transforms tab of the DataRaptor Interface page is displayed.
4. Expand the Input JSON pane and paste the following JSON data into it:
{
"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"
}
]
}
Convert a List of Objects to a List of Values

You can convert a list of JSON objects (key-value pairs in braces) to a list of single values, regardless of
the length of the list. The trick is to use a formula to remove the second level of the hierarchy.
To create a DataRaptor Transform that converts a list of objects to a list of values:

company 552
• Interface Type — Transform
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"
},
{

company 553
"Property": "P5678"
},
{
"Property": "P2345"
},
{
"Property": "P7654"
}
]
}
10. Click Execute. The Response should look like this:
{
"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.
DataRaptor Load Overview

DataRaptor Loads accept data in JSON, XML, or custom input formats and write the data to Salesforce
objects. Formulas and attributes are supported.
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:
• OmniScript or Integration Procedure: During execution, an OmniScript or Integration Procedure builds a

Data JSON that is populated with the data required for the business use case. When the script invokes
the DataRaptor Load, the Data JSON is sent as input.
• DataRaptor API REST call: If the DataRaptor is invoked using a POST action, the Data JSON can be
included in the payload of the call.
• Apex code: Specify the Data JSON as a parameter in the call to the DataRaptor Load.
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.

company 554
Create a DataRaptor Load

To create a DataRaptor Load, specify its name, input and output types, permissions, and options.
1. Go to the OmniStudio DataRaptor tab.

2. Click New.
3. On the Create dialog, specify the following settings and click Save:
• DataRaptor Interface Name: Descriptive name of your choice
• Batch Size: Number of records processed per batch transaction, between 1 and 2000
• Interface Type: Load
• Input Type: Choose JSON or Custom. If your DataRaptor load is called from an OmniScript, choose
JSON. For details about custom data serialization, see Custom Input and Output for DataRaptors.)
• Output Type: SObject
4. On the Objects tab, specify the Salesforce objects that you want to update.
5. On the Formulas tab, define any transformations you want to apply to the input data to add data to the
output data. For details about the functions that you can use in formulas to define transformations, see
Use Formulas in DataRaptors.
6. On the Fields tab, map the input data to the Salesforce object fields that you want to update. For more
information, see Object Field Mapping.
7. On the Options tab are optional properties you can set.
The following options are available only if the Input Type is SObject:
• Batch Size: The number of records processed per batch transaction, between 1 and 2000.
• Process Now Threshold: The number of records processed immediately, between 0 and 199.
• Preprocessor Class Name: The adapter Apex class that implements the IDRPreprocess Apex
interface.
• Delete on Success: Automatically delete bulk records after successfully bulk-loading data.
• Process Super Bulk: Process large jobs spread over multiple Salesforce Apex batch jobs without
exceeding Salesforce governor limits.
• Is Default for Interface: Specify this DataRaptor as the default bundle for the specified interface
object.
The following options are available for all DataRaptor Loads:
• Ignore Errors: Execute the DataRaptor even if errors occur, skipping only the steps having errors.
This option is useful when you know a record will fail with limited data and future steps don't rely on
previous steps.
• Rollback on Error: Don't create or update the sObjects if errors occur. For more information, see
Apex Transactions and Transaction Control in the Salesforce documentation.

company 555
• 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 Field Mapping

You must map data from the DataRaptor Load input JSON to the target Salesforce object and field. You can
also handle data types and default values.
1. Go to the Fields tab.

2. Click +. A new mapping is added to the list.
3. Configure the following settings:
• Input JSON Path: The key of the JSON node containing the data you want to write to Salesforce.
• Domain Object Field: The field in the sObject that you want to update.
Some fields contain JSON data. To map this data, use standard notation, for example:
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:
• Is Disabled: Prevents the field from being loaded.

• Upsert Key: Specifies that the field is a key for the Salesforce object being loaded. The DataRaptor uses
the value to determine whether it updates an existing record or inserts a new one. If the Upsert property
is enabled for multiple field mappings, the result is a multi-field upsert key. DataRaptor uses this key to
check the object for unique values to determine whether to create a new object or update an existing
one.
• Is Required for Upsert: Prevents an object record from being updated if this field is null.
• Is Lookup: Uses the field value to query for the specified Salesforce data, and writes the result to the
output field.
• Output Data Type: Must be compatible with the data type of the target field.
The Output Data Type setting must be compatible with the target field in Salesforce. If you configure
incompatible types, the load operation can fail. For a list of valid output types, see DataRaptor Output
Data Types.

company 556
• 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
Multiple Related Object Loads (Link Mappings)

When loading data into a sequence of objects, you can propagate data directly from one object to another
related object. For example, you can use a DataRaptor Load to support an OmniScript that creates an
Account and a Contact for the Account.
To link the Account to its Contact, the DataRaptor must perform the following sequence of operations:
1. Create the Account.

2. Create the Contact.
3. Link the Account and Contact records by populating the Contact record’s AccountId field with the Id of
the Account record.
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.

company 557
For an example that uses link mapping, see Create a Contact for an Existing Account.
Test a DataRaptor Load

You can test the results of a DataRaptor Load on the Preview tab.

2. Specify JSON input in the Input panel.
3. Click Execute.
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.
DataRaptor Load Examples

DataRaptor Load examples demonstrate formulas and object relationships.
Create a Contact and Use a Formula

A DataRaptor Load creates a record in the Salesforce Contact object. A formula checks whether the
contact is over 18 years old: if so, a custom Authorized field is set to true.
The input JSON for this DataRaptor Load contains the Contact details, for example:
{
"ContactDetails": {
"Birthdate": "10/10/1954",
"LastName": "Singh",
"Telephone": "5106345789",
"FirstName": "Sanjay"

company 558
}
}
To create this example DataRaptor Load:
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
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.
Input JSON Path Domain Object Field

ContactDetails:Authorized Authorized__c
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.

8. Paste the following test data into the Input pane on the left.

company 559
{
"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.
Create a Contact for an Existing Account

The following example of a DataRaptor Load creates a record in the Salesforce Contact object. A link to an
Account object record with a specific Id ensures that the new Contact is related to that Account.
The input JSON for this DataRaptor Load contains the Account Id and the Contact name, for example:
{
"AccountId": "0016100001BKL4uAAH",
"Name": {
"First": "Jane",
"Last": "Doe"
}
}
To create this example DataRaptor Load:
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
3. On the Objects tab, click Add Object and choose Account.
4. Click Add Object again and choose Contact.

company 560
5. Click Add Link and enter settings as follows:

• Domain Object Field: AccountId
• Linked Object: 1 - Account
• Linked Object Field (after the period): Id
6. Go to the Fields tab and the Account subtab. Click the + icon and add the following mapping:
• Input JSON Path: AccountId
• Domain Object Field: Id
• Upsert Key: checked
7. Go to the Contact subtab. Add the following name mappings:
The AccountId mapping is already present.

8. On the Preview tab, test the DataRaptor using input with the same structure as the sample input
above, substituting an Account Id from your org and a name of your choice.
DataRaptor Best Practices

To maximize the benefits of DataRaptors, follow the best practices whenever possible.
• Create targeted DataRaptors that only extract or load the data needed for one operation.
• Use relationship notation (queries) whenever possible to pull data from other SObjects. For more
information, see 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
To determine whether a DataRaptor or an Integration Procedure is best for your use case, see DataRaptor
or Integration Procedure?.

company 561
List Input for DataRaptors

DataRaptors can perform list transformations. For mapping input to output, DataRaptors require list input in
which every value is paired with a key.
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.

company 562
Input JSON Path Output JSON Path

Oldest Nephews|1:Name
Middle Nephews|2:Name
Youngest Nephews|3:Name
To convert List 2 to List 1, use the reverse mappings.
To download DataPacks of DataRaptor Transforms for these mappings, click these links:
• List 1 to List 2 example

• List 2 to List 1 example
In the following list, values don't have keys.
List 3:
{
"Nephews": [
"Huey",
"Dewey",
"Louie"
]
}
You can convert List 1 to List 3 using the following mappings:
Input JSON Path Output JSON Path

Oldest Nephews|1
Middle Nephews|2
Youngest Nephews|3
However, you can't convert List 3 to either List 1 or List 2.
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)

company 563
Use Formulas in DataRaptors

To add data to the output of a DataRaptor, you can define formulas. All types of DataRaptor (Turbo Extract,
Extract, Transform, and Load) support formulas. When you define a formula, you map its output to the
output JSON (for extracts and transforms) or Salesforce object field (for loads).
For details about the operators and functions that you can use in formulas, see Function Reference.
To create a formula:
1. In the DataRaptor Interface page, go to the Formulas tab.

2. Click Add Formula. An empty formula is added to the list.
3. In the Formula field, specify the desired logic. For example, to determine the total price of the items
being purchased by a customer, enter a formula such as:
SUM(Products:Price)
You can also use relationship notation in formulas to reference fields in a parent object. See
Relationship Notation versus Multiple Extract Steps.
4. In the Formula Result Path field, specify a JSON node in which to store the formula result.
5. Map the result to the final output as follows:
• Extract: Go to the Output tab and map the formula result to the output structure. Use a colon (:) to
delimit levels in the input and output paths in mappings.
• Transform: Go to the Transforms tab and map the formula result to the output structure. Use a
colon (:) to delimit levels in the input and output paths in mappings.
• Load: For each sObject that you want to update, go to its Fields tab and map the formula result to
the specific field that you want to update.
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
Create a DataRaptor Example with a Formula

The following example accepts a list of prices and uses a formula to compute the total price.

company 564
To create this DataRaptor Transform, perform the following steps:
1. Go the OmniStudio DataRaptor Designer tab and click New. The Create dialog 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:
{
"TotalPrice": 830,
"Products": [
{
"Name": "iPhone",
"Price": 600
},
{
"Price": 30
},

company 565
{
"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
DataRaptor Output Data Types

Many data types can be assigned to data in the Output JSON, including boolean, currency, string, various
number and list types, and date formats.
• 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.

company 566
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:
Date("EEE, d MMM yyyy HH:mm:ss Z")
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
DataRaptor Developer Features

You can call DataRaptors using Apex or a REST API. You can also use custom input and output and
environment variables in DataRaptors.
DataRaptor REST API

You can invoke any type of DataRaptor using the DataRaptor REST API. To update Salesforce objects
using a DataRaptor Load, issue a POST request that includes a JSON payload that is formatted to comply
with the input that the DataRaptor load expects. To retrieve data from Salesforce, issue a GET call to a
DataRaptor Extract, specifying the Id or parameters identifying the data to be retrieved. The data is
returned in the response in JSON format.
NOTE
The Salesforce Workbench REST Explorer is a useful testing tool.
Example
POST Data
{
"bundleName" : "AccountUpload",
"objectList" : {

company 567
"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": []
}
DataRaptor Extract Invocation Using GET

To retrieve data from Salesforce using a REST call, issue a GET statement that invokes a DataRaptor
Extract. To identify the data to be retrieved you can either specify the object Id or one or more parameters
to be matched. Data is returned in the response in the output JSON format that the DataRaptor Extract
creates.
Use an ID to Retrieve Data

To retrieve Salesforce data by specifying the Id, issue a GET request that invokes a DataRaptor Extract,
using a URL formatted as follows:
/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

company 568
Example Result
{
"Contact": {
"Contact Name" : "Dennis Reynolds",
"Case Information": [
{
"Title": "Wrong widget shipped..."},
{
"Title": "Overcharged for gizmo..."},
{
"Title": "Damaged item..."}
]
}
}
Use Parameters to Retrieve Data

To retrieve Salesforce data by passing parameters to a DataRaptor extract, issue a GET request using a
URL formatted as follows:
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
DataRaptor Load Invocation Using POST

To update Salesforce data, issue a POST request with a URL formatted as follows:
/services/apexrest/vlocityNamespace/v2/DataRaptor/
In the POST data, specify the following parameters:
• bundleName: Name of the DataRaptor Load to invoke

• objectList: JSON data to be loaded. Must match the format expected by the DataRaptor Load.
• filesList: (Optional) Map of keys to base 64-encoded files.
• bulkUpload: TRUE to use batch Apex.
DataRaptor Calls From Apex

To call a DataRaptor from Apex, call the vlocity_ins.DRGlobal.processObjectsJSON() method,
specifying the name of the DataRaptor and the input data that it requires.
Specify the input as follows:

company 569
• 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 Extract or Transform Example

/* Specify DataRaptor extract or transform to call */
String DRName = 'DataRaptorName';
/* Populate the input JSON */
Map<String, Object> myTransformData = new Map<String,
Object>{'MyKey'=>'MyValue'};
/* Call the DataRaptor */
vlocity_ins.DRProcessResult result =
vlocity_ins.DRGlobal.process(myTransformData, DRName);
/* Deserialize the DataRaptor output for processing in Apex */
List<Map<String, Object>> myTransformResult = (List<Map<String,
Object>>)result.toJsonList();
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.
DataRaptor Load Example

String dataJson = '{"accountName":"Vlocity", "contractCode":"SKS9181"}';
vlocity_ins.DRProcessResult result =
vlocity_ins.DRGlobal.processObjectsJSON(dataJson, 'Create Contracts');
Map<String, Object> resultMap = result.convertToMap();
System.debug(JSON.serialize(resultMap));
/*
Process the results of the load: these methods return details about objects
affected by the DataRaptor load, plus any errors that occured
*/
Map<String, Object> createdObjectsByType = (Map<String,
Object>)resultMap.get('createdObjectsByType');
Map<String, Object> createdObjectsByTypeForBundle = (Map<String,

company 570
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
DataRaptor Load Example with the bulkUpload Parameter

Use the processPost method if you need to pass the bulkUpload parameter to a DataRaptor Load.
String objectList = '[{"ProductCode__c": 11050665},{"ProductCode__c":

11070100}]'; // replace this with the input for your DR Load
String bundleName = 'DRLoadPrice'; // replace this with your DR name
String bulkUpload = 'true';
Map<String,Object> bodyData = new Map<String,Object>();
bodyData.put('bundleName',bundleName);
bodyData.put('bulkUpload',bulkUpload);
bodyData.put('objectList',objectList);
vlocity_cmt.DRGlobal.processPost(bodyData);
DRGlobal Class and Methods

The DRGlobal class provides multiple methods for calling Vlocity DataRaptors from Apex.
In all the method signatures shown below, the namespace is vlocity_cmt, vlocity_ins, or
vlocity_ps. The bundleName is the DataRaptor name.
For sample code, see DataRaptor Calls From Apex.
Method Names
processObjectsJSON
Signature:
static namespace.DRProcessResult processObjectsJSON(String objectList, String

bundleName)
The objectList must be a JSON String.
processObjects
Signatures:
static namespace.DRProcessResult processObjects(List<SObject> objectList)

static namespace.DRProcessResult processObjects(List<SObject> objectList,

company 571
String bundleName)
String bundleName, Map<String, Object> additionalInfo)
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:
static namespace.DRProcessResult processString(String input, String bundleName)
The input must be an XML String.
processFromApex
Signatures:
static namespace.DRProcessResult processFromApex(List<Map<String, Object>>

objectList, String bundleName, String locale)
static namespace.DRProcessResult processFromApex(Map<String, Object>
objectList, String bundleName, String locale)
These methods ignore Sharing Rules, which ensures that the DataRaptor being invoked is private. See
Sharing Rules in the Salesforce help.
process
Signatures:
static namespace.DRProcessResult process(List<Map<String, Object>> objectList,

String bundleName, String locale)
static namespace.DRProcessResult process(Map<String, Object> objectList,
String bundleName, String locale)
processPost
Signature:
global static Map<String, Object> processPost(Map<String, Object> bodyData)
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

company 572
For details about these methods, see Cache for DataRaptors and Integration Procedures.
Environment Variables in DataRaptors and Integration Procedures

You can use environment variables to define Default Values and Filter Values, and in Formulas.
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.
Environment Variable Description

$Vlocity.TODAY Today’s date
$Vlocity.TOMORROW Tomorrow’s date
$Vlocity.NOW Current date and time
$Vlocity.N_DAYS_FROM_NOW:{N} The date the specified number of days from now
$Vlocity.N_DAYS_AGO:{N} The date the specified number of days ago
$Vlocity.NULL Null
$Vlocity.StandardPricebookId Id of the standard pricebook
$Vlocity.DocumentsFolderId Documents folder Id
$Vlocity.true or $Vlocity.TRUE Boolean TRUE
$Vlocity.false or $Vlocity.FALSE Boolean FALSE
$Vlocity.UserId Current user Id
$Vlocity.Percent Percent character. Useful for escaping % characters in URLs so they aren't mistaken for merge
field syntax.
$Vlocity.CpuTotal Apex CPU value
$Vlocity.DMLStatementsTotal Number of Data Manipulation Language statements
$Vlocity.DMLRowsTotal Number of Data Manipulation Language rows
$Vlocity.HeapSizeTotal Heap size value
$Vlocity.QueriesTotal Number of queries run
$Vlocity.QueryRowsTotal Number of query rows fetched
$Vlocity.SoslQueriesTotal Number of SOSL queries run
Custom Input and Output for DataRaptors

By default, DataRaptors handle JSON and XML data. To handle other data formats, you can configure a
DataRaptor to use a custom input or output that you implement is a custom class. For example, you can
define a DataRaptor Transform that accepts CSV-formatted data and outputs it as JSON.
Options are as follows:

company 573
• DataRaptor Load: Custom input (output is always a Salesforce object)

• DataRaptor Transform: Custom input and output
• DataRaptor Extract: Custom input and output
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.
Custom Class Implementation

To create the logic required to custom input and output, you must define a custom class that implements
VlocityOpenInterface2. For custom output, implement the serialize method. For custom input,
implement the deserialize method. You cannot rename the input and output parameters.
The following example shows the basic structure of a customer serialization/deserialization class.
global with sharing class VlocityPreprocessorClassExample implements

VlocityOpenInterface2 {
global Object invokeMethod(String methodName, Map<String,Object> input,
Map<String,Object> output, Map<String,Object> options) {
if (methodName == 'serialize') {
return serialize(input, output);
}
else if (methodName == 'deserialize') {

company 574
return deserialize(input, output);

}
return false;
}
/*
Serializes Apex objects into JSON content. return String json
*/
global Boolean serialize(Map<String, Object> input, Map<String, Object>
output) {
String jsonString = '';
// code
output.put('output', jsonString); // JSON String
return true;
}
/*
Deserializes the specified JSON string into collections of primitive
data types. return Object ((Map<String, Object>))
*/
global Boolean deserialize(Map<String, Object> input, Map<String, Object>
output) {
Map<String, Object> returnMap = new Map<String, Object>();
// code
output.put('output', returnMap); // ---> collections of primitive data
types Map<String, Object>, List<Map<String, Object>>()
return true;
}
}
The following example serializes and deserializes CSV data.
global with sharing class VlocityPreprocessorClass implements

VlocityOpenInterface2
{
Map<String,Object> output, Map<String,Object> options)
{
if (methodName == 'serialize')
{
return serialize(input, output);
}
else if (methodName == 'deserialize')
{
return deserialize(input, output);
}
return false;
}

company 575
/*
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;
}

company 576
}
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"
}
]
*/

company 577
global Boolean deserialize(Map<String, Object> input, Map<String, Object>

output)
{
Object inputValue = input.get('input');
if (inputValue != null && inputValue InstanceOf String)
{
List<String> valueSet = ((String)inputValue).split('\n');
List<Map<String, String>> csvList = new List<Map<String, String>>();
List<String> columns = new List<String>();
for (Integer i = 0; i < valueSet.size(); i++)
{
String value = valueSet[i];
if (String.isBlank(value))
{
continue;
}
if (i == 0)
{
List<String> valSet = value.split(',');
for (Integer y = 0; y < valSet.size(); y++)
{
columns.add(valSet[y]);
}
}
else
{
List<String> valSet = value.split(',');
if (columns.size() >= valSet.size())
{
Map<String, String> rows = new Map<String, String>();
for (Integer z = 0; z < valSet.size(); z++)
{
rows.put(columns[z], valSet[z]);
}
csvList.add(rows);
}
}
}
output.put('output', csvList);
return true;
}
return false;
}
}

company 578
Cache for DataRaptors and Integration Procedures

Using a cache to store frequently accessed, infrequently updated DataRaptor and Integration Procedure
data saves round trips to the database and improves performance.
You can use caching with DataRaptors in three ways:
• 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 use caching with Integration Procedures in three ways:
• You can cache metadata for the entire Integration Procedure.

• You can cache the response of the entire Integration Procedure, called top-level data. See Cache for
Top-Level Integration Procedure Data.
• You can cache the result of a specific set of steps by placing the steps inside a Cache Block. See
Enhance Performance Using Cache Blocks.
Use Cache Blocks if some parts of the Integration Procedure update data, or if you need different cached
data to expire at different times. For example, current weather data changes more frequently than user
session data.
You can also perform a record-level security check for cached data. See Security for DataRaptors and
Metadata Cache for DataRaptors and Integration Procedures

Integration Procedure metadata is cached by default and DataRaptor metadata is automatically cached.
To disable metadata caching for an Integration Procedure, go to the Procedure Configuration and check the
Disable Definition Cache checkbox.

company 579
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.
Methods to Clear Metadata from Either Cache

If you must clear DataRaptor metadata from the cache, follow the instructions in this topic, but execute one
of these lines of code instead:
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');
Methods to Clear Data from the Scale Cache

OmniStudio DataRaptors and Integration Procedures use the Scale Cache and not the Platform Cache. To
clear the Scale Cache, you can use either the preceding methods or the following ScaleCacheService
method.
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,

company 580
'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:
String>{'VIPId' =>
Type_SubType});
For example, to clear data from an Integration Procedure with a Type_SubType of

LoopList_ContactNames, use this line of code:
String>{'VIPId' =>
'LoopList_ContactNames'});
See Also
• Turn Off the Scale Cache
Security for DataRaptors and Integration Procedures

You can control access to DataRaptors and Integration Procedures using settings that reference Sharing
Settings and Sharing Sets or Profiles and Permission Sets.
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.

company 581
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.
Configure DataRaptor and Integration Procedure Security Settings

You can change settings for DataRaptor and Integration Procedure security in Setup.
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.
DataRaptor and Integration Procedure Security Settings

These settings affect DataRaptor and Integration Procedure security.
To configure these settings, see Configure DataRaptor and Integration Procedure Security Settings.

company 582
Setting Description Data Default

Type Value
DefaultRequiredPermission Specifies the Custom Permission a user must have to run String (none)
The Required Permission setting, which you can optionally

specify when creating a DataRaptor or Integration Procedure,
overrides this setting.
If this setting is absent or blank, all users can run any

DataRaptors or Integration Procedures that don't have Required
Permission values.
Custom Permissions for users are defined in Salesforce Profiles

or Permission Sets.
For this setting to work, the

VlocityRequiredPermissionCheck class must be
implemented. See Implement the
VlocityRequiredPermissionCheck Class.
CheckCachedMetadataRecordSecurity By default, cached data is not secured when you use Salesforce True/ False
Sharing Settings or Sharing Sets to secure access. If True, this False
setting performs a record-level security check for cached data.
This lessens the performance benefit of metadata caching
slightly. This setting isn't needed if you use Custom Permissions
to secure access.
Implement the VlocityRequiredPermissionCheck Class

For the DefaultRequiredPermission setting to work, you must implement the
VlocityRequiredPermissionCheck class manually because Salesforce handles classes in managed
and unmanaged packages differently. This class doesn't work properly if it's included in the Vlocity
managed package.
For DefaultRequiredPermission details, see DataRaptor and Integration Procedure Security Settings.
1. From Setup, in the Quick Find box, type apex.

2. Click Apex Classes.
3. Click New.
4. Enter the following Apex code in the Apex Class tab:

company 583

{
{
{
return checkPermission((String)args.get('requiredPermission'));
}
return false;
}

{
List<String> customPermissionsName = requiredPermission.split(',');
{
{
break;
}
}
}
}
5. Click Save.

company 584
OmniStudio Integration Procedures
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.

company 585
See Also
• Integration Procedure Best Practices
• DataRaptor or Integration Procedure?
• OmniScript Action Elements Reference
Create an Integration Procedure

To create an OmniStudio Integration Procedure, you must name it, configure it, define its logic, and preview
how it runs. You can also view debugging information and set options that apply only to previews.
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.
1. Go to the OmniStudio Integration Procedures tab.

company 586
2. Click New. The New Integration Procedure screen is displayed.

3. In the Procedure Configuration section, specify the following settings:
• Integration Procedure Name: The name displayed on the Vlocity Integration Procedures tab when
you expand the Type/SubType node.
• Type and SubType: The top-level node on the Vlocity Integration Procedures tab under which you
want the Integration Procedure listed.
After providing a Name, Type, and SubType, you must click Save.
• Description: A general description of the Integration Procedure.
• Tracking Custom Data: Key/value pairs to be recorded when the Integration Procedure is executed,
if tracking is enabled.
• Include All Actions in Response: Write the results of each action to the root level of the Data JSON.
By default, results are written to the Data JSON under a node with the same name as the action.
• Rollback on Error: If an error occurs, roll back data manipulation language (DML) statements.
run this Integration Procedure, a user must have one of these permissions. If this setting is blank,
any user can run this Integration Procedure unless a DefaultRequiredPermission is set.
When an Integration Procedure calls a DataRaptor or another Integration Procedure, the Required
Permission setting of the calling Integration Procedure overrides the Required Permission setting of
the DataRaptor or Integration Procedure being called.
• Chainable and Queueable Chainable Limits: These settings control how long-running procedures are
executed when there’s a risk of hitting Salesforce governor limits. For details, see Settings for Long-
Running Integration Procedures.
• Cache Configuration: These settings control caching of Integration Procedure metadata and JSON
data. See Cache for DataRaptors and Integration Procedures.
4. To define the logic for the Integration Procedure, drag blocks and actions from the palette to the
Structure panel in the Properties pane. For details about blocks, see Group Integration Procedure
Steps Using Blocks. For details about actions, see Integration Procedure Actions.
When a step executes, its results are written to the Data JSON under a node with the same name as
the step. Subsequent steps can access the data that was written to the Data JSON by preceding steps.
5. To test the Integration Procedure, click Preview. In the Input Parameter pane, specify any parameters
that must be provided by callers, then click Execute. Verify that the JSON results are composed
correctly according to the requirements of the caller.
6. To view debugging information in Preview mode, display the Error/Debug Output pane on the right side
of the Integration Procedure Designer. This pane contains the following subpanes:
• Debug Log: Output from the execution of each step in the procedure.
• Errors: Any errors that occurred during execution.
• Options: JSON containing Boolean flags that you can set to enable or disable run-time options for
debugging. These options are for debugging only, and by default aren’t in effect when the Integration
Procedure is called from an OmniScript.
• isDebug: Enable or disable display of debugging information.

company 587
• 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
• resetCache and ignoreCache: Enable or disable caching features. For details about caching, see
Cache for DataRaptors and Integration Procedures.
Access Integration Procedure Data JSON with Merge Fields

Enable Integration Procedure elements and element properties to access data JSON using merge fields. A
merge field is a variable that references the value of a JSON node. For example, if a JSON node
is "FirstName": "John", then the merge field %FirstName% returns John.
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.
Common Use Cases

• Setting values to rename elements, access JSON nodes, run formulas, and populate elements. See Set
Values for Integration Procedures.
• Access data stored in Integration Procedure elements in a formula or in a future step.
• Access data returned from an action. For example, a DataRaptor Action or an HTTP Action returns data
from Salesforce or an external source. See Integration Procedure Actions.
Access the Data JSON

Use existing data JSON in an element property by indicating the use of a merge field.
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.

"ContactInfo": { Use a colon symbol : to access a nested JSON node.
"FirstName": "John"
} %ContactInfo:FirstName%

company 588

"ContactInfo": { Use |n to access a specific node in a list. This merge field returns Steve:
"ContactInfoList": [
{ %ContactInfo:ContactInfoList|3:FirstName%
"FirstName": "John"
},
{
"FirstName": "Adam"
},
{
"FirstName":
"Steve"
}
]
}
Group Integration Procedure Steps Using Blocks

In an OmniStudio Integration Procedure, you can run a group of related steps as a unit inside a block to
execute them conditionally, cache them, repeat them for each item in a list, or return an error if they fail.
Integration Procedures provide these block types:
• 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.
Define Execution Logic Using Conditional Blocks

A Conditional Block executes in its entirety if an expression is true, executes one of a set of mutually
exclusive conditions defined in the steps it contains, or both.
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.

company 589
How to Compose IF - ELSEIF - ELSE Logic

To define a set of mutually exclusive conditions, use a Conditional Block and check Is If Else Block. For
each action in the block, specify a unique condition in its Execution Conditional Formula. The sequence
of actions is important: When the block is executed, the first action that has an Execution Conditional
Formula that evaluates to True is executed, then execution resumes with the step following the Conditional
Block. No other actions in the block execute. To configure a step that is executed if none of the preceding
steps execute, leave the Execution Conditional Formula of the last step blank. The following figure
illustrates the use of this logic to perform a different action, depending on the type of device. The
Conditional Block itself executes only when the device being processed comes from Apple, and the block
contains actions that execute only for a specific type of device. To execute multiple actions for a condition,
you can nest Conditional Blocks.
See Also
• Conditional Block Properties
• Create a Conditional Block Example with If-Elseif-Else Logic
Conditional Block Properties

These properties are unique to or function in a unique manner in Conditional Blocks. A Conditional Block
executes in its entirety if an expression is true, executes one of a set of mutually exclusive conditions
defined in the steps it contains, or both.
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
• Group Integration Procedure Steps Using Blocks

• Create a Conditional Block Example with If-Elseif-Else Logic

company 590
Create a Conditional Block Example with If-Elseif-Else Logic

Based on a price and a state code, an Integration Procedure calculates the sales tax and reports the total
price. For brevity, only four state codes are included: WA, OR, CA, and NV.
The Integration Procedure has these components:
• A Conditional Block, named StateSalesTaxes

• Set Values components within the Conditional Block, named IfCA, IfOR, IfWA, IfNV, and IfOtherState
• Set Values components following the Conditional Block, named CalculateTax and AssembleOutput
• A Response Action, named Response
The Structure panel looks like this:
To build this Integration Procedure:
1. From the OmniStudio Integration Procedures tab, click New.

2. Provide an Integration Procedure Name, a Type, and a SubType, and click Save.
3. Drag a Conditional Block into the Structure panel, set its Element Name to StateSalesTaxes, and
check Is If Else Block.

company 591
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:
Property IfOR IfWA IfNV IfOtherState

Element Name IfOR IfWA IfNV IfOtherState
Element Value Map, Element Name ORSalesTax WASalesTax NVSalesTax DefaultSalesTax
Element Value Map, Value 0 0.0921 0.0832 0.07
Response JSON Path ORSalesTax WASalesTax NVSalesTax DefaultSalesTax
Response JSON Node SalesTax SalesTax SalesTax SalesTax
Execution Conditional Formula State == "OR" State == "WA" State == "NV" (leave blank)
6. Drag a Set Values component after the Conditional Block and set its Element Name to
CalculateTax. Under the Element Value Map, give it the following settings:
Element Name Value

Tax =(%Price% * %SalesTax%)
TaxRate =(%SalesTax% * 100)
Total =(%Price% + (%Price% * %SalesTax%))
7. Drag a Set Values component after the previous one and set its Element Name to AssembleOutput.
Click Edit as JSON and edit the ElementValueMap node as follows:
"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.

company 592
9. Go to the Preview tab and click Edit as JSON.

10. Paste the following input into the Input Parameters panel:
{
"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
• Define Execution Logic Using Conditional Blocks

• Conditional Block Properties
Enhance Performance Using Cache Blocks

Using a cache to store frequently accessed, infrequently updated data saves round trips to the database
and improves performance. Use Cache Blocks if some parts of the Integration Procedure update data, or if
you need different cached data to expire at different times. For example, current weather data changes
more frequently than user session data.
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.
Here’s an example Cache Block configuration:

company 593
Test Options for Cache-Block Caching in Preview

When you test an Integration Procedure that includes a Cache Block in the Preview tab, you can use two
caching settings in the Options JSON section. These settings also affect top-level caching but have no
effect on the metadata cache.
• 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.
The Options pane on the Preview tab looks like this:

company 594
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.
Cache Block JSON Nodes

An active Integration Procedure that uses a Cache Block can include the following JSON nodes in its
Debug Log output, which is visible on the Preview tab:
• vlcCacheKey — Key for any data stored in the cache

• vlcCacheResult — Included and set to true if data is retrieved from the cache
• vlcCacheEnabled — Included and set to false if the ignoreCache setting disables caching
• vlcCacheException — Any caching errors
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:

company 595
Apex Methods to Clear Cache Block Data

If you must clear Cache Block data from the cache, follow the instructions in this topic, but execute one of
these lines of code instead:
IntegrationProcedureService.clearSessionCache('Type_Subtype', 'blockName', new

Map<String, Object>{'key' => 'value'});
IntegrationProcedureService.clearOrgCache('Type_Subtype', 'blockName', new

Map<String, Object>{'key' => 'value'});
IntegrationProcedureService.clearSessionCache('vlcCacheKey');
IntegrationProcedureService.clearOrgCache('vlcCacheKey');
For example, execute the following code if:
• You want to clear a Cache Block key in the Org Cache

• The Type_Subtype parameter for the Integration Procedure is LastNames_Cached
• The Cache Block is named CacheContacts
• The cache key you want to clear is ContactLastName
• The key's value is Smith
IntegrationProcedureService.clearOrgCache('LastNames_Cached', 'CacheContacts',
new Map<String, Object>{'ContactLastName' => 'Smith'});

company 596
The following example clears the session cache using a vlcCacheKey value:
IntegrationProcedureService.clearSessionCache('2032076016a1745801061oc');
See Also
• Cache Block Properties
• Create a Cache Block Example
Cache Block Properties

These properties are unique to or function in a unique manner in Cache Blocks. Use Cache Blocks if some
parts of the Integration Procedure update data and therefore shouldn't be cached, or if different cached
data should expire at different times.
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
Create a Cache Block Example

An Integration Procedure accepts a list of first or last names and retrieves Contacts having those names. A
Cache Block improves Contact retrieval performance.

company 597
This Integration Procedure also includes a Loop Block; see Process Arrays Using Loop Blocks.
This Integration Procedure has these components:
• A Cache Block, named CacheBlock1

• A Loop Block within the Cache Block, named LoopBlock1
• A DataRaptor Extract Action within the Loop Block, named ExtractContact
• A Response Action, named ResponseAction

3. Drag a Cache Block into the Structure panel and give it the following settings:
Property Value
Salesforce Platform Cache Type Org Cache
Time To Live In Minutes 5
Cache Keys contactId set to %ExtractContact:Contact:Id%
contactName set to %ExtractContact:Contact:Name%

Cache Block Output LoopBlock1 set to %LoopBlock1%
4. Drag a Loop Block inside the CacheBlock and give it the following settings:
Property Value
Loop List names
Additional Loop Output ExtractContact set to %ExtractContact%

company 598
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
A mapping from Contact:Name to Contact:Name
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"
}
]
}
To demonstrate performance most effectively, specify common and/or many names.

9. Click Execute and note the resulting Browser, Server, and Apex CPU values.
10. Open the Options pane and change the ignoreCache value to false.

company 599
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
• Cache Block Properties

• Enhance Performance Using Cache Blocks
Process Arrays Using Loop Blocks

A Loop Block iterates over the items in a data array, enabling the Actions within it to repeat for each item.
For example, in Vlocity Communications, Media, and Energy, without a Loop Block, adding four products to
a cart would require running four separate Remote Actions. But one Remote Action within a Loop Block can
add all four products.

company 600
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.
To configure a Loop Block:
1. Drag a Loop Block into the structure panel.

2. In the Loop Block property field labeled Loop List, enter the name of a JSON node that contains an
array of data. For example, entering Products:Ids provides a list of Ids to the Action. The JSON
node name does not need to be entered with merge field syntax.
3. Add any Action that needs to iterate over the array and pass the full the path of the array to the action.
For example, if the Loop List is set to an array named Products:Ids that contains key-value pairs of
Ids, the full path in the action would be Products:Ids:Id.
For more information on Actions, see Integration Procedure Actions.
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%.

company 601
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
Loop Block Properties

These properties are unique to or function in a unique manner in Loop Blocks. A Loop Block iterates over
the items in a data array, enabling the Actions within it to repeat for each item.
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
• Process Arrays Using Loop Blocks

Create a Loop Block Example that Retrieves Names

An Integration Procedure accepts last names and returns the full names of all Contacts having the specified
last names.
• An optional Set Values component, named SetValues1

• A Loop Block component, named LoopBlock1
• A DataRaptor Extract Action component within the Loop Block, named DataRaptorExtractAction1

company 602
• A DataRaptor Extract that uses the LIKE operator to find names similar to those in the input, named
ExtractFirstNames
• A Response Action, named ResponseAction1

3. Provide input with the following structure, using last names of your choice:
{
"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:

company 603
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
A mapping from Contact:LastName to Name:Last
Examples.
6. Drag a DataRaptor Extract Action component within the Loop Block and give it the following settings:
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,

company 604
"LoopBlockIterationIndex": 1
},
{
"DataRaptorExtractAction1": {
"Name": [
{
"Last": "Torres",
"First": “Maria”
},
{
"Last": "Torres",
"First": “Ricardo”
}
]
},
}
],
"LoopBlock1Status": true,
"options": {
"chainable": false
},
"names": [
{
"Name": "Miller"
},
{
"Name": "Torres"
}
]
}
See Also

Create a Loop Block Example that Creates Contacts

An Integration Procedure accepts an Account Id and an array of first and last names and creates new
Contacts for the specified Account. It also includes a step that deletes these Contacts, which you can
optionally disable.

company 605
• An optional Set Values component, named SetValues1

• A Loop Block component, named LoopBlock1
• A DataRaptor Post Action component within the Loop Block, named CreateContact
• A DataRaptor Load that creates a new Contact for an existing Account, named NewContactForAccount
• A Delete Action component within the Loop Block, named DeleteContact

3. Provide input with the following structure, using names of your choice:
{
"Contacts": [
{
"Name": {
"First": "John",

company 606
"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 {}.
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:
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:
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:

company 607
{
"response": {},
"LoopBlock1": [
{
"CreateContact": {
"ActualTime": 793,
"CpuTime": 537,
"Contact_2": [
{
"UpsertSuccess": true,
"Id": "0034N00001qh5hVQAQ",
"LastName": "Doe",
"FirstName": "John"
}
],
"Account_1": [
{
"Id": "0016100001BKL4uAAH"
}
],
"error": "OK",
"responseType": "SObject"
},
"DeleteContactStatus": true,
"CreateContactStatus": true,
},
{
"CreateContact": {
"ActualTime": 1262,
"CpuTime": 799,
"Contact_2": [
{
"Id": "0034N00001qh5hWQAQ",
"LastName": "Doe",
"FirstName": "June"
}
],
"Account_1": [
{

company 608
"Id": "0016100001BKL4uAAH"
}
],
"error": "OK",
},
"DeleteContactStatus": true,
"CreateContactStatus": true,
}
],
"LoopBlock1Status": true,
"SetValues1": {
"Contacts": [
{
"Name": {
"Last": "Doe",
"First": "John"
}
},
{
"Name": {
"Last": "Doe",
"First": "June"
}
}
],
"AccountId": "0016100001BKL4uAAH"
},
"SetValues1Status": true,
"options": {
"chainable": false
}
}
See Also


company 609
Create a Loop Block Example that Concatenates List Items

An Integration Procedure concatenates the values of items in a list. In this case, it creates an underscore-
separated String of QuoteLineItem Ids.
To watch a video that shows how to create this Integration Procedure, click here.
The input looks like this:
{
"QuoteLineItems": {
"Ids": [
{
"Id": "0QL3h000000VF04GAG"
},
{
"Id": "0QL3h000000VEvlGAG"
}
]
}
}
The output looks like this:
{
"Output": "0QL3h000000VF04GAG_0QL3h000000VEvlGAG"
}
• A Set Values component before the Loop Block, named InitString

• A Loop Block, named LoopBlock1
• A Set Values component within the Loop Block, named ConcatListItem
• A Set Values component after the Loop Block, named TrimUnderscore

company 610

3. Drag a Set Values component into the Structure panel and give it the following settings:
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:
Element Name Set this value to ConcatListItem.
Element Value Map, Click Add New Value and assign an Element Name of Concat.
Element Name

company 611
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:
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:
Send JSON Path Set this value to TrimUnderscore:Trim.
Send JSON Node Set this value to Output.

9. In the Input Parameters panel, provide input with the following structure:
{
"QuoteLineItems": {
"Ids": [
{
"Id": "0QL3h000000VF04GAG"
},
{
"Id": "0QL3h000000VEvlGAG"
}
]
}
}
10. Click Execute. The output should look something like this:
{
"Output": "0QL3h000000VF04GAG_0QL3h000000VEvlGAG"
}
See Also


company 612

Handle Errors Using Try-Catch Blocks

A Try-Catch Block lets you "try" running the steps inside it and then "catch" the error if a step fails.
To set up a Try-Catch Block:
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
• Try-Catch Block Properties

• Create a Try-Catch Block Example
• Create a Try-Catch Block Example with a Formula
Try-Catch Block Properties

These properties are unique to or function in a unique manner in Try-Catch Blocks. A Try-Catch Block lets
you "try" running the steps inside it and then "catch" the error if a step fails.
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
• Handle Errors Using Try-Catch Blocks


company 613
Create a Try-Catch Block Example

An Integration Procedure creates and deletes a Contact with the specified LastName and returns an error
message if the LastName is blank.
• A Try-Catch Block, named TryCatchBlock1

• A DataRaptor Post Action, named DataRaptorPostAction1
• A Delete Action, named DeleteAction1

3. Drag a Try-Catch Block into the Structure panel and give it the following settings:
a. Under Failure Response, click Add Key/Value Pair. Set the Key to failureResponse and the
Value to You must provide a last name.
b. Make sure the Fail on Block Error checkbox is checked.
4. Create the DataRaptor Load that the DataRaptor Post Action component calls:
a. Give it a DataRaptor Interface Name of CreateContact and an Interface Type of Load.
b. On the Objects tab, click Add Object and select Contact.

company 614
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": {},
"DeleteAction1": [
{
"errors": [],
"success": true,
"id": "0034N00001rNgqqQAC"
}
],
"DeleteAction1Status": true,
"TryCatchBlock1": null,
"TryCatchBlock1Status": true,
"DataRaptorPostAction1": {
"ActualTime": 626,
"CpuTime": 345,
"Contact_1": [
{
"Id": "0034N00001rNgqqQAC",
"LastName": "Aristotle"
}
],
"error": "OK",
},
"DataRaptorPostAction1Status": true,
"options": {
"queueableChainable": false,

company 615
"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

Create a Try-Catch Block Example with a Formula

An Integration Procedure finds Contacts with the specified Name and returns an error message if none are
found. Because returning no records normally isn't considered a failure, the DataRaptor Extract Action
within the Try-Catch Block includes a Failure Condition Formula.
• A Try-Catch Block, named TryCatchBlock1

• A DataRaptor Extract Action, named DataRaptorExtractAction1

company 616

3. Drag a Try-Catch Block into the Structure panel and give it the following settings:
a. Under Failure Response, click Add Key/Value Pair. Set the Key to failureResponse and the
Value to Name %Name% not found.
b. Make sure the Fail on Block Error checkbox is checked.
4. Create the DataRaptor Extract that the DataRaptor Extract Action component calls:
a. Give it a DataRaptor Interface Name of GetContactName and an Interface Type of Extract.
b. On the Extract tab, click Add Extract Step and select Contact. Specify the path and filter
Contact Name LIKE Name.
c. On the Output tab, click the + icon and enter Contact:Name as the Extract JSON Path and
ContactName as the Output JSON Path.
Examples.
5. Drag a DataRaptor Extract Action component within the Try-Catch Block and give it the following
settings:
a. Set the DataRaptor Interface to GetContactName.
b. Make sure the Fail on Step Error checkbox is checked.
c. Specify ISBLANK(DataRaptorExtractAction1) as the Failure Condition Formula.
6. Drag a Response Action after the Try-Catch Block and check the Return Full Data JSON checkbox.
7. 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 Name and the Value to any first or last name you like.
c. Click Execute.
If at least one Contact with that Name is found, the output should look something like this:

company 617
{
"response": {},
"TryCatchBlock1": null,
"DataRaptorExtractAction1": [
{
"ContactName": "Amy Argent"
},
{
"ContactName": "Amy Smith"
}
],
"options": {
"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 compose an Integration Procedure, you add actions that run sequentially. These actions can set data
values, perform functions, call DataRaptors, invoke Apex classes, send emails, invoke REST endpoints,
run other Integration Procedures, and more.
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.

company 618
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
Common Integration Procedure Action Properties

To compose an Integration Procedure, you add a sequence of actions. To configure an action, you set the
action's properties. Standard properties that exist in most or all actions are listed here. All properties are of
the String data type unless otherwise noted.
For details about the properties of specific actions, see the topics for the actions.
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.

company 619
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:
• Failure Conditional Formula: Result:Success == 'FALSE'

• Failure Response:
• Key: ErrorCode
• Value: %StepName:Result:ErrorCode%
Fail On Step Error If set to TRUE, the Integration Procedure ends if this step fails.
Chain On Step Allows the action to run in its own Salesforce transaction. This can slow performance but will decrease the
likelihood of exceeding the Salesforce governor limits. For more information, see Settings for Long-Running
Additional Chainable Specifies a key-value pair that is sent in the response. The value field accepts merge field syntax.
Response
Action Message Sends a message to the user if this is the first Action Message in the Integration Procedure or if this action is
chained. Useful for long-running actions.
Internal Notes Descriptive text that only someone who is viewing the Integration Procedure in the Vlocity Integration
Procedure app sees.
Set Values for Integration Procedures

The Set Values action sets values in the data JSON of an Integration Procedure literally, using merge fields,
or using formulas. This action has many uses. The example includes the most common uses.
Uses of Set Values Actions Example

The Integration Procedure that demonstrates Set Values uses restructures, concatenates, and performs
simple calculations on input data. All of its components are Set Values actions except the last, which is a
Response Action.
This example Integration Procedure has the following structure:

company 620
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.
The input data has the following structure:
{
"Name": {
"LastName": "Smith"
},
"Finances": {
"GrossIncome": "100000",
"Expenses": "60000"

company 621
}
}
Inputs: Rename Nodes in the Input Data

This component shortens and simplifies the input JSON nodes. Set its Element Value Map as follows:
Element Name Value

FirstName %Name:FirstName%
LastName %Name:LastName%
GrossIncome %Finances:GrossIncome%
Expenses %Finances:Expenses%
LocationData: Add Literal Values

This component adds literal values, which are useful for testing or for specifying data that doesn't
change.Set its Element Value Map as follows:
Element Name Value

Location San Francisco
Code 2345
TextWithCode: Concatenate Literal Values and Merge Fields

This component shows how to concatenate a literal string with a merge field. Set its Element Value Map as
follows:
Element Name Value

LocationCode Code is %LocationData:Code%
Note that the %LocationData:Code% merge field retrieves data from the previous component,
LocationData.
DeptArray: Define an Array

This component defines an array, or list of values. A later component will retrieve a value from the array. To
set up an array, click Edit as JSON and edit the ElementValueMap node as follows:
"Departments": [
"Sales",
"Development",
"Support",
"Training"
]
},
AfterTax and CalculateNet: Perform Simple Calculations Using Formulas

These components calculate after-tax income using multiplication and net income using subtraction. Note
that each operator has spaces before and after it. Set the Element Value Map of AfterTax as follows:

company 622
Element Name Value

AfterTaxIncome =%Inputs:GrossIncome% * 0.7
Set the Element Value Map of CalculateNet as follows:
Element Name Value

NetIncome =%AfterTax:AfterTaxIncome% - %Inputs:Expenses%
ConcatName: Concatenate Two Merge Fields

This component combines first and last names to form full names. Set its Element Value Map as follows:
Element Name Value

FullName =%Inputs:FirstName% + " " + %Inputs:LastName%
Note how a literal space is included.
RetrieveDept: Use a Function and Retrieving an Array Value

This component uses the IF function. It also uses listnode|listnumber notation to retrieve array
values. Set its Element Value Map as follows:
Element Name Value

Department =IF(%Inputs:FirstName% = "John",%DeptArray:Departments|2%,%DeptArray:Departments|3%)
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.
CalcFirstOfThisMonth: Perform a Complex Date Calculation

This component uses four nested date functions to return the first day of the current month. Set its Element
Value Map as follows:
Element Name Value

FirstOfThisMonth =ADDDAY(EOM(ADDMONTH(TODAY(),-1)),1)
AssembleOutput: Create the Structure of the Output Data

This component creates a JSON structure for the transformed data. To set up the structure, click Edit as
JSON and edit the ElementValueMap node as follows:
"Output": {
"FullName": "%ConcatName:FullName%",
"Department": "%RetrieveDept:Department%",
"AfterTaxIncome": "%AfterTax:AfterTaxIncome%",
"NetIncome": "%CalculateNet:NetIncome%",
"Location": "%LocationData:Location%",

company 623
"LocationCode": "%TextWithCode:LocationCode%",
"FirstOfThisMonth": "%CalcFirstOfThisMonth:FirstOfThisMonth%"
}
},
Response: Return the Output Data

This component returns the output data to the entity that called the Integration Procedure. Set one property
as follows:
Send JSON Path Response JSON Node

AssembleOutput Output
What's Next
Test the Integration Procedure that Sets Values
See Also
• Set Values Properties for Integration Procedures
Set Values Properties for Integration Procedures

These properties are unique to or function in a unique manner in Set Values actions. The Set Values action
sets values in the data JSON of an Integration Procedure literally, using merge fields, or using formulas.
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:

• Literal value
See Also
• Set Values for Integration Procedures
• Common Integration Procedure Action Properties
Test the Integration Procedure that Sets Values

After you have created the Integration Procedure that demonstrates Set Values action uses, the final step is
to test it.

2. Click Edit as JSON.
{
"Name": {

company 624
"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
• Set Values for Integration Procedures
Assert Action for Integration Procedures

The Assert Action compares the expected and actual results of a Test Procedure using an expression that
evaluates to true or false. You can use environment variables in the Assert Conditional Formula to test
performance.
See Also
• Assert Action Properties for Integration Procedures
• Test Procedures: Integration Procedures for Unit Testing
• Environment Variables in DataRaptors and Integration Procedures
Assert Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in Assert Actions. The Assert Action
compares the expected and actual results of a Test Procedure using an expression that evaluates to true or
false.
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.

company 625
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
• Assert Action for Integration Procedures

• Environment Variables in DataRaptors and Integration Procedures
Chatter Action for Integration Procedures

The Chatter Action creates a Chatter post and sends it to a Chatter feed.
See Also
• Chatter Action Properties for Integration Procedures
• Find the Id of a Community
• Workflow for Chatter Action Example
Chatter Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in Chatter Actions. All properties except
Markup Type support merge fields. The Chatter Action creates a Chatter post and sends it to a Chatter
feed.
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.
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
• Chatter Action for Integration Procedures

company 626

• Find the Id of a Community
Find the Id of a Community

To find the Id of a community, you must run a query in the Developer Console.
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:
SELECT Id,Name FROM Network
The Ids and Names of all the Communities in the org are listed.
4. Find the Name of the Community, then copy its Id.
Workflow for Chatter Action Example

An Integration Procedure sends a Chatter post to a user. This post includes text, an image, and mentions of
two other users.
To build this example:
1. Collect Ids for the Chatter Post.

2. Create the Integration Procedure with the Chatter Action.
See Also

• Chatter Action Properties for Integration Procedures
Collect Ids for the Chatter Post

Before you can create the Integration Procedure example with the Chatter Action, you must collect the Ids
needed for assembling the Chatter post.
1. Go to the People tab.

2. Go to the record pages of three users and get their Ids from the browser URL.
Each Id looks something like this: 00561000000hjm3AAA.
3. Choose which user will receive the Chatter post.
This user’s Id will be the Subject Id of the Integration Procedure's Chatter Action. You will return to this
user’s record page later to verify that the user received the Chatter post.
4. Go to the Files tab, click Upload Files, and upload an image file of your choice.
5. Select View File Details from the down-arrow menu for that file.
6. While on the file's detail page, get the Id from the browser URL.

company 627
What's Next
Create the Integration Procedure with the Chatter Action
See Also

Create the Integration Procedure with the Chatter Action

After you collect the Ids needed for assembling a Chatter post, you can create an Integration Procedure
that sends a Chatter post to a user. The example post includes text, an image, and mentions of two other
users.
1. Go to the OmniStudio Integration Procedures tab. Click New.

2. Provide a Name, Type, and SubType for the Integration Procedure. Click Save.
3. Drag a Chatter Action into the Structure panel. Assign these properties:
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


company 628
DataRaptor Extract Action for Integration Procedures

The DataRaptor Extract Action calls the specified DataRaptor Extract to read data from Salesforce and
returns it to the Integration Procedure.
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
DataRaptor Extract Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in DataRaptor Extract Actions. The
DataRaptor Extract Action calls the specified DataRaptor Extract to read data from Salesforce and returns it
to the Integration Procedure.
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
• DataRaptor Extract Action for Integration Procedures

DataRaptor Post Action for Integration Procedures

The DataRaptor Post Action calls a DataRaptor Load (post) to write data to Salesforce.
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

company 629
}],
"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
• DataRaptor Post Action Properties for Integration Procedures

DataRaptor Post Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in DataRaptor Post Actions. The DataRaptor
Post Action calls a DataRaptor Load (post) to write data to Salesforce.
DataRaptor Interface Name of DataRaptor post to run.
See Also
• DataRaptor Post Action for Integration Procedures

DataRaptor Transform Action for Integration Procedures

A DataRaptor Transform Action calls the specified DataRaptor Transform to execute transformations on the
Data JSON and returns the transformed data.
See Also
• DataRaptor Transform Action Properties for Integration Procedures

• Create a DataRaptor Transform Action Example
• DataRaptor Transform Overview
• DataRaptor Output Data Types
DataRaptor Transform Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in DataRaptor Transform Actions. A
DataRaptor Transform Action calls the specified DataRaptor Transform to execute transformations on the
Data JSON and returns the transformed data.

company 630
DataRaptor Interface Name of the DataRaptor transform to run.
Ignore Cache Disables caching in the DataRaptor Transform.
See Also
• DataRaptor Transform Action for Integration Procedures

Create a DataRaptor Transform Action Example

An Integration Procedure calls a DataRaptor Transform that calculates a sum and returns it.
1. Create the DataRaptor Transform example described in Use Formulas in DataRaptors and name it
DRFormula1.
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
Property Value
Send JSON Path DataRaptorTransformAction1:TotalPrice
Note that the DataRaptor Transform output is wrapped in a DataRaptorTransformAction1 node,

from which only the TotalPrice sub-node is selected.
Send JSON Node TotalPrice
{
"Input": {
"Products": [
{
"Name": "iPhone",
"Price": 600
},
{

company 631

"Price": 30
},
{
"Name": "Ear Buds",
"Price": 200
}
]
}
}
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
• DataRaptor Transform Action for Integration Procedures
DataRaptor Turbo Action for Integration Procedures

A DataRaptor Turbo Action calls the specified DataRaptor Turbo Extract to read data from Salesforce and
returns it to the Integration Procedure.
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
• DataRaptor Turbo Action Properties for Integration Procedures

DataRaptor Turbo Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in DataRaptor Extract Actions. A DataRaptor
Turbo Action calls the specified DataRaptor Turbo Extract to read data from Salesforce and returns it to the

company 632
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
• DataRaptor Turbo Action for Integration Procedures

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.
To delete records with the Delete Action:
1. Preview the OmniScript and identify the JSON path for the record. For example, this data JSON
contains a list of Accounts:
{ "Account": { "accId": ["001f400000EPQ8o", "001f400000BAkbn"] } }

2. In the Delete Action properties, click Add sObject to Delete.
3. In the Type column, select an Object.
4. In the Path to Id field, enter the JSON path for the record id using merge field syntax. Using the
Account example, the path to delete the array of Account ids is: %Account:accId%.
5. Preview the OmniScript and use a test record's id to test the functionality.
For Integration Procedure examples that include a Delete Action, see Process Arrays Using Loop Blocks
and Handle Errors Using Try-Catch Blocks.
Delete Action Properties

This page contains information on Delete Action Properties.
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.

company 633
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
• Confirming Record Deletion

• Displaying Messages from a Delete Action
DocuSign Envelope Action for Integration Procedures

The DocuSign Envelope Action emails a set of documents for signing.
See Also
• DocuSign Envelope Action Properties for Integration Procedures
• Using the DocuSign Envelope Action to Email Documents for Signature
DocuSign Envelope Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in DocuSign Envelope Actions. The
DocuSign Envelope Action emails a set of documents for signing.
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 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
• DocuSign Envelope Action for Integration Procedures

Email Action for Integration Procedures

An Email Action sends the specified email. You can either specify all the email field values or use a
Salesforce email template.
See Also
• Email Action Properties for Integration Procedures
• Create an Email Action Example with Specified Fields
• Workflow for Email Action Example with Template

company 634
Email Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in Email Actions. An Email Action sends the
specified email. You can either specify all the email field values or use a Salesforce email 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.
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.

CC Email Address List Specifies the recipients in the CC field of the email. Click Add Recipient to add each email address. Can
accept an array of up to 25 addresses.

BCC Email Address Specifies the recipients in the BCC field of the email. Click Add Recipient to add each email address. Can
List accept an array of up to 25 addresses.

Email Subject Specifies the email subject line.

Email Body Specifies the body of the email.

Set HTML Body Determines whether the Email Body should be read as plain text (not checked) or HTML (checked).
Available if Use Template is not checked.

Org Wide Email Specifies the sender in the FROM field of the email. This is assumed to be an email that represents the
Address entire org. If not specified, the default sender is the user that invoked the Integration Procedure. See
Organization-Wide Email Addresses in the Salesforce help.

Select Email Template Specifies the Salesforce email template. Enter the sObject Id, then select the template from the drop-down
list.

Email Target Object Id Specifies the Id of a Contact, User, or Lead with an email address.

What Id If you specify a Contact in the Email Target Object Id field, this property can 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 checked, saves the email as an activity record on the recipient’s page in Salesforce.

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

company 635
Attachment List Specifies a node in the data JSON that contains a list of attachment Ids.
See Also
• Email Action for Integration Procedures

Create an Email Action Example with Specified Fields

An Integration Procedure accepts email, subject, and message input parameters and uses them to
compose and send an email.

3. Drag an Email Action component into the Structure panel.
4. In the Email Action, remove the check from the Use Template setting.
5. Give the Email Action the following settings. Click Add Recipient to add to the address list.
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": "kim@example.com",
"subject": "Test Email",
"message": "This is a test."
}
7. Click Execute. You should receive a Test Email from your org in a few minutes.

company 636
See Also

Workflow for Email Action Example with Template

An Integration Procedure uses an Email Template and includes the sent email in the recipient's Activities
list. No Email Templates exist by default, so this example includes steps for creating one.
1. Create the Email Template.

2. Select an Email Recipient.
3. Create the Integration Procedure with the Email Action.
4. Test the Integration Procedure with the Email Action.
See Also

Create the Email Template

Create the email template that the Email Action example uses.
1. Go to the Email Templates tab, and click New Email Template.

2. In the Email Template Name field, type Simple Email Template.
3. Type any text you like in the Subject and HTML Value fields.
For example, the Subject could be Hello and the HTML Value could be Just saying hello.
4. Click Save. The Email Template's page opens.
5. While on the Email Template's page, copy the Id from the URL, for example 00X4N000000aCE5UAM.
What's Next
Select an Email Recipient
See Also

Select an Email Recipient

Select the Id of the Contact to whom the email in the Email Action example is sent.

company 637
1. Go to the Contacts tab.

2. Find a Contact that has an email address, or add an email address to a Contact.
3. While on the Contact's page, copy the Id from the URL, for example 0036100000423z8AAA.
What's Next
Create the Integration Procedure with the Email Action
See Also

Create the Integration Procedure with the Email Action

After you create the email template and select the recipient, you can create an Integration Procedure that
sends an email to a Contact.
1. Go to the OmniStudio Integration Procedures tab and click New.

3. Drag an Email Action component into the Structure panel.
4. Make sure the Use Template box is checked.
5. Copy the Email Template Id into the Select Email Template field.
6. A drop-down list appears with an item that looks like this: Simple_Email_Template_1580943234381.
Select the list item. The list item replaces the Id in the field.
7. In the Email Target Object Id field, type %contact%.
8. Check the Save As Activity box.
What's Next
Test the Integration Procedure with the Email Action
See Also

Test the Integration Procedure with the Email Action

After you have created the Integration Procedure with the Email Action, your final task is to test it.
1. Go to the Preview tab and click Add New Key/Value Pair.

2. Specify contact as the Key and the Contact Id that you copied previously as the Value.
3. Click Execute. This sends the email.
4. Go back to the Contacts tab. Select the Contact to whom you sent the email to open their page.
If the Contact record page includes an Activities component, you should see the email in the list of
activities after you click Refresh. For example:

company 638
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

HTTP Action for Integration Procedures

The HTTP Action executes a REST call and returns its results to the Integration Procedure.
See Also
• HTTP Action Properties for Integration Procedures

• Workflow for HTTP Action Example

company 639
HTTP Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in HTTP Actions. The HTTP Action executes
a REST call and returns its results to the Integration Procedure.
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

Workflow for HTTP Action Example

An Integration Procedure retrieves the astronomy picture of the day from NASA using NASA's publicly
available REST API.
1. Add NASA as a Remote Site.

2. Get an API Key from NASA.
3. Create the Integration Procedure with the HTTP Action.

company 640
See Also
Add NASA as a Remote Site

To be able to invoke NASA REST APIs from your org, you must add NASA as a Remote Site.
1. From Setup, in the Quick Find box, type remote, then click Remote Site Settings.
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
Get an API Key from NASA

You must specify an API key every time you invoke a NASA REST API. You can get this key from NASA.
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:
Your API key for me@example.com is:

YbbMNWeWX2BqxoPKXEiWWcKMgNlUHhHXgqWG5XBt
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:
Account Email: me@example.com

Account ID: b4345628-22cd-4a1d-b610-3d9ec5ba95fd
You will need your API key to run the Integration Procedure.

company 641
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
Create the Integration Procedure with the HTTP Action

After you configure NASA as a Remote Site and get a NASA API key, you can create and run the example
Integration Procedure, which retrieves the astronomy picture of the day.

3. Drag an HTTP Action component into the Structure panel and give it the following settings:
a. Set its HTTP Path to https://api.nasa.gov/planetary/apod.
b. Set its HTTP Method to GET.
c. Expand the REST OPTIONS section and click Add Param.
d. Under Params, set the Key to api_key and the Value to %ApiKey%.
4. Drag a Response Action component into the Structure panel below the HTTP Action and give it the
following settings:
a. Set its Send JSON Path to HTTPAction1.
b. Set its Send JSON Node to PictureInfo.
5. Go to the Preview tab and click Add New Key/Value Pair.
6. Set the Key to ApiKey and the Value to your NASA API key, for example
YbbMNWeWX2BqxoPKXEiWWcKMgNlUHhHXgqWG5XBt.
7. Click Execute. The output should look like this:
{
"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

company 642
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

Integration Procedure Action for Integration Procedures

The Integration Procedure Action runs a subordinate Integration Procedure.
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
Integration Procedure Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in Integration Procedure Actions. The
Integration Procedure Action runs a subordinate Integration Procedure.
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
• Integration Procedure Action for Integration Procedures


company 643
Workflow for Integration Procedure Action Example

Parent and child Integration Procedures transform a list of paired values into a list of keys and values.
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"
}
]
}
1. Create the Child Integration Procedure.

2. Create the Parent Integration Procedure.
See Also

Create the Child Integration Procedure

The child Integration Procedure renames a JSON node to the value of another JSON node and has only
one component, a Response Action.

company 644

2. Give the Integration Procedure the following settings:
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

Create the Parent Integration Procedure

The parent Integration Procedure iterates through a list and calls the child Integration Procedure for each
list item.
The parent Integration Procedure has these components:
• A Loop Block component named LoopBlock1

• An Integration Procedure Action component within the Loop Block named IntegrationProcedureAction1
• A Response Action named ResponseAction1

company 645
To create the parent Integration Procedure:

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
7. Click Edit as JSON.
8. In the Input Parameters panel, provide input with the following structure:
{
"InputList": [
{
"Key": "serial_number",

company 646
"Value": "ABC1234"
},
{
"Key": "install_date",
"Value": "20200101"
}
]
}
{
"OutputList": [
{
"serial_number": "ABC1234"
},
{
"install_date": "20200101"
}
]
}
See Also

List Action for Integration Procedures

The List Action merges multiple lists by matching values of specified list item JSON nodes. A basic merge
matches node names exactly. An advanced merge matches nodes that have different names and/or reside
at different levels in the incoming lists.
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.

company 647
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
List Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in List Actions. The List Action merges
multiple lists by matching values of specified list item JSON nodes.
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.

company 648
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.
For more information, see Function Reference.
See Also
• List Action for Integration Procedures


company 649
Workflow for List Action Examples

Three Integration Procedures with List Actions demonstrate a basic list merge, an advanced list merge, and
a list merge with dynamic output fields. Each example builds on the previous example.
To build these examples:
1. Create a Basic List Merge Example.

2. Create an Advanced List Merge Example.
3. Create a List Merge Example with Dynamic Output Fields.
See Also
Create a Basic List Merge Example

The first Integration Procedure retrieves all Contacts with the same AccountId in two lists, one containing
addresses, the other birthdates. It then merges the two lists into one.
1. A DataRaptor Extract Action component named DRExtractAddresses

2. A DataRaptor Extract Action component named DRExtractBirthdates
3. A List Action named ListAction1
4. A Response Action named ResponseAction1

company 650
1. Create the DataRaptor Extract that the DRExtractAddresses component calls. Name it GetAddresses
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
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.
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.
{
"contactMerge": [
{

company 651
"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",
"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",
"id": "0036100001E5xr2AAB",
"firstName": "Ben"
}
]
}
What's Next
Create an Advanced List Merge Example
See Also


company 652
Create an Advanced List Merge Example

The next Integration Procedure is a modified version of the previous example. Instead of matching list items
using Id fields, it uses the Advanced Merge feature to match first and last names.
1. Create a Basic List Merge Example.

2. Clone the GetBirthdates DataRaptor and name it GetBirthdates2. On the Output tab, change the
Output JSON Path values from contact:firstName to contact:FN and from
contact:lastName to contact:LN.
3. In the Integration Procedure, in the DRExtractBirthdates component, change the DataRaptor Interface
to GetBirthdates2.
4. In the Integration Procedure, in the List Action, check Advanced Merge and add the following rows to
the Advanced Merge Map table:
List Key Matching Path Matching Group

DRExtractAddresses:contact firstName 1
DRExtractBirthdates:contact FN 1
DRExtractAddresses:contact lastName 2
DRExtractBirthdates:contact LN 2
5. On the Preview tab, click Execute. The output should look something like this:
{
"contactMerge": [
{
"LN": "Jones",
"FN": "Cathy",
"birthdate": "1975-10-03",
"state": "FL",
"city": "Orlando",
"id": "0036100001E5xrWAAR",
},
{
"LN": "Jones",
"FN": "Doug",
"birthdate": "1976-10-04",
"state": "AZ",
"city": "Phoenix",
"id": "0036100001E5xrvAAB",
"firstName": "Doug"
},

company 653
{
"LN": "Smith",
"FN": "Albert",
"birthdate": "1973-10-01",
"state": "CA",
"id": "0036100001E5xqnAAB",
},
{
"LN": "Smith",
"FN": "Ben",
"birthdate": "1974-10-02",
"state": "OR",
"city": "Portland",
"id": "0036100001E5xr2AAB",
"firstName": "Ben"
}
]
}
What's Next
Create a List Merge Example with Dynamic Output Fields
See Also

Create a List Merge Example with Dynamic Output Fields

The final Integration Procedure is a modified version of the previous example. It uses Dynamic Output
Fields to eliminate the duplicate FN and LN JSON nodes from the output.
1. Create an Advanced List Merge Example.

2. In the List Action, give the Dynamic Output Fields setting a value of include.
3. On the Preview tab, in the Input Parameters pane, click Add New Key/Value Pair. Enter include as
the Key and birthdate,street,state,city,lastName,firstName,id as the Value. Note
that only commas, and not spaces, separate the node names.

company 654
{
"contactMerge": [
{
"birthdate": "1975-10-03",
"state": "FL",
"city": "Orlando",
"id": "0036100001E5xrWAAR",
},
{
"birthdate": "1976-10-04",
"state": "AZ",
"city": "Phoenix",
"id": "0036100001E5xrvAAB",
"firstName": "Doug"
},
{
"birthdate": "1973-10-01",
"state": "CA",
"id": "0036100001E5xqnAAB",
},
{
"birthdate": "1974-10-02",
"state": "OR",
"city": "Portland",
"id": "0036100001E5xr2AAB",
"firstName": "Ben"
}
]
}
See Also


company 655
Remote Action for Integration Procedures

A Remote Action calls the specified Apex class and method. You can also pass in invocation options and
data.
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
Remote Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in Remote Actions. A Remote Action calls
the specified Apex class and method. You can also pass in invocation options and data.
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
• Remote Action for Integration Procedures

Workflow for Remote Action Example

An Integration Procedure uses a Remote Action to call an Apex class and demonstrate how to reserialize
data.
To download a DataPack of this example, click here. The DataPack does not include the Apex class.
1. Create the TestReserializeApex Class.

2. Create the Integration Procedure with the Remote Action.

company 656
3. Test the Integration Procedure with the Remote Action.
See Also
Create the TestReserializeApex Class

Before you can create the Integration Procedure example, you must create the TestReserializeApex
Apex class that it calls.

3. Click New.
@JsonAccess(serializable='always')
global with sharing class TestReserializeApex implements
vlocity_ins.VlocityOpenInterface2 {
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

company 657
See Also

Create the Integration Procedure with the Remote Action

An Integration Procedure retrieves and reserializes the value of a name variable from the
TestReserializeApex Apex class.
• A Remote Action, named ReserializeApex

• A Set Values component, named ReserializeApexFunction
• A Set Values component, named MyName

3. Drag a Remote Action component into the Structure panel and give it the following settings:
Property Value
Element Name ReserializeApex
Remote Class TestReserializeApex

company 658
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.
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

Test the Integration Procedure with the Remote Action

After you have created the example Integration Procedure with the Remote Action, the final task is to test it.
1. Go to the Preview tab and click Execute. The output should look like this:
{
"response": {},
"vlcchainableStepDepth": 0,
"MyName": {
"Full Name": "Dave Smith"

company 659
},
"MyNameStatus": true,
"ReserializeApexFunctionStatus": true,
"ReserializeApex": {
"result": {
"name": "Dave Smith"
},
"errorCode": "INVOKE-200",
"error": "OK"
},
"ReserializeApexStatus": true,
"options": {
"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": {},
"MyName": {
"Full Name": ""
},
"result": {
},
"error": "OK"
},
"options": {
"chainable": false

company 660
}
}
Note that the Full Name node has no value.

4. Go to the Properties tab, select the ReserializeApex component, and change the Remote Options
Value to true. This enables reserialization in a different way.
5. Go to the Preview tab and click Execute a third time. The output should look like this:
{
"response": {},
"MyName": {
"Full Name": "Dave Smith"
},
"error": "OK",
"result": {
}
},
"options": {
"chainable": false
}
}
Note that the Full Name node has a value again.
See Also
Response Action for Integration Procedures

The Response Action ends an Integration Procedure and returns data to the entity that called it. It can also
add data to the data JSON or end conditionally. Response Actions are useful for debugging Integration
Procedures.
Response Actions are also useful for trimming the data response. For specific trimming strategies, see

company 661
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
Response Action Properties for Integration Procedures

These properties are unique to or function in a unique manner in Response Actions. The Response Action
ends an Integration Procedure and returns data to the entity that called it.
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:
Key Field: Key1:Key2
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
Integration Procedure Best Practices

To maximize the benefits of Integration Procedures, follow the best practices whenever possible.
• Use Integration Procedures for all data calls to Salesforce.

• Use a Response Action for Integration Procedures to trim the data and only return what is needed. For
specific trimming strategies, see Manipulate JSON with the Send/Response Transformations Properties.
• Use multiple Response Actions with different Execution Conditional Formulas to allow an Integration
Procedure to exit early under appropriate conditions.
• Use caching to store frequently accessed, infrequently updated data. See Cache for DataRaptors and

company 662
• 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?.
Cache for DataRaptors and Integration Procedures

Using a cache to store frequently accessed, infrequently updated DataRaptor and Integration Procedure
data saves round trips to the database and improves performance.
You can use caching with DataRaptors in three ways:
• 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 use caching with Integration Procedures in three ways:
• You can cache metadata for the entire Integration Procedure.

• You can cache the response of the entire Integration Procedure, called top-level data. See Cache for
Top-Level Integration Procedure Data.
• You can cache the result of a specific set of steps by placing the steps inside a Cache Block. See
Enhance Performance Using Cache Blocks.
Use Cache Blocks if some parts of the Integration Procedure update data, or if you need different cached
data to expire at different times. For example, current weather data changes more frequently than user
session data.
You can also perform a record-level security check for cached data. See Security for DataRaptors and
Metadata Cache for DataRaptors and Integration Procedures

Integration Procedure metadata is cached by default and DataRaptor metadata is automatically cached.
To disable metadata caching for an Integration Procedure, go to the Procedure Configuration and check the
Disable Definition Cache checkbox.

company 663
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.
Methods to Clear Metadata from Either Cache

If you must clear DataRaptor metadata from the cache, follow the instructions in this topic, but execute one
of these lines of code instead:
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');
Methods to Clear Data from the Scale Cache

OmniStudio DataRaptors and Integration Procedures use the Scale Cache and not the Platform Cache. To
clear the Scale Cache, you can use either the preceding methods or the following ScaleCacheService
method.

company 664
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:
DataRaptor_Name});
For example, to clear data from a DataRaptor named ExtractContactName, use this line of code:
'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:
String>{'VIPId' =>
Type_SubType});
For example, to clear data from an Integration Procedure with a Type_SubType of

LoopList_ContactNames, use this line of code:
String>{'VIPId' =>
'LoopList_ContactNames'});
See Also
• Turn Off the Scale Cache
Cache for Top-Level Integration Procedure Data

Using a cache to store frequently accessed, infrequently updated Integration Procedure data saves round
trips to the database and improves performance. You can cache all the data for an Integration Procedure,
as described here, or you can use a Cache Block to cache only part of it.
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.

company 665
NOTE
If an Integration Procedure that has top-level caching enabled fails, its data isn’t cached.
Options in Preview for Top-Level Caching

When you test an Integration Procedure that uses top-level caching in the Preview tab, you can use two
caching settings in the Options JSON section. These settings control top-level data and have no effect on
the metadata cache.
• 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.
The Options pane on the Preview tab looks like this:

company 666
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.
Top-Level Caching JSON Nodes and REST Headers

If top-level caching is configured and the Integration Procedure is active, the Integration Procedure JSON
can include the following nodes under the root node:
• vlcCacheKey — Key for any data stored in the cache

• vlcCacheResult — Included and set to true if data is retrieved from the cache
• vlcCacheEnabled — Included and set to false if the ignoreCache setting disables caching
• vlcCacheException — Any caching errors
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.
Methods for Clearing Top-Level Data

If you must clear top-level Integration Procedure data from the cache, follow the instructions in this topic,
but execute one of these lines of code instead:
IntegrationProcedureService.clearSessionCache('Type_Subtype', new Map<String,

Object>{'key' => 'value'});
IntegrationProcedureService.clearOrgCache('Type_Subtype', new Map<String,

Object>{'key' => 'value'});
IntegrationProcedureService.clearSessionCache('vlcCacheKey');
IntegrationProcedureService.clearOrgCache('vlcCacheKey');
For example, execute the following code if:
• You want to clear data in the Org Cache

• The Type_Subtype parameter for the Integration Procedure is LastNames_Cached
• The key you want to clear is ContactLastName
• The key's value is Smith
IntegrationProcedureService.clearOrgCache('LastNames_Cached', new Map<String,

Object>{'ContactLastName' => 'Smith'});
The following example clears the session cache using a vlcCacheKey value:

company 667
IntegrationProcedureService.clearSessionCache('2032076016a1745801061oc');
Configure Top-Level Caching for an Integration Procedure

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.
1. Go to the Procedure Configuration.

2. In the Cache Configuration section, set the Salesforce Platform Cache Type to one of the following:
• Blank — For no caching
• Session Cache — For data related to users and their login sessions
• Org Cache — For all other types of data
Behind this drop-down is the IsCacheable__c picklist.

3. Specify a value for Time To Live In Minutes. This setting determines how long data remains in the
cache. The minimum value is 5. Default and maximum values depend on the cache type:
• Session Cache — The default value is 5. The maximum value is 480, equivalent to 8 hours. The
cache is cleared when the user's session expires regardless of this value.
• Org Cache — The default value is 1440, equivalent to 24 hours. 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. Top-level and Cache Block data is cleared when the Integration Procedure is
deactivated regardless of this value.
4. Click Activate Version. Top-level caching occurs only if the Integration Procedure is active.
See Also
• Cache for Top-Level Integration Procedure Data
Create a Top-Level Caching Example

An Integration Procedure accepts a list of first or last names and retrieves Contacts having those names.
Top-level caching to the VlocityAPIResponse partition improves Contact retrieval performance.
This Integration Procedure also includes a Loop Block; see Process Arrays Using Loop Blocks.

company 668
This Integration Procedure has these components:
• A Loop Block, named LoopBlock1

• A DataRaptor Extract Action within the Loop Block, named ExtractContact
• A Response Action, named ResponseAction

3. In the Procedure Configuration, set the Salesforce Platform Cache Type to Org Cache.
4. Drag a Loop Block component into the Structure panel. Give the Loop Block the following settings:
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,
Tab Settings
Extract A Contact extract step set to Contact Name LIKE name
Output A mapping from Contact:Id to Contact:Id
A mapping from Contact:Name to Contact:Name
Examples.

company 669
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"
}
]
}
To demonstrate performance most effectively, specify common names or many names.

10. Click Execute and note the resulting Browser, Server, and Apex CPU values.
11. Open the Options pane and change the ignoreCache value to false.

company 670
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.
Turn Off the Scale Cache

To turn off the Scale Cache that DataRaptors and Integration Procedures use, go to Setup and add the
TurnOffScaleCache setting to the Omni Interaction Configuration.
1. Go to Setup.
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
Error Handling in Integration Procedures

You can configure the conditions for success or failure of an Integration Procedure action or group of
actions.

company 671
In each step, you can set the following properties:
• 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:
• Response headers, for example, Content-Type

• Status of the response
• Status code, for example, 200
Environment Variables in DataRaptors and Integration Procedures

You can use environment variables to define Default Values and Filter Values, and in Formulas.
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.

$Vlocity.TODAY Today’s date
$Vlocity.TOMORROW Tomorrow’s date

company 672

$Vlocity.NOW Current date and time
$Vlocity.N_DAYS_FROM_NOW:{N} The date the specified number of days from now
$Vlocity.N_DAYS_AGO:{N} The date the specified number of days ago
$Vlocity.NULL Null
$Vlocity.StandardPricebookId Id of the standard pricebook
$Vlocity.DocumentsFolderId Documents folder Id
$Vlocity.true or $Vlocity.TRUE Boolean TRUE
$Vlocity.false or $Vlocity.FALSE Boolean FALSE
$Vlocity.UserId Current user Id
$Vlocity.Percent Percent character. Useful for escaping % characters in URLs so they aren't mistaken for merge
field syntax.
$Vlocity.CpuTotal Apex CPU value
$Vlocity.DMLStatementsTotal Number of Data Manipulation Language statements
$Vlocity.DMLRowsTotal Number of Data Manipulation Language rows
$Vlocity.HeapSizeTotal Heap size value
$Vlocity.QueriesTotal Number of queries run
$Vlocity.QueryRowsTotal Number of query rows fetched
$Vlocity.SoslQueriesTotal Number of SOSL queries run
External Objects in Integration Procedures

Integration Procedures support Salesforce External Objects. The external data can come from any source
that can be accessed using a REST endpoint. The returned data can be rendered as JSON or XML.
Here's how it works:
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 following diagram illustrates the process.

company 673
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.
Query-Handling Logic in the Integration Procedure

To indicate the type of operation being requested of the Integration Procedure, the Vlocity handler sets a
"Context" entry in the input JSON. To define the actions for handling each type of query in your Integration
Procedure, set the actions' Execution Conditional Formula field (for example: Context = "QueryAll"). The
following list describes the values passed in the Context node for each type of request, with SOQL
examples and the corresponding JSON payload sent to the Integration Procedure.
QueryAll: SELECT returning all rows (no WHERE clause)
Example query: SELECT ExternalId FROM myExternalObject;
Corresponding JSON input: {"Context":"QueryAll"}
Query: SELECT with WHERE clause
Example query: SELECT ExternalId FROM vlocity_dev__ContactsList__x WHERE

ExternalId = '59f0f91a51280e0012c90584';
Corresponding JSON input: {"Input":

[{"ExternalId":"59f0f91a51280e0012c90584"}],"Context":"Query"}
Upsert: Update a row (if ExternalId is specified) or create a row (if ExternalId is omitted).
Example query (UPDATE): INSERT INTO myExternalObject (Name, Mobile...) VALUES

("Davidov Spruth", "415-607-9865"...)
Corresponding JSON input: {"Input":[{"Name":"Davidov

Spruth","Mobile":"415-607-9865","CreateDate":"2017-10-25T20:50:34.188Z","Work":
"415-232-6365","ExternalId":"59f0f91a51280e0012c90584","Email":"davs@gmail.com"
}],"Context":"Upsert"}
Delete: Delete specified rows.
Example query: DELETE FROM myExternalObject WHERE ExternalId =

'"'59f0f91a51280e0012c90584'"';

company 674
Corresponding JSON input: {"Input":

[{"ExternalId":"59f0f91a51280e0012c90584"}],"Context":"Query"}
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.
Query Result Format

To return results from the Integration Procedure to the query, structure the output JSON as follows:
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": "davs@gmail.com",
"CreateDate": "2017-10-25T20:50:34.188Z",
"Name": "Davidov Spruth",
"ExternalId": "59f0f91a51280e0012c90584",
"ExternalLookup": "59f0f91a51280e0012c90584",
"AccountIndirectLookup": "123"
},
{
"Email": "mw@gmail.com",
"CreateDate": "2017-10-25T21:49:41.633Z",
"Name": "Mike Wormwood",
"ExternalId": "59f106f5e928870012f2b0a0",
},
{
"Work": "33-555-1212",
"Mobile": "33-879-0610",
"CreateDate": "2017-10-25T20:59:18.657Z",
"Name": "Tom Sor",
"ExternalId": "59f0fb26e928870012f2b09e",
}
]
UPDATE and DELETE queries: Return the external Id of the object affected in a node named "ExternalID";
for example:

company 675
{
"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
Implement an External Object in an Integration Procedure

To access external data, you can define an Integration Procedure that implements a Salesforce External
Object.
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
Test Procedures: Integration Procedures for Unit Testing

An Integration Procedure that performs a unit test is a Test Procedure. You can use a Test Procedure to
unit test almost anything an Integration Procedure can invoke, such as a DataRaptor, a Calculation Matrix,
an Apex class, or another Integration Procedure.
Using Test Procedures and the test framework, you can:
• Add Debugging Data to Test Procedure Event Tracking.

• Provide sample input to the entity being tested using a Set Values for Integration Procedures component.
• Mock responses of specific steps if the entity being tested is an Integration Procedure.
• Compare expected and actual results using an Assert Action for Integration Procedures component.
• Use the IDX Workbench Desktop Application to run Test Procedures.
• Review Integration Procedure Event Tracking data generated as a result of the tests.
After a Test Procedure finishes, its transaction is rolled back. This lets you run tests that create sObjects
without affecting the database.

company 676
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.
When to Mock Integration Procedure Components

When you use a Test Procedure to test another Integration Procedure, you can simulate, or mock, the
responses of some of the components in the testing Integration Procedure or the Integration Procedure
being tested. For example, you can mock a component that would normally retrieve a credit score, using a
hard-coded score for testing. This has no effect on how the Integration Procedure normally runs when it
isn't being tested.
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.
Component Reason for Mocking

DocuSign Envelope Action for Integration Procedures The response to the delivered email isn't available.
Email Action for Integration Procedures The response to the delivered email isn't available.
HTTP Action for Integration Procedures Salesforce has specific requirements for testing HTTP callouts.
HTTP Callouts in Called Apex Classes

If a Test Procedure or an Integration Procedure being tested includes a Remote Action, and the Apex class
the Remote Action invokes includes an HTTP callout, then you must ensure that the HTTP callout isn't part
of the test. To do this, edit the Apex class and enclose the HTTP callout in an if
(IntegrationProcedureService.isTest == false) statement, for example:
if (IntegrationProcedureService.isTest == false) {
HttpRequest request = new HttpRequest();
request.setMethod('GET');
request.setEndpoint('http://example.com');
Http httpCall = new Http();

HttpResponse response = httpCall.send(request);
}

company 677
Workflow for Test Procedure Example

A Test Procedure tests a calculation performed by another Integration Procedure.
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.
High-level steps 3 and 4 are described here.
See Also
• Assert Action for Integration Procedures
• Assert Action Properties for Integration Procedures
Mock a Response in the Tested Integration Procedure

Before you create the example Test Procedure, add a Mock Response Map to the Integration Procedure to
be tested.
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
• Workflow for Test Procedure Example


company 678
Create an Example Test Procedure

After you mock a response in the Integration Procedure to be tested, create the Test Procedure that tests a
calculation it performs.
The Test Procedure has these components:
• A Set Values component, named IPInput

• An Integration Procedure Action component, named TestIP
• An Assert Action, named AssertTotal
• A Response Action, named TestResponse
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.
To create the Test Procedure:

3. Scroll to the bottom of the Procedure Configuration and check Is Test Procedure.
Property Value
Element Name IPInput
Element Value Map: Price 250
Element Value Map: State NY

company 679
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,

company 680
"Total": 265
}
},
"TestIPStatus": true,
"IPInput": {
"Price": 250,
"State": "NY"
},
"IPInputStatus": true,
"options": {
"useQueueableApexRemoting": 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
Integration Procedure Invocation

You can invoke Integration Procedures from other OmniStudio tools such as OmniScripts and Cards. You
can also invoke Integration Procedures from Apex classes, batch jobs, REST APIs, or Salesforce flows.
Integration Procedure Invocation from Apex

You can invoke an Integration Procedure from Apex code in two ways using the
IntegrationProcedureService class in the Vlocity managed package.
Integration Procedure Call Example 1

class IntegrationProcedureService {
/*
procedureAPIName - the Type_SubType of Procedure or the OmniScript__c.Id
input - The payload / initial data in the DataJSON for the Procedure
*/
public static Object runIntegrationService(String procedureAPIName,
Map<String, Object> input, Map<String, Object> options);

company 681
/*
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);
}
Integration Procedure Call Example 2

/* Initialize variables */
String procedureName = 'Type_SubType';
Map<String, Object> ipInput = new Map<String, Object> ();
Map<String, Object> ipOutput = new Map<String, Object> ();
Map<String, Object> ipOptions = new Map<String, Object> ();
/* Populating input map for an Integration Procedure.

Follow whatever structure your VIP expects */
String orderId = '80100000000abcd';
ipInput.put('orderId', orderId);
/* Call the IP via runIntegrationService,

and save the output to ipOutput */
ipOutput = (Map<String, Object>)
vlocity_cmt.IntegrationProcedureService.runIntegrationService(procedureName,
ipInput, ipOptions);
System.debug('IP Output: ' + ipOutput);
Integration Procedure Unit Testing from Apex

You can set up a test class in Apex and use it to call and test an Integration Procedure. You must mock
HTTP Action responses.
The following is an example unit test of an Integration Procedure:
@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>{

company 682
'AccountName' => 'Vlocity'

}, new Map<String, Object>());
System.assertEquals('joe@vlocity.com', response.get('ContactEmail'));
}
}
Note these features of the example:
• 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:
global with sharing class TestVlocityIntergationProcedure
{
static testMethod void testVipWithHttpCallout()
{
HttpResponse res = new HttpResponse();
res.setHeader('Content-Type', 'application/json');
res.setBody('{"ContactEmail":"joe@vlocity.com"}');
res.setStatusCode(200);
namespace.IntegrationProcedureServiceTest.setMockHttpResponse(res);

pe',

company 683
}
}
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:
global with sharing class TestMockHttpIP
{
static testMethod void testVipWithHttpCallout()
{
HttpResponse res1 = new HttpResponse();
res1.setHeader('Content-Type', 'application/json');
res1.setBody('{"ContactEmail":"joe@vlocity.com"}');
res1.setStatusCode(200);
namespace.IntegrationProcedureServiceTest.setMockHttpResponseByUrlOrActionName(
'GetContactsHttp', res1);
HttpResponse res2 = new HttpResponse();

res2.setHeader('Content-Type', 'application/json');
res2.setBody('{"ContactEmail":"joe2@vlocity.com"}');
res2.setStatusCode(200);
namespace.IntegrationProcedureServiceTest.setMockHttpResponseByUrlOrActionName(
'callout:MyContactInfo2', res2);

pe',

company 684
System.assertEquals('joe2@vlocity.com',
response.get('Action2Response'));
}
}
Integration Procedure Invocation from REST APIs

You can use either a GET or a POST call to run an Integration Procedure and retrieve the result. The only
difference is that a GET call can't include a JSON request body.
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.
Integration Procedure Invocation Using GET

To get JSON data for an Integration Procedure, issue a GET call. You can include inline values and query
parameters, but you can't pass in JSON data.
Use a URL formatted as follows:
/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"

company 685
}
}
There are two ways to pass parameters to the Integration Procedure in the URL:
• Parameter/value pairs
• Inline values in the URL path
The syntax is as follows:
{inlinevalue1}/{inlinevalue2}/?{Param1}={Value1}
For example, the following URL:
/services/apexrest/vlocity_cmt/v1/integrationprocedure/IP_Rest/Apple/Phones/?
product=iPhoneX
...sends this input to the Integration Procedure:
{
"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:
chainable=true
Integration Procedure Invocation Using POST

To post JSON data to an Integration Procedure, issue a POST call. You can also include inline values,
query parameters, and a JSON request body.
Use a URL formatted as follows:
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.

company 686
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/
POST JSON Data:
{
"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
The syntax is as follows:
{inlinevalue1}/{inlinevalue2}/?{Param1}={Value1}
For example, the following URL:
/services/apexrest/vlocity_cmt/v1/integrationprocedure/IP_Rest/Apple/Phones/?
product=iPhoneX
...sends this input to the Integration Procedure:
{
"options": {
"Path1": "Apple",
"Path2": "Phones",
"product": "iPhoneX",
"isDebug": "true"
}
}
Values passed in the path are added under the options node, with keys named PathN.

company 687
You can also set Integration Procedure options such as chainable or queueableChainable using a
REST API. For example:
chainable=true
Integration Procedure Invocation from Salesforce Flow

To call an Integration Procedure from a Salesforce Flow, create a Salesforce Flow component by defining a
class using the Salesforce Developer Console, as shown in the following example. Note that the class must
have the @InvocableMethod annotation.
global with sharing class IntegrationProcedureInvocable {

@InvocableMethod(label = 'Integration Procedure')
global static List < IntegrationProcedureOutput >
runIntegrationServiceInvocable(List < IntegrationProcedureInput > input) {
System.debug(LoggingLevel.Error, JSON.serialize(input));
IntegrationProcedureOutput result = new IntegrationProcedureOutput();
result.output = JSON.serialize(
IntegrationProcedureService.runIntegrationService(
input[0].procedureAPIName,
new Map < String, Object >
{
'Id' => input[0].input
},
new Map < String, Object > ()));
System.debug(LoggingLevel.Error, JSON.serialize(result));
return new List < IntegrationProcedureOutput >
{
result
};
}
global class IntegrationProcedureInput
{
@InvocableVariable(label = 'Procedure Name') global String procedureAPIName;
@InvocableVariable(label = 'Input') global String input;
}
global class IntegrationProcedureOutput
{
@InvocableVariable(label = 'Output') global String output;
}
}
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.

company 688
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}
Settings for Long-Running Integration Procedures

You can use chainable and queueable chainable settings to avoid hitting Salesforce governor limits when
invoking long-running Integration Procedures. You can also chain on one or more specific long-running
steps.
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.
To mitigate this problem, use settings at both these levels:
• Enable chaining from the OmniScript or parent Integration Procedure action that calls the long-running
• 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.

company 689
Chainable and Queueable Chainable Settings

To configure limits below the Salesforce defaults, edit the Chainable Configuration and Queueable
Chainable Limits settings in the Integration Procedure's Procedure Configuration section. To disable
checking for a limit, leave it blank. If you disable checking for a limit and a step exceeds the Salesforce
limit, the Integration Procedure fails.
Chainable settings are as follows:
• 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 settings are as follows:
• 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.

company 690
How to Call a Chainable or Queueable Chainable Integration Procedure

To enable chaining for an Integration Procedure that is called from an OmniScript, open the Integration
Procedure action that calls the Integration Procedure and check the Chainable checkbox. To enable
chainable steps to start queueable jobs, also check the Queueable checkbox. See Integration Procedure
Action.
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.
The Chain on Step Setting

To enable chaining for a particular long-running step in an Integration Procedure, check its Chain On Step
setting. When the Integration Procedure is called with chaining enabled, and a limit is reached, the step
runs in its own transaction.
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.
Chainable and Queueable Chainable Settings in Preview

To enable the Chainable and/or Queueable Chainable settings when testing an Integration Procedure using
the Preview tab, expand the Options pane and set one or more of these options:
• chainable: If true, enables the Chainable settings for testing.

• queueableChainable: If true, enables the Queueable Chainable settings for testing.
• useQueueableApexRemoting: If true, limits the amount of time the Apex CPU runs by starting a
queueable job with no chaining.
The Action Message Property in the Calling OmniScript

To view the progress of a chained Integration Procedure when debugging the OminScript that calls it, set
the Action Message property of the chained steps in the Integration Procedure. The text you enter in the
Action Message field can be viewed in the Debug pane of the OmniScript Designer, as shown in the
following figure.

company 691
JavaScript Code to Call Chainable Integration Procedures

OmniScripts and parent Integration Procedures that call chainable Integration Procedures handle the
transactions automatically. However, if you call a chainable Integration Procedure from a Lightning Web
Component, you need to include code that handles the intermediate responses.
To see what the intermediate responses look like, see Invoke a Chainable Integration Procedure with REST
Calls.
Here is a way to structure JavaScript code to handle these responses:
function runChainable(options) {
options.isDebug = vm.isDebug;
remoteActions.testIntegrationProcedure(ipId, inputData,
options).then(function(response) {
responseHandler(response);

company 692
});
}
function responseHandler(response) {
if (typeof(response) === 'string') {
response = JSON.parse(response);
}
if (response &&
response.vlcIPData &&
response.vlcStatus === 'InProgress') {
runChainable(response);
} else {
// handle IP response
}
}
Invoke a Chainable Integration Procedure with REST Calls

A chainable Integration Procedure is split into multiple transactions to avoid hitting Salesforce governor
limits. Using a REST API is the easiest way to see the partial responses each transaction returns before the
Integration Procedure completes.
Before You Begin

1. To ensure you can use curl commands on your computer, in a terminal window, type curl -help. If curl is available, you see a
long list of curl options.
2. Determine the namespace that Integration Procedures in your org use, either omnistudio, vlocity_ins, vlocity_cmt, or
vlocity_ps.
3. Create this Integration Procedure example or import its DataPack: Create a Try-Catch Block Example with a Formula.
4. Get the session ID for your current login to your org. See Set Up Authorization in Salesforce's REST API Developer Guide.
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:
curl -X POST -H 'Authorization: Bearer session_id' -H 'Content-Type:

application/json' -H 'chainable:true' --data-raw '{"Name":"Name"}' https://
ap1.salesforce.com/services/apexrest/namespace/v1/integrationprocedure/
Type_SubType

company 693
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:
curl -X POST -H 'Authorization: Bearer 00Dnn000000nnnn!ARUAQLt ...

QqodNY3' -H 'Content-Type: application/json' -H 'chainable:true' --data-
raw '{"Name":"Jones"}' https://ap1.salesforce.com/services/apexrest/
vlocity_ins/v1/integrationprocedure/Documentation_IPTryCatchF2
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.
7. Examine the response. It looks like this:
{
"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:
curl -X POST -H 'Authorization: Bearer 00Dnn000000nnnn!ARUAQLt ...

QqodNY3' -H 'Content-Type: application/json' -H 'chainable:true' --data-
raw '{"Name":"Jones"}' -H 'vlcIPData:dc3e1986-2f7c-0871-e968-28eb63e11820'
https://ap1.salesforce.com/services/apexrest/vlocity_ins/v1/
integrationprocedure/Documentation_IPTryCatchF2
9. Examine the response. If it contains another vlcIPData value, repeat the previous step with the new
vlcIPData value. Keep repeating with each new vlcIPData value until the response looks like this:
{
"response": {},
"Name": "Jones",
"options": {
"Accept": "*/*",
"X-B3-SpanId": "ee09609f22d890e1",

company 694
"CipherSuite": "ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 256-bits",

"User-Agent": "curl/7.64.1",
"X-B3-Sampled": "0",
"Host": "ap1.salesforce.com",
"X-B3-TraceId": "ee09609f22d890e1",
"chainable": "true",
"X-Salesforce-SIP": "42.42.42.42",
"Content-Type": "application/json"
},
"DataRaptorExtractAction1": [
{
"ContactName": "John Jones"
},
{
"ContactName": "June Jones"
}
],
"TryCatchBlock1": null
}
This response is an example of what you get when the Integration Procedure is complete.
Continuation in Long-Running Calls

To support long-running calls, Salesforce provides Apex Continuations. If your OmniScript calls a long-
running Integration Procedure or Apex class, you can enable continuation.
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.
Make a Long-Running Remote Call Using VlocityContinuationIntegration

To support long-running remote calls, Vlocity supports the use of the Salesforce Continuation object. The
VlocityOpenInterface2 interface and VlocityContinuationIntegration class support normal
Remote Calls and Remote Calls that use the Continuation Object. For the new Apex classes, don’t use
VlocityOpenInterface.
For more information on the SFDC Continuation object, see the following Salesforce documentation:

company 695
• Process for Using Asynchronous Callouts

• Apex Continuations: Asynchronous Callouts from Visualforce Pages
To make a remote call using the Salesforce Continuation object and extending the
VlocityContinuationIntegration class:
1. Create an Apex class that extends the VlocityContinuationIntegration class.

This class implements VlocityOpenInterface2.
2. Implement the callback method in the invokeMethod. For more information, refer to the sample class
at the end of this topic.
3. For the method that returns the Continuation Object, call the method
VlocitySetAsyncCallbackState before the return.
con.continuationMethod = 'customcallback'; // implemented in invokeMethod

VlocitySetAsyncCallbackState(con, con.addHttpRequest(req), options);
4. For the last callback method in the chain that returns the response back to OmniScript, use the
following code to get the state of the Continuation Object and system labels.
Object state = inputMap.get('vlcContinuationCallbackState');

Object labels = inputMap.get('vlcContinuationCallbackLabels');
5. The 'state' Object returned from inputMap.get('vlcContinuationCallbackState') must be a
Map<String, Object> with contents that can’t be directly cast using
(CustomApexWrapperClass)inputMap.get('vlcContinuationCallbackState'). Instead,
the returned object must be serialized to JSON and then deserialized and cast to its correct class. For
example:
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.
Example 15. Sample Class VlocityContinuationIntegrationTest.cls

// Sample Apex class for making Remote Call in OmniScript
// (1) Create a custom Apex class which extends
VlocityContinuationIntegration, for a Vlocity managed package,
// need to include the Namespace prefix - NS.VlocityContinuationIntegration
// (2) implement invokeMethod, return type is Object (a) in the Continuation
Object case, return Continuation Object
// (b) in the normal case, you can return Boolean
global with sharing class VlocityContinuationIntegrationTest extends
VlocityContinuationIntegration
{
global override Object invokeMethod(String methodName, Map<String, Object>
inputMap, Map<String, Object> outMap, Map<String, Object> options)

company 696
{
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);

company 697
//
// 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
// 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
HttpRequest req = new 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

company 698

return con;
}
// Last callback method
// This does NOT return Continuation Object
// This will return the response back to OmniScript, therefore need to set
outMap
private Object customcallback(Map<String, Object> inputMap, Map<String,
Object> outMap, Map<String, Object> options)
{
// This is how you access the state and labels passed by the Continuation
Object
// EXAMPLE
HttpResponse response = Continuation.getResponse((String)state);
Integer statusCode = response.getStatusCode();
if (statusCode >= 2000)
{
// System.log ...
}
// This goes back to OmniScript
outMap.put('continuousResp', response.getBody());
return null;
}
}
Make a Long-Running Remote Call Using OmniStudio.OmniContinuation

To support long-running remote calls, Vlocity supports the use of the Salesforce Continuation object. Calling
the OmniStudio.OmniContinuation constructor method returns an OmniContinuation object, which
extends the Continuation object. If the class that calls this constructor method implements the Callable
interface, you can call the class using the Remote Class and Remote Method properties of an OmniScript
For details about the SFDC Continuation object and the Callable interface, see the following Salesforce
documentation:
• Process for Using Asynchronous Callouts

• Apex Continuations: Asynchronous Callouts from Visualforce Pages
• Callable Interface
To make a remote call using the OmniContinuation object and implementing the Callable interface:
1. Create an Apex class that implements the Callable interface.

2. Implement the callback method in the invokeMethod. See the private Object invokeMethod
code in the example.

company 699
3. For the method that returns the OmniContinuation Object, call the OmniStudio.OmniContinuation
constructor.
OmniStudio.OmniContinuation con = new OmniStudio.OmniContinuation(120);

con.ContinuationMethod = 'customCallback';
4. For the last callback method in the chain that returns the response back to OmniScript, use the
following code to get the state of the OmniContinuation Object and system labels.

5. Use the OmniStudio.OmniContinuation.getResponse method to retrieve the response.
Example 16. Sample Class OmniContinuationTest.cls

global with sharing class RemoteActionCallableOmniContinuation implements
Callable
{
// Dispatch actual methods
public Object call(String action, Map<String, Object> args) {
Map<String, Object> input = (Map<String, Object>)args.get('input');

Map<String, Object> output = (Map<String, Object>)args.get('output');
Map<String, Object> options = (Map<String, Object>)args.get('options');
return invokeMethod(action, input, output, options);

}
private Object invokeMethod(String methodName, Map<String, Object>

{
try
{
// the custom methods can have any customized signature, but
// PLEASE MAKE USRE YOU ALWAYS PASS IN options
if(methodName.equals('populateElements'))
{
// this returns Continuation Object
return populateElements(5, inputMap, outMap, options);
}
else if(methodName.equals('continuation2'))
{
return continuation2(8, inputMap, options);
}
else if(methodName.equals('customCallback'))
{
customCallback(inputMap, outMap, options);

company 700
}
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>
{
// THIS IS A SAMPLE TO CALL HEROKU NODE SERVICE
//

con.ContinuationMethod = 'continuation2';
// Create the state

Map<string, Object> stateAsMap = new Map<String, Object>();
String label = con.addHttpRequest(req);
stateAsMap.put('label', label);
// Store the state

con.state = stateAsMap;
options.put('continuationState', label);
options.put('continuationCallback', 'continuation2');

company 701

return con;
}
// callback for the first Continuation

// this again returns Continuation Object
// This is to show you how to serialize multiple long running remote calls
private Object continuation2(Integer count, Map<String, Object> inputMap,
Map<String, Object> options)
{
// Create a OmniContinuationTest for the HTTPRequest

con.ContinuationMethod = 'customCallback';
// Create the state

Map<string, Object> stateAsMap = new Map<String, Object>();
String label = con.addHttpRequest(req);
stateAsMap.put('label', label);
stateAsMap.put('populateElements-label',
inputMap.get('vlcContinuationCallbackState'));
// Save the state

con.state = stateAsMap;
options.put('continuationState', label);
options.put('continuationCallback', 'customCallback');

return con;
}
// Last callback method

// This does NOT return Continuation Object
// This will return the response back to OmniScript, therefore need to set
outMap
private Object customCallback(Map<String, Object> inputMap, Map<String,
Object> outMap, Map<String, Object> options)
{
// This is how you access the state and labels passed by the
Continuation Object

company 702
Map<String, Object> stateAsMap = (Map<String, Object>) state;
// EXAMPLE
HttpResponse response =
OmniStudio.OmniContinuation.getResponse((String)stateAsMap.get('label'));
Integer statusCode = response.getStatusCode();
if (statusCode >= 2000)

{
// System.log ...
}
// This goes back to OmniScript

outMap.put('responseFromCallableOmniContinuation', 'Response using
OmniContinuationWrapperPtc (Using Callable): ' + response.getBody());
return null;
}
}
Security for DataRaptors and Integration Procedures

You can control access to DataRaptors and Integration Procedures using settings that reference Sharing
Settings and Sharing Sets or Profiles and Permission Sets.
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

company 703
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
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.
Configure DataRaptor and Integration Procedure Security Settings

You can change settings for DataRaptor and Integration Procedure security in Setup.
For a list of settings, see DataRaptor and Integration Procedure Security Settings.
1. Go to Setup.
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.
DataRaptor and Integration Procedure Security Settings

These settings affect DataRaptor and Integration Procedure security.
To configure these settings, see Configure DataRaptor and Integration Procedure Security Settings.

company 704
Setting Description Data Default

Type Value
DefaultRequiredPermission Specifies the Custom Permission a user must have to run String (none)
The Required Permission setting, which you can optionally

specify when creating a DataRaptor or Integration Procedure,
overrides this setting.
If this setting is absent or blank, all users can run any

DataRaptors or Integration Procedures that don't have Required
Permission values.
Custom Permissions for users are defined in Salesforce Profiles

or Permission Sets.
For this setting to work, the

VlocityRequiredPermissionCheck class must be
implemented. See Implement the
VlocityRequiredPermissionCheck Class.
CheckCachedMetadataRecordSecurity By default, cached data is not secured when you use Salesforce True/ False
Sharing Settings or Sharing Sets to secure access. If True, this False
setting performs a record-level security check for cached data.
This lessens the performance benefit of metadata caching
slightly. This setting isn't needed if you use Custom Permissions
to secure access.
Implement the VlocityRequiredPermissionCheck Class

For the DefaultRequiredPermission setting to work, you must implement the
VlocityRequiredPermissionCheck class manually because Salesforce handles classes in managed
and unmanaged packages differently. This class doesn't work properly if it's included in the Vlocity
managed package.
For DefaultRequiredPermission details, see DataRaptor and Integration Procedure Security Settings.

3. Click New.

company 705

{
{
{
return checkPermission((String)args.get('requiredPermission'));
}
return false;
}

{
List<String> customPermissionsName = requiredPermission.split(',');
{
{
break;
}
}
}
}
5. Click Save.

company 706
Calculation Procedures and Matrices
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.
Figure 13. Calculation Procedures and Matrices
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:
• An individual health insurance plan via a website to a customer

• A term life quote via an agent
• A volume discount on an order
• A permit or application fee
• A person applying for benefits or services
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.

company 707
Calculation Example for Life Insurance Quote

To provide an accurate quote, an agent must know a person’s age, home ZIP code, and whether they
smoke. First, a form prompts for the needed data, from an agent or web self-service. When the form is
submitted, a calculation procedure defined for that form runs. The first procedure step is a Matrix Lookup,
which looks across the matrix input fields—Smoker, ZIP, and Age—to find the corresponding output (Rate).
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.

company 708
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.

company 709
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.
But modifying calculation matrices in a production environment can have severe

consequences on the rates you get for insurance products. We recommend that you limit
the number of people who can modify production calculation matrices to only essential
administrators.
Standard Calculation Matrices

All calculation matrices have the characteristics that standard calculation matrices have. Other types have
characteristics that standard calculation matrices lack. All calculation matrices have input columns, output
columns, and versions.
A calculation matrix is a Vlocity rating table that is structured and stored as follows:
• One input column or a set of input columns

• Input column header names must match inputs, such as attributes and remote options
• Each input or set of inputs must be unique
• Vlocity stores all input column header names and all input data in one JSON
• One output column or a set of output columns
• Outputs and sets of outputs don't need to be unique
• Vlocity stores all output column header names and all output data in one JSON

company 710
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

You can create groups of calculation matrices, and subgroups within each group.
Grouped calculation matrices have several benefits:
• 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.

company 711
• 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.
Example 17. Property and Casualty Sample Use Case

An auto insurance carrier has different insurance rates for different jurisdictions (such as states). The
carrier needs to manage each jurisdiction separately, but they don't want to have to create a separate
calculation for each jurisdiction (because all the calculations are the same).
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.
Example 18. Group Health Sample Use Case

Each provider in a health insurance carrier's network has a different fee schedule, and these fee schedules
must be updated throughout the year as providers change or renew their contracts with the carrier.
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.
Row-Versioned Calculation Matrices

If you're wrangling large calculation matrices that can't be sectioned cleanly into groups and subgroups, you
can create calculation matrices that are versioned by row.
For example, you've got a matrix that creates a rating factor per ZIP (postal) code, which includes all ZIP
codes in the United States. You want to be able to update ZIP codes individually or in small groups. This
situation calls for a row-versioned calculation matrix.
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.

company 712
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.
Third Version and Beyond

You upload version 3 the same as you did version 2, and give it a different Start Date / Time than version 1
or version 2. Vlocity gives all the new and changed rows this Start Date / Time.
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.

company 713
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.
Ways to Create a Standard Calculation Matrix

A standard calculation matrix isn't part of a group, and doesn't have row versioning. You can create a
standard calculation matrix in three different ways.
• Upload a CSV file

To save time and reduce errors when configuring complex matrices with a lot of data, create a CSV file
containing the data and upload it to the matrix.
• Manually create the matrix in Vlocity
For a simple matrix with a small amount of data, enter the data manually.
• Create a new version of an existing matrix (recommended when possible)
Create a new version of an existing matrix, and change its data manually or by uploading a CSV file
containing revised data.
CAUTION
Once you've chosen Standard as the record type of a calculation matrix, you can't change
it. Choose wisely.
Prepare a CSV File to Upload to a Calculation Matrix

You must take specific steps to configure CSV files for uploading to populate a calculation matrix.
IMPORTANT
Starting in the CME Summer '18 release, the following limits are supported:
• Input and output rows: 12,752 total characters (max)

• Columns: Approximately 500 (max) depending on amount of data in columns.
• Rows displayed: 2000 (max)

company 714
Before you start the upload, follow the guidelines below to make sure that your CSV file is formatted for use
as a calculation matrix.
1. Add a header name to each column.

Make your headers short and easy to read and understand. Column headers get imported with the
CSV data, which means you don't have to rename them all in Vlocity if they're well named in the CSV
file.
• For input columns, give each column a name that you'll use as an input variable.
This makes it possible for Vlocity to correctly pass in input variables when a matrix lookup calls a
calculation matrix.
• Whenever possible, create consistent column names for input columns.
This makes it possible for an input JSON to provide one input variable that can be used by multiple
matrix lookups in a calculation procedure.
For example, for two CSV files you plan to use as matrices in a single calculation procedure, name
the input column for liability limit liabilityLimit in both CSV files.
• For output columns, enter unique column names that you will use as output variables in calculation
procedures.
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:
input1 input2 output1

1 a 0.1
1 b 0.2
1 c 0.3
20 a 0.4
20 b 0.5

company 715
input1 input2 output1

20 c 0.6
300 a 0.7
300 b 0.8
300 c 0.9
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:
Upload a CSV File to Create a Calculation Matrix

You can upload a CSV file to create a new calculation matrix. You can also upload a CSV file to an existing
calculation matrix, such as a new version of an existing matrix, to update and add to the headers and data.
For details, see Prepare a CSV File to Upload to a Calculation Matrix.
To create a calculation matrix by uploading a CSV file:

company 716
1. On the Vlocity Calculation Matrices page, click New.

2. On the New Vlocity Calculation Matrices window, choose Standard.
3. Enter a Calculation Matrix Name.
Choose a simple name for your calculation matrix. Vlocity adds the calculation matrix name to column
header names and uses the combination in calculation procedures.
Leave the rest of the fields on this window blank.
4. (Optional) If you plan to use a wildcard column, enter the following:
• Wildcard Column: The name of the column that can have a wildcard entered as a user value.
• Wildcard Value: The value a user can enter that's the wildcard.
Be sure to add the Wildcard Value to its column in the CSV file.
5. Click Save.
6. To open the detail page, click the version that you just created.
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.
7. In the Table section, click Upload CSV.

8. When the Upload CSV window opens, click Choose File.
9. Select the file, click Open, then click Upload.
10. Set the Header Type of each column. The Header Type defines the column mapping.
• Input: The column gets data for the calculation.
• Output: The column returns data from the calculation.
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.

company 717
To see columns that have errors, click Show Errors Only. (The button toggles to Show All Rows after
you click it.)
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.
Create a Calculation Matrix Manually

If a calculation matrix has only a few rows of data, it might be easier to create it manually.
1. On the Vlocity Calculation Matrices list page, click New.

2. On the New Vlocity Calculation Matrices window, choose Standard.
3. In the Calculation Matrix Name box, enter the name for the calculation matrix.
Choose a simple name for your calculation matrix. Vlocity adds the calculation matrix name to column
header names and uses the combination in calculation procedures.
Leave the rest of the fields on this window blank.
5. Click Save.
6. Click the version of the matrix that you just created.
7. In the Table section, click Add Header.
8. Enter the following information:
• Name is the column header name.
• Header Type defines the column mapping. Select Input if the column gets data for the calculation.
Select Output if the column returns data from the calculation.
• Data Type specifies the type of data stored in the column:
• Text
• Number
• Currency
• Percent
• Boolean
• Number Range

company 718
• 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.
• Matrix Display Order defines the column number (sequence).

9. Repeat steps 5 and 6 to define the rest of the column headers.
11. Click Edit Data to enter values into the columns.
12. Enter a value into each data field in each column.
NOTE
You must enter data in every data field. You cannot enable a calculation matrix that
contains empty data fields.
13. When you're done editing, click Save Data.

Approval.
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.
Create a New Version of an Existing Calculation Matrix

It's a lot quicker to clone an existing version of a calculation matrix than it is to create a new matrix from
scratch. Cloning copies all the headers and data.
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

company 719
• The same start date as the previous version

• The same end date (or lack of end date) as the previous version
• All the same data as the previous version
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.
Approval.
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.

company 720
Workflow for Creating a Grouped Calculation Matrix

You can create a calculation matrix that's part of a group of matrices. You create grouped calculation
matrices so that a calculation procedure (or another calling process) can search all the matrices using only
one SOQL query. This speeds up Vlocity processing and frees up SOQL queries for other purposes.
Versions in a grouped matrix can have different effective dates.
To create a grouped calculation 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.
Create a Grouped Calculation Matrix

Created grouped calculation matrices can be a bit tricky. Hang in there!

2. On the New Vlocity Calculation Matrices window, choose Group.
5. Enter a Group Key. (Required)
You'll only do this once per group.
6. Enter a Sub Group Key. (Optional)
You'll do this only once per subgroup.
7. Click Save.
8. Click the name of the Matrix Version you just created.
9. Enter a Group Value.
10. If you're using subgroups, enter a Sub Group Value.
11. (Optional) You can add and change the following:
• Name
You can change the name of this matrix version to something more descriptive.
• Priority
• Version Number
• Start Date/Time
• End Date/Time

company 721
After you've made your changes, click Save.

12. Still on the matrix version page, click Upload CVS. See Upload a CSV File to Create a Calculation
Matrix.
If you're creating this group of matrices by hand in Vlocity, click Add Headers.
Populate the Rest of the Matrices in the Group

After you've created the first matrix in a group, you can create as many other group members as you need.
TIP
We call matrix group members Versions.
To add a new member (version) matrix:
1. On the Calculation Matrix group page, click the Related tab.

2. Next to Vlocity Calculation Matrix Versions, click New.
3. Enter a Name for this matrix.
5. Change the Version Number to a number different from all the other Version Numbers of the existing
matrices in this group.
6. Add any of the following optional information:
• Start Date / Time
Defaults to the date and time you create this member matrix.
• End Date / Time
Defaults to no value.
• Group Key Value
Enter a value for the Group Key you entered when you created this group.
• Sub Group Key Value
Enter a value for the Sub Group Key if you're using Sub Groups.
• Priority
This one's important if you plan to eventually have more than one version of each member matrix in
this group. For example, if you have two member matrices that have overlapping Start Dates and
End Dates, set a Priority so Vlocity knows which member matrix to use when called.
7. Click Save.

company 722
Workflow for Creating a Row Versioned Calculation Matrix

Creating the first version of a row-versioned calculation matrix follows most of the same steps as creating a
standard calculation matrix. Then, as you need to make changes to these matrices, you can upload new
individual rows. This creates new versions of the replaced rows with new start dates and end dates.
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.
To create and manage a row-versioned calculation matrix:
1. Create a Row Versioned Calculation Matrix.

2. Upload New Versioned Rows.
3. Delete Versioned Rows.
4. Delete an Entire Matrix Version.
Create a Row Versioned Calculation Matrix

The first step is to create the row-versioned matrix and choose how to add data.

2. On the New Vlocity Calculation Matrices window, choose Row-Versioned.
4. (Optional) If you plan to use a wildcard column (available in Winter '20 and later releases), enter the
following:
5. Click Save.
6. Click the name of the Matrix Version you just created.
7. Still on the matrix version page, choose one of these options:
• If you're uploading data from a .csv file, click Upload CVS. See Upload a CSV File to Create a
Calculation Matrix.
• If you're creating this matrix by hand, click Add Headers.

company 723
IMPORTANT
Once you've enabled your calculation matrix version, the headers are locked. You won't be
able to change them again.
Upload New Versioned Rows

You must create a new version of a row-versioned calculation matrix before you upload new data from
a .csv file.
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.

company 724
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.
Delete Versioned Rows

You can delete individual rows from a row-versioned calculation matrix.
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.
To delete a single row from a version of a calculation matrix:
1. Open the calculation matrix.

2. Deselect the Enabled checkbox if this matrix is enabled.
3. On the Related tab, open the version of the calculation matrix you want to delete a row from.
4. In the header, click the pencil beside Enable.
5. Deselect Enable, then click Save.
6. Find the row you want to delete.
7. Click the trash can icon at the right side of the row to be deleted.
8. On the message that appears, click OK.
9. Click Save Data.
Delete an Entire Matrix Version

You can delete all the data from a specific version of a row-versioned calculation matrix.

company 725
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.
1. Open the calculation matrix.

2. On the Related tab, open the version of the calculation matrix you want to delete.
3. Click Delete Data.
4. On the message that appears, click OK.
5. Click Save Data.
Wildcards in Calculation Matrices

Starting in Winter '20, you can make it possible for calculation procedures and other Vlocity features that
call calculation matrices to use a wildcard in place of a value for one column.
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:
• Wildcard Column: state

• Wildcard Value: ALL
Wildcard columns work in standard, grouped, and row-versioned calculation matrices.
Search in a Calculation Matrix

You can search for specific values in a calculation matrix that has many rows.
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.
3. Click the Search button above the columns.

Vlocity displays the matrix rows containing the specified value in the selected column.

company 726
4. If your search returns no results, note the following:

• By default, Vlocity returns only the first 2000 results of your search.
• For multi-column searches, Vlocity searches one column at a time, in order.
You can enter search parameters into multiple columns and click Search. Vlocity searches the first
column, then uses the second parameter to search the results from the first column.
5. To improve search results:
• Set the General Setting CalculationMatrixRowPrettify = true (if it's set to false).
a. To set this setting, go to Setup > Custom Settings > General Settings > Manage.
b. Either add the setting manually, or if it exists already, edit it.
• For calculation matrices created before the Summer '19 release, click the Update JSON button
before you search.
Download Calculation Matrix Data to a CSV File

You can download all or part of the data in a calculation matrix.
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.
To download part of a matrix:
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.
Edit and Delete Matrix Data

You can edit and delete the data in a calculation matrix if you haven't enabled it yet.
1. Click Edit Data.

2. Change data in any field.
3. To delete a whole row, click the trashcan icon at the far right of the row that you want to delete.
4. To delete all the data from a matrix but leave the headers in place, click Delete Data, then click OK to
confirm.
5. To delete all headers and data, click Delete All, then click OK to confirm.
6. Click Save Data.
Edit Matrix Headers

You can change the names and data types of the column headers in a calculation matrix.
1. Click Edit Headers.

2. Change names and fields in any header.
• Name is the column header name.
• Header Type defines the column mapping. Select Input if the column gets data for the calculation.
Select Output if the column returns data from the calculation.

company 727
NOTE
You can't use a split-limit attribute as an Output in a calculation matrix.
• Data Type specifies the type of data stored in the column:

• Text
• Number
• Currency
• Percent
• Boolean
• Number Range
• 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.
If the data becomes corrupted, reimport the CSV file to overwrite the corrupted data.
• Matrix Display Order defines the column number (sequence).

3. To delete a column, including its data, from the matrix, click Remove Column at the bottom of the
column header.
4. To add a header, click Add Header.
Fill out the header as described in step 2.
5. Click Save Data.
Disable a Calculation Matrix

To disable a calculation matrix, edit its End Date/Time.
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.
Ranges in Calculation Matrices

A range takes a number or text value and assigns it to groups that you've defined. You can use numeric
ranges and alphabet ranges in Vlocity Calculation Matrices. For example, if age is a component of your
pricing, you can use a numeric range to map the applicant's age to the correct age group.
Age Today Assigned to Age Group

17 or younger Age Group 0
18 to 24 Age Group 1

company 728
Age Today Assigned to Age Group

25 to 29 Age Group 2
30 to ... ...
Numeric Ranges in Calculation Matrices

When you configure numeric ranges for a matrix, values below the lowest level that you configure are
treated as the lowest value, and values above the highest value that you configure are treated as the
highest value configured for the matrix.
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:

company 729
See Also
• ???
• ???
Collating by Alphabetic Ranges (Example)

Suppose you want to assign Contacts into one of three buckets by last name such that:
• I = Contacts whose last names begin with A-I

• J = Contacts whose last names begin with J-R
• S = Contacts whose last names begin with S-Z
Set up the matrix as follows:

company 730
Added Dimensions in the Matrix

You might want to look up additional dimensions in the Matrix. For example, to look up Age Range Band by
gender, create two rows for each age: one for Male applicants, the other for Female applicants. Additional
dimensions require additional rows.
Calculation Procedures Overview

A Calculation Procedure is a series of calculations performed using matrix lookups and user-defined
variables and constants. A calculation procedure can call Apex classes for pre- and post-calculation custom
logic. Calculation procedures are part of pricing rules.
There are two types of calculation procedures:
• Class-based: Pricing logic is written in an Apex class.

• Declarative: Pricing logic is implemented using matrix lookups, variables, constants, and basic math
operations.

company 731
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.
A calculation procedure can use two types of steps.
• 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.
Use Cases for Calculation Procedures

Here are ways to set up the possible use cases for calculation procedures that use or don't use attribute-
based pricing or volume-based pricing.
Case 1 — No attribute-based pricing or volume-based pricing across multiple line items:
• Define the input DataRaptor filter on the OrderItem.

• Use a DataRaptor Extract for input and a DataRaptor Load for output.
Case 2 — Attribute-based pricing, but no volume-based pricing across multiple line items:
• You cannot specify the DataRaptor input in the Calculation Procedure.

• A preprocessor is required to format the input data and attribute information for use in the Calculation
Matrix.
• In the unmanaged package, an Apex class named CalcProcPreProcessor formats the DataRaptor
input as required to support attributes in the Calculation Matrix.
• A custom setting—CPPreProcObjectDRBundle—specifies the name of the input DataRaptor that the
preprocessor uses.
• The object must be Opportunity, Order, or Quote.
Case 3 — Attribute-based pricing and volume-based pricing across 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.

company 732
• Two Apex classes—CalcProcPreProcessor and CalcProcPostProcessor—are provided in the

unmanaged package.
• Custom settings define the name of the input DataRaptor that the preprocessor uses and the output
DataRaptor that the postprocessor uses.
• CPPreProcObjectDRBundle
• CPPostProcObjectDRBundle
• The object must be Opportunity, Order, or Quote.
Use Apex to Define Pricing Logic

To use Apex to define pricing logic, create a class-based Calculation Procedure. The Calculation Procedure
name and action class name must be the same as the name of the Apex class. (To define pricing logic
without using an Apex class, create a declarative Calculation Procedure.)
To create a Calculation Procedure:
1. Go to the Vlocity Calculation Procedures tab.

2. Click New.
3. From the Record Type of new record picklist, select Class Based.
4. Click Continue.
5. In the Calculation Procedure Name field, enter a name for the procedure.
6. In the Description box, enter a brief description.
7. Click Save.
Clone a Calculation Procedure

The Clone action button isn't present for calculation procedures by default, but you can add it. When you
clone a calculation procedure, you're cloning all of its versions, steps, variables, and constants.
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.
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.

company 733
10. Choose the layout.

11. In the top pane, choose Buttons, then drag the Clone button onto the page layout.
Recommended location: The Vlocity Calculation Procedure Detail > Custom Buttons area.
12. Click Save.
13. After you have added the button, you can clone a calculation procedure:
a. Go to the Vlocity Calculation Procedures list page and click the calculation procedure that you
want to clone.
b. Click the Clone button.
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
Variables and Constants in Calculation Procedures

You must create variables, constants, and matrices before you can use them in a Calculation Procedure.
After you create them, they will be available to use in Calculation Procedures.
The following are a few guidelines for using variables in Calculation Procedures:
• Create a variable for every value in the calculation.

• A variable to the right of the equals sign (=) means that the equation output will be assigned as the
variable value.
For example, x + y = variable means the value of variable is now the sum of x + y.
• A variable to the left of the equals sign (=) means that the current value of the variable is part of the
calculation.
For example, x + variable = y means the value of y is now the sum of x plus the current value of
the variable.
• A variable keeps the value assigned to it until another operation changes its value. For example:
x = 2
y = 3
variable = 0
variable = 0
Step 1: x + y = variable // 2 + 3 = 5. variable = 5

Step 2: y + y = variable // 3 + 3 = 6. variable = 6
Step 3: variable + y = variable // 6 + 3 = 9. variable is now 9.
Step 4: variable + variable = variable // 9 + 9 = 18. variable is now 18.

company 734
See Also
• Add Variables and Constants
Conditional Steps For Calculation Procedures

For each step in the Calculation Procedure, you can define a condition that must be met in order for the
step to be executed. The step is only executed when the condition is met.
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.
Functions for Calculation Procedures

The following functions are supported in calculation procedures.
Function Description Example

ADDDAY Adds the specified number of days to the ADDDAY("1999-01-01",100) returns "1999-04-11 00:00:00"
specified date and returns the resulting date.
ADDMONTH Adds the specified number of months to the ADDMONTH("1999-01-01",100) returns "2007-05-01
specified date and returns the resulting date. 00:00:00"
ADDYEAR Adds the specified number of years to the ADDYEAR("1999-01-01",100) returns "2099-01-01 00:00:00"
specified date and returns the resulting date.
AGE Returns the age for the specified birthdate. AGE(Account:Contact:Birthdate)
AGEON Given a birth date, returns the age on a AGEON(Account:Contact:Birthdate,TODAY()).
specified date
DATEDIFF Returns the number of days between two DATEDIFF("1900-01-01","2000-01-01") returns 36524
specified dates. If the first date is greater than
the second date, the value is returned as a DATEDIFF("2000-01-01","1999-01-01") returns -36524
negative number.
DATEDIFF(Account:Cases:CreatedDate,TODAY()) returns the
number of days a case has been open
EOM For a specified date, returns the date of the last EOM(Account:CaseReturns the month of the specified date as
day of the month. an integer. s:CreatedDate)
MONTH For a specified date, returns the month as an MONTH("1999-01-11") returns 1
integer (1-12).
ROUND Rounds the specified number or expression. By ROUND(3.1415 * 3) = 9.42
default, results are rounded to two decimal
places, but you can specify the desired number ROUND(3.1415 * 3, 0) = 9
of decimal places for the result.
You can also use the UP, DOWN, HALF_UP,

HALF_DOWN, and HALF_EVEN parameters to
refine the rounding results.
FLOOR Returns a number rounded down to the nearest FLOOR(2.5) returns 2, which is 2.5 rounded down to the
integer, towards zero if negative. nearest integer.
UP Use with ROUND to specify that the rounding ROUND(2.572, 2, UP) returns 2.58
result is rounded up (away from zero).
DOWN Use with ROUND to specify that the rounding ROUND(2.572, 2, DOWN) returns 2.57
result is rounded down (towards zero).

company 735

HALF_UP Use with ROUND to specify that the rounding ROUND(2.575, 2, HALF_UP) returns 2.58
result is rounded towards the nearest neighbor
(up or down) unless the neighbors are
equidistant, in which case it rounds up.
HALF_DOWN Use with ROUND to specify that the rounding ROUND(2.575, 2, HALF_DOWN) returns 2.57
result is rounded rounded towards the nearest
neighbor (up or down) unless the neighbors are
equidistant, in which case it rounds down.
HALF_EVEN Use with ROUND to specify that the rounding ROUND(2.57, 1, HALF_EVEN) returns 2.6, which is rounded
result is rounded rounded towards the nearest up to the nearest even one-decimal place.
neighbor (up or down) unless the neighbors are
equidistant, in which case it rounds to the
nearest even neighbor.
Behaves as for ROUND HALF_UP if the digit to

the left of the discarded fraction is odd; behaves
as for ROUND HALF_DOWN if it is even.
CEILING Rounds a number up to the nearest integer, CEILING(2.5) returns 3, which is 2.5 rounded up to the nearest
away from zero if negative. integer.
SQRT Calculates the square root of a value. SQRT(12 * 3) returns 6
TODAY Returns today's date
YEAR Returns the year of the specified date as an YEAR("1999-01-11") returns 1999
integer.
For looping procedures: PREVIOUS
For aggregation steps, the following functions are supported.

AVG Average of list of values. AVG(1,2,3,4,5,6,7,8,9,10) returns 5.5
MAX Maximum value in a list of values. MAX(1,2,3,4,5,6,7,8,9,10) returns 10
MIN Minimum value in a list of values. MIN(1,2,3,4,5,6,7,8,9,10) returns 1
SUM Returns the sum of a list of values SUM(1,2,3,4,5,6,7,8,9,10) returns 55
Declarative Calculation Procedures

Declarative calculation procedures are a key component of the ratings engine. Along with calculation
matrices, calculation procedures are the key components of any or ratings engine. Calculation procedures
take an input JSON and run through a series of matrix lookups (calling values from calculation matrices)
and calculations to calculate ratings for policy products.

company 736
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:
• Grouped calculation matrices

• Row-versioned calculation matrices
What's in a Calculation Procedure

A well-formed calculation procedure contains the following elements:
• 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.

company 737
How Calculation Procedures Work in Context
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.
Here's an example of a single set of input values, as passed in by a JSON:
{
"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": [
{

company 738
"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.
How Aggregation Works in Calculation Procedures

When you add aggregation steps to your calculation procedure, the calculation procedure puts together the
results of each run through itself, performs operations on them, then outputs the results of the operations.
Here's what that looks like:
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

company 739
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:

company 740
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.
Preprocessor and Postprocessor Classes

These are Apex classes that you can use if you have to massage your input data or output data before and
after it's processed by a calculation procedure. See Preprocessor Class Example.
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.)
Workflow for Creating a Calculation Procedure

To create a calculation procedure, you set up the overall configuration, add variables and constants, add
steps, and test.
1. Set Up a Calculation Procedure.

company 741
2. Add Variables and Constants.

3. Add Calculation Steps.
4. Add Matrix Lookups.
5. Add Aggregation Steps.
6. Test a Calculation Procedure.
Set Up a Calculation Procedure

Before you can create calculation procedure steps, you must configure the calculation procedure as a
whole.
1. On the Vlocity Calculation Procedures list page, click New.

2. Enter a Calculation Procedure Name, then click Save.
3. In the Vlocity Calculation Procedure Versions list, click the name of the version you just created.
4. To complete the header, click Edit.
In the Vlocity Calculation Procedure Version Detail header, enter the following information:
• Start Date Time: The day and time Vlocity will start using this calculation procedure.
• End Date Time: The day and time Vlocity will stop using this calculation procedure.
• Enabled: Select to enable this calculation procedure and locks it. Note: You can't edit a calculation
procedure that's enabled.
• Priority: The priority Vlocity gives this calculation procedure if a call matches more than one enabled
calculation procedure. The higher the priority number, the higher Vlocity ranks it. For example, if
Vlocity finds two matching calculation procedures, RatingCalc with Priority = 1 and RatingCalc with
Priority = 2, Vlocity uses the calculation procedure with Priority = 2.
• Version Number: Change if you want to give this calculation procedure a different version number.
• Enable Looping: Select to enable this as a looping calculation procedure.
To learn more about looping calculation procedures, see Using Looping in Calculation Procedures.
• Looping Specification: If you selected Enable Looping, enter a looping specification here.
5. Click Save.
Add Variables and Constants

All calculation procedures require constants, variables, or both.
NOTE
You can't use the same name for a variable that you use for a constant. Variables and
constants use the same namespace.
Here's how you add both variables and constants:
1. Add variables:
a. In the Variables and Constants section, click +Add Variable.

company 742
b. Enter variable data:

• Name: A unique name for the variable.
• Data Type: Choose one from the list.
• Precision: Optional. Enter the level of precision you want Vlocity to adhere to for this variable.
For example, enter 0.25 to make this variable's value precise to the nearest quarter of an
integer. For a dollar value example, enter 10 to make the variable precise to the nearest $10.
Enter 0 if this calculation procedure must use the precise value of this variable, with no slippage.
• Default Value: Optional. Enter a value if this calculation procedure requires a value for this
variable (it can't use a null).
If you don't enter a default value, Vlocity sets this variable to null if no value is entered for the
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
• Variables and Constants in Calculation Procedures
Add Calculation Steps

A calculation step includes one or more mathematical operations and/or functions.
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.

company 743
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.
See Also
• Functions for Calculation Procedures

• Function Reference
Add Matrix Lookups

A matrix lookup step calls a calculation matrix, supplying input to the matrix and returning its output.
1. In the Calculation Steps area, click Add Step.

2. Select Matrix Lookup.
3. In the Matrix Name field, enter the name of the calculation matrix.
After you select the calculation matrix, the calculation step displays the matrix inputs and outputs. The
system adds all columns to the Variables section. Vlocity grays out variables it adds for matrix lookups,
so you can't accidentally modify or delete them.
A link to the calculation matrix also appears on the calculation step.
4. To make this calculation step conditional, select Conditional Step.
Enter the condition that will invoke this matrix lookup.
5. To include the matrix lookup output in the calculation output data, select Include in Calculation
Output.
Add Aggregation Steps

If the input to the calculation procedure is an array—for example, multiple family members are applying for
insurance and want to view the total premium—the calculation procedure runs for each input. Using an
aggregation step, you can aggregate the procedure results and execute additional calculations on the
aggregated result.
1. On the Vlocity Calculation Procedure Version Detail page, scroll down to the Pricing Calculation
section.

company 744
2. In the Aggregation Step area, click Add Step.

3. Select Aggregation.
4. In the first field, enter one of the following operators:
• SUM
• AVG
• MIN
• MAX
5. Enter the variable to be aggregated enclosed in parentheses. For example, (price).
6. In the second field, enter a variable to represent the aggregated variable. For example, totalPrice.
7. Create all the other aggregation steps you need to complete the aggregation.
Test a Calculation Procedure

We recommend that you use the Simulator tab to test the calculation procedure you just created before
going on to create other calculation procedures, Integration Procedures, or OmniScripts.
1. On the calculation procedure page, click the Simulate tab.

2. Enter or change the information in the available fields.
3. To see only the end results of the calculation, click Simulate Final Step.
Vlocity shows the results of the final calculation step. It also shows the Input JSON (with all the values
you entered in step 2 of the test) and the Output JSON.
OR
4. To see the results of every calculation step you entered and the final result, click Simulate All Steps.
Vlocity shows the results of every step in the calculation procedure, the variables of all the values for
each step, the Input JSON, and the Output JSON.
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.
Create a New Version of a Calculation Procedure

It's much quicker to create a new version of an existing calculation procedure than it is to create a new
version from scratch. When you create a new version, all the details, variables, constants, calculations,
matrix lookups, and aggregation steps are cloned from the previous version.
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.

company 745
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.
The Looping Feature in Calculation Procedures

Looping calculations take a starting point, an endpoint, and an interval. At run time, the calculation
procedure runs in a loop from start to end per interval. Each run uses the same input variables, plus an
index variable that you can use in the calculation.
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.
To set up looping, see Configure a Calculation Procedure for Looping.
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.

company 746
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.
PREVIOUS accepts the following:
• 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).
Example 1: Calculation Procedure Simulation

For this example, the term = 2 (years), the start = 0 (year zero of the term), and the increment = 1 (year).

company 747
The output JSON for this simulation is:
{
"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"
},

company 748
{
"index": 1,
"deathBenefit": 5995.83,
"cashValue": 2995.83,
"intervalDividend": 0,
"currentAge": 48,
"endAge": 52,
"ID": "input"
},
{
"index": 2,
"deathBenefit": 8992.35,
"cashValue": 5992.35,
"intervalDividend": 44.94,
"currentAge": 49,
"endAge": 52,
"ID": "input"
}
],
"aggregationResults": {}
}
]
}
Example 2: OmniScript
In this example, the looping calculation procedure is added to an OmniScript as a Calculation Action.

company 749
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).

company 750
Configure a Calculation Procedure for Looping

Make sure that your calculation procedure UI is set up for looping calculations, then configure looping
variables.
1. From the App Launcher, go to the Vlocity Calculation Procedures tab.

2. Select your calculation procedure from the list. On the record page, click the Related tab.
3. Click the name of the Calculation Procedure Version you're using.
4. Click the gear icon and select Edit Object.
A new browser tab opens and you are in Setup, in the Object Manager, and on the Vlocity Calculation
Procedure Version page.
5. Select Page Layouts, then select the page layout you're using.

company 751
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:
11. Click Save.

12. In your calculation procedure, create three variables with a Data Type of Number and a Precision of 0.
The names must match the variables you set in the Loop Specification in the previous step.
For example:

After looping is configured, you can create calculation steps using the index variable and the
PREVIOUS function. See The Looping Feature in Calculation Procedures.
Preprocessor Class Example

The following example shows the typical structure of a preprocessor Apex class for a declarative
Calculation Procedure.
global with Sharing class PricingCalculationPreProcessExample implements

VlocityOpenInterface {

company 752
public Boolean invokeMethod(String methodName, Map<String,Object> inputMap,

Map<String,Object> outMap, Map<String,Object> options) {
Boolean success = true;
try{
if(methodName == 'calculate') {
calculation(inputMap, outMap, options);
}
}catch(Exception e){
logger.err(e);
success=false;
}
return success;
}
private static void calculation(Map<String,Object> inputMap,

Map<String,Object> outMap, Map<String,Object> options){
Logger.dbg('in preprocess input map is '+inputMap);
for(String key : inputMap.keySet()){
if(key == 'ABCD1234'){
Object realData = inputMap.get(key);
Map<String, Object> real = (Map<String, Object>) realData;
for(String key1 : real.keySet()){
if(key1=='Payor_code'){
real.put('Payor_code', 'kpf');
}
}
}
}
Logger.dbg(' in preprocess after conversion, input map is '+inputMap);
}

company 753
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.
To configure Vlocity Actions, see Configure a Vlocity Action.
Configure a Vlocity Action

Configure a Vlocity Action to 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.
1. Go to the Vlocity Actions tab.

2. Click New or select an action and click Edit.
3. On the New Vlocity Action page or Details page in edit mode, enter or update the values for these
fields:
NOTE
If a field is missing, confirm that the field is available in the Vlocity Action Layout
page layout for the Vlocity Action object.

company 754
Field Name Description

Vlocity Actions Name Required. Enter a name for the action no longer than 80 characters.
Description Beginning with Vlocity Insurance and Health Winter '20 and Vlocity CME Winter '20, Vlocity
Actions support entering a description for the action.
Applicable Type Required. Select the objects from which you want the action to launch. Default value is All.
Vlocity recommends selecting specific objects because the action attempts to invoke every
Applicable Type, which reduces performance.
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:
• 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.
Is Seed Action Select this checkbox if the action is a Contracts Document action provided out-of-the-box. Do
not check this for a custom action. Seed actions are seed data that the Vlocity Actions require
for certain functionality to work. 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.
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.

company 755

Target URL Required. The URL to which the action navigates. Enter a URL, such as /apex/<pageName>,
or a URL with parameters. For example:
/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.
Example Target URLs:
• /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.

company 756

URL Parameter If the Target URL requires parameters, enter them here. The URL parameter represents the
attribute name from the Applicable Type object, such as AccountId in Contact. In the
sequence that you want to replace the parameters in the Target URL, specify parameters in a
comma separated list with no spaces.
For example, when you enter AssetId,CustomerInteractionId,Role in this field,

AssetId replaces {0}, CustomerInteractionId replaces {1}, and Role replaces {2} in
a Target URL.
See Target URL and URL Parameters.

Applicable Permission For Vlocity Winter '18 minor release 900.85.3 and later. To specify what actions display based
Name on whether permission is granted to the user's profile or one or more of the user's permission
sets, enter the name of a standard Custom Permission object. For more information about
permission sets, see Control Who Sees What in the Salesforce help.
Filter To specify what action displays for each instance of the object, create a filter using AND or OR
conditions with attributes from the Applicable Type. For example:
Applicable Type=Policy__c, Filter=PolicyType__c='Auto' AND

Status__c='Active'
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.
Update Filter Logic for Vlocity Actions

Vlocity Action filters and the Applicable Type setting determine which action appears for an instance of an
object. You can use AND or OR conditions with the attributes in the Applicable Type setting. For example,
Applicable Type=Policy__c, Filter=PolicyType__c='Auto' AND Status__c='Active',

company 757
means this action appears only on the Action toolbar for the Policies with policy type ='Auto' and status is
'active'.
1. Go the Vlocity Actions tab.

2. Click the down arrow for the Action to update, and click Edit.
3. In the Filter field, enter the new filter logic.
4. Click Save.
Update Profile Settings for Contract Actions

Vlocity Actions control the actions and operations that are allowed in each state on a particular Contract
Document record. Vlocity Actions also control which users can perform actions and operations.
1. Go to the Vlocity Actions tab and click the checkbox next to

2. Click the down arrow for the Add Vlocity Action, and click Edit.
3. In the Applicable User Profile picklist:
a. To prevent unauthorized users from downloading contract documents, for each authorized user,
select the user from the Available list and click the right arrow to move it to the Chosen list.
b. To ensure only authorized users can download contract documents, for each unauthorized user,
select the user from the Chosen list and click the left arrow to move it to the Available list.

company 758
4. Click Save.
5. Repeat steps 1 through 4 for the Check Out to Customize and Check Out to Customize Console
actions.
Update the Link Type for an Action

The Vlocity mobile app uses the Vlocity Action link type to filter OmniScript Actions.

company 759
1. Go to the Vlocity Actions tab.

2. Click the down arrow for the Action to edit, and click Edit.
3. From the Link Type picklist, select a link type.
4. Click Save.
Target URL and URL Parameters

To launch Vlocity OmniScripts, Vlocity Cards components, web pages, or external applications from a
Vlocity Action, enter an Apex page, or a URL with parameters as the Target URL. LWC components are not
URL addressable and so can't be accessed directly from a URL and must embedded on a page. See
Vlocity 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.
Available Visualforce Pages to Launch OmniScripts

Vlocity provides these Visualforce pages to launch OmniScripts:
• OmniScriptUniversalPage
• OmniScriptUniversalPageWHeader
• OmniScriptUniversalPageWHeaderSidebar.
• OmniScriptUniversalMobilePage (for use with Mobile only)
• OmniScriptUniveralPageConsole (for use in the Industry Console)
• OmniScriptUniversalCommunitiesPage (for use in Communities)
Formatting the Target URL

For a Target URL that launches a Vlocity Card component or a Vlocity OmniScript, the first part of the URL
is the apex page, followed by the PageName, such as /apex/<PageName>. The second part of the Target
URL is a list of parameters defined in the URL Parameters field and is available to any URL types Vlocity
Actions support, including web pages and external applications.
The following example shows how to format the URL:
//Example Target URL for launching an OmniScript
/apexNS__[PageName]?id={0}#/OmniScriptType/AAA1/OmniScriptSubType/AAA2/
OmniScriptLang/AAA3/layout/[LayoutName]/ContextId/{0}/PrefillDataRaptorBundle/
[BundleName]/[verticalMode]

company 760
//Example Target URL for launching a Card component
/apex/NS__[PageName]?id={0}#/layout=[LayoutName]
//Example External URL
https://www.domainName.com/?id={0}/
Beginning with Vlocity Version 12, an alternative URL pattern is available:
//Example Target URL for launching an OmniScript
/apexNS__[PageName]?
id={0}&OmniScriptType=AAA1&OmniScriptSubType=AAA2&OmniScriptLang=AAA3&layout=[L
ayoutName]]&PrefillDataRaptorBundle=[BundleName]&scriptMode=[verticalMode]
/apex/NS__[PageName]?id={0}&layout=[LayoutName]
//Example External URL
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".
Target URL Variable Descriptions

This table lists descriptions for the variables from the Target URL examples on this page:
Variable Description Available

For
NS__ Namespace of the installed package. Use when referencing a Universal Visualforce page. OmniScript,
Card

company 761
Variable Description Available

For
[PageName] Universal Visualforce page, OmniScriptUniversalPage, OmniScriptUniversalPageWHeader, OmniScript,
OmniScriptUniversalPageWHeaderSidebar, or OmniScriptUniversalMobilePage) or another Card
Visualforce page containing the OmniScript.
{0} The first parameter listed in the URL Parameters field and is often the Context Id of an OmniScript,
sObject. See URL Parameters on this page. Card
AAA1 OmniScript Type OmniScript
AAA2 OmniScript Sub Type OmniScript
AAA3 OmniScript Language OmniScript
[LayoutName] • (Optional) For OmniScript: lightning or Newport. Defines which layout theme to use. The OmniScript,
default is lightning. Card
• (Optional) For Card: Defines which card layout to use.
[BundleName] (Optional) DataRaptor Bundle name used for prefilling fields in the script. OmniScript
[verticalMode] (Optional) true or false. If true, all the steps in an OmniScript are vertically stacked. If false, all OmniScript
the steps in an OmniScript are horizontally navigated. Default is true.
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'.
Example 19. URL Parameter Example

/apex/vlocity_ins__OmniScriptUniversalPage?
id={0}&OmniScriptType=AppointmentApplication&OmniScriptSubType=IndependentAgent
AppointmentApplication&OmniScriptLang=English&layout=lightning

company 762
/apex/NameSpace__ConsoleCards?id={0}&layout=lex-layout
Navigating URLs in Lightning and Lightning Community

Navigating to Lightning pages and from Lightning Containers requires the relative path to have a prefix.
To use proper URL syntax, follow these requirements :
• 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.
Display Vlocity Actions with the Vlocity Action Toolbar

Open Cards, OmniScripts, Community pages, web pages, documents, and external applications on a
Lightning or Community record page by clicking Vlocity Action links in the Vlocity Actions Toolbar. The
Record Id of the record page and permissions granted to Vlocity Actions determine what actions display in
the Vlocity Action Toolbar.
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.
Add the Vlocity Action Toolbar to a Lightning Record Page

Add the Vlocity Action Toolbar to a Lighting record page to open a card, OmniScript, Community page, web
page, document, or external application. For example, add the toolbar on an Account page to view all
available Vlocity Actions available to Accounts such as Update Account.
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.

company 763
Add the Vlocity Actions Toolbar to a Community Record Page

Add the Vlocity Action Toolbar to a Community record page to open a card, OmniScript, another
Community page, web page, document, or external application. For example, add the toolbar on an
Account page to view all available Vlocity Actions available to Accounts such as Update Account.
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.
Configure the Vlocity Action Toolbar

The Vlocity Action Toolbar has optional properties you can configure. By default, the toolbar works out of
the box without configuring any properties. Add a Vlocity Action Toolbar to open Cards, OmniScripts,
Community pages, web pages, documents, and external applications on a Lightning or Community record
page by clicking Vlocity Action links in the toolbar. See Display Vlocity Actions with the Vlocity Action
Toolbar.
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

company 764
Formulas and Functions
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:
&& AND || OR > >= < <= = == != <> + - * / % ^
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.
Make sure to include a space before and after an operator.
Supported Functions
Functio Return Example
n s
ABS Absolut ABS(-1) returns 1
e value
of the
specifie
d
number

company 765
ADDDA Adds ADDDAY("1999-01-01",100) returns "1999-04-11 00:00:00"

Y the
specifie
d
number
of days
to the
specifie
d date
and
returns
the
resultin
g date.
ADDM Adds ADDMONTH("1999-01-01",100) returns "2007-05-01 00:00:00"
ONTH the
specifie
d
number
of
months
to the
specifie
d date
and
returns
the
resultin
g date.
ADDYE Adds ADDYEAR("1999-01-01",100) returns "2099-01-01 00:00:00"
AR the
specifie
d
number
of years
to the
specifie
d date
and
returns
the
resultin
g date.
AGE Returns AGE(Account:Contact:Birthdate)
the age
for the
specifie
d
birthdat
e.

company 766
AGEON For a AGEON(Account:Contact:Birthdate,TODAY()) (same as AGE).

specifie
d
birthdat
e,
returns
the age
on the
specifie
d date
AVG Averag AVG(1,2,3,4,5,6,7,8,9,10) returns 5.5
e of list
of You can use AVG on a JSON array. For example, AVG(List:Item) returns 4 for the following sample data:
values.
{
"List": [
{
"Item": 3
},
{
"Item": 4
},
{
"Item": 5
}
]
}
BASEU Returns BASEURL()
RL the
base
URL of
the Org.
A
paramet
er is not
required
.
CEILIN Rounds CEILING(2.5) returns 3, which is 2.5 rounded up to the nearest integer.
G a
number
up to
the
nearest
integer,
away
from
zero if
negativ
e.
CONCA Returns CONCAT(Contact:FirstName, " ", Contact:LastName)
T the
concate
ntation
of the
specifie
d
strings.

company 767
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.

company 768
DATEDI Returns DATEDIFF("1900-01-01","2000-01-01") returns 36524

FF the
number DATEDIFF("2000-01-01","1999-01-01") returns -36524
of days
DATEDIFF(Account:Cases:CreatedDate,TODAY()) returns the number of days a case has been open
betwee
n two
specifie
d dates.
If the
first
date is
greater
than the
second
date,
the
value is
returne
d as a
negativ
e
number.
DATETI Convert DATETIMETOUNIX('11/30/2016 07:15:34') returns 1480490134000
METOU sa
NIX DateTi
me
value to
epoch
(the
number
of
second
s
elapsed
since
1/1/197
0).
DESER Convert DESERIALIZE("{\"key\":\"value\"}")
IALIZE( sa
String JSON returns { "key": "value" }
) String
LIST(DESERIALIZE("[{\"key\":\"value\"},{\"key2\":\"value2\"}]"))
into a
JSON returns [ { "key": "value" }, { "key2": "value2" } ]
object.
If the
data is
in list
format,
use the
DESER
IALIZE
function
inside
LIST
the
function
.

company 769
DOWN Use ROUND(2.572, 2, DOWN) returns 2.57

with
ROUND
to
specify
that the
roundin
g result
is
rounded
down
(toward
s zero).
EOM For a EOM(Account:Cases:CreatedDate)
specifie
d date,
returns
the date
of the
last day
of the
month.
EXIST( Returns EXIST(rentDwelling.dwBusUse, 'office')
search true if
List, the
target specifie
Value) d target
value is
found in
the list.
FILTER Filter a FILTER(LIST(InputList), 'LastName == "Smith"')
list of
JSON FILTER(LIST(data(PromotionProducts), 'productCode == "' + ConnectionProdCode + '"')
objects
and
return
the
subset
that
matche
s the
specifie
d
conditio
ns.
Support
ed only
for
DataRa
ptor
Transfo
rms.

company 770
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.

company 771
FORMA Accepts FORMATDATETIME("2019-02-02T00:00:00")

TDATE a date
TIME or FORMATDATETIME("2018-12-30T00:00:00.000000Z","yyyy-MM-dd'T'HH:mm:ss.SSSZ")
datetim
e
SObject
field or
a
datetim
e string
and
returns
a
formatte
d
datetim
e string.
A string
input
must be
in one
of these
formats:
• 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

company 772
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.

company 773
FORMA Formats FORMATDATETIMEGMT("2018-12-30T00:00:00.000000Z","America/New_York","yyyy-MM-

TDATE datetim dd'T'HH:mm:ss.SSSZ")
TIMEG e data
MT as
FORMA
TDATE
TIME
does,
but also
convert
s from
the
specifie
d time
zone to
GMT.
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.

company 774
HALF_ Use ROUND(2.575, 2, HALF_DOWN) returns 2.57

DOWN 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
down.

company 775
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.

company 776
HALF_ Use ROUND(2.575, 2, HALF_UP) returns 2.58

UP with
ROUND
to
specify
that the
roundin
g result
is
rounded
towards
the
nearest
neighbo
r (up or
down)
unless
the
neighbo
rs are
equidist
ant, in
which
case it
rounds
up.
GENER Generat GENERATEGLOBALKEY(SUB)
ATEGL es a
OBALK global Returns a value such as SUB-4c6aaba3-88e4-13f3-fe07-afa756f31e92
EY key that
can be
used as
an Id in
a
DataPa
ck. If
you
include
an
optional
paramet
er, it is
prefixed
to the
key.

company 777
IF(expr Evaluat IF(InputDate < "2000-01-01", "20th Century", "21st Century")

ession es the
, express IF(phones:brand == "Apple", phones:name, null)
trueRe ion. If
IF(SUBSTRING(price,0,1) == "$", SUBSTRING(price,1), price)
sult, true,
falseR returns IF(DriverAge >= 25,IF(FriendsReferred >= 2, true, false),IF(GPA >= 3.0, true, false))
esult) the first
result
value, if
false,
returns
the
second.
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.

company 778
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.

company 779
InvokeI Calls an InvokeIP ('Auto_Renewal', INPUT('assetId', 123456), 'AnOutPutKey')

P Integrati
('IP_Na on
me', Proced
INPUT(' ure for
Key', formula
Value), s with
INPUT(' comple
Key', x use
Value). cases.
..,
'Outpu Takes
tKey') the
'IP_Na
me' in
the
format
Type_S
ubType.
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.

company 780
ISNOT Returns ISNOTBLANK('Marty') returns true

BLANK true if
the
argume
nt is not
blank,
false if it
is.
LIST Encaps
ulates
the
argume
nt as a
list, for
calling
function
s that
require
input in
list
format.

company 781
LISTME Merges LISTMERGE("Id", LIST(CurrentAccounts), LIST(ArchivedAccounts), LIST(ProspectiveAccounts))

RGE("m any
erge_k number
ey1"[,... of lists,
"merge combini
keyN"], ng
LIST(Li entries
st1), ... when
LIST(Li the
stN)) values
of the
specifie
d keys
matche
s.
Specify
the
keys as
a
comma-
separat
ed list
of
quoted
key
names,
and
specify
lists
using
the
LIST
function
. If lists
contain
identical
ly-
named
nodes
that
contain
different
values,
subseq
uent
values
overwrit
e earlier
values
in the
result
list. The
output
contain
s all the
keys
from all
the lists.

company 782
LISTME Identica LISTMERGEPRIMARY("FirstName,LastName", LIST(ListMerge1), LIST(ListMerge2), LIST(ListMerge3))

RGEPR l to
IMARY( LISTME
"merge RGE,
_key1"[ except
,..."mer that the
gekeyN output
"], list
LIST(Li contain
st1), ... s only
LIST(Li the
stN)) keys
from the
first list.
Useful,
for
exampl
e, when
you
have a
list of
qualifie
d
product
s that
you
want to
augmen
t with
data
from
related
lists, but
you do
not
want
any
product
s from
the
related
lists
added
to the
output.

company 783
LISTSI Returns LIST(6,7,8,9,10) returns 5

ZE the
number You can use LISTSIZE on a JSON array. For example, LISTSIZE(NameList) returns 3 for the following
of items sample data:
in the
{
list.
"NameList": [
To test {
for an "FirstName": "Aaron",
empty "LastName": "Xavier"
list, use },
the {
ISBLAN "FirstName": "Zellie",
K "LastName": "Xavier"
function },
. {
"FirstName": "Mike",
"LastName": "Smith"
}
]
}
MAX Maximu MAX(1,2,3,4,5,6,7,8,9,10) returns 10
m value
in a list You can use MAX on a JSON array. For example, MAX(List:Item) returns 5 for the following sample data:
of
{
numeric
"List": [
values.
{
"Item": 3
},
{
"Item": 4
},
{
"Item": 5
}
]
}
MAXST Returns MAXSTRING("Amy","Ziggy") returns "Ziggy"
RING the last
string
alphabe
tically.
MIN Returns MIN(1,2,3,4,5,6,7,8,9,10) returns 1
the
lowest You can use MIN on a JSON array. For example, AVG(List:Item) returns 3 for the following sample data:
in a list
{
of
"List": [
values
{
"Item": 3
},
{
"Item": 4
},
{
"Item": 5
}
]
}

company 784
MONT Returns MONTH("1999-01-11") returns 1

H the
month
of the
specifie
d date
as an
integer.
NOTEX Returns NOTEXIST(rentDwelling.dwBusUse, 'office')
IST(se true if
archLi the
st, specifie
target d target
Value) value is
not
found in
the list.

company 785
NOW Returns NOW()

the
current NOW("yyyy-MM-dd'T'HH:mm:ss.SSSZ")
date
and
time in
the
user's
time
zone.
You can
supply
an
optional
formatti
ng
paramet
er using
https://
docs.or
acle.co
m/
javase/
7/
docs/ap
i/java/
text/
Simple
DateFor
mat.htm
l
notation
.
You can
use
NOW to
specify
dates
and
times
relative
to the
current
date
and
time.

company 786
ORDER Returns ORDERITEMATTRIBUTES(80146000002I7dO)

ITEMAT the
TRIBUT attribute
ES(Ord s of the
eritem order
id) item in
key-
value
pairs.
OrderIte
mId
must be
specifie
d as a
paramet
er.
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.

company 787
RESER Equival See Remote Action for Integration Procedures.

IALIZE( ent to
String SERIAL
) IZE(DE
SERIAL
IZE()).
Convert
s data
into
generic
Map<St
ring,
Object>
format.
Useful
in
Remote
Actions
for
converti
ng Apex
class
output
so that
Integrati
on Proc
edures
and
DataRa
ptors
can
accept
it.

company 788
ROUN Rounds ROUND(3.1415 * 3) = 9.42

D the
specifie ROUND(3.1415 * 3, 0) = 9
d
number
or
express
ion. By
default,
results
are
rounded
to two
decimal
places,
but you
can
specify
the
desired
number
of
decimal
places
for the
result.
You can
also
use the
UP,
DOWN,
HALF_
UP,
HALF_
DOWN,
and
HALF_
EVEN
paramet
ers to
refine
the
roundin
g
results.

company 789
SERIAL Convert SERIALIZE({ "key": "value" })

IZE(js sa
onObje JSON returns "{\"key\":\"value\"}"
ct) object
SERIALIZE(LIST([ { "key": "value" }, { "key2": "value2" } ]))
into a
JSON returns "[{\"key\":\"value\"},{\"key2\":\"value2\"}]"
string. If
the data
is in list
format,
use the
LIST
function
inside
the
SERIAL
IZE
function
. Note
how it
differs
from
TOSTRI
NG.

company 790
SORTB Sort a SORTBY(LIST(NameList), 'LastName', 'FirstName')

Y list of
JSON Sample data:
objects
{
by
"NameList": [
specifie
{
d
"FirstName": "Aaron",
nodes.
"LastName": "Xavier"
By
},
default,
{
perform
"FirstName": "Zellie",
s an
"LastName": "Xavier"
ascendi
},
ng sort.
{
To sort
"FirstName": "Mike",
descen
"LastName": "Smith"
ding,
}
specify
]
:DSC.
}
Support
ed only
for
DataRa
ptor
Transfo
rms.
Syntax:
SORTB
Y(LIS
T(Inpu
tList)
,
'key1'
,
'key2'
...,
[:DSC]
)
SQRT Calculat SQRT(12 * 3) returns 6
es the
square
root of a
value.

company 791
STRIN Returns STRINGINDEXOF("This is the test String","test") returns 12

GINDE the
XOF(St position
ring, index of
substr a
ing) substr
ing in
the
given
String
. The
first
position
is zero.
If the
substr
ing is
not
present,
the
value
returne
d is -1.

company 792
SUBST Returns The following examples operate on this input:

RING(S the
tring, portion { "input": "The quick brown fox jumped over the lazy dog." }
startI of the
String SUBSTRING(input) returns the entire String
ndex,e
ndInde that SUBSTRING(input,32) returns "the lazy dog."
x) begins
at the SUBSTRING(input,"lazy") returns "lazy dog."
startI
ndex SUBSTRING(input,0,9) returns "The quick"
and
ends at SUBSTRING(input,10,19) returns "brown fox"
the
endInd SUBSTRING(input,"q","n") returns "quick brow"
ex. The
optional
startI
ndex
and
endInd
ex can
be
Strings
or
integers
. For
integers
, the
first
position
is zero.
If the
startI
ndex is
not
found,
the first
position
is used.
If the
endInd
ex is
not
found,
the last
position
is used.

company 793
SUM Returns SUM(1,2,3,4,5,6,7,8,9,10) returns 55

the sum
of a list You can use SUM on a JSON array. For example, AVG(List:Item) returns 12 for the following sample data:
of
{
values.
"List": [
{
"Item": 3
},
{
"Item": 4
},
{
"Item": 5
}
]
}
TODAY Returns TODAY()
today's
date. TODAY("yyyy-MM-dd'T'HH:mm:ss.SSSZ")
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.

company 794
UP Use ROUND(2.572, 2, UP) returns 2.58

with
ROUND
to
specify
that the
roundin
g result
is
rounded
up
(away
from
zero).

company 795
VALUE Returns For the following sample input data:

LOOKU the
P(Star value of {
tNode, a JSON "Data": {
NodeVa node "Name": {
r, referenc "FirstName": "Thomas",
NodeVa ed by "MiddleName": "Alva",
r ,,,) another "LastName": "Edison"
JSON }
node. },
This "GetGroup": "Name",
lets you "GetField": "FirstName"
dynami }
cally
VALUELOOKUP(Data, GetGroup, GetField) returns "Thomas"
specify
the VALUELOOKUP(Data:Name, GetField) also returns "Thomas"
node to
retrieve VALUELOOKUP(Data, GetGroup) returns the contents of Name
from.
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

company 796
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.
Sample Apex Code for a Custom Function

An Apex class implements a customer function containing methods for a SPLIT() function and a SUM()
function. Note that the class and invokeMethod must be global. Note also the use of the namespace in
the interface reference.
global class CustomFunctionImplementation implements

vlocity_cmt.VlocityOpenInterface
{
/*
inputs - arguments - List<Object> of passed in arguments
output - result - The result of the Function being called. Supports
single Object values, List<Object> or Map<String, Object>
*/
global Boolean invokeMethod(String methodName, Map<String, Object> inputs,
Map<String, Object> output, Map<String, Object> options)
{
// SUM Returns a single value
if (methodName == 'sum')
{
List<Object> arguments = (List<Object>)inputs.get('arguments');
output.put('result', sum(arguments));
}
/*
Split Returns a Map<String, Object of values. Not all functions
will be able to handle Map<String, Object> results,
so be careful when using these functions.
In a DataRaptor Transform step returning a Map<String, Object>
from a Formula will result in applying that Map to the
JSON Data at the FormulaResultPath. See https://
vlocity.atlassian.net/wiki/display/RAP/Transforms

company 797
*/
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;
}
}
List Input in Custom Functions

If an input to your custom function is of the type List<Object>, the input is saved to a VLOCITY-
FORMULA-LIST key. To retrieve the input, use code that retrieves this key.
For example:

company 798
static List<Map<String, Object>> CUSTOMFUNCTION(List<Object> inputs)

{
List<Object> listInput = ((Map<String, Object>)inputs[0]).get('VLOCITY-
FORMULA-LIST');
Object variableInput = inputs[1];
// Rest of Function
}

company 799
OmniStudio Tracking Service
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.

company 800
Enable Tracking for OmniStudio Components

You can enable tracking for OmniStudio components by configuring triggers.
To configure triggers for custom fields, see Event Tracking for Custom Fields.
1. Go to Setup.
4. Enter one of the following settings in the Label field. (The Name defaults to the same value.)
Vlocity Component Type Trigger Name

OmniScripts Track_OmniScript
Integration Procedures Track_IntProc
FlexCards Track_CardFramework
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.

company 801
6. Click Save.
7. Repeat steps 3 through 6 for each trigger you want to add.
OmniStudio Components Event Tracking

Tracking data is stored in the VlocityTrackingEntry__c object. Some data, listed here, is tracked for
all components and event types. You can also add custom fields to the data being tracked.
NOTE
If you track a large amount of data, manage space consumption by implementing an
archiving policy for the tracking object.
The following data is tracked for all events:
• Tracking Event or Name: Event type, for example StepActionTime or Error

• User Id: User who triggered the event
• Context Id: The value of the Context Id node in the Data JSON
• Data: Data JSON of the tracking call
• Interaction Message
• Salesforce Session Token: Slightly masked Salesforce session token for the user
• Customer Interaction Token: Unique identifier for events logged for a single session
• Timestamp: Time of the event
• Tracking Service: The service that logged the event
• Vlocity Acuity Resource: Intelligence resource
• Vlocity Interaction: Interaction Id
• Vlocity Interaction Token: Unique token used as an identifier to associate events logged for a single
session.
See Also
• ???
• OmniScript Event Tracking
• Integration Procedure Event Tracking
• Event Tracking Data for Cards Framework
• Event Tracking for Custom Fields
OmniScript Event Tracking

For OmniScripts, the following events are tracked. For Outcome events, the user's SaveForLater and
Cancel events are logged by default. To configure the value logged for a Done action, set its Outcome
property.

company 802
Event Data Tracked

StepActionTime • OmniScript Id: The Id of the OmniScript__c sObject containing the OmniScript definition
• Context Id: Context Id value from the OmniScript Data JSON
• OmniScript Type
• OmniScript SubType
• Language
• Element Type
• Element Name
• Element Label
• Element Step Number
• Elapsed Time
Outcome • Elapsed Time
• Element Label
• Element Name
• Element Step Number
• Element Type
• OmniScript Context Id
• OmniScript Id
• OmniScript Language
• OmniScrip tSubType
• OmniScript Type
• Outcome: Cancel, Save, or the outcome configured for a Done action element.
• TrackingEvent: Outcome
Integration Procedure Event Tracking

For Integration Procedures, the following events are tracked. 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.
To track events for specific Integration Procedures, see Enable Tracking for OmniStudio Components.
Tracking Event Data Tracked

All Integration Procedure Events • CpuTotal
• DMLRowsTotal
• DMLStatementsTotal
• HeapSizeTotal
• OmniScriptId: The Id of the OmniScript__c sObject containing the definition of the
Integration Procedure
• OmniScriptType
• OmniScriptSubType
• OmniScriptVersion
• ParentInteractionToken: The VlocityInteractionToken from the calling OmniScript or
parent Integration Procedure.
• QueriesTotal
• QueryRowsTotal
• SoslQueriesTotal
• TestBatchUniqueKey: identifier for a group of test invoked together, with Preview suffix if
run in Preview, included only for Test Procedures
• TestUniqueKey: identifier for a single test invocation, included only for Test Procedures
• TrackingService: set to IntProc

company 803
Test Procedure events if • Error Code

OmniAnalyticsTrackingDebug is true • Error Message
• Error Occurred
• Request Payload
• Response Payload
Assert • assertConditionalFormula
• assertFailureMessage
(Only tracked for Test Procedures)
• assertResult
• ElementName
• StepDebugInfo: included if the OmniAnalyticsTrackingDebug custom setting is set to
true
• variableData: data that is compared with the assertConditionalFormula
Error • Action
• assertConditionalFormula: included only for Test Procedures
• assertFailureMessage: included only for Test Procedures
• assertResult: included only for Test Procedures
• ErrorTime
• StepDebugInfo: included if the OmniAnalyticsTrackingDebug custom setting is set to
true
• variableData: data that is compared with the assertConditionalFormula, included only for
Test Procedures
StepActionTime • ElapsedTime
• ElementName
• ElementResult
• ElementStepNumber
• ElementType
• StepResult
TestResult • TestStatus: Success or Failed
(Only tracked for Test Procedures)
Add Debugging Data to Test Procedure Event Tracking

When you run a Test Procedure in the Preview tab, JSON data for debugging is included in the Errors/
Debug Output pane. To include this debugging data in VlocityTrackingEntry__c object records under
the StepDebugInfo JSON node, you can set the value of the OmniAnalyticsTrackingDebug custom
setting to True.
1. Go to Setup.
4. In the Label field, type OmniAnalyticsTrackingDebug.
5. In the Value field, type True.
6. Click Save.
Cards Framework Event Tracking

The OmniStudio Tracking Service is an event-tracking service that can capture details about how Vlocity
users interact with the Cards Framework.

company 804
Preview Event Tracking in the Cards Designer

Typically, administrators who are tracing Cards Framework triggers want to track only runtime events. The
Cards Framework includes a Track_CardPreview trigger for Card Designer Preview tracking entries,
which you can disable to screen out preview events.
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
Event Tracking Data for Cards Framework

For the Cards Framework, events tracked are OmniAnalytics Card Events, initTracking, initCardFramework,
initLayout, selectCard, performAction, trackField, and Resolution.
The following data is logged for all Card events:
• Salesforce Session Token

• Vlocity Interaction Token
• User ID
• Timestamp
The following table lists events and event-specific data logged for user interaction with the Cards
Framework:
Event Data Tracked

initTracking Context ID
initCardFramework Context ID
initLayout • Card Name
• Context ID
• Layout Info
• Layout Name
• Layout Version

company 805
selectCard • ID
• Interaction Topic ID
• Name
• Policyholder
performAction • Context ID
• ID
• Interaction ID
• Role
trackField • ElapsedTime
• EntityLabel
• EntityName
• Field Value
Resolution None
(End tracking)
Event Tracking for Custom Fields

For Integration Procedures, FlexCards, and OmniScripts, you can add your own custom fields to the data
stored by the Tracking Service.
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:
• Custom field added to VlocityTrackingEntry__c object: MyTrackingField__c

• Corresponding Data JSON key: MyTrackingField
Add the JSON key/value pairs to the Tracking Custom Data list in the component. This list is located:
• In the Setup panel of the FlexCard

• In the Procedure Configuration of the Integration Procedure
• In the Script Configuration of the OmniScript
NOTE
If space is a concern, be sure to monitor the size of the tracking object and delete
unneeded records as required.
Tracking Session Interaction Id

To associate all the events tracked for a single session, the tracking system logs an Interaction Id that is
unique for the session. To provide this Id from an OmniScript or Integration Procedure, add a key/value pair
to the Tracking Custom Data field in the Configuration section.
For example:

company 806
CustomerInteractionId: %InteractionId%
To provide the Interaction Id in a REST call, specify it as a parameter:
/apex/DFOmniScriptUniversalPageConsole?id={0}&OmniScriptType=Policy
%20Servicing&OmniScriptSubType=Payment
%20Extension&OmniScriptLang=English&scriptMode=vertical&layout=lightning&Contex
tId={0}&InteractionId={1}&Role={2}
Tracking Data Preprocessor

Before the tracking service executes its own logic, it calls any interface implementations named
TrackOmniScript or TrackCard, enabling you to preprocess tracking data. For example, this
implementation uses the customer ID submitted by an OmniScript to add customer detail to the event data.
global class VlocityDemoTrackOmniscript implements

vlocity_cmt.VlocityOpenInterface {
global Boolean invokeMethod( String methodName, Map<String,Object>
inputMap, Map<String,Object> outMap, Map<String,Object> options ) {
Boolean success = true;
string errors = 'OK';
try {
if( methodName == 'processTracking' ){
processTrackingEvent( (List<Map<String,
Object>>)inputMap.get('trackingDataList'), outMap );
}
} catch ( Exception e ) {
errors = e.getMessage();
success = false;
System.debug( '##### errors: ' + errors );
}
return true;
}
/**
* Process the tracking events
*/
void processTrackingEvent( List<Map<String, Object>> trackingDataList,
Map<String, Object> outMap ){
// Get the current users Id from the input JSON...
Id userId = (Id)trackingDataList[0].get('UserId');
// Get the users details to add to the tracking data...
User currentUser = [SELECT Id, FirstName, LastName, Profile.Name,
UserRole.Name FROM User WHERE Id = :userId];
// Iterate through the tracking entries and add the User's details...
for ( Map<String, Object> trackingEvent : trackingDataList ){
trackingEvent.put( 'UserFirstName', currentUser.FirstName );
trackingEvent.put( 'UserLastName', currentUser.LastName );

company 807
trackingEvent.put( 'UserProfile', currentUser.Profile.Name );

trackingEvent.put( 'UserRole', currentUser.UserRole.Name );
}
outMap.put( 'trackingDataList', trackingDataList );
}
}

company 808
OmniStudio Lightning Web Components
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.
OmniStudio Vlocity Lightning Web Components are:
• 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.
OmniStudio Vlocity Lightning Web Components Reference

Component Type Description References
Base Basic components used by the entire Vlocity platform. Extend or ReadMes: Base Vlocity LWC ReadMe
modify base components to customize appearance and behavior. Reference
OmniScript Components specific to OmniScript. ReadMes: OmniScript ReadMe
Reference
NOTE
OmniStudio FlexCards are built with the Lightning Web Components programming model
and share base components. FlexCards are created in the FlexCard Designer.
Set Up Lightning Web Components

To manage and develop Vlocity Lightning Web Components, use Salesforce DX with Visual Studio or IDX
Workbench with Visual Studio. Both development approaches have source control. However, we
recommend IDX Workbench because it enables you to migrate Vlocity components from one org to another
and compare both source and target files.
• 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.

company 809
Extend Vlocity Lightning Web Components

Customize the behavior and styling of an application by extending OmniStudio Vlocity Lightning web
components. For example, override properties, add other components, or insert HTML.
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.
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:
sfdx force:lightning:component:create --type lwc --componentname

componentname_extended
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.

company 810
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
import Button from "NS/button";
export default class buttonExtended extends Button {

//override the property here so it gets triggered
onclickbutton() {
this.label = "Button clicked";
}}
//.js-meta.xml
<?xml version="1.0" encoding="UTF-8"?><LightningComponentBundle xmlns="http://

soap.sforce.com/2006/04/metadata">
<apiVersion>45.0</apiVersion>
<isExposed>true</isExposed>
<masterLabel>button_extended</masterLabel>
<description>Button extended</description>
<targets>
<target>lightning__RecordPage</target>
<target>lightning__AppPage</target>
<target>lightning__HomePage</target>
</targets>
<runtimeNamespace>NS</runtimeNamespace>
</LightningComponentBundle>
//.html
<template>
//add HTML here to override the template layout
</template>
//_slds.css
//add CSS to override or append the SLDS theme css

.slds-button {
background: #cccccc;
border-color: #dddddd;
}

company 811
Deploy Lightning Web Components

Deploy new Lightning web components or change existing components from your local development
environment with Visual Studio and Salesforce DX or IDX Workbench. To set up your development
environment for managing and deploying your components, see Set Up Lightning Web Components.
1. Open your project in Visual Studio.

2. Make sure you have Salesforce DX or IDX Workbench installed. To install Salesforce DX or IDX
Workbench, see Salesforce DX Setup Guide.
3. In the terminal, run the following command to deploy changes to your org:
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.
Launch Lightning Web Component URLs with vlocityLWCWrapper

Add the vlocityLWCWrapper to make Lightning web components in a Lightning page URL addressable.
Lightning web components are not URL addressable by default. The vlocityLWCWrapper wraps the
Lightning web component in a URL addressable aura component.
For information on accessing an LWC OmniScript through a URL, see Launch an OmniScript with LWC
OmniScript Wrapper.
Configuring a URL to launch a Lightning Web Component

1. Add the wrapper by copying the relative path in the example and replacing the NS variable with the
namespace of the OmniStudio Vlocity package. For information on locating the namespace, see
Viewing the Namespace and Version of the OmniStudio Vlocity Package.
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

company 812
5. (Optional) Assign additional attributes by passing parameters that match the attribute names.
Parameters must use the c__ prefix.
Example Button Component Code:
<c-button label=”Dynamically Generated” variant=”outline-brand”</c-button>
Example Button Component as a URL addressable component:
lightning/cmp/NS__vlocityLWCWrapper?
c__target=c:button&c__label=Dynamically Generated&c__variant=outline-brand
Example Image:
Launching an LWC from a Layout Action

1. From Setup, enter Object Manager into the Quick Find search.

company 813
2. Select an Object, and click Buttons, Links, and Actions.

4. Set Display Type to Detail Page Button.
5. Set Content Source to URL.
6. In the URL value, add a vlocityLWCWrapper URL. For information on configuring vlocityLWCWrapper
URLs, see Configuring a URL to launch a Lightning Web Component.
lightning/cmp/NS__vlocityLWCWrapper?c__target=c:demoButton
Base Vlocity LWC ReadMe Reference

View examples, and learn about available attributes, methods, and other functions from the ReadMes of
each Base Vlocity Lightning web component. To extend components, see Extend Vlocity Lightning Web
Components.
Release Download File

Vlocity Health and Insurance Spring '21 baseLWCReadMes.zip

company 814
Data Migration with OmniStudio DataPacks
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.

company 815
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.
1. Open the object to export in its designer.

2. Click Export.
The Export DataPack dialog box opens.
3. Click Next.
The Review dialog box opens.
4. Click Next.
The final Export dialog box opens.
To avoid overwriting an existing DataPack, specify a unique name and version.
When Published is checked, the DataPack goes to the Published subtab in the DataPacks tab.
When Download is checked, the DataPack JSON is downloaded to your local machine.
5. Click Done.
The DataPack is created, then downloaded to your download directory if you selected Download.
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.

company 816
NOTE
supported.
1. Download the DataPack from the source org.

2. Log into the target org.
3. Go to the appropriate designer tab and click Import.
4. When prompted, browse to the DataPack file and click Open.
5. Click Next and respond to the import wizard prompts until the file is imported.
Supported DataPack Object Types

Objects that can be exported as DataPacks are listed here.
• 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

company 817
• 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

company 818
Fix the DataPack Import/Export Error: No Configuration Found

If you see the error message No Configuration Found: while trying to import or export a DataPack, this is
most likely an issue with the Salesforce Org's configuration. This error often occurs in Developer
Sandboxes that are missing some of the Vlocity Configuration files due to a recent refresh or an install or
upgrade that has missed a post-install or post-upgrade step. You can fix this error.
The solution is to run code in Anonymous Apex. To do that, you must access the Developer Console:
1. Navigate to the Developer Console.

• In Lightning Experience, click the gear icon and select Developer Console from the menu.
• In Salesforce Classic, click the user menu and select Developer Console from the menu.
2. Select Debug > Open Execute Anonymous Window.
3. Paste the following code into the Enter Apex Code window:
namespace.CorePostInstallClass.runDev2ProdInserts();
If you are using Contract Life Cycle Management, add:
namespace.CmPostInstallClass.cmRunDev2ProdInserts();
If you are using Order Management, add:
namespace.XOMCreateDPMappings.createDPMappings();
4. For namespace, substitute one of the following:
• vlocity_cmt for Vlocity Communications, Media, and Energy
• vlocity_ins for Vlocity Insurance
• vlocity_ps for Vlocity Government
5. Click Execute.

company 819
IDX Workbench Desktop Application
IDX Workbench is a desktop application that enables you to migrate OmniStudio DataPacks and Salesforce
metadata.
Migrations are supported:
• From one Vlocity org to another

• From a Vlocity org to a Git repository
• From a Git repository to a Vlocity org
• From the Vlocity Process Library to a Vlocity org
• From a JSON file to a Git repository or a Vlocity org
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
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.
Install IDX Workbench

IDX Workbench is a desktop application, so you must install it on your computer.

company 820
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.
Configure LWC OmniScript and FlexCard Activation and

Compilation
If Google Chrome is your default browser and IDX Workbench logs you into your source and target orgs
through it, you can skip this task. When you migrate OmniScripts, Integration Procedures, and FlexCards,
they’re automatically activated in the target org. However, if you use a different browser, you must configure
this automatic activation feature manually.
To configure automatic activation of migrated OmniScripts, Integration Procedures, and FlexCards for a
non-Chrome browser:
1. Install Node.js on your computer.

2. Open a terminal window on your computer.
3. Install the Puppeteer module on your computer using this command:
npm install puppeteer -g
IDX Workbench uses the Puppeteer module to automatically activate OmniScripts, Integration
Procedures, and FlexCards in the target org.
See Also
• nodejs.org
IDX Workbench Configuration for Migration

Before you can migrate components, you must specify the source, the target, and the objects to be
migrated. The source can be an org, a Project object in an org, a JSON file, the Vlocity Process Library, or
a Git repository. The target can be an org or a Git repository.
You can also save to a JSON file when you migrate. See Save Objects to a JSON File.

company 821
Configure for Migration Between Orgs

You must configure a Source org and a Target org. Both must be Vlocity orgs.
NOTE
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.

company 822
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.

company 823
7. If your Source is a sandbox org, change the Organization Type to https://test.salesforce.com.

8. Click Log in using OAuth. The Salesforce login window appears. Log in to the org.
If the Allow Access window appears, click Allow.
9. From the Target drop-down list, select New Environment.
Repeat the same steps.

company 824
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.

company 825
13. Click Fetch DataPacks.

14. Under Pick datapacks for project, you can optionally enter text to filter the names of the fetched
objects.
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.

company 826
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.
18. Click Save to save the workspace.

Messages appear as objects are fetched. To cancel, press Command-R on the Mac or Control-R on
other operating systems.
19. When the listing is complete, IDX Workbench looks like this:
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.

company 827
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.
Configure an Org Using a Community User Login

When you configure an org for running Test Procedures, you can specify a Salesforce Community and
authenticate as a Community user. This is especially useful for running Test Procedures in which user
access affects the results.
You must set up the Community user to have access to all Integration Procedure related objects, the
Tracking Service, and the Apex class ProcedureTestFramework.
Before You Begin

For assistance with these tasks, see Set Up and Manage Salesforce Communities.
1. Set up a Salesforce Community.

2. Create a Community user with the required Permission Sets.
3. Know the username and password for this user.
1. In the org, go to Setup.

2. In Setup, in the Quick Find box, type communities, then select All Communities.
3. Copy the URL of the Community you want to use.
4. In IDX Workbench, select New Environment from the Source, Target, or Test User drop-down list.
5. Specify the Name of the user or another descriptive name.
6. Click the + to the right of the Organization Type field.
7. Paste the URL of the Community into the Enter a new Login URL field.
8. Click Log in using OAuth. The Salesforce login window appears. Log in to the org using the user's
username and password.
If the Allow Access window appears, click Allow.
Configure a Project Object

To create a Project object, see the Vlocity Success Community Documentation.
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.

company 828
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.
Configure for Migration from a JSON File

You can specify a DataPack as a Source and migrate to either an org or a Git repository Target. The
DataPack must include all the objects you want to migrate in a single JSON file.
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.
Configure for Migration from the Salesforce Industries Process Library

You can migrate DataPacks from the Salesforce Industries Process Library to a Vlocity org.
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.
Configure for Migration Between a Repository and an Org

You can use a Git repository as a Source or Target in IDX Workbench, migrating DataPacks from the
repository to a Vlocity org or the reverse.

company 829
Before You Begin

Before you can set up a project with a Git repository as a Source or Target, you must:
1. Install Git on your computer. See Installing Git.

2. Set up your identity for using Git. See First-Time Git Setup.
3. Ensure that IDX Workbench has access to the Git repository.
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.
To create a project using a Git repository as its Source or Target:
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.
Give a Bitbucket Git Repository Access to IDX Workbench

You can give IDX Workbench access to a Bitbucket repository using a password.
1. Go to Bitbucket in your browser.

2. Click the icon with your initials and select Bitbucket settings.
3. Under ACCESS MANAGEMENT, click App passwords.

company 830
4. Click Create app password.

5. For the Label, specify VlocityDX.
6. Under Repositories, check the level of access you have to the repository.
For example, if you have write access, check Write.

company 831
7. Click Create.
8. Copy the displayed password to a place from which you can copy it again, such as a text file.
9. Go to the repository you want to use as the Source.

company 832
10. Click Clone.

11. In the Clone this repository dialog, change SSH to HTTPS.
12. Copy the URL to a place from which you can copy it again, such as a text file. It should look something
like this:
https://username@bitbucket.org/company/reponame.git
13. Edit the URL to add a colon and the password after the username. For example:
https://username:rCcrFYhXY4rSrxLaW8HV@bitbucket.org/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.
Create Additional Projects

After you have created your first project, you can create additional projects.
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
Switch Between Projects

You can switch from your current project to another existing project.
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
Handle a Login Failed Message

If you refresh a Source or Target org and see a Login Failed ... Please Login Again message,
you can fix the error.
1. If the Configure Workspace dialog isn't open, click the Edit icon on the main IDX Workbench screen to
open it.

company 833
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.
Use a .vlocityignore File to Exclude Objects

You can specify a list of object types and/or objects to ignore in all the projects that use the same
repository.
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.
Object Migration and Comparison

After you have configured a project, you can migrate objects from the Source to the Target. After the initial
migration, you can compare objects in the Source and Target to see if any have been updated and need to
be migrated again. You can also save objects in the Source to DataPacks.
Migrate Objects from the Source to the Target

When you first create a project, the objects to be migrated still exist only in the Source. These objects are
listed in the left panel on the main IDX Workbench screen.
To migrate objects to the Target:

company 834
1. Select the check box next to each object to be migrated.
2. Click Actions > Migrate with Dependencies.
3. Verify that migration was successful.

When migration is complete, Migrated labels appear next to successfully migrated objects.
In addition, information about the objects appears in the Comparison and Migration tabs.

company 835
Object Migration and Comparison Options

After you have configured a project, you can migrate objects from the Source to the Target. After the initial
migration, you can compare objects in the Source and Target to see if any have been updated and need to
be migrated again. You can also save objects in the Source to DataPacks.
Refresh Options for Comparing Objects

To see if any objects have been updated in your project, click Refresh on the main IDX Workbench screen,
then select one of these options:
• 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.
When the Refresh Diffs? dialog appears, click Continue.
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.
If the Source is a JSON file, the Refresh menu is disabled.

company 836
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.
On the Comparison tab, differences are summarized.
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.
To synchronize objects that differ, do one of the following:
• Select the check box next to each object to be migrated and click Actions > Migrate with
Dependencies.

company 837
• 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.
Discard All Option for Deleting Components

When you compare DataPacks on the Comparison tab, details of differences are displayed. For example,
here is a comparison showing a Set Values action in an OmniScript:
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.
Options to Filter the List of Objects

To filter the list of objects, click the Filter (funnel) icon. Use the following filter options:
• 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.
Git Command Options

To use Git commands on a Target Git repository, click the Git (branch) icon. Use the following Git
commands:
• Init — Initialize the repository folder.

company 838
• Checkout Branch — Select an existing branch or create a new one.

• Pull — Pull the latest changes from the selected branch into your branch.
• Push — Push your changes to the selected branch.
• Status — List the changes in your local branch that aren't present in the remote branch.
Save Objects to a JSON File

Instead of migrating objects to another org, you can save them to a DataPack instead.
1. Select the check box next to each object to be saved.
2. Click Actions > Save. The Save DataPacks window appears.

3. Specify a File Name and a File Path. Click Choose to browse for a file path.
4. Click Save. The saved file is given a .json extension.
Use the IDX Workbench Process Profiler

The Process Profiler lets you view OmniStudio Tracking Service data for an object in a Source or Target
org. Before you can view this data, you must enable triggers as described in Enable Tracking for
OmniStudio Components and run through your business flow to capture this tracking data.
1. Click the List Panel icon in the upper left corner, .

2. Click Process Profiler.
3. Select an Org from the drop-down list. Orgs configured in any project are listed, or you can configure a
New Environment.
Performance data is downloaded immediately. For large orgs, this can take some time.
4. Select a Component Type from the drop-down list, either OmniScript or Integration Procedure.
Component types that have tracking data are listed.
5. Select a Component from the drop-down list. Components that have tracking data are listed.
6. (Optional) To filter the data by date, enter a Start Date and/or an End Date.
7. (Optional) To limit the number of invocations to be averaged, type an integer in Last N Executions.
8. (Optional) To filter the data by component users, click the User list and check the boxes to the left of
the desired user names.
9. (Optional) 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.

company 839
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:
Compare OmniScript and Integration Procedure Versions

The Version Compare dashboard lets you compare two versions of an OmniScript or Integration Procedure
in the same Source or Target org.

2. Click Version Compare.
3. Select a Data Source from the drop-down list. Orgs configured in any project are listed.
Data is downloaded immediately. For large orgs, this can take some time.
4. Select a Component Type, either OmniScript or IntegrationProcedure, from the drop-down list.
5. Select a Component from the drop-down list.
6. Select a Base Version and a Target Version.

company 840
7. Click Find Differences.

The listing of differences looks something like this:

company 841
8. Click View Source to see additional details about the differences. To delete a component from the
target version, click Discard All.
Run Test Procedures

The Test dashboard lets you run Test Procedures (Integration Procedures that perform unit tests) and
analyze the results of the tests.
To create Test Procedures, see Test Procedures: Integration Procedures for Unit Testing.

2. Click Test Console.
3. Select a user logged into an org from the Test User drop-down list.
A list of active Test Procedures appears. To refresh the list, click Get Tests.

company 842
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.

company 843
If a test fails, the failure message and test expression from the Test Procedure's Assert Action for
Integration Procedures are displayed.
6. To display all of the test result data, click View JSON.

company 844
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.

company 845
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.

company 846
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.

company 847
11. You can expand Data and scroll down to see the request and response data.

company 848
IDX Workbench Menu Commands

Most of the commands in the IDX Workbench menus are like those of any application. For example, Edit >
Copy copies the selected text. Commands specific to IDX Workbench are listed here.

company 849
• 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.

company 850

OmniStudio Documentation

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OmniStudio Documentation

Uploaded by

Copyright:

Available Formats

OmniStudio Foundation

OmniStudio Basics ..................................................................................................................... 2

© 2021 Vlocity LLC, a Salesforce

Activate Elements in the OmniScript Designer ............................................................. 21

© 2021 Vlocity LLC, a Salesforce

Apply Custom Styling to OmniScripts with Static Resources ....................................... 187

© 2021 Vlocity LLC, a Salesforce

Manage OmniScript Data ......................................................................................... 258

OmniStudio FlexCards ............................................................................................................. 288

© 2021 Vlocity LLC, a Salesforce

FlexCards Action Properties ..................................................................................... 309

© 2021 Vlocity LLC, a Salesforce

Configure an Apex Remote Data Source on a FlexCard ............................................. 395

© 2021 Vlocity LLC, a Salesforce

Activate a FlexCard ......................................................................................................... 458

© 2021 Vlocity LLC, a Salesforce

Local Variables ........................................................................................................ 484

OmniOut ................................................................................................................................. 488

© 2021 Vlocity LLC, a Salesforce

What's Next ............................................................................................................. 510

OmniStudio DataRaptors .......................................................................................................... 523

© 2021 Vlocity LLC, a Salesforce

DataRaptor Calls From Apex .................................................................................... 569

OmniStudio Integration Procedures ........................................................................................... 585

© 2021 Vlocity LLC, a Salesforce

Integration Procedure Best Practices ................................................................................ 662

Calculation Procedures and Matrices ........................................................................................ 707

© 2021 Vlocity LLC, a Salesforce

Calculation Matrices ......................................................................................................... 709

Vlocity Actions ......................................................................................................................... 754

© 2021 Vlocity LLC, a Salesforce

Formulas and Functions ........................................................................................................... 765

OmniStudio Tracking Service .................................................................................................... 800

OmniStudio Lightning Web Components ................................................................................... 809

Data Migration with OmniStudio DataPacks ............................................................................... 815

© 2021 Vlocity LLC, a Salesforce

IDX Workbench Desktop Application ......................................................................................... 820

© 2021 Vlocity LLC, a Salesforce

With OmniStudio, you can create:

• OmniScripts, which contain the interaction logic

© 2021 Vlocity LLC, a Salesforce

• A customer service agent to add a new customer

• Add actions such as extract data or send an email

© 2021 Vlocity LLC, a Salesforce

You can launch an OmniScript from anywhere, including:

© 2021 Vlocity LLC, a Salesforce

Actions on an account card might include:

© 2021 Vlocity LLC, a Salesforce

Design and Layout

DataRaptor or Integration Procedure?

Use a single DataRaptor if:

Use an Integration Procedure if:

© 2021 Vlocity LLC, a Salesforce

Use the Applications Together

Here's an example of FlexCards, OmniScripts, and DataRaptors used together to:

• Display and provide a context for information and actions

© 2021 Vlocity LLC, a Salesforce

Customizable Style Guide for Newport Design System

• Lightning: This references the Salesforce Lightning Design System.

About the Newport Design System

The Newport Design System supports two functions:

• Provides an out-of-the-box consumer-grade visual style guide.

Although the VlocityOpenInterface and VlocityOpenInterface2 interfaces enable flexible

To change custom classes that implement VlocityOpenInterface or VlocityOpenInterface2 to