Powered By GoodData - Create Data Permissions

Related Tags: quick start mandatory user filters powered by data permissions

NOTE: This article is part of the Powered By GoodData Tutorial. Some aspects may not apply to other implementation scenarios.

Depending on the nature of your implementations, you may need to filter the data for the individual user. For example, if your project contains customer-specific information and users from multiple customers, the data returned should be filtered for the specific customer. This kind of filtration may also be applied based on specific users, regions, products, and other dimensions of your data, so that individual users are seeing only the data that pertains to them.

NOTE: Data Permissions were formerly called Mandatory User Filters.

In GoodData, these filters are called Data Permissions. At the technical level, a Data Permissions filter is a hidden parameter/value pair that is passed to the datastore with every query initiated from the GoodData Portal to filter the returned data. This parameter value is retrieved for the user initiating the query from a designated attribute in the logical data model and silently appended to each query that is submitted for the user.

For example, suppose you wish to filter an entire project by the region of the country. If you designate the Region attribute as your Data Permissions filter, then all queries are filtered by the value of the attribute for the current user.

If you are familiar with dashboard filters in GoodData, a Data Permissions filter functions like a selected value or a wildcard in a dashboard filter, except for the following differences:

  • The Data Permissions filter is hidden from the user.
  • It cannot be modified by the user.
  • It applies to the entire project for the user, and the user is unaware of any data that does not pass the filter.

For multi-project implementation projects, a Data Permissions filter attribute typically used for user filtering is some kind of customer identifier. When a value is used as the Data Permissions filter, the data returned in any query should apply only to the querying user. Example attributes of this type are user ID and corporate domain.

  • Multiple Data Permissions may be applied to a single user.

Tip: Data Permissions filters provide an effective means of managing data access. However, you may find it easier to manage data access by provisioning different projects for sets of users requiring varying data access permissions. For example, you could create one project that provides view-only dashboard level access without any drill-down capability, which would provision users to access aggregated data while securing the underlying details from view.

Configuring the Logical Data Model for the Data Permissions filter

To support use of Data Permissions, you must add an attribute for each user filter to your logical data model.

NOTE: The attribute for Data Permissions filtering must be added to each dataset where it makes sense for you to filter the data based on values in the attribute.

For each dataset, the attribute must be added to the highest point in the hierarchy where you wish to apply filtering. Suppose your hierarchy looks like the following:

Accounts -> Opportunity -> Opportunity Line Item

By adding the attribute to the Accounts, you are enabling data filtration by user for the Accounts dataset only. If you wish to filter data in the Opportunity and Opportunity Line Item datasets, the attribute must be added to them, too.

Configuring Data Permissions for Your Project

After the attribute has been added to your logical data model, you can create the Data Permissions filter object in each of your destination projects.

NOTE: You should avoid creating Data Permissions filters in your master project. When you create new projects from these resources, the Data Permissions filters are not included. The recommended practice is to create the Data Permissions filters new in each project created from the project template, gather the identifiers at the time of creation, and then apply them to individual users.

To add a Data Permissions filter to your project, please complete the following steps:

  1. Locate the attribute ID of the attribute to use.
  2. Create the Data Permissions filter object in your project.
  3. Load project to refresh.
  4. In a later step, you apply the new Data Permissions filter to users in the project.

These steps are accomplished by using the GoodData APIs.

Before You Begin

NOTE: If you are specifying Data Permissions filters via the gray pages or API for a specific user, you must re-specify all Data Permissions filters for that user each time you update. You cannot simply add a new Data Permissions filter or update a subset of the user’s Data Permissions filters. For this reason, it may be useful to maintain an external record of the Data Permissions filters applied to each user.

NOTE: You must be an Administrator in each project where you wish to create Data Permissions.

You should already have the following information:

  • Project identifiers. Internal IDs for all projects to which you are applying Data Permissions filters.
  • User identifiers. Internal IDs for all users of the projects to which you are applying Data Permissions filters.

Acquire identifiers for users in the project

You can use the following API call to acquire the internal identifiers for all user profiles in your project.

Steps:

  1. Execute the following API call:
    Type GET
    URI /gdc/projects/{project-id}/users?offset=0&limit=5
  2. where:
    • {domain_name} corresponds to the name of your GoodData organization. This information should be provided to you during your initial implementation.
  3. The above call returns the first five (limit=5) user profiles in the project. You can page through the remainder of the user profiles by incrementing the offset value (offset=1) in subsequent calls to page by the number of users (offset x (limit-1)).
  4. An example response with an account profile is included below:
    200 (OK)
        Content-Type: application/json
        
    {
       "users" : [
          {
             "user" : {
                "content" : {
                   "email" : "user@domain.com",
                   "firstname" : "John",
                   "userRoles" : [
                      "/gdc/projects/{project_id}/roles/2"
                   ],
                   "phonenumber" : "+777777777",
                   "status" : "ENABLED",
                   "lastname" : "Dow",
                   "login" : "user@domain.com"
                },
                "links" : {
                   "roles" : "/gdc/projects/{project_id}/users/2f35048619b7b0ff03f408d2c4b6390d/roles",
                   "permissions" : "/gdc/projects/{project_id}/users/2f35048619b7b0ff03f408d2c4b6390d/permissions",
                   "groups" : "/gdc/projects/{project_id}/users/2f35048619b7b0ff03f408d2c4b6390d/groups",
                   "self" : "/gdc/account/profile/{project_id}",
                   "invitations" : "/gdc/account/profile/{project_id}/invitations",
                   "projects" : "/gdc/account/profile/{project_id}/projects",
                   "projectRelUri" : "/gdc/projects/{project_id}/users/2f35048619b7b0ff03f408d2c4b6390d"
                },
                "meta" : {
                   "created" : "2011-08-10 08:37:46",
                   "updated" : "2013-05-27 11:08:09",
                   "author" : "/gdc/account/profile/876ec68f5630b38de65852ed5d6236ff",
                   "title" : "John Dow",
                   "contributor" : "/gdc/account/profile/876ec68f5630b38de65852ed5d6236ff"
                }
             }
          }
       ]
    }
    
  5. From the above data, you may wish to gather the following values:
    email
    firstname
    lastname
    projectRelUri
  6. The projectRelUri value identifies the user identifier internal to the project.

