Übersicht über die Integrations-API

Die API ist als Cloud-basierter Webdienst konzipiert, der einen bidirektionalen Datenaustausch
zwischen Indeavor und externen Systemen ermöglicht. Die API-Funktionen umfassen verschiedene Import- und
Exportszenarien für mehrere Indeavor-Entitäten, darunter demografische Daten zu Mitarbeitern,
Zeitpläne und Daten zur Urlaubsverwaltung. Die API akzeptiert und stellt Inhalte in XML-
oder JSON-Formaten über HTTP bereit.

Informationen zu den besten Praktiken beim Design finden Sie unter Best Practices für Schnittstellen.

Integrationsprozess

Der Prozess der technologischen Integration umfasst im Allgemeinen die folgenden Hauptdatenströme und -verarbeitungspunkte:

Indeavor Cloud-basierte Datenspeicherung:
- Speichert Indeavor-Daten, die importiert oder exportiert werden sollen.
Indeavor Cloud-basierte Integrations-API – basierend auf den erhaltenen HTTP-Richtlinie:
- Liest die entsprechenden Daten aus dem WL-Datenspeicher und stellt sie für den Export bereit;
- Aktualisiert Daten im WL-Datenspeicher gemäß der entsprechenden Importquelle aus dem externen System.
Zwischenspeicher für den Datenaustausch – je nach Integrationsumgebung dediziert für
- die Speicherung importierter Quelldaten aus dem externen System in die API;
- die Speicherung der „Datenmodell“-Vorlage für den Export;
- die Speicherung von Exportergebnisdaten aus der API in das externe System.
Externer System Data Exchange Point:
- Stellt Quelldaten für Indeavor zum Import zur Verfügung;
- Stellt Export-„Richtlinien“ (korrekt formatierte Datenmodellvorlage) für den Export bereit;
- Erhält und verbraucht Exportergebnisdaten von Indeavor.
Data Integration Engine – abhängig von der Integrationsumgebung:
- Aktiviert das externe System, um Quelldaten für den Import in Indeavor zu erstellen;
- Speichert Importdaten zur Zwischenspeicherung für den Datenaustausch;
- Liest Daten aus dem Zwischenspeicher für den Datenaustausch;
- Stellt Importdatenmapping und -konvertierung für die Nutzung durch die API zur Verfügung
- Sendet Quelldaten zur Verarbeitung an die API;
- Empfängt Ergebnisdaten von der API.
Datenmapping und -konvertierung:
- Stellt die Konvertierung von Quelldaten aus von einem „flachen“ Format (.txt, .csv usw.) in das XML-Format gemäß der entsprechenden Vorlage der Indeavor-Entität bereit;
- Stellt die Konvertierung von Ergebnisexportdaten vom vorlagendefinierten XML-Format in das vom externen System benötigte Format bereit.

Im folgenden Diagramm werden die Verbindungen der Integrationsprozesse grafisch dargestellt:

Integrationsszenarien

Je nach Art der Integrations-Middleware (Data Integration Engine) kann es mehrere Möglichkeiten für die Integration des Architekturdesigns geben.

Es gibt drei Hauptoptionen für die Integrations-Middleware:

In externes System integriert. Die Art Middleware, die in ein externes System integriert und in der Lage ist, die an Indeavor zu übertragenden Daten des externen Systems „direkt“ zu lesen, die Daten in das von der Indeavor API akzeptierte XML-Format zu konvertieren (einschließlich der gesamten Datenkonvertierung und des gesamten Datenmappings), die Integrationsdaten in den Zwischenspeicher für den Datenaustausch zu platzieren oder die API direkt aufzurufen, um die Daten als HTTP-Anfrage-Nutzlast bereitzustellen;
Integration-Middleware von Drittherstellern – DELL Boomi. Es befindet sich auf AWS und bietet mehrere mögliche Anschlüsse, darunter Datenzugriffsanschlüsse (FTP, Festplatte, DB-Anschlüsse) und einen HTTP-Anschluss für die API-Kommunikation. Sofern die Dell Boomi-Umgebung nicht vor Ort installiert ist (überschreitet den Geltungsbereich) ermöglicht sie keine direkte Kommunikation mit dem externen Systemspeicher. Die einzige Möglichkeit zum Zugriff auf die Daten des externen Systems ist der Zwischenspeicher für den Datenaustausch: dies kann entweder eine FTP-Site im Besitz eines externen Anbieters oder im Besitz von Indeavor sein.
„Indeavor Connect“-Dienst. Dies ist eine vor Ort installierte Software, die auf die Daten des externen Systems über die FTP-Site, Festplatte oder über direkte DB-Quellenverbindungen zugreifen oder diese bereitstellen kann. Er kann außerdem Daten aus jedem bzw. in jedes Format konvertieren, das sowohl mit dem externen System als auch mit dem Indeavor API Datenaustausch kompatibel ist.

