Retrieve and apply filters
Filters can be applied both during the execution of an embedded dashboard and after it has been rendered.
- 
Apply filters during execution You can pass filters as properties when an embedded dashboard is being executed. You use the dossier.create(props)method in the Embedding SDK and define the filters to apply using the filters property.
- 
Apply and retrieve filters after execution Once you have used the dossier.create(props)method to embed a dashboard into a third-party web page, you can use methods in the Embedding SDK to retrieve and apply filters.- 
Retrieve filters after a dashboard is rendered After an embedded dashboard has been rendered, you can use the getFilterList()method of theDossierclass to retrieve information about filters that were applied to chapters in the dossier.
- 
Apply filters after a dashboard is rendered After an embedded dashboard has been rendered, you can apply different kinds of filters to chapters in the dashboard using a number of different methods on the Embedding SDK. Chapter is the only filter type that is currently supported. 
- 
Apply multiple filters after a dashboard is rendered This section introduces how you can cache the results of several filters and apply them together. 
 
- 
To help you get started, we have provided a set of filter examples in the Embedding SDK Playground.
Retrieve filters after a dashboard is rendered
After an embedded dashboard has been rendered, you can use the getFilterList() method of the Dossier class in the Embedding SDK to retrieve information about filters that were applied to chapters in the dossier.
| getFilterList() | |
|---|---|
| Class | Dossier | 
| Return Type | Promise<filter[]> | 
| Description | Returns a list of filters defined in the current chapter. | 
| Example | dossier.getFilterList() | 
getFilterList() returns an array of JSON objects that each describe a specific filter. Each JSON filter object has the following fields:
| Field | Description | 
|---|---|
| filterKey | A string to represent the key for the filter. | 
| filterName | A string to represent the name for the filter (which is the same as the name of the data used by the filter). | 
| filterType | A string to represent the filter type, in an easy-to-read format. | 
| filterDetail | An object to show the expressions and values that define the filter. They are different for each filter type. | 
| isExclude | A boolean to specify whether to include or exclude the selections for the filter. | 
Filter types and filter details
The sections below show the filter details for each filter type.
metricQualByValue
- 
from,to,value, andnullIf the filter operator is "between" or "not between", the filterDetailwill be:{
 "operator": "between", // An enum string in ["equals", "not equals", "greater", "greater equal", "less", "less equal", "between", "not between", "in", "not in", "is null", "is not null"]
 "from": 0, // Number
 "to": 100 // Number
 }If the filter operator is not "is null" or "is not null", the filterDetailwill only haveoperator:{
 "operator": "is null" // An enum string in ["equals", "not equals", "greater", "greater equal", "less", "less equal", "between", "not between", "in", "not in", "is null", "is not null"]
 }For the remaining filter operators, the filterDetailwill be:{
 "operator": "greater", // An enum string in ["equals", "not equals", "greater", "greater equal", "less", "less equal", "between", "not between", "in", "not in", "is null", "is not null"]
 "value": 1 // Number
 }
- 
operatorA stringthat refers to a specific function type used by the metric qualifier filter. Only thequalByValuequalify type is supported. Possible values are "equals", "not equals", "greater", "greater equal", "less", "less equal", "between", "not between", "in", "not in", "is null", or "is not null".
metricQualByRank
- 
valueUser-inputted value that specifies the rank used in the filter expression. 
- 
qualTypeA stringthat refers to a specific qualify type used by the metric qualifier filter. Qualify types include "highest", "lowest", "highest percent", "lowest percent".
metricSliderByValue
- 
maxMaximum allowed value for the metric slider filter. If the user-inputted value is greater than this value, it will be set to max automatically. 
- 
minMinimum allowed value for the metric slider filter. If the user-inputted value is less than this value, it will be set to min automatically. 
- 
fromUser-inputted value that specifies the beginning of the metric range used in the filter expression for the metric slider filter. 
- 
toUser-inputted value that specifies the ending of the metric range used in the filter expression for the metric slider filter. 
- 
indexInfoJSON object that specifies the total number of items and selection indexes of the items. {
 "itemLength": 150,
 "itemStep": 7016,
 "from": 50,
 "to": 106
 }
