Manage Users and UserGroups Together

Instead of managing the declarative layout for users and user groups individually, you can manage the declarative layout four users and user groups together through the following endpoint:

• /api/v1/layout/usersAndUserGroups

The default hostname for the application endpoint is determined by which edition of GoodData.CN you use:

• GoodData.CN
  https://{organization-hostname}/api/v1/layout/usersAndUserGroups
• GoodData.CN Community Edition
  http://localhost:{port}/api/v1/layout/userAndUserGroups

Where:

• {organization-hostname}
  Specifies the hostname for your organization with GoodData.CN. For example gooddata.com.
• {port}
  Specifies the port to access your installation of GoodData.CN Community Edition. The default port is 3000.

usersAndUserGroups Considerations

GoodData.CN expects all user details to be managed and stored in an external OIDC compatible service. The only details about users that are stored within the GoodData.CN platform are the user ID, the user authentication ID for the OIDC authentication provider, and any groups that the user belongs to. The only details available for the user groups are the identifier and a list of parents (user groups).

Write Operations

The following details must be present in the declarative payload when you issue a PUT request:

• The adminUser that was used to create the bootstrap token for the organization must always be present.
• The authentication identifier (authId) so that users can be authenticated through the OIDC provider.
• The user group that was used to create the bootstrap token for the organization must always be present.

Example Requests

The examples in this section are not meant to be used without modification. Please modify the examples to match the requirements of your site before using them.

Retrieve All Users and User Groups

The following example retrieves all of the users and user groups in your organization and stores the output in a JSON file named usersAndGroups-layout.json.

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  $HOST_URL/api/v1/layout/usersAndUserGroups > usersAndGroups-layout.json

Restore or Redefine All Users and User Groups

The following example replaces the users and user groups layout for the organization with that of a previously retrieved layout.

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X PUT \
  $HOST_URL/api/v1/layout/usersAndUserGroups -d @usersAndGroups-layout.json

Users and User Groups Layout Document Structure

The following example shows the layout for users and user groups when you issue a GET request to the declarative endpoint. AuthId is replaced by a dummy value.

{
   "userGroups" : [
      {
         "id" : "adminGroup"
      },
      {
         "id" : "develGroup"
      }
   ],
   "users" : [
      {
         "id" : "admin",
         "settings": [
            {
               "id": "timezone",
               "content": {
                  "value": "Europe/Prague"
               }
            }
         ],
         "userGroups" : [
            {
               "id" : "adminGroup",    
               "type" : "userGroup"
            }
         ]
      },
      {
         "authId": "<your-client-id>",
         "email": "<your-email>",
         "firstname": "<your-first-name>",
         "lastname": "<your-last-name>",
         "id" : "test",
         "settings": [
            {
               "id": "timezone",
               "content": {
                  "value": "Europe/Prague"
               }
            }
         ],
         "userGroups" : [
            {
               "id" : "develGroup",
               "type" : "userGroup"
            }
         ]
      }
   ]
}