How to debug Vlocity Omniscripts in runtime mode

Structure of the OmniScript used as example

This example uses a simple OmniScript with two steps and one Integration Procedure:

•  In the first step the user provides an account Id.

•  The Integration Procedure calls a DataRaptor that retrieves accounts based on the Id provided. The response from the IP is outputted to the “IPGetAccountById” node.

•  The second step displays the details retrieved by the Integration Procedure.

Angular OmniScript Debugging

This controller contains a:

1. Scope -> definition of all available methods

Path: baseCtrl.prototype.$scope

1. bpTree ->  the OmniScript structure definition and variables

Path: baseCtrl.prototype.$scope.bpTree

1. response -> the OmniScript JSON Data

Path: baseCtrl.prototype.$scope.bpTree.response

Debug the Omniscript JSON Data

1. While the OS is being executed, right-click anywhere on the OS and select “Inspect Element”

This step is important otherwise the controller might not be accessible or appear as undefined.

2. Go to console and type baseCtrl.prototype.$scope.bpTree.response

The values printed in the console (left) are the same values that would be visible on the JSON Data in preview mode (right):

3. The values printed on the console are not automatically refreshed. Therefore, call baseCtrl.prototype.$scope.bpTree.response any time the JSON Data is updated.

The Omniscript field values can also be accessed directly by traversing the Omniscript JSON Data, for example the “TxtGetAccountId” field can be accessed by using the following path:

baseCtrl.prototype.$scope.bpTree.response.StepGetAccountInfo.TxtGetAccountId

Debug omniscript actions

All OmniScript Action components (Integration Procedure, Remote Actions, etc…) will trigger a request to the server. Server requests and responses can be monitored through the browser’s “Network” tab.

1. In the OmniScript, right-click and select “inspect Element”

2. In the “Network” tab start recording the network activity (in chromium browser’s: “crtl + E”)

3. Follow the OmniScript flow until the OmniScript action to debug is executed.

In the Network tab an “apexremote” entry should appear. Depending on the OmniScript, several “apexremote” entries might appear. There will be one entry per OS Action. Make use of the “Record Network” functionality to limit the number of entries.

4. Select the “apexremote” entry and go to the “Headers” tab > “Request Payload” > “Data”

In the “Data” section, you’ll find the type of OmniScript action (0), the Unique name of the OmniScript: Type_Subtype (1), the payload (2) and the Action remote options (3).

5. The response from the server can be found under the “Preview” tab (Pretty-printed) and under the “Response” tab (raw response)

LWC Omniscript 

LWC OmniScripts (LWC OS) makes use of the Salesforce Lightning Web Components (LWC) framework. As such, the same debugging principles can be applied.

Like it’s Angular counterpart, a LWC OS contains an object with all the OmniScript variables, including the JSON data: 

1. jsonDef -> json definition of the OmniScript

Path: .jsonDef

2. jsonData -> the data JSON of the OmniScript

Path: .jsonData

Tip: look at the documentation for the LWC OS and read the examples provided by vlocity to get insights of how the LWC OS javascript code is structured.

Debug the OmniScript JSON Data

1. While the Omniscript is running, right-click anywhere on the OmniScript and select “Inspect Element”.

2. Go to the “Source” tab and select the javascript file for the OmniScript

Source > lightning/cmp > modules > c > [typeSubType of the OS].js

3. Use the Pretty-print functionality to have a better view of the OmniScript code. Either click on the “Pretty-print” prompt in the top of the file or press the { } icon at the bottom.

4. Create a breakpoint in the line with the string literal “vlocity_cmt-omniScript-step”.

Salesforce LWC components are compressed to facilitate delivery through the Web, this means that all variables and functions names are replaced with single letters. However, it’s still possible to understand what the code is doing. The javascript file generated for the LWC OmniScript contains a reference to every type of component that was added to the OmniScript and these references are using string literals. For example: a LWC OS that contains a single Step and a single text field will generate a javascript file with the following string literals:

Step -> vlocity_cmt-omniscript-step

Text file -> vlocity_cmt-omniscript-text

5.  Click “Next” on the OmniScript.

This will start the debugging session and provide access to the variables.

If the OmniScript only contains one step, then create the breakpoint in another component, a text field for example.

6. In the  sources tab check where the jsonDef is nested. 

Because the javascript is minified, the variable names will be changed. In the source tab check to which variable the jsonDef object is assigned to. 

In the following example, it’s assigned to the variable “t”.

7. In the Console tab type t.jsonDef.response or t.jsonDataStr

t.jsonDef.response will output a proxy object with the OmniScript JSON Data. 

Click to open the proxy and go to [[Handler]].originalTarget

t.jsonDataStr will output a string the OmniScript JSON Data in a string format.

Debug OmniScript Actions

All OmniScript Action components (Integration Procedure, Remote Actions, etc…) will trigger a request to the server. Server requests and responses can be monitored through the browser’s “Network” tab.

1. In the OmniScript, right-click and select “inspect Element”

2. In the “Network” tab start recording the network activity (in chromium browser’s: “crtl + E”)

3. Follow the OmniScript flow until the OmniScript action to debug is executed.

In the Network tab an “aura.ApexAction” entry should appear. Depending on the OmniScript, several “aura.ApexAction” entries might appear. There will be one entry per OS Action. Make use of the “Record Network” functionality to limit the number of entries.

4. Select the “aura.ApexAction” entry and go to the “Headers” tab > “Form Data” > “Message”

In the “Message” JSON, you’ll find the type of OmniScript action name and the values sent to the server.

5. The response from the server can be found under the “Preview” tab (Pretty-printed) and under the “Response” tab (raw response)

Conclusion

The techniques illustrated by this guide can be applied during the building phase or even when the omniScript is running in a production environment. This will add one more tool to your vlocity toolbelt and better prepare you to handle future challenges. 

There is a final and very important point that should be highlighted: Security. With the browser console it’s very easy to track what data is being traded between the OmniScript and the server. So when building an Omniscript, or any client-side application, always be conscious of the data that is being retrieved. Ask yourself what the data will be used for. If only the first name and last name of the customer is needed for display purposes, perhaps there is no need to also bring the customer address and contact information. Another example are client keys and security tokens used for HTTP/remote callouts. When doing multiple callouts, it might be quicker to fetch the tokens once, store in the OmniScript JSON and then pass them to the HTTP actions as needed. However, doing so will expose those tokens to the client also. 

Being careful and deliberate with the data being exposed to the client side will avoid security and GDPR risks.