How can we help you?

Jira Bulk Import and Export

In order to expedite the linking of many Jira Projects and Boards to AgilityHealth Teams at one time, as well as quickly make changes to existing links, Company Admins can import and export that data in bulk.

Company Admins will see a blue Bulk Link button available on the Link Team tab within their Jira Cloud or Jira Data Center integration in AgilityHealth. This button allows the user to download a template to use for one Jira Instance at a time to update, import, or export the links between Jira Projects and Boards to AgilityHealth Teams. 

Screenshot 2023-09-06 at 2.57.15 PM.png

Please note the below, before trying to import your data:

  • Growth items can only be synced to company-managed projects in Jira. Growth items cannot be synced to team-managed projects
  • Make sure in your Jira instance that each board is only associated with one project. Otherwise, growth items may not sync to the correct board.

Starting from Scratch or Linking Additional Teams?

If you are starting from scratch setting up the link between Jira Projects and Boards to AgilityHealth Teams, downloading the Excel template is a good place to begin. Skip to the template section.

This template can also be used if you already have Jira Projects and Boards linked to Teams in AgilityHealth and want to add more, without modifying the ones you already have.


Need to Update Existing Links between Jira and AgilityHealth?

If your company already has Jira Projects and Boards linked to Teams in AgilityHealth but you need to make changes, you can download a file with all the data by choosing Export from the drop-down. 

Your data will download as an Excel file, which allows you to quickly make updates to it and then put that information back into AgilityHealth, using the Import option from the drop-down.

Data can be downloaded for one instance at a time. Select the instance you wish to use from the Jira Instance drop-down, then click Export under the Bulk Link button.


How to Use the Template or Edit an Exported File

Add your Jira Instance, using the Add New Instance button, if necessary.

Screenshot 2023-09-11 at 1.23.14 PM.png

Select the Instance you wish to modify from the Jira Instance drop-down.

Screenshot 2023-09-06 at 2.56.47 PM.png

Then choose Download Template from the Bulk Link drop-down or choose Export (for those companies who already have links). The template will download as an Excel file for the Instance selected. 

Screenshot 2023-09-06 at 2.57.46 PM.png

Items you need to know:

  • Do not delete rows 1-2.
  • Pay close attention to rows 1 and 2 which explain how data in the cells of that row need to be formatted and list which columns are required. If a column is required but not filled in, you will receive an error when trying to import your data.  
  • Hover over the red triangle in each cell in Row 1 to understand where to find the information the file is asking for.

Screenshot 2023-09-11 at 2.07.13 PM.png


Formatting the Data

Before you start editing, if you exported your company's data and are updating that file to import back into AgilityHealth, you should understand these basic rules:

  • Links between Jira Projects and Boards to AgilityHealth Teams cannot be unlinked via this option and must be unlinked manually from the Link Teams tab in AgilityHealth.
  • You can delete the entire row(s) of data for any link(s) you do not need to update. Only the teams with data that changed in the Excel file will be updated when you import the data back into AgilityHealth.
  • If you make changes to Projects, Boards and/or AgilityHealth Teams that are already linked, the changes you make will override the existing links.
  • Do not delete columns of data.
  • Fill in each row completely. Your spreadsheet should look like the below:

Screenshot 2023-09-11 at 2.20.11 PM.png

Column A: Team Unique Identifier

  • This column consists of the team's unique identifier in AgilityHealth in our database.
  • This column is required. 
  • If your teams already have external identifiers, you can edit the team from the Teams Dashboard and find a team's identifier in the External Identifier field on the Team's Profile. 
  • If your teams do not have external identifiers, AgilityHealth can generate them for you.
    • Go to the Teams Dashboard, and from the Bulk Data Mgmt button, choose Generate Ext. Identifiers.
      • If you do not see the Bulk Data Mgmt button on the Teams Dashboard, go to Settings > Manage Features and turn the toggle for Enable Bulk Data Management on. You must be a Company Feature Admin to do this or you can submit a support ticket to have this turned on for you.
    • After clicking Generate Ext. Identifiers, you may see your screen flash or refresh - that's AgilityHealth generating those team identifiers. We will not override any unique team identifiers that already exist.
    • Once AgilityHealth has finished generating the external identifiers, select Export from the Bulk Data Mgmt button drop-down. This will download all your company's data into an Excel file. In the first tab, Teams, column B will list all your team's unique identifiers. 

Column B: Team Name

  • This column consists of the team's unique name in AgilityHealth.
  • This column is optional.
  • This column is case-sensitive.
  • To find this value in AgilityHealth, go to the Teams Dashboard and make sure you're in Grid View.
  • If you export your company's data following the instructions above for the last bullet for Column A, then in the Excel file you download, on the Teams tab in Column C all your team's unique names will be listed for you.

Column C: External Project Identifier

  • This column comes from either Jira Cloud or Jira Data Center.
  • This column is required. 
  • To find this data, in either Jira Cloud or Jira Data Center, click "Projects" in the header of the main page. In the window that opens click "View all projects". The "Key" Column lists the External Project Identifiers" for all projects visible to you.

Column D: External Project Name

  • This column comes from either Jira Cloud or Jira Data Center.
  • This column is optional.
  • To find this data, in either Jira Cloud or Jira Data Center, click "Projects" in the header of the main page. In the window that opens click "View all projects". The "Project" Column lists the "External Project Names" for all projects visible to you.

Column E: External Board ID

  • This column comes from either Jira Cloud or Jira Data Center.
  • This column is required. 
  • To find this data in Jira Data Center, click "Boards" in the blue header on the main page and then click "View all boards". In Jira Cloud, click the / (forward slash key) on your keyboard and a window with a search field opens up. On the bottom of the window click "Boards".

    • Once the Boards page opens click the name of a board in either Jira Data Center or Jira Cloud.

    • Once the board opens up look at the URL.

      • In Jira Data Center the Board ID is at the end of the URL after the word rapid view. Example: https://jira.testcompany.com/secure/RapidBoard.jspa?rapidView=154.

      • In Jira Cloud, the Board ID is at the end of the URL after the word board. Example: https://testcompany.atlassian.net/jira/software/c/projects/HTEP/boards/80

Column F: External Board Name

  • This column comes from either Jira Cloud or Jira Data Center.
  • This column is optional.
  • To find this data in Jira Data Center click "Boards" in the blue header on the main page and then click "View all boards". In Jira Cloud, click the / (forward slash key) on your keyboard and a window with a search field opens up.
    • On the bottom of the window click "Boards". When the board page opens up the Board Names will be listed under the "Name" column.

Importing the file

Once you have adjusted your data in the template or export file, you're ready to import the data into AgilityHealth! In the Bulk Link button drop-down, choose Import. A modal will open for you to use. 

Screenshot 2023-09-25 at 2.46.07 PM.png

Things to note:

  • After you click the Upload button and select your updated Excel file, the upload will first validate all data in the spreadsheet to make sure the formatting and reference data are correct and verify that all mandatory fields are populated.
  • After validation has been completed, the import will begin. While processing your data, be sure not to close the browser window.
  • You will receive a confirmation message if your data is uploaded without error.

If there are errors found:

  • Errors will be shown in the Status box and no data will be imported.
  • You will need to correct the errors and re-run the import with the corrected file for successful processing.
  • The error messages will tell you what line of your data needs to be adjusted.
  • You can click Download Errors to download a .txt file of all the errors. 

The below example shows many errors:

Screenshot 2023-09-25 at 2.51.14 PM.png

Was this article helpful?
0 out of 0 found this helpful
    Download article

Comments

Please sign in to leave a comment.