Grobkonzeption - garaio/jira2vertec-Gateway GitHub Wiki
Anforderungen
Die Rapportierung von Leistungen soll direkt in JIRA im Kontext des bearbeiteten Tasks erfolgen können ODER alternativ auch im Vertec erfolgen (der Projektleiter entscheidet sich für einen Pfad und kontrolliert dies organisatorisch)
Gespräche mit den Projektleitern haben gezeigt, dass auf die Informationen zum Burndown in JIRA nicht verzichtet werden soll, weshalb in den meisten Projekten von einer Rapportierung in JIRA auszugehen ist
Dies impliziert, dass bezüglich den erfassten Leistungen zwei Datenbestände vorhanden sind (JIRA und Vertec)
Technische Grundlagen
JIRA bietet ein Listener Interface, über welches durch Events (z.B. Rapportieren einer Leistung) eigener Code angestossen werden kann (wird heute für die Schnittstelle zu Wombat verwendet)
JIRA bietet ein API, über welches auf das Objektmodell in JIRA zugegriffen werden kann (CRUD)
Jede in JIRA erfasste Leistung besitzt eine eindeutige ID
Vertec bietet die Möglichkeit, die ID's der Leistung aus JIRA zu speichern
Jedes Element (Phase) auf welches Rapportiert werden kann und jede erfasste Leistung besitzt eine eindeutige ID
Fachliches Lösungskonzept
Grundsatz
Die Schnittstelle ist unidirektional: JIRA -> Vertec; es werden KEINE Daten zurück ins JIRA übertragen.
Verknüpfung von JIRA Tasks und Vertec Projektphasen
Die Verknüpfung von JIRA Tasks mit Vertec Projektphasen erfolgt in JIRA.
Dazu werden alle für die Rapportierung verfügbaren Elemente aus Vertec ausgelesen, wenn ein JIRA Task mit einem Rapportierungselement verknüpft werden soll (Projekt, Phase, eindeutige ID).
Dabei soll zuerst das Projekt ausgewählt werden können und in einem zweiten Schritt eine der zu diesem Projekt gehörenden Phasen. (2 Dropdown-Felder in JIRA).
Überführung der Leistungen in Vertec
In JIRA erfasste Leistungen werden über den WebService in Vertec geschrieben (ID der Vertec Phase, Datum, Leistung in h, Text, Bearbeiter, ID der JIRA Leistung, ID des JIRA-Tasks (dem Text zur Leistung vorangestellt)).
Mutationen in JIRA führen zu einer Änderung in Vertec.
Behandlung von Ausnahmefällen
Falls die zu ändernde Leistung nicht mehr mutierbar ist (Leistung bereits verrechnet), wird eine Differenzleistung erzeugt. (Innerhalb der gleichen Phase des Projekts, sofern diese noch bebuchbar ist).
Weitere Mutationen ändern die bestehende Differenzleistung. Es wird erst dann eine neue Differenzleistung in Vertec erzeugt, wenn die bestehende Differenzleistung auch bereits verrechnet wurde. Da sich der Status einer Leistung beliebig ändern kann (offen -> verrechnet -> offen) müssen immer alle in Vertec vorhandenen Leistungen zu einer Leistung in JIRA berücksichtigt werden.
Wenn in JIRA keine Zuordnung zu einer Vertec Projektphase vorgenommen wurde, dann wird die Leistung in die dazu konfigurierte Phase gebucht. Diese Phase gilt für ALLE nicht zugeordneten Leistungen. Projektleiter können im Vertec über eigene Sichten die relevanten Sätze filtern.
Wenn die Projektphase zugeordnet, aber als Ganzes nicht bebuchbar ist (z.B. Projektphase ist inaktiv), dann wird die Leistung in entsprechend konfigurierte Phase gebucht.
Verhindern von Mutationen an Leistungen, welche bereits in Rechnungen enthalten sind
Um zu verhindern, dass bereits auf einer Rechnung aufgeführte Leistungen noch mutiert werden, muss die Rechnung in Vertec auf den Status "verrechnet" gesetzt werden.
Alle darin enthaltenen Leistungen erhalten dadurch ebenfalls den Status "verrechnet" und können nicht mehr mutiert werden.
Die Rechnung wird dadurch noch nicht verbucht, dies erfolgt in einem separaten Schritt.
Der Projektleiter hat die Möglichkeit, die Verrechnung rückgängig zu machen und die Rechnung anzupassen, solange diese noch nicht verbucht wurde (danach muss die Rechnung zuerst storniert werden).
Sperrdatum
In Vertec wird monatlich ein Sperrdatum gesetzt.
Dies hat zur Folge, dass ab diesem Zeitpunkt Leistungen, welche vor dem Sperrdatum datiert sind, nicht mehr bearbeitet werden dürfen und keine vor dem Sperrdatum datierte Leistungen mehr erfasst werden dürfen.
Die von Bearbeitern in Vertec erfassten Freigaben werden als individuelles Sperrdatum interpretiert. Das Bis-Datum auf der Freigabe wird als Sperrdatum interpretiert, wenn auf der Freigabe "freigabeSelbst" gesetzt ist und das Datum nach dem systemweiten Sperrdatum liegt. Andernfalls gilt das Systemweite Sperrdatum.
Mehr Informationen zum Thema Bearbeiterfreigaben sind im Kapitel "Voraussetzungen in Vertec" zu finden. Die Verwendung dieses Features ist optional.
In JIRA erfasste oder mutierte Leistungen, welche zugeordnet werden können, jedoch vor das Sperrdatum fallen, werden in die dafür konfigurierte Phase gebucht.
Nicht funktionale Anforderungen
Die Schnittstelle soll offen konzipiert und umgesetzt werden. Eine Kapselung in ein JIRA-Plugin ist dabei zu bevorzugen.