metricSliderByRank
- 
maxMaximum allowed value for the metric slider filter. If the user-inputted value is greater than this value, it will be set to max automatically. 
- 
minMinimum allowed value for the metric slider filter. If the user-inputted value is less than this value, it will be set to min automatically. 
- 
valueUser-inputted value that specifies the rank used in the filter expression for the metric slider filter. 
- 
qualTypeNumber that refers to a specific qualify type used by the metric qualifier filter. Qualify types include "highest", "lowest", "highest percent", "lowest percent". 
- 
indexInfoJSON object that specifies the total number of items and selection index of the item. {
 "itemLength": 35,
 "itemStep": 1,
 "value": 1
 }
attributeSearchSelector
- 
supportMultipleSpecifies whether multiple search selections can be applied to the metric slider filter. If it is not true, only one selection will be applied to the filter. 
- 
itemsArray of attribute items, containing names, IDs and selection status of all attribute items {
 "name": "item name to show",
 "value": "item ID used to do filter",
 "selected": true // if this item is selected
 }
attributeSelector
- 
supportMultipleSpecifies whether multiple selections can be applied to the metric slider filter. If it is not true, only one selection will be applied to the filter. 
- 
itemsArray of attribute items, containing names, IDs and selection status of all attribute items {
 "name": "item name to show",
 "value": "item ID used to do filter",
 "selected": true // if this item is selected
 }
attributeSlider
- 
supportMultipleSpecifies whether multiple selections can be applied to the filter. If it is not true, only one selection will be applied to the filter. 
- 
indexInfoJSON object that specifies the total number of items and selection index of the item(s). If supportMultipleis true:{
 "itemLength": 20, // The length of the items array
 "from": 0, // The starting position of selected elements in the items array
 "to": 19 // The ending position of selected elements in the items array
 }If supportMultipleis false:{
 "itemLength": 20, // The length of the items array
 "value": 0 // The position of the selected element in the items array
 }
- 
itemsArray of attribute items, containing names, IDs and selection status of all attribute items [
 {
 "name": "item name to show",
 "value": "item ID used to do filter",
 "selected": true // if this item is selected
 }
 ]
