Integrationen mit Monosync entwickeln
Was hat sich geändert
Jede Inhaltsänderung wird versioniert. Wählen Sie eine Version, um sie mit der vorherigen zu vergleichen.
Version 7 → 8
AktualisierungNeues Modul zu Integrationsjobs im Detail, damit der Kurs die MCIE-Prüfung abdeckt: Plattformquellen, Schema-Reload, Variablen in jeder Schreibweise, Mapping-Fehler und Zeilenreihenfolge, Entfernen-Aktionen, Links, die Objekt-API, Export und Import, Timeouts sowie das Stoppen und Wiederherstellen von Läufen. Korrigiert: Eine Aktion, die eine Ausnahme auslöst, deaktiviert die Integration. Die neuen Lektionen erhielten Diagramme und Listen für die erste Prüfung.
3 Lektionen aktualisiertDauer
Inhaltliche Aktualisierung. Eingeschriebene Lernende wurden benachrichtigt.
Dauer von 22 auf 25 Minuten geändert.
Eine Integration, die in der Demo funktioniert, kann sich mit echten Daten trotzdem schlecht verhalten. Die Ursachen sind fast immer eine Handvoll Regeln zu Quellen, Schemas und Mapping-Zeilen. Diese Lektion geht sie in der Reihenfolge durch, in der ein Lauf ihnen begegnet.
### Den Monosync-Objektspeicher lesen
Eine Quelle vom Typ `Integration Platform` liest die eigenen Objekte von Monosync. Ihre Einstellung `Use only updated items` macht einen `Incremental Sync` klein: Ohne sie nimmt ein inkrementeller Lauf jedes Objekt und dauert so lange wie ein vollständiger. Suchen Sie die Antwort nicht in `Priority`. Dieses Feld wird gespeichert, aber der Laufcode liest es nicht.
### Reload setzt Ihre Flags zurück
`Reload` an einem bereits vorhandenen Schema ersetzt jede nicht benutzerdefinierte Eigenschaft durch die aktuelle Liste des Providers. Selbst angelegte Eigenschaften bleiben, aber `Key`, `Identity` und die anderen Flags an Provider-Eigenschaften gehen auf die Werte des Providers zurück. Ein Link-Lauf gleicht über die `Key`-Eigenschaft des Zielschemas ab und speichert den `Identity`-Wert. Nach einem unachtsamen Reload werden vorhandene Benutzer daher nicht mehr gefunden, und eine Create-Aktion trifft auf bereits vorhandene Konten. Prüfen Sie die Flags nach `Reload` und vor `Save`.
### Geheimnisse gehören in Variablen
Eine Quelleneinstellung mit Schlosssymbol wird nur am Bildschirm maskiert. Die Einstellungen der Quelle werden als einfaches JSON gespeichert, und jedes Speichern einer Quelle schreibt eine Commit-Zeile. Der eigentliche verschlüsselte Speicher ist eine als verschlüsselt markierte Variable. Legen Sie das Passwort in einer solchen Variable ab und verweisen Sie in der Quelleneinstellung mit `{{Variables.AdPassword}}` darauf. Der Wert wird zur Laufzeit und beim Verbindungstest eingesetzt.
### Drei Orte, drei Schreibweisen
| Wo Sie schreiben | Wie eine Variable geschrieben wird | Beispiel |
| --- | --- | --- |
| Quelleneinstellungen und Aktionsparameter | Doppelte geschweifte Klammern | `{{Variables.MailDomain}}` |
| Modifikator `Formatted` an einer Mapping-Zeile | Einfache geschweifte Klammern, dazu `{0}` für den eingehenden Wert | `{0}@{Variables.MailDomain}` |
| Modifikator `Code` | Ein C#-Name | `Variables.MailDomain` |
Mit der `Formatted`-Vorlage oben ergeben der Wert `jdoe` und die Variable `MailDomain` = `example.com` das Ergebnis `[email protected]`. Eine in der falschen Form geschriebene Variable wird nicht ersetzt, und die Zeile scheitert mit einem Mapping-Fehler.
### Was eine fehlschlagende Zeile bewirkt
Eine Mapping-Zeile, die eine Ausnahme auslöst, wird für diesen Datensatz protokolliert, und der Datensatz wird übersprungen. Der Lauf geht weiter. Er endet nur dann im Fehler, wenn jeder Datensatz scheitert. Eine `Code`-Zeile muss leere Werte selbst prüfen. Die fehlgeschlagenen Datensätze finden Sie unter `Mapping error(s) found!` in der Aktionsansicht des Laufs. Mit `Include Action(s) failed on last run(s)`, das standardmäßig an ist, nehmen spätere inkrementelle Läufe sie wieder auf, sobald der Code korrigiert ist.
### Reihenfolge zwischen Zeilen
Zeilen werden parallel ausgewertet, mit einer Ausnahme: Eine `Code`-Zeile, die `Data.X = ...` zuweist, läuft seriell vor allen anderen. Baut eine Zeile die E-Mail-Adresse aus einem Benutzernamen, den eine andere Zeile berechnet, muss die erste Zeile den berechneten Wert über `Data.X` zuweisen. `One Time` hilft hier nicht. Es verhält sich wie `One Way`.
::diagram scd-mapping-order
### Warum ein Link-Lauf eine Änderung sieht, die es nicht gibt
Ein Link-Lauf vergleicht skalare Werte in ihrer Textform, und der Vergleich beachtet Groß- und Kleinschreibung. Ein Boolean aus einem Mapping wird als `True` geschrieben, was nie einem Zielwert `true` entspricht. Dieselben Benutzer werden also bei jedem Lauf zur Aktualisierung markiert. Öffnen Sie das Fenster `Values` eines solchen Objekts: `Before` und `Now` unterscheiden sich nur in Schreibweise oder Typ. Die Lösung ist, den Wert im Mapping zu normalisieren, zum Beispiel in Text in Kleinbuchstaben.
### Funktionen werden bei jedem Lauf kompiliert
Jede Funktion wird beim Start eines Laufs neu kompiliert. `Remove` an einer Funktion prüft nur Mapping-Code. Eine Funktion, die noch aus einem Interceptor, einem Filter oder einer anderen Funktion aufgerufen wird, lässt sich entfernen. Von da an kompilieren die Aufrufer nicht mehr, und jeder Lauf der betroffenen Integrationen endet im Fehler. Nutzen Sie `Show References` und durchsuchen Sie Interceptor- und Filtercode nach dem Namen, bevor Sie eine Funktion entfernen.
> Tipp: Wenn ein Lauf Sie überrascht, prüfen Sie in dieser Reihenfolge: die Kennzeichen `Key` und `Identity` nach einem `Reload`, die Schreibweise jeder Variable für die Stelle, an der sie steht, und `Mapping error(s) found!` in der Aktionsansicht des Laufs.
Nach dem Mapping erreichen die Datensätze die Aktionen. Hier schreibt eine Integration in ein echtes System, deshalb zählen die Regeln hier am meisten.
### Wo gefiltert wird
| Ort | Sieht | Wofür |
| --- | --- | --- |
| Regel-Editor im Tab `Sources` der Integration | Quelldatensätze | Zeilen auf der Quellseite auswählen |
| Interceptor `After Source Fetch` | Rohfelder der gewählten Quellen | Datensätze vor dem Mapping per Code verwerfen oder ändern |
| Interceptor `After Mapping` | Gemappte Datensätze | Die gemappte Liste vor den Aktionen anpassen |
| Filter an einer Aktion | Die gemappten, zielseitigen Werte | Entscheiden, welche Datensätze diese Aktion erhält |
Ein Feld, das nirgends gemappt ist, lässt sich nur an den ersten beiden Stellen prüfen. Eine Ausnahme in einem Interceptor beendet den Lauf im Fehler. Bevorzugen Sie daher den einfachen Quellfilter, wenn er genügt.
::diagram scd-filter-places
### Entfernen braucht `None` und einen Filter
Eine Aktion erhält die Datensätze, die zu ihrer `Projection` passen. `Create` und `Update` folgen dem Link des Objekts. Eine Aktion zum Entfernen, etwa das Deaktivieren der Konten von Austritten, ist der Sonderfall: In Sync-Läufen wählt die Projektion `Remove` keinen Datensatz aus, und das Aktionsprotokoll meldet `No need to take action. There is no data for this projection.` Konfigurieren Sie die Aktion mit der Projektion `None` und einem Filter, der die Austritte auswählt. Weil Aktionsfilter gemappte Werte lesen, muss das Austrittsmerkmal eine gemappte Eigenschaft sein.
### Eine fehlgeschlagene Aktion und eine Ausnahme sind verschieden
| Was in einer Aktion geschieht | Wirkung auf den Lauf |
| --- | --- |
| Einige Elemente enden mit Warning oder Error | Das Aktionsprotokoll zeigt es, und die nächste Aktion läuft trotzdem |
| Die Aktion löst eine Ausnahme aus, etwa durch einen ungültigen Filter oder einen Provider-Absturz | Spätere Aktionen laufen nicht, der Lauf wird auf Error gesetzt und die Integration wird deaktiviert |
In beiden Fällen bleibt die Arbeit früherer Aktionen bestehen. Nichts wird zurückgerollt. Nach einer Ausnahme beheben Sie die Ursache und aktivieren die Integration wieder.
### Datensatzwerte an ein Skript übergeben
Die PowerShell-Aktion `Execute Script` kann Datensatzwerte auf zwei Wegen erhalten. Ein Platzhalter `{{Data.displayName}}` wird in den Skripttext eingefügt. Ein Wert mit Anführungszeichen oder Semikolon verändert also den Code, der mit den Rechten des konfigurierten Kontos läuft. Ein benannter Eintrag unter `Parameters` wird als Wert übergeben:
```
param($DisplayName, $Sam)
Set-ADUser -Identity $Sam -DisplayName $DisplayName
```
Verwenden Sie `Parameters` für alles, was aus Datensatzdaten stammt.
### Links entscheiden über Create oder Update
Ein Link-Lauf ordnet jedes Objekt über die `Key`-Eigenschaft des Zielschemas einer Zielzeile zu und speichert den `Identity`-Wert der Zeile im Link. Wählen Sie einen `Key`, der in beiden Systemen stabil und eindeutig ist, etwa eine Personalnummer. Anzeigenamen ändern und wiederholen sich.
Ein Link wird über Objekt, Quelle und Provider gefunden, nicht über die Integration. Schreiben die Integrationen A und B in dieselbe Quelle, lässt ein von A angelegter Link auch B das Objekt als verknüpft behandeln. Das Löschen der Links von B lässt die von A bestehen, und B sendet das Objekt weiter an seine Update-Aktion.
### Objekte über die REST-API schreiben
```
PATCH /api/v1/objects/employee/1042
Api-Key: <Schlüssel>
{ "department": "Sales" }
```
| Methode | Eigenschaften, die im Body fehlen |
| --- | --- |
| `POST`, `PUT` | Ihre Werte werden entfernt |
| `PATCH` | Ihre Werte bleiben erhalten |
Jeder API-Schreibvorgang zeichnet eine Objektänderung auf, auch wenn sich kein Wert geändert hat. Das Objekt gelangt also in den nächsten inkrementellen Lauf. Senden Sie nur echte Änderungen.
### Export und Import zwischen Umgebungen
`Settings` exportiert ausgewählte Integrationen, Quellen, Objekttypen, Variablen und Funktionen in eine JSON-Datei und importiert sie an anderer Stelle, Element für Element. Ein eingehendes Element wird über die ID, dann über den Namen zugeordnet, und ein Treffer wird nur mit `Overwrite all objects` ersetzt. Bevor Sie mit dieser Option in die Produktion importieren, denken Sie an drei Dinge: Ausgewählte Quellen bringen ihre Testhosts und Passwörter mit, wählen Sie sie also ab. Eine importierte oder überschriebene Integration bleibt inaktiv, aktivieren Sie sie danach. Und Objektdatensätze sind nicht Teil des Exports.
Ein Lauf ist der Moment, in dem eine Integration ein Zielsystem tatsächlich berührt. Die meisten Überraschungen im Betrieb betreffen drei Fragen: wann ein Lauf startet, warum einer nicht gestartet ist und was zurückbleibt, wenn einer mittendrin stoppt. Diese Lektion beantwortet sie in dieser Reihenfolge.
### Vier Wege, wie ein Lauf startet
| Start | Wann | Merken |
| --- | --- | --- |
| Zeitplan | Eine Cron-Zeit im Tab `Triggers`, in UTC ausgewertet | Ein Laufmodus je Zeitplan |
| Ungeplante Schleife | Die Integration ist aktiv und hat keinen aktivierten Zeitplan | Läuft unmittelbar nacheinander |
| `Run Once` | Nur an einer inaktiven Integration | Schreibt wirklich |
| `Calculate` | Jederzeit, mit gewähltem Modus | Ein Probelauf, der nie Zielaktionen aufruft |
Die ungeplante Schleife überrascht alle, die eine Integration aktivieren, bevor sie den Zeitplan anlegen. Die Integration wartet nicht. Sie läuft sofort und nach jedem Lauf erneut, als Full Sync, wenn innerhalb des letzten Tages kein erfolgreicher ungeplanter Full Sync gestartet ist, sonst als Incremental Sync. Legen Sie zuerst den Zeitplan an und aktivieren Sie dann.
### Verpasste Zeiten werden nicht nachgeholt
Die nächste Planzeit ist das nächste Cron-Vorkommen nach dem späteren von zwei Zeitpunkten: dem letzten Jobstart dieses Zeitplans und der Aktivierung. Eine Integration, die über das Wochenende deaktiviert war, holt die beiden verpassten Zeiten nicht nach, wenn Sie sie am Montag aktivieren. Das Beenden des Wartungsmodus verhält sich ebenso. Wird die verpasste Arbeit gebraucht, starten Sie sie bewusst.
### Ein Lauf je Integration
Monosync führt nie zwei Jobs einer Integration gleichzeitig aus. Ein Lauf, der sich überschneiden würde, wird mit `This integration is running in another task.` übersprungen. Seine Zeile auf `Integration Jobs` bleibt im Leerlauf und wird später als Aborted geschlossen. Mehrere Aborted-Zeilen mit leerem `Start / End` sind also Auslassungen, keine Fehler. Eine häufige Ursache ist ein Zeitplan, der öfter auslöst, als ein Lauf dauert.
### Das Timeout
| Einstellung | Wert | Bedeutung |
| --- | --- | --- |
| `Timeout (in seconds)` an der Integration | Größer als 0 | Der Lauf wird nach so vielen Sekunden abgebrochen |
| `Timeout (in seconds)` an der Integration | 0 oder leer | Der Dienststandard gilt |
| `MONOSYNC_SERVICE_INTEGRATION_TIMEOUT_SECONDS` auf den Dienstknoten | Standard `14400` | Vier Stunden für jede Integration ohne eigenes Timeout |
Ein Lauf, der die Grenze erreicht, endet als Aborted. Ein Full Sync, der auf einer Standardinstallation fünf Stunden braucht, wird jedes Mal abgebrochen, bis Sie der Integration einen eigenen Wert geben, zum Beispiel `21600` für sechs Stunden. `Cron Buffer (in minutes)` und `Priority` werden gespeichert, aber nicht gelesen. Sie helfen also nicht.
### Einen Lauf stoppen
`Integration Jobs` ist schreibgeschützt und hat nur die Schaltfläche `Refresh`. Um einen laufenden Job zu stoppen, deaktivieren Sie die Integration und beantworten die Frage mit `Yes, stop also running tasks`.
### Nach einem abgebrochenen Lauf
Schreibvorgänge am Ziel werden Aktion für Aktion gespeichert, und eine Objektänderung wird erst als verarbeitet vermerkt, wenn ihre Verarbeitung gelungen ist. Aus einem Abbruch mitten in den Aktionen folgen zwei Dinge:
- Die bereits erfolgten Schreibvorgänge bleiben am Ziel bestehen.
- Der nächste inkrementelle Lauf nimmt dieselben Objektänderungen erneut.
Das Datendatum der Integration rückt nur nach einem erfolgreichen Sync vor, es geht also nichts verloren. Die Zielaktionen müssen aber eine Wiederholung vertragen: Eine zweimal angewendete Aktualisierung muss dasselbe Ergebnis liefern wie eine einmal angewendete.
::diagram scd-run-after-abort
### Was Sie zuerst prüfen
- Läufe direkt hintereinander: Ist die Integration aktiv, ohne dass ein Zeitplan aktiviert ist?
- Aborted-Zeilen mit leerem `Start / End`: Das sind übersprungene Läufe. Vergleichen Sie das Intervall des Zeitplans mit der Dauer eines Laufs.
- Ein langer Full Sync, der immer Aborted endet: Geben Sie der Integration einen eigenen Wert für `Timeout (in seconds)`.