/
JIRA

JIRA

Owned by Karsten Baumgartl (Unlicensed)
Last updated: Jan 10, 2025 by Maximilian Stephan
9 min read

Die Funktionalität

Die Troi-JIRA-Integration bietet im Wesentlichen die folgenden Funktionalitäten:

Verwalten von JIRA Vorgängen und Unteraufgaben direkt aus TROI im "JIRA"-Tab

Projektmanager können ohne Wechsel der Applikation direkt aus Troi heraus Vorgänge und Unteraufgaben anlegen, ändern oder löschen und deren Status überwachen.

Innerhalb der TROI-Software gibt es einen speziellen JIRA-Reiter für Projekte, die die JIRA-Schnittstelle nutzen. In diesem Bereich wird das TROI-Projekt hierarchisch dargestellt.

Für die Zusammenfassung der Daten erfolgt eine Aggregation aller JIRA-Issues pro Kalkulationsposition, sofern mehrere JIRA-Issues mit derselben Position verknüpft sind. Darüber hinaus wird eine Gesamtsumme auf Projektebene berechnet, was eine vereinfachte Kontrolle und Überwachung des Projektfortschritts ermöglicht.

Übergabe des in JIRA erfassten Arbeitsprotokolls an die Troi-Stundenerfassung

Die TROI-JIRA-Integration bietet eine Funktionalität zur Übertragung der in JIRA erfassten Arbeitsprotokolle in die TROI-Stundenerfassung. Diese Funktion erzeugt automatisch Stundenbuchungen für die korrespondierenden Kalkulationspositionen in den zugehörigen TROI-Projekten.

Da das JIRA-Arbeitsprotokoll automatisch an die Troi-Stundenerfassung übergeben wird, entfällt auch hier ein Wechsel der Applikation. Die für die Bearbeitung der Vorgänge zuständigen Mitarbeiter können sich auf ihre eigentliche Arbeit, das Lösen von Problemen, konzentrieren. Ihre erfassten Stunden stehen unmittelbar dem Troi-Projektmanagement zur Verfügung.

TROI unterstützt hierbei sowohl die Übertragung von Arbeitsprotokollen aus einzelnen JIRA-Issues als auch aus JIRA-Issues inklusive Unteraufgaben.

Dieser Prozess der Datensynchronisation erfolgt periodisch, basierend auf voreingestellten Zeitintervallen. Die Wiederholrate ist standardmäßig auf 15 Minuten eingestellt.

 

Übergabe der in JIRA ermittelten Restaufwandsschätzungen an TROI

Ebenso werden im Rahmen dieser Synchronisation die in JIRA ermittelten Restaufwandsschätzungen in die zugehörigen Stundenbuchungen und TROI-Projekte integriert.

 

 

Abb.: Jira-Tab in TROI-Projekten

 

Die Einrichtung der Jira Umgebung in TROI

Für die Einrichtung der Jira Schnittstelle wird sowohl in TROI als auch in JIRA eine administrative Anpassung benötigt.
Unter System →  Systemeinstellungen → Reiter Jira-Integration muss in TROI die JIRA Konfiguration hinterlegt werden:


Abb.: Konfiguration von Jira in TROI

 

  • Server-URL: Bitte geben Sie hier die Server-URL der JIRA-Instanz an

    • incl. http bzw. https

  • Benutzername: Bitte geben Sie hier den Benutzernamen des JIRA-Benutzers an

  • Benutzerpasswort: Bitte geben Sie hier das Passwort des JIRA-Benutzers an

    • Für die Authentifizierung bei JIRA-Cloud wird ein API-Token statt Passwort benötigt. Dieses Token wird als Benutzerpasswort-Passwort in den TROI-EInstellungen eingetragen.

  • Name des Jira-Feldes für die Referenz zur Kalkulationsposition: Bitte geben Sie hier den Namen des CustomFields ein, welches Sie später in JIRA erstellen und zur Eingabe der zu verknüpfenden ID's zu TROI Kalkulationspositionen verwenden.

  • Formatierungs-Zeichenfolge für den Kommentar: %2$s // %1$s 

    • %1$s = Kommentar, %2$s = Ticket-Nummer (Beispiel: '%1$s (%2$s)')

  • JIRA-PlugIn installiert: Bitte die Checkbox aktivieren, sofern das Jira-PlugIn verwendet wird

 

Die Verbindung von JIRA zu TROI

