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 | ||
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 | ||
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
Using $0 to $3 you can than build the strings, defining the project, issue id and url. e.g. the url could be which would use to create the hypelink |  | |
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
"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:
[
{
"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.
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
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 :
Navigate to Settings (cog Icon) > Issues > Custom fields under the Fields section
Find the custom field you want to configure and click > Contexts and default value > Edit Options.
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)