In diesem Kapitel werden Konfigurationsanweisungen für den Connector beschrieben, um eine Verbindung zur REST API herstellen zu können.

Zum Konfigurieren der Bereitstellung benötigen Sie Zugriff auf die Plattformkonfigurationskonsole.

1. Öffnen Sie den Administrationsbereich (ein Zahnradsymbol).
2. Öffnen Sie die Connectors-Ansicht.
3. Wählen Sie „Neuer Connector“

4. Wählen Sie als Datenquellentyp „Generische REST API aus

5. Geben Sie dem Connector einen Namen und fügen Sie Verbindungseinstellungen hinzu:

• Connector-Name – geben Sie Ihrem Connector einen benutzerfreundlichen Namen (der Name kann später geändert werden)
• Host-URL – Basis-URL für REST API . Dies kann als Präfix für die endgültige aufzurufende URL verwendet werden.
• REST Connector-Typ – Allgemein oder Google . Verwenden Sie für Google Google und für alle anderen REST API -Typen Allgemein.

Wählen Sie die richtige Authentifizierungsmethode basierend auf dem System, mit dem Sie eine Verbindung herstellen

• Basic Auth - Basisauthentifizierung mit Benutzername/Passwort als Base64-codierter Authentifizierungsheader
• Bearer Token - Verwendung eines konstanten Bearer Token-Authentifizierungsheaders
• Deaktiviert – Für öffentliche API ohne Authentifizierung (in Version 2025.3 und neuer)
• Auth-Header – Für konstanten geheimen Header (in Version 2025.3 und neuer)
• Dynamisches Token – Für den OAuth 2.0-Client-Anmeldeinformationsfluss und ähnliches (in Version 2025.3 und neuer)

Legen Sie die richtige Seitennummerierung fest, basierend auf dem Drittanbietersystem, das Sie mit diesem Connector verbinden.

Die generische Paginierung REST API Connectors unterstützt fünf verschiedene Paginierungstypen. Diese werden von geplanten Aufgaben verwendet:

• Deaktiviert – Die API unterstützt keine Paginierung und gibt alle Daten in einer einzigen Antwort zurück.
• Start & Offset – Die API verwendet Start- und Offset-Parameter. Erhöhen Sie bei jeder Anfrage den Start um den Offset, bis alle Daten abgerufen wurden.
• Seiteninkrement - Die API verwendet Seitennummerierung. Erhöhen Sie bei jeder Anfrage die Seitenzahl um eins, bis keine weiteren Ergebnisse zurückgegeben werden.
• Link-Token – Die Antwort enthält eine URL für die nächste Seite. Folgen Sie dieser URL, bis kein nächster Link mehr bereitgestellt wird.
• Link-Attribut-Token – Die Antwort enthält ein Token für die nächste Seite. Senden Sie dieses Token als Abfrageparameter in der nächsten Anfrage. Paginierung Google Stil.

Erfüllen Sie die Benutzerinformationen der Web API

• Web API Benutzer – wählen Sie den richtigen Web- API Benutzer aus, der beim Schreiben von Daten aus einem externen System in Matrix42 Core , Pro and IGA Lösungen verwendet wird
• Web API Passwort – Passwort für den Web API Benutzer

7. Connector-Informationen speichern

8. Fügen Sie das Root-HTTPS-Zertifikat externer REST API Systeme hinzu, dem die Connector-Verwaltung (EPE) vertraut. Dies ist nur mit Matrix42 möglich: Zertifikat hinzufügen.

9. Matrix42 Core , Pro and IGA Lösung kann jetzt eine Verbindung zur externen REST API herstellen

• Der nächste Schritt besteht darin, geplante Aufgaben zum Lesen von Daten oder Ereignisaufgaben zum Schreiben von Daten und Aktionen in Richtung REST API zu konfigurieren.

In der Version 2025.3 wurde Unterstützung für das Lesen von Daten mit geplanten Aufgaben hinzugefügt.

Der generische REST API Connector wird verwendet, um Daten aus Drittanbieterlösungen zu lesen, die REST API verfügbar machen, indem zeitplanbasierte Bereitstellungsaufgaben erstellt werden.

So erstellen Sie eine neue Aufgabe für die geplante Pro

Zum Konfigurieren zeitplanbasierter Bereitstellungsaufgaben benötigen Sie Zugriff auf die Plattformkonfigurationskonsole.

Hinweis! Wenn kein Connector erstellt wird, müssen Sie zuerst einen „neuen Connector“ erstellen. Danach können Sie neue Aufgaben erstellen.

