Communication with Embedded KPI Dashboards

When you embed Dashboards (see Embed a Dashboard), you can set up receiving messages from the dashboard to your application.

Supported events and commands

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

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.

ContextId is used to correlate events and commands. It identifies the input and output of the communication.

Events

EventEvent trigger
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 // Height in px
            },
            "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",
                "client": "client_id",
                "dashboard": "dashboard_identifier",
                "dashboardId": "dashboard_id"
            }
            "contextId": "context123"
        }
    }
}
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"
        }
    }
}
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",
                "client": "client_id",
                "dashboard": "dashboard_identifier",
                "dashboardId": "dashboard_id"
            }
            "contextId": "context123"
        }
    }
}
platform

The GoodData platform is temporary unavailable.

Possible status values: maintenance, upgrade, or error.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "platform",
            "data": {
                "status": "maintenance"
            }
            "contextId": "context123"
        }
    }
}

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

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "platform",
            "data": {
                "status": "error",
                "errorCode": 500,
                "description": "Internal server error"
            }
            "contextId": "context123"
        }
    }
}
setFilterContextFinished

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

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

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

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "setFilterParentsFinished",
            "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": {
                            "dataSet": {
                                "identifier": "identifier 123"
                            },
                            "granularity": "GDC.time.date",
                            "from": -6,
                            "to": 0
                        },
                    }
                ]
            },
            "contextId": "context123"
        }
    }
}
setFilterParentsFailed

Failed command if you try to connect a child filter to the parent filter.

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "setFilterParentsFailed",
            "data": {
                "errorCode": "circularDependency"
            },
            "contextId": "setFilterParents-1601932858809"
        }
    }
}

List of possible errors:

  • invalidDataFormat - The command data format is invalid. For example, there are missing properties or wrong types.
  • invalidAttributeFilterDisplayForm - The attribute filter display form has an invalid reference or the display form does not exist in the workspace.
  • invalidParentFilterDisplayForm - The parent filter display form has an invalid reference or does not exist in the workspace.
  • filterNotFound - The filter is not on the dashboard.
  • circularDependency - The filter can not depend on itself.
  • invalidConnectingAttribute - The connecting attribute is invalid or does not exist in the workspace.
  • incompatibleConnectingAttribute - The connecting attribute is not shared between the filter and its parent.
  • duplicateFilters - Multiple filters with the same id in a single command.
  • duplicateParents - Multiple parents with the same id in a single filter.
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": "/gdc/md/auiwj6pa2cs3twpjr98gtjfb34x3i0gv/obj/1252",
                            "negativeSelection": true,
                            "attributeElements": [
                                "/gdc/md/auiwj6pa2cs3twpjr98gtjfb34x3i0gv/obj/1251/elements?id=169661"
                                ]
                            }
                    },
                    {
                        "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

CommandCommand trigger
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 insight

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

Example: Add a KPI

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "addWidget",
            "data": {
                "widget": {
                    "type": "kpi"
                }
            },
            "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": [
                                "/gdc/md/kr3t3bca94asl/obj/400/elements?id=12"
                            ]
                        }
                    }
                ],
            },
            "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": [
            "/gdc/md/kr3t3bca94asl/obj/400/elements?id=12"
        ]
    }
}

Example: Attribute filter - using URI

{
    "positiveAttributeFilter": {
        "displayForm": {
            "uri": "/gdc/md/kr3t3bca94asl/obj/399"
        },
        "in": [
            "/gdc/md/kr3t3bca94asl/obj/400/elements?id=12"
        ]
    }
}

Example: Negative attribute filter

{
    "negativeAttributeFilter": {
        "displayForm": {
            "identifier": "identifier123"
        },
        "notIn": [
            "/gdc/md/kr3t3bca94asl/obj/400/elements?id=12"
        ]
    }
}

Example: Attribute filter with all values

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

Example: Single selection filter

{
    "positiveAttributeFilter": {
        "displayForm": {
            "uri": "/gdc/md/kr3t3bca94asl/obj/399"
        },
        "in": ["/gdc/md/kr3t3bca94asl/obj/400/elements?id=12"],
        "selectionMode": "single"
    }
}

Example: Absolute date filter

{
    "absoluteDateFilter": {
        "dataSet": {
            "identifier": "identifier123"
        },
        "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": "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. See Embed Analytical Designer.

removeFilterContext

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

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "removeFilterContext",
            data: {
                filters: [
                    // attribute filter
                    {
                        displayForm: {
                            identifier: "identifier123"
                        }
                    },
                    // date filter
                    {
                        dataSet: {
                            identifier: "identifier123"
                        }
                    },
                ],
            },
            "contextId": "context123"
        }
    }
}
setFilterParents

Applies a hierarchy among attribute filters on a dashboard (in edit mode only).

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "setFilterParents",
            "data": {
                "filters": [
                    {
                        "filter": {
                            "attributeFilter": {
                                "displayForm": {
                                    "uri": "/gdc/md/ux8xk21n3al4qr1akoz7j6xkl5dt1dqj/obj/102844"
                                }
                            }
                        },
                        "parents": [
                            {
                                "parent": {
                                    "attributeFilter": {
                                        "displayForm": {
                                            "uri": "/gdc/md/ux8xk21n3al4qr1akoz7j6xkl5dt1dqj/obj/1028"
                                        }
                                    }
                                },
                                "connectingAttribute": {
                                    "uri": "/gdc/md/ux8xk21n3al4qr1akoz7j6xkl5dt1dqj/obj/1025"
                                }
                            }
                        ]
                    }
                ]
            },
            "contextId": "setFilterParents-1601932858809"
        }
    }
}

Example: Remove all parent filters

{
    "gdc": {
        "product": "dashboard",
        "event": {
            "name": "setFilterParents",
            "data": {
                "filters": [
                    {
                        "filter": {
                            "attributeFilter": {
                                "displayForm": {
                                    "uri": "/gdc/md/ux8xk21n3al4qr1akoz7j6xkl5dt1dqj/obj/1028"
                                }
                            }
                        },
                        "parents": []
                    }
                ]
            },
            "contextId": "setFilterParents-1601932858809"
        }
    }
}
openScheduleEmailDialog

Opens a dialog for scheduling emails for the current dashboard (in view mode only).

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