Customize a guidance preview experience in the UI Builder

  • Release version: Washingtondc
  • Updated January 30, 2025
  • 2 minutes to read

    • Customize a preview of a Recommended Actions card that displays in the contextual side panel using UI Builder. The preview experience includes a hint, an icon, a message, and an action button.

    Before you begin

    Role required: sn_nb_action.next_best_action_author and ui_builder_admin, admin

    About this task

    You begin by creating a UI page variant of a guidance preview experience. When you create a UI page variant from a page template, you start with a base structure that you can customize. By using the component properties, you can change how your recommendation card preview looks.

    Procedure

    1. Navigate to All > Recommended Actions > Action Types > Guidances.
    2. Select a guidance from the Guidances list.
    3. Select Create preview UI to create a UI page variant of a guidance preview experience.

      This page includes an empty container with the properties listed in the following table. The Recommended Actions framework passes the customExpProps object as a property to the custom experience.

      Table 1. Preview experience properties
      Property Description
      sysId ID of the recommendation.
      name Title of the preview experience.
      description Message for the preview experience.
      recommendationHint Text that tells the agent why a recommendation is being suggested.
      callToActions Settings for the guidance action.
      actionTypeLabel Label for the recommended action type.
      icon Icon for the recommendation card.
      actionStateLabel External name of the action state.
      actionStateValue Internal name of the action state.
      previewFields The fields to display in the guidance preview experience.
      errorMessage Error message to display when the recommendation fails to display.

      The following example shows properties and sample values for the preview experience.

      "customExpProps": {
        "sysId": "e8421a2a436f0210f81d92621ab8f2da",
        "name": "Attach and share article",
        "description": null,
        "recommendationHint": "Knowledge",
        "callToActions": [
            {
                "label": "",
                "name": "",
                "id": "1e8392aa436f0210f81d92621ab8f291",
                "actionBehavior": "contextual_side_panel",
                "primary": "true",
                "order": "100",
                "completionMessage": "Knowledge article successfully attached."
            }
        ],
        "recommendationAction": "",
        "actionTypeLabel": "Guidance",
        "icon": "magnifying-glass-sparkle-outline",
        "actionStateLabel": "New",
        "actionStateValue": "new",
        "previewFields": null,
        "attributes": "",
        "errorMessage": "",
        "ariaHidden": false,
        "useCase": "search",
        "actionInputs": {},
        "actionTypeSysId": "",
        "actionId": "",
        "table": "sn_customerservice_case",
        "tableSysId": "",
        "renderer": "sn-guidance-experience-connected",
        "secondaryCallToAction": {},
        "isGenius": false,
        "contextSysId": "",
        "actionConfigurations": {},
        "isFullSearchView": false
    }
    4. Select Edit preview in UI Builder.
      The UI page variant opens in UI Builder, where you can add and configure components to customize the look and feel of the preview experience. For more information, see Working with components in the UI Builder.
    5. Bind the preview experience properties to your preview UI.
      Data bindings are in the Config tab of the configuration panel in UI Builder. For more information, see Data resources in UI Builder.
    6. Add and bind scripts to components in your preview UI to dispatch events by using an event handler to execute or skip a recommendation with a corresponding payload.
      Table 2. Preview experience events
      Events handled Description
      ON_SINGLE_CLICK_ACTION Initiates and completes the action when an agent selects the action button. This event passes the following parameters in the payload:
      api.emit( 
    ‘ON_SINGLE_CLICK_ACTION‘, { 
        sysId: api.context.props.customExpProps.sysId, 
        name: api.context.props.customExpProps.name, 
        actionStateValue: api.context.props.customExpProps.actionStateValue, 
        actionMetadata: api.context.props.customExpProps.callToActions[0] 
    }
)
      ON_DRILL_DOWN_ACTION Expands the action and displays more actions or information after an agent selects the primary action button. This event passes the following parameters in the payload:
      api.emit( 
    ‘ON_DRILL_DOWN_ACTION‘, { 
        sysId: api.context.props.customExpProps.sysId, 
        name: api.context.props.customExpProps.name, 
        actionStateValue: api.context.props.customExpProps.actionStateValue, 
        actionMetadata: api.context.props.customExpProps.callToActions[0] 
     }
)
      DISMISS_ACTION_CLICK Cancels the action.
      api.emit( 
    ‘DISMISS_ACTION_CLICK‘, { 
         sysId: api.context.props.customExpProps.sysId
    }
)
      ACTION_TRIGGERED_PROPAGATION Enables user to add UI-specific behavior for guidance actions. This event propagates the payload details to the parent where this event can be handled.
      api.emit(
    ‘SN_NEXT_BEST_ACTION_LIST_CONNECTED#ACTION_TRIGGERED_PROPAGATION' ‘, {
   "actionSysId": api.context.props.customExpProps.actionId
   "actionName": api.context.props.customExpProps.actionConfigurations[api.context.props.customExpProps.actionId ][“actionName”]
   "actionType": "guidance",
   "eventName": "<eventName>",
   "payload": {
   }
}

      For more information, see Define and bind client scripts to components.