Workspaces

How To Create A Workspace And Add User To It


💡 3 min read

Workspaces help keep your work organized. Once a workspace has users, you can share content that you've uploaded with them.

You can see the current sharing status on any resource by querying the @sharing endpoint.

You can always check the results of the API calls on your Onna account.

# Before You Begin

Make sure that you're authenticated with your Onna instance.

# Create A Workspace

You'll create a workspace, which for us is another content type created with a POST.

First, lets see if there are any workspaces associated with our user.

headers = {'Accept': 'application/json', 'Authorization': "Bearer {}".format(jwt_token)}
resp = requests.get(f'{base_url}/api/{container}/{account}/@workspaces', headers=headers)
print(f"Workspaces: {resp.json()}")
1
2
3

Unless you've already created a workspace either through the Web interface or the API, the response is an empty array.

Now, you can create a new workspace and store it's uid in a variable workspace_uid.

workspace_uid = None
payload = {
    "@type": "Workspace",
    "title": "Legal"
}
resp = requests.post(f"{base_url}/api/{container}/{account}/workspaces", headers=headers, data=json.dumps(payload))
workspace_uid = resp.json()['@uid']
print(resp.json())
1
2
3
4
5
6
7
8

With that POST, you created a workspace named "Legal".

The returned values include the @id combined with other metadata such as creation_date and the owners.

In subsequent calls, you'll refer to this workspace by its @uid, such as when you add users to this workspace.

You'll save the @uid value in a variable to use when you add a user to the workspace.

# Add A User To A Workspace

There are four roles a user can have when added to a workspace.

The role is set when the user is added to the workspace.

To add a user to a workspace, you'll do a POST to the workspace URLs @sharing endpoint.

The permissions that a user can have in a workspace are as follows:

For additional information on the roles and permissions used in Onna, please see Guillotina developer documentation

guillotina.Owner: Can Invite Users to the Workspace and Add Data Sources
guillotina.Editor: Can add Datasources and Edit Workspace, Datasource and Files
onna.Contributor: Can add Datasources and Files
guillotina.Reader: Can View Files in the Workspace
1
2
3
4
payload = {
"prinrole": [{
        "setting": "Allow",
        "principal": "another_user@onna.com",
        "role": "onna.Contributor"
    }
],
"magic_url": true,
"notify": true,
"notify_message": ""
}

resp = requests.post(f"{base_url}/api/{container}/{account}/workspaces/{workspace_uid}/@sharing",
                     headers=headers,
                     data=json.dumps(payload)
                    )
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

The response JSON should be a 200 with an empty body.

This also applies to adding User Groups to a workspace, together with adding multiple users/groups at once.

{
"prinrole": [{
        "setting": "Allow",
        "principal": "7cf46566-c4db-11e9-b7a7-921bb8ebe70b",
        "role": "guillotina.Editor"
    }, {
        "setting": "Allow",
        "principal": "another.user@onna.com",
        "role": "guillotina.Editor"
    }
],
"magic_url": true,
"notify": true,
"notify_message": ""
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Above, the first principal is the uid of a group of users. The second principal value is another user.

# Remove A User From A Workspace

In case you need to remove a user from a workspace, that is done through the same endpoint.

payload = {
"prinrole": [{
        "setting": "Unset",
        "principal": "a_user@onna.com",
        "role": "onna.Contributor"
    }, {
        "setting": "Unset",
        "principal": "another_user@onna.com",
        "role": "guillotina.Editor"
    }
],
"notify": false
}

resp = requests.post(f"{base_url}/api/{container}/{account}/workspaces/{workspace_uid}/@sharing",
                     headers=headers,
                     data=json.dumps(payload)
                    )
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

It is important to note that the role you are removing needs to be the role that the user had.

# Recap

You created a new workspace, and added a user to it.

Last Updated: 7/16/2020, 1:03:29 PM