1. Öffnen Sie die Plattformkonfigurationsansicht (ein Zahnradsymbol).
2. Öffnen Sie die Connectors-Ansicht.
3. Wählen Sie den Connector, für den die zeitgesteuerte Aufgabe konfiguriert ist
4. Wählen Sie unter dem richtigen Konnektor „Neue Aufgabe“ aus

5. Definieren Sie die Planung für die Aufgabe (ob und wie die geplante Aufgabe regelmäßig ausgeführt werden soll). Wählen Sie die Planungssequenz, die davon abhängt, wie viele Daten in Matrix42 Core , Pro and IGA Lösung gelesen werden.

Die empfohlene Planungsreihenfolge hängt davon ab, wie viele Daten aus dem Kundenverzeichnis in die Matrix42 Core , Pro and IGA Lösung gelesen werden und ob der Import teilweise oder vollständig erfolgt.

Beispielplanung zum Lesen von Daten.

5. Aufgabendetails ausfüllen

• Geben Sie einen eindeutigen Aufgabennamen für die geplante Aufgabe ein.
• Die angegebene Aufgabenverwendung ist die Aufgabe, die zum Lesen, Schreiben oder zur Authentifizierung verwendet wird. Beachten Sie, dass eine nachträgliche Änderung des Ereignistyps zu Unterbrechungen der Workflows oder Integrationen führen kann.
• Der Zuordnungstyp hängt davon ab, welche Art von Informationen aus dem Verzeichnis gelesen werden. Für den generischen REST API -Connector wird nur „Generic“ unterstützt.
  • Generisch (eine Vorlage) – werden verwendet, wenn generische Informationen aus dem Verzeichnis gelesen werden

6. Aufgabenparameter ausfüllen

• Abfrage – tatsächlicher API URL-Endpunkt, der aufgerufen werden soll
• Unterabfragen – optional. Kann verwendet werden, wenn Abfragedaten von einem anderen API Endpunkt abgerufen werden müssen.
• Abfragekopfzeilen – Benutzerdefinierte Kopfzeilen, die während der Datenextraktion zur endgültigen Abfrage hinzugefügt werden.
  Die Connector-Verwaltung (EPE) fügt diese Header automatisch hinzu, Sie müssen sie also nicht explizit hinzufügen:
  “Content-Type”, “…”
"Authorization", “…”
• Wertmarkierung – kann leer sein. Der Wert hängt von der von der Abfrage API zurückgegebenen JSON-Datenstruktur ab. Wenn sich beispielsweise alle Daten im Resultset-JSON-Objekt befinden, setzen Sie diese Wertmarkierung auf das Resultset.
• Fehlermarkierung – kann leer sein. Der Wert hängt von der Struktur der JSON-Fehlermeldung ab, die von der Abfrage API zurückgegeben wird. Wenn sich beispielsweise die gesamte Fehlermeldung im JSON-Objekt „Fehler“ befindet, setzen Sie diese Wertmarkierung auf „Fehler“.
• Sicherheitsschwelle für API Aufrufe – Sicherheitsschwelle zur Vermeidung von Endlosschleifen. Setzen Sie diesen Wert doppelt so hoch wie die aktuell für diesen Task benötigten Aufrufe zum Abrufen aller Daten. Wenn Sie alle Ihre Daten mit diesem Task abrufen möchten, z. B. 50 paginierte Aufrufe, setzen Sie diesen Wert auf 100.
• Eindeutiges Attribut – Legen Sie einen eindeutigen Attributnamen (Groß-/Kleinschreibung beachten) aus dem JSON-Ergebnissatz fest. Normalerweise ID, id oder g uid usw. Jede Zeile muss einen eindeutigen Wert in diesem Attribut haben. Sie müssen dieses Attribut auch am Ende der Aufgabenkonfiguration zur Zuordnungstabelle hinzufügen. Hinweis! Geplante Aufgaben können keine Daten abrufen, die dieses eindeutige Attribut nicht für jedes Objekt enthalten.
  

7. Fehlerinformationen eingeben

Optionale Einstellungen für die Fehlerbehandlung. Wenn geplante Aufgaben fehlschlagen, kann eine Datenkarte für ESM erstellt werden, die den Fehler anzeigt. Wenn Fehlereinstellungen definiert sind, muss der Administrator den Status geplanter Aufgaben nicht manuell überprüfen.

• Fehlervorlage – Wählen Sie eine Datenkartenvorlage aus, die im Falle von Fehlern während der Bereitstellung (Verbindung zu Datenquellen, Zeitüberschreitungen usw.) erstellt wird.
• Fehlerordner – Wählen Sie den Ordner aus, in dem die Fehlerdatenkarte gespeichert ist.
• Fehlerattribut – Wählen Sie ein Attribut aus, in dem in der Fehlervorlage die Fehlerinformationen gespeichert werden sollen. Wählen Sie das Attribut vom Typ „Text“ aus.

