# Enterprise actions reference guide for Seven Bridges API R Client

#### 2025-03-25

# 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.

    # 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.

    # 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`.

    # 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.

    # 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.

    # 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:

    # 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>

    # 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:

    # 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:

    # 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:

    # 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:

    # 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:

    # 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.`