Customize a guidance detail experience in the UI Builder

  • Release version: Australia
  • Updated March 12, 2026
  • 2 minutes to read

    • Customize how your detail experience looks in the contextual side panel or in a subtab of the Recommended Actions card using UI Builder. The detail experience can include things such as user inputs and drill down actions.

    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 detail experience. When you create a UI page variant from a page template, you start with a base structure that you can customize. By configuring the components and using the component properties, you can change how your detail experience looks in the contextual side panel or in a subtab.

    Procedure

    1. Navigate to All > Recommended Actions > Action Types > Guidances.
    2. Select a guidance from the Guidances list.
    3. Select Create detail UI to create a UI page variant of a guidance detail experience.
      This page includes an empty container with the properties listed in the following table.
      Table 1. Detail experience properties
      Property Description
      guidanceInputs The inputs required to perform the guidance.
      guidanceOutputs The outputs of the guidance.
      status The status of the guidance.
      guidanceMessage The message for the detail experience.
      guidanceActions The guidance actions in the detail view.
      errorMessages The error message to display when the recommendation fails to display.

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

      {
    "guidanceInputs": {},
    "guidanceOutputs": {
        "meta": []
    },
    "status": "waiting",
    "guidanceMessage": "",
    "guidanceActions": [
        {
            "label": "Attach",
            "action_sys_id": "1e8392aa436f0210f81d92621ab8f291",
            "variant": "primary",
            "isExecuted": false,
            "completionMessage": "Knowledge article successfully attached.",
            "action_behaviour": "contextual_side_panel",
            "primary": true
        }
    ],
    "errorMessage": "",
    "actionConfigurations": {},
    "guidanceId": "",
    "tableName": "sn_customerservice_case",
    "bare": true,
    "scrollable": "none"
}
    4. Select Edit detail 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 detail experience. For more information, see Working with components in the UI Builder.
    5. Bind the preview experience properties to your custom detail UI.
      Data bindings are located 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 custom detail UI to dispatch events by using an event handler to execute, skip, or mark complete a recommendation with a corresponding payload.
      Table 2. Detail experience events
      Events handled Description
      GUIDANCE_ACTION_CLICKED The action that is selected. This event passes the action selected to the payload.
      api.emit( 
  ‘GUIDANCE_ACTION_CLICKED’,{ 
        model: {
               fields: [{'name': 'input',
               'value':  '100'}]
               },
        action: api.context.props.guidanceActions.find(action => action.label == "guidance action label"); 
    } 
);
      Note:
      In the guidanceActions[n] property in the response, provide the index number of the action that you want to apply.
      SKIP_GUIDANCE Skips the guidance.
      api.emit(
   ‘SKIP_GUIDANCE’
);
      GUIDANCE_MESSAGE_PUBLISHED Passes data to an upstream application.
      api.emit( 
  ‘SN_GUIDANCE_EXPERIENCE_CONNECTED#GUIDANCE_MESSAGE_PUBLISHED’,
    { 
     name:'decision-tree-payload'
     jsonPayload: jsonObject
    } 
);
      GUIDANCE_MARK_COMPLETE Marks a custom guidance as completed.
      api.emit(
  'GUIDANCE_MARK_COMPLETE'
);
      GO_BACK_GUIDANCE Goes back to the previous node in a decision tree.
      api.emit(
   ‘GO_BACK_GUIDANCE’
);
      ACTION_TRIGGERED_PROPAGATION Enables you 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‘, {
   "actionSysId":api.context.props.guidanceId,
   "actionName": api.context.props.actionConfigurations[api.context.props.guidanceId][“actionName”]
   "actionType": "guidance",
   "eventName": "<eventName>",
   "payload": {}

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