Salesforce-Datensätze mit SOQL in Jitterbit Studio abfragen

Einführung

SOQL (Salesforce Object Query Language) ist die Abfragesprache, die von allen Salesforce-APIs zum Abrufen von Datensätzen verwendet wird. Studio bietet zwei Möglichkeiten zum Abfragen von Salesforce-Datensätzen:

• Salesforce Query-Aktivität: Ein Konfigurationsassistent, der die SOQL-Anweisung erstellt und validiert, ein Antworschema generiert und als Quelle in einem Vorgang fungiert. Verwende diese für Bulk-Lesevorgänge, bei denen Salesforce-Datensätze eine Transformation steuern.
• Skriptfunktionen (SfLookup, SfLookupAll): Inline-Lookups, die in einem Skript oder einer Transformationszuordnung ausgeführt werden. Verwende diese für Lookups mit einzelnem Wert oder kleinen Sätzen, die Verarbeitungslogik unterstützen, z. B. das Auflösen einer übergeordneten Datensatz-ID während einer Transformation.

Vollständige Referenzdokumentation findest du unter Salesforce Query-Aktivität und Salesforce-Funktionen.

In dieser Anleitung wird vorausgesetzt, dass eine Salesforce-Verbindung bereits im Projekt konfiguriert ist.

Designmuster

Die Query-Aktivität folgt dem Transformationsmuster:

Teil 1: Konfiguriere die Salesforce Query-Aktivität

Schritt 1: Benennen Sie die Aktivität und wählen Sie Objekte aus

1. Ziehe auf der Design-Leinwand eine Query-Aktivität vom Typ einer vorhandenen Salesforce-Verbindung, um den Vorgang zu starten.

2. Doppelklicke auf die Aktivität, um ihre Konfiguration zu öffnen.

3. Name: Gib einen aussagekräftigen Namen ein, z. B. Query Contacts.

4. Objekt(e) auswählen: Klicke auf das primäre Objekt, das abgefragt werden soll, z. B. Contact oder Account. Es kann nur ein primäres Objekt ausgewählt werden.

5. Zugehörige Objekt(e) auswählen: Aktiviere optional das Kontrollkästchen neben jedem zugehörigen Objekt, das in die Abfrage einbezogen werden soll. Dies erzeugt eine Beziehungsabfrage, mit der du Felder von untergeordneten oder übergeordneten Objekten in einer einzigen Anfrage abrufen kannst. Die Auswahl von zugehörigen Objekten ist auf unmittelbare untergeordnete Elemente und Vorgänger bis zu fünf Ebenen beschränkt.

6. Klicke auf Weiter.

Schritt 2: Wählen Sie Felder aus und erstellen Sie Bedingungen

1. Aktiviere im Panel Felder auswählen und Bedingungen erstellen die Kontrollkästchen für die Felder, die einbezogen werden sollen. Das Textfeld SOQL-Anweisung auf der rechten Seite wird automatisch aktualisiert, wenn du Auswahl vorgenommen hast.

2. Um Klauseln hinzuzufügen, die vom Feldwähler nicht unterstützt werden (z. B. ORDER BY, LIMIT oder Unterabfragen), bearbeite das Textfeld der SOQL-Anweisung direkt. Eine SOQL-Syntaxreferenz findest du in der Salesforce-Dokumentation zu SOQL SELECT-Syntax.

3. Um Ergebnisse zu filtern, füge mit den Dropdown-Menüs Objekt: Feld, Operator und Wert eine WHERE-Klausel hinzu und klicke dann auf den Link „Hinzufügen", um die Bedingung an die Klausel anzuhängen. Wiederhole dies, um mehrere Bedingungen hinzuzufügen, und füge zwischen diesen AND oder OR ein.

   Tipp

   Um nur Datensätze abzurufen, die seit einem bestimmten Zeitpunkt geändert wurden (das häufigste Filtermuster in Synchronisierungsintegrationen), füge eine Bedingung für LastModifiedDate mit dem Operator >= und einer Projektvariablen oder globalen Variablen, die den Zeitstempel enthält, hinzu. Beispiel:

   SELECT Id, Name, Email FROM Contact WHERE LastModifiedDate >= 2024-01-01T00:00:00Z
   

   Ersetze das Datumsliteral durch einen Variablenverweis wie [last_sync_timestamp], damit der Wert zwischen den Ausführungen aktualisiert werden kann, ohne die Aktivitätskonfiguration zu ändern.

