Aktualisieren Sie Clarizen Daten mit einer Operationskette im Jitterbit Design Studio

Einführung

Dieses Integrationsmuster verwendet eine Kette von Operationen innerhalb von Harmony Design Studio, um Daten in Ihre verbundene Clarizen-Instanz einzufügen. Bevor Sie beginnen, sollten Sie bereits mit der Funktionsweise von Jitterbit vertraut sein und einen Clarizen Endpoint einrichten und in der Lage sein, die native Abfrage zu verwenden, erstellen und update Operationen innerhalb des Design Studio Clarizen-Connector.

Zusammenfassung

Der Zweck eines Upsert Operation besteht darin, bereits vorhandene Datensätze zu aktualisieren und nicht vorhandene Datensätze einzufügen. Obwohl Clarizens REST- API Upsert-Vorgänge nicht explizit unterstützt, ermöglicht Jitterbit einfache und flexible Konfigurationen von Einfüge-/ 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 beibehält, kann verwendet werden, und wenn für das Objekt keines vorhanden ist, kann in Clarizen ein benutzerdefiniertes Feld erstellt werden, um die Datensatz-IDs des Quellsystems zu speichern.

Das folgende Diagramm zeigt den verallgemeinerten Workflow eines Clarizen-Upserts unter Verwendung dieses Entwurfsmusters.

Insbesondere erfordert das Upserting von Datensätzen in Clarizen die Pflege von (Schlüssel, Wert)-Paaren der eindeutigen Schlüssel/Werte und deren Zuordnung zu Clarizen-Datensatz-IDs. Anschließend können die Datensätze in „Erstellen“ oder „Aktualisieren“ unterteilt werden, je nachdem, ob ihr eindeutiger Schlüssel eine entsprechende Clarizen ID im Schlüsselspeicher hat.

Es gibt zahlreiche Möglichkeiten, den Schlüsselspeicher und die Trennung von Datensätzen mit unterschiedlichen Effizienzgraden zu implementieren. Unten sehen Sie die Implementierung, der wir in diesem Muster folgen werden, wobei an bestimmten Stellen die Effizienz zugunsten der Einfachheit geopfert wird. Die Zahlen entsprechen den Schritten im nächsten Abschnitt.

Umsetzung

In den folgenden Abschnitten werden die wichtigsten Schritte zur Implementierung dieses Entwurfsmusters beschrieben. Als Beispiel werden wir vorhandene Benutzerobjektdaten in Clarizen in unsere Kundenobjektdaten in Clarizen hochladen. Dies ist das endgültige Setup:

Schritt 1: Abrufen der zu aktualisierenden Quelldaten

Geben Sie zunächst die Daten ein, die Sie für den Upsert Operation verwenden möchten. Verwenden Sie dazu die Standardfunktion von Jitterbit. Sie können eine Vielzahl von Quellen verwenden von Daten.

Für dieses Beispiel Abfrage wir alle vorhandenen Mitarbeiter aus dem Benutzerobjekt innerhalb unserer verbundenen Clarizen Instanz ab und verwenden diese Daten dann als Quelle für unseren Upsert. Für das Beispiel richten wir unsere Quelldaten wie folgt ein:

1. Erstellen Operation eine neue Clarizen Abfrage für das Benutzerobjekt und wählen Sie alle Felder aus. Die Abfrage heißt „Mitarbeiter abfragen“.

2. Erstellen Sie aus dieser Abfrage eine Operation (klicken Sie auf die Schaltfläche Operation erstellen). Die Operation hat den Namen „1. Zu aktualisierende Quelldaten abrufen.“

3. Führen Sie die Daten unverändert durch die Transformation (Rechtsklick auf Antwort > Pass-Through). Sie können auch eine normale Transformation einrichten, um Daten in dem von Ihnen gewünschten Format zu erhalten.

4. Legen Sie das Ziel als temporären Speicher mit dem Namen „Mitarbeiter“ fest (doppelklicken Sie auf Ziel > Neues Ziel erstellen; geben Sie ein: „Temporärer Speicher“; Dateiname: „Mitarbeiter“).

5. Kopieren Sie das Ziel „Mitarbeiter“ in eine Quelle, die ebenfalls „Mitarbeiter“ heißt (klicken Sie im linken Baum mit der rechten Maustaste auf das entsprechende Ziel > In neue Quelle kopieren). Dies wird im nächsten Operation als Quelle für unsere Upsert-Daten verwendet.

6. Führen Sie bei Erfolg eine neue Transformation aus (Rechtsklick auf Operation > Bei Erfolg > Operation > Neue Operation erstellen > Transformation). Diese Operation wird als Nächstes in Schritt 2 verwendet.

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

