Get/set permissions for a project — getPermissions • zircon

Get or set permissions for a project from an ArtifactDB using its REST endpoints.

getPermissions(project, url, version = NULL)

setPermissions(
  project,
  url,
  owners = NULL,
  viewers = NULL,
  action = c("append", "set", "remove"),
  public = NULL,
  version = NULL
)

Arguments

project: String containing the name of a project.
url: String containing the URL of the ArtifactDB REST endpoint.
version: String specifying the version or revision of the project for which to set/get permissions.
owners: Character vector of unix IDs or d-lists to set as/append to/remove from the list of owners for project.
viewers: Character vector of unix IDs or d-lists to set as/append to/remove from the list of viewers for project.
action: String indicating the action to use to modify the permissions.
public: Logical scalar indicating whether the results should be made public.

Value

For getPermissions, a list is returned containing permission information for a project (or one of its versions). This contains the fields:

scope, a string specifying the scope to which the permissions apply. Usually "project".
owners, a character vector identifying the project owners in the form of unix IDs or d-lists. Owners can read all files and edit the permissions.
viewers, a character vector identifying all users with read access to the project files.
read_access, a string specifying who is allowed to view the results. This can be everyone ("public"), all "authenticated" users, "viewers" and owners, "owners" only, or no one at all ("none").
write_access, a string specifying who is allowed to edit the permissions. This may be any of values described for read_access, though it is rarely anything other than "owners".

For .setPermissions, the permissions are modified for the project and NULL is invisibly returned. Note that there may be some delay in processing the request; the project itself will be locked until the processing is complete.

Details

Only users listed in the project's owners are allowed to modify the permissions for a project. Users in viewers (or all users, for public projects) are allowed to view but not modify a project's permissions.

If action="append", any specified owners are appended to the existing list of owners in the permissions for project. If action="remove", any specified owners are removed from the existing list. If action="set", any specified owners replace the existing list (unless owners=NULL, in which case no action is taken). The same logic applies to viewers.

If public=TRUE, the project is made public, i.e., read_access is set to "public". If public=FALSE, the project is viewable only by the users specified in the "viewers" field. The default of NULL will preserve any existing value for read_access.

If version is specified, these functions will get/set permissions for a specific version of a project. By default, if no permissions are placed on individual versions, they inherit their permissions from the project-level settings. This option is only applicable if version-level permissions are supported by the API at url.

Author

Aaron Lun

Examples

getPermissions(example.project, url = example.url)
#> $scope
#> [1] "project"
#> 
#> $read_access
#> [1] "public"
#> 
#> $write_access
#> [1] "owners"
#> 
#> $owners
#> [1] "ArtifactDB-bot"
#> 
#> $viewers
#> character(0)
#> 

if (FALSE) {
# Add Michael Lawrence to the viewers.
setPermissions(example.project, url = example.url,
    viewers="lawremi", action="append")

# Remove Michael Lawrence from the viewers.
setPermissions(example.project, url = example.url,
    viewers="lawremi", action="remove")
}