Anwendungen

Inhaltsverzeichnis

Einleitung
Generelle Pflege
- Anwendung bearbeiten
- Anwendung löschen
Jira mit foreknown verbinden
Personio mit foreknown verbinden
Mail (SMTP) mit foreknown verbinden

Einleitung

In dem Bereich “System Administration / Anwendungen” werden in foreknown alle Verbindungen zu externen Anwendungen konfiguriert. Aktuell unterstützt foreknown eine Integration der Aufgaben- und Projektmanagement Lösung “Atlassian Jira”.

Die Verwaltung von Anwendungen ist nur Benutzern mit der Rolle “Konto Administrator” möglich

Generelle Pflege

Wenn bereits eine oder mehrere Anwendungen erstellt sind, werden diese in Form einer blätter, sortier- und filterbaren Liste angezeigt.

Hier kann in jeder Zeile über die drei Punkte am Anfang das Aktionsmenü geöffnet werden. Dies bietet die Optionen, die jeweilige Anwendung zu bearbeiten oder zu löschen.

Zudem sind in der Listenansicht die Namen, App-Id und Status der einzelnen Anwendungen zu finden.

Anwendung bearbeiten

Um die in Schritt 1 festgelegten Angaben zu bearbeiten, klickst Du auf das Aktionsmenü und dann auf "Anwendung bearbeiten". Es öffnet sich der "Jira Anwendung aktualisieren" Dialog.

Mit der Aktion "Speichern" werden die Änderungen übernommen. Die Aktion "Zurücksetzten"(Pfeil im Kreis) leert alle Felder und bei der Aktion "Abbrechen" wird der Dialog geschlossen.

Nach oben ↑

Anwendung löschen

Um eine Anwendung wieder zu löschen, musst Du auf das Aktionsmenü und dann "Anwendung löschen" klicken. Es öffnet sich der "Anwendung löschen" Dialog, der mit "Löschen" bestätigt werden muss.

Auch in Jira kann die Verbindung zu foreknown gelöscht werden. Dazu muss unter "Einstellungen / Apps / foreknown / Konfiguration" in der Liste bei der entsprechende App-Id auf das Aktionsmenü geklickt und dann "Entfernen" gewählt werden.

Nach oben ↑

Jira mit foreknown verbinden

Im Folgenden wird dir in drei Schritten gezeigt, wie Du Deine Jira Projekte mit foreknown verbindest und Projekte oder einzelne Aufgaben synchronisierst.

Schritt 1: Jira Anwendung in foreknown erstellen

Um eine neue Jira Anwendung in foreknown hinzuzufügen, muss zunächst auf das Plus oben rechts in der Ecke geklickt werden.

Es öffnet sich der "Jira Anwendung erstellen" Dialog:

Folgende Eingaben können/müssen für eine neue Anwendung angegeben werden:

Name: Hier muss ein eindeutiger Name gewählt werden.
Automatische Erstellung von Benutzern: Wird diese Checkbox aktiviert, werden neue Benutzer in foreknown bei der Synchronisation erstellt. Diese Checkbox sollte in der Regel aktiviert werden, um eine problemlose Synchronisation zu ermöglichen.

Hinweis: Benutzer, die noch nicht in foreknown existieren, werden mit der Benutzer-ID aus Jira und dem Vor- und Nachnamen in foreknown erstellt und mit den Aufgaben, Kommentaren, Arbeitsprotokollen verlinkt. Nachträglich können die Benutzerdaten in foreknown vervollständigt werden. Mit der Erstellung ist sichergestellt, dass der foreknown Benutzer mit dem Jira Benutzer über die Jira Benutzer ID verlinkt ist und somit bei zukünftigen Synchronisationen eindeutig zugeordnet werden kann.
Automatische Erstellung von Projekten: Wird diese Checkbox aktiviert, werden neue Projekte und zugehörige Daten wie Aufgaben, Kommmentare und Arbeitszeiten direkt beim Erstellen des Projekts in Jira übernommen. Ist die Checkbox deaktiviert, werden nur Projekte und dessen Daten übernommen, die mindestens einmal manuell aus Jira heraus synchronisiert wurden.
Datenschutz-Hinweis akzeptieren: Damit Daten aus Jira übertragen werden können, muss der Datenschutz-Hinweis akzeptiert werden. Wird dem Datenschutz-Hinweis nicht zugestimmt, werden keine Daten aus Jira übertragen.

