Einrichtung

Der DYCE Connector for Jira & Jira Service Management verbindet sich mit Jira Service Management über eine Atlassian OAuth 2.0 (3LO)-App. Die Einrichtung besteht aus der Registrierung dieser App bei Atlassian und der anschließenden Ausführung des Assistenten DYCE Connector for Jira Unterstütztes Setup in Business Central, der die OAuth2 Einrichtung, die Tabellenzuordnung und die Autorisierung in einem geführten Ablauf erstellt.

Voraussetzungen

• Eine Jira Service Management-Website.
• Berechtigung zum Erstellen einer OAuth 2.0-App in der Atlassian Developer Console.

Registrierung der OAuth 2.0-App in Atlassian

1. Die Atlassian Developer Console öffnen und eine neue OAuth 2.0 integration erstellen.
2. Unter Permissions die von Jira Service Management benötigten APIs hinzufügen und die unten aufgeführten benötigten Scopes gewähren.
3. Unter Authorization die Callback URL setzen auf:

   https://app.dyce.cloud/jira/oauth/callback

   Business Central kann einen Browser-Redirect nicht direkt empfangen, daher wird der Callback über eine DYCE Connect-Seite abgewickelt. Diese Seite zeigt den Autorisierungscode an, der anschließend zurück in Business Central eingegeben wird, um die Authentifizierung abzuschließen.
4. Die Client ID notieren und ein Client Secret erzeugen. Das Secret wird von Atlassian nur einmal angezeigt und sollte daher sicher aufbewahrt werden, bis es in Business Central eingetragen wird.

Benötigte Scopes

Welche Scopes benötigt werden, hängt davon ab, ob nur die Standardfelder von Organisation und Kunde synchronisiert werden, oder ob auch Detailfelder (benutzerdefinierte Felder) zugeordnet sind. Der Einrichtungsassistent schlägt im Schritt Scopes und Autorisierung einen minimalen Startsatz an Scopes vor (manage:jira-organization, manage:jira-service-management-project, read:jira-user, read:servicedesk-request, write:jira-service-management-request, offline_access); für eine vollständige Einrichtung sollten stattdessen die unten aufgeführten Scopes verwendet werden.

Scopes für die Synchronisation von Organisation und Kunde

Scope	Zweck
offline_access	Ermöglicht ein Aktualisierungstoken, damit Zugriffstoken automatisch erneuert werden können
read:jira-user	Liest Jira Benutzerinformationen (wird zum Testen der Verbindung verwendet)
read:jira-work	Allgemeiner Lesezugriff auf Jira
read:servicedesk-request	Liest Service Desk Anfragen
write:servicedesk-request	Erstellt und aktualisiert Service Desk Anfragen
manage:servicedesk-customer	Erstellt und verwaltet Jira Service Management Kunden (Synchronisation Kontakt → Kunde)
read:servicedesk:jira-service-management	Liest Service Desks (Spaces)
write:servicedesk:jira-service-management	Verwaltet Service Desks
read:servicedesk.organization:jira-service-management	Liest, welche Organisationen einem Service Desk zugeordnet sind
write:servicedesk.organization:jira-service-management	Verknüpft Organisationen mit Service Desks (Space-Zuordnung)
delete:servicedesk.organization:jira-service-management	Entfernt die Verknüpfung von Organisationen mit Service Desks
read:organization:jira-service-management	Liest Organisationen
write:organization:jira-service-management	Erstellt und aktualisiert Organisationen (Synchronisation Debitor → Organisation)
delete:organization:jira-service-management	Löscht Organisationen

Zusätzliche Scopes - nur bei Verwendung von Detailfeldern erforderlich

Feldzuordnungen mit Feldkategorie = Benutzerdefiniertes Feld werden über die Detailfelder-API von Organisation/Kunde in Jira übertragen statt über den Standard-Erstell-/Aktualisierungsaufruf und benötigen daher diese zusätzlichen Scopes. Sofern keine benutzerdefinierten Felder zugeordnet sind, können sie entfallen:

Scope	Zweck
read:organization.detail:jira-service-management	Liest Detailfelder der Organisation
write:organization.detail:jira-service-management	Schreibt Detailfelder der Organisation
read:organization.detail-field:jira-service-management	Liest die Definitionen der Detailfelder der Organisation
read:customer.detail:jira-service-management	Liest Detailfelder des Kunden
write:customer.detail:jira-service-management	Schreibt Detailfelder des Kunden
read:customer.detail-field:jira-service-management	Liest die Definitionen der Detailfelder des Kunden

Service-Management-Einrichtung erstellen

Die Seite Jira OAuth2 Einrichtungsliste bietet zudem die Aktion Service-Management-Einrichtung erstellen, mit der eine gebrauchsfertige OAuth2 Einrichtung mit allen oben genannten Scopes - einschließlich der Detailfeld-Scopes - erstellt wird.

Ausführung des Einrichtungsassistenten

Der Assistent DYCE Connector for Jira Unterstütztes Setup kann über die Unterstützte Einrichtung oder direkt über die Suche (Alt+Q) geöffnet werden. Der Assistent führt durch vier Schritte:

1. OAuth Einrichtung
   Es kann eine bestehende, aktivierte OAuth2 Einrichtung wiederverwendet oder eine neue erstellt werden, indem ein Einrichtung Code, die Client ID von Atlassian, die Basis URL (Standard https://api.atlassian.com) und die Token URL (Standard https://auth.atlassian.com/oauth/token) angegeben werden, sowie festgelegt wird, ob Token automatisch erneuert werden sollen. Über OAuth Einrichtungen öffnen lässt sich die Einrichtung auf der vollständigen Listenseite prüfen oder anpassen.
2. Tabellenzuordnung
   Es kann eine bestehende Tabellenzuordnung wiederverwendet oder eine neue erstellt werden, indem die BC Quell Tabelle, der Jira Entitätstyp und eine Beschreibung gewählt werden, sowie optional ein kombinierter Name aktiviert wird. Die Feldzuordnungen für die neue Tabellenzuordnung können direkt in diesem Schritt konfiguriert werden. Entitätskonfiguration öffnen zeigt den für den gewählten Entitätstyp verwendeten Jira REST-Endpunkt an; Details siehe Tabellen- und Feldzuordnung.
3. Scopes und Autorisierung
   Der Assistent listet seinen Startsatz an benötigten Scopes auf und schreibt diese, sofern Benötigte Scopes automatisch übernehmen aktiviert bleibt, in die OAuth2 Einrichtung. Das Client Secret eingeben und Autorisierung starten wählen, um den unten beschriebenen Atlassian Consent-Ablauf zu starten. Anschließend die benötigten Scopes prüfen und die OAuth2 Einrichtung erweitern, falls Detailfelder (benutzerdefinierte Felder) zugeordnet werden sollen.
4. Zusammenfassung
   Zeigt den Status der OAuth2 Einrichtung und der Tabellenzuordnung, den Cloud ID Status sowie den verwendeten Endpunkt an. Von hier aus richten Aufgabenwarteschlange initialisieren und Aufgabenwarteschlange starten die Hintergrundverarbeitung ein - siehe Aufgabenwarteschlange für Details dazu. Mit Beenden wird der Assistent geschlossen.

Autorisierung mit Atlassian

Die Auswahl von Autorisierung starten (oder Authentifizieren auf der unten beschriebenen Jira OAuth2 Einrichtungsliste) durchläuft folgenden Ablauf:

1. Business Central öffnet den Standardbrowser auf der Atlassian Autorisierungsseite.
2. Anmeldung mit einem Atlassian Konto, das Zugriff auf die Jira Service Management-Website hat, und Bestätigung der angeforderten Scopes.
3. Atlassian leitet auf die DYCE Connect Callback-Seite weiter, die einen Autorisierungscode anzeigt.
4. Zurück in Business Central wird bestätigt, dass der Code sichtbar ist, und dieser anschließend in den Dialog Autorisierungscode eingeben eingefügt.
5. Business Central tauscht den Code gegen ein Zugriffs- und Aktualisierungstoken, speichert diese sicher und ruft die Cloud ID und Site-URL der Jira-Website ab.

Nach erfolgreicher Authentifizierung werden Zugriffstoken automatisch vor Ablauf erneuert, solange Zugriffstoken automatisch erneuern aktiviert bleibt; siehe Aufgabenwarteschlange zur Konfiguration des Aktualisierungsschwellenwerts.

Verwaltung der OAuth2 Einrichtungen

Auf der Seite Jira OAuth2 Einrichtungsliste können mehrere OAuth2 Einrichtungen verwaltet werden, zum Beispiel um mehrere Jira-Websites zu verbinden. Jede Einrichtung zeigt ihre Basis URL, Client ID, die Einstellung Zugriffstoken automatisch erneuern, die aktuellen OAuth Scopes, sowie ob ein Client Secret, Zugriffstoken oder Aktualisierungstoken gespeichert ist, zusammen mit den Zeitpunkten Letzte Token Erneuerung und Token läuft ab am.

Verfügbare Aktionen:

• Service-Management-Einrichtung erstellen - erstellt eine Einrichtung mit dem vollständigen Jira Service Management Scope-Satz (siehe Tipp oben), einschließlich der nur für Detailfelder benötigten Scopes.
• Authentifizieren - durchläuft den oben beschriebenen Autorisierungsablauf.
• Aktualisierungstoken - erneuert das Zugriffstoken manuell mithilfe des gespeicherten Aktualisierungstokens.
• Token testen - ruft die Jira API auf, um zu bestätigen, dass das gespeicherte Token noch funktioniert.
• Token leeren - entfernt das gespeicherte Zugriffs- und Aktualisierungstoken, zum Beispiel vor einer erneuten Authentifizierung mit anderen Scopes.

note

Eine OAuth2 Einrichtung kann nicht gelöscht oder umbenannt werden, solange sie von einer Jira Tabellenzuordnung referenziert wird.

Berechtigungen

Mit DYCE Connector for Jira & Jira Service Management werden drei Berechtigungssätze ausgeliefert. Um die darin enthaltenen Berechtigungen im Detail zu prüfen, die Seite Berechtigungssätze (Alt+Q) öffnen und die Aktion Berechtigungen aufrufen.

• DYCEJiraRead (DYCE Connector for Jira Lesen)
  Lesezugriff auf alle Tabellen des Jira Connectors: OAuth2 Einrichtung, Tabellen- und Feldzuordnungen, Entitätskonfiguration, Aktivierungsregeln, zugewiesene Spaces sowie die Nachrichtenwarteschlange und ihre Protokolle. Ist automatisch im Standard-Berechtigungssatz D365 Basic - Read enthalten.
• DYCEJiraEdit (DYCE Connector for Jira Bearbeiten)
  Ergänzt Einfüge-, Änderungs- und Löschrechte für Synchronisationsdaten: die Nachrichtenwarteschlange, das Nachrichtenprotokoll, Tracking-Anfragen und Folge-Aktionen. Dieser Berechtigungssatz wird benötigt, um die Synchronisation bei einem Debitor oder Kontakt zu aktivieren bzw. zu deaktivieren, eine manuelle Synchronisation auszulösen und Nachrichten wie in Nachrichten verstehen beschrieben zu verwalten. Enthält DYCE Connector for Jira Lesen und ist automatisch im Standard-Berechtigungssatz D365 BASIC enthalten.
• DYCEJiraAdmin (DYCE Connector for Jira Admin)
  Ergänzt Einfüge-, Änderungs- und Löschrechte für Konfigurationsdaten: OAuth2 Einrichtung, Tabellen- und Feldzuordnungen, Entitätskonfiguration, Aktivierungsregel-Zuordnungen und Space-Zuordnungen. Enthält DYCE Connector for Jira Bearbeiten und ist automatisch im Standard-Berechtigungssatz D365 SETUP enthalten.

Die Berechtigungssätze bauen aufeinander auf, in dieser Reihenfolge: Lesen, Bearbeiten, Admin. Jeder wird automatisch dem entsprechenden Standard-Berechtigungssatz von Business Central zugeordnet, sodass die meisten Anwender keinen DYCE-spezifischen Berechtigungssatz explizit zugewiesen bekommen müssen - nur Anwender ohne einen der oben genannten Standard-Berechtigungssätze.

Weitere Informationen zu Berechtigungssätzen finden Sie in diesem Teil der Microsoft Dokumentation.