---
title: "Enterprise actions reference guide for Seven Bridges API R Client"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_document:
    toc: true
    toc_float: true
    toc_depth: 4
    number_sections: false
    theme: "flatly"
    highlight: "textmate"
    css: "sevenbridges.css"
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Managing Divisions with Seven Bridges API R Client}
  %\VignetteEncoding{UTF-8}
---


<a name="top"></a>

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

# Managing Divisions

Enterprise access to the Platform is available on demand, and allows companies
or organizations to mimic their internal structure and hierarchy on the Seven
Bridges Platform, thus facilitating simpler and more efficient collaboration.

Enterprise accounts are granted to users through their organizations. The
organization associated with the Enterprise account may create user groups
(`Divisions` and `Teams`) composed of Enterprise account holders, which are
used to enable collaboration between members of the organization.

A `Division` on the Platform is a subgroup of users within an `Enterprise`. Use
the `Division` entity to replicate the structure and hierarchy of an
organization, such as departmental groups on the Platform. `Enterprise`
administrators create `Divisions`, but they can assign `Division`
administrators to manage them.

A `Team` is a subgroup within a `Division`. Division administrators can create
`Teams` to simplify adding multiple members to a project at once. A single
`Division` member can belong to multiple `Teams`.

Division related operations can be accessed through the `divisions` path
from the `Auth` object.

When fetching a single division, it is represented as a `Division` object,
which contains the following information:

- `id`: Division ID
- `name`: Division name

The division object also has additional methods that can be executed directly
on it, such as: `TO BE ADDED`



## List all your divisions

The following call returns a Collection with a list of all divisions you are a
member of. Each division ID, name and URL on the Seven Bridges Platform will be
returned.

```{r}
# Authenticate (division authentication token is required)
a <- Auth$new(platform = "aws-us", token = "<your-token>")

# Query all divisions of which you are a member
a$divisions$query()
```


## Get details of a division

The following call returns the details of a specified division.

```{r}
# Retrieve details of a specified division
a$divisions$get(id = "division-id")
```


## List all your teams in a division

To retrieve a list of all teams in a division that you are a member of, use the
`list_teams()` method of a `Division` object. This method returns a
`Collection` of `Team` objects, each containing the team's ID and name.

If you want to list all teams within the division, regardless of whether you
are a member, set the `list_all` parameter to `TRUE`.

```{r}
# Retrieve details of a specified division
my_division <- a$divisions$get(id = "division-id")

# List division teams you are a member of
my_division$list_teams()

# List all teams in the division, including those you are not a member of
my_division$list_teams(list_all = TRUE)
```


## List members of a division

To retrieve a list of all members in a division, use the `list_members()`
method of a `Division` object. This method returns a `Collection` of `User`
objects, each containing user details.

If you want to filter members by role, you can specify the `role` parameter. 
The supported roles are `"ADMIN"`, `"MEMBER"`, and `"EXTERNAL_COLLABORATOR"`.
The default value for this parameter is `NULL`, meaning that if `role` is not
provided, members of all roles will be included in the results.

```{r}
# Retrieve details of a specific division
my_division <- a$divisions$get(id = "division-id")

# List all members in the division
my_division$list_members()

# List only members with the "ADMIN" role
my_division$list_members(role = "ADMIN")
```


## Remove a member from a division

To remove a member from a division, use the `remove_member()` method of a
`Division` object. This action revokes the user's membership in the division
but does not delete their Platform account.

Only users with the `ADMIN` role in the division have permission to remove
members. If a user without `ADMIN` privileges attempts to perform this action,
an error will be raised.

The user parameter accepts either a username (formatted as
`"division-name/username"`) or a `User` object.

```{r}
# Retrieve details of a specific division
my_division <- a$divisions$get(id = "division-id")

# Remove a member using their username
my_division$remove_member(user = "division-name/username")

# Remove a member using a User object
members <- my_division$list_members(role = "MEMBER")
member_to_remove <- members$items[[1]]
my_division$remove_member(user = member_to_remove)
```

# Managing teams

As mentioned before, the `Team` entity is the subgroup of the `Division` and
enterprise users can perform certain actions on created teams too. 

We have created the `Teams` class as a `Resource` class, just like we have for
`Apps`, `Files`, `Projects`, etc., in addition to the `Team` class,
which stores information about a single team.

`Teams` class helps us organizing our team methods on `Auth` object, therefore,
on the `auth$teams` path you may find the well known methods for querying teams
(`query()`), fetching a single team (`get()`), creating a new team (`create()`) 
and deleting teams (`delete()`). 

Querying teams (`query()`) requires a division parameter provided in form of 
string (as division ID) or as `Division` object, and it returns a `Collection` 
of teams user has access to. With parameter `list_all` you can control whether 
to return all teams regardless of whether you are a member of a team or not.

Method `get()` fetches a single team by its ID provided. 

Creating new teams (`create()`) requires only a `division` parameter specifying
where to create the team, and a `name` parameter for the new team's name. 

Deleting teams (`delete()`) is possible by providing a team ID or `Team` object.

Examples of usage are presented below:

```{r}
# Query all teams in a specific division
my_teams <- a$teams$query(division = "division-id", list_all = TRUE)
print(my_teams)
```
```
── 1 ──

── Team ─────────────────────────────────────────────────────────────────────
• name: <team-name-1>
• id: <team-id-1>
• href: <href-1>

── 2 ──

── Team ─────────────────────────────────────────────────────────────────────
• name: <team-name-2>
• id: <team-id-2>
• href: <href-2>

```
```{r}
# Fetch single team by ID
my_test_team <- a$teams$get("my-test-team-id")
print(my_test_team)

# Create new team
new_team <- a$teams$create(division = "division-id", name = "my-new-team")
print(new_team)

# Delete a team
a$teams$delete(team = "my-new-team-id")
```


## Team object methods

When you retrieve a single Team, you can use the following methods to manage
it:

* list_members()
* add_member()
* remove_member()
* rename()
* delete()

Your ability to perform these actions depends on your `role` within the
platform division to which the team belongs. Some operations require `ADMIN`
privileges, while users with the `MEMBER` or `EXTERNAL_COLLABORATOR` role may
have limited access. If you attempt an action without sufficient privileges,
you will receive an error message like:

`Insufficient privileges to access the requested team/member information.`


### Listing team members

To retrieve the members of a specific team, use the `list_members()` method on
a `Team` object:

```{r}
# Fetch a team by its ID
my_team <- a$teams$get("my-team-id")

# List the team's members
my_team$list_members()
```


### Adding a member to a team

You can add a new member to a team using the `add_member()` method on a `Team`
object:

```{r}
# Add a team member by providing their username
my_team$add_member(user = "division-name/username")
```

Alternatively, you can pass a `User` object to the `user` parameter instead of
a username.


### Removing a team member

You can remove a team member using the `remove_member()` method on a `Team`
object:

```{r}
# Remove a team member by providing their username
my_team$remove_member(user = "division-name/username")
```

Providing a `User` object would work as well.


### Renaming a team

To rename an existing team, use the `rename()` method on a `Team` object and
provide the new name via the `name` parameter:

```{r}
# Rename the team
my_team$rename(name = "new-team-name")
```

### Deleting a team

If you need to delete a team, use the `delete()` method on the corresponding
`Team` object:

```{r}
# Delete the team
my_team$delete()
```

After executing this command, you will see a confirmation message in the console:

`The team <team-id> has been deleted.`