Indeavor verfügt über Erfahrung bei der Implementierung von Integrationsszenarien, die auf allen drei erwähnten Integrations-Middleware-Optionen basieren. Es ist zu erwähnen, dass jede der Optionen mehrere architektonische Varianten ermöglicht und dass verschiedene Optionen kombiniert werden können. Im Folgenden finden Sie nur die Integrationsszenarien, die von Indeavor bisher umgesetzt wurden.

Szenario 1

Basiert auf Option 1 für Integrations-Middleware: In externes System integriert.

Das externe System bereitet Integrationsquelldaten vor, die es aus seinem Datenspeicher im eigenem Format erhält (Verbindung 1 in Abb. 1), und konvertiert sie in:
- eine Datenmodellvorlage für den Export im vordefinierten XML-Format der API;
- Quelldaten für den Import im XML-Format der API (Verbindung 4 in Abb. 1).
Externes System initiiert die HTTP-Kommunikation mit der Indeavor API und stellt geeignete Daten für die Integration bereit (Verbindung 5 in Abb. 1);
Externes System empfängt die Antwort von der API mit Daten, die entweder das Ergebnis des Imports widerspiegeln oder Indeavor-Exportdaten darstellen, die an das externe System übertragen werden sollen (Verbindungen 5, 1 in Abb. 1);

In Szenario 1 werden alle Phasen des Integrationsprozesses durch das externe System initiiert (ausgelöst).

Szenario 2

Basiert auf Option 2 für Integrations-Middleware: DELL Boomi.

Externes System bereitet die Integrationsquelldaten in seinem eigenen Format vor und führt eine der folgenden Aktionen aus (abhängig von den externen Systemfunktionen):
- Es lädt die Daten entweder wie vorliegend (im Format des externen Systems) auf eine sichere FTP-Site hoch (Verbindung 1 in Abb. 1);
- oder es konvertiert die Daten in das XML-Format der API und lädt sie auf eine sichere FTP-Site hoch (Verbindung 2 in Abb. 1).

Quelldaten-Uploads folgen einem vordefinierten Zeitplan, der für die DELL Boomi Middleware verfügbar ist.

DELL Boomi lädt Quelldaten von FTP (Verbindung 3 in Abb. 1) herunter und konvertiert sie in ein API-konformes XML-Format (Verbindung 4 in Abb. 1), es sei denn, dies wurde durch das externe System in der vorherigen Phase durchgeführt;
DELL Boomi initiiert die HTTP-Kommunikation mit der Indeavor API (Verbindung 5 in Abb. 1) und stellt die entsprechenden Daten für die Integration bereit;
DELL Boomi erhält eine Antwort von der API mit Daten (Verbindung 5 in Abb. 1), die entweder das Ergebnis des Imports widerspiegeln oder die Daten für den Indeavor-Export darstellen, die an das externe System zu übermitteln sind;
Dell Boomi lädt die API-Antwort – Importergebnis oder Exportausgabe – auf eine dedizierte, sichere FTP-Site zum Herunterladen und zur Nutzung durch das externe System hoch (Verbindung 3 in Abb. 1).

