Manage Workspaces
Learn how to create a Workspace and add a user to it
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()}")
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())
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 (opens new window)
Role | Description |
---|---|
guillotina.Owner | Can Invite Users to the Workspace and Add Datasources |
guillotina.Editor | Can Add Datasources and Edit the Workspace, Datasources and Files |
onna.Contributor | Can Add Datasources and Files |
guillotina.Reader | Can View Files in the Workspace |
payload = {
"prinrole": [{
"setting": "Allow",
"principal": "user@domain.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)
)
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": "user@domain.com",
"role": "guillotina.Editor"
}
],
"magic_url": true,
"notify": true,
"notify_message": ""
}
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": "user1@domain.com",
"role": "onna.Contributor"
}, {
"setting": "Unset",
"principal": "user2@domain.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)
)
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.