Hinweis: Als Datenverarbeiter gemäß DSGVO möchten wir sicherstellen, dass betroffene Personen darüber informiert werden, dass personenbezogene Daten dieser Personen z.B. durch eine Jira-Integration in foreknown gespeichert und verarbeitet werden. Mit dieser Checkbox wird versichert, dass alle betroffenen Personen entsprechend informiert wurden und dem zugestimmt haben.

Mit der Aktion "Speichern" wird die neue Jira Anwendung gespeichert. Mit der Aktion "Zurücksetzen" und "Abbrechen" werden die Eingaben verworfen und im Falle der Aktion "Abbrechen" wird der Dialog geschlossen.

Wurde eine neue Jira Anwendung angelegt, wird sie in der Liste mit der App-Id und dem Status angezeigt.

Die App-Id wird in der Liste hinter dem Namen angezeigt. Diese ID wird bei der Einrichtung des Jira-Plugins in der gewünschte Jira Instanz benötigt, um eine Verbindung mit der foreknown Instanz herstellen zu können.

In der Liste der Anwendungen / Jira wird pro Eintrag ein Status angezeigt:

Getrennt: Es wurde noch keine Verbindung mit einer Jira Instanz hergestellt.
Verbunden: Die Verbindung mit einer Jira Instanz wurde hergestellt.

Nach oben ↑

Schritt 2: foreknown Plug-In in Jira installieren

Das foreknown Jira Plug-In ist aktuell noch als ein “private Plug-In” konfiguriert und somit noch nicht über den Atlassian Marketplace auffindbar. Bei Interesse wende Dich bitte an unseren Support (support@foreknown.io), um die erforderliche URL für die Installation des foreknown Plug-In zu erhalten.

Um die App mit der von uns zur Verfügung gestellten URL zu installieren, musst du zunächst in dem entsprechenden Projekt auf "Apps/Apps verwalten" gehen. Dort muss in den "Einstellungen", die unterhalb der "User-installed apps" zu finden sind, die Checkbox "Enable private listings" aktiviert werden.

Danach ist auf der "Apps verwalten" Seite oben rechts "App hochladen" zu finden. Durch einen Klick darauf öffnet sich der "Upload app" Dialog.

In diesem muss die von Uns zur Verfügung gestellte URL eingegeben werden. Durch "Upload" beginnt die Installation der App, "Cancel" verwirft die Eingabe und schließt den Dialog.

Nach oben ↑

Schritt 3: Verbindung herstellen

Über die Konfigurationsseite “Einstellungen / Apps / foreknown / Konfiguration” wird über den Link “Neue foreknown App verbinden…” der Popup Dialog “Foreknown App verbinden” geöffnet, wo die in foreknown erstellte “App-Id” der Jira Anwendung eingetragen werden muss.

Mit der Aktion “Absenden” wird die App-Id in foreknown geprüft. Wenn dazu eine Jira Anwendung in foreknown gefunden wird, so wird eine Verbindung hergestellt und der Status der Jira Anwendung in foreknown erhält den Status “Verbunden”.

Projekt synchronisieren

In den Projekteinstellungen findet man unter dem Bereich “Apps” in der Navigation den Eintrag “Foreknown”. Dieser Link öffnet den Dialog “Foreknown Projekteinstellungen”, wo über die Aktion “Projekt synchronisieren” der Popup Dialog “Synchronisation mit foreknown” geöffnet wird.

Anwendungen - Synchronisation mit Foreknown

Die folgenden Eingaben können/müssen für eine neue Anwendung angegeben werden:

Arbeitsprotokolle synchronisieren: Wenn dieses Kontrollkästchen aktiviert ist, werden alle Arbeitsprotokolle ab dem angegebenen Datum synchronisiert.
Kommentare synchronisieren: Wenn diese Checkbox aktiv ist, werden alle Kommentare ab dem angegebenen Datum synchronisiert.
Datum: Das Startdatum, ab dem die Daten übertragen werden sollen.

Mit der Aktion "Senden" wird das Projekt synchronisiert, die Aktion "Schließen" schließt den Dialog.

Aufgabe synchronisieren

Es ist auch möglich, eine einzelne Aufgabe in Jira mit foreknown zu synchronisieren. Dazu wählt man die gewünschte Aufgabe aus und öffnet über das Aktionsmenü die Aktion “Sync mit foreknown”. Diese Aktion öffnet ebenfalls den “Synchronisation mit foreknown” Dialog (Siehe: Projekt Synchronisieren) mit dem Unterschied, dass nur die ausgewählte Aufgabe und nicht das gesamte Projekt erneut synchronisiert wird. Es gelten die gleichen Einstellungsmöglichkeiten.

