Manage Dashboard Permissions

Dashboard permissions dictate who can view, share and edit a particular dashboard. In a typical workflow, dashboard permissions can be managed using the Share button in the dashboard’s web user interface, see Share Dashboards. This article describes how to manage these permissions using the API in case you want to automate the process, or if you have to deal with an edge case scenario.

When a user creates new dashboard, by default the only users who can view, share and edit the dashboard are:

• The user who created the dashboard, who is automatically assigned the EDIT permission to this particular dashboard.
• Users who have Workspace.MANAGE permission to the workspace the dashboard is native to.
• Users who have Workspace.MANAGE hierarchyPermission to the workspace workspace the dashboard is native to, or to its parent workspace, if the workspace is part of a workspace hierarchy.
• Users with Organization.MANAGE permission.

To enable other users to access the dashboard, you need to fulfill the following two criteria:

1. Ensure the user or user group has a Workspace.VIEW or higher level permission to the workspace the dashboard is a part of; this can mean a direct permission to the workspace, or at least a hierarchyPermission to a parent workspace. To update the workspace permissions, see Manage Workspace Permissions.

2. Assign one of the supported dashboard permissions to the user or user group in the particular dashboard, see Set Permissions For a Dashboard.

Supported Dashboard Permissions

The following permissions are applicable to the analyticalDashboard object:

• VIEW - corresponds to the View sharing option in the web UI.
• SHARE - corresponds to the View & Share sharing option in the web UI.
• EDIT - corresponds to the Edit & Share sharing option in the web UI.

The permission levels work hierarchically - each subsequent permission level grants the assigned users all the rights of the previous permission level.

The level of access each dashboard permission level gives the user depends on the user’s permission level to the workspace the dashboard is in. The following table shows all possible combinations of workspace and dashboard permissions a user or user group can have:

* User with Dashboard.SHARE or Dashboard.EDIT can also unassign permissions from other users, unless they have a higher level permission than the user themselves.

Available Assignees

Before you add new users to the dashboard’s permissions, you should use the /api/v1/actions/workspaces/<workspaceId>/analyticalDashboards/<dashboardId>/availableAssignees API endpoint to list users and user groups that are eligible.

If the user or user group are not listed as being eligible, it is because of one of the following reasons:

• The user or user group does not have the required workspace permission, so even if you assigned them a permission to access the dashboard, it will remain inacessible to them. Assign a Workspace.VIEW or Workspace.ANALYZE permission to the user or user group first.
• The user or user group already has a permission assigned to them to this particular dashboard.
• The user or user group already has full access to the dashboard, because they have the Workspace.MANAGE or Organization.MANAGE permission.

You can add users and user groups to the dashboard’s permissions using the API even if they are not listed as eligible.

The list produced by the /availableAssignees API endpoint is what the web user interface users see when they click the Share button and then the Add button to add a new user or user group.

Set Permissions For a Dashboard

Use the following API endpoints to manage dashboard permissions:

• /api/v1/actions/workspaces/<workspaceId>/analyticalDashboards/<dashboardId>/permissions

  Lists dashboard’s existing permissions.

• /api/v1/actions/workspaces/<workspaceId>/analyticalDashboards/<dashboardId>/managePermissions

  Updates dashboard’s permissions.

Note that the first two steps are optional, but we recommend you do them before you try to change a dashboard’s permissions.

Steps:

1. (Optional) Make the following API call to fetch an up-to-date json definition of the dashboard’s permissions:

   curl -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -X GET \
       $HOST_URL/api/v1/actions/workspaces/<workspaceId>/analyticalDashboards/<dashboardId>/permissions
   

2. (Optional) If a user or user group is not on the listed in the permissions definition, and you want to add them, first check if they are eligible by calling the following endpoint:

   curl -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -X GET \
       $HOST_URL/api/v1/actions/workspaces/<workspaceId>/analyticalDashboards/<dashboardId>/availableAssignees
   

   If the user or user group is not listed here either, it is because they lack access to the workspace, or because they already have full access to the dashboard with their Workspace.MANAGE or Organization.MANAGE permission.

3. Prepare new permissions in a <new_permissions>.json file:

   [
       {
           "assignee": {
           "id": "<user-group-id>",
           "type": "userGroup"
           },
           "permissions": ["VIEW"],
       },
       {
           "assignee": {
           "id": "<user-id>",
           "type": "user"
           },
           "permissions": ["EDIT"]
       },
       {
           "assignee": {
           "id": "<user2-id>",
           "type": "user"
           },
           "permissions": [],
       },        
   ]
   

   In this example I want to give VIEW permission to user group <user-group-id>, I want to give EDIT permission to user <user-id>, and I want to remove all existing permissions from user <user2-id>.

4. Update the dashboard’s permissions using the new permissions definition:

   curl -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -X POST \
       $HOST_URL/api/v1/actions/workspaces/<workspaceId>/analyticalDashboards/<dashboardId>/managePermissions \
       -d @<new_permissions>.json
   

   The /managePermissions API endpoint only updates permissions for users and user groups that you list in <new_permissions>.json, permissions of other users and user groups to this dashboard stay unchanged.

   You should get back a 204 No Content response.

Dashboard Inheritance in Workspace Hierarchies

