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.