Hinweis: Die Angabe eines Datums, ab dem Kommentare und Arbeitszeiten synchronisiert werden sollen, dient der Optimierung der Synchronisation, da häufig nur die letzten Änderungen an Kommentaren bzw. Arbeitszeiten fehlen und durch die Synchronisation übertragen werden sollen.

Nach oben ↑

Tempo verbinden

Wichtig: Die folgenden Schritte müssen von einem Benutzer mit VOLLEM ZUGRIFF auf ALLE Arbeitszeiten durchgeführt werden.

Für den Fall, dass Du auch die "Tempo" Jira App mit foreknown verbinden möchtest, musst Du zunächst die API Integration unter "Apps/Apps verwalten/Timesheets/Configure/API Integration" öffnen.

Hier muss ein Token unter "+ Neues Token" erstellt werden. In dem "Token erstellen" Dialog müssen die Checkboxen

Zeitnachweise anzeigen
Account anzeigen (optional, erzeugt ein Label für den zugeordneten Account an der Aufgabe)

aktiviert werden. Nach dem Speichern wird ein neues Token erzeugt, welches kopiert und in der foreknown Konfiguration von Jira unter "Tempo API Token einrichten..." eingefügt werden muss.

Wird der Dialog nach Eintragen des Tokens mit "Absenden" bestätigt, verbindet sich Tempo mit foreknown. Mit der Aktion "Close" werden die Eingaben verworfen und der Dialog geschlossen.

Doku-Hinweis: Durch die Integration mit Jira und Tempo Timesheets werden zusätzliche Informationen (Labels) Deiner foreknown Instanz übermittelt. Diese sind für die automatische Erzeugung von Leistungen über die Regeln sehr hilfreich und daher in der Dokumentation unter Faktura / Regeln verwalten näher beschrieben.

Nach oben ↑

Personio mit foreknown verbinden

Nachfolgend wird beschrieben, wie Du Dein Personio System mit foreknown verbinden kannst, um die Abwesenheitszeiten aus Personio mit foreknown regelmäßig synchronisieren zu können. Diese Integration ermöglicht es Dir, dass Deine Mitarbeiter ausschließlich in Personio Abwesenheitszeiten, wie z.B. Urlaub, Krankheit, pflegen und diese automatisiert nach foreknown übertragen werden.

Sobald eine Personio Anwendung aktiv in foreknown eingerichtet ist, finden folgende Synchronisationen automatisch statt:

Alle 5 Minuten (wenn nicht anderes eingestellt) werden Änderungen an Abwesenheiten in Personio mit foreknown synchronisiert. Dabei werden nur neue und geänderte Abwesenheiten übernommen. Löschungen von Abwesenheiten werden bei dieser Synchronisation nicht berücksichtigt.
Einmal nächtlich wird eine vollständige Synchronisation von Abwesenheiten durchgeführt. Diese berücksichtigt immer einen Zeitraum ausgehend vom aktuellen Tag, der zwei volle Monate rückwirkend und alle zukünftigen Monate des aktuellen Jahres betrachtet. Wenn der aktuelle Tag >= dem 1. Juli ist, werden immer 6 Monate im Voraus mit einbezogen. Diese Synchronisation berücksichtigt auch Löschungen von Abwesenheiten.

Zusätzlich können Synchronization auch manuell ausgelöst werden:

Über die Zeiterfassung kann jeder Mitarbeiter oder ein Team Manager für seine Mitarbeiter die Aktion "Abwesenheitszeiten synchronisieren" ausführen, wodurch für den aktuellen Monat die Abwesenheiten aus Personio für den entsprechenden Mitarbeiter in foreknown aktualisiert werden.
Über die Personio Anwendung unter "System Administration / Anwendungen" kann ein Account Administrator die Aktion "Synchronisation starten" auslösen, welche eine vollständige Synchronisation wie oben beschrieben auslöst. Diese Aktion sollte nur als Ausnahme gesehen werden, da dadurch umfangreiche Daten von Personio abgefragt werden.

Nach oben ↑

Schritt 1: API-Key in Personio erstellen

Um eine Verbindung zum Personio System aufbauen zu können, sind entsprechende Zugriffsdaten in Personio zu erzeugen. Nachdem Du Dich als "Administrator" in Personio angemeldet hast, öffnest Du die Einstellungen.

Auf der Seite findest Du einen Kasten "Integrationen" den Link "API-Zugriffsdaten". Dieser führt Dich in einen Dialog, wo alle API-Zugriffsdaten für Deine Personio Instanz erzeugt werden können.

Anwendungen - Personio - API-Zugriffsdaten erstellen

Führe nun folgende Schritte aus:

Klicke auf "Neue Zugriffsdaten generieren".
Vergebe einen eindeutigen Namen z.B. "foreknown Sync"
Wähle unter "Integration" den Wert "Andere" aus.
Wähle die Checkboxen für "Mitarbeitende / Lesen" und "Abwesenheiten / Lesen" aus.
Wähle unter "Lesbare Mitarbeitendenattribute" die Attribute "E-Mail", "Employee ID", "Kostenstelle", "Personal email" aus.
Schließe diese Aktion mit "Neue Zugriffsdaten generieren" ab.

Wenn alle Daten korrekt eingegeben wurden, erscheinen nun die API-Zugriffsdaten in Form einer Client-ID und eines Secrets. Diese beiden Werte werden für den nächsten Schritt benötigt, um in foreknown eine Personio Anwendung zu erstellen.

Nach oben ↑

Schritt 2: Personio Anwendung in foreknown erstellen

Nachdem die erforderlichen API-Zugriffsdaten erzeugt wurden, kann in foreknown eine Personio Anwendung erstellt werden.

Anwendungen - Personio - Anwendung erstellen

Folgende Schritte sind hierfür erforderlich:

Melde Dich mit einem Benutzer, der über eine "Account-Administrator" Rolle verfügt in foreknown an.
Gehe über die Navigation auf die Seite "System Administration / Anwendungen".
Erstelle eine neue Personio Anwendung durch Klick auf den "+" Button rechts oberhalb der Personio Box.
Vergebe einen eindeutigen Namen für die Anwendung, z.B. "Personio System".
Füge die Client-ID und das Client-Secret aus den zuvor in Personio erstellten API-Zugriffsdaten ein.
Akzeptiere den Datenschutz-Hinweis durch Aktivierung der Checkbox.
Schließe den Schritt mit "Speichern" ab.

Es sollte nun ein Eintrag in der Personio Box erscheinen. Dort befindet sich auch eine Aktion "Verbindung testen". Führe diese Aktion aus, um sicherzustellen, dass tatsächlich eine Verbindung mit dem konfigurierten Personio System aufgebaut werden kann. Eine Systemmeldung zeigt an, ob die Verbindung hergestellt wurde oder nicht.

Nach oben ↑

Schritt 3: Konfiguration der Personio Anwendung

Die Personio Anwendung stellt für die Synchronisation initial ein Standardverhalten bereit, welches im Bedarfsfall angepasst werden kann.

Folgende Einstellungen werden dabei berücksichtigt:

runtimeInterval: Legt einen Wert in Minuten fest und definiert, wie häufig geänderten Abwesenheitszeiten von der Personio Instanz abgefragt werden sollen. Der Standartwert beträgt 5.
syncStartDate: Legt das Startdatum fest, ab dem Einträge aus Personio nach foreknown übernommen werden sollen. Wenn keine Konfiguration hinterlegt ist, werden standardmäßig ausgehend vom aktuellem Datum
- zwei vollständige Monate rückwirkend betrachtet
- immer alle Monate bis zum Ende des Jahres betrachtet
- immer 6 Monate im Voraus betrachtet, wenn das aktuelle Datum >= dem 1. Juli lautet.
syncEnabled: Über diese Einstellung kann die Synchronisation aktiviert (true) bzw. deaktiviert (false) werden. Der Standardwert ist "true";
syncComments: Legt fest, ob der Kommentar, der in Personio optional an einer Abwesenheit angegeben werden kann, bei der Synchronisation nach foreknown übernommen wird. Standardwert ist "true".
typeMapping: Sowohl in Personio als auch in foreknown existieren Abwesenheitstypen, die bei einer Synchronisation miteinander verbunden werden müssen. Initial ist eine Zuordnung hinterlegt, die sich an den Kategorien der Abwesenheitsarten in Personio orientiert (siehe Einstellungen / Abwesenheit).

Um diese Standardeinstellungen für eine Personio Anwendung anzupassen, können individuelle Einstellungen über die Aktion "Anwendung konfigurieren" (siehe Aktionsmenü vor der Personio Anwendung) in Form einer definierten json-Struktur hinterlegt werden.

Folgendes Beispiel zeigt eine mögliche angepasste Konfiguration der Personio Anwendung:

{
    "runtimeInterval": 5,
    "syncStartDate": "2022-07-01",
    "syncEnabled": true,
    "syncComments": false,
    "typeMapping": {
        "Überstunden": "OVERTIME"
    }
}

Die Definition des "typeMapping" findet wie folgt statt.