Die Verknüpfung von Troi-Projekten und Jira-Projekten ermöglicht es, Informationen und Daten zwischen beiden Systemen auszutauschen. Die Kommunikation mit JIRA erfolgt über die Standard JIRA-REST-API. Die Verknüpfung erfolgt über den Jira-Projektschlüssel, der in den erweiterten Projekteinstellungen in Troi eingetragen wird.  Um weiteren Datentransfer der Stunden zu ermöglichen, ist es notwendig, in JIRA die Verbindungen zu den TROI-Kalkulationspositionen herzustellen. Um die Verknüpfung zwischen Jira-Vorgängen und Troi-Kalkulationspositionen herzustellen, wird in Jira ein „benutzerdefiniertes Feld“ verwendet. Dieses Feld kann je nach Hosting-Option von Jira auf verschiedene Weise erstellt werden. Bei einer "on demand"-Version (bei Atlassian gehostet) verwenden Sie ein einfaches Textfeld. Bei einer "self-hosted"-Version (Kunde hat eigenen Server für Jira) können Sie das Troi Jira-Plugin installieren und einen neuen Feldtyp verwenden.

Der in der Integration eingesetzte JIRA-Benutzer muss Lesezugriffsrechte für die zugehörigen Jira-Projekte besitzen. Dies stellt sicher, dass alle relevanten Informationen aus Jira abgerufen und in Troi verarbeitet werden können.

Zur eindeutigen Identifizierung der Benutzer zwischen beiden Systemen muss die E-Mail-Adresse des Jira-Benutzers mit der in TROI registrierten E-Mail-Adresse übereinstimmen. Weiterhin muss die E-Mailadresse in Jira öffentlich für alle sichtbar sein, sodass jeder Nutzer diese in dem Mitarbeiterprofil sehen kann.

Die Assoziation von JIRA-Issues zu TROI-Kalkulationspositionen wird durch die Nutzung eines "benutzerdefinierten Feldes" in Jira erreicht. Dieses Feld dient als zentraler Verknüpfungspunkt für die Übertragung relevanter Daten zwischen den beiden Systemen.

Falls erforderlich, kann der in Jira dokumentierte Kommentar durch Hinzufügung der Jira-Issue-Nummer ergänzt werden. Dies bietet eine zusätzliche Methode zur Nachverfolgung und Identifizierung spezifischer Datenpunkte zwischen Jira und TROI.

 

Um den Projektschlüssel in Jira zu finden, kann wie folgt vorgegangen werden:

1.) Öffnen Sie Ihr Jira-Projekt: Gehen Sie zu Ihrem Jira-Projekt und klicken Sie auf die Projektübersicht.

2.) Projektinformationen anzeigen: In der oberen rechten Ecke finden Sie einen Link "Projektinformationen" oder "Project Details". Klicken Sie darauf.

3.) Projektschlüssel finden: In den Projektinformationen sehen Sie den Projektschlüssel unter dem Abschnitt "Projektübersicht" oder "Project Summary".

Alternativ können Sie den Projektschlüssel auch in der URL sehen, wenn Sie das Projekt öffnen. Die URL sieht normalerweise so aus: https://yourdomain.atlassian.net/browse/PROJECT_KEY .

Falls Sie den Projektschlüssel programmatisch abrufen möchten, können Sie versuchen die Jira REST API zu verwenden:
GET https://yourdomain.atlassian.net/rest/api/2/project/PROJECT_KEY?expand=projectKeys

Installation vom Jira-PlugIn (optional)

Das Jira-PlugIn laden Sie bitte unter folgender Adresse herunter (Kompatibel mit Jira 7.13.0 - 8.22.0) → https://dist.TROI.software/Jira/Jira-plugin-1.3.zip

Das Plugin wird mittels einer Konfigurationsdatei konfiguriert. Dazu erstellen Sie die Datei troi.properties im Verzeichnis /target/Jira/home  (Standard: /var/atlassian/application-data/Jira) mit folgendem Inhalt:

 

Config Stuff
#TROI - Jira - Integration TROI.cp_id_field_name= Hier bitte den exakten Namen des benutzerdefinierten Feldes eingeben TROI.TROI_url=Hier bitte die URL Ihrer TROI Installation eingeben z.B. https://kundenname.TROI.de TROI.TROI_user_name=Hier bitte den TROI Benutzernamen eingeben TROI.TROI_user_password_md5=Hier bitte das Kennwort, welches für den o.g. Benutzer in TROI hinterlegt ist, (als MD5 Hash) eingeben. Bspw. hier können Sie Ihr Passwort in einen MD5 Hash konvertieren > http://www.md5-generator.de/ TROI.max_cache_age_in_seconds=3600

Anlegen des benutzerdefinierten Feldes in JIRA

Navigieren Sie dazu zu Administration → Vorgänge/Issues → Benutzerdefinierte Felder/Custom Fields und klicken Sie auf Benutzerdefiniertes Feld hinzufügen/Add Custom Field.



Abb.: Benutzerdefiniertes Feld in Jira hinzufügen

 

Wenn Sie JIRA in der Atlassian Cloud hosten

Wenn Sie Jira in der Atlassian Cloud hosten, muss das JIRA-Plugin nicht installiert werden.

