TeamForm for Jira App setup

The TeamForm for Jira Marketplace App allows existing TeamForm customers using Atlassian’s Jira Cloud SaaS product to link both Jira Projects and their Jira Issues to their respective team pages in TeamForm.

This creates transparency on which team is working on which work.

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.

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.

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.

TeamForm Public API:

If you have not setup TeamForm Public API access, you can request them for your TeamForm Tenant by talking to your TeamForm admin, who can create a key for you.

More information via TeamForm Public API.

IP Based Restrictions:

If your TeamForm tenant is configured with IP based restrictions you will also need to request the TeamForm Support so Atlassian IPs can be added to the whitelist if not yet added.

A current list of Atlassian IPs can be found under the Outgoing Connections section on this page https://support.atlassian.com/organization-administration/docs/ip-addresses-and-domains-for-atlassian-cloud-products/.

Installation and Setup

This process can only be completed by your Jira Admin.

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
Within Jira, navigate to the Admin Page for the Marketplace App:

Screenshot highlighting link to ‘Manage your apps’ under the ‘Apps’ button in Jira top navigation.

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 (required)
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.
Select which TeamForm teams you intend to link for projects or issue types:
1. Select change to select team types (the Team Type ID from TeamForm) you wish to map for each issue type.
2. Select which you intend to have imported into TeamForm by toggling values in the Import column from Excluded to Included.

🎉 Congratulations - You can now start to link TeamForm Teams to Jira Projects!

How-to Use

Project Linking

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

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.
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 Jira Project.
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.
Once a team is linked, Jira issues will be synchronised to TeamForm based on the integration’s schedule update settings - usually twice a day.

🎉 Congratulations - You have created a link between your project and a TeamForm Team.

The Team will appear in a side panel for any issue owned by this Team.

You can now jump straight to the Team in TeamForm, by clicking its name.

Issue Linking beta

This feature is still in Beta and is still being tested. It may not always behave as expected until final release.

Head to an Issue on any Jira board on the current Instance:
Click on ‘TeamForm Team’ on the right-hand side.

Screenshot highlighting the means to link an issue with a team from Jira to TeamForm.

A panel will open, showing that this issue is currently ‘Unassigned’ to a TeamForm Team.
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:

Selection box to associate an Issue in Jira to a team from TeamForm.

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

Listed TeamForm teams associated with a Jira issue.

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

🎉 Congratulations - You have made a link between your project and a TeamForm Team.

The Team will appear in a side panel for any issue owned by this Team.

You can now jump straight to the Team in TeamForm, by clicking its name.

Board Issues Linking ( V1 deprecated soon )

The minimum version of the TeamForm plugin must be greater than 17.0.0 to enable board issue linking. Please refer to the official Jira documentation for instructions on upgrading:
Updating apps in Jira

The upgrade is required due to scope changes, which are necessary to allow requests for retrieving board data.

Required scopes

read:board-scope:jira-software

read:project:jira

read:issue-details:jira

Set up board-team linkage mappings

Note that V1 supports only one way of setting up the mappings.
Prepare a JSON file containing the mapping details., for example:

{
  "boardTeamMappings": {
    "1": [
      "ABC",
      "DEF"
    ],
    "2": [
      "ABC"
    ]
  }
}

Here, 1 and 2 are board IDs, which you can find in the board page URL.
ABC and DEF are TeamForm team IDs.

Passing incorrect board IDs will cause an error, and the import will fail. Please make sure the IDs are correct.

Upload the mappings file to your Jira integration page.

Click Import

Note that the issue type mapping configured in the plugin admin panel is also applied to board-level issue data polling

Board Issues Linking ( V2 )

The minimum version of the TeamForm plugin must be greater than 17.4.0 to enable board issue linking. Please refer to the official Jira documentation for instructions on upgrading:
Updating apps in Jira

The upgrade is required due to scope changes, which are necessary to allow requests for retrieving board data.

Required scopes

read:board-scope:jira-software

read:project:jira

read:issue-details:jira

Set up board-team linkage mappings

On the Admin Page of the TeamForm for Jira App, enable the toggle of “Show board-based linking UI“

Navigate to the project link page of the plugin.

Search for and select TeamForm teams to link to a board.

Configure the Jira integration in TeamForm

{
  "requestIntegrationConfig": true
}

Copy and paste the code above into a JSON file, then upload it to the datasource

Click the import button

Linking & Importing

There are two types of linking:

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)
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

This process can only be completed by your Jira Admin.

We recommend only importing a subset of Issue types into TeamForm, so that only meaningful work items are visible in TeamForm, rather than work items of varying size and granularity
e.g. showing a bug that is open for day or two is not helpful to show in TeamForm, however a strategic Epic that other teams are contributing is essential to creating transparency.

This section details how to include or exclude Jira issue types.

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).

Secret Key and URL of the TeamForm for Jira App are available on the Admin Page.

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.

Selecting what issues to include/exclude on the admin page of the app.

Remember:

Even though an Issue Type is selected, only some of the Issues with that Issue Type will be imported: e.g only those whose Project is linked to a TeamForm Team, as described above.

Setting up Jira Integration from TeamForm

