Provisioning Users to Domains and Workspaces

This article discusses the user provisioning process within the GoodData platform.

User provisioning covers all aspects of creating, updating, and deleting users in your GoodData domain and provisioning them to workspaces.

The following illustration provides the relationship between a domain and a workspace, and their respective administrators:

For more information about domains, see Your GoodData Domain.

Using GoodData APIs for User Provisioning

GoodData API allows you to automate user provisioning tasks on both the domain and the workspace level.

Using this process involves two steps:

1. Build User Provisioning - To enable user provisioning within your GoodData domain, you can use scripts provided by GoodData to interact with the GoodData APIs, or you can build your own tools to manage the API calls.
2. Execute User Provisioning - After you have built the user provisioning mechanism and tested it, you need to use it to add your users.

Creating a User in a Domain

Before you can add or invite a user to a workspace, you must create them in your domain. Domain administrators can create, manage and delete users in a domain. 

When a user is created to the domain, they cannot access data in any of the workspaces.

• Method: POST
• URL: https://secure.gooddata.com/gdc/account/domains/{domain_name}/users
• Response: 201 Created  Includes the URI of the newly created user in the following format: /account/profile/{user_id}

Body:

{
  "accountSetting": {
    "login": "{user_login@company.com}",
    "firstName": "{first_name}",
    "lastName": "{last_name}
  }
}

In the request body, specify the following mandatory parameters:

• login (string in the format of an email address) is the user login. Once created, this property cannot be updated. The login must be a string in the format of an email address but does not have to be an actual working email address. You can generate logins from unique user IDs used on your site (for example, 123456@gd.example.com, 234567@gd.example.com, and so on). For receiving emails sent by GoodData (such as notifications or scheduled emails), you set the email for each user via the optional email property. A user’s email can (but does not have to) be the same as the login. The email does not have to be unique within the domain. The login is case-sensitive and must be written in lowercase.

  • Correct: john.doe@example.com

  • Incorrect: John.Doe@example.com

• firstName (string) is the user’s first name.

• lastName (string) is the user’s last name.

For more information about these mandatory parameters and the optional parameters that you can add to the user, see the API for adding users to a domain.

Response:

Adding or Inviting Users to a Workspace

Domain users cannot access a particular workspace, unless they are invited or add ed to that workspace. The two methods differ in how the user is notified about being added.

• When you add a user to a workspace, the user is not immediately informed of the access.
• When you invite a user to a workspace, the user receives an email with a link. When the user clicks the link, they can immediately access the workspace and its contents.

There are two ways to add a user to workspace on the GoodData platform.

• You can invite users through the GoodData Portal’s user interface.
• You can add or invite users through the GoodData REST APIs.

Workspace administrators who are not also domain administrators can only invite users to their workspace. 

Adding Users Using Rest APIs

After the user is added to the domain, you can add or invite the user to individual workspaces.

When you are adding or inviting a user to a workspace, assign the user a specific user role in the workspace. A user role defines the permissions available to the assigned user account. For more information, see User Roles.

User roles are referenced by their IDs. These IDs are specific to a workspace. For each workspace where you are adding or inviting a user, acquire the user role ID to assign to the user.

Steps:

1. Acquire all user roles from the workspace (see the API for obtaining project user roles).

   • Method: GET

   • URL: https://secure.gooddata.com/gdc/projects/{workspace_id}/roles

   • The response includes the IDs for each user role in the workspace in the following format: /gdc/projects/{workspace_id}/roles/{role_id}

2. Acquire information about the user role that you want to give to the user (see the API for a specific user role).

   • Method: GET

   • URL: https://secure.gooddata.com/gdc/projects/{workspace_id}/roles/{role_id}

   • The response includes permissions for the specific role.

3. Do one of the following:

   • Add the user: The user is added to the workspace silently and does not know that access has been provided. This information must be communicated through a different mechanism (for example, inviting the user to the workspace).
   • Invite the user to the project: The user receives an email invitation and can access the workspace immediately.

Add the User to a Workspace

See the API for adding users.

• Method: POST
• URL: https://secure.gooddata.com/gdc/projects/{workspace_id}/users
• Response: 200 OK

Body:

{
  "user": {
    "content": {
      "status": "ENABLED",
      "userRoles": ["/gdc/projects/{workspace_id}/roles/{role_id}"]
    },
    "links": {
      "self": "/gdc/account/profile/{user_id}"
    }
  }
}

Invite the User to a Workspace

See the API for inviting users.

• Method: POST
• URL: https://secure.gooddata.com/gdc/projects/{workspace_id}/invitations
• Response: 200 OK

Body:

{
  "invitations": [
    {
      "invitation": {
        "content": {
          "email": "{invited-user-email@company.com}",
          "userFilters": [ "/gdc/md/{workspace_id}/obj/{filter_object_id}" ], 
          "role": "/gdc/projects/{workspace_id}/roles/{role_id}",
          "firstname": "{first_name}",
          "lastname": "{last_name}",
          "action": {
            "setMessage": "{message_for_invited_user}"
          }
        }
      }
    }
  ]
}

Response:

User Roles

When a user is added to a workspace, the user must be assigned a role within the workspace. For more information, see User Roles.