---
title: "Teams based on Jira teams"
canonical: "https://support.appfire.com/space/DLP/2212236519/Teams%20based%20on%20Jira%20teams"
format: markdown
---
> Macro (aura-html)

## Initial setup

> 📝 Setup must done by a **Jira admin**. 
> 📝 
> 📝 Configuration is done once for the entire instance.

In the Teams module:

1. Go to **App Configuration** > **Integrations**
2. Navigate to the **Jira Teams **tab
3. Generate an API token and add it to the app:
  1. Log in to [Atlassian account](https://id.atlassian.com/manage-profile/security/api-tokens).
  2. Click **Create API token.**
  3. In the dialog that appears, enter a memorable **Label** for your token and click **Create.**
  4. Click **Copy** to clipboard.
  5. Add it to the app.
4. Enter the Organization ID
  1. Open URL [https://admin.atlassian.com](https://nostromo11.atlassian.net/admin/users)
  2. If you have access to more than one Organization, select the one associated with your BigPicture instance
  3. The ID can be found in the URL  
[https://admin.atlassian.com/o/](https://admin.atlassian.com/o/)**my-organization-id-xxxxx-xxxxxxx-xxxxxx**/overview
  4. Copy the ID from the URL and paste it into the required field
5. Enter the email address
6. Click **Save**

You will see a confirmation message:

![Connection confirmation message.](media://fbe21a82-7e34-4502-a259-8efc5e7cbdde)

Organization ID is listed on the page:

![successful sync confirmed on the app configuration page.](media://968f686e-4804-4230-8aa5-c8dd4b75d54f)

## Expiration of tokens

> 📝 Jira tokens are valid for a limited period of time. To ensure that synchronization can continue, the token must be replaced periodically.

### What happens if synchronization fails? (for example, if the token stops working)

- Changes made to Jira teams can no longer be transferred to the app.
- Teams that already exist in the app remain unchanged (in the state corresponding to the last successful synchronization).

### Will replacing the token with a new one trigger another synchronization?

- No. Currently, synchronization is always triggered manually. There is no auto-synchronization

---

## Create app teams based on Jira teams

In the Teams module:

1. Click the **+** button.
2. Select **Create new team based on Jira team**
3. Select a Jira Cloud team and fill out the fields:
  1. **Jira cloud team** (required)
  2. **Team name** (required)
  3. **Team code and color **(required)
  4. Board (optional)
  5. **Start date of Team memberships** (required)

![Create new team based on Jira team screen.](media://5569457e-a8d0-4d5e-adf1-6096056d28d9)

4. Click **Create**.

**Result**: A new team appears on the list. 

![New team based on Jira team listed in the Teams module.](media://acef130b-0e38-47b2-8f44-777a2cb94cc7)

### Memberships

- By default, the availability of team members is set to 100%.
- Memberships of team members and their availability can be modified as usual.
- When synchronization is triggered, based on a Jira team, new team members are added to the app:
  - the date of adding a person becomes the membership start date
  - availability is set to 100%
- When synchronization is triggered, based on a Jira team, team members are removed from BigPicture.

### Using the same Jira team in multiple boxes

You can’t create multiple box teams based on the same Jira team:

![Error message.](media://a569a28f-4ad4-43ce-a1b1-18b3cc0dae9e)

> ✅ **You can assign the same app team to multiple boxes. **

![How to create team based on Jira in multiple boxes.](media://d300ef99-5ac2-4c6f-981f-cd58c8ff05b6)

### Can I synchronize an existing app team with a Jira team?

No. The old team needs to be removed, and a new team (based on a Jira team) needs to be created).

## Synchronization

> 📝 Synchronization of the app teams with Jira teams has to be **triggered** **manually**. 
> 📝 
> 📝 Synchronization is **uni-directional**. Information from Jira is pulled into BigPicture.

### Where can synchronization be triggered

Synchronization must be triggered in the primary box of a team. 

You can’t trigger synchronization in boxes that have inherited the team. 

### Global synchronization

All app teams in a box (based on Jira teams) get synchronized. 

**Exception**: If a team has been edited in the app, for example, team members have been added or removed, the team will **NOT** be synchronized during global synchronization to prevent the loss of information. 

A pencil icon appears to teams that are excluded from the global synchronization.

**How to trigger a synchronization**

In a Teams module of a box:

1. Click **Synchronize **
2. Select Synchronize with Jira Cloud Teams

![Synchronize with Jira Cloud Teams option.](media://4bccc0d2-4d8d-438e-8bf9-4db3c506cc1f)

### Local synchronization (per team)

If a team has been edited in the app, for example, team members have been added or removed, the team will **NOT** be synchronized during global synchronization to prevent the loss of information. 

A pencil icon appears to teams that are excluded from the global synchronization.

![Local sync of the teams based on Jira teams.](media://a5543461-03f4-46dd-9ac4-4a55f350340b)

**How to trigger a synchronization**

To synchronize such a team, click the **re-synchronize button**:

- synchronization applies only to one team
- changes made in the app are overwritten with Jira team information

![How to resynchronize teams.](media://ca102be3-c3c6-45f0-8328-39b69b5d4b3a)