Build a Workspace Hierarchy

A workspace hierarchy in an multitenant environment defines how entities of a particular tenant (parent workspace) can be shared with other tenants (child workspaces) in read-only mode. The child workspaces use the parent workspace’s logical data model (LDM), analytical model, connected data sources and so on. Once the parent workspace gets a new entity, it becomes available to its child workspaces.

Child workspaces inherit entities from their parent workspace and the parent workspace’s parent workspace up to the root workspace. The root workspace is the top-level workspace in the hierarchy and does not have a parent workspace. You can have as many root workspaces as you need.

Please note that you require the appropriate hierarchyPermissions in order to access or edit workspaces inside a workspace hierarchy.

How Child-Parent Relations Work

While entities from a parent workspace are available in its child workspaces in read-only mode, you can add new entities to the child workspaces. For example, you can create more visualizations in addition to those inherited from the parent workspace. These new entities will be available to these workspaces’ child workspaces at any hierarchy level downwards, if any exist, but will not be available to the parent workspace.
Although the child workspaces use the same entities as their parent workspace does, you can limit the data available in the child workspaces. For example, a parent workspace may contain a visualization displaying the data from all company departments, but a child workspace will see only the Sales department-related data in this visualization. To limit the data, use data filters.
You can reference entities from the parent workspace in the child workspaces using fully qualified references.

Create a Root Workspace

API

To create a root (i.e. top-level parent) workspace, open the Workspaces tab and click Create Workspace.

Once the workspace is created, click its row in the list to open the workspace details. There, you can connect data, manage users, create a child workspace etc.

To create a root workspace, submit a POST request to /api/v1/entities/workspaces.

Bash

PowerShell 7

curl -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -X POST \
  -d '
{
  "data": {
    "id": "headquarters",
    "type": "workspace",
    "attributes": {
      "description": "My root workspace.",
      "name": "Headquarters"
    }
  }
}
  ' $HOST_URL/api/v1/entities/workspaces

Invoke-RestMethod -Method Post -Uri "$HOST_URL/api/v1/entities/workspaces" `
  -ContentType 'application/vnd.gooddata.api+json' `
   -H @{ 
     'Accept' = 'application/vnd.gooddata.api+json'
     'Authorization' = "Bearer $API_TOKEN" 
   } `
   -Body '
{
  "data": {
    "id": "headquarters",
    "type": "workspace",
    "attributes": {
      "description": "My root workspace.",
      "name": "Headquarters"
    }
  }
}'

Create a Child Workspace

API

To create a child workspace, open the Workspaces tab and click the root workspace, i.e. the one that the child workspace should be related to.

In the root workspace details, click Create child workspace and fill in its details. You can also see the list of all the child workspaces related to this specific root workspace.

To create a child workspace, submit a POST request to /api/v1/entities/workspaces.

The workspace that will become the parent workspace for the newly created child workspace must already exist.

Bash

PowerShell 7

curl -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -X POST \
  -d '
{
  "data": {
    "id": "subs1",
    "type": "workspace",
    "attributes": {
      "description": "My child workspace.",
      "name": "Subsidiary I."
    },
    "relationships": {
      "parent": {
        "data": {
          "id": "headquarters",
          "type": "workspace"
        }
      }
    }
  }
}
  ' $HOST_URL/api/v1/entities/workspaces

Invoke-RestMethod -Method Post -Uri "$HOST_URL/api/v1/entities/workspaces" `
  -ContentType 'application/vnd.gooddata.api+json' `
   -H @{ 
     'Accept' = 'application/vnd.gooddata.api+json'
     'Authorization' = "Bearer $API_TOKEN" 
   } `
   -Body '
{
  "data": {
    "id": "subs1",
    "type": "workspace",
    "attributes": {
      "description": "My child workspace.",
      "name": "Subsidiary I."
    },
    "relationships": {
      "parent": {
        "data": {
          "id": "headquarters",
          "type": "workspace"
        }
      }
    }
  }
}'

Get Information about a Workspace

To get basic information about a workspace, submit a GET request to /api/v1/entities/workspaces/<workspace-id>.

To get basic information about a workspace and its parent workspace, submit a GET request to /api/v1/entities/workspaces/<workspace-id>[?include=workspaces].

Bash

PowerShell 7

curl -H "Authorization: Bearer $API_TOKEN" -X GET \
 $HOST_URL/api/v1/entities/workspaces/subs1?include=workspaces

Invoke-RestMethod -Method GET -Uri "$HOST_URL/api/v1/entities/workspaces/subs1?include=workspaces" `
   -H @{ 'Authorization' = "Bearer $API_TOKEN" }

To get child workspaces of a specific parent workspace, search for all workspaces while filtering by the parent workspace:

/api/v1/entities/workspaces?include=workspaces&parent.id=<parent-workspace-id>

Change a Workspace’s Parameters

To change a workspace’s parameters, submit a PUT request to /api/v1/entities/workspaces/<workspace-id>.

You cannot update a workspace’s id property or its parent workspace.

Bash

PowerShell 7

curl -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -X PUT \
  -d '
{
  "data": {
    "attributes": {
      "name": "updated-child"
    },
    "id": "subs1",
    "type": "workspace"
  }
}
  ' $HOST_URL/api/v1/entities/workspaces/subs1

Invoke-RestMethod -Method Put -Uri "$HOST_URL/api/v1/entities/workspaces/subs1" `
  -ContentType 'application/vnd.gooddata.api+json' `
   -H @{ 
     'Accept' = 'application/vnd.gooddata.api+json'
     'Authorization' = "Bearer $API_TOKEN" 
   } `
   -Body '
{
  "data": {
    "attributes": {
      "description": "My child workspace.",
      "name": "updated-child"
    },
    "id": "subs1",
    "type": "workspace"
  }
}'

Delete a Workspace

To delete a workspace, submit a DELETE request to /api/v1/entities/workspaces/<workspace-id>.

You cannot delete a workspace that has child workspaces.

Bash

PowerShell 7

curl -H "Authorization: Bearer $API_TOKEN" -X DELETE $HOST_URL/api/v1/entities/workspaces/subs1

Invoke-RestMethod -Method Delete -Uri "$HOST_URL/api/v1/entities/workspaces/subs1" `
   -H @{ 'Authorization' = "Bearer $API_TOKEN" }

Once you have built the workspace hierarchy, set up the workspace data filters. Only users with the Organization.MANAGE permission or the Workspace.MANAGE hierarchyPermission can create, read, update, or delete workspace data filters.

Other Available Operations

In addition to creating, updating, and deleting workspaces, you can also work with the workspaces and their metadata using the entity API interface and the declarative API interface.

Set Up Data Filters in Workspaces