In Szenario 2 werden alle Integrationsprozessphasen bis auf die erste von DELL Boomi initiiert (ausgelöst) und entsprechend mit dem FTP-Upload/Download-Zeitplan des externen Systems synchronisiert.

Szenario 3

Basiert auf Option 3 für Integrations-Middleware: Indeavor Connect neben dem externen System vor Ort installiert.

Indeavor Connect empfängt Quelldaten für den Import (Verbindung 1 in Abb. 1) durch direkten Zugriff auf den Datenspeicher des externen Systems (DB-Ansichten) oder bereitet ein XML-formatiertes Exportdatenmodell vor;
Indeavor Connect wandelt importierte Quelldaten aus der flachen Ansicht in das XML-Format der API um (Verbindung 4 in Abb. 1);
Indeavor Connect initiiert die HTTP-Kommunikation mit der Indeavor API, und stellt geeignete (Import- oder Export-) Daten für die Integration zur Verfügung (Verbindung 5 in Abb. 1);
Indeavor Connect empfängt die Antwort von der API (Verbindung 5 in Abb. 1) mit Daten, die entweder das Ergebnis der Einfuhr widerspiegeln oder Indeavor-Exportdaten darstellen, die an das externe System zu übermitteln sind;
Indeavor Connect sendet Exportausgabe zur Verarbeitung an das externe System (Verbindung 1 in Abb. 1) durch direkte Kommunikation mit seiner(n) Datenspeicheransicht(en) oder Hochladen des Importergebnisses als lokale Netzwerkressource zur Analyse.

Mit Szenario 3 werden alle Integrationsprozessphasen von Indeavor Connect über die Planungs-Funktionalität des Windows Task Scheduler initiiert (ausgelöst).

Indeavor Integration API

Um einen Integrationsprozess (Import oder Export) mit der Indeavor Integration API zu initiieren, muss der Zugriff auf Indeavor-Daten über den Authentifizierungsprozess gewährt werden.

Authentifizierung

Um sich bei der API zu authentifizieren, sollte die unten beschriebene HTTP-Anfrage verwendet werden. Die Anforderungsdaten sind ein JSON-Objekt mit Benutzernamen- und Passwortfeldern. Die Antwort ist ein JSON-Objekt, das Details zum Anmeldevorgang enthält. Für die erfolgreiche Anmeldung ist das Feld "_r" 1, und das Feld "SessionID" enthält einen Schlüssel, der bei nachfolgenden API-Aufrufen zur Identifizierung des Benutzers verwendet wird.

Name	Wert
URL	https://interop.[UMGEBUNGSNAME].indeavor.com/current/Session/SessionHandlerWS.asmx/Login
Http-Methode	POSTEN
Kopfzeilen	Inhaltstyp: Anwendung/json Zeichensatz: utf-8
Text	{ “Benutzername”:”<UserName>@rjr”, "Kennwort":"<Password", “Antwort”:1 }

Die API-Antwort gibt einige JSON formatierte Daten zurück... aber was für die nachfolgenden Import/Export API-Aufrufe zur Identifizierung eines Benutzers wichtig ist, ist ein Cookie-Container, der mit der HTTP-Antwort zurückgegeben wird. Er enthält zwei unten gezeigte Cookies und muss mit API-Import-/Exportaufrufen weitergeleitet werden:

Name	Wert
ASP.NET_SessionId	(Beispiel): lkqs4bndhvk1snc4z2mxpe5s
AWSELB	(Beispiel): BF836DE70EC369F6241CF55E41A743DEB743F2E50E11C505FFF413E8CDF89B0DF47D58D512F53721BDEDFBB5FB2B2C97320B290D32DA311A71E93F0B0E1965E6ECBB108D5DC9ECF83AE34C6903E489407E5F90FBC4

Importieren

Das Importieren von Daten erfolgt durch das Senden der in XML-Form zu importierenden Daten an den Importhandler der API. Folgende Maßnahmen sind erforderlich:

