New API lets you create group linked teams

[#1]

Hello Atlassian Teams Community! 👋

Admins, are you spending too much time manually creating group-linked teams? We know what a cumbersome task this has been, especially when dealing with larger organizations. That’s why we have a new API for you! 🚀

This new API enables you to automate the creation of group-linked teams, saving you time and effort. ⏰

New Group Linked Team Creation API: POST /public/teams/v1/org/{orgId}/teams/external
Note: The API is available for customers using the new user management experience only. 🔒

We have also developed a script as a proof of concept for how admins can bulk create teams from groups using this new API. To do this, we will combine the Adminhub groups search API and our new group-linked teams API.

Walk through of script to bulk create grouped linked teams: Watch Video 🎥

Below details are necessary for code: 📋

• SiteId: Go to https://{SiteName}.atlassian.net/_edge/tenant_info
• User API Key: Go to Site → Profile → Settings → Manage Account → Security → Manage API Keys → Create API Token
• OrgId & Admin API Key: Admin Hub → Settings → API Keys → Create API Key.

Replace your details from above in a .env file as well as the group names you are searching for. E.g., if you want to create linked teams for all groups that have “marketing” in their title, replace group_names_create_teams with “marketing”.

Implementation 🛠️

Here's a simplified python script to help you get started with the bulk team creation process. If you want to create a team for every group in your org, you could leave the group_name_to_teams string blank. This will iterate over all groups in your org. This script should only be used as a starting point and considered only as a proof of concept.

import os
from dotenv import load_dotenv
import requests
import json
from base64 import b64encode

# Load environment variables from .env file
load_dotenv()

# Retrieve environment variables
org_id = os.getenv("ORG_ID")
api_admin_key = os.getenv("API_ADMIN_KEY")
site_id = os.getenv("SITE_ID")
site_url = os.getenv("SITE_URL")
api_user_key = os.getenv("API_USER_KEY")
email = os.getenv("EMAIL")

group_name_to_create_teams = "cx"

def get_groups_and_create_team(org_id, api_admin_key, email, api_user_key):
    # Construct the initial URL for getting groups
    base_group_url = f"https://api.atlassian.com/admin/v1/orgs/{org_id}/groups/search"
    
    # Define headers for getting groups
    group_headers = {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_admin_key}"
    }
    
    # Define payload for group search
    group_payload = json.dumps({
        "limit": 1000,  # Maximum number of groups to return
        "groupNames": {
            "contains": group_name_to_create_teams
        }
    })
    
    # Start with the base URL
    next_link = base_group_url
    
    while next_link:
        # Make the POST request to get groups
        group_response = requests.post(next_link, data=group_payload, headers=group_headers)
        
        # Check response status for group retrieval
        if group_response.status_code == 200:
            groups_data = group_response.json()
            groups = groups_data.get('data', [])
            
            print("Groups List Retrieved Successfully:")
            if (len(groups) == 0):
                print("No groups returned")

            for group in groups:
                # Print out group information
                group_id = group.get('id', 'Unknown ID')
                group_name = group.get('name', 'Unnamed Group')
                group_description = group.get('description', 'No description available')
                print(f"Group ID: {group_id}")
                print(f"Group Name: {group_name}")
                print(f"Group Description: {group_description}")

                # Constructing the basic authentication header for team creation
                auth_string = f"{email}:{api_user_key}"
                auth_header = b64encode(auth_string.encode()).decode()

                # Define the URL for creating a team
                external_team_url = f'https://{site_url}/gateway/api/public/teams/v1/org/{org_id}/teams/external'
                # Define headers for creating a team
                team_headers = {
                    "Accept": "application/json",
                    "Authorization": f"Basic {auth_header}",
                    "Content-Type": "application/json"
                }
                # Define payload for creating a team based on group data
                team_payload = json.dumps({
                    "description": group_description,
                    "externalReference" : {
                        "id": group_id,
                        "source": "ATLASSIAN_GROUP"
                    },
                    "siteId": site_id,
                })

                # Make the POST request to create a team
                team_response = requests.post(external_team_url, data=team_payload, headers=team_headers)

                # Check response status for team creation
                if team_response.status_code == 201:
                    team = team_response.json()
                    print(f"Team Created Successfully for {group_name}:")
                    print(json.dumps(team, sort_keys=True, indent=4, separators=(",", ": ")))
                else:
                    print(f"Failed to create team for {group_name}. Status Code: {team_response.status_code}")
                    print(f"Response: {team_response.text}")

            # Update the next link for pagination
            next_link = groups_data.get('links', {}).get('next', None)
            if next_link:
                next_link = f"{base_group_url}?cursor={next_link}"
        else:
            print(f"Failed to retrieve groups. Status Code: {group_response.status_code}")
            print(f"Response: {group_response.text}")
            # Exit the loop if there's an error
            break

# Call the function
get_groups_and_create_team(org_id, api_admin_key, email, api_user_key)
    

Feedback: 💬
We would love to hear your questions, feedback, and any ways we can continue to support admins who are managing teams!

Thanks,
Marcus, Atlassian Product Manager

[abdullah razzaq]

This is a fantastic update for Atlassian admins managing large organizations! 🚀 Automating group-linked team creation will undoubtedly save time and reduce manual workload. The inclusion of a proof-of-concept script is a great addition, making it easier for admins to get started.

A couple of thoughts for improvement:
1️⃣ Error Handling: It would be helpful to include more robust error handling in the script, such as retries for API failures or handling rate limits.
2️⃣ Logging & Notifications: Adding logging or email notifications could help track successful team creations and any failures for better monitoring.
3️⃣ Security Considerations: Since API keys are sensitive, emphasizing best practices for storing and managing them securely would be valuable.