{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":6655,"path":"customer-service-management/customize-ra-preview-experience.md","title":"Customize a guidance preview experience in the UI Builder","bundle":null,"doc_type":null,"release":"australia","body":"\n# Customize a guidance preview experience in the UI Builder\n\nCustomize 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.\n\n## Before you begin\n\nRole required: sn\\_nb\\_action.next\\_best\\_action\\_author and ui\\_builder\\_admin, admin\n\n## About this task\n\nYou 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.\n\n## Procedure\n\n1. Navigate to **All** > **Recommended Actions** > **Action Types** > **Guidances**.\n\n2. Select a guidance from the Guidances list.\n\n3. Select **Create preview UI** to create a UI page variant of a guidance preview experience.\n\n This page includes an empty `customExpProps` container with the properties listed in the following table during run-time. The Recommended Actions framework passes the `customExpProps` object as a property to the custom experience.\n\n |Property|Description|\n |--------|-----------|\n |sysId|ID of the recommendation.|\n |name|Title of the preview experience.|\n |description|Message for the preview experience.|\n |recommendationHint|Text that tells the agent why a recommendation is being suggested.|\n |callToActions|Settings for the guidance action.|\n |actionTypeLabel|Label for the recommended action type.|\n |icon|Icon for the recommendation card.|\n |actionStateLabel|External name of the action state.|\n |actionStateValue|Internal name of the action state.|\n |previewFields|The fields to display in the guidance preview experience.|\n |errorMessage|Error message to display when the recommendation fails to display.|\n |ariaHidden|On the Recommended Actions grouped list, the sn-carousel component passes this property to each card to determine if the content is hidden within the carousel. If the card is hidden, you can use this value to set aria-hidden or disable any actionable component to true and avoid accessibility issues.|\n |useCase|Search/RA tab where the guidance is getting rendered.|\n |actionInputs|Guidance Inputs.|\n |actionTypeSysId|Sys Id of the recommendation type.|\n |actionId|Sys Id of the recommendation.|\n |table|Recommended Actions Context table.|\n |tableSysId|Recommended Actions Context table record sys\\_id.|\n |renderer|Component responsible to render the detailed experience|\n |secondaryCallToAction|Secondary actions to be shown on card.|\n |isGenius|Is genius result card, used in Search tab genius result.|\n |contextSysId|Recommended Actions context sysId.|\n |actionConfigurations|Recommended Actions actionConfigurations property value. The Value field is empty by default.|\n |isFullSearchView|If search displayed in full search view of side panel view, the value is true.|\n |contextInputs|Recommended Actions contextInput property value. To get the predefined syntax, navigate to **All >** > **Recommended Actions** > **Context** > **Context Inputs** and copy the JSON format of the context inputs.|\n |Search relevancy score|Relevancy score of a search result which displays on the on the guidance card when the use case is `search` but not suggested actions. If the value is null or undefined, the relevancy score component is hidden on the guidance card.|\n\n The following example shows properties and sample values for the preview experience.\n\n ```\n \"customExpProps\": {\n \"sysId\": \"e8421a2a436f0210f81d92621ab8f2da\",\n \"name\": \"Attach and share article\",\n \"description\": null,\n \"recommendationHint\": \"Knowledge\",\n \"callToActions\": [\n {\n \"label\": \"\",\n \"name\": \"\",\n \"id\": \"1e8392aa436f0210f81d92621ab8f291\",\n \"actionBehavior\": \"contextual_side_panel\",\n \"primary\": \"true\",\n \"order\": \"100\",\n \"completionMessage\": \"Knowledge article successfully attached.\"\n }\n ],\n \"recommendationAction\": \"\",\n \"actionTypeLabel\": \"Guidance\",\n \"icon\": \"magnifying-glass-sparkle-outline\",\n \"actionStateLabel\": \"New\",\n \"actionStateValue\": \"new\",\n \"previewFields\": null,\n \"attributes\": \"\",\n \"errorMessage\": \"\",\n \"ariaHidden\": false,\n \"useCase\": \"search\",\n \"actionInputs\": {},\n \"actionTypeSysId\": \"\",\n \"actionId\": \"\",\n \"table\": \"sn_customerservice_case\",\n \"tableSysId\": \"\",\n \"renderer\": \"sn-guidance-experience-connected\",\n \"secondaryCallToAction\": {},\n \"isGenius\": false,\n \"contextSysId\": \"\",\n \"actionConfigurations\": {},\n \"isFullSearchView\": false\n }\n \n ```\n\n4. Select **Edit preview in UI Builder**.\n\n 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/work-components.md).\n\n5. Bind the preview experience properties to your preview UI.\n\n Data bindings are in the **Config** tab of the configuration panel in UI Builder. For more information, see [Data resources in UI Builder](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/data-resources.md).\n\n6. 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.\n\n The following table shows the list of events that are emitted with respect to the actions perform by an agent:\n\n\n
\n\nEvents handled\n\n\n\nDescription\n\n
\n\nON\\_SINGLE\\_CLICK\\_ACTION\\_INITIATE\n\n\n\nInitiates and completes the action when an agent selects the action button. This event passes the following parameters in the payload:```\napi.emit( \n ‘ON_SINGLE_CLICK_ACTION_INITIATE‘, { \n sysId: api.context.props.customExpProps.sysId, \n \n name: api.context.props.customExpProps.name, \n \n actionStateValue: api.context.props.customExpProps.actionStateValue, \n actionMetadata: api.context.props.customExpProps.callToActions[0] ,\n table: api.context.props.customExpProps.table,\n tableSysId: api.context.props.customExpProps.tableSysId,\n contextSysId: api.context.props.customExpProps.contextSysId,\n actionType: api.context.props.customExpProps.actionTypeSysId,\n actionInputs: api.context.props.customExpProps.actionInputs,\n formFieldInputs: { : },\n actionId: api.context.props.customExpProps.actionId,\n name: api.context.props.customExpProps.name,\n actionMetadata: api.context.props.customExpProps.callToActions[0],\n actionStateValue: api.context.props.customExpProps.actionStateValue,\n }\n)\n\n```\n\nThe `formFieldInputs` contains the `actionInputs`, which must be updated when the event is emitted.\n\n
\n\nON\\_DRILL\\_DOWN\\_ACTION\\_INITIATE\n\n\n\nExpands 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:```\napi.emit( \n ‘ON_DRILL_DOWN_ACTION_INITIATE ‘, { \n table: api.context.props.customExpProps.table,\n tableSysId: api.context.props.customExpProps.tableSysId,\n actionType: ,\n actionInputs: api.context.props.customExpProps.actionInputs,\n formFieldInputs: {\"\":\"\"},\n actionId: api.context.props.customExpProps.actionId,\n sysId: api.context.props.customExpProps.sysId,\n name: api.context.props.customExpProps.name,\n actionStateValue: api.context.props.customExpProps.actionStateValue,\n actionMetadata: api.context.props.customExpProps.callToActions[0],\n renderer: api.context.props.customExpProps.renderer,\n contextSysId: api.context.props.customExpProps.contextSysId,\n sysId: api.context.props.customExpProps.sysId, \n name: api.context.props.customExpProps.name }\n\n)\n\n```\n\n
\n\nDISMISS\\_ACTION\\_CLICK\n\n\n\nCancels the action.```\napi.emit( \n ‘DISMISS_ACTION_CLICK‘, { \n sysId: api.context.props.customExpProps.sysId\n }\n)\n```\n\n
\n\nACTION\\_TRIGGERED\\_PROPAGATION\n\n\n\nEnables user to add UI-specific behavior for guidance actions. This event propagates the payload details to the parent where this event can be handled.```\napi.emit(\n ‘SN_NEXT_BEST_ACTION_LIST_CONNECTED#ACTION_TRIGGERED_PROPAGATION' ‘, {\n \"actionSysId\": api.context.props.customExpProps.actionId\n \"actionName\": api.context.props.customExpProps.actionConfigurations[api.context.props.customExpProps.actionId ][“actionName”]\n \"actionType\": \"guidance\",\n \"eventName\": \"\",\n \"payload\": {\n }\n}\n\n```\n\n
\n\nLOG\\_SEARCH\\_RESULT\\_EVENT\n\n\n\nAdds the search result logs to the Queued Signal Events \\[sys\\_signal\\_event\\_queue\\] table.```\napi.emit(LOG_SEARCH_RESULT_EVENT, {actionData: {actionName: actionId}})\n```\n\n
For more information, see [Define and bind client scripts to components](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/define-client-scripts.md).\n\n\n"}}