{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":35462,"path":"now-intelligence/dashboard-url-parameter-delegation.md","title":"Dashboard URL parameter delegation","bundle":null,"doc_type":null,"release":"australia","body":"\n# Dashboard URL parameter delegation\n\nThe Delegate URL params property enables UIB pages containing dashboard components to control how URL parameter updates are handled. Doing so enables custom navigation logic for embedded or workspace scenarios.\n\n**Note:** This functionality requires the latest Platform Analytics experience application from the ServiceNow® Store.\n\nBy default, dashboard components automatically update the browser URL when users switch dashboards, change tabs, or toggle edit mode. This behavior works well for standard dashboard pages but may not suit all implementation scenarios.\n\nThe **Delegate URL params** property provides an alternative approach where the dashboard component dispatches events instead of directly updating URLs. This delegation mechanism allows parent pages to implement custom navigation logic.\n\nFor information about this property in the context of the Dashboard component configuration panel, see [Dashboard component properties](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/dashboard-component-properties-setup.md).\n\n## When to use URL parameter delegation\n\nURL parameter delegation is useful in these scenarios:\n\n-   The page URL structure does not include dashboard URL parameters — for example, no `sys-id` in the URL path\n-   The page requires custom navigation logic for dashboard changes\n-   The dashboard is embedded in a workspace where URL management is handled by the parent component\n-   Multiple dashboard components exist on the same page and need coordinated URL handling\n\n## How delegation works\n\nWhen **Delegate URL params** is disabled \\(default behavior\\):\n\n1.  User performs an action, such as switching the dashboard, changing the tab, or toggling edit mode\n2.  Dashboard component dispatches an internal `CONTENT_UPDATED` action\n3.  UIB framework processes the action and updates URL parameters automatically\n\nWhen **Delegate URL params** is enabled:\n\n1.  User performs an action\n2.  Dashboard component suppresses the `CONTENT_UPDATED` dispatch\n3.  Dashboard component dispatches `DASHBOARD#URL_PARAMS_UPDATE_REQUESTED` with structured parameter data\n4.  Client script on the page receives the event and implements custom navigation logic\n\n## Event payload structure\n\nThe `DASHBOARD#URL_PARAMS_UPDATE_REQUESTED` event contains a **urlParams** object with structured parameter information. Each parameter includes the value, description, and additional metadata such as dashboard names and new tab indicators.\n\nThis structured approach provides client scripts with sufficient context to make informed navigation decisions, including handling special cases like opening dashboards in new browser tabs.\n\nFor more information about this event, see [Dashboard component events](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/dashboard-component-events-setup.md).\n\n**Parent Topic:**[Creating Platform Analytics pages in your own workspace](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/now-intelligence/adding-analytics-center-to-ws.md)\n\n**Related topics**  \n\n\n[Create a Platform Analytics workspace from App Engine Studio]()\n\n[Add Platform Analytics pages to a configurable workspace]()\n\n[Add a dashboard to a Dashboards page]()\n\n[Configure custom redirection from a dashboard component]()\n\n[Pass global filters to the dashboard page template]()\n\n[Configure dashboard data broker]()\n\n## Configure dashboard URL parameter delegation\n\nEnable URL parameter delegation for dashboard components to implement custom navigation logic in UIB pages.\n\n### Before you begin\n\nRole required: ui\\_builder\\_admin\n\n### About this task\n\nConfigure URL parameter delegation when you need custom control over how dashboard navigation updates browser URLs. This is useful for embedded dashboards, workspace scenarios, or pages with non-standard URL structures.\n\n### Procedure\n\n1.  Navigate to the UIB page containing the dashboard component.\n\n2.  Select the dashboard component in the design canvas.\n\n3.  Open the **Configure** tab in the component properties panel.\n\n4.  Select the **Delegate URL params** check box.\n\n    When enabled, the dashboard component will dispatch `DASHBOARD#URL_PARAMS_UPDATE_REQUESTED` events instead of updating URLs directly.\n\n5.  Switch to the **Events** tab.\n\n6.  Select **Add event mapping**.\n\n7.  Select the **URL params update requested** event from the list.\n\n8.  Add an event handler that executes a client script.\n\n    The client script will receive the URL parameter data and implement your custom navigation logic.\n\n9.  Create a client script to handle the URL parameter updates.\n\n    The script receives a structured **urlParams** payload containing parameter values, descriptions, and metadata such as dashboard names and new tab indicators.\n\n    The dashboard component now delegates URL parameter handling to your custom client script instead of updating the browser URL directly.\n\n\n### Result\n\nWhen users interact with the dashboard \\(switch dashboards, change tabs, toggle edit mode\\), the component dispatches events that your client script can handle with custom navigation logic.\n\n### Basic delegation client script\n\nThis example script replicates the default URL update behavior:\n\n```javascript\nfunction handler({api, event}) {\n    const {urlParams} = event.payload;\n    \n    for (const [key, paramInfo] of Object.entries(urlParams)) {\n        if (key === 'sysId' && paramInfo.isNewTab === true) {\n            // Handle new tab navigation\n            api.emit('NAV_ITEM_SELECTED', {\n                route: 'dashboards',\n                title: paramInfo.dashboardName || paramInfo.value,\n                params: {sysId: paramInfo.value},\n                navigationOptions: {\n                    navigateExternal: true,\n                    target: '_blank'\n                }\n            });\n            return;\n        }\n        \n        // Handle normal navigation\n        api.emit('CONTENT_UPDATED', {\n            route: 'dashboards',\n            params: {[key]: paramInfo.value}\n        });\n    }\n}\n```\n\n"}}