GoodData.CN: Workspace Hierarchy and Inheritance Tutorial

3 years ago
15 April 2021
0 replies
305 views

tereza.cihelkova
GoodData Employee
0 replies

Introduction

One of the key features of GoodData.CN that makes multi-tenancy easy is workspace hierarchy. It allows you to set up parent-child relationships between workspaces. The child workspaces inherit the logical data model, insights, and dashboards from their parents. This means that you can easily:

provision workspaces with pre-built content for each of your customers or teams
update the pre-built content in all child workspaces by simply updating the content in their parent workspace

Step by Step Tutorial

Prepare a Parent Workspace

To test this out, you need one workspace with some content. You can either use a workspace you’ve built, or you can download and import a layout we prepared for you. The layout is designed to work with the sample Postgresql database that is a part of the GoodData.CN Community Edition.

To import the layout we provided, go to the Homepage in the browser and create an empty workspace by clicking on “Create workspace”:

Next, click on “Connect Data”. If this is the first time you are using the pre-installed database, a pop-up will show up. Select “Connect demo data” to continue. This will connect the workspace to the sample database that comes pre-installed with the GoodData.CN Community Edition.

Clicking on the button should take you to the workspace’s data modeler. Here click on “Create model” and click the “Scan button”.

Uncheck the “Generate datasets” checkbox in the dialog that pops up and hit “Scan”. This downloads and saves the schema of the source database so that it knows what tables it contains.

For the next step, you’ll need to know the workspace’s ID. The ID is a string that will show in the URL address while you are inside of the workspace like:

Download the layout JSON if you haven’t done so yet. To import it into the empty workspace you just created, you’ll need to issue an API call. The below example illustrates how you can issue the call from a mac terminal, but you can use postman or other tools on different platforms:

curl http://localhost:3000/api/layout/workspaces/<workspace_id>\
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -X PUT \
  -d @freelayout.json

TIP: the API calls shown in this tutorial are set up to work against the GoodData.CN Community Edition with standard port settings. If you are using a different edition of GoodData.CN, do not forget to adjust the URL and the authorization token accordingly.

Once the layout is imported, refresh the workspace in your browser, and you should be able to see sample LDM and dashboards.

This workspace will become the parent workspace.

Create a Child Workspace

To create a parent-child relationship, you need to create a new empty workspace and define a parent property. This is done via APIs. There are two different APIs you can use. In this tutorial, we’ll use an entity API that lets you create workspaces one by one.

Post the following payload to the entities API to create a new workspace called Child 1 that inherits content from the demo workspace. Do not forget to replace the <workspace_id> with the ID of your parent workspace.

curl http://localhost:3000/api/entities/workspaces \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -X POST \
  -d '{
      "data": {
        "attributes": {
          "name": "Child 1"
        },
        "id": "child1",
        "type": "workspace",
        "relationships": {
          "parent": {
            "data": {
              "id": "<workspace_id>",
              "type": "workspace"
            }
          }
        }
      }
      }'

Go to the homepage in your browser. You should be able to see the new Child 1 workspace listed there.

The workspace contains the same data model, dashboards, and insights as does the Parent workspace.

Testing out the inheritance feature

Switch to the parent workspace and go to the Dashboards. Create a new dashboard and add insight to it and publish the dashboard.

Now switch to the child workspace and go to Dashboards. You’ll see the new Dashboard you created in the parent workspace in the Child too. All changes you make in the parent workspace are immediately available in all child workspaces. Notice you cannot edit the dashboard. It is set to read-only, but you can create your own copy by clicking “Save as new”.

Now try to create a new dashboard in the Child workspace and save it. Switch to the parent workspace and go to Dashboards. Notice that you cannot see the Dashboard you created in the Child workspace here. The content propagates only from Parent to Child, not the other way around.

To sum it up, you can easily make changes to any inherited content in child workspaces by making the change to the parent. At the same time, the child workspaces' end-users can create their own custom insights and dashboards that will be only available in their workspace. The users in child workspaces cannot edit or delete the content that is inherited from the parent workspace.

Different Data for Different Workspaces

One important thing we didn’t talk about is the data. Right now, both workspaces sit over the same database and pull the same data. In the case of customer-facing analytics, you typically want to expose only a subset of the data to each customer - their data. For that purpose, GoodData.CN offers so-called workspace data filters, which allow you to filter what data is available for each of the workspaces. To learn more about the data filters, review the documentation.

GoodData.CN: Workspace Hierarchy and Inheritance Tutorial

Introduction