Communicate with Embedded Dashboards Using PostMessages

When you embed Dashboards, you can set up receiving messages from the dashboard to your application.

Supported postMessages can be broken down into two categories:

  • Events are outgoing messages that the embedded Dashboards send to your application to notify you about the status of commands (for example, success or failure). Events are sent automatically.

  • Commands are incoming messages sent from your application to the embedded Dashboard to apply actions.

Events

The following events are supported:

loadingStarted

The embedded content starts loading.

{
	"gdc": {
		"product": "dashboard",
		"event": {
			"name": "loadingStarted",
			"data": {
				"dashboard": "dashboard_identifier",
				"dashboardId": "dashboard_id"
			},
			"contextId": "context123"
		}
	}
}

loaded

The content is fully loaded, and the user has permissions to access the dashboard.

{
	"gdc": {
		"product": "dashboard",
		"event": {
			"name": "loaded",
			"data": {
				"dashboard": "dashboard_identifier",
				"dashboardId": "dashboard_id"
			},
			"contextId": "context123"
		}
	}
}

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.

Possible reason values: viewDenied and editDenied.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "noPermissions",
            "data": {
                "reason": "viewDenied"
            },
            "contextId": "context123"
        }
    }
}

resized

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

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "resized",
            "data": {
                "height": 600
            },
            "contextId": "context123"
        }
    }
}

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.

{
	"gdc": {
		"product": "dashboard",
		"event": {
			"name": "dashboardCreated",
			"data": {
				"project": "project_id",
				"dashboard": "dashboard_identifier",
				"dashboardId": "dashboard_id"
			},
			"contextId": "context123"
		}
	}
}

Note that in GoodData, terms workspace and project denote the same entity. For example, project ID is exactly the same as workspace ID.

dashboardCreationCanceled

The user cancels the creation of the dashboard.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "dashboardCreationCanceled",
            "contextId": "context123"
        }
    }
}

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.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "dashboardUpdated",
            "data": {
                "project": "project_id",
                "client": "client_id",
                "dashboard": "dashboard_identifier",
                "dashboardId": "dashboard_id"
            },
            "contextId": "context123"
        }
    }
}

Note that in GoodData, terms workspace and project denote the same entity. For example, project ID is exactly the same as workspace ID.

dashboardDeleted

The dashboard has been deleted. The ‘data’ section contains information about the deleted dashboard.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "dashboardDeleted",
            "data": {
                "project": "project_id",
                "dashboard": "dashboard_identifier",
                "dashboardId": "dashboard_id"
            },
            "contextId": "context123"
        }
    }
}

Note that in GoodData, terms workspace and project denote the same entity. For example, project ID is exactly the same as workspace ID.

setFilterContextFinished

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

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "setFilterContextFinished",
            "contextId": "context123"
        }
    }
}

filterContextChanged

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

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "filterContextChanged",
            "data": {
                "filters": [
                    {
                        "relativeDateFilter": {
                            "granularity": "GDC.time.date",
                            "from": -6,
                            "to": 0
                        }
                    }
                ]
            },
            "contextId": "context123"
        }
    }
}

drillableItems

Lists the identifiers of metrics and attributes that can be drilled into.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "drillableItems",
            "data": {
                "identifiers": ["identifier123"]
            },
            "contextId": "context123"
        }
    }
}

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.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "drillToUrlStarted",
            "data": {
                "id": "windowId123"
            },
            "contextId": "context123"
        }
    }
}

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.

The filters section includes all dashboard filters applied to the insight that you drill from. It also includes information if the filter values are included or excluded from the filter.

