Atlassian Jira Connector
Installation and Configuration
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2023.
All rights reserved. All hardware and software names are brand names and/or trademarks of their respective manufacturers.
These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes or other protected rights. The dissemination, publication or reproduction hereof is prohibited.
For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.
.
Installation
Before you install the Atlassian Jira connector, you must ensure that the Mindbreeze server is installed and that the Atlassian Jira connector is included in the license. Use the Mindbreeze Management Center to install or update the connector.
Configuring the Index and Crawler
Navigate to the tab "Indices" and click on "+ Add Index" in the upper right corner to create a new index.
Add a new data source by clicking on "Add Data Source" in the upper right corner. Select the category "Atlassian Jira".
Configure the following required settings:
“User Name” | User name of a Jira user who has read access to the REST API. ATTENTION: This user should have the same time zone preference set as the time zone of the Jira server. If "Disable ACLs" is set, the fields "User Name" and "Password" can be left empty. See below for more information on "Disable ACLs". |
“Password” | Password of the user If you want to index a Jira Cloud instance, the API token must be set here instead. You can find out how to create this in the next section. |
“Atlassian Jira URL” | URL of the Jira REST-API |
To create an API token, go to https://id.atlassian.com/manage-profile/security/api-tokens and log in with the Jira user that will be used for crawling. Then click on "Create API token" to create, name, and then copy the token.
The following settings are optional:
“REST API Base Path” (Advanced Setting) | Normally, the REST API is located at “<Atlassian Jira URL>/rest/api/2”, but if the path to your API is other than "rest/api/2", you can specify it here |
“Is Cloud” | Enable this setting when indexing a Jira Cloud instance. |
“Ignore Proxy” | Ignores the proxy settings of the „Network“ tab |
“Page Size” (Advanced Setting) | Number of Elements that a requested at the same time. Default value: 100 (Note: higher values can increase throughput, but also increase memory consumption) |
“Crawler Thread Count” (Advanced Setting) | Number of threads used to download content. Default: 20 |
„Issue Constraint (JQL)“ | A JQL (Jira Query Language) Query that restricts the issues to be crawled. E.g.: project = "Machine Learning". You can use the "Advanced Search" in the Jira interface to create a suitable JQL query. You can also find the official Jira documentation on JQL syntax here. Note: the keywords "ORDER BY" must not be used, as this is used by the crawler itself. Changing this option requires a re-index. Default value: not set (All issues will be crawled). |
“Max Attachment Size (MB)” | If set, attachment exceeding this size limit are not indexed. (A setting of 0 disables the indexing of attachments completely) |
“Attachment Extension Include Pattern” | If set, only attachments matching this regular expression are indexed (Java Regex) for example. odt|xls|doc|docx |
“Include Issue Comments” | If active, comments on issues are set as HTML content |
“Disable ACLs“ | If set, no ACL information is indexed. Use only for public servers. Also, in the index configuration (Advanced Settings must be enabled), enable the "Unrestricted Public Access" option and disable the "Enforce ACL Evaluation" option. ATTENTION: All documents on the index are then visible to every user. |
„Ignore Issue Level Security“ | Normally, this option is not enabled and all (Jira-)Issues with "Issue Level Security" set are not accessible to anyone for security reasons If this option is enabled, all issues that have the “Issue Level Security” property will also be crawled and the relevant project permissions will be used. CAUTION: If you enable this option, users may see Issues that they are not supposed to see in Jira. |
„Issue Level Security Override“ | The project roles (one per line) that should have access to all Issues where "Issue Level Security" is set. If this option is empty, all Issues with "Issue Level Security" set are not accessible to anyone for security reasons. CAUTION: If you enable this option, users may see Issues that they are not supposed to see in Jira. |
If your Jira instance contains a large amount of data, it is recommended to enable delta crawling:
"Enable Attachment Delta Crawling" | If active, only attachments that have not yet been indexed are downloaded |
"Enable Issue Delta Crawling" | If active, only new or changed issues are downloaded. Issues that have been deleted in Jira are not deleted during a delta crawl run. In order to remove deleted issues from the index, you must configure a "Delete Job Schedule" (see description below). |
"Crawler State Persistence Directory" | If "Enable Issue Delta Crawling" is active, a directory is required to store status information about the last delta crawl run (or delete crawl run). If no directory is specified, this status information is stored in "/data/servicedata/<service-id>" by default. |
"Delete Job Schedule" | If "Enable Issue Delta Crawling" is active, it is recommended to specify an extended cron expression here (documentation and examples of cron expressions can be found here). If the cron job is triggered, a delete crawl run will be started immediately after the next delta crawl run to delete issues and attachments that are no longer present in Jira. Please note that a delete crawl run can take a long time when dealing with large amounts of data. |
Then save the configuration and restart.
Configuration of the Principal Resolution Service
If you have checked the "Disable ACLs" option in the crawler, you can skip the configuration of the Atlassian Jira Caching Principal Resolution Service. Otherwise, the Atlassian Jira Caching Principal Resolution Service is necessary for groups, roles, etc. to be resolved and for Jira permissions to work correctly in Mindbreeze InSpire.
Navigate to the "Indices" tab, scroll down to the "Services" section and click "+ Add Service" on the right to add a new Atlassian Jira Caching Principal Resolution Service. Select the "Service" "Atlassian Jira Caching Principal Resolution Service”.
Configure the following required settings:
“User Name” | User name of a Jira user who has read access to the REST API. |
“Password” | Password of the user |
“Atlassian Jira URL” | URL of the Jira REST-API |
The following settings are optional:
"REST API Base Path" (Advanced Setting) | Normally, the REST API is located at “<Atlassian Jira URL>/rest/api/2”, but if the path to your API is other than "rest/api/2", you can specify it here | ||||||
“Is Cloud” | Enable this setting when indexing a Jira Cloud instance. | ||||||
“Ignore Proxy” | Ignores the proxy settings of the „Network“ tab | ||||||
“Page Size” (Advanced Setting) | Number of Elements that a requested at the same time. Default value: 100 (Note: higher values can increase throughput, but also increase memory consumption) | ||||||
“Maximum Request Threads” | The maximum number of threads used to make Jira API requests. A higher value can shorten the cache update duration, but results in a higher load on the Jira server. | ||||||
„CSV Access Logging Mode“ | HTTP requests to the Jira API are logged in access-log.csv in the log directory. This option can be used to control how detailed they are logged. The following selections are available:
|
Then select the currently configured "Caching Principal Resolution Service" on your Jira index.
Additional config options for the Cache, Health Check and Webservice Services are described in the documentation for the Caching Principal Resolution Service: https://help.mindbreeze.com/en/index.php?topic=doc/Installation--Configuration---Caching-Principal-Resolution-Service/index.htm
Appendix
Restrictions
- Jira permission schemes with "Group custom field value" in the "Browse projects" permission are not supported.
- Jira issue-level security is not supported. Jira issues with security level set cannot be found in the search if ACLs are enabled.
- For the Principal Resolution Service to resolve Project Roles or Groups for a user, the user’s email address needs to be public. You can configure this here. To do this, set the column "Who can see this?" to "Anyone" for the user's email address.
Troubleshooting
“ERROR: CrawlRun was unsuccessful” with URL Path “/search” and “status code 400”
Most likely an "Issue Constraint (JQL)" is configured, which causes the error
- Check the configured "Issue Constraint (JQL)" using the "Advanced Search" function in Jira directly. In any case, the JQL must work within Jira.
- Check that there are no forbidden keywords in the JQL, such as "ORDER BY". Remove these keywords.
- The crawler does not use the entered JQL directly, but transforms it before performing Jira API requests. The entered JQL is enclosed in brackets and further constraints and sorting are performed. The transformed JQL is then passed as a URL parameter in the Jira API requests. The effective URL is then displayed in the error message.
E.g.: https://jira.mycompany.com/ rest/api/2/search?jql=%28proect+%3D+%22Big+Data%22%29+AND+updated+%3E%3D+%272020-06-17+17%3A10%27+ORDER+BY+updated+ASC&startAt=100&maxResults=100&fields=key,updated,description...
This corresponds decoded e.g. to the effective JQL: (proect = \"Big Data\") AND updated >= '2020-06-17 17:10' ORDER BY updated ASC
If you open the effective URL from the error message in a browser, you will get a detailed error message about what exactly went wrong with the effective JQL. E.g.: "Field 'proect' does not exist or you do not have permission to view it."
Crawl run is not completed or certain issues were not indexed
If the time zone preference of the user used for crawling and the Jira server are different, various errors can occur. For example, it is possible that the crawl run is never completed or certain issues are skipped.
The former case can be detected by checking the log of the crawler. If the same URLs are called over and over again, the reason may be the user's time zone.
Therefore, you should always make sure that the user's time zone matches the server's time zone. This can be set in the user's profile.
A User is finding too little documents and calling ‘checkprinicpals’ on the Principal Resolution Service does not return Project Roles or Groups
As described in Section 4.1 Restrictions, the Principal Resolution Service can only resolve the Project Roles and Groups of users, if their Email Address is public. You can configure this here. To do this, set the column "Who can see this?" to "Anyone" for the user's email address.