Workspaces

Workspaces provide a means to collect multiple typed objects (TOs) into one container and share the container with other people. This documentation will demonstrate some of the most common operations on workspaces (see Workspace API documentation for the full API). It assumes that a functional client is available (see Build and initialize the workspace client). The examples use the Python client, but translating to other clients is trivial.

Creating workspaces

Create a workspace called MyWorkspace:

In [4]: ws.create_workspace({'workspace': 'MyWorkspace'})
Out[4]:
[12,                             # workspace numerical ID
 u'MyWorkspace',                 # workspace name
 u'kbasetest',                   # workspace creator
 u'2015-12-13T20:48:00+0000',    # modification date of the workspace
 0,                              # number of objects created in this workspace
 u'a',                           # user's permission for the workspace
 u'n',                           # global permissions for the workspace
 u'unlocked',                    # whether the workspace is locked
 {}]                             # user provided metadata

Once created, a workspace’s numerical ID is permanent and unchangeable. A locked workspace cannot be altered (other than making it world-readable).

Note that the object count is the total objects ever created in this workspace, not the currently existing objects.

Permissions

Permissions are coded according to the following table:

Permission	Allows
n	No access
r	Read access
w	Write access, see permissions of other users
a	Admin access, set permissions of other users

A workspace can have a description and arbitrary key-value metadata associated with it:

In [5]: ws.create_workspace({'workspace': 'MyOtherWorkspace',
   ...:                      'description': 'Workspace for other things',
   ...:                      'meta': {'contents': 'other things',
   ...:                               'project_id': '42'}
   ...:                      })
Out[5]:
[13,
 u'MyOtherWorkspace',
 u'kbasetest',
 u'2015-12-13T20:51:57+0000',
 0,
 u'a',
 u'n',
 u'unlocked',
 {u'contents': u'other things', u'project_id': u'42'}]

Retrieving information about workspaces

The workspace description and information list can be retrieved:

In [6]: ws.get_workspace_description({'id': 13}) # retrieving by ID
Out[6]: u'Workspace for other things'

In [11]: ws.get_workspace_info({'workspace': 'MyOtherWorkspace'})
Out[11]:
[13,
 u'MyOtherWorkspace',
 u'kbasetest',
 u'2015-12-13T20:51:57+0000',
 0,
 u'a',
 u'n',
 u'unlocked',
 {u'contents': u'other things', u'project_id': u'42'}]

Listing workspaces

Workspaces with at least read access can be listed:

In [8]: ws.list_workspace_info({})
Out[8]:
 [12,
  u'MyWorkspace',
  u'kbasetest',
  u'2015-12-13T20:48:00+0000',
  0,
  u'a',
  u'n',
  u'unlocked',
  {}],
 [13,
  u'MyOtherWorkspace',
  u'kbasetest',
  u'2015-12-13T20:51:57+0000',
  0,
  u'a',
  u'n',
  u'unlocked',
  {u'contents': u'other things', u'project_id': u'42'}]]

The list can be filtered in several ways. Here it’s filtered by the user provided metadata:

In [10]: ws.list_workspace_info({'meta': {'project_id': '42'}})
Out[10]:
[[13,
  u'MyOtherWorkspace',
  u'kbasetest',
  u'2015-12-13T20:51:57+0000',
  0,
  u'a',
  u'n',
  u'unlocked',
  {u'contents': u'other things', u'project_id': u'42'}]

Sharing workspaces

Users with admin privileges with to a workspace can allow other users to read, write to, and administrate the workspace. These privileges apply to all objects contained in the workspace.

In [12]: ws.set_permissions({'workspace': 'MyWorkspace',
                             'users': ['kbasetest2'],
                             'new_permission': 'a'
                             })

In [13]: ws.set_permissions({'workspace': 'MyWorkspace',
                             'users': ['kbasetest8'],
                             'new_permission': 'r'
                             })

In [16]: ws.get_permissions_mass([{'id': 12},
                                  {'workspace': 'MyOtherWorkspace'}
                                  ])
Out[16]:
[{u'kbasetest': u'a', u'kbasetest2': u'a', u'kbasetest8': u'r'},
 {u'kbasetest': u'a'}]