The resolvedFilterValues section includes all actual values of dashboard filters applied to the insight that you drill from:

  • The attribute filters: text values of the filter elements.
  • The date filters: values from and to in the MM/dd/yyyy format
{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "drillToUrlResolved",
            "data": {
                "id": "48769ef3-ef36-4532-baa7-b46294386117",
                "url": "https://www.company.com/my_products",
                "filters": [
                    {
                        "attributeFilter": {
                            "displayForm":"label.f_owner.salesrep.ownername",
                            "negativeSelection": false,
                            "attributeElements":["Cory Owens","Dale Perdadtin","Dave Bostadt"]
                        }
                    },
                    {
                        "dateFilter": {
                            "type": "relative",
                            "granularity": "GDC.time.year",
                            "from": -7,
                            "to": -1
                        }
                    }
                ],
                "resolvedFilterValues": {
                    "dateFilters": [
                        {
                            "from": "01/01/2014",
                            "to": "12/31/2020"
                        }
                    ],
                    "attributeFilters": {
                        "/gdc/md/auiwj6pa2cs3twpjr98gtjfb34x3i0gv/obj/1252": {
                            "/gdc/md/auiwj6pa2cs3twpjr98gtjfb34x3i0gv/obj/1251/elements?id=169661": "In Person Meeting"
                        }
                    }
                }
            },
            "contextId": "context123"
        }
    }
}

Commands

The following commands are supported:

setApiToken

Set the API token you want to use for authentication. See the Example in the parent article.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "setApiToken",
            "contextId": "context123",
            "data": {
                "token": "<api_token_value>"
            }
        }
    }
}

switchToEdit

Opens the dashboard for editing (in view mode only).

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "switchToEdit",
            "contextId": "context123"
        }
    }
}

cancelEdit

Closes the dashboard (in edit mode only).

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "cancelEdit",
            "contextId": "context123"
        }
    }
}

addWidget

Adds an item to the dashboard (in edit mode only).

Example: Add visualization

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "addWidget",
            "data": {
                "widget": {
                    "type": "insight",
                    "ref": {
                        "identifier": "c67470a1-a9dd-4a1e-980a-f51d947a195a"
                    }
                }
            },
            "contextId": "context123"
        }
    }
}

addFilter

Add a filter to the dashboard (in edit mode only).

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "addFilter",
            "contextId": "context123"
        }
    }
}

setFilterContext

Applies a set of filters to the embedded 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.
  • All display forms (not only default) are supported in the filter configuration.
{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "setFilterContext",
            "data": {
                "filters": [
                    {
                        "positiveAttributeFilter": {
                            "displayForm": {
                                "identifier": "identifier123"
                            },
                            "in": ["someValue"],
                            "textFilter": true
                        }
                    }
                ]
            },
            "contextId": "context123"
        }
    }
}

Notes:

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

Example: Attribute filter - using an identifier

{
    "positiveAttributeFilter": {
        "displayForm": {
            "identifier": "identifier123"
        },
        "in": ["someValue"],
        "textFilter": true
    }
}

Example: Negative attribute filter

{
    "negativeAttributeFilter": {
        "displayForm": {
            "identifier": "identifier123"
        },
        "notIn": ["someValue"],
        "textFilter": true
    }
}

Example: Attribute filter with all values

{
    "negativeAttributeFilter": {
        "displayForm": {
            "identifier": "identifier123"
        },
        "notIn": []
    }
}

Example: Single selection filter

{
    "positiveAttributeFilter": {
        "displayForm": {
            "identifier": "identifier123"
        },
        "in": ["someValue"],
        "selectionMode": "single",
        "textFilter": true
    }
}

Example: Absolute date filter

{
    "absoluteDateFilter": {
        "dataSet": {
            "identifier": "identifier123"
        },
        "from": "2023-01-01",
        "to": "2023-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": "identifier 123"
        },
        "granularity": "GDC.time.date",
        "from": -6,
        "to": 0
    }
}

Example: All time date filter

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

Example: Ranking filter

Although the ranking filter is supported by the interface of setFilterContext , dashboards do not support this filter and it results in error.

removeFilterContext

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

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "removeFilterContext",
            "data": {
                "filters": [
                    {
                        "displayForm": {
                            "identifier": "identifier123"
                        }
                    }
                ]
            },
            "contextId": "context123"
        }
    }
}

where displayForm refers to the attribute filter.