Auf der linken Seite steht der Name der Abwesenheitsart in Anführungszeichen. Dieser ist unter "Einstellungen / Abwesenheit" in Personio zu finden.
Auf der rechten Seite steht der Abwesenheitstyp von foreknown in Anführungszeichen. Dieser kann folgende Werte enthalten
- VACATION: Urlaub
- SICK_LEAVE: Krankheit
- OVERTIME: Überstundenabbau
- ABSENT_TIME: Sonstige Abwesenheit
Wenn eine Personio Abwesenheitsart ignoriert werden soll, so kann statt eines foreknown Abwesenheitstyps der Wert "skip" angegeben werden. Alle Abwesenheitsbuchungen aus Personio, die diese Abwesenheitsart haben, werden dann nicht übernommen.

Das "typeMapping" muss nur für die Personio Abwesenheitsart geändert werden, wo die Standardzuordnung gemäß der Personio Kategorie nicht passt. Das Standardverhalten ist wie folgt:

Kategorie "Krankheitsfall" wird dem Abwesenheitstyp "Krankheit" in foreknown zugeordnet.
Kategorie "Bezahlter Urlaub" wird dem Abwesenheitstyp "Urlaub" in foreknown zugeordnet.
Alle anderen Kategorien werden dem Abwesenheitstyp "ABSENT_TIME" in foreknown zugeordnet.
Kategorie "Mobiles Arbeiten" wird nicht nach foreknown übernommen ("skip").

HINWEIS: Eine Zuordnung einer Personio Abwesenheitskategorie auf den Abwesenheitstyp "OVERTIME" ist standardmäßig nicht möglich, da es keine Kategorie für Überstunden gibt. Da in Personio aber individuelle Abwesenheitsarten z.B. mit der Kategorie "Sonstige bezahlte Freistellung" erstellt werden können, müsste hierfür eine Zuordnung auf "OVERTIME" über die Konfiguration vorgenommen werden.

Nach oben ↑

Mail (SMTP) mit foreknown verbinden

Nachfolgend wird beschrieben, wie Du in foreknown einen SMTP-Server für den Versand von E-Mails konfigurieren kannst.

Benutzer mit der Rolle "Konto-Administrator" können über die Navigation unter "System Administration / Anwendungen" eine Anwendung von Typ "Mail (SMTP)" einrichten. Durch einen Klick auf den entsprechenden Hinzufügen-Button (Plus) öffnet sich folgender Dialog:

Anwendungen - Mail (SMTP) - Konfiguration

Folgende Eigenschaften müssen gepflegt werden:

Name: Es muss ein eindeutiger Name eingegeben werden, der für die Anzeige in der Liste der Anwendungen und als Bestandteil des Absenders einer E-Mail verwendet wird.
Server: Name des Servers z.B. smtp.domain.de. Ein Standard-Port wird anhand der ausgewählten Verbindungssicherheit automatisch ermittelt. Verwendet Ihr Anbieter einen unüblichen Port, muss dieser in der Form server:port angegeben werden. Beispiel: smtp.domain.de:1234
E-Mail: E-Mail Adresse des Postfachs, welches für den Versand von E-Mails via SMTP verwendet wird.
Benutzer: Benutzername des Postfachs, welches für den Versand von E-Mails via SMTP verwendet wird.
Passwort: Passwort des Postfachs, welches für den Versand von E-Mails via SMTP verwendet wird.
Verbindungssicherheit: Art der Verbindungssicherheit, die für den Versand von E-Mails via SMTP verwendet werden soll. Es wird STARTTLS und SSL/TLS angeboten. Unverschlüsselte Verbindungen werden von foreknown aus Sicherheitsgründen nicht unterstützt.
Datenschutz-Hinweis akzeptieren: Damit Daten über SMTP versendet werden können, muss der Datenschutz-Hinweis akzeptiert werden. Wird dem Datenschutz-Hinweis nicht zugestimmt, können keine E-Mails versendet werden.

Hinweis: Als Datenverarbeiter gemäß DSGVO möchten wir sicherstellen, dass betroffene Personen darüber informiert werden, dass personenbezogene Daten dieser Personen z.B. durch eine Mail (SMTP) Integration in foreknown gespeichert und verarbeitet werden. Mit dieser Checkbox wird versichert, dass alle betroffenen Personen entsprechend informiert wurden und dem zugestimmt haben.

Mit dem Speichern der Daten wird eine neue Anwendung vom Typ "Mail (SMTP)" erstellt. Über die Aktion "Verbindung testen", kann überprüft werden, ob eine E-Mail über den angegebenen SMTP-Server versandt werden kann.

Nach oben ↑

Dokumente

Zurück zu "System Administration"