8. Generische Zuordnungen hinzufügen

Im Abschnitt „Zuordnungen“ konfigurieren Sie, welches Attribut aus der JSON-Nachricht in welches Attribut auf Matrix42 Core , Pro and IGA Datenkarte gelesen wird.

• Zielvorlage – Wählen Sie eine Vorlage aus, um Attributzuordnungen zu definieren
• Zielordner – Wählen Sie einen Ordner aus einer Liste aus. Die Liste wird entsprechend der Kompatibilität mit der ausgewählten Vorlage eingegrenzt.
• Zuordnung des Datenquellentyps – optional. Wenn diese Option festgelegt ist, wird der Konnektortyp in dieses Attribut geschrieben.
• Aufgaben-ID-Zuordnung – Die Aufgaben-ID-Nummer wird in dieses Attribut geschrieben.
• Wert für Datenkarte für aus dem Quellsystem gelöschtes Objekt setzen – Diese Funktion wird durch Aktivieren des Kontrollkästchens aktiviert. Wenn ein Objekt, das zuvor aus einem Drittsystem in die Lösung eingelesen wurde, aus dem Drittsystem gelöscht wird, erkennt diese geplante Aufgabe die Löschung und markiert das ausgewählte Attribut der Datenkarte mit dem gewünschten Wert. Dies kann beispielsweise verwendet werden, um das Statusattribut auf „Gelöscht“ zu setzen (siehe Beispiel-Screenshot unten).

• Attributzuordnungen
  1. Externes Attribut – welches Attribut aus der API des Drittanbietersystems wird aus dem JSON-Text gelesen
  2. Lokales Attribut - welches Attribut in Matrix42 Core , Pro and IGA abgebildet wird
• Es ist möglich, zusätzliche Attribute für Attributzuordnungen festzulegen, indem Sie Neues Attribut

9 Speichern Sie die Bereitstellungsaufgabe über die Schaltfläche „Speichern“.

Wenn einige erforderliche Attribute fehlen, wird die Schaltfläche „Speichern“ grau angezeigt und es wird angezeigt, was in den Einstellungen fehlt.

10. Sie haben nun eine zeitgesteuerte Connector-Aufgabe für das Lesen der generischen REST API konfiguriert.

• Sie können jetzt warten, bis die Aufgabe basierend auf der Planung gestartet wird oder
• Task manuell ausführen – Durch Klicken auf die Schaltfläche „Task ausführen“ oben im Task-Bearbeitungsfenster wird der Task so konfiguriert, dass er sofort gestartet wird. Dies ist normalerweise für Testläufe oder wenn Sie die Zeitplaneinstellungen nicht ändern, sondern den Task sofort ausführen möchten.

Beispiel einer Meldung zum Starten der manuellen Aufgabenausführung:

Wenn die Aufgabe manuell ausgeführt wird ( Aufgabe ausführen ) oder gemäß Zeitplan ausgeführt wird, kann der Aufgabenstatus in der Verwaltungsspalte der Liste der geplanten Aufgaben durch Klicken auf die Schaltfläche „Verlauf anzeigen“ überprüft werden .

Die Ereignisaufgabe wird beim Schreiben von Daten (oder beim Tätigen anderer ereignisbasierter REST API Aufrufe vom Workflow) in Richtung einer Kundenlösung verwendet, die eine generische REST API bietet. Diese Connector-Management-Funktionen sind für alle Matrix42 Core , Pro and IGA Lösungen verfügbar.

Beispiele für die ereignisbasierte Aufgabenverwendung:

• Konto hinzufügen
• Person aktualisieren
• Konto aktivieren
• Ticket erstellen
• Inaktives Gerät

Alle Konfigurationen im Zusammenhang mit Connector Management und ereignisbasierten Bereitstellungsaufgaben werden in der Matrix42 Core , Pro oder IGA -Connectors-Ansicht konfiguriert.

1. Öffnen Sie die Matrix42 Core , Pro oder IGA -Konfigurationsansicht (ein Zahnradsymbol).

2. Konnektorenansicht öffnen

3. Wählen Sie den Connector, der die Ereignisaufgabe verwenden soll

4. Wählen Sie unter dem richtigen Connector „Neue Aufgabe“

5. Aufgabeneinstellungen ausfüllen

