Managing Access to Workspace Objects via API

When a metric, report, or dashboard is first created in a workspace, it is visible only to the object’s creator at first.

This article describes two independent operations that you can use to manage access to the object for other users in the workspace. These independent operations can be executed at the same time using the same API endpoint:

• listed/unlisted - When an object is created, it is unlisted in the Portal GUI. You can use the API to make the object visible in the workspace, effectively publishing the object to other users.

  When an object is first created, it is not visible to users other than its creator or workspace administrators. It must be made visible through the Portal GUI or through this API for others in the workspace to use it.

• lock/unlock - You may lock workspace objects to prevent others from editing them, which is useful for production assets. As needed, you can unlock assets via API to make them available for editing.

Overview of the API

End point:

https://secure.gooddata.com/gdc/internal/projects/{workspace_id}/objects/setPermissions

Method:

POST

Body:

 {
    "permissions":{
        "lock":true,
        "unlisted":true,
        "items":[
          "/gdc/md/{workspace_id}/obj/{object-id1}",
          "/gdc/md/{workspace_id}/obj/{object-id2}"
        ]
    }
}

Under items, you must list all objects for which you want to change the permissions. You do not need to specify dependent objects in this area. For example, if you make a dashboard object visible, all reports referenced in the dashboard and metrics referenced within those reports are automatically made visible.

You can set the following parameters:

• lock - can be true or false and specify if the object lock is applied
• unlisted - can be true or false and specify the visibility of the object in the GoodData Portal

Object Visibility via API

When the object (called a personal object) is ready to share, it can be made visible to other users in the workspace through the GoodData Portal or the APIs.

• Workspace Administrators can locate personal objects.

Object visibility is useful in the following situations:

• Primary: I want to publish a report or dashboard that I’ve been developing to the other users in the workspace.
• I’ve made a mistake in a published report or dashboard and need to remove it from public use.
• I’ve created a report or dashboard which is no longer useful. However, it contains other objects that are still useful.

Visibility of individual objects may be toggled through the GoodData Portal. For more information, see Manage Object Visibility - Hide and Share Objects.

Object Locking via API

Object locking enables you to set edit permissions for specific objects. Each dashboard, report, and metric in a workspace is an individual object with its own URL. Through the APIs, you can toggle whether the objects can be edited or not.

Object locking covers following use cases:

• Primary: I want to set edit restrictions on a dashboard or report and all objects it contains. This step prevents workspace Editors from modifying production objects.
• I want to update production objects in the production environment with new versions prepared in the development/staging environment using Migrate Selected Objects between Workspaces.
• I want to remove edit restrictions from a dashboard and then from all reports and metrics contained in it.

Individual objects may be locked through the GoodData Portal. For more information, see Permission to Edit Workspace Metrics, Reports, and Dashboards.

Examples

Publishing production objects

The following POST makes three object (object-id’s) publicly available (unlisted=false) and locked for editing (lock=true). Effectively, this request publishes a production asset.

Note: The terms ‘workspace ID’ and ‘project ID’ mean one and the same thing. See Find the Workspace ID.

 {
    "permissions":{
        "lock":true,
        "unlisted":false,
        "items":[
          "/gdc/md/{workspace_id}/obj/{object-id1}",
          "/gdc/md/{workspace_id}/obj/{object-id2}",
          "/gdc/md/{workspace_id}/obj/{object-id3}"
        ]
    }
}

Making an asset private again

The following POST to the API endpoint unlocks (lock=false) the object and hides it (unlisted=true) so that development can begin again without confusing workspace users.

{
    "permissions":{
        "lock":false,
        "unlisted":true,
        "items":[
          "/gdc/md/{workspace_id}/obj/{object-id}",
        ]
    }
}

Any dependent objects of the hidden object are not hidden. If they should be hidden, you must execute requests to hide those objects, too.

Collaborate with other editors

The following POST unlocks an asset for editing without changing the visibility permissions. You can use this method to collaborate with other Editors.

{
    "permissions":{
        "lock":false,
        "items":[
          "/gdc/md/{workspace_id}/obj/{object-id}",
        ]
    }
}

Reference

For API reference documentation, see Manage Object Visibility - Hide and Share Objects.