Zum Inhalt springen

Clarizen-Daten mit einer Operationskette in Jitterbit Design Studio aktualisieren oder einfügen

Einführung

Dieses Integrationsmuster verwendet eine Operationskette in Harmony Design Studio, um Daten in Ihre verbundene Clarizen-Instanz einzufügen oder zu aktualisieren. Bevor Sie beginnen, sollten Sie bereits mit der Funktionsweise von Jitterbit vertraut sein, einen Clarizen-Endpunkt eingerichtet haben und die nativen Operationen Abfrage, Erstellen und Aktualisieren im Design Studio Clarizen-Connector verwenden können.

Zusammenfassung

Der Zweck einer Upsert-Operation besteht darin, vorhandene Datensätze zu aktualisieren und neue Datensätze einzufügen. Obwohl die REST-API von Clarizen Upsert-Operationen nicht explizit unterstützt, ermöglicht Jitterbit einfache und flexible Konfigurationen von Einfüge-/Aktualisierungs-Workflows.

In diesem Muster wird ein eindeutiges Schlüsselfeld verwendet, um die Existenz eines Datensatzes zu bestimmen, indem in Clarizen nach einem Datensatz gesucht wird, dessen eindeutiges Schlüsselfeld denselben Wert hat. Das eindeutige Schlüsselfeld muss für jeden Datensatz einen anderen Wert haben und in beiden Systemen gleich sein. Jedes Feld, das diese Eigenschaften bereits erfüllt, kann verwendet werden. Falls kein solches Feld im Objekt vorhanden ist, kann ein benutzerdefiniertes Feld in Clarizen erstellt werden, um die Datensatz-IDs des Quellsystems zu speichern.

Das folgende Diagramm zeigt den verallgemeinerten Workflow eines Clarizen-Upserts mit diesem Designmuster.

attachment

Konkret erfordert das Aktualisieren oder Einfügen von Datensätzen in Clarizen die Verwaltung von (Schlüssel, Wert)-Paaren der eindeutigen Schlüssel/Werte und deren Zuordnung zu Clarizen-Datensatz-IDs. Anschließend können die Datensätze basierend darauf in „Erstellen" oder „Aktualisieren" unterteilt werden, ob ihr eindeutiger Schlüssel eine entsprechende Clarizen-ID im Schlüsselspeicher hat.

Es gibt zahlreiche Möglichkeiten, den Schlüsselspeicher zu implementieren und Datensätze zu trennen, mit unterschiedlichen Effizienzgraden. Nachfolgend finden Sie die Implementierung, die wir in diesem Muster verwenden und die an bestimmten Stellen Effizienz für Einfachheit opfert. Die Nummern entsprechen den Schritten im nächsten Abschnitt.

attachment

Implementierung

Die folgenden Abschnitte beschreiben die wichtigsten Schritte zur Implementierung dieses Designmusters. Als Beispiel werden wir vorhandene Benutzerobjekt-Daten in Clarizen in unsere Kundenobjekt-Daten in Clarizen einfügen oder aktualisieren. Dies ist die endgültige Einrichtung:

attachment

Schritt 1 – Quelldaten für das Einfügen oder Aktualisieren abrufen

attachment

Rufen Sie zunächst die Daten ab, die Sie für die Upsert-Operation verwenden möchten, indem Sie die standardmäßige Jitterbit-Funktionalität nutzen. Sie können verschiedene Datenquellen verwenden.

