Pass Filters with Embedded Visier Visualizations

Filter passing allows a web application or web portal to pass visualization filters implicitly into an embedded Visier visualization.

Overview

With filter passing, you can configure a default filter or dynamic filters to apply to embedded Visier visualizations in your web portal or application. To learn how to embed a visualization in your web application or web portal, see Embed a Visualization.

You may want to configure filter passing to provide a default filter in embedded visualizations for your users, or to provide your users with different filtering options to which the hosting application or portal passes into the embedded visualizations. This is useful when you want to create a base visualization that will be used in multiple pages of your web application or portal and ensures users will see relevant data. This means you don't have to create unique visuals in Visier each time.

You can configure the filters to apply to an embedded visualization if you are an IT administrator or development team member with access to the studio experience.

If a visualization is embedded in a web application or portal without filter passing, the visual is displayed exactly as it appeared in Visier. With filter passing, you can configure a default filter or dynamic filters to apply in the web portal or application.

• Default filter: Set the initial filter to apply to an embedded visualization. You may use one or more filters in the default, such as Age and Job Name. The default filter is configured by adding an additional attribute to the code snippet that is provided from the analysis as part of the embedding workflow.
• Dynamic filters: Define a set of filters to pass in an embedded visualization. You can configure your web application or portal to programmatically control the filters of an embedded visualization. Dynamic filters are configured by adding specific JavaScript to the embedding page.

The following list describes the order in which to complete the steps to set up filter passing.

1. Retrieve the unique ID for the filters you want to use. See Step One: Find the filter's unique ID.
2. Determine the syntax for your filter. See Step Two: Construct the filter syntax.
3. Edit the visual in Visier. See Step Three: Prepare the visual for filtering.
4. Put it all together. See Step Four: Pass filters to an embedded visual.
5. Optional: If you run into an issue, try some troubleshooting methods. See Troubleshoot common errors.

The following sections guide the IT administrator and/or development team through setting up an embedded visual to pass a filter.

Step One: Find the filter's unique ID

You can use dimension members to filter an embedded visualization. This can be achieved by constructing a filter where the correct syntax consists of a combination of unique IDs from analytic objects, dimensions, and dimension members. To properly construct the filter syntax, you must first obtain these unique IDs. Record the object's ID for use in Step Two: Construct the filter syntax.

Analytic objects or dimensions

The ID for an analytic object or dimension is its unique object name. Follow the procedure below to retrieve the ID for an analytic object or dimension.

1. Open a project.
2. Navigate to Model > Analytic Objects or Dimensions.
3. In the Search bar, type the display name of the object. For example, Employee Exit.
4. In the Object Name column, find the unique object name. For example, Employee_Exit.

   

   Tip: If you cannot find the Object Name column, click Columns on the right side of the table, as shown below. In the list of column options, select Object name.

   

Dimension members

The ID for a dimension member comes from your data. You can find the unique ID in your source data or in Visier. After you retrieve the unique ID, the member ID is used in the following syntax structure: [Hierarchy].[MemberId]. For example, if the unique ID for the dimension member "Engineer" is DEV01, the syntax would read as follows: "[Hierarchy].[DEV01]".

To find the unique ID in Visier:

1. Open a project.
2. Navigate to Model > Dimensions.
3. Find and select the dimension that the dimension member belongs to. For example, find and select the "Gender" dimension to find its dimension member "Woman".
4.  In the dimension, navigate to Configure.
5. In the Name column, find the name of the dimension member that you want to use in your filter, as shown next. The name is the dimension member's unique ID.

   

Step Two: Construct the filter syntax

To filter a visualization, Visier uses data from the analytic objects and dimensions in your solution. To pass a filter in an embedded visual, you must assemble a statement using the filter IDs that you retrieved in Step One above.

The supported filter types are:

• Include/exclude filter: A method to filter the visualization by specific included or excluded objects. For example, you can include the "Gender" dimension member "Woman" and exclude the "Job Name" dimension member "Engineer". This filters the visualization to include data about women in the organization and exclude those women who are engineers.
• Numeric range filter: A method to filter the visualization by a range of numbers. For example, you can filter the dimension "Age Range" by a numeric range of 25 to 30. This filters the visualization to only include data about individuals aged 25 to 30 years old.

The following sections describe the syntax associated with supported filter types.

Include/exclude filter

An include/exclude filter allows you to choose specific objects to include or exclude in your visualization filter.

Parameters

Examples

The following examples show different ways to use the include/exclude filter.

filters: [
    {
        includeExclude: {
            hierarchyId: "Job_Name",
            subjectReferences: ["Employee"],
            includedMembers: ["[Hierarchy].[Chief Executive Officer]", "[Hierarchy].[Chief Financial Officer]"],
            excludedMembers: []
        }
    }
]

filters: [
    {
        includeExclude: {
            hierarchyId: "Gender",
            subjectReferences: ["Employee"],
            includedMembers: ["[Hierarchy].[Woman]"],
            excludedMembers: []
        },{
            hierarchyId: "Location",
            subjectReferences: ["Employee"],
            includedMembers: ["[Hierarchy].[North America].[Canada].[British Columbia]"],
            excludedMembers: []
        }
    }
]

Numeric range filter

A numeric range filter allows you to specify a specific range of numbers to filter a dimension by.

Parameters

Examples

filters: [
    {
        numericRangeFilter: {
            hierarchyId: "Age_Range",
            subjectReferences: ["Employee"],
            isExcluded: false,
            numericRange: {
                rangeStart: "25",
                rangeEnd: "28",
                rangeType: "InclusiveExclusive"
            }
        }
    }
]

Multiple filters

If you want to include multiple filter types in your embedded visualization, each filter must be an element in the filters array.

