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.

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

To create a root space, 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": {
      "name": "Headquarters"
    }
  }
}
  ' $ENDPOINT/api/v1/entities/workspaces

Invoke-RestMethod -Method Post -Uri "$ENDPOINT/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": {
      "name": "Headquarters"
    }
  }
}'

Create a Child 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": {
      "name": "Subsidiary I."
    },
    "relationships": {
      "parent": {
        "data": {
          "id": "headquarters",
          "type": "workspace"
        }
      }
    }
  }
}
  ' $ENDPOINT/api/v1/entities/workspaces

Invoke-RestMethod -Method Post -Uri "$ENDPOINT/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": {
      "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 \
 $ENDPOINT/api/v1/entities/workspaces/subs1?include=workspaces

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

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"
  }
}
  ' $ENDPOINT/api/v1/entities/workspaces/subs1

Invoke-RestMethod -Method Put -Uri "$ENDPOINT/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": {
      "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 $ENDPOINT/api/v1/entities/workspaces/subs1

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

Once you have built the workspace hierarchy, set up the 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