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>

Object Identifiers in Past Versions of GoodData

Prior to the 23rd of February 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.

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}/... + the analyticsModel or logicalModel)