Use ServiceNow® Virtual Agent script methods and variables to write chat scripts, such as response, trigger, and flow scripts. Variables can also provide context for your live support topics and conversations.

Virtual Agent scripts can provide context for topics, such as retaining information about a user or a user's input. You can use this information to personalize a conversation, such as to present a scripted greeting or confirmation. Scripts can also specify certain actions to be performed on information that was obtained during a conversation. These actions can be used for creating or updating ServiceNow records.

Scripts run on the server in the scope in which a topic is defined. All scope protections apply. If you're developing a conversation for a scoped application, you must use the scoped API. You can use most APIs that run in server scripts.

User input and ServiceNow record variables

In Virtual Agent, the following variables are available for use in scripts that you create for a topic.

User input variables

When you add an input control to a topic, the system automatically creates a variable to store the user input (a string, Boolean value, and so on.). The syntax is vaInputs.myvar where myvar is the name that you assigned to the input node.

For example, a text input prompt with the name First prompt has a system-defined variable called vaInputs.first_prompt. Spaces in the name are replaced with an underscore character, and uppercase characters are changed to lowercase.

ServiceNow record variables

If you create a script for a topic that queries a ServiceNow table, then the record object (GlideRecord) returned is automatically available for use in the topic. The variable syntax is vaInputs.myvar where myvar is the record object. For details on querying ServiceNow tables to return a record object, see Querying tables in script.

Use dot-walking in variables that contain a ServiceNow record to specify a particular field in the table. The syntax is vaInputs.myvar.field. For details on dot-walking within a script, see Dot-walking examples.

Accessing user input and ServiceNow record variables

Use vaInputs objects to access ServiceNow record variables in scripts. For example, the vaInputs.myvar == "expected value". To access values from user inputs that are not records, use vaInputs.myvar.getValue().

The following methods are available.

Table 1. vaInputs methods
Method Description
vaInputs.myvar == "expected value" Evaluates whether myvar matches an expected value.
Note: Values for user input variables are assigned using user input controls. These values can’t be changed in your scripts.
  • The Xanadu release supports additional data types. For more information, see Input data types in Virtual Agent topics.
  • By default, the user variable is available and is a reference to the sys_user record for the user.
vaInputs.myvar.getValue(); Returns the value.
vaInputs.myvar.getDisplayValue();

Returns the display value if the stored value is not a ServiceNow record. For variables that contain ServiceNow records, this method returns the display value, as defined by the display field for that table.

The following example shows the label and choice values for a user input. In this case, myVar.getValue() would return a value of 10, 20, or 30, while myVar.getDisplayValue() would return Apple, Orange, or Pear.

Figure 1. Example choice list
Label fields include Apple, Orange, and Pear for the choices. The values for each are 10, 20, and 30.
vaInputs.myvar.getDefaultValue(); Returns the default value in a confirmation message.
vaInputs.myvar.getDefaultDisplayValue(); Returns the display value for the default value in a confirmation message.
vaInputs.myvar.unbindEntity(); Removes the value of input variables that the NLU prediction service slot-filled with extracted entities (unbinds it from the initial input value).

For example, if the user decides to change their choice on a confirmation prompt, you can unbind the entity's value from the input variable. The user will then be prompted again when they loop back to the corresponding input node.

Note: NLU must be enabled on the topic. In the Virtual Agent Designer, select the Properties tab to set up NLU. For information about defining NLU entities, see Entities.

Script variables

You can define script variables for information that is not stored in ServiceNow tables but that can be used to share that information elsewhere in a topic. Script variables are similar to workflow scratchpad variables that store primitives such as integers, Boolean values, or strings. A string value can be either a static or dynamic scripted value. Use the Variables sidebar to define script variables for a topic in Virtual Agent Designer.

Figure 2. Variables sidebar
Sidebar in the Virtual Agent Designer page for manually adding script variables that are used in topic scripts.
Note: Script variables are intended for use by topic authors with advanced scripting skills.

The variable syntax is vaVars.myvar, where myvar is the name that you assign to the variable. For example, you can assign a value to the variable using vaVars.myvar = value;. Unlike user input variables, script variables can be assigned values in a script.

For information about defining a script variable in a topic, see Define script variables for a topic.

Table 2. vaVars methods
Method Description
vaVars.global_utterance Updates when skill picker renders and an utterance is typed in.

Context variables

Context variables work in a global scope whereas system variables work within the scope of the topic. You can use context variables in system parameters within the chat widget URL. These variables can be used anywhere in the conversation using the vaContext object. Use these options to create links to Virtual Agent with predefined variables.

The following example link contains a parameter, sysparm_city=milan. In addition to opening a Virtual Agent conversation, using this link creates a variable called city with a value of milan. This variable can be accessed in a script using vaContext.city.

https://<instance>.service-now.com/$sn-va-web-client-app.do?sysparm_city=milan
A number of Live Agent variables are available for use in topic scripts. These variables include the following:
  • application
  • language
  • portal
  • search_text
  • short_description

The variable syntax is vaContext.LiveAgent_myvar, where myvar is one of the available live agent context variables. Access the variable using vaContext.LiveAgent_myvar = value;.

To use Live Agent variables in topic scripts, open the topic in Virtual Agent Designer. On the Properties tab, select the pencil icon next to Live Agent Variables to add them to the topic.

For information about live agent context variables that are included with Virtual Agent, see Live agent chat context variables.

vaSystem methods

