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_):

Example of custom prefix in metric ID

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_ and EU__.
  • Avoid making your prefix in a child workspace a subpart of your parent workspace prefix, such as having prefix EU__ in the parent, and EU_ 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:

  1. 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>.

  2. 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 the prefix 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}/... + the analyticsModel or logicalModel)
Entity API Interface
Objects Organization