Embed a KPI Dashboard

Embedding a KPI dashboard creates a version of the KPI dashboard minus platform functions for use in your own product.

  • If you are a Growth or Enterprise customer, embedding Analytical Designer (insights) and KPI Dashboards will remove all the GoodData branding.
  • If you are a Free customer, the following Powered by GoodData logo will be displayed on embedded tools.


    Note: Clicking the logo redirects you to either the GoodData product documentation (Administrators) or the GoodData website (other roles). See User Roles.

Contents:

Embed a KPI Dashboard

Steps:

  1. Create a URL for the embedded KPI dashboard:
    1. Log in to the GoodData Portal.
    2. Click the KPIs tab.
    3. From the list of KPI dashboards, select the KPI dashboard that you want to embed.

    4. Check the URL in the browser address bar. For example:

      https://secure.gooddata.com/dashboards/#/project/{project_id}/dashboard/{dashboard_identifier}/
    5. Add the string /embedded/ into the URL after /dashboards. For example:

       https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}/

      By default, you would have the dashboard identifier and the project ID in your URL. However, there are other ways to construct the embedding URL.

      • If you store the dashboard ID, you can use it instead of the dashboard identifier:

        https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboardId/{dashboard_id}/
      • If you use LCM (see Managing Projects via Life Cycle Management), use the combination of the data product ID and client ID instead of the project ID:

        https://secure.gooddata.com/dashboards/embedded/#/product/{data_product_id}/client/{client_id}/dashboard/{dashboard_identifier}
      For more details about formats of the embedded URL, see Embedding Code Formats.
    6. If you want the navigation panel listing KPI dashboards to be visible (by default, it is hidden), add the showNavigation parameter to the URL and set to true:

      https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}?showNavigation=true
    7. (Only when you have tags assigned to attributes, measures, or date datasets) If you want to configure hiding and displaying attributes, measures, or dates based on tags, add either of the following parameters to the URL:

      ?includeObjectsWithTags=[tag_name] - to show only the attributes, measures, and dates with the specified tag
      ?excludeObjectsWithTags=[tag_name] - to hide the attributes, measures, and dates with the specified tag

      https://secure.gooddata.com/dashboards/embedded/#/project/{project_ID}/dashboard/{dashboard_identifier}?includeObjectsWithTags=[sales]
      
      https://secure.gooddata.com/dashboards/embedded/#/project/{project_ID}/dashboard/{dashboard_identifier}?excludeObjectsWithTags=[marketing,hr]
      
      https://secure.gooddata.com/dashboards/embedded/#/project/{project_ID}/dashboard/{dashboard_identifier}?excludeObjectsWithTags=[finance]&showNavigation=true

      Do not specify both the parameters at the same time. If you do, only the includeObjectsWithTags parameter is applied, and the excludeObjectsWithTags parameter is ignored. You can specify more than one tag by separating them with a comma. The tags must include only lowercase characters, uppercase characters, and numbers.

      Hiding and displaying attributes, measures, and dates is not a security feature. Attributes, measures, and dates are hidden and shown depending on the parameter in the URL, and anyone who can access and edit the URL can change the parameters and display all the attributes, measures, and dates.

      For more information about adding tags to attributes, measures, facts, or date datasets, see: 

      When you are done with creating the URL, you can use this URL as the basis for embedding the KPI dashboard.

    8. If you want to hide the filter bar, add the ?hideControl=[filterBar] parameter to the URL.
      You can hide the filter bar in both the view and edit modes.

      https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}?hideControl=[filterBar] 

      To hide multiple parameters, separate them with a comma: ?hideControl=[filterBar,widgetsCatalogue]

    9. If you want to hide the list of insights and other items that you can add to a dahboard, ?hideControl=[widgetsCatalogue] parameter to the URL.
      You can hide the filter bar in both the view and edit modes.

      https://secure.gooddata.com/dashboards/embedded/#/project/{project_id/dashboard/{dashboard_identifier}?hideControl=[widgetsCatalogue]
    10. If you want to hide the top bar, add the ?hideControl=[topBar] parameter to the URL.
      You can hide the filter bar in both the view and edit modes.

      https://secure.gooddata.com/dashboards/embedded/#/project/{project_id/dashboard/{dashboard_identifier}?hideControl=[topBar]
  2. Include the embedded dashboard in your page.
    The following is an example reference using the project ID in your URL:

    <iframe src="https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}/" frameborder="0" id="frame"></iframe>

    If you are using an Apple mobile device for viewing a large embedded KPI dashboard, the table headers may not stick to the top of the visible area and therefore scroll up with the rest of the content.

    To prevent this, do the following:

    1. Set a static height for the iframe.
    2. Use the setHeight parameter in your source URL and set it to the same number as the height of the iframe.

    Your reference for including the embedded dashboard should look like the following (a height of 500 px is used in this example):

    <iframe src="https://secure.gooddata.com/dashboards/embedded/#/project/{project_id}/dashboard/{dashboard_identifier}?setHeight=500"
    height="500px" frameborder="0" id="frame"></iframe>

  3. (Only when you are using scrolling=no in the URL) Make sure that the iframe is resized according to its content so it is handled by JavaScript:

    <script> 
    window.addEventListener('message',function(event) {
    		switch(event.data.gdc.event.name) {
    			case 'resized':			
    				var height = event.data.gdc.event.data.height;
    			
    				if (height) { 
    					document.getElementById('frame').style.height = height + 'px'; 
    				}	
    				break;
    		}
    	},false);
    </script>
  4. (Optional) If you want to hide the Drill into dashboard section from the embedded KPI dashboard so that users of this KPI dashboard cannot see it, contact GoodData Support.
  5. (Optional) Select which events become drillable.
    For details, see Setting up Events for Drilling in Embedded Analytical Designer and KPI Dashboards.

