> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage groups and collaborations
export const MultiRelatedLinks = ({sections = []}) => {
if (!sections || sections.length === 0) {
return null;
}
return
;
};
export const Link = ({href, children, className, ...props}) => {
const localizedHref = href;
return
{children}
;
};
## Script structure
This script uses the Box CLI to create or update groups, add users to them, and create collaborations between groups and folders.
The script consists of two parts described in detail in the sections below. You can run them both or use the optional flags to decide which part to run.
### Create or update groups
1. The script uses the `.csv` file you specify for the `UserGroupAdditionPath` parameter. The file lists group names and user emails. When creating the file, you can use the same group name for several users, and assign one user to several groups. For example:
| `GroupName` | `UserEmail` |
| ----------- | ----------------------- |
| Group1 | `ManagedUser1@test.com` |
| Group1 | `ManagedUser2@test.com` |
| Group2 | `ManagedUser3@test.com` |
| Group3 | `ManagedUser1@test.com` |
2. If the group doesn't exist, the script creates it. If it does exist, the script can update the entries based on the provided data.
### Create or update collaborations
1. The script uses the `.csv` file you specify for the `CollaborationsCreationPath` parameter. The file lists group names, folder IDs, and collaboration roles.
2. For each row, the script checks if a group exists and if it's not already added as a collaborator to the corresponding folder. For example:
| `GroupName` | `FolderId` | `CollaborationRole` |
| ----------- | ---------- | ------------------- |
| Group1 | 1111111 | editor |
| Group2 | 1111111 | viewer\_uploader |
| Group2 | 2222222 | viewer |
| Group3 | 1111111 | viewer\_uploader |
3. If both of these conditions are met, the script assigns the group to a folder using the role defined in the `CollaborationRole` column. Also, if a group already exists, but the `CollaborationRole` changed, the script will update it if you pass the `-UpdateExistingCollabs` flag when running the script.
## Prerequisites
### Windows
Install the latest version of [.NET core](https://dotnet.microsoft.com/download).
### MacOS & Linux
Install [PowerShell][pwsh]. Run the `pwsh` command to test the installation.
```bash theme={null}
pwsh
```
Depending on the directory you are
running the command in, the output may differ.
For example:
```bash theme={null}
PowerShell 7.2.5
Copyright (c) Microsoft Corporation.
https://aka.ms/powershell
Type 'help' to get help.
PS /Users/user/repos/boxcli/examples>
```
If you encounter issues make sure you installed both
[dotnet core](https://dotnet.microsoft.com/download) and
[PowerShell][pwsh].
### Box CLI
To use the script, you need to install and configure the Box CLI. You can do this by following
our quick start guide. The user you use to login with should
be the main Box admin or co-admin.
## Configure the script
1. Clone the `boxcli` GitHub repository and cd into this example's folder or download the files from the [`examples`][examples] directory.
```bash theme={null}
git clone https://github.com/box/boxcli.git boxcli
cd boxcli/examples/Mass\ Groups\ \&\ Collaborations\ Update/
```
2. Set the path to the `.csv` file with the list of groups and user emails.
```bash theme={null}
$UserGroupAdditionPath = "./User_Group_Addition.csv"
```
* `UserEmail` is the primary email address for the user in Box.
* `GroupName` is the name of the group.
3. Set your own path to the `.csv` file with the list groups and user emails.
```bash theme={null}
$CollaborationsCreationPath = "./Collaborations_Creation.csv"
```
* `GroupName` is name of the group the script will add as a collaborator to the folder.
* `FolderId` is the folder ID the collaborator will be added to.
* `CollaborationRole` is the name of the role used when creating a collaboration.
You can configure the available roles by setting the `AvailableCollaborationRoles` parameter:
```bash theme={null}
$AvailableCollaborationRoles = @("editor", "viewer", "previewer", "uploader", "previewer_uploader", "viewer_uploader", "co-owner")
```
## Run the script
1. Run the Powershell command.
```bash theme={null}
pwsh
```
2. Run the script.
```bash theme={null}
./Mass_Groups_Collabs_Update.ps1
```
### Optional flags
You can use flags to run or skip specific parts of the script.
* If a group is already set as a collaborator for a specific folder but with a role other than defined in the .`csv` file, the script informs you about it. It does not make any changes to an existing collaboration. If you want to update an existing collaboration with a role defined in the `.csv` file, set an additional `-UpdateExistingCollabs` flag when running the script.
```bash theme={null}
Mass_Groups_Collabs_Update.ps1 -UpdateExistingCollabs
```
* To update groups without creating collaborations, add the `-SkipCollabsCreation` boolean flag when running the script:
```bash theme={null}
Mass_Groups_Collabs_Update.ps1 -SkipCollabsCreation
```
* To create collaborations without any group updates, add the `-SkipGroupsUpdate` boolean flag when running the script:
```bash theme={null}
Mass_Groups_Collabs_Update.ps1 -SkipGroupsUpdate
```
## Logs
Logs are stored in the `logs` folder located in the main folder.
You have access to these log files:
* `Mass_Groups_Collabs_Update_all.txt` that contains all log entries.
* `Mass_Groups_Collabs_Update_errors.txt` that contains only errors.
[examples]: https://github.com/box/boxcli/tree/main/examples
[pwsh]: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2
[console]: https://app.box.com/developers/console
[auth]: /guides/authentication/oauth2/oauth2-setup