Page tree
Skip to end of metadata
Go to start of metadata

This article is part of the Powered By GoodData Tutorial. Some aspects may not apply to other implementation scenarios.

For Powered By GoodData implementations, you must create mechanisms by which you can provision new users to their projects. These mechanisms utilize documented GoodData APIs.

Defining Users and Roles

During this phase, you must specify the users and their roles for each of your projects. As part of this mapping, one user account (UserID) may apply to multiple projects. For example, one Administrator may be managing multiple projects.

Best practice is for one account to be both the organization owner and admin of all projects. The organization owner can add users to the organization, but the project administrator is required to add the user to a project.

Each project should have at least one project administrator. For a Powered By GoodData implementation, this user account can be internal to your enterprise or part of the customer’s user community. The account you used to create the project is automatically provisioned administrator permissions and should not be counted toward fulfilling this requirement.

You may also choose to set up another account for managing all data loads and another one as a backup administrator for each project.

In the user and role mapping, the combination of user and project is the unique identifier of an entry, since one user may belong to multiple projects.

Organizing users

A recommended approach is to create a spreadsheet containing the following columns. In this sheet, there are multiple entries for each of the main information categories: User, Project, and Role.

Since you are likely to be assigning users and roles to projects via API, the internal identifiers for these items should be tracked. However, if you have a different mechanism for tracking those values, you may remove these columns from this sheet.

FieldDescription
IndexYou may wish to maintain identifiers within the spreadsheet for each of the user-project entries.
User EmailValid email address of the user. This address is used when delivering system messages or report and dashboard exports to the user. See Uniqueness in Identifiers.
UserIDInternal identifier of the user. This ID must be in the form of an email address, although it does not have to be a valid email address. Domain information should be included. See Uniqueness in Identifiers.
User Password

When you create the account via API, you must submit the password for the account as well. You should create random secure passwords for each user account. Users can change their passwords from within the project.

This password is functional for direct access to the GoodData Portal, even if SSO is enabled. GoodData recommends generating random, hard-to-guess strings for all user passwords. Users can their reset passwords from within the GoodData Portal.

Project NameName of the project to which the user is being assigned
ProjectIDInternal identifier of the project to which the user is being assigned. This value is acquired via API.
User Role NameName of the role to which the user is being assigned for this project (Embedded Dashboard Only, Viewer, Editor, Administrator, or other value if you are assigning custom roles)
RoleIDInternal identifier of the role within the project. This value is acquired via API.

Uniqueness in Identifiers

USERID UNIQUENESS

In creating a user identifier within the GoodData organization, you should create it in the following format:

First.Last+MyDomain@MyDomain.com


During authentication to the GoodData platform, the GoodData Portal has no awareness of domain organization context; all user are authenticated against the entire set of users. So, if you limit the user identifier to just the email address, you could run into conflicts if that email address is present in the set of users of another GoodData customer.

EMAIL ADDRESSES FOR USERS

For the email address value that is posted as part of the JSON, you can use remove the domain information, so that the email address value for the above user is the following:

First.Last@MyDomain.com


UNIQUENESS WITHIN THE GOODDATA PLATFORM

Within the platform, the combination of UserID and ProjectID should be unique; one user can only be assigned one role in a project.

  • Each user does not have to be provisioned in each project.

Methods for Integrating Users

Whether you are integrating users for a single project or across multiple projects, the process of integration is similar. For multi-project deployments, however, there are additional pre-requisites.

  • In most implementations, users are integrated into a project via API.
  • For each Project and Role within the project, you must retrieve the corresponding identifiers via API. Instructions are provided later in this document.

Users may be added to a project using one of the following methods:

  • Manual invitation: A project Administrator manually enters the user’s email address through the GoodData Portal, and an email invitation is delivered to the user, to which the user responds to begin engaging with the project.

    This email invitation includes GoodData branding, unless white labeling has been applied.

  • API invitation: Through the GoodData APIs, you can invite users to projects. When the API is successfully executed, an email invitation is delivered to the user.
  • API addition: Through the GoodData APIs, you can add users to projects. These additions do not cause an email to be generated. These users must be updated separately to be notified about the project.

These options are described below.

Adding Users via Script

GoodData provides a set of provisioning scripts, which can be modified and used to manage users in your projects.

These scripts are considered an option to using the APIs for specific project-related tasks. They require scripting knowledge to implement.

Instructions are included in the download package.

Adding Users via API

