workspaces.rst

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 :ref:`apidocs` for the full API). It assumes that a functional client is available (see :ref:`buildinitclient`). 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'}]