Managed Teams Integration with Jira

What are Managed Teams?

Jira Managed Teams allows organisations to set an external source of truth (such as TeamForm) for Jira teams.

The TeamForm Managed Teams integration allows you to configure TeamForm as the source for Jira teams, so that Jira team names and memberships are set using with information from TeamForm.

This removes the admin burden of independently maintaining Jira team lists and ensures consistent and up to date team information in Jira.

Key Features

Automatic Updates: Team names and memberships from TeamForm are automatically updated in Jira
New Team Creation: New teams created in TeamForm are automatically created in Jira
Integration settings: You can configure which teams are synced and how often this occurs from settings in TeamForm
Managed Team Appearance in Jira: Managed Teams are identified by a blue, verified check mark and memberships are locked from editing in Jira (as TeamForm is the source of truth).

Getting Started

To set up the integration, you will need:

A Jira Premium subscription (required to use the Managed Teams API).
Jira Username:
A user account with Admin Role in the Jira instance.
Jira Organisation ID:
The unique identifier of the tenant’s Jira organization.
1. Go to admin.atlassian.com
2. Select your organisation (if you manage more than one).
3. Look at the URL — it will look something like this: https://admin.atlassian.com/o/<ORG_ID>
Instance URL:
The URL of the Jira instance, e.g. <https://<sub-domain>>.atlassian.net
Authentication Token:
An API token generated by the user account mentioned in (1). This token will be used for Basic Auth.
1. Go to Atlassian API Token page
  https://id.atlassian.com/manage/api-tokens
2. Click "Create API token"

Configuring the integration

In TeamForm, from Settings/ Data Integrations, select create new integration and select the Jira Atlassian Team Sync:

Complete the API Connection Settings using information gathered at Getting Started.

(optional) specify sync behaviour and api request behaviour using the a JSON field map:

Filter Teams to be Synced

Specify rules to include only specific teams based on attributes:

groupTypes: Filters teams by their group type (e.g., "Domains", "Capabilities").
groupIds: Filters teams by exact internal team IDs.
areas: Filters by group ID and includes all their dependents.

Control API Request Behaviour

Fine-tune the integration’s performance and API usage:

concurrencyLimit: Maximum number of concurrent API calls. ( default: 5 )
delayBetweenRequestsMs: Delay (in milliseconds) between individual API calls. ( default: 150ms )
delayBetweenBatchRequestsMs: Delay (in milliseconds) between batches of API requests. ( default: 200ms )
maxBatchTimeoutMs: Maximum time (in milliseconds) the integration is allowed to run when creating new syncs. Once this time is reached, the integration will exit forcefully, even if there are remaining teams to process. The next run will continue processing from where it left off. This timeout does not apply to updating deltas. (Default: 30 minutes)

Sample Fieldsmap Configuration

{
  "filter": {
    "sync": [
      {
        "type": "groupTypes",
        "values": ["Domains", "domain"]
      },
      {
        "type": "groupIds",
        "values": ["A00062", "A00061"]
      },
      {
        "type": "areas",
        "values": ["A00029"]
      }
    ]
  },
  "requestConfig": {
    "concurrencyLimit": 5,
    "delayBetweenRequestsMs": 150,
    "delayBetweenBatchRequestsMs": 200,
    "maxBatchTimeoutMs": 60000
  }
}

Schedule the integration:

A 2 or 3 hour interval is recommended practice to ensure data is kept current without overloading the Jira api.