Groups and roles [VC 21.3 GEN] | Legacy 1 KB VidiNet

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