You can use methods in the vaSystem object to do various tasks. Some of these tasks include the following:
  • Attach images to records.
  • Access the search string that was used to find the current topic.
  • Verify that a live agent is available to receive a conversation.
  • Connect the user to a live agent.
Note: The use of undocumented system methods is not recommended, as they are unsupported and may be discontinued or altered at any time without prior notice.
Table 3. Methods used in Virtual Agent topic scripts
Method Description
vaSystem.applyLinkTemplate(String sysId, String tableName, String actionName) Creates an external link that is specific to a portal.
vaSystem.attachRecordToConversation(String tableName, String sysId)

Attach ServiceNow records to the Related Tasks list in a Virtual Agent interaction record. These records are updated or created during a Virtual Agent conversation.
vaSystem.attachToRecord(String mediaId, String tableName, String sysId)
Attach an uploaded image to a ServiceNow record. The method uses the following parameters:
  • mediaId: The path for the image to be attached. To use an image entered by the customer, use getValue() on an image input variable. For example, vaInputs.image_input.getValue().
  • tableName: A string that contains the name of the table.
  • sysId: The sys_id of the record.
vaSystem.connectToAgent() Connects the customer to a live agent. For more information on this method, see Transferring Virtual Agent conversations to a live agent.
vaSystem.didConnectToLiveAgent() Returns a Boolean (true or false) value whether the current conversation was connected to a live agent.
vaSystem.getClosingMessage() Returns a closing message for a conversation from system property: com.glide.cs.general.closing_message. (The message is different for third-party messaging apps such as Microsoft Teams and Slack).
vaSystem.getConversationId() Returns the conversation ID of the current conversation.
vaSystem.getGreetingMessage() Returns a greeting message from UI Message with the key "Hi, I'm your Virtual Agent. Let me know how I can help you today."
vaSystem.getInteractionSysId() Returns the interaction ID of the current conversation.
vaSystem.getSearchText() Returns the last utterance typed by the user.
vaSystem.getTopicSelectionMessage() Returns a UI message with the key "What's your issue or request? Or take a look at what I can help with." (The message is different for third party messaging apps such as Microsoft Teams and Slack). This method is returned from the system property com.glide.cs.topic_picker_msg.
vaSystem.getTranscript() Gets the conversation transcript.
vaSystem.isLiveAgentAvailable() Checks whether a live agent is available to receive a conversation that is transferred from the bot. To transfer a conversation to a live agent, call this method before using vaSystem.connectToAgent().
vaSystem.isLiveAgentConfigured() Returns whether live chat is enabled.
vaSystem.resetAllEntities() Resets all entities logged in the conversation.
vaSystem.sendBatchedMessages() Immediately sends queued messages.
vaSystem.sendSeparatorMessage() Sends a separator message line and returns the closing message from getClosingMessage().
vaSystem.sendSystemMessage(String message, Boolean showAvatar) Sends a system message and returns greetings message from getGreetingMessage().
vaSystem.sendTopicPickerControl(String topicSelectionMessage, String topicPickerButtonLabel) Sends a topic picker control with associated values for the message and "Show me everything" button label.
vaSystem.sendSkillPickerControl(skillSelectionMessage, args)

Sends the skill picker control to the user.

The skillSelectionMessage is the message displayed before showing the picker.The args parameter allows additional configuration options:

  • hideSkillDetails hides the skill selection message. It defaults to false.
  • hidePromotedTopics hides promoted topics from the skill picker. It defaults to false.
  • hideShowMeEverything removes the "Show Me Everything" button from the skill picker. It defaults to false.
  • showNoSkillsConfigured displays a "No Skills Configured" message if there are no applicable skills. It defaults to false.
  • appendPromotedSkillsToMsg appends a bulleted list of promoted skills to the skill selection message. It defaults to true.
vaSystem.switchTopicByName() Enables the user to jump from the current conversation topic to the specified topic name. The X button is available, so that the user can end the conversation. After the topic ends, the user resumes the global topic. When the conversation ends, the user can select Click here to start a new conversation at the bottom of the chat window to restart the topic.
The optional resumeBehavior parameter specifies how the conversation flow resumes, as follows:
  • If resumeBehavior=resume, Virtual Agent resumes the calling topic.
  • If resumeBehavior=skip, Virtual Agent skips the calling topic.

If resumeBehavior is not specified, the default behavior for the instance is used.
vaSystem.switchTopicById(sysid) This method is the sysid of sys_cb_topic, and enables the user to jump from the current conversation topic to the specified topic ID. The X button is available, so that the user can end the conversation. After the topic ends, the user resumes the global topic. When the conversation ends, the user can select Click here to start a new conversation at the bottom of the chat window to restart the topic.
The optional resumeBehavior parameter specifies how the conversation flow resumes, as follows:
  • If resumeBehavior=resume, Virtual Agent resumes the calling topic.
  • If resumeBehavior=skip, Virtual Agent skips the calling topic.

If resumeBehavior is not specified, the default behavior for the instance is used.
vaSystem.topicDiscovery(String searchTextOverride, Boolean keywordImpl) Performs topic discovery based on term in the searchTextOverride parameter. The method uses the following parameters:
  • searchTextOverride: A string on which to run topic discovery.
  • keywordImpl: A Boolean that determines whether to use keywords.
Table 4. Method that can be used outside Virtual Agent topics
Method Description
sn_cs.VASystemObject.getTranscriptById(<conversation sysId>)

Gets the transcript for the current Virtual Agent conversation.