Atlassian Jira Connector
Installation und Konfiguration
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2023.
Alle Rechte vorbehalten. Alle verwendeten Hard- und Softwarenamen sind Handelsnamen und/oder Marken der jeweiligen Hersteller.
Diese Unterlagen sind streng vertraulich. Durch die Übermittlung und Präsentation dieser Unterlagen alleine werden keine Rechte an unserer Software, an unseren Dienstleistungen und Dienstleistungsresultaten oder sonstigen geschützten Rechten begründet. Die Weitergabe, Veröffentlichung oder Vervielfältigung ist nicht gestattet.
Aus Gründen der einfacheren Lesbarkeit wird auf die geschlechtsspezifische Differenzierung, z.B. Benutzer/-innen, verzichtet. Entsprechende Begriffe gelten im Sinne der Gleichbehandlung grundsätzlich für beide Geschlechter.
Installation
Vor der Installation des Atlassian Jira Connector muss sichergestellt werden, dass der Mindbreeze Server installiert und der Atlassian Jira Connector in der Lizenz inkludiert ist. Zur Installation oder Aktualisierung des Konnektors verwenden Sie bitte das Mindbreeze Management Center.
Konfiguration von Index und Crawler
Navigieren Sie auf den Reiter „Indices“ und klicken Sie rechts oben auf „+ Add Index“, um einen neuen Index zu erzeugen.
Fügen Sie eine neue Datenquelle durch Klick auf „Add Data Source“ rechts oben hinzu. Wählen Sie die Category „Atlassian Jira“ aus.
Setzen Sie folgende notwendige Einstellungen:
Benutzername eines Jira-Benutzers der Leserechte auf die REST-API besitzt. ACHTUNG: Dieser Benutzer muss dieselbe Zeitzonen Präferenz gesetzt haben, wie die Zeitzone des Jira Servers. Wenn „Disable ACLs“ gesetzt ist, können die Felder „User Name“ und „Password“ leer gelassen werden. Für weitere Informationen zu „Disable ACLs“ siehe weiter unten. | |
„Password“ | Passwort des Benutzers Wenn Sie eine Jira Cloud-Instanz indizieren möchten, muss hier stattdessen das API-Token gesetzt werden. Wie Sie diesen erstellen, erfahren Sie im nächsten Abschnitt. |
„Atlassian Jira URL“ | URL unter der die Jira REST-API erreichbar ist |
Um ein API-Token zu erstellen, gehen Sie auf https://id.atlassian.com/manage-profile/security/api-tokens und melden Sie sich mit dem Jira-Benutzer an, der für das Crawlen verwendet werden soll. Klicken Sie anschließend auf „Create API token“ um das Token zu erstellen, zu benennen und dann zu kopieren.
Folgende Einstellungen sind optional:
„REST API Base Path“ (Advanced Setting) | Normalerweise befindet sich die REST API auf <Atlassian Jira URL>/rest/api/2. Wenn der Pfad zu Ihrer API ein anderer als „rest/api/2“ ist, können Sie diesen hier angeben. |
„Is Cloud“ | Aktivieren Sie diese Option beim Indizieren einer Jira Cloud-Instanz. |
„Ignore Proxy“ | Verwendet keinen HTTP-Proxy, unabhängig was im „Network“-Tab konfiguriert ist. |
„Page Size“ (Advanced Setting) | Setzt die Anzahl der Elemente, die gleichzeitig abgerufen werden. Standardwert: 100 (Hinweis: höhere Werte können den Durchsatz erhöhen, erhöhen jedoch auch den Arbeitsspeicherverbrauch) |
„Crawler Thread Count“ (Advanced Setting) | Anzahl der Threads, die zum Herunterladen von Inhalten verwendet werden. Standardwert: 20 |
„Issue Constraint (JQL)“ | Eine JQL (Jira Query Language) Query, welche die zu crawlenden Issues einschränkt. Z.B.: project = "Machine Learning". Sie können in der Jira-Oberfläche die „Advanced Search“ verwenden, um eine passende JQL Query zu erstellen. Hier finden Sie auch die offizielle Jira-Dokumentation zur JQL Syntax. Hinweis: die Keywords „ORDER BY“ dürfen nicht verwendet werden, da dies der Crawler selbst verwendet. Eine Änderung dieser Option erfordert einen Re-Index. Standardwert: nicht gesetzt (Alle Issues werden gecrawlt) |
„Max Attachment Size (MB)“ | Wenn gesetzt, werden größere Anhänge nicht indiziert. (Hinweis: ein Wert von 0 indiziert gar keine Anhänge) |
„Attachment Extension Include Pattern“ | Wenn gesetzt, werden nur Anhänge indiziert, dessen Dateinamenerweiterungen auf diesen regulären Ausdruck matchen. (Java Regex) z.B. odt|xls|doc|docx |
„Include Issue Comments“ | Wenn gesetzt, werden Kommentare zu Issues als HTML-Content gesetzt. |
„Disable ACLs“ | Wenn gesetzt, werden keine ACL-Informationen Indiziert. Nur für öffentliche Server verwenden. Aktivieren Sie außerdem in der Index-Konfiguration die Option „Unrestricted Public Access“ (Advanced Setting) und deaktivieren Sie die Option „Enforce ACL Evaluation“. ACHTUNG: Alle Dokumente am Index sind anschließend für jeden Benutzer einsehbar) |
Im Normalfall ist diese Option nicht aktiviert und alle (Jira-)Issues, bei denen „Issue Level Security“ gesetzt ist, sind aus Sicherheitsgründen für niemanden zugänglich. Wenn diese Option aktiviert wird, werden ebenfalls alle Issues, die die Eigenschaft „Issue Level Security“ besitzen gecrawlt und die relevanten Projekt-Berechtigungen werden verwendet. ACHTUNG: Wenn Sie diese Option aktivieren, können Benutzer möglicherweise Issues sehen, die sie in Jira nicht sehen sollen. Verwenden Sie diese Option nur, wenn das für Ihren Anwendungsfall kein Problem darstellt. | |
„Issue Level Security Override“ | Die Projektrollen (eine pro Zeile), welche auf alle Issues Zugriff haben sollen, bei denen „Issue Level Security“ gesetzt ist. ACHTUNG: Wenn Sie diese Option aktivieren, können Benutzer möglicherweise Issues sehen, die sie in Jira nicht sehen sollen. Verwenden Sie diese Option nur, wenn das für Ihren Anwendungsfall kein Problem darstellt. |
Wenn Ihre Jira Instanz eine große Menge an Daten enthält, wird empfohlen, Delta Crawling zu aktivieren:
„Enable Attachment Delta Crawling“ | Wenn aktiv, werden nur Anhänge heruntergeladen, die noch nicht indiziert worden sind |
„Enable Issue Delta Crawling“ | Wenn aktiv, werden nur neue oder geänderte Issues heruntergeladen. Issues, die in Jira gelöscht wurden, werden bei einem Delta Crawl Run nicht gelöscht. Um auch gelöschte Issues aus dem Index zu entfernen, müssen Sie einen „Delete Job Schedule“ konfigurieren (siehe Beschreibung weiter unten). |
„Crawler State Persistence Directory“ | Wenn „Enable Issue Delta Crawling“ aktiv ist, wird ein Verzeichnis benötigt, um Statusinformationen zum letzten Delta Crawl Run (oder Delete Crawl Run) abzulegen. Wenn kein Verzeichnis angegeben wird, werden diese Statusinformationen standardmäßig in „/data/servicedata/<service-id>“ abgelegt. |
„Delete Job Schedule“ | Wenn „Enable Issue Delta Crawling“ aktiv ist, wird empfohlen, hier eine Extended Cron Expression anzugeben (eine Dokumentation und Beispiele zu den cron expressions finden Sie hier). Wird der Cron Job getriggert, wird direkt nach dem nächsten Delta Crawl Run ein Delete Crawl Run gestartet, um Issues und Attachments zu löschen, die nicht mehr in Jira vorhanden sind. Bitte beachten Sie, dass ein Delete Crawl Run bei großen Datenmengen sehr lange dauern kann. |
Speichern Sie anschließend die Konfiguration und starten Sie neu.
Konfiguration des Principal Resolution Service
Wenn Sie im Crawler die Option „Disable ACLs“ angehakt haben, können Sie die Konfiguration des Atlassian Jira Caching Principal Resolution Services überspringen. Ansonsten ist der Atlassian Jira Caching Principal Resolution Service notwendig, damit Gruppen, Rollen etc. korrekt aufgelöst werden können und die Jira Berechtigungen korrekt in Mindbreeze InSpire funktionieren.
Navigieren Sie auf den Reiter „Indices“, scrollen sie runter zum Abschnitt „Services“ und klicken Sie rechts auf „+ Add Service“, um einen neuen Atlassian Jira Caching Principal Resolution Service hinzuzufügen. Wählen Sie das „Service“ „Atlassian Jira Caching Principal Resolution Service“ aus.
Setzen Sie folgende notwendige Einstellungen:
„User Name“ | Benutzername eines Jira-Benutzers der Leserechte auf die REST-API besitzt. |
„Password“ | Passwort des Benutzers |
„Atlassian Jira URL“ | URL unter der die Jira REST-API erreichbar ist |
Folgende Einstellungen sind optional:
„REST API Base Path“ (Advanced Setting) | Normalerweise befindet sich die REST API auf <Atlassian Jira URL>/rest/api/2. Wenn der Pfad zu Ihrer API ein anderer als „rest/api/2“ ist, können Sie diesen hier angeben. | ||||||
Aktivieren Sie diese Einstellung beim Indizieren einer Jira Cloud-Instanz. | |||||||
„Ignore Proxy“ | Verwendet keinen HTTP-Proxy, unabhängig was im „Network“-Tab konfiguriert ist. | ||||||
„Page Size“ (Advanced Setting) | Setzt die Anzahl der Elemente, die gleichzeitig abgerufen werden. Standardwert: 100 (Hinweis: höhere Werte können den Durchsatz erhöhen, erhöhen jedoch auch den Arbeitsspeicherverbrauch) | ||||||
„Maximum Request Threads“ | Die maximale Anzahl von Threads, die für Jira API-Anfragen verwendet werden. Ein höherer Wert kann die Cache-Update-Dauer verkürzen, führt jedoch zu einer höheren Last am Jira-Server. | ||||||
„CSV Access Logging Mode“ | HTTP Anfragen zur Jira API werden in access-log.csv im Log-Verzeichnis protokolliert. Mit dieser Option kann gesteuert werden, wie detailliert diese protokolliert werden. Folgende Auswahlmöglichkeiten stehen zur Verfügung:
|
Wählen Sie anschließend auf ihrem Jira Index den gerade konfigurierten „Caching Principal Resolution Service“ aus.
Weitere Config Optionen zu den Cache, Health Check und den Webservice Services sind in der Dokumentation des Caching Principal Resolution Service beschrieben: https://help.mindbreeze.com/de/index.php?topic=doc/Installation--Konfiguration---Caching-Principal-Resolution-Service/index.htm
Appendix
Einschränkungen
- Jira Permission Schemes mit “Group custom field value” in den “Browse projects” Permission werden nicht unterstützt.
- Jira Issue-Level Security wird nicht unterstützt. Jira Issues mit gesetztem Security Level können in der Suche nicht gefunden werden, wenn ACLs aktiviert sind.
- Damit der Principal Resolution Service für einen Benutzer die jeweiligen Projekt-Rollen oder Gruppen auflösen kann, muss die E-Mail-Adresse des Benutzers öffentlich sichtbar sein. Sie können das hier konfigurieren. Setzen Sie dafür die Spalte „Wer kann das sehen?“ auf „Jeder“ für die E-Mail-Adresse des Benutzers..
Troubleshooting
“ERROR: CrawlRun was unsuccessful” mit URL Pfad “/search” und “status code 400”
Höchstwahrscheinlich ist ein "Issue Constraint (JQL)" konfiguriert, welche den Fehler verursacht
- Überprüfen Sie die konfigurierte "Issue Constraint (JQL)" mithilfe der Funktion "Advanced Search" in Jira direkt. Die JQL muss jedenfalls innerhalb von Jira funktionieren.
- Prüfen Sie, ob es in der JQL keine unerlaubten Schlüsselwörter gibt, wie z.B. "ORDER BY". Entfernen Sie diese Schlüsselwörter.
- Der Crawler verwendet nicht die eingegebene JQL direkt, sondern transformiert diese noch, bevor damit Jira-API-Requests durchgeführt werden. Die eingegebene JQL wird in Klammern gesetzt und es werden noch weitere Einschränkungen und Sortierungen durchgeführt. Die transformierte JQL wird dann als URL-Parameter bei den Jira-API-Requests übergeben. In der Fehlermeldung wird dann die effektive URL angezeigt.
Z.B.: 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...
Dies entspricht decodiert z.B. der effektiven JQL: (proect = \"Big Data\") AND updated >= '2020-06-17 17:10' ORDER BY updated ASC
Wenn Sie die effektive URL aus der Fehlermeldung in einem Browser aufrufen, bekommen Sie eine detaillierte Fehlermeldung, was genau mit der effektiven JQL nicht stimmt. Z.B.: "Field 'proect' does not exist or you do not have permission to view it."
Crawl-Run wird nicht abgeschlossen oder gewisse Issues wurden nicht indiziert
Wenn die Zeitzonenpräferenz des Benutzers der zum Crawlen verwendet wird und dem Jira Server unterschiedlich sind, kann es zu verschiedenen Fehlern kommen. Zum Beispiel ist es möglich, dass der Crawl-Run nie fertiggestellt wird oder gewisse Issues übersprungen werden.
Den ersteren Fall kann man erkennen, indem man das Log des Crawlers überprüft. Wenn immer wieder dieselben URLs aufgerufen werden, kann der Grund dafür an der Zeitzone des Benutzers liegen.
Deshalb sollte immer sichergestellt werden, dass die Zeitzone des Users mit der des Servers übereinstimmt. Diese kann im Profil des Users eingestellt werden.
Ein Benutzer findet zu wenige Dokumente und das Kommando ‚checkprincipals‘ gegen den Principal Resolution Service liefert keine Projektrollen oder Gruppen zurück
Wie in Abschnitt 4.1 Einschränkungen beschrieben, kann der Principal Resolution Service die Projektrollen oder Gruppen von Benutzern nur auflösen, wenn deren Email Adresse öffentlich sichtbar ist. Sie können das hier konfigurieren. Setzen Sie dafür die Spalte „Wer kann das sehen?“ auf „Jeder“ für die E-Mail-Adresse des Benutzers.