Parameters

Examples

filters: [
    {
        includeExclude: {
            hierarchyId: "Job_Name",
            subjectReferences: ["Employee"],
            includedMembers: ["[Hierarchy].[Plant Operator]","[Hierarchy].[Plant Supervisor]"],
            excludedMembers: []
        }
    },{
        numericRangeFilter: {
            hierarchyId: "Age_Range",
            subjectReferences: ["Employee"],
            isExcluded: false,
            numericRange: {
                rangeStart: "25",
                rangeEnd: "30",
                rangeType: "InclusiveExclusive"
            }
        }
    }
]

Step Three: Prepare the visual for filtering

To pass filters into an embedded visualization, you must configure the embedding analysis to accept filters.

1. Navigate to the analysis that contains the embedding visual that will support filters. There are two ways to navigate to an analysis:
   1. If you created the analysis and have the Embed Analytic Content capability:
      1. Open the solution experience and, on the navigation bar, click Analyses.
      2. Select the analysis you created that contains the visualization you want to embed in your application or web portal. The first visualization displayed in the analysis will be embedded in your target environment.
      3. In the upper-right corner, click the Edit button .
   2. If you are embedding a visualization from a Visier-created analysis and have an administrator capability:
      1. Open a project and navigate to Model > Analyses.
      2. Select an analysis from the list that contains the visualization you want to embed in your application or web portal. The first visualization displayed in the analysis will be embedded in your target environment.
      3. In the upper-right corner, click Edit Analysis.

      Caution: If you edit a Visier-created analysis, you will not receive future updates to that analysis from Visier experts. For more information, see Edit Visier Content.

2. If the Driving Subject is not already set for the analysis, set the Driving Subject filter. In the Analysis Editor, under the analysis title, expand Filter analysis by, as shown next. The Driving Subject is the object associated with the filters you want to add, such as Employee. This configures the subject on which filters can be applied for the whole analysis. For more information, see The driving subject.

   

3. Click Done editing.

   Result: Your embedded visualization is ready to accept filters.

Step Four: Pass filters to an embedded visual

Now that you retrieved the unique filter IDs (Step One), constructed the filter syntax (Step Two), and configured the analysis to accept filters (Step Three), you can add filters to the embedded visualization.

As described previously, there are two ways to pass a filter:

• Default filter: Set the initial filter to apply to an embedded visualization. You may use one or more filters in the default, such as Age and Job Name. The default filter is configured by adding an additional attribute to the code snippet that is provided from the analysis as part of the embedding workflow.
• Dynamic filters: Define a set of filters to pass in an embedded visualization. You can configure your web application or portal to programmatically control the filters of an embedded visualization. Dynamic filters are configured by adding specific JavaScript to the embedding page.

Option One: Pass a default filter

To define a default filter in an embedded visual to apply when the visual first loads in your web application or web portal, a filters attribute must be added to the chart config passed into embedCharts.

Follow the below steps to successfully pass a default filter.

1. Retrieve a code snippet from the Visier analysis by following the instructions in Embed a Visualization.
2. In the code snippet, find the embedCharts method call and the chart config passed as a parameter.
3. In the corresponding chart config, add an attribute called filters. This attribute includes your filters to pass into the embedded visualization. The following example shows the correct format to use.

app.embedCharts([
    {
        contentId: "bbfdf21b-1f37-4504-8397-ac97043555f1",
        containerId: "chart-container",
        filters: [
            {
                includeExclude: {
                    hierarchyId: "Job_Name",
                    subjectReferences: ["Employee"],
                    includedMembers: ["[Hierarchy].[Plant Operator]", "[Hierarchy].[Plant Supervisor]"],
                    excludedMembers: []
                }
            }, {
                numericRangeFilter: {
                    hierarchyId: "Age_Range",
                    subjectReferences: ["Employee"],
                    isExcluded: false,
                    numericRange: {
                        rangeStart: "25",
                        rangeEnd: "30",
                        rangeType: "InclusiveExclusive"
                    }
                }
            }
        ]
    }
]);

Result: When the embedded visualization is rendered, the filters are passed in the visualization.

Option Two: Pass dynamic filters

To pass filters dynamically, the hosting web application or web portal executes a JavaScript. Use the following JavaScript code snippet to pass dynamic filters.

var your_JSON = {messageType: "set_filters", filters: [
    {supported_filter}, ...
    ]};
document.getElementById("visier-embedded-app-frame-containerId").contentWindow.postMessage(your_JSON, "*");

You must change some of the attributes in the above JavaScript to be unique to your web application or web portal, as described next.

• your_JSON: Identifies the data you want to pass to the iframe. This can be any string of your preference; it does not have to read "your_JSON".
• supported_filter: An array of supported filters to pass into the embedded visual. See Step Two: Construct the filter syntax.
• containerID: The container ID as defined in your chart config code snippet. In the below example, the containerID is "chart-container".

var your_JSON = {messageType: "set_filters", filters: [
    {
        includeExclude: {
            hierarchyId: "Job_Name",
            subjectReferences: ["Employee"],
            includedMembers: ["[Hierarchy].[Plant Operator]","[Hierarchy].[Plant Supervisor]"],
            excludedMembers: []
        }
    },{
        numericRangeFilter: {
            hierarchyId: "Age_Range",
            subjectReferences: ["Employee"],
            isExcluded: false,
            numericRange: {
                rangeStart: "25"
                rangeEnd: "30"
                rangeType: "InclusiveExclusive"
            }
        }
    }
]}; document.getElementById("visier-embedded-app-frame-chart-container").contentWindow.postMessage(your_JSON, "*");

Troubleshoot common errors

The following scenarios provide guidance for common errors that may occur while setting up filters for embedded visualizations.