In diesem Beispiel fragen wir alle vorhandenen Mitarbeiter aus dem Benutzerobjekt in unserer verbundenen Clarizen-Instanz ab und verwenden diese Daten dann als Quelle für unser Upsert. Für das Beispiel richten wir unsere Quelldaten wie folgt ein:

  1. Erstellen Sie eine neue Clarizen-Abfrageoperation für das Benutzerobjekt und wählen Sie alle Felder aus. Die Abfrage heißt „Query Employees".

  2. Erstellen Sie eine Operation aus dieser Abfrage (klicken Sie auf die Schaltfläche Operation erstellen). Die Operation heißt „1. Quelldaten für das Einfügen oder Aktualisieren abrufen".

  3. Leiten Sie die Daten ohne Änderungen durch die Transformation (Rechtsklick auf Antwort > Durchleiten). Sie können auch eine normale Transformation einrichten, um Daten in dem Format zu erhalten, das Sie verwenden möchten.

  4. Legen Sie das Ziel als temporären Speicher fest, benannt "Employees" (doppelklicken Sie auf Target > Create New Target; Typ: "Temporary Storage"; Dateiname: "employees").

  5. Kopieren Sie das Ziel "Employees" in eine Quelle, ebenfalls benannt "Employees" (klicken Sie im Baum auf der linken Seite mit der rechten Maustaste auf das spezifische Ziel > Copy to New Source). Dies wird als Quelle für unsere Upsert-Daten in der nächsten Operation verwendet.

  6. Führen Sie eine neue Transformationsoperation bei erfolgreicher Ausführung aus (klicken Sie mit der rechten Maustaste auf den Operationshintergrund > On Success > Operation > Create New Operation > Transformation). Diese Operation wird im nächsten Schritt verwendet.

Schritt 2 – Eindeutige Schlüssel zu einem Wörterbuch hinzufügen

attachment

In diesem Muster wird ein Wörterbuch verwendet, um die Paare (eindeutiger Schlüssel, Clarizen-ID) zu verwalten. In dieser Operation fügen wir ein Skript vor der Quelle ein, um ein globales Wörterbuch zu initialisieren, und erstellen eine Transformation, um das Feld des eindeutigen Schlüssels zuzuordnen.

  1. Je nachdem, wie Sie Ihre Quelle konfiguriert haben, sollten Sie bereits eine neue leere Operation aus Schritt 1 erstellt haben. Wenn nicht, erstellen Sie eine neue Transformationsoperation (New Operation > Transformation). Die Operation heißt "2. Add Unique Keys to Dictionary."

  2. Geben Sie die Quelle Ihrer Daten an. Die Quelle sollte alle Datensätze enthalten, die eingefügt oder aktualisiert werden sollen. Im Beispiel verwenden wir die in Schritt 1 erstellte Quelle "Employees" (doppelklicken Sie auf Source und wählen Sie die vorhandene Quelle "Employees").

  3. Es ist kein Ziel erforderlich, daher entfernen Sie das Ziel aus der Operation (klicken Sie mit der rechten Maustaste auf Target > Remove from Graph).

  4. Fügen Sie ein Skript vor der Quelle ein (klicken Sie mit der rechten Maustaste auf Source > Insert Before This > Script), und erstellen Sie ein neues Skript (benannt "Initialize the Dictionary") wie folgt:

    <trans>
$UpsertIdDict = Dict();
</trans>

  5. Erstellen Sie eine neue Transformation, deren Quell- und Zielstrukturen mit Ihren Daten identisch sind (doppelklicken Sie auf Transformation > Create New Transformation). Die Transformation im Beispiel heißt "Map Unique Key Field."

    1. Wählen Sie für die Quelle die gleiche Struktur wie Ihre Quelldaten. Im Beispiel ist unsere Quelle das Ergebnis einer Clarizen-Abfrage, daher verwenden wir "Clarizen Function Response." Für das Ziel wählen wir "Text."
    2. Folgen Sie für die Quelle den Anweisungen des Assistenten, wählen Sie im Beispiel "Query" und die spezifische Abfrageoperation, die als Quelle verwendet wird.
    3. Für das Ziel erstellen wir manuell eine neue Struktur mit einem Feld darin (Available File Format Definitions > Create New > Create Manually; klicken Sie unter Define Segment Properties auf New und geben Sie einen Feldnamen ein, z. B. "ID"). Im Beispiel heißt das Dateiformat "Unique Keys."
    4. Iterieren Sie in der Transformation über das Feld des eindeutigen Schlüssels, indem Sie es auf der Quellenseite auf die Zielseite abbilden (ziehen Sie im Beispiel das Feld User > Entity > "id" auf der linken Seite auf das Feld "ID" auf der rechten Seite).

  6. Ändern Sie die Transformation so, dass ein neuer Eintrag im Wörterbuch mit dem Feld des eindeutigen Schlüssels als ID und "0" als Wert hinzugefügt wird. Doppelklicken Sie dazu auf Ihr ID-Feld auf der Zielseite und geben Sie Folgendes ein:

    <trans>
