Skip to main content
Skip table of contents

Jira Integration

The following settings need / can be provided (example for JIRA clouds and JIRA server)

The settings differ for each extension, depending on the capabilities of the external tool. For JIRA clouds you need to install our (free) add-on on the Atlassian Marketplace

Setting

Explanation

Example (JIRA clouds)

Example (Jira server)

JIRA base URL

The url  under which JIRA is accessible in a web browser

https://YOUR_COMPANY.atlassian.net

http://server.mycompany.com:8080/jira

JIRA REST API URL

The rest URL of the JIRA API, will normally be the the JIRA base URL with a appendix /rest/api/2

If you have a Jira server < 7.0 beware of this: https://community.atlassian.com/t5/Answers-Developer-Questions/How-do-I-install-or-enable-the-Jira-REST-API/qaq-p/536234 

https://YOUR_COMPANY.atlassian.net/rest/api/2

http://server.mycompany.com:8080/jira/rest/api/2

List of JIRA Projects

A comma separated list of JIRA projects (without space) that our server should use

PROJECTX,PROJECTY


JIRA user

The login name of a user in JIRA with access to the projects

na (we don't need that for JIRA clouds)

matrixuser

JIRA user's password

The password of the above user

na (we don't need that for JIRA clouds)

thesuperpasswordnoonewilleverfindIthink

Allow empty search expressions

If the external tool can handle searches for empty strings (and returns something useful) this can be enabled by ticking this option.

off


run default search when opening search dialog

If there are quick searches defined (see below), the first quick search can be run automatically when opening the link with existing issue dialog. 

(default) off


Quick searches

This allows to add searches to the dropdown in "link with existing tickets' dialog. These searches are forwarded to the external tool, so for example they can contain jql expressions if the external tool is JIRA.


External Ticket Creation Configuration

This section needs to have at least one entry inside - for JIRA it must be a list of all projects / issue type for which a user can create tickets. For others like github which does not have this concept, you need also to add an entry, but the project id and type id can stay empty. 


Regex definitions to detect references to external item identifiers

These regex expressions are used when you want to refer to a ticket somewhere in a full text box. You can just type a ticket id which is matched by the rule and it will be replaced by a hyperlink to that ticket.

For this to work the regex must build different matching groups allowing you to extract the information needed to build the links, e.g. 

(PROJ)(-)([0-9]+) would matching PROJ-123 returning 4 matches 

  • $0 as PROJ-123

  • $1 as PROJ

  • $2 as -

  • $3 as 123

Using $0 to $3 you can than build the strings, defining the project, issue id and url.

e.g. the url could be

https://somewhere/$1/issue/$3

which would use to create the hypelink

https://somewhere/PROJ/issue/123


Regex definitions to detect references to external item urls 

These regex expressions are used if you drag and drop an extranl link to a website into the task attachment control. If the dragged url matches the regex, a link between the matrix item and the external item will be established.

Works like the other regex tools (see above).


Additional Advanced Settings


You can add the following to the Jira extension setting in the respective projects

CODE
  "showStatus":true,
  "autoAddCommentOnSave": true,
  "userMapping": { "francois": "5bf54067bc02091aaaaaaa", "ann": "557448:9849c290-d05f-4444-b6fa-456a23d6fba1"},
  "catFieldMapping": {
    "UREQ": {
      "description": { "extFieldId": "description", "converter": "plaintext" },
      "labels": { "extFieldId": "labels", "converter": "labels" },
      "my dropdown": {
        "extFieldId": "customfield_11508",
        "converter": "dropdown",
        "ddMapping": { "maxtrixOption1": "10200", "maxtrixOption2": "10201"  }
      }
    }

showStatus (optional): if set to true, the status of the Jira is shown behind links to JIRA

autoAddCommentOnSave (optional): if set to true the Jira tickets linked to a Matrix item will get a comment if the Matrix Item is modified. The comment shows what was changed in Matrix. The ticket fields itself are not automatically updated, to avoid conflicts or overwrites.

userMapping (optional): this allows to map Matrix user ids to Jira user account ids. This mapping can be used to impersonate Matrix users in JIRA. If a user pushes an item to JIRA, the reporter in Jira is automatically set based on this mapping. Note: if a Matrix user tries to push and item, with a mapping defined but without mapping for this specific user, an error message is displayed and the item is not pushed.
You can get the Jira user ids by opening this url : https://your_company.atlassian.net/rest/api/2/user/assignable/search?project=YOURJIRAPROJECTSHORTNAME. This will prompt you with a JSON similar to this after formatting:

CODE
[
   {
      "self":"https://your_company.atlassian.net/rest/api/2/user?accountId=6xxxxxxx1xxx341xx",
      "accountId":"6xxxxxxx1x122xx341xx"",
      "accountType":"atlassian",
      "emailAddress":"xxxxxx@your_company.com",
      "avatarUrls":{
         "48x48":"https://secure.gravatar.com/avatar/d358c7995d4ac17c76805c023cb?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FA-5.png",
         "24x24":"https://secure.gravatar.com/avatar/d358c7995d4ac17c76805c023cb?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FA-5.png",
         "16x16":"https://secure.gravatar.com/avatar/d358c7995d4ac17c76805c023cb?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FA-5.png",
         "32x32":"https://secure.gravatar.com/avatar/d358c7995d4ac17c76805c023cb?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FA-5.png"
      },
      ... 

catFieldMapping: this is a list of Matrix field names (like description or labels) with details to which field in Jira they should be mapped (extFieldId) and details how to convert from the Matrix field to the Jira field.

From Matrix you can push the following field types to JIRA

  • rich text boxes, text lines and plain text boxes (using the converter plaintext, which will remove all formatting)

  • labels (using the converter labels, to the external field “labels”). This will create Jira flags with the label ids

  • drop downs (using the converter dropdown, which requires a mapping for the values in drop down values in Jira, or plaintext to write the selected ids in a Jira text box)

ExtFieldId is defined by the Jira api. You can peek the available ExtFieldIds under the property “field” when browsing to https://your_company.atlassian.net/rest/api/2/issue/ISSUE-ID

You can use : environment or description or labels or custom fields prefixed with customfield_ or any other field that is writable.

You can obtain the customFieldIds using this procedure :
Please note, the Administer Jira Global permission is necessary to complete these steps.

  1. Navigate to Settings (cog Icon) > Issues > Custom fields under the Fields section

    Click on the More () icon to the right of the custom field you are obtaining the ID

    Select the View field information option

  2. Observe the URL in your browser, which will contain the ID of the field:
    https://labo21.atlassian.net/secure/admin/ConfigureCustomField!default.jspa?customFieldId=10004

In the above example, the extFieldId is customfield_10004

The dropdown values of a Jira drop down can be found this way :

  1. Navigate to Settings (cog Icon) > Issues > Custom fields under the Fields section

  2. Find the custom field you want to configure and click  > Contexts and default value Edit Options.

  3. Edit an option and observe the URL in you browser :
    https://your-domain.atlassian.net/secure/admin/EditCustomFieldOptions!edit.jspa?fieldConfigId=10104&atl_token=XXXX-9492-4e27-bc70-409acfbc0fd8_3dac7c9dafd3bXXXXXXX3cb6deXXd4X_lin&selectedValue=10000

In the above the dropdown value id is 10000

Webinar:

Look at the recorded webinar on Jira Integration: (direct link here)

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.