Name	Wert
URL	https://interop.[UMGEBUNGSNAME].indeavor.com/current/import/importhandler.ashx
Http-Methode	POSTEN
Kopfzeilen	Inhaltstyp: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie: <Cookie-Container aus dem Authentifizierungsaufruf oder geben Sie einfach die Cookies als Parameter wie folgt an: SessionId=<SessionId>&AWSELB=<AWSELB_value>
Text	isBackgroundJob=true&Data=<zu importierende Daten> Erläuterung der Parameter: - isBackgroundJob : der einzige empfohlene Wert für den Parameter ist true - <Zu importierende Daten>: stellt XML-Eingabedaten dar, die gemäß der entsprechenden Vorlage für Importdaten formatiert sind.

Wenn sie einmal als Hintergrundauftrag gesendet wurde – gibt die HTTP-Anfrage, falls sie erfolgreich ist, sofort den passenden Auftrags-"id"-Parameter für die zukünftige Verwendung mittels der folgenden JSON-Struktur zurück:

{

"Tätigkeit":{

"id":"<Auftragskennung>",

"startTime":"<Startzeit des Auftrags>"

}

Um den Status des Hintergrundauftrags zu überprüfen, muss der folgende Handler der API verwendet werden

Name	Wert
URL	https://interop.[UMGEBUNGSNAME].indeavor.com/current/import/import.asmx/GetCurrentResultForJob
Http-Methode	POSTEN
Kopfzeilen	Inhaltstyp: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie: <Cookie-Container aus dem Authentifizierungsaufruf oder geben Sie einfach die Cookies als Parameter wie folgt an: SessionId=<SessionId>&AWSELB=<AWSELB_value>
Text	jobID=<Auftragskennung> Erläuterung der Parameter: - <Auftragskennung>: stellt den "id"-Parameter der JSON-Antwort dar, die von der Import-Handler-Anfrage erhalten wurde.

Je nach Auftragsausführungsstatus kann man zwei mögliche Antworten erhalten:

XML-Ergebnis, wenn der Hintergrundauftrag noch läuft:

<Output>

<Results>

<Error Value="Keine Operationsergebnisse gefunden" />

<Job id=”<Job Identifier>” currentStep=”0” totalSteps=”1” startTime=”2018-11-26T16:05:25.0000000” />

</Results>

</Output>

JSON-Ergebnis, wenn der Hintergrundauftrag erfolgreich ausgeführt wurde (Beispiel: Import der Urlaubssaldi von Mitarbeitern):
- {
- "d":
- “<Output>
- <Results>
- <Items type=”EmployeeLeaveBalance”>
- <Item result=”0” action=”0” index=”1”/>
- <Item result="200" action="0" index="2" messages="Kombination aus angegebenem Mitarbeiter, Urlaubsart und Rechnungslegungsperiode ist nicht erlaubt"/>
- <Item result=”0” action=”0” index=”3”/>
- </Items>
- </Results>
- </ Output>”

}

Der "d"-Parameter der Ausgabe stellt also das tatsächliche Ergebnis der Import-Ausführung dar.

Exportieren

Der Export von Daten erfolgt durch die Bereitstellung von Datenvorlagen in XML-Form an den Exporthandler der API. Folgende Maßnahmen sind erforderlich:

Name	Wert
URL	https://int erop.[UMGEBUNGSNAME].indeavor.com/current/export/exportHandler.ashx
Http-Methode	POSTEN
Kopfzeilen	Inhaltstyp: application/x-www-form-urlencoded Accept-Encoding: deflate Cookie: <Cookie-Container aus dem Authentifizierungsaufruf oder geben Sie einfach die Cookies als Parameter wie folgt an: SessionId=<SessionId>&AWSELB=<AWSELB_value>
Text	returnType=response&definition=<Exportdatenvorlage> Erläuterung der Parameter: - <Exportdatenvorlage>: XML-formatierte Datenmodellvorlage mit Datentypen, Feldern und Filtern für die zu exportierenden Daten.

Das Ergebnis der Exportausführung ist ein XML-Dokument, das gemäß der Vorlage des Datenmodells strukturiert ist und das entsprechende Indeavor-Daten enthält, die entsprechend den bereitgestellten Datenfiltern abgerufen werden.

Gemeinsame Integrationen – Eingabe- und Ausgabedatenmodelle

Es gibt mehrere gängige Integrationsschnittstellen, die von Indeavor-Kunden verwendet werden:

Importschnittstelle für demografische Mitarbeiterdaten;
Importschnittstelle für Urlaubssaldi von Mitarbeitern;
Arbeitsplan-Exportschnittstelle.

Import demografischer Mitarbeiterdaten

Die Schnittstelle verwendet die „EmployeeUpdates“-Datenmodellvorlage als „Anleitung“ zum Erstellen der XML-formatierten Eingabe von der Indeavor API. Als einfaches Beispiel (die Vorlage erlaubt es, viel mehr Felder und Entitäten für eine Aktualisierung bereitzustellen), wenn die folgenden Felder als Mitarbeiterdaten für eine Aktualisierung in Indeavor aus dem externen System eingehen:

Mitarbeiter-ID;
Vorname;
Nachname;
Aktivitätsflagge;
Aktivitätsdatum;
Datum der Betriebszugehörigkeit;
Primäre Organisationseinheit;
Gruppenzuweisung

werden die folgenden XML-Daten die Eingabe der Indeavor API als "<Zu importierende Daten>" (Beispiel eines Mitarbeiters) darstellen:

<?xml version='1.0' encoding='UTF-8'?>

</Options>

</Fields>

</EntityMapping>

</Fields>

</OrganizationalUnitEmployee>

</OrganizationalUnitsEmployee>

</Fields>

</GroupMembership>

</GroupMemberships>

</Employee>

</EmployeeUpdate>

</EmployeeUpdates>

</Input>

Import der Urlaubssaldi von Mitarbeitern

Die Schnittstelle verwendet die „EmployeeLeaveBalances“-Datenmodellvorlage als „Anleitung“ zum Erstellen der XML-formatierten Eingabe von der Indeavor API. In den meisten Fällen – die Schnittstelle „korrigiert“ Indexbilanzen gemäß den Daten des externen Systems – sollten die folgenden Felder als Quelle für die Erstellung von API XML-Eingaben zur Verfügung gestellt werden:

Mitarbeiter-ID;
Urlaubsart;
Rechnungslegungsperiode;
Wirksamkeitsdatum des Saldos;
Saldo;

Die XML-Eingabe der passenden API sieht wie folgt aus (Beispiel eines Mitarbeiters):

<?xml version='1.0' encoding='UTF-8'?>

</Options>

</Fields>

</EmployeeLeaveBalance>

</EmployeeLeaveBalances>

</Input

Export von Mitarbeiterarbeitsplänen

Die Schnittstelle verwendet die „EmployeeScheduleReport“-Datenmodellvorlage als „Anleitung“ zum Erstellen der XML-formatierten Eingabe von der Indeavor API. Als einfaches Beispiel (die Vorlage erlaubt es, viel mehr Felder und Entitäten für die Aktualisierung bereitzustellen), wenn die folgenden Felder an das externe System übertragen werden sollen:

Mitarbeiter-ID;
Geplanter Ereignistyp (=0: Arbeitsauftrag; =4: Urlaub usw.)
Geplante Startzeit des Ereignisses;
Geplante Endzeit des Ereignisses;
Arbeitsstandort des Arbeitsauftrags;
Überstundenflagge des Arbeitsauftrags;
Urlaubs-ID;
Abrechenbare Dauer des Urlaubs;
Geplantes Datum des Ereignisses;
Arbeitsauftragsdauer;
Arbeitscode(s) des Arbeitsauftrags.

Die folgenden XML-Daten sollten als "<Export Query>" an die Indeavor API bereitgestellt werden:

</Options>

</OutputFields>

</Filters>

</Export>

Die folgende Ausgabe stellt die Exportergebnisdaten dar (die Daten spiegeln die Schnittstelle wider, die am 26.12.2018 ausgeführt wird):

<Item>

</Item>

<Item>

</LaborCode>

</LaborCodes>

</Item>

</Output>