Although this function can be used in all sorts of situations, it can be particularly useful in setting up a workflow with a service-account:
If you are authenticated as a user, using box_auth()
, you can invite
the service account to collaborate on a folder in your user filespace.
In this case, the shared folder will appear in the service-account
filespace.
If you are authenticated as the service-account using
box_auth_service()
, you can invite your user-account to collaborate.
In this case, the shared folder will appear in your user file-space.
Once you issue an invitation to create a collaboration, you cannot change it,
e.g. you cannot change the role
from "viewer"
to "co-owner"
.
However, you can delete the collaboration, then issue a new invitation.
To delete a collaboration, use box_collab_delete()
. To check a Box folder ID or file ID
for existing collaborations, use box_collab_get()
.
You can also use the Box web-portal to manage collaborations.
The default role
, i.e. permission level, for an invitation
is "editor"
. Legal values for role
are "editor"
, "viewer"
,
"previewer"
, "uploader"
, "previewer uploader"
, "viewer uploader"
,
"co-owner"
, "owner"
.
box_collab_create(
dir_id = NULL,
user_id = NULL,
file_id = NULL,
group_id = NULL,
login = NULL,
role = "editor",
can_view_path = FALSE
)
numeric
or character
, folder ID at Box.
character
ID for Box user-account to invite.
numeric
or character
, file ID at Box.
character
ID for Box group-account to invite.
character
email address of account to invite, if specified
will be used instead of user_id
.
character
role of the collaborator; default is "viewer"
.
logical
indicates to allow the collaborator to
navigate parent-folders at Box.
Object with S3 class boxr_collab
.
To use this function, you must provide exactly one of: dir_id
or file_id
,
to specify what you want to share, and exactly one of: user_id
,
group_id
, or login
(email address), to specify the account you want to
share it with.
While authenticated from the host account, the one that will issue the
invitation, you can use box_ls()
and box_setwd()
to get the dir_id
or file_id
for the item you want to share. If the host-account is the
user-account, you can also use the web-portal to find the dir_id
or
file-id
. If the host account is the service-account, you can use the Box
content-portal to find this.
A user can find their user_id
using the Box web-portal. As well, when
you authenticate using boxr, the user_id
is included in the login
message. Thus, you can use box_auth_service()
to find out the user_id
for a given service-account.
This returns an object with S3 class boxr_collab
;
this is a list containing the response from the API. You can use
as_tibble()
or as.data.frame()
on this return-object to convert to
a tibble or data frame.