AddToDict($UpsertIdDict, Quote(<Your_Unique_Key>), 0)
</trans>

    Im Beispiel wird \<Your_Unique_Key> durch OUTPUT\(User\)Entity.id$ ersetzt, indem das Feld des eindeutigen Schlüssels auf der Quellenseite ausgewählt wird.

    <trans>
AddToDict($UpsertIdDict, Quote(OUTPUT$User$Entity.id$), 0)
</trans>

  7. Fügen Sie ein neues Skript nach der gerade erstellten Transformation ein (klicken Sie mit der rechten Maustaste auf die Transformation > Insert After This > Script), und erstellen Sie ein neues Skript namens "Update Keystore." Vorerst lassen wir das Skript leer. Dies wird im nächsten Schritt ausgefüllt, um einen Filter zu erstellen, damit nur Clarizen-Datensätze mit eindeutigen Schlüsseln abgefragt werden, die einem im Wörterbuch entsprechen.

Schritt 3 – Clarizen nach Datensätzen mit übereinstimmenden eindeutigen Schlüsseln abfragen

attachment

Um das Wörterbuch mit zugehörigen Clarizen-IDs zu füllen, müssen Sie in diesem Muster eine neue Clarizen-Abfrageoperation für das Objekt erstellen, zu dem Sie Daten einfügen oder aktualisieren möchten. Die ID und der eindeutige Schlüssel müssen abgefragt werden, und am Ende sollte eine Projektvariable hinzugefügt werden, um eine WHERE-Klausel einzuschließen.

  1. Erstellen Sie eine neue Clarizen-Abfrageoperation für Ihr Objekt (im Beispiel verwenden wir das Customer-Objekt) mit einer Abfragezeichenfolge im folgenden Format.

    SELECT <Your_Unique_Key> FROM <Your_Object> Where <Your_Unique_Key> In [ClarizenWhereClause]

    Im Beispiel verwenden wir ein benutzerdefiniertes Feld namens "C_JB_External_Id" in unserem Customer-Objekt als eindeutigen Schlüssel wie folgt:

    SELECT C_JB_External_Id FROM Customer Where C_JB_External_Id In [ClarizenWhereClause]

    Hinweis

    Die [ClarizenWhereClause] ist eine Projektvariable, die wir später im Skript "Update Keystore" definieren.

  2. Erstellen Sie eine Operation aus dieser Abfrage (klicken Sie auf die Schaltfläche Create Operation). Die Operation trägt den Namen "3. Query Clarizen for Records with Matching Unique Keys."

  3. Es ist kein Ziel erforderlich, daher entfernen Sie das Ziel aus der Operation (Rechtsklick auf Target > Remove from Graph).

  4. Erstellen Sie eine neue Transformation (Doppelklick auf Transformation > Create New Transformation). Die Transformation im Beispiel trägt den Namen "Match Unique Keys."

    1. Im Beispiel sollte die Quelle bereits als Antwort aus der Objektabfrage definiert sein. Für das Ziel wählen wir "Text."
    2. Wählen Sie für die Zielstruktur das gleiche Dateiformat aus, das in Schritt 2 erstellt wurde (im Beispiel "Unique Keys" genannt).
    3. Ordnen Sie in der Transformation die ID-Felder von der Quellseite zur Zielseite zu (im Beispiel ziehen Sie sowohl das Feld User > Entity > "id" als auch das benutzerdefinierte Feld "C_JB_External_Id" von links zum Feld "ID" auf der rechten Seite).

  5. Ändern Sie die Transformation, um die Clarizen-IDs in die Wörterbuchwerte für die entsprechenden eindeutigen Schlüssel zu schreiben. Dies setzt Ihren eindeutigen Schlüssel gleich Ihrer Objekt-ID. Doppelklicken Sie dazu auf Ihr ID-Feld auf der Zielseite und geben Sie Folgendes ein:

    <trans>
$UpsertIdDict[Quote(OUTPUT$<Your_Object>$Entity.<Your_Unique_Key>$)] = OUTPUT$<Your_Object>$Entity.id$;
</trans>

    Denken Sie daran, dass Sie auf die Felder unter OUTPUT auf der rechten Seite doppelklicken können, um die entsprechenden Felder für Ihren eindeutigen Schlüssel und Ihr Objekt zu erhalten. Das Beispiel lautet wie folgt:

    <trans>