• Aufgabenname – Geben Sie der Aufgabe einen Namen, er wird in der Konnektoransicht angezeigt.
  • Es empfiehlt sich, eine Aufgabe so zu benennen, dass ihr Zweck beschrieben wird, zum Beispiel [Vorlagenname]:[Aktivität] IGA -Serviceanfrage: Konto hinzufügen
• Die angegebene Taskverwendung ist die Task, die zum Lesen oder Schreiben von Daten verwendet wird. Kann nachträglich geändert werden, wird aber nicht empfohlen, wenn eine Ereignistask verwendet wird. Dadurch werden Arbeitsabläufe unterbrochen.
• Der Zuordnungstyp hängt davon ab, welche Art von Informationen aus dem Verzeichnis gelesen werden. Die Auswahl der Identitätszuordnungen wird basierend auf dieser Einstellung angezeigt.
  • Generisch (eine Vorlage) – wird verwendet, wenn generische Informationen aus dem Verzeichnis gelesen werden. Dies kann jeder Datentyp sein.

Warnung zur Änderung der Aufgabenverwendung oder des Zuordnungstyps bei Verwendung der Ereignisaufgabe:

6. Aufgabenparameter ausfüllen

• Abfrage – API-Endpunkt, den diese Aufgabe aufruft. Dieses Feld kann leer gelassen und im Workflow-Orchestrierungsknoten angegeben werden. Sie können die vollständige Endpunktadresse wie https://apiurl.com/endpointtocall oder nur das URL-Ende angeben. Wenn Sie nur das URL-Ende angeben, z. B. endpointtocall , wird die endgültige URL aus Folgendem zusammengesetzt: Connector-Host-URL + Aufgabenabfrage + Orchestrierungsknoten-URL.
• Abfrageheader – Benutzerdefinierte Header, die der endgültigen Abfrage an die REST API hinzugefügt werden. Welche Header erforderlich sind, erfahren Sie in API Dokumentation des Ziel-/Quellsystems.
• Datumsattributformatierer – dient zur Formatierung von Datumsangaben bei der Bereitstellung von Datumsattributen im Zielsystem. Sie können das Format aus der Liste auswählen oder ein eigenes Format hinzufügen. Das Feld rechts zeigt ein Beispiel für ein formatiertes Datum.
• DateTime-Attributformatierer – dient zur Formatierung von Datums- und Uhrzeitangaben bei der Bereitstellung von Datums- und Uhrzeitattributen im Zielsystem. Sie können das Format aus der Liste auswählen oder ein eigenes benutzerdefiniertes Format hinzufügen. Das rechte Feld zeigt ein Beispiel für die Formatierung von Datum und Uhrzeit.

7. Generische Zuordnungen definieren