In diesem Muster wird ein Wörterbuch verwendet, um die Paare (eindeutiger Schlüssel, Clarizen-ID) beizubehalten. Bei diesem Operation fügen wir vor der Quelle ein Script ein, um ein globales Wörterbuch zu initialisieren, und erstellen eine Transformation zum Zuordnen des eindeutigen Schlüsselfelds.

1. Je nachdem, wie Sie Ihre Quelle konfiguriert haben, sollte in Schritt 1 bereits eine neue leere Operation erstellt worden sein. Operation (Neue Operation > Transformation). Die Operation heißt „2. Dem Wörterbuch eindeutige Schlüssel hinzufügen.“

2. Geben Sie die Quelle Ihrer Daten an. Die Quelle sollte alle Datensätze enthalten, die aktualisiert werden sollen. Im Beispiel verwenden wir die in Schritt 1 erstellte Quelle „Mitarbeiter“ (doppelklicken Sie auf Quelle und wählen Sie die vorhandene Quelle „Mitarbeiter“).

3. Es wird kein Ziel benötigt. Entfernen Sie daher das Ziel aus der Operation (Rechtsklick auf Ziel > Aus Diagramm entfernen).

4. Fügen Sie vor der Quelle ein Script ein (klicken Sie mit der rechten Maustaste auf Quelle > Davor einfügen > Script) und erstellen Sie ein neues Script (mit dem Namen „Wörterbuch initialisieren“) wie folgt:

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

5. Erstellen Sie eine neue Transformation, deren Quell- und Zielstruktur mit Ihren Daten übereinstimmen (Doppelklick auf Transformation > Neue Transformation erstellen). Die Transformation im Beispiel heißt "Map Unique Key Field".

   1. Wählen Sie als Quelle dieselbe Struktur wie für Ihre Quelldaten. Im Beispiel ist unsere Quelle das Ergebnis einer Clarizen Abfrage, daher verwenden wir „Clarizen Function Response“. Als Ziel wählen wir „Text“.
   2. Folgen Sie für die Quelle den Anweisungen des Assistenten. Wählen Sie im Beispiel „Abfrage“ und die spezifische Abfrage aus, die als Quelle verwendet wird.
   3. Für das Ziel erstellen wir manuell eine neue Struktur, die ein Feld enthält (Verfügbare Dateiformatdefinitionen > Neu erstellen > Manuell erstellen; klicken Sie unter Segmenteigenschaften definieren auf Neu und geben Sie einen Feldnamen ein, z. B. „ID“). Im Beispiel lautet der Name des Dateiformats „Eindeutige Schlüssel“.
   4. Iterieren Sie in der Transformation über das eindeutige Schlüsselfeld, indem Sie es auf der Quellseite auf die Zielseite abbilden (im Beispiel ziehen Sie das Feld Benutzer > Entität > „id“ auf der linken Seite per Drag & Drop in das Feld „ID“ auf der rechten Seite).

6. Passen Sie die Transformation so an, dass im Wörterbuch ein neuer Eintrag mit dem eindeutigen Schlüsselfeld als ID und '0' als Wert hinzugefügt wird. Klicken Sie dazu auf der Zielseite doppelt auf Ihr ID-Feld 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 eindeutige Schlüsselfeld von der Quellseite ausgewählt wird.

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

7. Fügen Sie nach der soeben erstellten Transformation ein neues Script ein (Rechtsklick auf die Transformation > Danach einfügen > Script) und erstellen Sie ein neues Script mit dem Namen „Keystore aktualisieren“. Vorerst lassen wir das Script leer. Dies wird später im nächsten Schritt ausgefüllt, um einen Filter zu erstellen, sodass nur Clarizen Datensätze mit eindeutigen Schlüsseln abgefragt werden, die mit einem im Wörterbuch übereinstimmen.

Schritt 3 - Abfrage von Clarizen nach Datensätzen mit übereinstimmenden eindeutigen Schlüsseln

Um das Wörterbuch mit zugehörigen Clarizen IDs zu füllen, müssen Sie in diesem Muster eine neue Clarizen Operation für das Objekt erstellen, für das Sie ein Upsert durchführen 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 Operation eine neue Clarizen Abfrage für Ihr Objekt (im Beispiel verwenden wir das Customer-Objekt) mit einer Abfrage 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 Kundenobjekt als unseren eindeutigen Schlüssel, und zwar wie folgt:

   SELECT C_JB_External_Id FROM Customer Where C_JB_External_Id In [ClarizenWhereClause]
   

   Notiz

   Die [ClarizenWhereClause] ist eine Projektvariable, die wir später im Script „Update Keystore“ definieren werden.

