When a metric, report, or dashboard is first created in a project, 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 project. 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 project, effectively publishing the object to other users.
When an object is first created, it is not visible to users other than its creator or project administrators. It must be made visible through the Portal GUI or through this API for others in the project to use it.
- lock/unlock - You may lock project 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
unlisted parameters are independent of each other. You may submit changes to either parameter or both parameters in a single request. If a parameter is omitted, its value is unchanged by the request.
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.
If you hide an object, any dependent objects are not automatically hidden. For example, after you hide a dashboard, you must hide each report and metric in it, if you wish to hide them, too. The same applies to unlocking an object, as well.
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 project through the GoodData Portal or the APIs.
- Project 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 project.
- 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 Managing Project Data.
Object Locking via API
Object locking enables you to set edit permissions for specific objects. Each dashboard, report, and metric in a project is an individual object with its own URL. Through the APIs, you can toggle whether the objects can be edited or not.
Only project Administrators can change editing permissions of objects.
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 project 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 Partial export/imports.
- 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 Project Metrics, Reports, and Dashboards.
Publishing production objects
POST makes three object (
object-id’s) publicly available (
unlisted=false) and locked for editing (
lock=true). Effectively, this request publishes a production asset.
Making an asset private again
POST to the API endpoint unlocks (
lock=false) the object and hides it (
unlisted=true) so that development can begin again without confusing project users.
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
POST unlocks an asset for editing without changing the visibility permissions. You can use this method to collaborate with other Editors.
While the object remains hidden in the Portal GUI, you can provide the direct URL to the object to other Editors who can edit the object after this change is made.
Note that the
unlisted parameter is not specified.
For API reference documentation, see Object Visibility using the API.