API endpoint base: https://pirca.arvadosapi.com/arvados/v1/groups
Object type: j7d0g
Example UUID: zzzzz-j7d0g-0123456789abcde
Groups provides a way to apply the same permissions to a set of Arvados objects. See permission model for details.
Each Group has, in addition to the Common resource fields:
Attribute | Type | Description | Example |
---|---|---|---|
name | string | ||
group_class | string | Type of group. project and filter indicate that the group should be displayed by Workbench and arv-mount as a project for organizing and naming objects. role is used as part of the permission system. |
"filter" "project" "role" |
description | text | Free text description of the group. May be HTML formatted, must be appropriately sanitized before display. | |
properties | hash | User-defined metadata, may be used in queries using subproperty filters | |
writable_by | array | (Deprecated) List of UUID strings identifying Users and other Groups that have write permission for this Group. Users who are allowed to administer the Group will receive a list of user/group UUIDs that have permission via explicit permission links; permissions via parent/ancestor groups are not taken into account. Other users will receive a partial list including only the Group’s owner_uuid and (if applicable) their own user UUID. | |
can_write | boolean | True if the current user has write permission on this group. | |
can_manage | boolean | True if the current user has manage permission on this group. | |
trash_at | datetime | If trash_at is non-null and in the past, this group and all objects directly or indirectly owned by the group will be hidden from API calls. May be untrashed as long as delete_at is in the future. |
|
delete_at | datetime | If delete_at is non-null and in the past, the group and all objects directly or indirectly owned by the group may be permanently deleted. |
|
is_trashed | datetime | True if trash_at is in the past, false if not. |
|
frozen_by_uuid | string | For a frozen project, indicates the user who froze the project; null in all other cases. When a project is frozen, no further changes can be made to the project or its contents, even by admins. Attempting to add new items or modify, rename, move, trash, or delete the project or its contents, including any subprojects, will return an error. |
Groups with group_class: project
are used to organize objects and subprojects through ownership. When trashed or deleted, all items owned by the project (including subprojects, collections, or container requests) as well as permissions (permission links) granted to the project are also trashed or deleted.
Groups with group_class: role
are used to grant permissions to users (or other groups) through permission links. Role groups can confer “can_manage” permission but cannot directly own objects. When trashed and deleted group membership and permission grants (expressed as permission links) are deleted as well.
Groups with group_class: filter
groups are virtual groups; they can not own other objects, but instead their contents (as returned by the contents API method) are defined by a query. Filter groups have a special properties
field named filters
, which must be an array of filter conditions. See list method filters for details on the syntax of valid filters, but keep in mind that the attributes must include the object type (collections
, container_requests
, groups
, workflows
), separated with a dot from the field to be filtered on.
Filters are applied with an implied and between them, but each filter only applies to the object type specified. The results are subject to the usual access controls – they are a subset of all objects the user can see. Here is an example:
"properties":{ "filters":[ [ "groups.name", "like", "Public%" ] ] },
This filter
group will return all groups (projects) that have a name starting with the word Public
and are visible to the user issuing the query. Because groups can contain many types of object, it will also return all objects of other types that the user can see.
The ‘is_a’ filter operator is of particular interest to limit the filter
group ‘content’ to the desired object(s). When the ‘is_a’ operator is used, the attribute must be ‘uuid’. The operand may be a string or an array which means objects of either type will match the filter. This example will return all groups (projects) that have a name starting with the word Public
, as well as all collections that are in the project with uuid zzzzz-j7d0g-0123456789abcde
.
"properties":{ "filters":[ [ "groups.name", "like", "Public%" ], [ "collections.owner_uuid", "=", "zzzzz-j7d0g-0123456789abcde" ], [ "uuid", "is_a", [ "arvados#group", "arvados#collection" ] ] ] },
Trashed or deleting a filter group causes the group itself to be hidden or deleted, but has no effect on the items returned in “contents”, i.e. the database objects in “contents” are not hidden or deleted and may be accessed by other means.
Groups can be trashed by updating the record and setting the trash_at
field, or with the delete method. The delete method sets trash_at
to “now”.
The value of trash_at
can be set to a time in the future as a feature to automatically expire groups.
When trash_at
is set, delete_at
will also be set. Normally delete_at = trash_at + Collections.DefaultTrashLifetime
for projects and filter groups, and delete_at = trash_at
for role groups. When the trash_at
time is past but delete_at
is in the future, the trashed group is invisible to most API calls unless the include_trash
parameter is true. All objects directly or indirectly owned by the group (including subprojects, collections, or container requests) are considered trashed as well. Groups in the trashed state can be untrashed so long as delete_at
has not past.
Once delete_at
is past, the group will be deleted permanently and can no longer be untrashed. Different group types have different behavior when deleted, described above.
Note: like other groups, “role” groups may have trash_at
set to date in the future, however roles groups are required to have delete_at = trash_at
, so the trash time and delete time expire at the same time. This means once trash_at
expires the role group is deleted immediately. Role groups with trash_at
set can only be untrashed before they expire.
A user with manage
permission can set the frozen_by_uuid
attribute of a project
group to their own user UUID. Once this is done, no further changes can be made to the project or its contents, including subprojects.
The frozen_by_uuid
attribute can be cleared by an admin user. It can also be cleared by a user with manage
permission, unless the API.UnfreezeProjectRequiresAdmin
configuration setting is active.
The optional API.FreezeProjectRequiresDescription
and API.FreezeProjectRequiresProperties
configuration settings can be used to prevent users from freezing projects that have empty description
and/or empty properties
entries.
See Common resource methods for more information about create
, delete
, get
, list
, and update
.
Required arguments are displayed in green.
Retrieve a list of items owned by the group or user. Use “recursive” to list objects within subprojects as well.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the group or user to enumerate. If this is a user UUID, this method returns the contents of that user’s home project. | path | |
limit | integer (default 100) | Maximum number of items to return. | query | |
order | array | Attributes to use as sort keys to determine the order resources are returned, each optionally followed by asc or desc to indicate ascending or descending order. Sort within a resource type by prefixing the attribute with the resource name and a period. |
query | ["collections.modified_at desc"] |
filters | array | Conditions for filtering items. | query | [["uuid", "is_a", "arvados#job"]] |
recursive | boolean (default false) | Include items owned by subprojects. | query | true |
exclude_home_project | boolean (default false) | Only return items which are visible to the user but not accessible within the user’s home project. Use this to get a list of items that are shared with the user. Uses the logic described under the “shared” endpoint. | query | true |
include | array | Look up objects referenced by the indicated fields and include them in the response. Only “owner_uuid” and “container_uuid” are supported. If “owner_uuid” is given, the parent project or user will be returned. If “container_uuid” is given and container requests are returned in the response, the corresponding container records will also be returned. These referenced objects will be returned in the “included” field of the response. For compatibility, a string "owner_uuid" is accepted as equivalent to ["owner_uuid"] . |
query | "owner_uuid" ["owner_uuid","container_uuid"] |
include_trash | boolean (default false) | Include trashed objects. | query | true |
include_old_versions | boolean (default false) | Include past versions of the collections being listed. | query | true |
select | array | Attributes of each object to return in the response. Specify an unqualified name like uuid to select that attribute on all object types, or a qualified name like collections.name to select that attribute on objects of the specified type. By default, all available attributes are returned, except on collections, where manifest_text is not returned and cannot be selected due to an implementation limitation. This limitation may be removed in the future. |
query | ["uuid", "collections.name"] |
Notes:
Because adding access tokens to manifests can be computationally expensive, the manifest_text
field is not included in listed collections. If you need it, request a list of collections with the filter ["owner_uuid", "=", GROUP_UUID]
, and "manifest_text"
listed in the select parameter.
Use filters with the attribute format <item type>.<field name>
to filter items of a specific type. For example: ["container_requests.state", "=", "Final"]
to filter container_requests
where state
is Final
. All other types of items owned by this group will be unimpacted by this filter and will still be included.
When called with “include=owner_uuid”, the included
field of the response is populated with users, projects, or other groups that own the objects returned in items
. This can be used to fetch an object and its parent with a single API call.
When called with “include=container_uuid”, the included
field of the response is populated with the container associated with each container request in the response.
Create a new Group.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
group | object | query | ||
async | boolean (default false) | Defer the permissions graph update by a configured number of seconds. (By default, async_permissions_update_interval is 20 seconds). On success, the response is 202 (Accepted). |
query | true |
Put a Group in the trash. See Trashing groups for details.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the Group in question. | path |
Gets a Group’s metadata by UUID.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the Group in question. | path |
List groups.
See common resource list method.
show groups
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | path |
Update attributes of an existing Group.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the Group in question. | path | |
group | object | query | ||
async | boolean (default false) | Defer the permissions graph update by a configured number of seconds. (By default, async_permissions_update_interval is 20 seconds). On success, the response is 202 (Accepted). |
query | true |
Remove a Group from the trash. Only valid when delete_at
is in the future. This sets the trash_at
and delete_at
fields to null
.
Arguments:
Argument | Type | Description | Location | Example |
---|---|---|---|---|
uuid | string | The UUID of the Group to untrash. | path | |
ensure_unique_name | boolean (default false) | Rename project uniquely if untrashing it would fail with a unique name conflict. | query |
This endpoint returns the toplevel set of groups to which access is granted through a chain of one or more permission links rather than through direct ownership by the current user account. This is useful for clients which wish to browse the list of projects the user has permission to read which are not part of the “home” project tree. Similar behavior is also available with the exclude_home_project
option of the “contents” endpoint.
Specifically, the logic is:
select groups that are readable by current user AND (the owner_uuid is a user (but not the current user) OR the owner_uuid is not readable by the current user OR the owner_uuid is a group but group_class is not a project)
Argument | Type | Description | Location | Example |
---|---|---|---|---|
include | string | If provided with the value “owner_uuid”, this will return owner objects in the included field of the response. |
query |
Notes:
When called with “include=owner_uuid”, the included
field of the response is populated with users and non-project groups that own the objects returned in items
.
In addition to the “include” parameter this endpoint also supports the same parameters as the list method.
The content of this documentation is licensed under the
Creative
Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the
Apache License, Version 2.0.