Please use the following general steps to add users to a project. Using the GoodData APIs, you can build the scripts necessary to provision users.

Do not invite users to their projects until data for the project has been loaded and any Data Permissions have been applied.

For more information on the GoodData APIs, see API Documentation.

Your Create User script should perform the following basic steps to create a new user and assign it to a project and a specific role within that project.

These API calls must be executed using the domain owner account. As part of the API calls, you must reference the internal user identifier of the domain owner account. See API Documentation.

Identify user

These steps are used to identify an existing user that you wish to add to a project.

Steps:

  1. For purposes of using the APIs, you need the following information: User Email, UserID, Project Name, User Role Name.
  2. You must acquire the internal identifier for the project to which you are assigning the user. Using the user ID of the domain owner account, you can acquire the list of all projects in the domain with the following API call:
TypeGET
URI/gdc/account/profile/{user-id}/projects


In the returned JSON, search for the Project Name value, which appears in the following name-value pair:

"title" : "Your Project Name",


From other name-value pairs in the same section, you can extract the project identifier.

See  Project API doc.

Acquire roleID

The user roles for each project have identifiers that are unique to the project; the roleID for one project is not the same as the roleID for another project.

Steps:

  1. Using the projectID that you retrieved, you can execute the following API call to retrieve all roles for the project:

    Type

    GET

    URI

    /gdc/projects/{project-id}/roles

  2. The list of available roles and their internal roleIDs in the project is displayed. For each listed role, you can execute the following API call to return role details, including its corresponding display name:

    Type

    GET

    URI

    /gdc/projects/{project-id}/roles/{role-id}

  3. In the returned JSON, search for the title name-value pair, as in the following example:

    "title": "Embedded Dashboard Only",
  4. The value of title corresponds to the User Role Name value that you wish to assign to the customer. You must do the assignment by referencing the corresponding role-id value.

 The value of the role-id should be added to your user tracking system.

For more information, see user API doc.

Add the user

Use the following API to create the user account.

TypePOST
URI/gdc/account/domains/{domain-name}/users

The submitted POST needs to be specified as follows:

Accept: application/json
Content-Type: application/json
{
	"accountSetting":{
		"login": "user@login.com",
		"password":"PASSWORD",
		"email":"contact@email.com",
		"verifyPassword":" PASSWORD ",
		"firstName":"FirstName",
		"lastName":"LastName",
		"ssoProvider":"SSO-PROVIDER"
	}
}


The returned JSON includes a URI, at the end of which is the internal profileID for the user.

This value should be added to your user tracking system.

Assign user to project with a specified role

In this step, you add the user to the project and assign a role to the user at the same time. Users may be added by: 1) inviting them or 2) silently adding them.

Steps:

Inviting users to a project generates an email from the GoodData platform, which may or may not be desirable, and enables them to access the project immediately. If you are applying Data Permissions to the project’s users, those Data Permissions filters must be applied immediately after the user is created. Otherwise, invited users can see all data until the Data Permissions filters are applied.

  1. Use the following API to add a user to a project. This user is not informed of the addition:

    TypePOST
    URI/gdc/projects/{project-id}/users
  2. The POST must be formatted in the following manner and must contain the projectID and roleID in the userRoles value:

    Accept: application/json
    Content-Type: application/json
    { "user" : {
    	"content" : {
    		"status":"ENABLED",
    		"userRoles":["/gdc/projects/{project-id}/roles/{role-id}"]
    			},
    		"links" : {
    			"self":"/gdc/account/profile/{user-id}"
    			}
    	}
    }

Inviting the user

You can use the following API to invite a user to the project. This API call generates an email with GoodData branding. Upon acceptance, the user can immediately begin using the project, so any Data Permissions must be already in place.

Steps:

  1. Inviting the user. You can use the following API call to invite the user to the specified project. If the user accepts the email invitation, the user is added to the project and assigned the designated user role:

    /gdc/projects/{project-id}/invitations
  2. The POST must be submitted in the following format:

    {
    	"invitations": [
    		{
    			"invitation": {
    				"content": {
    					"email": "invited.user.mail@company.com",
    					"role": "/gdc/projects/{project-id}/roles/{role-id}",
    					"firstname": "firstname",
    					"lastname": "lastname",
    					"action": {
    						"setMessage": "You can set message here!"
    					}
    				}
    			}
    		}
    	]
    }
  3. The user has been invited and assigned to the designated project in the selected role.

 

Read next

  • No labels