Workspace Object Identification
An instance of a workspace object can be uniquely identified using an object identifier (object ID) in combination with its object type. This means that there can be two objects with the same object ID, but of different object types.
Object ID is a string that is limited to 255 characters consisting of characters a-Z0-9._-
.
Referencing an Object
For logical and physical layer all relations are solid part of an appropriate object structure, for analytics objects free-form content is supported, with an exception for metrics.
To establish relationship between analytics object and other object following structure must be used.
{
"identifier" :
{
"id" : STRING,
"type" : "metric"|"analyticalDashboard"|...,
}
}
For MAQL, a serialised form is used {<type>/<id>}
. For example:
SELECT SUM({fact/size}) WHERE {label/name} IN ("Special","Small")
where size
is the object ID of and fact
the object type.
Object Origin
All objects that are part of a workspace have a metadata property called origin:
{
"data": {
…,
"meta": {
"origin": {
“originType”: “NATIVE”|”PARENT”,
“originId”: STRING
}
},
},
}
The origin metadata contains information on whether the object is inherited from a parent workspace, or whether it is native to the workspace:
originId
is the id of the workspace where the object originates from.NATIVE
origin indicates that the object is native to the workspace it’s in. (i.e.originId
= current workspace id)PARENT
origin indicates that the object comes from a parent object. (i.e.originId
= some parent workspace id)
This ensures that there is always a reliable way of checking whether an object is native to a given workspace, or whether it is inherited from a parent workspace (and thus, whether the restrictions that apply to inherited objects need to apply to this object or not, for instance).
Accessing an Object via the API
You can access an object of object type <type>
and object id <id>
located in workspace <workspace-id>
using the following GET API endpoint:
$HOST_URL/api/v1/entities/workspaces/<workspace-id>/<type>/<obj-id>
Custom Object ID Prefix
You can set a unique custom prefix for each workspace. When you create a new analytical object (metric, visualization, dashboard) in that workspace, the prefix is automatically prepended to its object ID. This way you can easily tell which workspace an object originates from at a glance even if you are working within a complicated workspace hierarchy. Using prefixes should also help you avoid a potential clash of identical object IDs within a workspace hierarchy.
Once you set custom prefix, you can then see it, for instance, when creating a new metric in the web user interface (here the custom prefix was set to doc_demo_
):
Note that:
Adding or changing the prefix will not update any pre-existing objects' IDs.
The prefix is applied only when you create an object using the web user interface, or when you create without explicitely defining its ID field.
If you create an object together with a custom ID, it is up to you to add the prefix to the ID manually, if you want it there.
Recommended Practice
When creating a custom prefix, we recommend you:
- End the prefix with a delimiter like
_
,-
or.
. This way it is apparent what part of the object identifier is the prefix, and which part is the raw ID. - Consider using the parent prefixes to create your child prefixes, for example
EU_
,EU-FR_
,EU-FR-PARIS_
. - Prefixes should be unique and easily distinguishable from each other. Avoid using prefixes that are very similar to each other, such as
EU_
andEU__
. - Avoid making your prefix in a child workspace a subpart of your parent workspace prefix, such as having prefix
EU__
in the parent, andEU_
in the child.
Set a Custom Object ID Prefix for a Workspace
The custom object ID prefix is set on the workspace object that can be accessed via the entity and declarative API endpoints:
/api/v1/entities/workspaces/<workspace_id>
/api/v1/layout/workspaces/<workspace_id>
Steps:
Make the following API call to the
/api/v1/entities/workspaces/<workspace_id>
API endpoint:curl -X PATCH $HOST_URL/api/v1/entities/workspaces/<workspace_id> \ -H "Content-Type: application/vnd.gooddata.api+json" \ -H "Accept: application/vnd.gooddata.api+json" \ -H "Authorization: Bearer $API_TOKEN" \ -d '{ "data": { "attributes": { "prefix": "<custom_object_prefix>" }, "id": "<workspace_id>", "type": "workspace" } }'
The custom object prefix for your
<workspace_id>
is set to your<custom_object_prefix>
.You can verify the change was made successfully by making a GET call to the same API endpoint:
curl -X GET $HOST_URL/api/v1/entities/workspaces/<workspace_id> \ -H "Content-Type: application/vnd.gooddata.api+json" \ -H "Accept: application/vnd.gooddata.api+json" \ -H "Authorization: Bearer $API_TOKEN"
You should see your
<custom_object_prefix>
in theprefix
field, for example:{ "data": { "id": "af3d7591d8e5420fbde7a6b210347cfa", "type": "workspace", "attributes": { "name": "documentationDemoWorkspace", "prefix": "doc_demo_" } }, "links": { ... }
Object Identifiers in Past Versions of GoodData
Prior to the 9th of March 2023 release of GoodData Cloud, or prior to updating to GoodData.CN 2.3, object identifiers in workspace hierarchies worked differently.
See Changes to Workspace Object Identification.
This is important to take into account if you are updating your GoodData environment from an older version.
Discontinued Object ID Prefix
An object that was inherited from a parent workspace used to have its object ID augmented with the parent workspace id. For example if a metric with object id revenue
was inherited from a parent workspace parent_workspace_id
, in the child workspace its object ID would be parent_workspace_id:revenue
.
This has now been supplanted by the object origin property.
Conflicting Object IDs
As a result of discontinuing object ID prefixes, it is possible that you may end up in a situation where two objects share an identical object ID.
For example you might have had a workspace with the metric revenue
and an inherited metric parent_workspace_id:revenue
. But since prefixes are no longer supported, you cannot directly reference the parent_workspace_id:revenue
object; both objects will have the ID revenue
.
In such cases, we apply the “parent wins strategy”, where requesting the conflicting object ID revenue
will return only the object that is highest up in the workspace hierarchy. The child object is deleted.
List and Resolve Conflicting Object IDs
To find objects with conflicting object IDs, use one of the following API endpoints:
/api/v1/action/workspaces/<workspaceId>/overriddenChildEntities
List objects in child workspaces that were overridden by objects in the workspace
<workspaceId>
./api/v1/actions/workspaces/<workspaceId>/inheritedEntityConflicts
List objects in parent workspaces that are overriding objects in the workspace
<workspaceId>
.
To resolve an issue with conflicting object IDs, you must either change the object IDs so that they are all unique, or delete the overridden objects altogether.
You have to make the changes using the declarative API, as the overridden objects are not going to be available via entity API. Depending on the shape of your hierarchy, you have to use the API for:
- the whole organization (
/api/v1/layout/organization
) - or all workspaces (
/api/v1/layout/workspaces
) - or a single workspace (
/api/v1/layout/workspaces/{workspaceId}/...
+ theanalyticsModel
orlogicalModel
)