TeamForm for Jira App setup

Why use the TeamForm for Jira App

With our TeamForm for Jira App, your organisation’s Jira Administrators can link Jira Projects to relevant TeamForm Teams. This allows a Jira user to click through from Jira to TeamForm to view the team and team members who deliver this project.

Open

Demonstration of using the TeamForm for Jira App to connect people to their work in TeamForm.

We also offer a TeamForm integration, that combines with the TeamForm Jira app, to import Issues from Jira into TeamForm - displaying this team’s work items as Objectives.

Open

Jira Issues are visible on a team’s page in TeamForm after successful set-up.

Installing the TeamForm for Jira App

Prerequisites

Identify your Jira Admin, you will need their help to establish the initial App Configuration.

Installation and Setup

1. Install the TeamForm for Jira Marketplace App into your Jira Cloud instance.
   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 (located via the help ? icon on the bottom left menu of TeamForm)

   2. Workspace ID (if left blank, the plug-in will use TeamForm’s default Workspace)

   3. Client ID and Client Secret (refer below for TeamForm API steps)

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

   5. Click Change with each of the new setup details.

How-to Use

Project Linking

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

1. Click on TeamForm on the left-hand sidebar

   • Note: on smaller screens, you might need to scroll down

   • 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 App will query TeamForm, and show potential Teams relevant to your search term.

   • e.g. typing: ‘customer', which should return 'Customer Success’ as the top result.

5. Once a team is linked, Jira issues will be synchronised to TeamForm however frequently the integration is configured for - every 15 minutes by default.

Issue Linking beta

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

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

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

4. 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:

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. Try typing: ‘customer', which should return 'Customer Success’ as the top result.

6. To remove the link between a team and an issue, click the X button to the right of the listed teams.

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 TeamForm for Jira 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 TeamForm for 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

Linking & Importing

There are two types of linking:

1. Project linking: When you link a Project to a Team, and say that all linked Projects should be imported, any child Issues under those linked projects are also imported.

   1. They will appear in TeamForm on a Teams page

   2. They are only imported if their Issue Type has been Included (see below)

2. Direct linking: When you link an Issue to a Team, only that Issue is imported as an Objective. No Child Issues are imported.

   1. They are only imported if their Issue Type has been Included (see below)

Setting up Jira Issue Types to Show in TeamForm

1. On the Admin Page of the TeamForm for Jira App, click the Reveal button to show a secret URL and Key (note: These are the credentials to be put into the Integration form).

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.

Setting up Jira Integration from TeamForm

1. Log into your TeamForm instance, and navigate to Settings > Data Integrations.

2. Click Create on New Integration

3. Select Connect next to Atlassian Jira

4. Click Create datasource
   
   

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

6. Click Update

7. 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 connect with the TeamForm for Jira App, and import any Issue of a Type that has been mapped to a Team Type in TeamForm.

Other Configuration settings for the TeamForm for Jira App

Customised Message (admin page)

This section of the Admin Page is used to customise the appearance of the App for projects not yet linked to teams.

Set Un-linked default text is used to customise the message shown when an Issue or Project is not linked to a Team - to this set up:

1. Enter your custom message into the text box. You could use the following, as an example:

   • Please go to this <a href='https://www.example.co' target='_blank'>link</a> if you need TeamForm access.

2. Click Save default text.

Permissions (admin page)

This section of the admin page is to restrict who is able to link TeamForm Teams to projects in Jira:

Grouping by Custom Field

Some organisations use a Custom Field to define a higher level strategy or work item that Jira issues contribute to, or are grouped under. These might be called Strategic Goals, Themes or Objectives (or any other term used to define higher level work). You can configure the TeamForm for Jira app to recognise custom fields so that links between these and Jira issues are visible in TeamForm.

1. You can learn how to create a Custom Field here: https://support.atlassian.com/jira-cloud-administration/docs/create-a-custom-field/

   1. Only Single Select and Multi Select drop-down Field Types are supported.

2. Once you have set up your Custom Field, go to the Jira Admin page, and head to the Custom Fields section.

3. Click Expand.

4. Select, or type to search, from the drop-down list as many Custom Fields you wish to use - most people just use one.

5. Click Submit - you should receive a message saying your changes have been submitted.

Example

Linking the Theme Custom Field to a high level objective shown in TeamForm:

Custom field: TeamFormSelect

Related information