1. Klicken Sie auf Test Query, um die Anweisung zu validieren. Die Query muss die Validierung bestehen, bevor die Schaltfläche Next verfügbar wird.

2. Klicken Sie auf Next.

Schritt 3: Datenschema überprüfen

1. Überprüfen Sie das Antwortschema, das aus der Query generiert wurde. Dieses Schema wird in der Transformation in Teil 2 verwendet.

2. Klicken Sie auf Finished.

Teil 2: Datensätze in einer Transformation zuordnen

1. Fügen Sie auf der Entwurfsfläche einen Transformation-Schritt nach der Query-Aktivität hinzu und dann eine Zielaktivität nach der Transformation.

2. Öffnen Sie die Transformation. Das Antwortschema aus der Query-Aktivität wird als Quelle angezeigt. Wenn die Transformation das Schema der Salesforce-Aktivität widerspiegelt, enthält die Quelle einen Root-Knoten records. Dieser Knoten wird automatisch als Loop-Knoten festgelegt, sodass jeder Datensatz im Ergebnissatz einzeln verarbeitet wird.

3. Ordnen Sie die Felder unter dem Knoten records den entsprechenden Zielfeldern zu.

Eine vollständige Anleitung zur Transformationszuordnung finden Sie unter Übersicht über die Transformationszuordnung.

Teil 3: Alternativ aus einem Skript abfragen

Verwenden Sie Skriptfunktionen, wenn Sie einen Wert oder einen kleinen Datensatzsatz inline nachschlagen müssen (z. B. um eine übergeordnete Datensatz-ID während einer Transformation zu ermitteln oder bedingungsabhängige Logik in einem Skript zu steuern). Skriptfunktionen melden sich automatisch bei Salesforce mit der Endpunktreferenz an. Ein separater Anmeldungsaufruf ist nicht erforderlich.

SfLookup

SfLookup gibt das erste Feld des ersten Datensatzes zurück, der der Query entspricht. Verwenden Sie es, um einen einzelnen Wert aufzulösen, z. B. eine Konto- oder Kontakt-ID:

accountId = SfLookup("<TAG>endpoint:salesforce/Salesforce</TAG>",
    "SELECT Id FROM Account WHERE Name='" + $account_name + "'");
If(IsNull(accountId), RaiseError(GetLastError()));

SfLookupAll

SfLookupAll gibt ein zweidimensionales Array aller Datensätze zurück, die der Query entsprechen. Verwenden Sie es, wenn Sie über einen Ergebnissatz in einem Skript iterieren müssen:

contacts = SfLookupAll("<TAG>endpoint:salesforce/Salesforce</TAG>",
    "SELECT Id, Name, Email FROM Contact WHERE AccountId='" + $account_id + "'");
If(IsNull(contacts), RaiseError(GetLastError()));
firstContactName = contacts[0]["Name"];

Auf Felder kann nach Name (contacts[0]["Name"]) oder nach nullbasiertem Index (contacts[0][1]) zugegriffen werden.

SfCacheLookup

SfCacheLookup hat die gleiche Signatur wie SfLookup, speichert das Ergebnis aber für die Dauer der Operationskette zwischen. Verwenden Sie es, wenn die gleiche Suche mehrmals mit identischen Parametern ausgeführt wird (z. B. bei der einmaligen Suche nach einem statischen Referenzwert pro Transformationsschleife-Iteration):

orgId = SfCacheLookup("<TAG>endpoint:salesforce/Salesforce</TAG>",
    "SELECT Id FROM Organization LIMIT 1");

Nachfolgende Aufrufe mit der gleichen Endpunktreferenz und SOQL-Zeichenkette geben den zwischengespeicherten Wert zurück, ohne einen weiteren API-Aufruf zu tätigen.

Integration überprüfen

Stellen Sie die Operation bereit und führen Sie sie aus. Überprüfen Sie die Operationsprotokolle, um sicherzustellen, dass die Query-Aktivität erfolgreich ausgeführt wurde, und überprüfen Sie, ob die Datensatzanzahl im Ziel dem erwarteten Ergebnissatz aus Salesforce entspricht. Wenn keine Datensätze zurückgegeben werden, überprüfen Sie die Bedingungen der WHERE-Klausel und stellen Sie sicher, dass alle in der Klausel verwendeten Variablen ihre erwarteten Werte erhalten haben, bevor die Operation ausgeführt wird.