2. Erstellen Sie aus dieser Abfrage eine Operation (klicken Sie auf die Schaltfläche Operation erstellen). Die Operation heißt „3. Clarizen nach Datensätzen mit übereinstimmenden eindeutigen Schlüsseln abfragen.“

3. Es wird kein Ziel benötigt. Entfernen Sie daher das Ziel aus der Operation (Rechtsklick auf Ziel > Aus Diagramm entfernen).

4. Erstellen Sie eine neue Transformation (Doppelklick auf Transformation > Neue Transformation erstellen). Die Transformation im Beispiel heißt „Match Unique Keys“.

   1. Im Beispiel sollte die Quelle bereits als Antwort auf die Abfrage definiert sein. Als Ziel wählen wir „Text“.
   2. Wählen Sie für die Zielstruktur dasselbe Dateiformat aus, das Sie in Schritt 2 erstellt haben (im Beispiel „Unique Keys“ genannt).
   3. Ordnen Sie in der Transformation die ID-Felder von der Quellseite der Zielseite zu (im Beispiel ziehen Sie per Drag & Drop sowohl das Feld „ID“ von Benutzer > Entität > als auch das benutzerdefinierte Feld „C_JB_External_Id“ auf der linken Seite in das 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. Dadurch wird Ihr eindeutiger Schlüssel gleich Ihrer Objekt-ID gesetzt. Doppelklicken Sie dazu auf der Zielseite auf Ihr ID-Feld 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 als Nächstes ein neues Script, das aus den Wörterbuchschlüsseln eine IN-Klausel erstellt. Dies kann außerhalb der Operation erstellt werden (klicken Sie im Baum links mit der rechten Maustaste auf Scripts > Neues Script). Das Script im Beispiel heißt „InClause aus Dict-Schlüsseln erstellen“. Fügen Sie Folgendes in das Script 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. Nachdem das IN- Script nun erstellt ist, können wir es im Script „Update Keystore“ verwenden, das am Ende der zweiten Operation in Schritt 2 erstellt wurde. Dieses Script durchläuft Ihr Schlüsselwörterbuch und durchsucht Clarizen nach einem übereinstimmenden Datensatz. Sobald es fertig ist, führt es die Aktualisierungs- und Einfügevorgänge aus, die wir in den nächsten Schritten einrichten werden. Doppelklicken Sie auf dieses Script und geben Sie Folgendes ein. Ersetzen Sie dabei bei Bedarf die Namen Ihrer tatsächlichen Scripts und Vorgänge.

   <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>
   

   Notiz

   Der letzte Teil dieses Script verbindet die Vorgänge, die als Nächstes in den Schritten 4 und 5 erstellt werden. Möglicherweise müssen Sie am Ende zu diesem Script zurückkehren, um bei Bedarf die Operation zu aktualisieren.

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

Dieser Schritt filtert Datensätze für einen Clarizen Operation heraus und führt dann die Aktualisierung der Datensätze in der Clarizen-Instanz durch.

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

2. Geben Sie die Quelle an, die alle Datensätze enthält, die aktualisiert werden sollen. Im Beispiel verwenden wir die in Schritt 1 erstellte Quelle „Mitarbeiter“ (doppelklicken Sie auf Quelle und wählen Sie die vorhandene Quelle „Mitarbeiter“).

3. Es wird kein Ziel benötigt. Entfernen Sie daher das Ziel aus der Operation (Rechtsklick auf Ziel > Aus Diagramm entfernen).

4. Erstellen Sie eine neue Transformation (Doppelklick auf Anfrage > Neue Transformation erstellen). Die Transformation im Beispiel heißt „Separate Records to Update“.

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

   2. Folgen Sie für die Beispielquelle den Anweisungen des Assistenten. Wählen Sie im Beispiel „Abfrage“ und die spezifische Abfrage aus, die als Quelle verwendet wird. Wenn Sie einen anderen Quelltyp haben, wählen Sie die entsprechenden Optionen aus.

   3. Erstellen Sie in der Transformation eine Bedingung für den Zielobjektordner (klicken Sie im Beispiel mit der rechten Maustaste auf den Ordner „Kunden“ > Bedingung hinzufügen). Die Bedingung sollte „true“ zurückgeben, wenn der Datensatz im Wörterbuch gefunden wird, und „false“, wenn dies nicht der Fall ist:

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

      Im Beispiel wird 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 mithilfe des eindeutigen Schlüssels aus dem Wörterbuch abrufen. Klicken Sie dazu doppelt auf die ID auf der Zielseite und geben Sie Folgendes ein:

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

      Im Beispiel wird dies wie folgt eingestellt:

      <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 das Feld „Benutzer > Entität > „ID“ auch dem Feld „Kunde > „C_JB_External_Id“ (benutzerdefiniertes Feld) auf der rechten Seite zu. Im Beispiel wird das Feld „Benutzer > Entität > „DisplayName“ auch dem Feld „Kunde > „Name“ auf der rechten Seite zugeordnet.

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

6. Wenn Ihr Operation abgeschlossen ist, überprüfen Sie das am Ende von Schritt 3 beschriebene Script „Update Keystore“, um sicherzustellen, dass dieser Operation im Script ausgeführt wird.

Schritt 5 - Einzelne Datensätze erstellen und dann in Clarizen einfügen

Dieser Schritt filtert Datensätze für einen Clarizen Operation heraus und führt dann das Einfügen der Datensätze in die Clarizen-Instanz durch.

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

2. Geben Sie die Quelle an, die alle Datensätze enthält, die aktualisiert werden sollen. Im Beispiel verwenden wir die in Schritt 1 erstellte Quelle „Mitarbeiter“ (doppelklicken Sie auf Quelle und wählen Sie die vorhandene Quelle „Mitarbeiter“).

3. Es wird kein Ziel benötigt. Entfernen Sie daher das Ziel aus der Operation (Rechtsklick auf Ziel > Aus Diagramm entfernen).

4. Erstellen Sie eine neue Transformation (Doppelklick auf Anfrage > Neue Transformation erstellen). Die Transformation im Beispiel heißt „Separate zu erstellende Datensätze“.

   1. Wählen Sie für die Quelle dieselbe Struktur wie für Ihre Quelldaten. Im Beispiel ist unsere Quelle das Ergebnis einer Clarizen Abfrage, daher verwenden wir „Clarizen Function Response“. Das Ziel sollte als Anforderung für den Operation definiert werden.

   2. Folgen Sie für die Beispielquelle den Anweisungen des Assistenten. Wählen Sie im Beispiel „Abfrage“ und die spezifische Abfrage aus, die als Quelle verwendet wird. Wenn Sie einen anderen Quelltyp haben, wählen Sie die entsprechenden Optionen aus.

   3. Erstellen Sie in der Transformation eine Bedingung für den Zielobjektordner (klicken Sie im Beispiel mit der rechten Maustaste auf den Ordner „Kunden“ > Bedingung hinzufügen). Die Bedingung sollte „false“ zurückgeben, wenn der Datensatz im Wörterbuch gefunden wird, und „true“, wenn dies nicht der Fall 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 wird 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 sollen. Im Beispiel ordnen wir das Feld „Benutzer > Entität > „ID“ auch dem Feld „Kunde > „C_JB_External_Id“ (benutzerdefiniertes Feld) auf der rechten Seite zu. Im Beispiel wird das Feld „Benutzer > Entität > „DisplayName“ auch dem Feld „Kunde > „Name“ auf der rechten Seite zugeordnet.

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

6. Wenn Ihr Operation abgeschlossen ist, überprüfen Sie das am Ende von Schritt 3 beschriebene Script „Update Keystore“, um sicherzustellen, dass dieser Operation im Script ausgeführt wird.

Optimierung

Das oben dargestellte Entwurfsmuster verwendet der Einfachheit halber ein Wörterbuch, um eindeutige Schlüssel mit ihren zugehörigen Clarizen IDs zu verwalten.

Dies ist für viele Anwendungsfälle ausreichend, aber da das Wörterbuch nicht gespeichert wird, muss Clarizen jedes Mal abgefragt werden, um den Schlüsselspeicher zu erstellen. Dadurch wird mindestens eine zusätzliche API Nutzung pro aktualisiertem Datensatz hinzugefügt.

Da sich mit einer Bulk Abfrage 100.000 Datensätze pro Aufruf Abfrage lassen, ist der Aufwand bei großen Datenmengen meist vernachlässigbar. Bei hochfrequenten Echtzeitanwendungen kann dies allerdings schnell zu einem kostspieligen Zusatzaufwand werden.

Eine Alternative besteht darin, den Cloud-Cache von Jitterbit zum Speichern dieser IDs zu verwenden. Die Verwendung des Cloud-Cache bringt einige zusätzliche Komplexitäten mit sich. Da er nur 250 Lese-/Schreibvorgänge pro Sekunde zulässt, muss der Implementierer den Fall berücksichtigen, dass das Lesen oder Schreiben fehlschlägt.

Andere Alternativen sind die Verwendung externer Persistenzebenen zur Verwaltung des Schlüsselspeicher oder die Verwendung eines lokalen Speichers bei Verwendung eines privaten Agenten.