Embedding Limitations

  • Editing embedded KPI dashboards requires at least 1170 px of horizontal space for the embedded component. When less space is available, the Edit button and all controls for saving in edit mode are not displayed.

  • When a user adds an alert to a KPI, the email notification that is generated when the KPI value meets the alert parameters may or may not contain a link to the KPI dashboard. Whether the link is or is not in the notification depends on the user's access to the GoodData Portal:
    • If the user does not have access to the GoodData Portal, the email notification will not contain a link to the KPI dashboard.
    • If the user has access to the GoodData Portal, the email notification will contain a link to the KPI dashboard. If you want to hide this link for the users with access to the GoodData Portal, contact GoodData Support.
  • If you are using scrolling=no in the URL, table headers become not sticky: they will behave as any other part of the dashboard and will not stick to the top of the visible area to ease reading tables.
  • The layout of the KPIs and insights on an embedded KPI dashboard (that is, how many KPIs and insights are placed in one row and spacing between them) depends on the size of horizontal space where the dashboard is embedded. Resizing the frame of the embedded dashboard changes the layout automatically in a predefined way, which cannot be adjusted manually.
  • If the KPI dashboard cannot be found within the project, GoodData displays the last opened KPI dashboard from the same project. Any parameters specified in the URL are disregarded.
  • If the project cannot be found, GoodData displays your last opened project. Any parameters specified in the URL are disregarded.

Communication with the Embedded KPI Dashboard

You can set up receiving messages from the embedded KPI dashboard to your application.

The messages are sent in the following format:

{
  "gdc": {
    "product": "dashboard",
    "event": {
      "name": "{event_name}",
      "data": {
        "{parameter_1_name}": "{parameter_1_value}",
        "{parameter_2_name}": "{parameter_2_value}"
      }
    }
  }
}

The following events are supported:

EventEvent trigger
loadingStartedThe embedded content starts loading.
loadedThe content is fully loaded, and the user has permissions to access the dashboard.
noPermissions

The user does not have permissions to view or edit the content. The 'data' section contains information about whether view or edit permissions are missing:

"data": {
  "reason": "viewDenied|editDenied"
}
 resized

An operation increasing the height of the hosting iframe is performed. The 'data' section contains information what hight the iframe needs (in pixels):

"data": {
  "height": {height_in_px}
}
dashboardCreated

A dashboard has been created and saved. The 'data' section contains, among other information, the dashboard ID. You can store it on your side and use later for managing multiple dashboards for this particular user.

"data": {
  "project": "{project_id}",
  "client": "{client_id}",
  "dashboard": "{dashboard_identifier}",
  "dashboardId": "{dashboard_id}"
}
dashboardCreationCanceledThe user cancels the creation of the dashboard.
dashboardUpdated

The existing dashboard has been updated. The 'data' section contains, among other information, the dashboard ID. You can store it on your side and use later for managing multiple dashboards for this particular user.

"data": {
  "project": "{project_id}",
  "client": "{client_id}",
  "dashboard": "{dashboard_identifier}",
  "dashboardId": "{dashboard_id}"
}
dashboardDeleted

The dashboard has been deleted. The 'data' section contains information about the deleted dashboard:

"data": {
  "project": "{project_id}",
  "client": "{client_id}",
  "dashboard": "{dashboard_identifier}",
  "dashboardId": "{dashboard_id}"
}
platform

The GoodData platform is temporary unavailable:

"data": {
  "status": "maintenance|upgrade|error"
}

For the status of 'error', the 'data' section contains additional error details:

"data": {
  "status": "error",
  "errorCode": "{error_code}",
  "description": "{error_description}"
}
addWidget

Adds an item to the KPI Dashboard.

{
	"product": "dashboard",
	"event": {
		"name": "addWidget",
		"data": {
			"widget": {
				"type": "insight",
				"ref": {
					"identifier": "aadFXtJKdz2k" // identifier or uri
				}
			}
		},
		"contextId": "addWidget-1601956026495"
	}
}
addFilter

