Jira Connector

Owned by Bettina Borces
Last updated: Mar 21, 2024
6 min read

Projector provides the ability to connect to JIRA. This page explains how to configure your JIRA connector. You may need to work with an implementation consultant to fully customize your integration.

If you wish to learn how to use the connectors, please see our How-To article, Workflow Management System User Guide.

In order to import time from JIRA to Projector, you must enable the Tempo Timesheets add-on in JIRA.

To reach this editor navigate to Administration Tab | Setup subsection | External Connectors.

a.png

Permissions and Settings

To update settings on this form you must have the global permission System Settings set to Update.

The JIRA connector is used for Enter Time and Time Card Import.

See our Workflow Management System User Guide which explains how this works for your end users.

Create a Resource User Defined Field

Go to your Administration tab | Setup subsection | User Defined Fields Editor  | Resource subtab. Add a new resource UDF of type Text.

 

a1.png

 

Create a Project User Defined Field

Go to your Administration tab | Setup subsection | User Defined Fields Editor  | Project subtab. Add a new resource UDF of type Text.

 

 

Create a Time Card User Defined Field

Go to your Administration tab | Setup subsection | User Defined Fields Editor  | Project subtab. Add a new resource UDF of type Jira (JIRA Issue - V2).

 

You must then edit each resource and fill out the resource UDF with their JIRA account ID. This value can be found by going to Users in JIRA and choosing Show Details. In the URL that is displayed will be their ID.

 

 

Configure JIRA External Connector

This section explains how to configure the JIRA connector. Some of the settings can be customized to your particular JIRA instance. For instance, only find JIRA issues of type=bug. You can reference this JIRA help page for a list of all their search APIs.

  1. Click New to create a new connector

  2. Fill out the form using the settings described in this table.

Field

Description

Field

Description

Code

Use this to uniquely describe your connector.

Connector Type

Set this to JIRA Issue V2. JIRA's API is currently on v2. This number may change as they release updates to their API.

Base URL

The root of your JIRA instance URL. Make sure you include the "s" in https.

Example:

https://mycompany.atlassian.net

Enable Item Search

Tick this checkbox so that resources entering a time card in Projector can search for and link JIRA tickets to the time card.

Enable Time Import

Tick this checkbox so that resources can use Time Card Import to search your JIRA database and create time cards from JIRA tickets. To use the Time Import function, the Tempo Timesheets add-on (version 7.20.18 or earlier) must be enabled in your JIRA instance.

Resource Identifier

You must choose User Defined Field from this dropdown list. You should have already configured a resource UDF called JIRA Account ID. Choose it from the second dropdown list.

Resource Field Name

At this time we don't see a great use case for this field. As assignees can change from person to person on a JIRA ticket, you can have a situation where the card can be seen and imported by Phil, but then later on be reassigned and then it can't be found.

Used only for the Item Search functionality.  It allows you to filter the tickets a resource can search on based on some criteria.  It is used in conjunction with the Resource Identifier. For example, in this field you might type:

assignee

This tells to Projector to search for JIRA tickets where assignee = {Resource Identifier}

If you want the resource to see all tickets, not only tickets assigned to them, leave this field blank.

See Assignee.

Project Identifier

Choose from the dropdown the project-related field in Projector that will be used to match JIRA tickets to Projector projects.  The options are Project Code or User-defined field.

Project Field Name

This is an optional field used only for the Item Search functionality. It represents the field in JIRA that maps to Projector projects.  Entering a value in this field will allow you to filter the tickets a resource can search on based on the project associated with the time card the resource is editing. This field is used in conjunction with the Project Identifier.  For example, in this field you might type:

project

This tells to Projector to search for JIRA tickets where the JIRA project = {Project Identifier}

If you want the resource to see all tickets, not only tickets on the current project, leave this field blank

See Project.

Key Field Name

This field is required and must contain the value "key" for a JIRA setup.  For Item Search, this will allow resources to search for issues directly by typing the issue key into the search box on their time card.  The field is also used by Time Import to extract additional details about each issue that might be needed during import.

key

See Issue Key.

Search Field Names

This is an optional (but highly recommended) field used only for the Item Search functionality.  Entering a value of "text#~" will allow resources to search for issues using a text string entered into the search box on their time card.  If required, other search fields can be appended in a comma-separated list.

text#~

See Text.

Search Constant Filters 

Use this field to append additional querystring parameters. For example, if you only want your connector to find JIRA issues created this year:

created>"2016/01/01"

You can also combine search terms. For example, only find JIRA issues with a specific fix version that were also created this year.

fixversion=10001 and created>"2016/01/01"

A full list of search APIs are available here.

Tempo Access Token

Get your access token by going to Tempo | Settings | API Integration in JIRA.

 

 

Custom Fields

As needed, you can add custom fields to the list of fields available during time import. 

To add a custom field, enter a name for the field in the “Header” column and the Column Identifier in the following format: 

fields.<customfield_XXXXX>.<field name>

 

You can find the custom field identifier by typing an API call directly into your web browser. Substitute in the correct URL based on your installation.

 

 

Click Set Credentials.

  1. Enter the Jira email address

  2. Enter the API token as the password: https://id.atlassian.com/manage/api-tokens

  1. Edit each resource in your installation and enter their JIRA Account ID #. To look up an account you can also use their RESTful services with one of the following four parameters: https://mycompany.atlassian.net/rest/api/2/user/search?query=emailAddress

    1. email address

    2. username

    3. key

    4. display name

  2. Now go to the User Defined Fields Editor and associate your new connector with time card UDFs.

  3. See our Workflow Management System User Guide

Time Card Importing

Set the Tempo Access Token (required for Time Import) see above.

The following lists all of the reasons the project key may not map in the Time Import Wizard.

  • Multiple projects in Projector match the mapped value

  • Project is marked for booked (to roles) resources only, and this resource has no role on the project

  • Project allows time from resources on certain cost centers only, and resource is not in an allowed cost center

  • Engagement cost center's company's accounting period is not open for time entry on any day during the date range

  • Project is not open for time entry

  • Project's date range does not overlap with the specified date range

  • Resource has one or more roles on the project, but none has a date range that overlaps the specified date range

  • Project is marked for assigned (to tasks) resources only, and the resource has no roles assigned to any tasks

  • No tasks/task types are open for time entry