$UpsertIdDict[Quote(OUTPUT$Customer$Entity.C_JB_External_Id$)] = OUTPUT$Customer$Entity.id$;
</trans>

  6. Erstellen Sie anschließend ein neues Skript, das eine IN-Klausel aus den Wörterbuchschlüsseln konstruiert. Dies kann außerhalb der Operation erstellt werden (im Baum auf der linken Seite, Rechtsklick auf Scripts > New Script). Das Skript im Beispiel trägt den Namen "Construct InClause from Dict Keys." Fügen Sie Folgendes in das Skript ein:

    <trans>
ArgumentList(Dictionary, start, end);
keys = GetKeys(Dictionary);

//keyIter = 0;
inClause = '';
if(end > length(keys),
//use length keys as condition
while( start <length(keys)-1,
    inClause = inClause + keys[start] + ', ';
    start++;);,
while( start < end ,
    inClause = inClause + keys[start] + ', ';
    start++;);
);

inClause + keys[start]
</trans>

  7. Jetzt, da das IN-Klausel-Skript erstellt ist, können wir es im Skript "Update Keystore" verwenden, das am Ende der zweiten Operation in Schritt 2 erstellt wurde. Dieses Skript durchläuft Ihr Schlüsselwörterbuch und sucht in Clarizen nach einem übereinstimmenden Datensatz. Nach Abschluss werden dann die Update- und Insert-Operationen ausgeführt, die wir in den nächsten Schritten einrichten. Doppelklicken Sie auf dieses Skript und geben Sie Folgendes ein, wobei Sie die Namen Ihrer tatsächlichen Skripte und Operationen nach Bedarf ersetzen.

    <trans>
//Update cache
keys = GetKeys($UpsertIdDict);
//WriteToOperationLog(keys);
interval = 999;
batch = 0;

While(batch*interval < Length(keys),
$ClarizenWhereClause = '(' + RunScript("<TAG>Scripts/Construct InClause From Dict Keys</TAG>",$UpsertIdDict, batch*interval, (batch + 1)*interval - 1) + ')';
WriteToOperationLog($ClarizenWhereClause);
If(!RunOperation("<TAG>Operations/3. Query Clarizen for Records with Matching Unique Keys</TAG>",true),
RaiseError(GetLastError())
);
batch ++;
);

RunOperation("<TAG>Operations/4. Separate Records to Update; Update Records</TAG>",false);
RunOperation("<TAG>Operations/5. Separate Records to Create; Insert Records</TAG>",false)
</trans>

    Wichtig

    Der synchrone RunOperation-Aufruf innerhalb der While-Schleife unterliegt einem Limit auf Agent-Ebene für synchrone Aufrufe, die innerhalb einer einzelnen While-Schleife durchgeführt werden (50 standardmäßig). Mit interval = 999 erreicht diese Schleife dieses Limit bei ungefähr 50.000 Schlüsseln; bei den in Optimization beschriebenen 100.000-Datensatz-Ladevorgängen erreicht die Schleife das Limit teilweise durch und die verbleibenden Batches werden nicht abgefragt. Weitere Informationen zum Konfigurieren oder Überschreiben dieses Limits finden Sie in der Anmerkung unter RunOperation, oder erhöhen Sie interval, um die Anzahl der Schleifeniterationen für große Schlüsselsätze zu reduzieren.

Hinweis

Der letzte Teil dieses Skripts verbindet die Operationen, die in den nächsten Schritten 4 und 5 erstellt werden. Möglicherweise müssen Sie am Ende zu diesem Skript zurückkehren, um bei Bedarf Operationsnamen zu aktualisieren.

Schritt 4 - Datensätze zum Aktualisieren trennen und dann Datensätze in Clarizen aktualisieren

attachment

