Create a Virtual Agent custom control

Build a custom input or response control that topic authors can use in topics or topic blocks. In Virtual Agent conversations, an input control gathers information from end users, while a response control displays information to end users.

Before you begin

Create the custom control definition.

Important:

To implement secure (password2) inputs in your Virtual Agent custom control, you must adhere to the scoped application requirements in Workflow Studio. For details, see Workflow Studio scoped application requirements for secure inputs.

Tip:

Developers and topic authors may need to access custom controls created in other application scopes. To give them access, see Configure cross-scope access privileges for topic blocks and custom controls.

Role required: virtual_agent_admin or admin

Procedure

1. Navigate to All > Conversational Interfaces > Virtual Agent > Designer.
2. On the home page, select Create.
3. On the form, fill in the fields.

   Table 1. Properties form

   Field	Description
   Type	List of assets that you can create in Virtual Agent Designer. Choose the type of custom control: Custom Input Control Custom Response Control
   Name	Unique name for the custom control that reflects its purpose.
   Description	Brief explanation of the purpose and functionality of the control.
   Advanced properties (optional)
   Make inputs secure [Custom input controls only]
   Enable	Toggle switch that lets a custom input control pass secure inputs, such as passwords.
   Available on the palette
   Enable	Toggle switch that determines whether the custom control appears as its own icon in the Utilities section of the palette on the Flow tab. This provides easy access to the control for other authors.
   Additional
   Categories	List of categories. Categories identify and group related topics, topic blocks, or custom controls. If applicable, choose a category for your control.

4. Select Create.
   The Flow tab opens and displays an initial flow that contains a custom control node.
5. Select the Start node and define the input parameters to the control.
   Topic authors will provide these input parameters and values from the calling topic.
   1. Select + Add.
   2. On the form, fill in the fields.

      Table 2. Add input dialog box

      Field	Description
      Name	Name of the input variable that stores the input value.
      Type	Type of data being passed to the topic block. For example, String, Boolean, and so on. The fields change according to your choice. For more information, see Input data types in Virtual Agent topics.
      Required	Option to set the parameter as required.
      Hint	Tooltip that is visible when authoring a calling topic. See the following example:
      Table	ServiceNow table that is used to query for input. This field is available only when Reference or Array.Reference is selected from the Type field.
      Max Number of Rows	Maximum number of rows that the topic block is allowed to define. This field is available only when Array is selected from the Type field.
      Default Value	Default value for the variable. This value can be used when previewing the block. Duplicate default values are not allowed for array data types.

   3. Select Save.
   4. Repeat these steps for additional parameters.
6. Select the End node and define the output parameters and values returned from the custom control.
   Topic authors can use the output value in the calling topic.
   1. Select + Add New.
   2. Enter the name and value of the parameter.
   3. Repeat these steps for additional parameters.
   4. Select Save.
7. Select the custom control node and complete the property sheet as follows:
   • For a custom input control, fill in the Custom input properties sheet.
   • For a secure custom input control, fill in the Secure custom input properties sheet.
   • For a custom response control, fill in the Custom output properties sheet.
8. To create the control, select Save and then Publish.

Result

If you selected Available on the palette in the Properties page, the Custom Control icon displays as its own icon in the Utilities section of the palette. The control is listed on the Topics page, and you can use the Type menu to show only custom controls.

What to do next

Add a custom control to a Virtual Agent topic or topic block.