Add a filter to the KPI Dashboard.

{
	"product": "dashboard",
	"event": {
		"name": "addFilter",
		"contextId": "addFilter-1601956608369"
	}
}
switchToEdit

Opens the KPI Dashbaord for editing.

{
	"product": "dashboard",
	"event": {
		"name": "switchToEdit",
		"contextId": "switchToEdit-1601956676605"
	}
}
cancelEdit

Closes the KPI Dashboard.

{
	"product": "dashboard",
	"event": {
		"name": "cancelEdit",
		"contextId": "cancelEdit-1601956658971"
	}
}
setFilterContext

Applies a set of filters to the embedded KPI Dashboard. You can define, one or more filters in the filter definition.

When the received filter configuration is applied, the following happens:

  • The filter configuration overrides any filters that the dashboard may already have, such as existing attribute and date filters, URL filters, previous filter configuration, and so on.

  • The filter configuration is applied even if the dashboard does not yet have any filters at all.
  • The filter configuration takes into account existing user permissions or variable filters: if they restrict some filters or filter values in the received configuration, those filters and values are not applied.

{
    data: {
        filters: [{
            "{filter_definition}"
        }],
    },
    contextId: "{filter_set_id}"
}

Notes:

  • To add a new filter, you must be in the Edit mode.
  • You can add max. 20 filters
  • If you receive an error, no filter from the postMessage is applied.

Example: Attribute filter

{
	positiveAttributeFilter: {
		displayForm: {
			identifier: "{attribute_label_identifier}",
			// or 
			// uri: "/gdc/md/{project_id}/obj/{attribute_label_id}"
		},
		in: ["/gdc/md/{project_id}/obj/{attribute_id}/elements?id={attribute_value_id}"],
	},
}


Example - Negative attribute filter

{
	negativeAttributeFilter: {
		displayForm: {
			identifier: "{attribute_label_identifier}",
			// or 
			// uri: "/gdc/md/{project_id}/obj/{attribute_label_id}"
		},
		notIn: ["/gdc/md/{project_id}/obj/{attribute_id}/elements?id={attribute_value_id}"],
	},
}


Example - Attribute filter with all values

{
	negativeAttributeFilter: {
		displayForm: {
			identifier: "{attribute_label_identifier}",
			// or 
			// uri: "/gdc/md/{project_id}/obj/{attribute_label_id}"
		},
		notIn: [],
	},
}

Example - Absolute date filter

{
	absoluteDateFilter: {
		dataSet: {
			identifier: "{dataset_identifier}",
			// or 
			// uri: "/gdc/md/{project_id}/obj/{dataset_id}"
		},
		from: "2017-01-01",
		to: "2017-12-31",
	},
}

Example - Relative date filter

You can use the following granularities: GDC.time.week_us, GDC.time.month, GDC.time.year, GDC.time.quarter, GDC.time.date.

{
	relativeDateFilter: {
		dataSet: {
			identifier: "{dataset_identifier}",
			// or 
			// uri: "/gdc/md/{project_id}/obj/{dataset_id}"
		},
		granularity: "GDC.time.date",
		from: -6,
		to: 0,
	},
}

Example - All time date filter

{
	relativeDateFilter: {
		dataSet: {
			identifier: "{dataset_identifier}",
		},
		granularity: "ALL_TIME_GRANULARITY",
		from: 0,
		to: 0,
	}
}

Example - Ranking filter

Although the ranking filter is supported by the interface of setFilterContext, KPI Dashboard does not support and it results in error. See Embed Analytical Designer.

removeFilterContext

Removes filters from the embedded KPI Dashboards (in edit mode only).

data: {
				filters: [
					// attribute filter
					{
						displayForm: {
							identifier: "{attribute_label_identifier}"
						}
					},
					// date filter
					{
						dataSet: {
							identifier: "{dataset_identifier}"
						}
					},
				],
			},
filterContextChanged

A set of filters has been changed. Includes the new definitions of all filters that have been changed.

data: {
			availableCommands: [
				...
			],
			filters: [
				"{filters_definitions}"
			]
		}
setFilterContextFinished

A confirmation that the filters that you sent have been applied.

data: {
			availableCommands: [
				...
			]
		},
drillToUrlStarted

Drilling to a URL address starts. The message contains the ID of the window.

You must enable the redirect-drill-url-to-message=all in the embedded mode URL. If not enabled, no postMessages are sent and drilling is managed by the application.

drillToUrlResolved

Contains the window ID and the target URL that opens in the specified tab/window.

You must enable the redirect-drill-url-to-message=all in the embedded mode URL. If not enabled, no postMessages are sent and drilling is managed by the application.

openScheduleEmailDialog

Opens a dialog for scheduling emails for the current dashboard.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "openScheduleEmailDialog",
            "contextId": "{context_id}"
        }
    }
}

Powered by Atlassian Confluence and Scroll Viewport.