Locate the attribute ID for Data Permissions filter

To create the Data Permissions filter, you must first locate the internal identifier of the attribute on which to filter. This identifier is specific to each project.

Steps:

  1. GET from the following API:
    Type GET
    URI /gdc/md/{project-id}/query/attributes
  2. The response contains the list of attributes for the project. Search for the name of the attribute to be used for filtering. The display value is stored in the Title parameter:
    {
           "link": "/gdc/md/wgx0zvz7489uys5vofom04o1aw1of3z9/obj/1049",
           "author": "/gdc/account/profile/6472c6662d1438b2ef59d75b0175aaea",
           "tags": "date day quarter",
           "created": "2012-08-23 04:56:49",
           "deprecated": "0",
           "summary": "Generic day of quarter (D1, D2, ... , D92)",
           "title": "Day of Quarter (Campaign Start)",
           "category": "attribute",
           "updated": "2012-08-23 04:56:52",
           "contributor": "/gdc/account/profile/6472c6662d1438b2ef59d75b0175aaea"
    },
    
  3. The last part of the link value for the attribute is the internal object ID for the attribute. In the above, this value is 1049.
  4. The attribute URI string is the following:
    /gdc/md/wgx0zvz7489uys5vofom04o1aw1of3z9/obj/1049
    
  5. Retain this value for later use.

NOTE: Depending on the Data Permissions filter, you may need to retrieve the element identifiers for specified values of the attribute. The API endpoint to use is the following: /gdc/md/{project-id}/obj/{object-id}/elements, which returns a list of identifiers. For a known element identifier, you can append the following to the URL to return the element: /{element-id}

For more information on gathering attribute information, see Determining the Attribute Value ID.

Building the Data Permissions filter expression

When you submit your request to create the Data Permissions filter for a project, you must submit an expression for the Data Permissions filter similar to the following:

"expression": "[/gdc/md/{project-id}/obj/{object-id}]=[/gdc/md/{project-id}/obj/{object-id}/elements?id={element-id}]"

In the above, the expression value defines the Data Permissions filter to evaluate for each user to which it assigned. In the above example, the left-hand side of the expression returns the current value of the attribute, which is compared to a specified value of the attribute (element-id) in the right-hand side. This expression might evaluate to something like: Region=West.

Expression Syntax:

In general, expression values are specified in the following format:

[URI-attribute] = [URI-element]

You may also apply the following logical structures to your expressions:

[URI-attribute] <> [URI-element]
[URI-attribute] IN ( [URI-element1], [URI-element2], ... )
[URI-attribute] NOT IN ( [URI-element1], [URI-element2], ... )

Logical AND is applied in the following manner, while logical OR is not allowed in Data Permissions:

[URI-attribute1] = [URI-element1] AND [URI-attribute2] = [URI-element2]

Parentheses can be added to expressions in the following manner.

( [URI-attribute1] = [URI-element1] ) AND ( [URI-attribute2] = [URI-element2] )

NOTE: The limit on the length of a filter expression is 200,000 characters.

Create the Data Permissions filter object

After you have defined the expression to evaluate, you can create the Data Permissions filter for the project.

Steps:

  1. Send a POST to the following API end point:
    Type POST
    URI /gdc/md/{project-id}/obj
  2. The JSON payload should look similar to the following. The expression value should match the value you previously defined for the Data Permissions filter.
    {
        "userFilter": {
            "content": {
                "expression": "[/gdc/md/{project-id}/obj/{object-id}]=[/gdc/md/{project-id}/obj/{object-id}/elements?id={element-id}]"
            },
            "meta": {
                "category": "userFilter",
                "title": "My simple User filter"
            }
        }
    }
    
  3. A Status Code 200 for the response indicates that the Data Permissions filter has been created. Retain the title value for later use in applying the filter.

Reload the project

NOTE: To verify that the Data Permissions filter has been applied to the entirety of the project, you should refresh one dashboard in the project to verify that they are enabled.

Steps:

  1. Login to the GoodData Portal.
  2. Select the project from the drop-down menu.
  3. Reload the page.