{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":5325,"path":"conversational-interfaces/virtual-agent/virtual-agent-scripts.md","title":"Virtual Agent scripts","bundle":null,"doc_type":null,"release":"australia","body":"\n# Virtual Agent scripts\n\nUse 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.\n\nVirtual 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.\n\nScripts 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.\n\n## User input and ServiceNow record variables\n\nIn Virtual Agent, the following variables are available for use in scripts that you create for a topic.\n\n-   **User input variables**\n\n    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.\n\n    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.\n\n-   **ServiceNow record variables**\n\n    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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/scripts/c_UsingGlideRecordToQueryTables.md).\n\n    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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-user-interface/dot-walking-examples.md).\n\n-   **Accessing user input and ServiceNow record variables**\n\n    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()`.\n\n    The following methods are available.\n\n<table id=\"table_uht_pzs_cpb\"><thead><tr><th>\n\nMethod\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nvaInputs.myvar == \"expected value\"\n\n</td><td>\n\nEvaluates 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.\n\n -   The Australia release supports additional data types. For more information, see [Input data types in Virtual Agent topics](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/va-data-types.md).\n-   By default, the user variable is available and is a reference to the sys\\_user record for the user.\n\n\n</td></tr><tr><td>\n\nvaInputs.myvar.getValue\\(\\);\n\n</td><td>\n\nReturns the value.\n\n</td></tr><tr><td>\n\nvaInputs.myvar.getDisplayValue\\(\\);\n\n</td><td>\n\nReturns 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.\n\n 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.\n\n \\[Omitted image \"va-value-vs-display.ong.png\"\\] Alt text: Label fields include Apple, Orange, and Pear for the choices. The values for each are 10, 20, and 30.\n\n</td></tr><tr><td>\n\nvaInputs.myvar.getDefaultValue\\(\\);\n\n</td><td>\n\nReturns the default value in a confirmation message.\n\n</td></tr><tr><td>\n\nvaInputs.myvar.getDefaultDisplayValue\\(\\);\n\n</td><td>\n\nReturns the display value for the default value in a confirmation message.\n\n</td></tr><tr><td>\n\nvaInputs.myvar.unbindEntity\\(\\);\n\n</td><td>\n\nRemoves 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.\n\n **Note:** NLU must be enabled on the topic. In the Assistant Designer, select the **Properties** tab to set up NLU. For information about defining NLU entities, see [Entities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/intelligent-experiences/entities.md).\n\n</td></tr></tbody>\n</table>\n## Script variables\n\nYou 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 Assistant Designer.\n\n\\[Omitted image \"ScriptVariablesExample.png\"\\] Alt text: Sidebar in theAssistant Designer canvas for manually adding script variables that are used in topic scripts.\n\n**Note:** Script variables are intended for use by topic authors with advanced scripting skills.\n\nThe 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.\n\nFor information about defining a script variable in a topic, see [Define script variables for a topic](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/define-script-variables-topic.md).\n\n## Context variables\n\nContext 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 web client 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.\n\nThe 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`.\n\n```\nhttps://<instance>.service-now.com/$sn-va-web-client-app.do?sysparm_city=milan\n```\n\nA number of Live Agent variables are available for use in topic scripts. These variables include the following:\n\n-   *application*\n-   *language*\n-   *portal*\n-   *search\\_text*\n-   *short\\_description*\n\nThe variable syntax is `vaContext.LiveAgent_myvar`, where `myvar` is one of the available [live agent context variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/live-agent-chat-context-vars.md). Access the variable using `vaContext.LiveAgent_myvar = value;`.\n\nTo use Live Agent variables in topic scripts, open the topic in Assistant Designer. On the **Properties** tab, select the pencil icon next to **Live Agent Variables** to add them to the topic.\n\nFor information about live agent context variables that are included with Virtual Agent, see [Live agent chat context variables](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/live-agent-chat-context-vars.md).\n\n|Method|Description|\n|------|-----------|\n|vaVars.global\\_utterance|Updates when skill picker renders and an utterance is typed in.|\n\n## vaSystem methods\n\nYou can use methods in the vaSystem object to do various tasks. Some of these tasks include the following:\n\n-   Attach images to records.\n-   Access the search string that was used to find the current topic.\n-   Verify that a live agent is available to receive a conversation.\n-   Connect the user to a live agent.\n\n**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.\n\n<table id=\"table_xvn_c5r_h2b\"><thead><tr><th>\n\nMethod\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nvaSystem.applyLinkTemplate\\(String sysId, String tableName, String actionName\\)\n\n</td><td>\n\nCreates an external link that is specific to a portal.\n\n</td></tr><tr><td>\n\nvaSystem.attachRecordToConversation\\(String tableName, String sysId\\)\n\n</td><td>\n\nAttach ServiceNow records to the Related Tasks list in a Virtual Agent interaction record. These records are updated or created during a Virtual Agent conversation.\n\n</td></tr><tr><td>\n\nvaSystem.attachToRecord\\(String mediaId, String tableName, String sysId\\)\n\n</td><td>\n\nAttach an uploaded image to a ServiceNow record. The method uses the following parameters:\n\n-   `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()`.\n-   `tableName`: A string that contains the name of the table.\n-   `sysId`: The sys\\_id of the record.\n\n</td></tr><tr><td>\n\nvaSystem.connectToAgent\\(\\)\n\n</td><td>\n\nConnects the customer to a live agent. For more information on this method, see [Transferring Virtual Agent conversations to a live agent](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/transfer-to-live-agent.md).\n\n</td></tr><tr><td>\n\nvaSystem.didConnectToLiveAgent\\(\\)\n\n</td><td>\n\nReturns a Boolean \\(true or false\\) value whether the current conversation was connected to a live agent.\n\n</td></tr><tr><td>\n\nvaSystem.getClosingMessage\\(\\)\n\n</td><td>\n\nReturns 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\\).\n\n</td></tr><tr><td>\n\nvaSystem.getConversationId\\(\\)\n\n</td><td>\n\nReturns the conversation ID of the current conversation.\n\n</td></tr><tr><td>\n\nvaSystem.getGreetingMessage\\(\\)\n\n</td><td>\n\nReturns a greeting message from UI Message with the key \"Hi, I'm your Virtual Agent. Let me know how I can help you today.\"\n\n</td></tr><tr><td>\n\nvaSystem.getInteractionSysId\\(\\)\n\n</td><td>\n\nReturns the interaction ID of the current conversation.\n\n</td></tr><tr><td>\n\nvaSystem.getSearchText\\(\\)\n\n</td><td>\n\nReturns the last utterance typed by the user.\n\n</td></tr><tr><td>\n\nvaSystem.getTopicSelectionMessage\\(\\)\n\n</td><td>\n\nReturns 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**.\n\n</td></tr><tr><td>\n\nvaSystem.getTranscript\\(\\)\n\n</td><td>\n\nGets the conversation transcript.\n\n</td></tr><tr><td>\n\nvaSystem.isLiveAgentAvailable\\(\\)\n\n</td><td>\n\nChecks 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()`.\n\n</td></tr><tr><td>\n\nvaSystem.isLiveAgentConfigured\\(\\)\n\n</td><td>\n\nReturns whether live chat is enabled.\n\n</td></tr><tr><td>\n\nvaSystem.resetAllEntities\\(\\)\n\n</td><td>\n\nResets all entities logged in the conversation.\n\n</td></tr><tr><td>\n\nvaSystem.sendBatchedMessages\\(\\)\n\n</td><td>\n\nImmediately sends queued messages.\n\n</td></tr><tr><td>\n\nvaSystem.sendSeparatorMessage\\(\\)\n\n</td><td>\n\nSends a separator message line and returns the closing message from `getClosingMessage()`.\n\n</td></tr><tr><td>\n\nvaSystem.sendSystemMessage\\(String message, Boolean showAvatar\\)\n\n</td><td>\n\nSends a system message and returns greetings message from `getGreetingMessage()`.\n\n</td></tr><tr><td>\n\nvaSystem.sendTopicPickerControl\\(String topicSelectionMessage, String topicPickerButtonLabel\\)\n\n</td><td>\n\nSends a topic picker control with associated values for the message and \"Show me everything\" button label.\n\n</td></tr><tr><td>\n\nvaSystem.sendSkillPickerControl\\(skillSelectionMessage, args\\)\n\n</td><td>\n\nSends the skill picker control to the user.\n\n The `skillSelectionMessage` is the message displayed before showing the picker.The `args` parameter allows additional configuration options:\n\n -   `hideSkillDetails` hides the skill selection message. It defaults to `false`.\n-   `hidePromotedTopics` hides promoted topics from the skill picker. It defaults to `false`.\n-   `hideShowMeEverything` removes the \"Show Me Everything\" button from the skill picker. It defaults to `false`.\n-   `showNoSkillsConfigured` displays a \"No Skills Configured\" message if there are no applicable skills. It defaults to `false`.\n-   `appendPromotedSkillsToMsg` appends a bulleted list of promoted skills to the skill selection message. It defaults to `true`.\n\n</td></tr><tr><td>\n\nvaSystem.switchTopicByName\\(\\)\n\n</td><td>\n\nEnables 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:\n\n-   If **resumeBehavior=resume**, Virtual Agent resumes the calling topic.\n-   If **resumeBehavior=skip**, Virtual Agent skips the calling topic.\n\n If **resumeBehavior** is not specified, the default behavior for the instance is used.\n\n</td></tr><tr><td>\n\nvaSystem.switchTopicById\\(sysid\\)\n\n</td><td>\n\nThis 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:\n\n-   If **resumeBehavior=resume**, Virtual Agent resumes the calling topic.\n-   If **resumeBehavior=skip**, Virtual Agent skips the calling topic.\n\n If **resumeBehavior** is not specified, the default behavior for the instance is used.\n\n</td></tr><tr><td>\n\nvaSystem.topicDiscovery\\(String searchTextOverride, Boolean keywordImpl\\)\n\n</td><td>\n\nPerforms topic discovery based on term in the **searchTextOverride** parameter. The method uses the following parameters:-   `searchTextOverride`: A string on which to run topic discovery.\n-   `keywordImpl`: A Boolean that determines whether to use keywords.\n\n</td></tr></tbody>\n</table><table id=\"table_mqd_wqp_1jb\"><thead><tr><th>\n\nMethod\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsn\\_cs.VASystemObject.getTranscriptById\\(&lt;conversation sysId&gt;\\)\n\n</td><td>\n\nGets the transcript for the current Virtual Agent conversation.\n\n</td></tr></tbody>\n</table>**Parent Topic:**[Virtual Agent technical reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/va-advanced-technical-reference.md)\n\n**Related topics**  \n\n\n[Domain separation and Virtual Agent]()\n\n[Virtual Agent interaction records]()\n\n[Input data types in Virtual Agent topics]()\n\n[NLU system entities]()\n\n[Virtual Agent URL parameters]()\n\n[Latency feedback in Virtual Agent]()\n\n"}}