Dashboard is inherited from a parent workspace together with its permissions. In the child workspace, you can extend the inherited permissions by adding new ones. However you cannot take away inherited permissions in the child workspace.

Note that Dashboard.EDIT permission in an inherited dashboard will not let the user edit the dashboard. The dashboard remains editable only in its native parent workspace. In the child workspace, the Dashboard.EDIT permission behaves as a Dashboard.SHARE permission.

User and User Group SEE Permission

There may be some edge case scenarios where a user or user group is not listed as an available assignee, even though you might want them to be there.

Example Scenario

Imagine a workspace hierarchy where a dashboard created in the parent workspace is inherited by the child workspace. The user who created the dashboard in the parent workspace (Parent User) wants to share the dashboard with a user of the child workspace (Child User).

The Child User does not have access to the parent workspace and the Parent User does not have access to the child workspace. This means that the Parent User cannot open the child workspace and share the dashboard with the Child User from there; Nor can the Parent User share the dashboard directly from the parent workspace, because the Child User is not going to be listed as an available assignees there.

What do you do in such a situation?

One solution would be to use the managePermissions API to manually update the dashboard’s permission definition to allow the Child User to access the dashboard.

Another solution would be to set up a SEE permission.

Introducing the SEE Permission

The SEE permission lets you see other users and user groups listed as eligible users when using the availableAssignees API or the share web user interface functionality, irrespective of user’s or user group’s workspace membership.

The SEE permission is defined in the User or UserGroup declarative object. You can access these permission via the API endpoints:

• /api/v1/layout/users/<userId>/permissions
• /api/v1/layout/userGroups/<userGroupId>/permissions
• /api/v1/layout/usersAndUserGroups/<userOrUserGroupId>/permissions

The User or UserGroup object you are updating is the user object that will be seen by other users, as defined in the objects permission definition.

Building on the previous example scenario; To let the Parent User see the Child User as an eligible user to share the dashboard with, the Child User object can be updated with the user.SEE permission which is assigned to the Parent User.

{
    "users": [
        {
            "authId": "<child-user-auth-id>",
            "id": "<child-user-id>",
            "permissions": [
                {
                    "assignee": {
                        "id": "<parent-user-id>",
                        "type": "user"
                    },
                    "name": "SEE"
                }
            ]
        },
        ...

This allows the Parent User to see the Child User any time they try to share a dashboard.

Please note:

• In general it is preferrable to assign these permissions to entire user groups, rather than individual users.

• Just because you see someone as an eligible user as a result of them having the SEE permission assigned to you, this does not mean that sharing a dashboard with them will guarantee that they will be able to access it. The workspace permission requirement still has to be met.

Set SEE Permissions For a User or UserGroup

Use the declarative API endpoints:

• /api/v1/layout/users/<userId>/permissions
• /api/v1/layout/userGroups/<userGroupId>/permissions
• /api/v1/layout/usersAndUserGroups/<userOrUserGroupId>/permissions

to assign the SEE permission to a user or user group.

Please note that you need to have an Organization.MANAGE permission to be able to update user and userGroup objects.

Steps:

1. Make the following API call to fetch an up-to-date json user groups’s permissions definition:

   curl -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -X GET \
       $HOST_URL/api/v1/layout/userGroups/<userGroupId>/permissions
   

2. Update the user groups’s permissions definition:

   [
       {
           "assignee": {
               "id": "<user-group-id>",
               "type": "userGroup"
           },
           "name": "SEE"
       },
       {
           "assignee": {
               "id": "<user-group2-id>",
               "type": "userGroup"
           },
           "name": "SEE"
       },
       {
           "assignee": {
               "id": "<user-id>",
               "type": "user"
           },
           "name": "SEE"
       }
   ]
   

3. Update the user group’s permissions using the new permissions definition:

   curl -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -X POST \
       $HOST_URL/api/v1/layout/userGroups/<userGroupId>/permissions \
       -d @<updated_permissions_definition>.json
   

   You should get back a 204 No Content response.

Identify Private Dashboards

Newly created dashboards, where only the user that created the dashboard has a dashboard permission assigned to the dashboard, are labelled as private. You can find out whether a dashboard is private using the API.

Call one of the dashboard API endpoints with a GET request and an URI parameter metaInclude=accessInfo:

• /api/v1/entities/workspaces/{workspaceId}/analyticalDashboards?metaInclude=accessInfo
• or ​/api​/v1​/entities​/workspaces​/{workspaceId}​/analyticalDashboards​/{objectId}?metaInclude=accessInfo

The response will contain meta: { "accessInfo": { "private": "true|false" } } telling you whether a particular dashboard is private or not.

Backwards Compatibility

Dashboard permissions were introduced in GoodData.CN version 2.3 and its GoodData Cloud release equivalent.

If you are updating your GoodData from an older version, note that the following permissions are automatically assigned for all existing dashboards:

• Dashboard.VIEW permission is assigned to all users who have a Workspace.VIEW permission to the workspace the dashboard is in.
• Dashboard.EDIT permission is assigned to all users who have a Workspace.ANALYZE permission to the workspace the dashboard is in.

If you are restoring from a backup made in an older version, the only users able to access these dashboards will be those with Workspace.ANALYZE or Organization.MANAGE permissions. Permissions to the individual dashboards will have to be reinstated manually by updating the Dashboard API layout objects.