Set Up Data Filters in Workspaces

Data filters allow you to limit the data available in child workspaces. By setting a data filter, you can define what subset of the data from a parent workspace will be available in its child workspaces. For example, a parent workspace may contain a visualization displaying the data from all company departments, but a child workspace will see only the Sales department-related data in this visualization.

Child workspaces inherit the data filters from their parent workspace the same way they inherit any other entity through the workspace hierarchy.

How Data Filters Work

A data filter relies on the following information:

• The parent workspace that holds the data that is to be limited in the child workspaces
• The child workspaces to apply the filter to (those can be direct child workspaces as well as their respective child workspaces at any hierarchy level downwards)
• The filter value assigned to a child workspace that acts as a condition for distinguishing whether the data should be available in this workspace
• The name of the column to look for in tables in a connected data source that holds the values to be compared to the filter value

The data filter uses the filter value assigned to a child workspace to distinguish what data should be made available in this workspace. The data filter compares the filter value to the values in the specified column in the data source tables. If the filter value matches the column value for some data record in a table, this record is made available in this workspace. The data records not matching the filter value are not available in the child workspace.

• The data filter is applied only to the tables that contains the specified column. If a table does not have the column, the filter is not applied, and all the data from the table is available in the workspace.
• Data records with no value in the specified column are treated as not meeting the filter condition and are not available in the workspace.
• If a data filter is set up, but a child workspace does not have any value specified, no data is available in this workspace.

Example: Imagine that you have the following workspace hierarchy:

Head Office
  |---> Western
    |---> California

You want to define what data will be available in each workspace:

• In the Head Office parent workspace, all the data should be available.
• In the Western workspace, which is a child workspace of Head Office, only the data related to the western United States should be available.
• In the California workspace, which is a child workspace of Western, only the data related to California should be available.

The following data filters will help you achieve your goal:

• A data filter that filters the data in the Western workspace by region

  When the data filter is applied, the Western workspace should be able to access only the data that meets the filter condition (that is, related to the Western region).

  • The parent workspace is Head Office.
  • The child workspace is Western.
  • The column name is wdf__region.
  • The filter value is West.

• A data filter that filters the data in the California workspace by state

  When the data filter is applied, the California workspace should be able to access only the data that meets the filter condition (that is, related to California).

  • The parent workspace is Western.
  • The child workspace is California.
  • The name of the column is wdf__state.
  • The filter value is California.

The following picture shows how a visualization in the Western workspace looks like comparing to the same visualization in the Head Office workspace when the data filter that filters the data in the Western workspace by region is applied:

Set Up Data Filters

To set up data filters, do the following:

1. Create a JSON document with filter definitions.
2. Upload the JSON document to the Organization’s metadata.

Create a JSON Document with Filter Definitions

Use the following template to create a JSON document that describes the data filters that you want to apply:

{
  "workspaceDataFilters": [
    {
      "id": "<data-filter-id>",
      "title": "<data-filter-name>",
      "columnName": "<column-name>",
      "workspace": {
        "id": "<parent-workspace-id>",
        "type": "workspace"
      },
      "workspaceDataFilterSettings": [
        {
          "id": "<data-filter-condition-id>",
          "title": "<data-filter-condition-name>",
          "filterValues": [
            "<filter-value>"
          ],
          "workspace": {
            "id": "<child-workspace-id>",
            "type": "workspace"
          }
        }
      ]
    }
  ]
}

• <data-filter-id> is the unique ID of the data filter.
• <data-filter-name> is the UI-friendly name of the data filter.
• <column name> is the name of the column in a connected data source that holds the values to be compared to the filter value specified in the <filter-value> parameter (for more information, see How Data Filters Work).
• <parent-workspace-id> is the ID of the parent workspace for whose child workspaces you are setting up the data filters.
• <data-filter-condition-id> is the unique ID of the data filter condition for a specific child workspace.
• <data-filter-condition-name> is the UI-friendly name of the data filter condition.
• <filter-value> is one or more filter values that act as a condition for distinguishing whether the data should be available in the child workspace.
• <child-workspace-id> is the ID of the child workspace that the data filter with the specified condition is applied to.

Example: A sample JSON document that describes the data filters for the scenario described earlier)

{
  "workspaceDataFilters": [
    {
      "id": "region",
      "title": "Customer Region",
      "columnName": "wdf__region",
      "workspace": {
        "id": "headoffice",
        "type": "workspace"
      },
      "workspaceDataFilterSettings": [
        {
          "id": "region_west",
          "title": "Western States",
          "filterValues": [
            "West"
          ],
          "workspace": {
            "id": "western",
            "type": "workspace"
          }
        }
      ]
    },
    {
      "id": "state",
      "title": "Customer State",
      "columnName": "wdf__state",
      "workspace": {
        "id": "western",
        "type": "workspace"
      },
      "workspaceDataFilterSettings": [
        {
          "id": "state_california",
          "title": "California",
          "filterValues": [
            "California"
          ],
          "workspace": {
            "id": "california",
            "type": "workspace"
          }
        }
      ]
    }
  ]
}

Upload the JSON Document to the Organization’s Metadata

To upload the JSON document, submit a PUT request to /api/v1/layout/workspaceDataFilters.

The data filters in the JSON document will replace all currently configured data filters.

curl $HOST_URL/api/v1/layout/workspaceDataFilters \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type:application/json" \
  -X PUT -d @/path/to/your-filter-definition.json

Invoke-RestMethod -Method Put -Uri "$HOST_URL/api/v1/layout/workspaceDataFilters" `
   -ContentType 'application/vnd.gooddata.api+json' `
   -H @{ 'Authorization' = "Bearer $API_TOKEN" } `
   -InFile path\to\your-filter-definition.json

For more information about updating the data filters in the Organization’s metadata, see the workspace declarative API interface. You can also use the workspace declarative API interface to describe all the workspaces in your Organization.

1. Download the complete declarative document from /api/v1/layout/workspaces (see the “Layout” section in the API reference).
2. In this document, replace the workspaceDataFilters section with the one that you created.
3. Upload the updated declarative document back to /api/v1/layout/workspaces.