calendar
- 
maxDateLatest date for the calendar filter. 
- 
minDateEarliest date for the calendar filter. 
- 
fromUser-inputted value that specifies the beginning of the date range. 
- 
toUser-inputted value that specifies the ending of the date range. 
Filter type examples
Some examples for the JSON filter object in the return array of getFilterList():
- attributeSelector
- attributeSearchSelector
- attributeSlider
- calendar
- metricQualByValue
- metricQualByRank
- metricSliderByValue
- metricSliderByRank
Filter type: attributeSelector
{
  "filterKey": "W394",
  "filterName": "Category",
  "isExclude": false,
  "filterType": "attributeSelector",
  "filterDetail": {
    "items": [
      {
        "name": "Books",
        "value": "h1;8D679D3711D3E4981000E787EC6DE8A4",
        "selected": true
      },
      {
        "name": "Electronics",
        "value": "h2;8D679D3711D3E4981000E787EC6DE8A4",
        "selected": true
      },
      {
        "name": "Movies",
        "value": "h3;8D679D3711D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "Music",
        "value": "h4;8D679D3711D3E4981000E787EC6DE8A4",
        "selected": false
      }
    ],
    "supportMultiple": true
  }
}
Filter type: attributeSearchSelector
{
  "filterKey": "W76",
  "filterName": "Year",
  "isExclude": false,
  "filterType": "attributeSearchSelector",
  "filterDetail": {
    "items": [
      {
        "name": "2007",
        "value": "h2007;8D679D5111D3E4981000E787EC6DE8A4",
        "selected": true
      },
      {
        "name": "2008",
        "value": "h2008;8D679D3711D3E4981000E787EC6DE8A4",
        "selected": true
      }
    ],
    "supportMultiple": true
  }
}
Filter type: attributeSlider
{
  "filterKey": "IGK228",
  "filterName": "Month of Year",
  "isExclude": false,
  "filterType": "attributeSlider",
  "filterDetail": {
    "indexInfo": {
      "itemsLength": 12,
      "from": 0,
      "to": 0
    },
    "items": [
      {
        "name": "January",
        "value": "h1;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": true
      },
      {
        "name": "February",
        "value": "h2;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "March",
        "value": "h3;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "April",
        "value": "h4;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "May",
        "value": "h5;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "June",
        "value": "h6;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "July",
        "value": "h7;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "August",
        "value": "h8;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "September",
        "value": "h9;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "October",
        "value": "h10;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "November",
        "value": "h11;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      },
      {
        "name": "December",
        "value": "h12;8D679D4511D3E4981000E787EC6DE8A4",
        "selected": false
      }
    ],
    "supportMultiple": true
  }
}
Filter type: calendar
{
  "filterKey": "W65",
  "filterName": "Daytime",
  "isExclude": false,
  "filterType": "calendar",
  "filterDetail": {
    "from": "1/30/2007 11:59:00 PM",
    "to": "5/30/2007 11:59:00 PM",
    "maxDate": "12/31/2010 11:59:59 PM",
    "minDate": "01/01/2007 12:00:00 AM"
  }
}
Filter type: metricQualByValue
{
  "filterKey": "W116",
  "filterName": "Cost",
  "isExclude": false,
  "filterType": "metricQualByValue",
  "filterDetail": {
    "operator": "between",
    "from": 400000,
    "to": 800000
  }
}
or
{
  "filterKey": "W116",
  "filterName": "Cost",
  "isExclude": false,
  "filterType": "metricQualByValue",
  "filterDetail": {
    "operator": "is null"
  }
}
or
{
  "filterKey": "W116",
  "filterName": "Cost",
  "isExclude": false,
  "filterType": "metricQualByValue",
  "filterDetail": {
    "operator": "greater",
    "value": 400000
  }
}
Filter type: metricQualByRank
{
  "filterKey": "IGK263",
  "filterName": "Cost",
  "isExclude": false,
  "filterType": "metricQualByRank",
  "filterDetail": {
    "qualType": "highest percent",
    "value": 20
  }
}
Filter type: metricSliderByValue
[
  {
    "filterKey": "IGK311",
    "filterName": "Cost",
    "isExclude": false,
    "filterType": "metricSliderByValue",
    "filterDetail": {
      "indexInfo": {
        "itemLength": 149,
        "itemStep": 5995,
        "from": 51,
        "to": 148
      },
      "min": 28271,
      "max": 921453,
      "from": 334016,
      "to": 921453
    }
  },
  {
    "filterKey": "W392",
    "filterName": "Profit",
    "isExclude": false,
    "filterType": "metricSliderByValue",
    "filterDetail": {
      "indexInfo": {
        "itemLength": 149,
        "itemStep": 1385,
        "from": 0,
        "to": 148
      },
      "min": -372,
      "max": 205973,
      "from": -372,
      "to": 205973
    }
  }
]
Filter type: metricSliderByRank
{
  "filterKey": "IGK359",
  "filterName": "Cost",
  "isExclude": false,
  "filterType": "metricSliderByRank",
  "filterDetail": {
    "indexInfo": {
      "itemLength": 144,
      "itemStep": 1,
      "value": 143
    },
    "min": 1,
    "max": 144,
    "qualType": "highest",
    "value": 144
  }
}
Apply a filter after the dashboard is rendered
After an embedded dashboard has been rendered, you can apply different kinds of filters to chapters in the dashboard using methods on the Embedding SDK. In this release, getFilterList() only exposes filters defined in the current chapter.
Dossier.filterSelectAllAttributes(filterJson)
Select all the attributes for the filter with key and apply the change immediately.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK359" // String. The filter key.
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterDeselectAllAttributes(filterJson)
Deselect all the attributes for the filter with key and save the change to client side.
Since holdSubmit is set to true, this change is applied and rendered together with other cached changes in an "Apply Filter request" where holdSubmit has a falsy value, typically filterApplyAll.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK359" // String. The filter key.
  },
  "holdSubmit": true // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSelectSingleAttribute(filterJson)