Log into your TeamForm instance, and navigate to Settings > Data Integrations.
Click Create on New Integration
Select Connect next to Atlassian Jira

Connecting a new Jira integration in TeamForm.

Click Create datasource

Setting up a new Jira integration in TeamForm.

Paste the Key and URL revealed earlier into the relevant fields
Click Update
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.

Note: the import process will not find any Issues to import, unless those Issue Types have been mapped to a Team Type in TeamForm.

The import process will import all Issues of mapped Types into TeamForm. This includes Issues in the past.

Be sure this is what you want before creating a mapping from an Issue Type to a Team Type.

In particular, it is not recommended to map Jira Tasks, Bugs, Stories as they are not a helpful granularity of work to display in TeamForm.

Excellent! You have now configured TeamForm to import Projects and Issues from Jira, using the Atlassian TeamForm Integration.

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:

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.

Setting up a custom message to be displayed when an issue or project isn’t linked to a team in TeamForm.

Click Save default text.

Example of a custom message displayed when an issue or project isn’t linked to a team.

Permissions (admin page)

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

Option to restrict linkage access.

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.

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.
Once you have set up your Custom Field, go to the Jira Admin page, and head to the Custom Fields section.
Click Expand.
Select, or type to search, from the drop-down list as many Custom Fields you wish to use - most people just use one.
Click Submit - you should receive a message saying your changes have been submitted.

That’s it! Now, the plugin will import each assigned value of this Custom Field, when it imports Issues across to TeamForm. The value will then be used to group all Issues under that value.

Example

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

Admin Page configuration

Selecting ‘Example Theme Value’ on a specific Issue

On import to TeamForm, the Theme’s Value is used to group the associated Issues as a high-level objective

TeamForm Custom fields

Add a new custom field

To add a new custom field:

Go to Settings ⚙️ > Work items.
Select Custom Fields from side menu
Select Create custom field to create a new custom field.
Select Advanced from modal sidebar.
Search “TeamForm” and select from TeamForm specific custom fields.
Add name and save custom field.

Configure a custom field

To configure a custom field:

Go to Settings ⚙️ > Work items.
Select Custom Fields from side menu
Search for your field by name.
Select Contexts and default value from custom field menu (3 dots on right).
Click Edit custom field config
Configure custom field and save

You can create 2 different types of teamform specific custom fields:

TeamForm Select

This custom field allows users to embed a teamform connected select within Jira.

Why would you use this? Maybe you want to associate a team as a dependency. Or perhaps design a workflow that references teams.

This field allows you to have a field that displays and allows association of TeamForm teams with the customisation of naming, which team types are shown and whether to allow association with just one or multiple teams.

Configuration Options

Select team types to filter by - This select is connected to the 'GroupTypes' configuration object and allows an admin to configure what teams the Custom Field can query/search against. It is a multi-select, allowing the admin to show multiple team types in the results.

Allow user to select multiple teams - This checkbox determines whether the CustomField allows multiple values, or only a single value.

JQL and TeamformSelect

There are two ways of querying a CustomField.

Option 1: "My Custom Field" {{operator}} {{value}}

IS - This operator is only usable with EMPTY or NULL checking for an empty value and will not trigger the autosuggest.
See more at Jira documentation.

IS NOT - This operator is only usable with EMPTY or NULL checking for an empty value and will not trigger the autosuggest.
See more at Jira documentation.

CONTAINS (~) - The "~" operator is used to search for issues where the value of the specified field matches the specified value (either an exact match or a "fuzzy" match — see examples in Jira documentation).
See more at Jira documentation.

CONTAINS (~) - The "!~" operator is used to search for issues where the value of the specified field is not a "fuzzy" match for the specified value.
See more at Jira documentation.

Option 2: "My Custom Field.Name" {{operator}} {{value}}

IS - This operator is only usable with EMPTY or NULL checking for an empty value and will not trigger the autosuggest.
See more at Jira documentation.

IS NOT - This operator is only usable with EMPTY or NULL checking for an empty value and will not trigger the autosuggest.
See more at Jira documentation.

IN - This operator searches for issues where the value of the specified field is one of multiple specified values. The values are specified as a comma-delimited list, surrounded by parentheses.
See more at Jira documentation.

NOT IN - This operator searches for issues where the value of the specified field is not one of multiple specified values. The values are specified as a comma-delimited list, surrounded by parentheses.
See more at Jira documentation.

= - This operator searches for issues where the value of the specified field matches exactly the specified value.
See more at Jira documentation.

!= - This operator searches for issues where the value of the specified field does not match the specified value.
See more at Jira documentation.

Teamform Cascade Select

This custom field allows users to embed a teamform connected cascading select (with hierarchy) within Jira.

Why would you use this? Maybe you want to associate a team as a dependency. Or perhaps design a workflow that references teams where there are many similarly named teams but in different structures.

This field allows you to have a field that displays and allows association of TeamForm teams with the customisation of naming, which team types are shown and whether to allow association with just one or multiple teams.

Configuration Options

The Cascade select allows admin to configure what hierarchy levels are visible (hidden) and what team types are included at each level. Please note that there are cases where team types are recursive, meaning it can reference itself as children. e.g. Team → Team → Team