Verwenden Sie in diesem Fall bitte als benutzerdefiniertes Feld / custom field ein einfaches Textfeld Textfeld (einzeilig) / Text Field (single line).



Abb.: Textfeld hinzufügen

 

Wenn Sie selber JIRA hosten

Wenn Sie Jira selbst hosten, können Sie das TROI Jira-PlugIn installieren und haben dann im Bereich Erweitert/Advanced den neuen Feldtyp Calculation position selection field zur Verfügung.

Das PlugIn bietet im Vergleich zur in der Atlassian Cloud gehosteten Variante, die Funktion, die Kalkulationsposition aus einem Drop-Down auszuwählen.

Ebenso wird der Projektpfad angezeigt.

d.h. Projekt → Unterprojekt → Kalkulationsposition, was bei der oben beschrieben Variante nicht der Fall ist. 

Konfigurieren Sie die Screens, in denen das Feld sichtbar sein soll.

 

 

Wenn Sie nun einen neuen Vorgang anlegen, steht Ihnen das zuvor erstelle Feld zur Verfügung.

Geben Sie hier bitte die TROI K-Nummer d.h. die ID der Kalkulationsposition ein, mit der dieser Jira-Vorgang verknüpft werden soll.

Sie erhalten diese von Ihrem TROI-Projektleiter bzw. finden diese in der Kalkulation des TROI Projektes bei Roll-Over über die Kalkulationsposition im Tooltip.

Damit Sie ein Projekt in TROI für die Synchronisierung freigeben, muss in den erweiterten Projekteinstellungen der Jira Schlüssel hinterlegt sein.

Dazu navigieren Sie bitte in das TROI Projekt, klicken oben links das erweitert Icon an → wählen das Projekt und klicken auf den Eintrag Erweiterte Einstellungen.

Dort geben Sie bitte den Jira-Projektschlüssel ein und speichern. 

 

Jira Cloud

Für die Authentifizierung bei Jira Cloud wird ein API Token benötigt.

Dieses Token wird als Benutzerpasswort-Passwort in den TROI-EInstellungen eingetragen.

API Token Generierung bei Atlassian unter https://id.atlassian.com/manage/api-tokens.

 

Tipps

JIRA-Projekt-Schlüssel

Der JIRA-Projekt-Schlüssel lässt in der Standardeinstellung nur Buchstaben von „A“ bis „Z“ zu. Möchte man die Troi- und JIRA-Projektnummern möglichst gleich halten, so stößt man hier relativ schnell an eine Grenze.

Man kann jedoch das zulässige Format für den Projekt-Schlüssel in JIRA ändern. Die relevante Einstellung findest sich unter „Administration“ > „System“ > „Erweiterte Einstellungen“. Hier gibt es einen Eintrag mit dem Namen „jira.projectkey.pattern“. Der Wert stellt einen „regulären Ausdruck“ und sollte nur von jemandem gepflegt werden, der sich damit auskennt.

Um das Troi-Projektnummernformat aus dem obigen Screenshot abzubilden kann man z.B. diesen Ausdruck verwenden: „([A-Z]*)_([0-9]*)_([0-9]*)“

Bitte beachten Sie, dass Sie diese Einstellung am besten ändern, bevor Sie Projekte in JIRA anlegen. Sollten bereits Projekte vorhanden sein, ist eine Änderung des Musters evtl. nicht mehr möglich.

Troubleshooting

Fehlende Stunden bei Übertrag

Problem: 

Es werden nicht alle Stunden rückwirkend übertragen.

Lösung:

Ändern Sie die Anzahl der Tage, welche rückwirkend für Benutzer bzw. Mandanten übernommen werden sollen, über System → Systemeinstellungen → Stundenerfassung.

Abb.: Position für Anzahl Tage, Stunden erfasst/geändert werden können

 

Troubleshooting

Fehlende Stunden bei Übertrag

Problem: 

Es werden nicht alle Stunden übertragen.

Lösung:

Prüfen Sie einmal die folgenden Hinweise:

 

Troubleshooting

Spezialfälle beim Umbuchen in TROI

Problem: 

Stunden aus Jira wurden in TROI umgebucht und sind nun nicht mehr auffindbar.

Lösung:

Das Umbuchen von Stunden aus Jira folgt folgendem Schema:

  1. Wenn Stunden von Jira in ein TROI-Projekt auf Position 1A synchronisiert wurden und die Stunden anschließend in TROI umgebucht werden in ein anderes Projekt auf Position 2B, gibt es zwei Fallunterschiede:

    1. das Projekt, auf das umgebucht wird, ist mit irgendeinem Jira-Projekt verbunden (Projektschlüssel).
      → dann werden die Stunden aus Jira bei der nächsten Synchronisation wieder auf Position 1A gebucht.

    2. das Projekt, auf das umgebucht wird, ist mit keinem Jira-Projekt verbunden.
      → dann bleiben die Stunden aus Jira bei der nächsten Synchronisation auf der Position 2B

  2. Wenn Stunden von Jira in ein TROI-Projekt auf Position 1A synchronisiert wurden und die Stunden anschließend in TROI umgebucht werden in dasselbe Projekt auf Position 1B:
    → dann bleiben die Stunden aus Jira bei der nächsten Synchronisation auf der Position 1B

  3. Wenn Stunden von Jira in ein TROI-Projekt auf Position 1A synchronisiert wurden und die Stunden anschließend in TROI umgebucht werden in dasselbe Projekt auf Position 1B, wobei Position 1B in Jira bei einer anderen Aufgabe eingetragen ist:
    → dann werden die Stunden bei der nächsten Synchronisation von der Position 1B gelöscht. Bei der darauffolgenden Synchronisation werden die Stunden wieder auf die Position 1A synchronisiert.

 

Troubleshooting

Im Jira-Tab werden mehr Stunden angezeigt, als Stunden protokolliert wurden.

Problem: 

In Jira gibt es Task A und Task B. Auf Task B wurde bereits Arbeit protokolliert. Task B wird nun in JIRA zu einem Sub-Task konvertiert und als Parent wird Task A ausgewählt. Task B ist anschließend ein Sub-Task von Task A. In TROI werden die Stunden von Task B nun doppelt im Jira-Tab angezeigt, einmal als Parent-Task und einmal als Sub-Task. Ins Reporting werden die Stunden aber nur einmal übernommen.

Lösung:

In einem Task A soll ein Sub-Task B angelegt werden.

  1. Wenn in einem Task A ein Sub-Task B angelegt werden soll, dann kann dieser im Task A neu angelegt und anschließend Stunden darauf protokolliert werden.

  2. Wenn es bereits einen Task B mit Stunden gibt, der zu einem Sub-Task zu Task A konvertiert werden soll, kann dieser erst einmal einem anderen Task C (z.B. Dummy) zugeordnet werden. Anschließend kann in Task A ein Sub-Task angelegt und dabei der bestehende Sub-Task B ausgewählt werden. Sub-Task B wechselt jetzt von Task C zu Task A und die Stunden werden in TROI im Jira-Tab auch nur einmal angezeigt.

 

 

Erweitertes Troubleshooting

 

Meldung

Verhalten

SKIP CP BECAUSE IT IS LOCKED FOR TIME RECORDING

Dieses Verhalten tritt auf, wenn eine bestimmte Kalkulationsposition für die Zeiterfassung gesperrt ist. (kann auch dort Projektstatus, Unterprojekt, etc. ausgelöst werden)

Unable to update estimation: Issue has no assigned employee

Dieses Verhalten tritt auf, wenn ein Jira-Issue keinem Mitarbeiter zugeordnet ist.

Jira API returned nothing

Dieses Verhalten tritt auf, wenn die Jira API keine Daten zurückgibt.

Jira API returned invalid result

Dieses Verhalten tritt auf, wenn die Jira API ein ungültiges Ergebnis zurückgibt.

Billing parent is locked for time recording

Dieses Verhalten tritt auf, wenn das übergeordnete Abrechnungselement für die Zeiterfassung gesperrt ist.

Billing is billed, so it is not possible to edit it

Dieses Verhalten tritt auf, wenn ein bestimmter Zeiterfassungseintrag bereits abgerechnet wurde und daher nicht bearbeitet werden kann.

Billing is invoiced, so it is not possible to edit it

Dieses Verhalten tritt auf, wenn ein bestimmter Zeiterfassungseintrag bereits in Rechnung gestellt wurde und daher nicht bearbeitet werden kann.

Billing is billed, so it is not possible to delete it

Dieses Verhalten tritt auf, wenn ein bestimmter Zeiterfassungseintrag bereits abgerechnet wurde und daher nicht gelöscht werden kann.

Billing is invoiced, so it is not possible to delete it

Dieses Verhalten tritt auf, wenn ein bestimmter Zeiterfassungseintrag bereits in Rechnung gestellt wurde und daher nicht gelöscht werden kann.

No employee found for SMTP address

Dieses Verhalten tritt auf, wenn kein Mitarbeiter für eine bestimmte E-Mail-Adresse gefunden wird.

Multiple employees found for SMTP address

Dieses Verhalten tritt auf, wenn mehrere Mitarbeiter für eine bestimmte E-Mail-Adresse gefunden werden.

Problem finding employee for SMTP address

Dieses Verhalten tritt auf, wenn ein Problem beim Finden eines Mitarbeiters für eine bestimmte SMTP-Adresse auftritt.

 

Related content

© 2024 Troi GmbH

Informationspflichten • Datenschutz • Impressum