Communication with Embedded Analytical Designer

Supported events and commands

When you embed Analytical Designer (see Embed Analytical Designer), you can set up receiving messages to your application.

Events

EventEvent trigger
insightOpened

The insight has been opened.

{
    "gdc": {
        "product": "analyticalDesigner",
        "event": {
            "name": "insightOpened",
            "contextId": "context123"
        }
    }
}

insightChanged

The insight has changed.

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

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

{
    "gdc": {
        "product": "analyticalDesigner",
        "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": "analyticalDesigner",
        "event": {
            "name": "filterContextChanged",
            "data": {
                "filters": [
                    {
                        "relativeDateFilter": {
                            "dataSet": {
                                "identifier": "identifier 123"
                            },
                            "granularity": "GDC.time.date",
                            "from": -6,
                            "to": 0
                        },
                    }
                ]
            },
            "contextId": "context123"
        }
    }
}

Commands

EventEvent trigger
undo

Undo the last action.

{
    "gdc": {
        "product": "analyticalDesigner",
        "event": {
            "name": "undo",
            "contextId": "context123"
        }
    }
}
redo

Applies the next action (if undo has been applied).

{
    "gdc": {
        "product": "analyticalDesigner",
        "event": {
            "name": "redo",
            "contextId": "context123"
        }
    }
}
clear

Removes all items and information from the insight.

{
    "gdc": {
        "product": "analyticalDesigner",
        "event": {
            "name": "clear",
            "contextId": "context123"
        }
    }
}

Note: This command deletes the complete insight.

clearInsight

Removes the following items from the insight:

  • Mertrics
  • Facts
  • Attributes
  • Filters
{
    "gdc": {
        "product": "analyticalDesigner",
        "event": {
            "name": "clearInsight",
            "contextId": "context123"
        }
    }
}

Note: This command deletes only the contents of the insight. When you add new info and save, it is saved as the original insight.

setFilterContext

Applies a set of filters to the embedded Analytical Designer. 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.
{
    "gdc": {
        "product": "analyticalDesigner",
        "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. 20 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

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

Example: Attribute filter with all values

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

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 supports also attributes in Analytical Designer, use only an array with a single attribute local identifier in the postMessage. Sending an empty array results in error.

You can get localidentifier of facts and metrics from InsightChanged and InsightOpened messages.

Note: In the following code sample, measure refers to both the facts and the metrics.

{
    "rankingFilter": {
        "measure": { "localIdentifier": "{local_identifier}" },
        "operator": "TOP",
        "value": 3
    }
}
removeFilterContext

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

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