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.