Build a reusable component that performs a specific subflow of tasks and conversational elements in Virtual Agent conversations.

Before you begin

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

Role required: virtual_agent_admin or admin

About this task

Use topic blocks to run common steps, such as retrieving certain records.

Procedure

  1. Navigate to All > Conversational Interfaces > Virtual Agent > Designer.
  2. In the Topics page, do one of the following:
    • To create a topic block from scratch, select + Create.
    • To create a topic block based on a pre-built topic block, open the topic block and do the following:
      1. In the header bar, click Duplicate.
      2. Enter the name of the new block and click Save.
  3. On the sheet, fill in the fields.
    Table 1. Topic Block Properties sheet
    Field Description
    Type

    List of items that you can create in Virtual Agent Designer.

    Select Topic Block and define the additional properties.
    Note: Once you set this topic as a topic block, you cannot change it to a regular topic.
    Name Unique name for the topic block that reflects its functional purpose. This name appears in the list of topic blocks that topic authors can choose from when creating or updating a topic.
    Description Brief explanation of the purpose of the topic block. For example, to retrieve records.
    Advanced properties (optional)
    Who can access this topic
    Channels

    Chat clients in which the topic or topic block will run.

    These channels are different from the default channels that are natively supported by Virtual Agent. Your instance may have additional channels for custom chat integrations created for it. For more information about channels, see Deploying Virtual Agent topics in other channels.
    Live agent
    Live agent context variables Live agent context variables that are defined in the General Chat Settings.

    Select the variables that provide dynamic context, which means information from the Virtual Agent chat. This information is transferred from the bot conversation to the live agent.

    For information about the default list of live agent variables, see Live agent chat context variables.
    Available for Agent Autopilot Toggle switch that determines whether the topic block is available to a live agent.

    When enabled, an agent can search for the topic and invoke the topic. For details, see Conversation Autopilot.
    Available on the palette
    Enable Toggle switch that determines whether the topic block appears as its own icon in the Utilities section of the palette on the Flow tab. This provides easy access to the topic block for other authors.
    Additional
    Categories Category that contains this block. You can define custom topic categories for your topic blocks.
  4. Click Create.
    The Flow tab opens. The canvas displays a flow with a Start and End node.
  5. To define an input to the block, do the following:
    1. Click the Start node in the canvas.
    2. In the Start Segment Properties sheet, click + Add
    3. On the sheet, fill in the fields.
      Table 2. Add input dialog box
      FieldDescription
      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:

      Input variable mapping tooltip in this example displaying "Test Hint String."
      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.
      For example, the pre-built Contextual Search topic block provides the following input parameters:

      Input parameters for the Contextual Search topic block include context, query, portal, and kb_knowledge_base.

    4. Click Save.
    The calling topic or topic block passes input parameters to the topic block.
  6. Drag Virtual Agent Designer controls onto the canvas.
    These controls include the input, bot responses, and utilities. Use them in combination to define the logic that is run in the topic block.
  7. To define the output returned from the topic block, do the following:
    1. Click the End node in the canvas.
    2. In the End Segment Properties sheet, click + Add New.
    3. On the sheet, fill in the following fields.
      • Name: Name of the value returned from the topic block.
      • Value: Either a string with variables or a script that can be used within the calling topic. The Value is presented as data pills for the input variables that you defined (the Default Value specified in the Input Parameters and the input values from the node in the topic block).
      For example, the pre-built Contextual Search topic block passes the following output parameters:

      Output parameters for the Contextual Search topic block include Results returned and Results Helpful.

    4. Click Save.
    When the topic block finishes running in the calling topic, it can pass output variables to the calling topic.
  8. To see how the topic block runs, click Test.
    For example, the Contextual Search topic block returned the following results, including a preview-only message with the output values. The preview message helps you verify expected outputs and is not viewable to your users.

    The preview window displays the chat conversation and a preview only section that shows the output variables and their values. For example, "results_helpful":true.

  9. If you're ready to make the topic block available for use in calling topics, then do the following:
    1. Remove the default parameters that you used for testing.
    2. Click Save, and then click Publish.
    The topic block state changes to Active and is ready for use in calling topics.

What to do next

Add a reusable topic block to a calling topic or topic block.