Groups and roles [VC 21.3 GEN]

Manage groups and roles.

Managing groups

List all groups/roles

GET /group

Returns list of all groups.

Query Parameters:	first (integer) – Start returning groups from specified number. Default is `1`, the beginning of the list. number (integer) – Return at most specified number of groups. Default is no limit. role (boolean) – `true` - Return only roles. `false` - Return only regular groups. Default is to return all. New in version 4.16.
Produces:	application/xml, application/json – GroupListDocument text/plain – CRLF-delimited list of group URIs
Role:	_group_read

Retrieve a group/role

GET /group/(group-name)

Returns information about the specified group.

Produces:	application/xml, application/json – GroupDocument text/plain – The URI to the group.
Role:	_group_read

Retrieve role status

GET /group/(group-name)/role

Returns the role status of the specified group.

Produces:	text/plain – 1 if group is a role, 0 if group is a regular group
Role:	_group_read

Create a group

PUT /group/(group-name)

Creates a new group with the specified name.

Status Codes:	200 OK – Group created. 409 Conflict – A group with that name already exists.
Role:	_group_write

Update or create a group

PUT /group/(group-name)

Creates or updates the group with the specified name. Also any specified parent and child associations, users, metadata and description will be added.

Query Parameters:	clear (boolean) – `true` - Remove any existing groups and users not in the given document. `false` (default) - Existing groups and users not in the request document will be kept as is.
Status Codes:	200 OK – Group created.
Accepts:	application/xml, application/json – GroupDocument
Role:	_group_write

Delete a group

DELETE /group/(group-name)

Deletes the group with the specified name.

Role:

_group_write

Delete multiple groups

DELETE /group

Deletes the groups with the specified names.

Query Parameters:	name (string) – Required. Comma-separated list of group names.
Role:	_group_write

Example

DELETE /group?name=teachers,students,guests

Search for groups

PUT /group

Simple search of fields groupname, description and metadata.

Query Parameters:	first (integer) – Start returning groups from specified number. Default is `1`, the beginning of the list. number (integer) – Return at most specified number of groups. Default is `10`. role (boolean) – `true` - Return only roles. `false` - Return only regular groups. Default is to return all.
Accepts:	application/xml, application/json – GroupSearchDocument
Produces:	application/xml, application/json – GroupListDocument text/plain – CRLF-delimited list of group names

Example

PUT /group
Content-Type: application/xml

<GroupSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <field>
        <name>groupname</name>
        <value>vidi</value>
    </field>
    <field>
        <name>key</name>
        <value>value</value>
    </field>
</GroupSearchDocument>

Note that keywords groupname and description are reserved to do search on groupname and description fields

The boolean operators AND and OR are supported:

<GroupSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <field>
        <name>groupname</name>
        <value>vidi</value>
    </field>
    <field>
        <name>description</name>
        <value>vidispine</value>
    </field>
    <operator operation="OR">
        <field>
          <name>key1</name>
          <value>value1</value>
        </field>
        <field>
          <name>key2</name>
          <value>value2</value>
        </field>
    </operator>
</GroupSearchDocument>

Group information

Retrieve the group description

GET /group/(group-name)/description

Returns the descriptive text about the specified group.

Produces:	text/plain – Group description
Role:	_group_read

Update the description of a group

PUT /group/(group-name)/description

Changes the description of a group.

Accepts:	text/plain – The new description.
Role:	_group_write

Group-to-group relations

List all parent groups to a group

GET /group/(group-name)/parents

Returns groups that the specified group belongs to.

Query Parameters:	traverse (boolean) – `true` - Return all ancestors. `false` (default) - Return only direct parents.
Produces:	application/xml, application/json – GroupListDocument text/plain – CRLF-delimeted list of URIs to the groups
Role:	_group_read

List all child groups to a group

GET /group/(group-name)/children

Returns groups that belongs to the specified group.

Query Parameters:	traverse (boolean) – `true` - Return all descendants. `false` (default) - Return only direct children.
Produces:	application/xml, application/json – GroupListDocument text/plain – CCRLF-delimeted list of URIs to the groups
Role:	_group_read

Add a group to another group

PUT /group/(group-name)/group/(child-groupname)

Creates parent-child relation between the two specified groups.

Role:

_group_write

Remove a group from another group

DELETE /group/(group-name)/group/(child-groupname)

Removes the parent-child relation between the two specified groups.

Role:

_group_write

Group-to-user relations

List all users in a group

GET /group/(group-name)/users

Returns all users belonging to the group/role, directly or indirectly.

Query Parameters:	traverse (boolean) – `true` - Return all users, including users in child groups. `false` (default) - Return only direct users.
Produces:	application/xml, application/json – UserListDocument text/plain – CRLF-delimeted list of Tabbed tuples of user name, user real name
Role:	_group_read

Add a user to a group

PUT /group/(group-name)/user/(username)

Adds the specified user to the specified group.

Role:

_group_write

Remove a user from a group

DELETE /group/(group-name)/user/(username)

Removes the specified user from the specified group.

Role:

_group_write