Dieser Schritt filtert Datensätze für eine Clarizen-Aktualisierungsoperation heraus und führt dann die Aktualisierung von Datensätzen in der Clarizen-Instanz durch.

  1. Erstellen Sie eine neue Clarizen-Aktualisierungsoperation für das Objekt, das Sie aktualisieren möchten (im Beispiel das Customer-Objekt).

  2. Geben Sie die Quelle an, die alle Datensätze enthält, die eingefügt oder aktualisiert werden sollen. Im Beispiel verwenden wir die in Schritt 1 erstellte Quelle „Employees" (doppelklicken Sie auf Source und wählen Sie die vorhandene Quelle „Employees" aus).

  3. Es ist kein Ziel erforderlich, daher entfernen Sie das Ziel aus der Operation (Rechtsklick auf Target > Remove from Graph).

  4. Erstellen Sie eine neue Request-Transformation (doppelklicken Sie auf Request > Create New Transformation). Die Transformation im Beispiel heißt „Separate Records to Update".

    1. Wählen Sie für die Quelle die gleiche Struktur wie Ihre Quelldaten aus. Im Beispiel ist unsere Quelle das Ergebnis einer Clarizen-Abfrage, daher verwenden wir „Clarizen Function Response". Das Ziel sollte als Anfrage für die Aktualisierungsoperation definiert werden.

    2. Folgen Sie für die Beispielquelle den Anweisungen des Assistenten, wählen Sie im Beispiel „Query" und die spezifische Abfrageoperation aus, die als Quelle verwendet wird. Wenn Sie eine andere Art von Quelle haben, wählen Sie die entsprechenden Optionen aus.

    3. Erstellen Sie in der Transformation eine Bedingung für den Zielobjektordner (im Beispiel Rechtsklick auf den Customer-Ordner > Add condition). Die Bedingung sollte „true" zurückgeben, wenn der Datensatz im Wörterbuch gefunden wird, und „false", wenn er nicht gefunden wird:

      <trans>
if($UpsertIdDict[Quote(OUTPUT$<Your_Object>$Entity.id$)]!='0',
WriteToOperationLog('Found in Dict');
true,
WriteToOperationLog('Not Found In Dict');
false)
</trans>

      Im Beispiel ist die Bedingung wie folgt festgelegt:

      <trans>
if($UpsertIdDict[Quote(OUTPUT$User$Entity.id$)]!='0',
WriteToOperationLog('Found in Dict');
true,
WriteToOperationLog('Not Found In Dict');
false)
</trans>

    4. Ordnen Sie dann das ID-Feld zu, indem Sie es mit dem eindeutigen Schlüssel aus dem Wörterbuch abrufen. Das heißt, doppelklicken Sie auf die ID auf der Zielseite und geben Sie Folgendes ein:

      <trans>
$UpsertIdDict[Quote(OUTPUT$<Your_Object>$Entity.id$)]
</trans>

      Im Beispiel ist dies wie folgt festgelegt:

      <trans>
$UpsertIdDict[Quote(OUTPUT$User$Entity.id$)]
</trans>

    5. Fahren Sie mit der Zuordnung aller verbleibenden ID-Felder sowie aller anderen Felder fort, die beim Aktualisieren zugeordnet werden sollen. Im Beispiel ordnen wir auch das Feld User > Entity > „id" dem Feld Customer > „C_JB_External_Id" (benutzerdefiniertes Feld) auf der rechten Seite zu. Im Beispiel wird das Feld User > Entity > „DisplayName" auch dem Feld Customer > „Name" auf der rechten Seite zugeordnet.

  5. Für die verbleibende Response-Transformation in der Operation können Sie die Daten ohne Änderungen durch die Transformation leiten (Rechtsklick auf Response > Pass-Through).

  6. Wenn Ihre Aktualisierungsoperation abgeschlossen ist, überprüfen Sie das am Ende von Schritt 3 beschriebene Skript „Update Keystore" noch einmal, um sicherzustellen, dass diese Operation zur Ausführung im Skript enthalten ist.

Schritt 5 - Datensätze zum Erstellen trennen und dann Datensätze in Clarizen einfügen

attachment