• Zielvorlage – Wählen Sie eine Vorlage aus, um Attributzuordnungen zu definieren
• Zielordner – Wählen Sie einen Ordner aus einer Liste aus. Die Liste wird entsprechend der Kompatibilität mit der ausgewählten Vorlage eingegrenzt.
• Attributzuordnungen ( Notiz! In den meisten Fällen ist es nicht notwendig, diese festzulegen. Die in der Ereignisaufgabe verwendeten Daten werden auf dem Workflow-Orchestrierungsknoten konfiguriert.
  1. Efecte-Vorlagenattribut – welches Attribut im Efecte-Verzeichnisattribut wird zugeordnet.
  2. Verzeichnisattribut - welches Attribut aus dem Verzeichnis wird Efecte zugeordnet
• Neues Attribut hinzufügen – Sie können zusätzliche Attribute festlegen, indem Sie die Schaltfläche „Neues Attribut“ auswählen.

8. Aufgabe speichern

Bereitstellungsaufgabe mit „Speichern“ speichern

Wenn obligatorische Informationen fehlen, können Sie die Aufgabe nicht speichern und die Schaltfläche „Speichern“ zeigt fehlende Informationen an.

9. Konfigurieren Sie den Workflow, um diese ereignisbasierte Aufgabe mit dem Orchestrierungsknoten zu verwenden

Der nächste Schritt besteht darin, den Workflow für die Verwendung dieser ereignisbasierten Aufgabe zu konfigurieren.

Über die Workflow-Engine in der Plattform können Bereitstellungsaktivitäten für Kundenverzeichnisdienste ausgeführt werden. Dies bedeutet, dass jede Aktivität der verfügbaren Orchestrierungsknoten an jedem Punkt des Workflows ausgeführt werden kann.

Workflow-Referenzen werden auf der Connector-Übersichtsseite angezeigt (Sie können Workflow-Referenzen mit der Schaltfläche „Workflow-Referenzen anzeigen“ aktualisieren):

Generischer REST Aufruf

Fügen Sie Ihrem Workflow einen Orchestrierungsknoten hinzu und konfigurieren Sie die folgenden Dinge.

Name - beschreibenden Namen festlegen

Beschreibung - Legen Sie eine beschreibende Beschreibung fest

Orchestrate – Pro Engine auswählen

Datenquelle – wählen Sie „Generische REST API

Aktivität – Wählen Sie „Generischer REST Aufruf“ aus

Ziel – wählen Sie Ihre ereignisbasierte Aufgabe aus (Sie können dieselbe Aufgabe für mehrere Orchestrierungsknoten verwenden)

Aktion - Wählen Sie die Aktion basierend auf der aufgerufenen REST API aus (die korrekte Aktion finden Sie in API Dokumentation). Unterstützte Aktionen sind: POST, PUT, PATCH, DELETE und GET

REST URL – der API-Endpunkt, den Sie aufrufen. Dies kann die vollständige URL oder deren Suffix sein. Bei Verwendung eines Suffixes wird die tatsächlich aufzurufende URL aus Folgendem zusammengesetzt: Connector-Host-URL + Task-Abfrage + Orchestrierungsknoten-URL. Sie können Vorlagenattributvariablen ähnlich wie im E-Mail-Knoten verwenden, indem Sie eine Dollar-Syntax wie $attribute_code$ und $reference:attribute_code$ verwenden.

Hinweis! Wenn Ihre URL Leerzeichen oder $-Zeichen enthält, denken Sie daran, diese URL-kodieren. $ ist also %24, Leerzeichen ist %20

Rest Body – JSON-Body für den API-Aufruf. Kann leer sein, wenn die aufgerufene API keinen Body benötigt. Details zum Body finden Sie in API Dokumentation. Sie können Vorlagenattributvariablen ähnlich wie im E-Mail-Knoten verwenden, indem Sie eine Dollar-Syntax wie $attribute_code$ und $reference:attribute_code$ verwenden.

In diesem Textkörper haben wir beispielsweise zwei Variablen: $firstname$ und $lastname$
{"Name": {
"givenName": "$Vorname$",
„familyName“: „$lastname$“}}

Falls Sie einen komplizierten JSON-Text für API Aufruf erstellen müssen, können Sie diesen vollständigen JSON-Text zunächst für ein Datacard-Attribut konstruieren. Und dann haben Sie nur diesen Attributcode im Text, wie folgt: $generated_json_body_attributecode$

import json

if onPremisesExtensionAttributes:
  _data = this.get("onPremisesExtensionAttributes")
  _obj = json.loads(_data)
  _value = _obj["extensionAttribute14"]
  this.set("extensionAttribute14code",_value)

REST-Antwortattribut – Das JSON-Ergebnis des API Aufrufs wird in dieses Attribut geschrieben. Nicht alle API geben JSON-Antworten zurück. Details finden Sie in API Dokumentation.

import json

if onPremisesExtensionAttributes:
  _data = this.get("onPremisesExtensionAttributes")
  _obj = json.loads(_data)
  _value = _obj["extensionAttribute14"]
  this.set("extensionAttribute14code",_value)

Pro – Wenn beim REST API Aufruf ein Problem auftritt, wird ein Fehler in dieses Attribut geschrieben.

Ausnahmebehandlung:

• Die Pro ist eine optionale Eigenschaft dieses Workflowknotens. Administratoren können diese Eigenschaft so konfigurieren, dass Ausnahmen geschrieben werden können, wenn während der Bereitstellungsaktionen Ausnahmen auftreten.
• Das Ergebnis eines Knotens befindet sich im Status „Abgeschlossen“, wenn der HTTP-Antwortcode REST API 200 oder darüber und unter 400 liegt.
• Details zu erfolgreichen/nicht erfolgreichen REST API Aufrufen finden Sie in den Protokollen.

In diesem Kapitel werden Möglichkeiten zur Fehlerbehebung beschrieben,

• Falls eine Fehlervorlage verwendet wird, überprüfen Sie die korrekte Datenkarte
• Überprüfen Sie den Verlauf geplanter Aufgaben über die Connector-Verwaltung
• Überprüfen Sie die Protokolle Efecte Provisioning Engine

Einschränkungen für ereignisbasierte Aufgaben

• E-Mails werden nicht unterstützt
• Anhänge werden nicht unterstützt

Einschränkungen für geplante Aufgaben

• Attribute vom Typ „Datum“ (Sie müssen diese Attributen vom Typ „Zeichenfolge“ zuordnen)
• Attribute vom Typ DateTime (Sie müssen diese Attributen vom Typ String zuordnen)
• E-Mails werden nicht unterstützt
• Anhänge werden nicht unterstützt