How to setup and use TeamForm with Jira Cloud

The TeamForm Atlassian Marketplace App is for existing TeamForm customers using Atlassian’s Jira Cloud SaaS product.

Setup and Usage Instructions

1. Install the 'TeamForm for Jira' Marketplace App into your Jira Cloud instance.

   1. A link to the Marketplace App is here: https://marketplace.atlassian.com/apps/1232958/teamform-for-jira

2. Within Jira, navigate to the Admin Page for the Marketplace App:

3. On the Admin Page, fill in your TeamForm Public API details including:

   1. Tenant ID

   2. Client ID and Client Secret provided to you by TeamForm

   3. Workspace ID (if left blank, the plugin will use TeamForm’s default Workspace)

4. Optional: If you use a Custom URL to connect to TeamForm, you can enter it on this page.

5. Clicked ‘Change' with each of the new setup details.

Issue Linking

1. Head to an Issue on any Jira board on the current Instance:

2. Click on ‘TeamForm Team’ on the right-hand side.

   1. A panel will open, showing that this issue is currently ‘Unassigned’ to a TeamForm Team.

   2. 

3. To assign a Team, click the select box at the bottom of the panel. Click on one of the Teams to ‘link’ it to this Issue:

   1. 

4. To search for other Teams in TeamForm, type the name, or part of a name into the select box. The Marketplace App will query TeamForm, and show potential Teams relevant to your search term.

5. For example, try typing: ‘customer', which should return 'Customer Success’ as the top result.

Project Linking

To link a project to one (or many) TeamForm Team(s):

1. Click on ‘TeamForm’ on the left-hand sidebar.

   1. This will show the Project-level settings for the App.

2. To assign a Team, click the select box at the bottom of the panel.

3. Click on one of the Teams to ‘link’ it to this Jira Project.

4. To search for other Teams in TeamForm, type the name, or part of a name into the select box. The Marketplace App will query TeamForm, and show potential Teams relevant to your search term.

   1. For example, try typing: ‘customer', which should return 'Customer Success’ as the top result.

Mapping Issue Types to Team Types

For example, in your company, Epics might be completed by your organization's Departments. By mapping Jira Epics to TeamForm Departments, only Departments will be selectable in the Jira Marketplace App, and TeamForm can be configured to import all Epics as Objectives to their TeamForm Department on a schedule.

1. Go to the Admin Page of the Jira Marketplace App.

2. Scroll to the bottom of the Admin Page, to the section entitled: Team Type Mappings

3. Make a note of, or copy-paste, a Team Type ID from TeamForm.

   1. You can see a particular Team Type’s ID in the Org Structure section of TeamForm.

4. Find the Issue Type you would like to map to this Team Type.

5. Click ‘Change’

6. Enter your Team Type ID in the text field.

7. Click ‘Create’.

   1. You can add multiple mappings to the same Jira Issue Type.

   2. You can remove a mapping by clicking on it.

8. Click ‘Done’.

Importing Jira Issues as TeamForm Objectives

1. On the Admin Page of the Jira Marketplace App, click the Reveal button to show a secret URL and Key.

2. Select which Issue Types you would like to include in the Import, by using the Included column. Click Excluded on the Issue Type you wish to import, to toggle it to Included.

3. Log into your TeamForm instance, and navigate to the ‘Data Integrations’ Settings Page.

4. Click Create on ‘New Integration’.

5. Select ‘Atlassian Jira'.

6. Click Create datasource.

7. Paste the Key and URL revealed earlier into the relevant fields.

8. Click ‘Update’.

9. Optional: Configure a schedule for the Integration. This determines how often the data in Jira is automatically imported into TeamForm. For example, to import every 2 hours, use the frequency of 7200 seconds.

The Datasource can now reach out to the Jira plugin, and import any Issue of a Type that has been mapped to a Team Type in TeamForm.

Related information