Dieser Schritt filtert Datensätze für eine Clarizen-Erstellungsoperation heraus und führt dann das Einfügen von Datensätzen in die Clarizen-Instanz durch.

  1. Erstellen Sie eine neue Clarizen-Erstellungsoperation für das Objekt, in das Sie Daten einfügen möchten (im Beispiel das Customer-Objekt).

  2. Geben Sie die Quelle an, die alle Datensätze enthält, die eingefügt oder aktualisiert werden sollen. Im Beispiel verwenden wir die in Schritt 1 erstellte Quelle „Employees" (doppelklicken Sie auf Source und wählen Sie die vorhandene Quelle „Employees" aus).

  3. Es ist kein Ziel erforderlich, daher entfernen Sie das Ziel aus der Operation (Rechtsklick auf Target > Remove from Graph).

  4. Erstellen Sie eine neue Request-Transformation (Doppelklick auf Request > Create New Transformation). Die Transformation im Beispiel heißt "Separate Records to Create."

    1. Wählen Sie als Quelle die gleiche Struktur wie Ihre Quelldaten aus. In unserem Beispiel ist die Quelle das Ergebnis einer Clarizen-Abfrage, daher verwenden wir "Clarizen Function Response." Das Ziel sollte als Request für die Create-Operation definiert werden.

    2. Folgen Sie für die Beispielquelle den Anweisungen des Assistenten und wählen Sie im Beispiel "Query" und die spezifische Query-Operation aus, die als Quelle verwendet wird. Wenn Sie eine andere Art von Quelle haben, wählen Sie die entsprechenden Optionen aus.

    3. Erstellen Sie in der Transformation eine Bedingung für den Zielobjektordner (im Beispiel Rechtsklick auf den Customer-Ordner > Add condition). Die Bedingung sollte "false" zurückgeben, wenn der Datensatz im Dictionary gefunden wird, und "true", wenn er nicht vorhanden ist:

      <trans>
if($UpsertIdDict[Quote(OUTPUT$<Your_Object>$Entity.id$)]=='0',
WriteToOperationLog('Not Found in Dict. Creating CZ customer');
true,
WriteToOperationLog('Found In Dict. Customer already exists in CZ');
false)
</trans>

      Im Beispiel ist die Bedingung wie folgt festgelegt:

      <trans>
if($UpsertIdDict[Quote(OUTPUT$User$Entity.id$)]=='0',
WriteToOperationLog('Not Found in Dict. Creating CZ customer');
true,
WriteToOperationLog('Found In Dict. Customer already exists in CZ');
false)
</trans>

    4. Fahren Sie mit der Zuordnung aller verbleibenden ID-Felder sowie aller anderen Felder fort, die beim Aktualisieren zugeordnet werden sollten. Im Beispiel ordnen wir auch das Feld User > Entity > "id" dem Feld Customer > "C_JB_External_Id" (benutzerdefiniertes Feld) auf der rechten Seite zu. Im Beispiel wird das Feld User > Entity > "DisplayName" auch dem Feld Customer > "Name" auf der rechten Seite zugeordnet.

  5. Für die verbleibende Response-Transformation der Operation können Sie die Daten ohne Änderungen durch die Transformation leiten (Rechtsklick auf Response > Pass-Through).

  6. Wenn Ihre Create-Operation abgeschlossen ist, überprüfen Sie das Skript "Update Keystore", das am Ende von Schritt 3 beschrieben wird, um sicherzustellen, dass diese Operation im Skript ausgeführt wird.

Optimierung

Das oben dargestellte Designmuster verwendet ein Dictionary, um eindeutige Schlüssel mit ihren zugehörigen Clarizen-IDs zu verwalten – aus Gründen der Einfachheit.

Dies ist für viele Anwendungsfälle ausreichend, aber da das Dictionary nicht persistent ist, muss Clarizen jedes Mal abgefragt werden, um den Keystore zu erstellen. Dies führt zu mindestens 1 zusätzlicher API-Nutzung pro upserted Datensatz.

Da eine Bulk-Abfrage verwendet werden kann, um 100.000 Datensätze pro Aufruf abzufragen, sind die Kosten normalerweise vernachlässigbar für große Datenmengen. Für hochfrequente Echtzeit-Anwendungen kann dies jedoch schnell zu einer teuren Ergänzung werden.

Eine Alternative besteht darin, Jitterbits Cloud-Cache zu verwenden, um diese IDs zu speichern. Die Verwendung des Cloud-Cache ist mit einigen zusätzlichen Komplexitäten verbunden, da nur 250 Lese-/Schreibvorgänge pro Sekunde möglich sind und der Implementierer den Fall behandeln muss, dass das Lesen oder Schreiben fehlschlägt.

Weitere Alternativen sind die Verwendung externer Persistierungsebenen zur Verwaltung des Keystores oder die Verwendung lokaler Speicherung bei Verwendung eines privaten Agenten.