Select single attributes for the filter with key.
Use this API for filters that support single selection.
Use either name or value to do the selection. value is the attribute element ID. You can get it from the getFilterList API. name should be the attribute element name, if you provide the name, it is converted to a value (ID).
Example of filterJson parameter
{
  "filterInfo": {
    "key": "W394" // String. The filter key.
  },
  "selection": {
    "value": "h1;8D679D3711D3E4981000E787EC6DE8A4" // String. The id of the attribute element. Use either "value" or "name".
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
or
{
  "filterInfo": {
    "key": "W394" // String. The filter key.
  },
  "selection": {
    "name": "Books" // String. The name of the attribute element. Use either "value" or "name".
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSelectMultiAttributes(filterJson)
Select multiple attributes for the filter with key.
Use this API for filters that support multiple selections.
Use either name or value to do the selection. value is the attribute element ID. You can get it from the getFilterList API. name should be the attribute element name, if you provide the name, it is converted to a value (ID).
Example of filterJson parameter
{
  "filterInfo": {
    "key": "W394" // String. The filter key.
  },
  "selections": [
    {
      "value": "h1;8D679D3711D3E4981000E787EC6DE8A4" // String. The id of the attribute element. Use either "value" or "name".
    },
    {
      "value": "h2;8D679D3711D3E4981000E787EC6DE8A4" // String. The id of the attribute element. Use either "value" or "name".
    }
  ],
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
or
{
  "filterInfo": {
    "key": "W394" // String. The filter key.
  },
  "selections": [
    {
      "name": "Books" // String. The name of the attribute element. Use either "value" or "name".
    },
    {
      "name": "Electronics" // String. The name of the attribute element. Use either "value" or "name".
    }
  ],
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSearchSingleAttribute(filterJson)
Select single attribute for the search filter with key.
Use this API for filters that support single selection.
value is the attribute element ID, which is required.
name is the attribute element name.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "W394" // String. The filter key.
  },
  "selections": [
    {
      "name": "Books", // String. The name of the attribute element. Use either "value" or "name".
      "value": "h1;8D679D3711D3E4981000E787EC6DE8A4" // String. The id of the attribute element. Use either "value" or "name".
    },
    {
      "name": "Movies", // String. The name of the attribute element. Use either "value" or "name".
      "value": "h2;8D679D3711D3E4981000E787EC6DE8A4" // String. The id of the attribute element. Use either "value" or "name".
    }
  ],
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSearchMultiAttributes(filterJson)
Select multiple attributes for the search filter with key.
Use this API for filters that support multiple selection.
value is the attribute element ID, which is required.
name is the attribute element name.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "W394" // String. The filter key.
  },
  "selections": [
    {
      "name": "Books", // String. The name of the attribute element. Use either "value" or "name".
      "value": "h1;8D679D3711D3E4981000E787EC6DE8A4" // String. The id of the attribute element. Use either "value" or "name".
    },
    {
      "name": "Movies", // String. The name of the attribute element. Use either "value" or "name".
      "value": "h2;8D679D3711D3E4981000E787EC6DE8A4" // String. The id of the attribute element. Use either "value" or "name".
    }
  ],
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterAttributeSingleSlider(filterJson)
Select single attributes for the filter with key using the slider style. Selection is the index of the attribute in the attributes items getFilterInfos result.
Use this API for filters that support single selection.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "W227" // String. The filter key.
  },
  "selection": 2, // Number. The index of the selection in items array.
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterAttributeMultiSlider(filterJson)
Select multiple attributes for the filter with key using the slider style. The from and to values in selections refer to the starting and ending attribute indexes for attribute items in the getFilterInfos result.
Use this API for filters that support multiple selection.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK228" // String. The filter key.
  },
  "selections": [2, 8], // [from: Number, to: Number]. The index of starting and ending positions in items array of the selection.
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSetDateRange(filterJson)
Select the from and to date range for the date range filter with key.
If from is missing, the dataset start date is used.
If to is missing, the dataset end date is used.
The from and to strings should a format recognized by the Date.parse() method. This format should beIETF-compliant RFC 2822 or ISO8601.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "W113" // String. The filter key.
  },
  "date": {
    "from": "01/01/2007 11:59:00 PM", // String. The starting date of selection.
    "to": "01/30/2007 11:59:00 PM" // String. The ending date of selection.
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSetMetricQualByValue(filterJson)
Apply a metric qualify by value filter.
key - The filterKey
operator - An enum of "equals", "not equals", "greater", "greater equal", "less", "less equal", "between", "not between", "in", "not in", "is null", or "is not null"
firstValue – The number in the top input box
lastValue – The number in the bottom input box
Example of filterJson parameter
{
  "filterInfo": {
    "key": "W116" // String. The filter key.
  },
  "exp": {
    "operator": "between", // String
    "firstValue": 400000, // Number.
    "lastValue": 800000 // Number.
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSetMetricQualByRank(filterJson)
Apply metric qualify by rank filter.
key – The filterKey
qualType – An enum of "highest", "lowest", "highest percent", or "lowest percent"
value – The rank value
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK263" // String. The filter key.
  },
  "exp": {
    "qualType": "highest", // String.
    "value": 20 // Number.
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSetMetricSliderByValue(filterJson)
Apply metric slider by range filter.
key – The filterKey
range – The metric range
Since a slider has fixed steps, the metric range you enter is converted to an index of step items.
Example:
The step items are: [0, 10, 20, 30, 40, 50]
You enter a metric range of [13, 26], which is converted to the index of step items [1, 3]. This refers to the value range of 10~30.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK311" // String. The filter key.
  },
  "exp": {
    "range": [400000, 600000], // [from: Number, to: Number]. The range of numbers starting at "from" and ending at "to".
    "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
  }
}
Dossier.filterSetMetricSliderByRank(filterJson)
Apply metric slider by rank filter
key – The filterKey
qualType – An enum of "highest", "lowest", "highest percent", or "lowest percent".
value – The rank value
Since a slider has fixed steps, the metric range you enter is converted to an index of step items.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK359" // String. The filter key.
  },
  "exp": {
    "qualType": "highest", // String.
    "value": 10 // Number.
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterClearAll()
Clears all filters.
No parameters
Dossier.filterClear(filterJson)
Clear filter with key.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK359" // String. The filter key.
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSetInclude(filterJson)
Set filter as include.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK359" // String. The filter key.
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterSetExclude(filterJson)
Set filter as exclude.
Example of filterJson parameter
{
  "filterInfo": {
    "key": "IGK359" // String. The filter key.
  },
  "holdSubmit": false // Boolean. Determines whether or not to hold off applying the filter until Dossier.filterApplyAll() is called.
}
Dossier.filterApplyAll()
Applies all changes cached by holdSubmit.
No parameters
Apply multiple filters after the dashboard is rendered
This section introduces how you can cache the results of several filters and apply them together. Let's say you have the following filters:
The items in bold are selected.
- 
A multi-selection filter that binds checkboxes: Category: Books, Movies, Games, Sports 
- 
A single selection filter that binds radio buttons: Gender: Male, Female 
Take the following steps:
- 
Apply filterSelectMultiAttributes, setselectionsasBooksandMovies, and setholdSubmitastrue.
- 
Apply filterSelectSingleAttribute, setselectionasFemale, and setholdSubmitastrue.
- 
Apply filterApplyAll.The result returned from server is filtered by Books, Movies, and Female. 
Events
There are two events that are fired on the embedded dashboard when a filter is applied after rendering.