Team Components for Jira
Support and documentation
How to set up and use Team Components for Jira, answers to common questions, known limitations and how to reach us.
1. Installation
A Jira site administrator installs the app from the Atlassian Marketplace: Settings (gear icon) → Apps → Explore more apps, search for Team Components for Jira and choose Get app.
2. Set up a space
Team-managed spaces only show the fields their admins add. In each space where you want components:
- Open Space settings → Fields and click Add field.
- Select Components (team-managed) and click Add 1 field.
- Open Work types, choose a work type and click Components (team-managed) in the right panel. Click Save changes. Repeat for every work type that should have components.
Until the field is added, the Components page shows these steps as a reminder.
3. Manage components
Space admins open Space settings → Apps → Components.
- Add component: a name (up to 255 characters) and an optional description.
- Edit: change the description, or rename. A rename updates affected work items, subject to Jira permissions; review the result and any failures.
- Merge: move the matching work items returned by the bulk search from one component to another. A work item that already had both keeps it once. Review the coverage limits below before using this action.
- Archive: hide a component from the picker. It stays on existing work items and in search. Restore brings it back.
- Delete: remove the component from the catalog and remove its value from the matching work items returned by the bulk search; other component values on those work items are preserved. Review the coverage limits below before using this action.
- Import…: paste a list (one per line or comma separated), or load the labels used in the space.
- Find unlisted values: shows values on work items that are not in the list (for example set through the REST API) and lets you add them.
Renames, merges and deletions run in your browser: keep the page open until the progress bar finishes. If unfinished work remains, use Resume and review any failures before continuing. Saved filters that use an old name need manual updates.
Bulk coverage limit. Bulk searches stop paging at the 5,000-result threshold and are limited to work items the current user can see. On larger or restricted projects, a finished progress bar does not prove that every affected work item was updated. Review the outcome before retrying.
4. Components on work items
On a work item, click the Components (team-managed) row to open the picker, tick the components and click Save. The picker only offers the space's active components. Values that are not in the list stay on the work item until someone removes them.
5. Search and board filters
Use the field in JQL by name or by id, for example:
"Components (team-managed)" = "Checkout""Components (team-managed)" in ("Checkout", "Search")"Components (team-managed)" is EMPTY
On a team-managed board, add it under Space settings → Custom filters. A click on the number of work items in the Components page opens the matching search.
6. FAQ
Does it replace the built-in Components field? No. Jira offers the built-in field only in company-managed spaces. Team Components is a separate field; built-in reports that use the native Components field do not include it.
Where is the data stored? During normal app use, the catalog is stored in a Jira project property and selected values in the custom field. The app has no PPFTEC-operated backend or external runtime database. Support correspondence is processed separately; see the privacy notice.
Who can manage the list? Space admins. Anyone who can edit a work item can pick components on it.
What happens to saved filters after a rename? Filters that search for the old name must be updated by hand.
What if two admins edit the list at the same time? The app checks the catalog revision before saving and refuses conflicts it detects. This does not lock the catalog against another save; changes made between the check and the write can still be overwritten. Coordinate catalog edits, refresh and review the current list before retrying.
7. Known limitations
- Up to 250 components per space and 100 components per work item.
- The field is not the native Components field: native component reports, component leads and default assignees do not apply.
- Bulk updates run in the browser and send a separate Jira update for each returned work item; large spaces take a while. The 5,000-result threshold and visibility limits apply.
- Concurrent catalog saves can overwrite changes made after the revision check; see concurrent edits.
- Not tested yet: company-managed spaces, Jira Service Management spaces, the create dialog of every work type.
8. Contact
E-mail support@ppftec.com. We answer on business days, usually within one business day. Describe the problem and use a synthetic or redacted reproduction where possible. Remove personal information, credentials and tokens from screenshots or attachments; do not send sensitive work item content.