Fehlerbehebung bei Operationen in Jitterbit Studio

Diese Anleitung behandelt Fehler und unerwartetes Verhalten beim Erstellen, Bereitstellen und Ausführen von Operationen in Jitterbit Studio, einschließlich Operationen, Transformationen, Skripte und Funktionen sowie Validierung zur Entwurfszeit. Wenn Sie Probleme mit einem bestimmten Connector beheben, siehe Connector-Fehlerbehebung.

Eine einheitliche Referenz, die Integrations-, Automatisierungs-, API-Management-, EDI- und App-Entwicklungsprobleme an einem Ort abdeckt, finden Sie im Harmony-Fehlerbehebungsleitfaden.

• HTTP- und API-Fehler

  • 504 Gateway Timeout
  • 507 Insufficient Storage
  • 502 Bad Gateway

• Fehler zur Entwurfszeit

  • Häufige Validierungsfehler bei Operationen
  • HTTP-Validierungsregelfehler
  • Komponentennamen müssen nach dem Projektimport eindeutig sein
  • Private Agent-only Connector-Blöcke importieren in eine Cloud-Agent-Umgebung
  • Das Hochladen einer Schemadatei ersetzt sie projektübergreifend
  • Die Bereitstellung der Marketplace-Prozessvorlage schlägt aufgrund eines Schemakonflikts fehl
  • Studio wird bei sehr großen Projekten langsam oder reagiert nicht mehr

• System- und Ressourcenfehler

  • Chunking wird nicht berücksichtigt, wenn die Quelle ein SDK-basierter Connector ist
  • Variablenupdates gehen bei segmentierten Multi-Threading-Operationen verloren
  • Fehler beim Erstellen des temporären Verzeichnisses
  • Operationsprotokollmeldungen werden bei etwa 100 KB gekürzt
  • Das Debug-Logging von Operationen zeigt PII und Anmeldedaten im Klartext

Diagnoseschritte

Diese Schritte gelten für fast jeden Operationsfehler und sind der empfohlene Ausgangspunkt, bevor man einen bestimmten Fehler untersucht.

Verbindung testen

Klicken Sie für alle Operationen, die Connectors verwenden, in der Verbindung auf die Schaltfläche Test, um sicherzustellen, dass die Verbindung erfolgreich ist.

Für Connector SDK-basierte Connectors, die in Operationen auf privaten Agents bereitgestellt werden, stellt das Klicken auf Test auch sicher, dass die neueste Version des Connectors auf den Agent heruntergeladen wird (es sei denn, die Organisationsrichtlinie Automatisches Connector-Update deaktivieren ist aktiviert).

Operationsprotokolle prüfen

Prüfen Sie die Operationsprotokolle auf alle während der Ausführung geschriebenen Informationen.

Je nach Agent-Typ sind zusätzliche Protokolldaten verfügbar:

• Aktivieren Sie das Debug-Logging von Operationen (für Cloud-Agents oder für private Agents).
• Aktivieren Sie ausführliches Connector-Logging (nur private Agents).
• Prüfen Sie die Agent-Protokolle (nur private Agents).

Agent-spezifische Fehler isolieren

Wenn eine Operation auf einigen Agents fehlschlägt, aber auf anderen innerhalb derselben privaten Agent-Gruppe erfolgreich ist, verwenden Sie die Option Auf dediziertem Agent ausführen, um die Operation an einen bestimmten Agent zu leiten. Dies ermöglicht es Ihnen, den Fehler auf dem problematischen Agent zu reproduzieren und zu untersuchen, ohne den Rest der Gruppe offline zu nehmen.

Um diese Option zu konfigurieren, öffnen Sie die Operationseinstellungen, wählen Sie die Registerkarte Optionen und konfigurieren Sie Auf dediziertem Agent ausführen.

Operationsausführung und Planung

Operationen, die im Status „Submitted" oder „Running" stecken bleiben

• Symptom: Eine Operation wird nicht wie erwartet abgeschlossen. Sie bleibt im Status Submitted oder Running stecken und macht keine Fortschritte, oder wird mit der Meldung abgebrochen:

  Long running operation canceled by System
  

  Der Abbruch kann erfolgen, nachdem die Operation eine Weile ausgeführt wurde, oder kurz nach dem Start, und spiegelt nicht unbedingt wider, wie lange die Operation tatsächlich ausgeführt wurde.

• Mögliche Ursachen:

  • Ein privater Agent hat die Verbindung zur Harmony-Plattform verloren und konnte den Operationsstatus nicht melden. Die Plattform zeigt die Operation weiterhin als Running an und kann sie als anscheinend hängend abbrechen, auch wenn die Operation auf dem Agent abgeschlossen wurde. Dies kann Operationen beeinflussen, die normalerweise in Sekunden abgeschlossen werden.
  • Die Operation wurde abgeschlossen, aber ihr endgültiger Status wurde nicht an Harmony zurückgemeldet, sodass sie weiterhin als Running angezeigt wird, bis sie abläuft.
  • Die Agent-Gruppe ist stark belastet und langsam beim Abholen oder Aktualisieren von Warteschlangen-Operationen.
  • Die Operation bleibt speziell im Status Submitted stecken: Die Ausführungsmeldung wurde in die Warteschlange eingereiht, aber kein Agent in der Gruppe hat sie akzeptiert, da die Agents offline sind, fehlerhaft sind oder keine freie Kapazität haben, um neue Operationen zu akzeptieren (z. B. ist jeder Worker-Thread belegt).

• Lösung:

  • Bestätigen Sie bei privaten Agents, dass der Agent auf der Seite Agents in der Management Console den Status Running hat, überprüfen Sie die Protokolle des privaten Agents auf Verbindungsprobleme, und stellen Sie sicher, dass die Netzwerkverbindung zwischen dem Agent und der Harmony-Plattform stabil ist.
  • Überprüfen Sie die Operationsprotokolle, um zu bestätigen, was während der Ausführung passiert ist. Die Abbruchmeldung kann auch bei Operationen angezeigt werden, die nur kurz ausgeführt wurden, daher deutet sie nicht unbedingt auf eine echte lange laufende Operation hin. Die Protokolle können auch einen spezifischen Fehler offenbaren, den man beheben kann, z. B. 401 Unauthorized (Anmeldedaten überprüfen) oder 429 Too Many Requests. Ein 429 von einem Ziel-Endpoint kann durch Reduzierung der Anfragerate oder durch Hinzufügen von Wiederholungslogik gelindert werden; ein 429 vom von Jitterbit verwalteten Cloud-API-Gateway ist sein Plattformlimit von 200 Anfragen pro Minute, daher verteilen Sie die Aufrufe über die Zeit oder führen Sie die betroffenen APIs auf privaten Agents aus.
  • Halten Sie private Agents auf einer aktuellen Version. Neuere Agent-Versionen verbessern die Agent-Ausfallsicherheit und reduzieren vorzeitige Abbrüche von Operationen.
  • Versuchen Sie, die betroffenen Operationen abzubrechen. Der Abbruch ist für Operationen mit dem Status Submitted, Received, Pending oder Running über die Seite Runtime der Management Console, die Operationsprotokolltabelle oder den Laufzeitstatus einer Operation auf der Design-Canvas verfügbar.
  • Wenn die betroffene Operation nach einem Zeitplan ausgeführt wird und nie startet, siehe Geplante Operationen werden nicht ausgeführt.
  • Wenn die Operationen nicht abgebrochen werden können, wenn das Problem erneut auftritt oder wenn viele Operationen gleichzeitig betroffen sind, kontaktieren Sie den Jitterbit-Support, da diese Fälle möglicherweise eine serverseitige Lösung erfordern.

Geplante Operationen werden nicht ausgeführt

• Symptom: Eine Operation, die mit einem Operationszeitplan konfiguriert ist, wird nicht zum geplanten Zeitpunkt ausgeführt oder wird versendet, bleibt aber in einem Pending- oder Received-Status.
• Mögliche Ursachen:
  • Der Zeitplan wurde der Operation in Studio zugewiesen, aber das Projekt wurde nicht bereitgestellt. In Studio zugewiesene Zeitpläne werden erst wirksam, wenn das Projekt bereitgestellt wird.
  • Der Zeitplan ist deaktiviert.
  • In den Zeitplaneinstellungen liegt eine Zeitzonen-Fehlkonfiguration vor.
  • Bei privaten Agents wird der Planungsdienst nicht ausgeführt.
  • Der dem Umfeld zugeordnete Agent ist offline oder fehlerhaft.
  • Änderungen, die in einem Projekt bereitgestellt wurden, haben sich nicht vollständig mit dem Agent synchronisiert.
  • Die Agent-Gruppe ist ressourcengesättigt. Ein Rückstau von lange laufenden Operationen oder anhaltend hohe CPU- oder Speicherauslastung kann verhindern, dass eine Agent-Gruppe geplante Operationen rechtzeitig aufgreift.
• Lösung:
  • Bestätigen Sie, dass das Projekt bereitgestellt wurde, seit der Zeitplan der Operation zugewiesen wurde.
  • Bestätigen Sie, dass der Zeitplan aktiviert ist. Zeitpläne können nur über die Seite Projects der Management Console auf den Registerkarten Operations und Schedules aktiviert oder deaktiviert werden.
  • Überprüfen Sie die Zeitplankonfiguration und achten Sie besonders auf die Zeitzonen-Einstellung. Weitere Informationen finden Sie unter Operationszeitzone.
  • Überprüfen Sie bei privaten Agents, ob der Agent auf der Seite Agents in der Management Console online und fehlerfrei ist, und bestätigen Sie, dass der Planungsdienst auf dem Agent-Computer ausgeführt wird. Überprüfen Sie unter Windows, ob Jitterbit Scheduler und Jitterbit Scheduler Service im Task Manager ausgeführt werden. Verwenden Sie unter Linux und Docker den Befehl jitterbit status.
  • Stellen Sie das Projekt erneut bereit, um zu erzwingen, dass sich der Zeitplan mit dem Agent neu synchronisiert.
  • Wenn Operationen in einem Pending-Status stecken, brechen Sie diese über die Seite Runtime der Management Console ab und starten Sie den Agent-Dienst neu.
  • Wenn Zeitplanausfälle mit der Last korrelieren, reduzieren Sie die Anzahl der gleichzeitig ausgeführten lange laufenden Operationen. Überprüfen Sie bei privaten Agents auch die CPU- und Speicherauslastung und gleichen Sie geplante Operationen mit der Kapazität des Agents ab (ein privater Agent kann bis zum Doppelten seiner CPU-Kernanzahl in gleichzeitigen Operationen ausgeführt werden).
  • Wenn eine geplante Operation versendet wird, dann aber steckenbleibt, anstatt nie zu starten, siehe Operationen, die in Submitted oder Running stecken.

Wörterbuch oder globale Variable ist nach asynchroner Ausführung einer Operation leer

• Symptom: Ein Wörterbuch oder eine globale Variable, die in einer untergeordneten Operation gefüllt wird, ist leer oder behält ihren früheren Wert, wenn die übergeordnete Operation es nach dem asynchronen Aufrufen der untergeordneten Operation liest.
• Mögliche Ursache: Wenn eine Operation asynchron aufgerufen wird (das Feld Run type des Tools Invoke Operation auf Asynchronously gesetzt oder RunOperation mit runSynchronously auf false gesetzt), wird die untergeordnete Operation in einem separaten Thread ausgeführt und die übergeordnete Operation wird fortgesetzt, ohne zu warten. Globale Variablen und Wörterbücher werden an die untergeordnete Operation nach Wert statt nach Referenz übergeben und sind nicht threadsicher. Daher werden Änderungen in der untergeordneten Operation nicht in der übergeordneten Operation widergespiegelt. Die übergeordnete Operation kann den Wert auch lesen, bevor die untergeordnete Operation abgeschlossen ist.
• Lösung:
  • Wenn die übergeordnete Operation von Werten abhängt, die die untergeordnete Operation erzeugt, rufen Sie die untergeordnete Operation synchron auf (das Feld Run type des Tools Invoke Operation auf Synchronously gesetzt oder RunOperation synchron ausgeführt, was die Standardeinstellung ist), damit die untergeordnete Operation abgeschlossen wird und ihre Änderungen an globalen Variablen von der übergeordneten Operation geerbt werden.
  • Um Daten zwischen Operationen zu teilen, die unabhängig ausgeführt werden müssen, speichern Sie diese mit Cache-Funktionen (WriteCache und ReadCache) statt sich auf ein Wörterbuch oder eine globale Variable über Threads hinweg zu verlassen. Cache-Funktionen sind standardmäßig auf 100 kombinierte Aufrufe pro Minute pro Organisation begrenzt.
  • Das Einfügen einer festen Verzögerung (z. B. mit der Funktion Sleep) erhöht die Latenz und garantiert nicht, dass die untergeordnete Operation abgeschlossen ist. Führen Sie die Operation stattdessen synchron aus.
• Verwandt: Für das entsprechende Verhalten in segmentierten Multi-Thread-Operationen siehe Variablenupdates gehen in segmentierten Multi-Thread-Operationen verloren.

Verbindungs- und Authentifizierungsfehler

Salesforce-Zertifikat: Nichtübereinstimmung des alternativen Antragstellers (SAN)

• Symptom: A Salesforce connection to a sandbox or an org with Enhanced Domains enabled fails with:

  Certificate for <url> doesn't match any of the subject alternative names
  

• Possible causes:

  • The certificate does not include the Salesforce MyDomain or sandbox URL in its Subject Alternative Names.
  • The Sandbox checkbox in the Salesforce connection settings is not correctly toggled.

• Resolution:

  • Inspect the certificate's SAN entries using OpenSSL: openssl x509 -in cert.crt -text -noout. Confirm the Subject Alternative Name section includes your Salesforce MyDomain URL.
  • In the Salesforce connection settings in Studio, verify the Sandbox checkbox is correctly set for your target org.
  • If the Salesforce URL is absent from the SANs, regenerate the certificate to include the specific domain.
  • If the same connection succeeds on a cloud agent group but fails on a private agent, the cause may instead be a missing SNI extension in the agent's TLS handshake. See Salesforce sandbox connection fails with certificate mismatch.

Fehler bei der Datenbankverbindung des privaten Agenten (TranDb)

• Symptom: Operationen schlagen mit Fehlern fehl, die auf die interne PostgreSQL-Datenbank des privaten Agenten (TranDb) verweisen, z. B. Failed to connect to back-end database 'TranDb' oder FATAL: query_wait_timeout.
• Ursache und Lösung: Dies ist ein Problem auf Agent-Ebene mit den internen Datenbankverbindungen des privaten Agenten. Weitere Informationen zu den Ursachen und der Lösung finden Sie unter TranDb-Verbindungsfehler im Fehlerbehebungsleitfaden für Agenten.

Client-Zertifikat kann auf Linux-Privatagenten nicht geladen werden

• Symptom: Eine Operation, die einen ausgehenden gegenseitigen TLS-Webservice-Aufruf (Client-Zertifikat) durchführt, schlägt zur Laufzeit auf einem Linux-Privatagenten fehl, mit einem Fehler wie:

  Problem with the local SSL certificate. Unable to set private key file: '<path>.key' type PEM.
  

  Das Zertifikat wird erfolgreich in Studio hochgeladen, aber die Operation schlägt fehl, wenn sie ausgeführt wird. Die gleiche Konfiguration hat möglicherweise zuvor auf einem Windows-Privatagenten funktioniert.

• Mögliche Ursachen:

  • Der Betriebssystembenutzer, der den Jitterbit-Agent ausführt, hat keine Leseberechtigung für die private Schlüsseldatei oder deren übergeordnete Verzeichnisse.
  • Ein Linux-Sicherheitsmodul wie SELinux oder AppArmor blockiert den Zugriff des Agents auf die private Schlüsseldatei.

• Lösung:

  • Stellen Sie sicher, dass das Konto, das den Jitterbit-Agent ausführt, Lesezugriff auf die private Schlüsseldatei und alle übergeordneten Verzeichnisse hat.
  • Überprüfen Sie, ob SELinux oder AppArmor den Zugriff auf die Schlüsseldatei einschränkt, und passen Sie die Richtlinie oder den Dateikontext entsprechend an.

Transformations- und Datenfehler

Nicht unterstützte XML-Elemente (CDATA) in JSON eingebettet

• Symptom: Character Data (CDATA) Abschnitte werden in XML, das in JSON eingebettet ist und durch eine Transformation verarbeitet wird, nicht unterstützt. Wenn vorhanden, wird der folgende Fehler im Operationsprotokoll angezeigt:

  Transformation failed. Error: The operation "Operation" failed.
  Error: Failed to convert XML file to JSON.
  org.jitterbit.integration.server.engine.EngineSessionException: org.xml.sax.SAXParseException ...
  

• Lösung: Verwenden Sie ein Jitterbit-Skript, um die Zeichen &, <, >, ' und " im CDATA-Abschnitt, einschließlich der CDATA-Trennzeichen (<![CDATA[ ... ]]>), mit ihren Escape-Äquivalenten (&, <, >, ', ") zu Replace. Wenn es nicht möglich ist, nur den CDATA-Abschnitt anzusteuern, kann die gesamte XML-Zeichenkette, die ihn enthält, ersetzt werden.

  Das folgende Beispiel gilt ohne diese Ersetzungen als ungültig:

  {
    "name": "Jitterbit",
    "data": "<xml><content><![CDATA[<greeting>Hello, world!</greeting>]]></content></xml>"
  }
  

Transformation schlägt fehl, wenn ein JSON-Zeichenfolgenwert die maximale Länge überschreitet

• Symptom: Eine Transformation, die einen großen JSON-Zeichenfolgenwert verarbeitet, schlägt mit einem Fehler fehl, der meldet, dass die Zeichenkette die maximal zulässige Länge überschreitet, zum Beispiel:

  Transformation failed. Error: Error Code: String value length (20054016) exceeds the maximum allowed (20000000, from StreamReadConstraints.getMaxStringLength())
  

  Die Stack-Trace verweist auf StreamConstraintsException und den JSON-Parser des Agents. Ein häufiger Auslöser ist eine HTTP v2-Antwort mit aktiviertem Get response content in base64 string: Base64-Codierung vergrößert binäre Inhalte (wie eine Audio- oder Mediendatei), sodass die codierte Zeichenkette die Grenze überschreiten kann, selbst wenn die ursprüngliche Datei kleiner ist.

• Ursache: Der JSON-Parser des Agents begrenzt einen einzelnen JSON-Zeichenfolgenwert standardmäßig auf 20 MB (20000000 Zeichen). Ein Wert, der größer als diese Grenze ist, schlägt fehl, während der Agent ihn analysiert, bevor eine nachgelagerte Aktivität (wie ein Upload) ausgeführt wird.

• Lösung: Erhöhen Sie auf einem privaten Agent mit Version 12.5 oder später die Grenze mit dem Schlüssel MaxStringLength im Abschnitt [JsonParser] der Konfigurationsdatei jitterbit.conf (setzen Sie ihn beispielsweise auf 50000000 für eine Grenze von 50 MB), und starten Sie den Agent neu. Dieser Schlüssel ist in Agent-Version 12.5 und später verfügbar. Aktualisieren Sie den Agent daher zuerst, wenn er eine frühere Version hat.

Sonderzeichen in von Connectoren bereitgestellten JSON-Schemas

• Symptom: Wenn eine Transformation ein JSON-Schema verwendet, das von einer benachbarten Connector-Aktivität geerbt wird, werden alle Sonderzeichen in einem Schemafeld oder Knotennamen durch Unterstriche (_) ersetzt. Bei Verwendung der Legacy-JSON-Verarbeitung (Standard für Projekte, die vor dem 11.48 Harmony Release erstellt wurden), kann dies dazu führen, dass der Endpunkt Fehler zurückgibt, da die tatsächlichen Feldnamen nicht mehr mit den erwarteten übereinstimmen.

Zum Beispiel wird ein Feld namens location_ids[] in location_ids__ konvertiert. Wenn der Endpunkt den ursprünglichen Namen erwartet, kann dies zu einem Fehler führen wie:

"error_message": "{location_ids:expected String to be a Array}"

• Lösung:

  1. Bestätigen Sie, dass im betroffenen Connector ein JSON-Schema verwendet wird. Solche Schemas haben einen Wurzelknoten namens json:

     

  2. Aktivieren Sie die Projekteinstellung JSON-Namen beibehalten (erfordert Agent-Version 11.48 oder später) .

  3. Konfigurieren Sie den Vorgang neu, stellen Sie ihn bereit und führen Sie ihn aus.

  Wichtig

  Wenn JSON-Namen beibehalten in einem Projekt aktiviert wird, in dem diese Einstellung zuvor deaktiviert war, gilt die neue Verarbeitungsmethode nur für Vorgänge und Schemas, die nach der Aktivierung der Einstellung konfiguriert werden. Bestehende Vorgänge und Schemas verwenden weiterhin die Legacy-JSON-Verarbeitung. Um Inkonsistenzen innerhalb eines Projekts zu vermeiden, konfigurieren Sie alle bestehenden Vorgänge und Schemas neu, nachdem Sie diese Einstellung aktiviert haben.

  Um den an den Endpunkt gesendeten Feldnamen zu überprüfen, prüfen Sie den Wert jsonPropertyName in den Ein- oder Ausgabedaten des Connectors mit aktiviertem Debug-Logging:

  

Multibyte-Zeichen werden in einer großen Connector-Antwort beschädigt

• Symptom: Ein Multibyte-Zeichen in einer JSON-Connector-Antwort wird beschädigt. Der beschädigte Text zeigt das klassische Muster von UTF-8-Bytes, die als Latin-1 dekodiert werden (z. B. São Luís wird als São LuÃs zurückgegeben). Normalerweise ist nur ein Multibyte-Zeichen betroffen, das nach etwa den ersten 8 KB der Antwort erscheint; das gleiche Zeichen, das früher in der Antwort erscheint, ist nicht betroffen.
• Mögliche Ursache: Bei Agent-Versionen 12.8 und 12.9 werden bei der automatischen Zeichenkodierungserkennung nur der Anfang der Antwort abgetastet, um die Kodierung zu bestimmen. Wenn dieses Beispiel nur ASCII-Zeichen enthält, wird die Antwort als Latin-1 (ISO-8859-1) statt UTF-8 erkannt, was alle Multibyte-Zeichen beschädigt, die über den abgetasteten Bereich hinausgehen.
• Lösung: Aktualisieren Sie auf Agent-Version 12.10 oder später, die die Kodierungserkennung korrigiert.

Gespiegelte Schemas mit Substitutionsgruppen

• Symptom: Gespiegelte Schemas, die XML-Substitutionsgruppen verwenden, werden nicht unterstützt. Die Verwendung führt zu einem Laufzeitfehler:

  Failed to initialize transformation "<transformation name>". Failed to expand the (source|target) tree for the path: <path to substitution head node>.
  

  Dieser Fehler kann auch aus anderen Gründen auftreten, z. B. beim Importieren einer Transformationszuordnung mit doppelten Knoten, und deutet nicht unbedingt auf ein Substitutionsgruppenprobleme hin.

• Lösung: Wenn Substitutionsgruppen die bestätigte Ursache sind, löschen Sie das gespiegelte Schema und erstellen Sie es mit einer anderen Methode neu (Hochladen, Erstellen eines benutzerdefinierten Schemas usw.).

Importieren einer Transformationszuordnung mit doppelten Knoten schlägt mit „Knoten kann nicht erstellt werden" fehl

• Symptom: Eine Transformation, deren Zuordnung aus einer Datei importiert wurde, die doppelte Knoten referenziert, schlägt zur Laufzeit mit einem Fehler wie folgt fehl:

Fehler beim Initialisieren der Transformation „<transformation name>". Fehler beim Erweitern des Zielbaums für den Pfad: <path to node>. Der Knoten: <node name> kann nicht erstellt werden.

Die Zuordnung kann im Transformations-Designer korrekt aussehen, auch wenn der Vorgang bei der Ausführung fehlschlägt.

• Mögliche Ursache: Das Importieren einer Zuordnungsdatei, die doppelte Knoten zum Zielschema hinzugefügt hat, hat die entsprechende Änderung an der Schemadefinition, die bei der Ausführung des Vorgangs verwendet wird, nicht angewendet, wodurch die beiden nicht mehr synchron sind. Dies wurde behoben, aber eine Transformation, deren Zuordnung vor der Behebung importiert wurde, kann weiterhin betroffen sein.

• Lösung: Verwenden Sie in der betroffenen Transformation Alle Zuordnungen unter diesem Knoten entfernen auf dem Stammknoten, um alle Zuordnungen zu entfernen, und importieren Sie die Zuordnungsdatei erneut. Das erneute Importieren synchronisiert die bei der Laufzeit verwendete Schemadefinition mit der Zuordnung. Wenn der Fehler weiterhin besteht, konfigurieren Sie die Aktivität neu, die das Schema bereitstellt, und aktualisieren Sie das Schema in der Transformation.

Erneute Verarbeitung von gespiegelten XML-Schemas in Projekten, die vor Version 10.25 erstellt wurden

• Symptom: Aufgrund von Änderungen in den Harmony-Versionen 10.25 und 10.27 können Projekte, die vor 10.25 erstellt wurden und gespiegelte XML-Schemas verwenden, sich anders als erwartet verhalten. Zuordnungen, die XML-Funktionen mit Namespaces (wie SelectNodes) verwendet haben, können jetzt ungültig sein.

  Der Unterschied liegt in der Namespace-Präfix-Behandlung:

  • Vor 10.25: Gespiegelte XML-Schemas verwendeten das Standard-Namespace-Präfix xsi.
  • 10.25 und später: Gespiegelte XML-Schemas verwenden das qualifizierte Namespace-Präfix ns. Nicht zugeordnete Felder werden im Schema nicht angezeigt.

• Lösung: Ab Version 10.27 behält das Importieren eines Projekts, dessen gespiegelte XML-Schemas vor 10.25 erstellt wurden, das ursprüngliche Namespace-Präfix bei, sodass das Schema mit dem Zeitpunkt der Erstellung identisch ist. Um ein Update auf das aktuelle Namespace-Präfix zu erzwingen, generieren Sie das Schema neu, indem Sie es aktualisieren oder die Aktivität, die es bereitstellt, neu konfigurieren. Überprüfen Sie nach der erneuten Generierung alle betroffenen XML-Namespace-Funktionsaufrufe und aktualisieren Sie die Präfix-Verweise entsprechend.

  Siehe den kommentierten XML-Schema-Vergleich für eine Illustration des Unterschieds zwischen den beiden Formaten.

Warnung zu zusätzlichen Unterelementen in Operationsprotokollen

• Symptom: Eine extra subelement-Meldung in den Operationsprotokollen ist eine Warnung, keine Fehlermeldung, und kann in der Regel ignoriert werden. Sie zeigt an, dass die API-Nutzlast eines Connectors mehr Knoten oder Felder zurückgegeben hat, als im Antwort-Datenschema definiert sind.
• Lösung: Wenn Sie die zusätzlichen Daten erfassen müssen, aktualisieren Sie das Schema, um die zusätzlichen Felder einzubeziehen.

Transformationsausgabe für Zielfelder mit dem Datentyp double in 0 konvertiert

• Symptom: Ein Zielfeld mit dem Datentyp double im Schema erhält den Wert 0, obwohl das Mapping-Skript einen nicht-leeren Zeichenfolgenwert zurückgibt.
• Mögliche Ursache: Wenn die Transformation eine Skriptausgabe verarbeitet, wird das Ergebnis in den Datentyp des Zielfelds konvertiert. Wenn der Zeichenfolgenwert mit einem Nicht-Ziffern-Zeichen beginnt (z. B. "string1"), kann kein numerischer Teil extrahiert werden und das Feld erhält den Standard-Zahlenwert 0. Im Gegensatz dazu würde ein Wert wie "1string" 1 ergeben, da die führende Ziffer übernommen wird.
• Lösung:
  1. Überprüfen Sie die Schemadefinition für das betroffene Zielfeld und bestätigen Sie, ob sein Datentyp double oder ein anderer numerischer Datentyp ist.
  2. Wenn das Mapping-Skript eine nicht-numerische Zeichenfolge zurückgeben kann, fügen Sie eine explizite Validierung hinzu, um sicherzustellen, dass nur numerische Werte auf numerische Zielfelder abgebildet werden, oder ändern Sie den Datentyp des Felds im Schema.

Leere zugeordnete Felder mit flachen Quellschemas

• Symptom: Zielfelder erscheinen in der Operationsausgabe leer, obwohl die Quelldaten Werte enthalten. Dieses Problem tritt speziell bei Verwendung eines flachen Quellschemas auf. Es tritt nicht bei gespiegelten Schemas oder JSON-Schemas auf.
• Mögliche Ursache: Der Standard-Streaming-Transformationsmodus verarbeitet Datensätze inkrementell, was dazu führen kann, dass zugeordnete Felder bei Verwendung mit flachen Quellschemas keine Werte erhalten.

• Lösung:

  1. Fügen Sie einen Skriptschritt am Anfang der Operation hinzu, der Streaming-Transformationen deaktiviert, indem Sie jitterbit.transformation.auto_streaming auf false setzen:

     $jitterbit.transformation.auto_streaming = false;
     

  2. Stellen Sie die Operation bereit und führen Sie sie erneut aus. Weitere Informationen zu Streaming und Transformationsverarbeitung finden Sie unter Transformationsverarbeitung.

Zielschleifenknoten, der mehreren Quellschleifenknoten zugeordnet ist

• Symptom: Eine Transformation ist ungültig oder kann nicht bereitgestellt werden mit:

  Mappings of a target loop node depend on more than one source loop node.
  

• Mögliche Ursache: Ein Zielschleifenknoten hat Feldmappings, die auf zwei oder mehr verschiedene Quellschleifenknoten verweisen. Jeder Zielschleifenknoten kann nur über einen einzelnen Quellschleifenknoten iterieren.

• Lösung:
  1. Öffnen Sie die Transformation und identifizieren Sie den Zielschleifenknoten, der im Fehler gekennzeichnet ist.
  2. Überprüfen Sie die Mappings unter diesem Knoten, um zu bestätigen, dass alle zugeordneten Felder vom gleichen Quellschleifenknoten stammen.
  3. Wenn Daten aus mehreren Quellknoten erforderlich sind, verarbeiten oder führen Sie die zusätzlichen Quelldaten in einem Skriptschritt vor der Transformation vor, damit ein einzelner einheitlicher Quellknoten das Zielschleifenknoten speist.
  4. Weitere Details zu gültigen Mapping-Mustern finden Sie unter Transformations-Mapping-Gültigkeit.

Transformation verwirft doppelte Datensätze, wenn die Ausgabe hierarchisch ist

• Symptom: Eine Transformation, die eine CSV-Quelle liest und auf ein hierarchisches Ausgabeformat (z. B. JSON) abbildet, verwirft stillschweigend doppelte Datensätze. Datensätze mit identischen Feldwerten erscheinen nur einmal in der Ausgabe, unabhängig davon, wie oft sie in der Quelle vorkommen. Die Operation wird erfolgreich abgeschlossen, meldet aber weniger Zieldatensätze als Quelldatensätze.
• Mögliche Ursachen:
  • Bei der Konvertierung flacher Quelldaten in ein hierarchisches Ausgabeformat entfernt die Transformations-Engine während der Normalisierung doppelte Datensätze. Datensätze mit identischen Werten nach dem Parsing werden als Duplikate behandelt und nur eine Kopie wird beibehalten.
  • Dieses Verhalten ist spezifisch für hierarchische Ausgaben. Wenn das Ausgabeschema flach ist, wird die Normalisierung nicht ausgeführt und alle Datensätze werden geschrieben.
  • Die Transformations-Engine schneidet auch standardmäßig führende und nachfolgende Leerzeichen von CSV-Feldwerten ab. Datensätze, die sich nur durch führende oder nachfolgende Leerzeichen unterscheiden, werden nach dem Trimmen identisch und unterliegen der gleichen Deduplizierung.
• Lösung:
  • Aktivieren Sie Chunking in den Operationsoptionen. Chunking verarbeitet Datensätze in Batches, wodurch die Normalisierung umgangen wird und alle Datensätze einschließlich Duplikate beibehalten werden.
  • Verwenden Sie ein flaches Ausgabeschema in der Transformation anstelle eines hierarchischen. Die Normalisierung gilt nicht für flache Ausgaben, daher werden alle Datensätze beibehalten.
  • Deaktivieren Sie die Normalisierung, indem Sie eine Jitterbit-Variable in einem Skriptschritt vor der Transformation setzen. Setzen Sie für Flat-to-Flat-Transformationen jitterbit.transformation.disable_normalization auf true. Setzen Sie für Flat-to-XML-Transformationen jitterbit.transformation.flat_to_xml.disable_normalization auf true (erfordert Agent 11.58 oder später). Beide Variablen können andere Transformationen in der gleichen Operation beeinflussen, daher testen Sie die Änderung sorgfältig.
  • Wenn die Duplikate speziell durch Leerzeichen-Unterschiede verursacht werden, setzen Sie jitterbit.source.preserve_char_whitespace auf true in einem Skriptschritt vor der Transformation. Dies bewahrt Leerzeichen während des Parsing, sodass betroffene Datensätze unterschiedlich bleiben.

Lange numerische IDs werden in der Transformationsausgabe beschädigt

• Symptom: Ein langer numerischer Wert (z. B. eine Verfolgungsnummer, Kontonummer oder externe ID) wird mit dem falschen Wert an das Ziel gesendet. Die Zahl ist zu groß, um in den impliziten numerischen Typ zu passen, der während der Zuordnung verwendet wird, sodass ein Überlauf auftritt und ein falscher Wert am Ziel erzeugt wird.
• Mögliche Ursache: Das Quell- oder Zielfeld ist implizit als numerischer Datentyp typisiert, dessen Bereich den vollständigen Wert nicht halten kann, was zu einem Überlauf während der Konvertierung führt.
• Lösung:
  • Legen Sie in der Transformation den Datentyp des betroffenen Zielfelds auf String statt auf einen numerischen Typ fest. Lange IDs, die nicht in arithmetischen Operationen verwendet werden, sollten als Strings behandelt werden.

  • Wenn das Quellfeld auch numerisch typisiert ist, konvertieren Sie den Wert explizit mit String vor der Zuordnung:

    String($source.numericId)
    

JSON-Transformationsausgabe lässt null- und leere String-Felder weg

• Symptom: Eine JSON-Transformation entfernt Felder mit dem Wert null oder einer leeren Zeichenkette ("") aus der Ausgabe-Payload, obwohl diese Felder explizit zugeordnet sind. Das Zielsystem erhält eine Payload, die die weggelassenen Felder nicht enthält, was zu Validierungsfehlern nachgelagerter Systeme führen kann, wenn das Ziel die Anwesenheit der Felder erfordert.
• Mögliche Ursache: Der JSON-Ausgabeprozessor lässt Felder mit null- oder leeren String-Werten standardmäßig weg.
• Lösung:
  • Legen Sie in einem Skriptschritt vor der Transformation jitterbit.target.xml.include_nil_attribute auf true fest. Bei Agent-Version 11.37 oder später werden null-Werte und leere Strings in der JSON-Ausgabe einbezogen, was der Eingabe entspricht. (Trotz des xml im Namen gilt diese Variable für JSON-Ziele.)
  • Wenn Sie vollständige Kontrolle darüber benötigen, welche Felder in der Payload angezeigt werden, erstellen Sie den JSON-Body in einem Skriptschritt mit Zeichenkettenverkettung und senden Sie ihn über einen HTTP v2-Connector mit einem Request-Body ohne Schema.

Leere zugeordnete Felder werden zu xsi:nil="true" und machen eine XML- oder SOAP-Anfrage ungültig

• Symptom: In einer XML- oder SOAP-Transformation wird ein zugeordnetes Feld mit einem leeren Wert als nil-Element ausgegeben, und der Ziel-Endpunkt lehnt die Anfrage ab. Beispielsweise erzeugt eine leere Telefonnummernzuordnung:

  <ns1:Phone_Number xsi:nil="true"/>
  

  Einige Endpunkte (z. B. Workday SOAP-Services) behandeln dies als ungültig und geben einen Fehler zurück.

• Ursache: Standardmäßig wird bei einer Zuordnung zu einem Zielknoten, die zu einem Null- oder leeren Wert führt, der Knoten in die Transformation einbezogen, aber als nil markiert (xsi:nil="true"). Dies wird durch jitterbit.target.xml.include_null_xml gesteuert, dessen Standardwert true ist.

• Lösung: Legen Sie in einem Skriptschritt vor der Transformation $jitterbit.target.xml.include_null_xml = false fest, um Knoten mit einem Null- oder leeren Wert vollständig aus der Ausgabe zu entfernen. Wenn der Knoten stattdessen als leeres Element vorhanden sein muss, verwenden Sie die zugehörigen Ziel-Jitterbit-Variablen jitterbit.target.xml.include_empty_xml und jitterbit.target.xml.include_nil_attribute, die steuern, ob leere und Null-Werte in der Ausgabe einbezogen werden.

Byte-Order-Marke (BOM) in einer Quelldatei wird an den Wert des ersten Datensatzes weitergeleitet

• Symptom: Wenn eine Quelldatei (z. B. eine CSV-Datei) mit einer UTF-8-Byte-Order-Marke (BOM) beginnt, enthält das erste Feld des ersten Datensatzes in der Transformationsausgabe ein zusätzliches oder unerwartetes Zeichen, das nicht Teil der Quelldaten ist, anstelle des erwarteten Werts. Dateien, die als UTF-8-CSV aus Microsoft Excel exportiert werden, enthalten häufig diese BOM.
• Mögliche Ursache: Studio liest den Inhalt einer Quelldatei unverändert und erkennt oder entfernt eine führende BOM nicht. Die Rohdaten der BOM werden Teil des Werts des ersten Felds, sobald die Datei in Datensätze analysiert wird.
• Lösung: Überprüfen Sie den Wert des betroffenen Felds, um die genauen Zeichen zu identifizieren, die von der BOM erzeugt werden, und ordnen Sie das Feld dann mit Replace zu, um diese zu entfernen. Bei Agent-Version 12.6 oder früher, wo UTF-8 nicht die Standardeinstellung ist, können Sie auch die Zeichenkodierung explizit auf UTF-8 setzen, bevor die Quellaktivität ausgeführt wird, z. B. $jitterbit.source.text.character_encoding = "utf-8";. Agent-Version 12.7 und später verwenden standardmäßig UTF-8.

Skript- und Funktionsfehler

Dateifunktionen: Vorgang wird nach ArchiveFile- oder ReadFile-Fehler fortgesetzt

• Symptom: Ein Vorgang wird mit erfolgreichem Status abgeschlossen, aber Dateien wurden nicht archiviert oder Daten wurden nicht wie erwartet gelesen. Im Vorgangsergebnis wird kein Fehler angezeigt, nur eine Warnung im Vorgangsprotokoll.
• Mögliche Ursache: ArchiveFile und ReadFile haben ein Soft-Failure-Verhalten: Wenn eine dieser Funktionen fehlschlägt, wird das aktuelle Skript abgebrochen und eine Warnung zum Vorgangsprotokoll hinzugefügt, aber der Vorgang selbst schlägt nicht fehl und nachfolgende Schritte werden fortgesetzt. Ab Agent-Version 12.5 gibt es eine Ausnahme: ArchiveFile mit deleteSource auf true gesetzt wirft einen abfangbaren Fehler, wenn die Quelldatei nicht gelöscht werden kann, anstatt stillschweigend fehlzuschlagen.
• Lösung:
  • Überprüfen Sie die Vorgangsprotokolle auf Warnmeldungen, wenn ein Vorgang erfolgreich ist, aber die erwartete Dateiausgabe fehlt.
  • Wenn das Skript bei einem Dateifunktionsfehler beendet werden muss, umhüllen Sie den Aufruf mit einer Eval-Funktion und rufen Sie RaiseError explizit auf, um die Warnung zu einem Vorgangsfehler zu erheben.

ReadFile: Teilweise Lesevorgänge mit binärem Dateiinhalt

• Symptom: Ein Skript, das ReadFile zum Lesen einer Binärdatei (z. B. ZIP oder PDF) verwendet, gibt unvollständige oder beschädigte Daten zurück.
• Mögliche Ursache: ReadFile ist bei Binärdateiinhalten nicht zuverlässig und liest normalerweise nur einen Teil solcher Dateien.
• Lösung: Verwenden Sie stattdessen Base64EncodeFile anstelle von ReadFile, um den vollständigen Inhalt einer Binärdatei als Base64-codierte Zeichenfolge zu lesen.

ReadFile-Inhalt mit Nicht-UTF-8-Bytes schlägt fehl, wenn er in eine UTF-8-XML- oder JSON-Nutzlast zugeordnet wird

• Symptom: Eine Transformation, die Rohdateiinhalte, die mit ReadFile gelesen werden (z. B. eine Raw-EDI-Datei), in ein UTF-8-XML- oder JSON-Zielfeld abbildet, schlägt während der XML- oder JSON-Konvertierung fehl. Das Ersetzen des abgebildeten Werts durch eine hartcodierte Zeichenkette ermöglicht den Abschluss des Vorgangs, was bestätigt, dass der Rohinhalte der Auslöser ist. Versuche, das problematische Zeichen mithilfe seines Unicode-Codepunkts zu entfernen (z. B. Replace($readFile, HexToString("2026"), "~") für die Ellipse U+2026), stimmen nicht überein, und das Aufrufen von StringToHex für den Inhalt mit aktivierter Unicode-Unterstützung wirft:

  not a UTF-8 string, byte not in range: 13
  

• Ursache: Der Dateiinhalt enthält ein Byte, das nicht gültig UTF-8 ist (z. B. das einzelne Byte 0x85, das einige EDI-Dateien als Segmenttrennzeichen verwenden). Dieses Rohe Byte ist nicht dasselbe wie die Multi-Byte-UTF-8-Codierung eines ähnlich aussehenden Unicode-Zeichens (die Ellipse U+2026 wird als drei Bytes codiert), daher stimmt ein Ersatz, der auf den Unicode-Codepunkt abzielt, nie überein. Wenn jitterbit.scripting.hex.enable_unicode_support auf true gesetzt ist, interpretieren die Hex-Funktionen den Inhalt als UTF-8 und schlagen beim ungültigen Byte fehl.

• Lösung: Stimmen Sie das Rohe Byte ab und ersetzen Sie es mit deaktivierter Unicode-Hex-Unterstützung, damit HexToString auf Rohe Bytes statt auf UTF-8-Zeichen arbeitet:

  $jitterbit.scripting.hex.enable_unicode_support = false;
  $badByte = HexToString("85");
  $readFile = Replace($readFile, $badByte, "~");
  

  Passen Sie den Hex-Wert (85) an das Byte an, das von StringToHex($readFile) gemeldet wird, und die Ersatzzeichenkette (~) nach Bedarf an, und bilden Sie dann den bereinigten Wert ab.

FlushFile / FlushAllFiles: Fehler, wenn Zieldatei bereits vorhanden ist

• Symptom: Ein Skript schlägt fehl, wenn versucht wird, eine Datei in ein Ziel zu schreiben, das bereits eine Datei mit demselben Namen enthält.
• Mögliche Ursache: FlushFile und FlushAllFiles (und damit auch ArchiveFile) werfen einen Fehler, wenn eine Datei mit dem Zielnamen bereits am Ziel vorhanden ist.
• Lösung:
  • Fügen Sie einen DeleteFile- oder DeleteFiles-Aufruf vor dem Schreibvorgang hinzu, um die vorhandene Datei zu entfernen.
  • Verwenden Sie alternativ einen dynamischen Dateinamen, der einen Zeitstempel oder eine eindeutige Kennung enthält, um Kollisionen zu vermeiden.

DeleteFiles: Fehler, wenn Quellpfad nicht gefunden werden kann

• Symptom: Ein Skript, das DeleteFiles verwendet, schlägt mit einem Fehler fehl, wenn der angegebene Quellpfad oder das Verzeichnis nicht gefunden werden kann. (Ein Filter, der keine Dateien abgleicht, gibt 0 statt eines Fehlers zurück.)
• Mögliche Ursache: Wenn der Quellpfad nicht gefunden werden kann, wirft DeleteFiles einen Fehler statt stillschweigend zurückzukehren. Dies kann zu unerwarteten Operationsfehlern führen, wenn die zu löschende Datei nicht vorhanden ist.
• Lösung: Umhüllen Sie den DeleteFiles-Aufruf mit einer Eval-Funktion, um den Fehler abzufangen und ihn zu behandeln, ohne den Vorgang fehlschlagen zu lassen.

GetJSONString: Ausführung bei ungültigem Pfad unterbrochen

• Symptom: Ein Skript, das GetJSONString aufruft, schlägt fehl, wenn der angegebene Pfad nicht im JSON aufgelöst wird (z. B. der Knoten fehlt oder ein Array ist leer). Die Fehlermeldung ist generisch und identifiziert den Pfad nicht als Ursache. Wenn der Vorgang über eine API aufgerufen wird, kann dies als irreführender Proxy Error [502] an den API-Aufrufer zurückgegeben werden.
• Mögliche Ursache: Wenn das an GetJSONString übergebene Argument path ungültig ist oder keine Daten entsprechen, unterbricht die Funktion sofort den Ausführungsfluss und gibt einen Fehler zurück, der zum Abbruch des gesamten Skripts führen kann.
• Lösung:
  • Validieren Sie den JSON-Pfad vor der Übergabe an GetJSONString, oder verwenden Sie (ab Agent-Version 11.59 / 12.3) GetJSONStringEx, das einen anpassbaren Wert zurückgibt, anstatt die Ausführung zu unterbrechen, wenn der Pfad ungültig oder nicht vorhanden ist.
  • Protokollieren Sie die JSON-Nutzlast unmittelbar vor dem GetJSONString-Aufruf, um die tatsächliche Struktur zu überprüfen und den Pfad zu bestätigen.

Iterationslimit der Skriptschleife überschritten

• Symptom: Ein Skript schlägt mit einer Fehlermeldung fehl, die angibt, dass die maximale Anzahl von Schleifeniterationen erreicht wurde. Das Standardlimit beträgt 50.000 Iterationen.
• Mögliche Ursachen:
  • Eine Schleife in einem Jitterbit-Skript überschreitet das Iterationslimit der Plattform.
  • Ein JavaScript-Skript enthält mehrere Schleifen, deren kombinierte Iterationszahlen 50.000 überschreiten. In JavaScript gilt das Limit pro Skript (über alle Schleifen hinweg), nicht pro einzelner Schleife.
• Lösung:
  • Überprüfen Sie die Skriptlogik, um festzustellen, ob die Schleife optimiert werden kann, um die Anzahl der Iterationen zu reduzieren.
  • Für JavaScript-Skripte auf privaten Agents kann das Pro-Skript-Limit erhöht werden, indem JavaScriptMaxIterations=X (wobei X größer als 50000 ist) zum Abschnitt [Settings] der Konfigurationsdatei des privaten Agents hinzugefügt wird.
  • Für Jitterbit Script auf privaten Agents erhöhen Sie das Limit, indem Sie jitterbit.scripting.while.max_iterations auf einen Wert größer als 50000 setzen.

Vergleich einer Zeichenkette mit einer Zahl liefert unerwartete Ergebnisse

• Symptom: Ein Vergleich zwischen einer Zeichenkette und einer Zahl liefert ein unerwartetes Ergebnis. Beispielsweise wird der Vergleich einer nicht-numerischen Zeichenkette mit 0 als gleich ausgewertet, sodass der falsche Zweig ausgeführt wird:

  $value = "test";
  If($value == 0, WriteToOperationLog("equal"), WriteToOperationLog("not equal"));
  // logs "equal", even though "test" is not 0
  

• Ursache: Wenn die beiden Operanden unterschiedliche Typen haben, konvertiert Jitterbit Script beide in Zahlen, um sie zu vergleichen. Eine Zeichenkette, die keine Zahl darstellt, wird in 0 konvertiert, sodass "test" == 0 zu 0 == 0 wird, was true ist. Dies ist das erwartete Verhalten.

• Lösung: Vergleichen Sie Werte desselben Typs. Um eine Zeichenkette gegen einen bestimmten Wert zu testen, vergleichen Sie sie mit einem Zeichenkettenliteral (z. B. $value == "0" oder $value == ""), anstatt mit einer Zahl. Wenn ein Wert als beide Typen ankommen kann, konvertieren Sie beide Operanden vor dem Vergleich in denselben Typ (z. B. mit String).

Unmap hebt die Zuordnung eines Feldes nicht auf, wenn es zusammen mit RunScript verwendet wird

• Symptom: Der Zuordnungsausdruck eines Zielfeldes umfasst sowohl RunScript als auch Unmap, aber das Feld wird nicht aufgehoben. Bei einem JSON- oder XML-Ziel erscheint das Feld in der Ausgabe mit einem null-Wert, anstatt weggelassen zu werden.

• Mögliche Ursachen:

  • RunScript steht vor Unmap im selben Zuordnungsausdruck (z. B. RunScript("<TAG>script:MyScript</TAG>"); Unmap();). Bei Agent-Versionen vor 12.9 hob diese Kombination das Feld nicht auf.
  • Unmap wird aus dem von RunScript aufgerufenen Skript aufgerufen, anstatt direkt im eigenen Zuordnungsausdruck des Zielfeldes. RunScript gibt das Ergebnis des aufgerufenen Skripts als Zeichenkette zurück, anstatt ein Unmap-Signal zurück zur Zuordnung zu propagieren. Das Aufrufen von Unmap aus dem aufgerufenen Skript hat daher keine Auswirkung, unabhängig von der Agent-Version und unabhängig von bedingter Logik um den Aufruf. Dies ist das erwartete Verhalten.

• Lösung:

  • Wenn RunScript und Unmap beide direkt im Zuordnungsausdruck des Zielfeldes aufgerufen werden, führen Sie ein Upgrade auf Agent-Version 12.9 oder später durch.

  • Wenn Unmap aus dem von RunScript aufgerufenen Skript aufgerufen wird, verschieben Sie den Unmap-Aufruf aus dem aufgerufenen Skript in den eigenen Zuordnungsausdruck des Zielfeldes, z. B.:

    RunScript("<TAG>script:MyScript</TAG>"); If(<condition>, Unmap(), <value>);
    

DBExecute: Fehler, wenn auto_commit und transaction beide true sind

• Symptom: Ein Vorgang mit DBExecute schlägt mit einem Fehler fehl, der sich auf widersprüchliche Transaktionseinstellungen bezieht.
• Mögliche Ursache: Sowohl jitterbit.scripting.db.auto_commit als auch jitterbit.scripting.db.transaction sind im Skript vor dem DBExecute-Aufruf auf true gesetzt. Diese beiden Einstellungen schließen sich gegenseitig aus, und ihre Kombination führt zu einem Fehler.
• Lösung: Entscheiden Sie, ob Sie Auto-Commit-Verhalten oder explizite Transaktionskontrolle benötigen, und setzen Sie dann nur die entsprechende Variable:
  • Für Auto-Commit (jede Anweisung wird sofort bestätigt): setzen Sie $jitterbit.scripting.db.auto_commit = true und lassen Sie jitterbit.scripting.db.transaction nicht gesetzt oder false.
  • Für Transaktionskontrolle (Bestätigung am Ende der Transformation): setzen Sie $jitterbit.scripting.db.transaction = true und jitterbit.scripting.db.auto_commit = false.

CallStoredProcedure: resultSet immer null mit ODBC-Treibern

• Symptom: Ein Skript mit CallStoredProcedure gibt null für den Parameter resultSet zurück, obwohl die gespeicherte Prozedur Daten zurückgibt.
• Mögliche Ursache: Der Parameter resultSet wird nur von JDBC-Datenbanktreibern unterstützt. Wenn der Datenbankendpunkt einen ODBC-Treiber verwendet, ist resultSet immer null, unabhängig davon, was die gespeicherte Prozedur zurückgibt.
• Lösung:
  • Wenn das Resultset der gespeicherten Prozedur erforderlich ist, wechseln Sie den Datenbankendpunkt so, dass er einen JDBC-Treiber anstelle von ODBC verwendet.
  • Wenn ein Treiberwechsel nicht möglich ist, rufen Sie Ausgabedaten über Ausgabeparameter anstelle des Arguments resultSet ab.

CallStoredProcedure: "Stored proc or function could not be found" mit PostgreSQL JDBC

• Symptom: Ein Skript mit CallStoredProcedure gegen eine PostgreSQL-Datenbank schlägt fehl mit:

  CallStoredProcedure failed to execute call "<function-name>".
  java.sql.SQLException: Stored proc or function could not be found: <function-name>
  

• Mögliche Ursache: Der PostgreSQL JDBC-Treiber unterscheidet zwischen Funktionen und Prozeduren. CallStoredProcedure erstellt seinen Aufruf immer nach einem Muster, das der Treiber als Suche nach einer Prozedur interpretiert. Wenn das Datenbankobjekt eine PostgreSQL-Funktion statt einer Prozedur ist, kann der Treiber es nicht finden und gibt die Fehlermeldung „nicht gefunden" zurück.

• Lösung:
  1. Bestimmen Sie, ob das aufgerufene Datenbankobjekt eine PostgreSQL-Funktion (gibt einen Wert zurück) oder eine Prozedur (kein Rückgabewert) ist.

  2. Ersetzen Sie CallStoredProcedure durch DBExecute und verwenden Sie die korrekte SQL-Syntax für den Objekttyp:

     • Funktion: verwenden Sie SELECT.

       $result = DBExecute("<TAG>Sources/My DB Connection</TAG>", "SELECT my_function(arg1, arg2)");
       

       DBExecute gibt ein Resultset zurück. Verwenden Sie eine While-Schleife mit Get, um die zurückgegebenen Werte zu lesen.

     • Prozedur: verwenden Sie CALL.

       DBExecute("<TAG>Sources/My DB Connection</TAG>", "CALL my_procedure(arg1, arg2)");
       

       PostgreSQL-Prozeduren geben keinen Wert zurück; der Rückgabewert von DBExecute kann verworfen werden.

DBLoad: Erfordert einen JDBC-Datenbanktreiber

• Symptom: Ein Vorgang mit DBLoad schlägt fehl oder erzeugt keine Ausgabe, wenn der Database-Endpunkt einen ODBC-Treiber verwendet.
• Mögliche Ursache: DBLoad funktioniert nur mit Database-Endpunkten, die für die Verwendung eines JDBC-Treibers konfiguriert sind. Es wird nicht mit ODBC-Treibern unterstützt.
• Lösung: Bestätigen Sie, dass der Database-Endpunkt, der der Zielaktivität zugeordnet ist, einen JDBC-Treiber verwendet. Wenn er einen ODBC-Treiber verwendet, wechseln Sie zu JDBC.

AESDecryption schlägt bei mit OpenSSL 3 verschlüsselten Daten fehl

• Symptom: Ein Vorgang mit AESDecryption schlägt fehl oder gibt verwirrte Ausgabe zurück, wenn Daten entschlüsselt werden, die mit OpenSSL 3 verschlüsselt wurden.
• Mögliche Ursache: AESDecryption verwendet standardmäßig einen älteren AES-Algorithmus, der nicht mit OpenSSL 3-Verschlüsselung kompatibel ist. Wenn die verschlüsselten Daten mit OpenSSL 3 erstellt wurden, schlägt die Entschlüsselung ohne zusätzliche Konfiguration fehl.
• Lösung:
  • Für Private Agents Version 11.42 oder später setzen Sie jitterbit.scripting.aes.default in einem Skriptschritt vor dem AESDecryption-Aufruf auf true, um die OpenSSL 3-Kompatibilität zu aktivieren.
  • Alternativ ersetzen Sie AESDecryption durch AESDecryptionEx, das OpenSSL 3 standardmäßig auf Agent-Versionen 11.42 oder später unterstützt.

Projektvariablen geben während Skript- und Transformationstests leere Werte zurück

• Symptom: Beim Testen eines Skriptschritts oder einer Transformation in Studio gibt eine Projektvariable, auf die im Skript oder in der Zuordnung verwiesen wird, einen leeren Wert statt des konfigurierten Werts zurück. Der Test kann mit einem Fehler fehlschlagen, der nicht mit der Variablen selbst zusammenhängt (z. B. ein Verbindungszeitüberschreitung aufgrund einer leeren Serveradresse).
• Mögliche Ursache: Projektvariablenwerte werden zur Laufzeit von der Harmony-Plattform eingefügt. Während eines Designzeit-Tests existiert kein Laufzeitkontext, um diesen Wert einzufügen. Daher gibt ein Projektvariablenverweis einen leeren Wert zurück, es sei denn, die Variable hat einen konfigurierten Standardwert als Fallback.
• Lösung:
  • Legen Sie einen Standardwert für die Projektvariable fest: Geben Sie in der Projektvariablenkonfiguration den Wert, der während des Tests verwendet werden soll, im Feld Standardwert ein. Dies ist die einfachste Lösung für einen statisch konfigurierten Wert. Beachten Sie, dass der Standardwert verwendet wird, wenn die Variable zur Laufzeit nicht gesetzt wurde (nicht nur während Designzeit-Tests). Zur Laufzeit fungiert er auch als Fallback, wenn die Variable anderweitig nicht gesetzt ist. Weitere Informationen zur Konfiguration finden Sie unter Projektvariablen.
  • Verwenden Sie eine globale Variable: Ersetzen Sie den Projektvariablenverweis durch eine globale Variable und weisen Sie deren Wert im Skript selbst vor der Zeile zu, die sie verwendet. Da eine globale Variable ihren Wert aus der Skriptausführung statt aus der Laufzeiteinspeisung erhält, macht das Zuweisen vor der Verwendung sie während eines Designzeit-Tests verfügbar. Verwenden Sie dies, wenn der Wert in einem Skript abgeleitet wird oder wenn Sie keinen Laufzeit-Fallback-Wert möchten. Weitere Informationen finden Sie unter Globale Variablen. Wenn auf die globale Variable in einem Connector-Konfigurationsfeld statt direkt in einem Skript verwiesen wird, müssen Sie auch einen feldspezifischen Standardwert für dieses Feld definieren (siehe Standardwert definieren, das sowohl die Variablenpillen-Methode als auch die Inline-Syntax-Methode für Felder ohne Pillen abdeckt).

IsNull gibt „false" für leere Strings aus JSON-Quelldaten zurück

• Symptom: IsNull gibt false für ein Feld zurück, das aus einer JSON-Quelle zugeordnet ist, auch wenn das Feld keinen Wert zu haben scheint. Nachgelagerte Logik, die vom Null-Check abhängt, verhält sich unerwartet oder erzeugt falsche Ergebnisse.
• Mögliche Ursache: JSON unterscheidet zwischen einem fehlenden oder expliziten null-Wert und einem leeren String (""). Ein Feld, das in JSON auf "" gesetzt ist, ist ein leerer String, kein Null-Wert. Daher gibt IsNull korrekt false dafür zurück. Ab Agent 11.37 behält der Agent diese Unterscheidung genau bei. Skripte oder Transformationen, die sich früher darauf verlassen haben, dass IsNull für leere Strings true zurückgibt, hingen von früherem Verhalten ab, das nicht mehr korrekt ist.

• Lösung:

  • Verwenden Sie IfEmpty, um sowohl Null als auch leere Strings zu verarbeiten: Die Funktion IfEmpty gibt einen Standardwert zurück, wenn das Argument null oder ein leerer String ist, und ist die empfohlene Ersetzung für dieses Szenario:

    // Gibt "default" zurück, wenn das Feld null oder ein leerer String ist
    result = IfEmpty($myField, "default");
    

  • Verwenden Sie Length, um explizit auf leere Strings zu prüfen: Wenn Sie nur prüfen müssen, ob ein String leer ist (nicht null), verwenden Sie Length($myField) == 0.

  • Beheben Sie die Quelldaten: Wenn die JSON-Quelle keinen Wert angeben soll, aktualisieren Sie sie so, dass sie "field": null sendet oder das Feld ganz weglässt, statt "field": "".

Der Vergleich einer Stringvariablen mit der Zahl 0 gibt unerwartet true zurück

• Symptom: Ein Vergleich wie $myVar == 0 gibt true zurück, auch wenn $myVar einen nicht-numerischen String enthält (z. B. "test"). If-Bedingungen und andere Logik, die auf Null prüft, erzeugen unerwartete Ergebnisse.
• Mögliche Ursache: Wenn Jitterbit Script Werte verschiedener Datentypen vergleicht, versucht es, beide Operanden als letzten Schritt in Doubles zu konvertieren. Bei Anwendung auf einen nicht-numerischen String schlägt die Konvertierung fehl und gibt 0 als Standardwert zurück. Der Vergleich wird dann als 0 == 0 ausgewertet, was true ist.
• Lösung:
  • Stellen Sie sicher, dass beide Seiten des Vergleichs denselben Datentyp verwenden. Wenn die Absicht darin besteht zu prüfen, ob eine Stringvariable den Wert "0" enthält, vergleichen Sie mit dem String-Literal "0" statt mit der Ganzzahl 0:

// Compares string to integer: non-numeric strings coerce to 0 and match unexpectedly
        If($myVar == 0, ...)

        // Compares string to string: behaves as expected
        If($myVar == "0", ...)

• Wenn die Variable einen numerischen Wert enthalten soll, stellen Sie sicher, dass sie vor dem Vergleich als Zahl und nicht als Zeichenkette zugewiesen wird.

Dezimalarithmetik erzeugt unerwartete Gleitkommawerte

• Symptom: Ein arithmetischer Ausdruck mit Dezimalliteralen erzeugt ein Ergebnis, das leicht vom erwarteten Wert abweicht. Beispielsweise gibt Double(12.01) - Double(12.00) statt 0.01 den Wert 0.00999999999999979 zurück, und (4.9 * 100) - 490 ergibt statt 0 den Wert 5.6843418860808e-14.
• Mögliche Ursache: Jitterbit Script speichert Zahlen als Gleitkommawerte. Die meisten Dezimalbrüche können in binärer Gleitkommadarstellung nicht exakt dargestellt werden, daher können arithmetische Operationen kleine Rundungsfehler ansammeln. Subtraktionen, die den Großteil eines Wertes aufheben, machen diesen Rest sichtbar. Das explizite Umwandeln von Werten als Double verhindert dies nicht: Es gibt den Datentyp an, ändert aber nicht, wie der Wert gespeichert oder berechnet wird.

• Lösung:

  • Wenden Sie Round auf das Ergebnis an: Verwenden Sie Round mit der für die Berechnung erforderlichen Anzahl von Dezimalstellen:

    $a = Round(Double(12.01) - Double(12.00), 2); // returns 0.01
    

  • Wandeln Sie Dezimalliterale mit Float um: Umhüllen Sie das Dezimalliteral mit Float vor der Berechnung:

    $a = (Float(4.9) * 100) - 490;
    WriteToOperationLog($a);
    

Datumsfunktionen geben Mitternacht statt eines reinen Datumswerts zurück

• Symptom: Nach dem Upgrade auf Agent-Version 12.8 oder später geben ConvertTimeZone, Date oder GeneralDate für eine Eingabe von genau Mitternacht eine vollständige Datums- und Zeitzeichenkette zurück (z. B. 2026-01-01 00:00:00) statt einer reinen Datumszeichenkette (2026-01-01), was die nachgelagerte Logik unterbrechen kann, die das kürzere Format erwartet. CVTDate ist nicht betroffen.
• Mögliche Ursache: Bei Agent-Version 12.8 und später behandeln diese Funktionen Mitternacht (00:00:00) als gültigen Zeitwert und behalten ihn im zurückgegebenen Wert bei, genauso wie jede andere Zeit. Zuvor wurde ein Wert von genau Mitternacht auf eine reine Datumszeichenkette gekürzt, während jede andere Zeit korrekt beibehalten wurde.
• Lösung: Wenn die nachgelagerte Logik einen reinen Datumswert erfordert, verwenden Sie FormatDate, um das Ergebnis explizit zu formatieren, anstatt sich auf das Standardausgabeformat der Funktion zu verlassen.

Zwischengespeicherter Wert läuft früher ab als erwartet

• Symptom: Ein Wert, der mit einer langen Ablaufzeit (z. B. 24 Stunden) in den Cache geschrieben wird, verschwindet lange vor Ablauf dieser Zeit, oder läuft nach 30 Minuten ab, unabhängig davon, was in WriteCache festgelegt wurde.
• Mögliche Ursache: Jeder Aufruf von ReadCache setzt die Ablaufzeit des zwischengespeicherten Elements auf 30 Minuten (1800 Sekunden) zurück, es sei denn, der Parameter expirationSeconds wird explizit angegeben. Die WriteCache-Ablaufzeit gilt nur zum Zeitpunkt des Schreibens; nachfolgende Lesevorgänge ohne explizite Ablaufzeit verkürzen die verbleibende Lebensdauer stillschweigend.
• Lösung:
  • Geben Sie die Ablaufzeit in ReadCache an: Übergeben Sie die gewünschte Anzahl von Sekunden als Parameter expirationSeconds, um die Lebensdauer des zwischengespeicherten Werts bei jedem Lesevorgang zu bewahren oder zu verlängern:

// Setzt das Ablaufdatum bei jedem Lesen auf 24 Stunden zurück
testVal = ReadCache("CacheTest", 86400, "env");

• Übergeben Sie -1, um das Schreibablaufdatum beizubehalten: Wenn Sie einen nicht-positiven Wert übergeben, behält ReadCache das Ablaufdatum bei, das durch den letzten WriteCache-Aufruf festgelegt wurde, anstatt ein neues anzuwenden:

  testVal = ReadCache("CacheTest", -1, "env");
  

RunXSLT schlägt mit „XML-Version muss 1.0 oder 1.1 sein" fehl

• Symptom: RunXSLT schlägt mit dem Fehler fehl:

  Failed to execute xslt. XML version must be 1.0 or 1.1
  

  obwohl die XML-Eingabedatei eine gültige <?xml version="1.0"?>-Deklaration enthält.

• Mögliche Ursache: Das XSLT-Stylesheet ist so konfiguriert, dass es HTML-Ausgabe erzeugt (z. B. <xsl:output method="html"/>). RunXSLT unterstützt nur XML als Ausgabe. Wenn das Stylesheet HTML erzeugt, generiert die Funktion ein leeres Ergebnis, das diesen Fehler auslöst. Die Fehlermeldung bezieht sich auf die fehlende XML-Deklaration in der (leeren) Ausgabe, nicht auf die XML-Eingabe.

• Lösung:

  • Aktualisieren Sie das XSLT, um XML-Ausgabe zu erzeugen: Ändern Sie die Ausgabeerklärung des Stylesheets in <xsl:output method="xml"/> oder entfernen Sie die xsl:output-Deklaration vollständig (XML ist die Standardeinstellung). Dies ist der empfohlene Ansatz und funktioniert sowohl auf Cloud- als auch auf privaten Agenten.

  • Verwenden Sie das XSL Transform-Plugin (nur private Agenten): Für private Agent-Gruppen verwendet das veraltete XSL Transform-Plugin den Saxon-XSLT-Prozessor und unterstützt Nicht-XML-Ausgabeformate einschließlich HTML. Siehe Verfügbare Plugins für Installationsdetails.

SelectSingleNode gibt den falschen Knoten zurück, wenn er mit einem SelectNodes-Array-Element verwendet wird

• Symptom: SelectSingleNode gibt Daten aus dem falschen Element zurück (z. B. immer die erste Übereinstimmung im Dokument), wenn es auf ein Element aufgerufen wird, das aus einem SelectNodes-Array abgerufen wurde.
• Mögliche Ursache: Die Verwendung eines absoluten XPath-Ausdrucks (einer, der mit // beginnt) als Pfadargument führt dazu, dass SelectSingleNode vom Stamm des ursprünglichen XML-Dokuments aus sucht, anstatt relativ zum aktuellen Knoten. Ein Ausdruck wie "//Item/ItemName" stimmt mit dem ersten ItemName überein, das sich irgendwo im Dokument befindet, unabhängig davon, welches Item-Element aus dem Array abgerufen wurde.

• Lösung:

  • Verwenden Sie einen relativen Pfad: Lassen Sie das führende // weg und geben Sie nur den Elementnamen oder einen Pfad relativ zum aktuellen Knoten an. Dies beschränkt die Suche auf den Knoten, der als erstes Argument übergeben wird:

    $itemName = SelectSingleNode($item, "ItemName");
    

  • Alternative: Wickeln Sie den Knoten in String: Das Konvertieren des Array-Elements in einen String, bevor es an SelectSingleNode übergeben wird, erzeugt auch das richtige Ergebnis, obwohl die Verwendung eines relativen Pfads der bevorzugte Ansatz ist:

    $item = String($items[2]);
    $itemName = SelectSingleNode($item, "//Item/ItemName");
    

HexToBinary-Ausgabe erscheint unverändert, wenn protokolliert

• Symptom: HexToBinary scheint keine Auswirkung zu haben: Der in das Operationsprotokoll geschriebene Wert sieht identisch mit der Hexadezimaleingabe aus, was darauf hindeutet, dass die Konvertierung nicht stattgefunden hat.
• Mögliche Ursache: WriteToOperationLog kann keine rohen Binärdaten ausgeben. Wenn ein Binärwert übergeben wird, konvertiert er ihn zur Anzeige zurück in Hexadezimal. Das gleiche Verhalten gilt im Skript-Testfenster. Die Konvertierung funktioniert korrekt; nur die Anzeige ist betroffen.
• Lösung: Um mit der Binärausgabe zu arbeiten oder sie zu überprüfen, schreiben Sie sie mit WriteFile in eine Datei. Beispiel:

WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/Write</TAG>", HexToBinary("1A3F"));

SortArray sortiert Dateinamen lexikografisch, nicht chronologisch

• Symptom: SortArray gibt Dateinamen in alphabetischer Reihenfolge zurück, anstatt sie chronologisch zu sortieren, wenn Dateinamen eingebettete Datums- oder Zeitzeichenfolgen enthalten.
• Mögliche Ursache: SortArray führt eine Zeichenketten- (lexikografische) Sortierung durch. Bei einem Dateinamen wie ordall_DDMMYYHHMMSS.txt steht der Tagteil dem Jahrteil in der Zeichenkette voraus, daher entspricht eine alphabetische Sortierung nicht einer datumsgestützten Sortierung.
• Lösung:
  • Wenn Sie die Dateibenennungskonvention kontrollieren, wechseln Sie zu einem Format, das bei alphabetischer Sortierung korrekt sortiert wird, z. B. YYYY-MM-DD_HHMMSS_filename.txt. Dies ist die einfachste und zuverlässigste Lösung.
  • Wenn das Dateinamenformat nicht geändert werden kann, analysieren Sie den Datumsteil jedes Dateinamens in einen sortierbaren Schlüssel (z. B. YYYYMMDDHHMMSS) und sortieren Sie nach dem analysierten Schlüssel anstelle des ursprünglichen Dateinamens.

URLEncode codiert bestimmte „sichere" oder Multibyte-Zeichen nicht

• Symptom: Ein Wert, der durch URLEncode geleitet wird, wird an das Ziel mit einigen nicht codierten Zeichen gesendet, was dazu führt, dass das empfangende System die Anfrage ablehnt oder den Wert falsch interpretiert. Dies betrifft häufig Anmeldedaten oder Abfragewerte, die Zeichen wie $, + oder ! enthalten.
• Mögliche Ursachen:
  • URLEncode folgt RFC 1738 und behandelt diese Zeichen als „sicher", daher codiert es sie nie: $ - _ . + ! * ' ( ) ,. Ein Ziel, das erwartet, dass diese Zeichen prozentual codiert werden, erhält stattdessen das Rohzeichen.
  • Die Multibyte-Zeichenunterstützung in URLEncode erfordert Agent-Version 12.4 oder später. Bei früheren Agents werden Multibyte-Zeichen möglicherweise nicht wie erwartet codiert.

• Lösung:

  • Wenn „sichere" Zeichen codiert werden müssen (z. B. in einem OAuth-Passwort oder einem Wert, der + enthält), verwenden Sie stattdessen die JavaScript-Funktion encodeURIComponent in einem JavaScript-Skriptschritt anstelle von URLEncode:

    <javascript>
    $my_username = "$Example+User";
    $loginValue = encodeURIComponent($my_username);
    </javascript>
    

    Dies gibt %24Example%2BUser zurück.

  • Um Multibyte-Zeichen mit URLEncode zu codieren, bestätigen Sie, dass sich der Agent in Version 12.4 oder später befindet.

JavaScript: Fehler „Call to Jitterbit Tomcat failed"

• Symptom: Ein komplexer oder lange laufender JavaScript-Schritt schlägt mit einem generischen Fehler fehl, der auf Tomcat verweist, obwohl beide Jitterbit Apache- und Jitterbit Tomcat-Dienste auf dem Agent ausgeführt werden. Das Skript kann erfolgreich sein, wenn seine Komplexität reduziert wird (z. B. durch Verringern der Iterationszählungen oder der Rekursionstiefen).

  Call to Jitterbit Tomcat failed (null response). Make sure the Jitterbit Apache and Jitterbit Tomcat services are both running.
  Failed to execute script
  

• Mögliche Ursache: Tiefe rekursive JavaScript-Aufrufe können das Rekursionstiefe-Limit der JavaScript-Engine des Agents überschreiten und einen Stack-Overflow verursachen, der sich als dieser generische Tomcat-Fehler äußert. Dieses Rekursionslimit ist beabsichtigt. Das Skript wird normalerweise abgeschlossen, sobald die Rekursionstiefe reduziert wird.

• Lösung:
  • Reduzieren Sie die Rekursionstiefe, oder schreiben Sie die rekursive Logik als iterative Schleife um.
  • Wenn der Algorithmus tiefe Rekursion nicht vermeiden kann, verwenden Sie einen Ansatz, der sich nicht darauf verlässt.
  • Beachten Sie, dass das separate Pro-Skript-Schleifeniterationslimit (JavaScriptMaxIterations, siehe Script loop iteration limit exceeded) die Rekursionsobergrenze nicht erhöht, die nicht als konfigurierbare Einstellung verfügbar gemacht wird.

JavaScript: Globale Variablenänderungen gehen bei Skriptfehlern verloren

• Symptom: Ein JavaScript-Skript, das globale Variablen ändert, läuft in einigen Fällen ohne erkennbaren Fehler, aber die Änderungen an diesen globalen Variablen fehlen in nachfolgenden Skripten oder Operationen.
• Mögliche Ursachen:
  • In JavaScript werden Änderungen an globalen Variablen nur committed, wenn das Skript erfolgreich abgeschlossen wird. Wenn das Skript an irgendeinem Punkt fehlschlägt, werden alle während dieser Ausführung vorgenommenen Änderungen an globalen Variablen verworfen.
  • Das Mischen von $variable-Syntax mit Jitterbit.SetVar/Jitterbit.GetVar für dieselbe Variable innerhalb eines JavaScript-Skripts kann zu unvorhersehbarem Laufzeitverhalten führen.
• Lösung:
  • Strukturieren Sie JavaScript-Skripte so, dass alle Zuweisungen globaler Variablen nach der Logik erfolgen, die fehlschlagen könnte, oder verwenden Sie Fehlerbehandlung, um Fehler in der Mitte des Skripts zu verhindern.
  • Verwenden Sie für jede Variable in einem JavaScript-Skript entweder $variable-Syntax oder Jitterbit.SetVar/Jitterbit.GetVar, niemals beides. Wählen Sie eine Variante und verwenden Sie diese konsistent im gesamten Skript.
  • Um zu bestätigen, welche Variablen gesetzt werden, fügen Sie WriteToOperationLog-Aufrufe hinzu, um Variablenwerte an wichtigen Punkten während der Ausführung zu protokollieren.

JavaScript: GetVar gibt null für benutzerdefinierte Projektvariablen zurück

• Symptom: Der Aufruf von Jitterbit.GetVar auf einer benutzerdefinierten Projektvariablen in einem JavaScript-Skriptschritt gibt null statt des Variablenwerts zurück, ohne Fehlermeldung.
• Mögliche Ursache: Jitterbit.GetVar und Jitterbit.SetVar sind für Jitterbit-Systemvariablen (z. B. jitterbit.operation.name) und für Variablennamen mit Punkt vorgesehen, auf die JavaScripts Punktnotation nicht direkt zugreifen kann. Sie lesen keine gewöhnlichen benutzerdefinierten Projektvariablen, deren Namen keinen Punkt enthalten; die Übergabe eines solchen Namens an GetVar gibt null zurück. Referenzieren Sie diese Variablen stattdessen direkt mit $name. Diese Funktionen konvertieren auch alle Werte in Strings, daher sind sie nicht für Arrays oder Objekte geeignet. Ein mit SetVar gesetzter Wert kann mit GetVar innerhalb desselben Skripts gelesen werden, bleibt aber nicht in späteren Skripten erhalten.

• Lösung: Verwenden Sie die $variableName-Syntax direkt in JavaScript, um auf benutzerdefinierte Projekt- und globale Variablen zuzugreifen, deren Namen keinen Punkt enthalten. Reservieren Sie GetVar und SetVar für Jitterbit-Systemvariablen und für Variablen, deren Namen einen Punkt enthalten (z. B. $hello.world), auf die JavaScripts Punktnotation nicht direkt zugreifen kann. Verwenden Sie für eine bestimmte Variable entweder $-Präfix oder GetVar/SetVar, nicht beides. Siehe auch JavaScript: Globale Variablenänderungen gehen bei Skriptfehlern verloren.

  // Correct: access a user-defined project variable directly
  var value = $myProjectVar;
  
  // Incorrect for user-defined variables without periods:
  var value = Jitterbit.GetVar("$myProjectVar"); // returns null
  

HTTP- und API-Fehler

504 Gateway Timeout

• Symptom: API-Aufrufe über das Cloud- oder Private-API-Gateway geben 504 Gateway Timeout zurück, typischerweise nach dem Timeout-Fenster des Gateways (30 bis 180 Sekunden).
• Ursache und Lösung: Die zugrunde liegende Operation überschreitet das Timeout des API-Gateways, oder die Anfrage kann keinem verfügbaren Agent zugewiesen werden. Siehe HTTP 504 Gateway Timeout im Troubleshooting-Leitfaden des API Managers für die vollständigen Ursachen und Lösungen.

507 Insufficient Storage

• Symptom: Ein API-Aufruf gibt folgende Meldung zurück:

  507 Insufficient Storage
  

• Mögliche Ursachen:

  • Der Agent oder Gateway-Host hat keinen Speicherplatz mehr.
  • Bei einem privaten API-Gateway kann das Gateway seine gehostete Payload- oder Antwortdatei nicht öffnen und gibt einen 507-Fehler zurück, auch wenn ausreichend Speicherplatz verfügbar ist. Dies deutet normalerweise auf ein Problem mit der privaten Domain-Registrierung oder der Gateway-Konfiguration hin.

• Lösung:

  • Bestätigen Sie, dass der Agent oder Gateway-Host über ausreichend freien Speicherplatz verfügt.
  • Wenn ausreichend Speicherplatz vorhanden ist und die API über ein privates API-Gateway bereitgestellt wird, siehe Private gateway returns HTTP 507 or "No such file or directory" für die Ursache und Lösung.

502 Bad Gateway

• Symptom: Ein Vorgang, der Jitterbit Message Queue (JBMQ) verwendet, schlägt fehl mit:

  502 Bad Gateway
  

  Der Server hat eine ungültige oder unvollständige Antwort zurückgegeben.

• Mögliche Ursache: Der JBMQ-Service hat keine vollständige Antwort auf die Anfrage zurückgegeben, was zu einem 502-Fehler führt. Dieser Fehler ist normalerweise vorübergehend und möglicherweise nicht reproduzierbar.

• Lösung:
  1. Wiederholen Sie den Vorgang.
  2. Wenn der Fehler weiterhin auftritt, kontaktieren Sie den Jitterbit-Support.

Fehler zur Entwurfszeit

Diese Probleme treten beim Erstellen, Validieren oder Bereitstellen eines Projekts in Studio auf, nicht wenn ein Vorgang ausgeführt wird.

Häufige Validierungsfehler bei Vorgängen

Vorgänge mit Validierungsfehlern zeigen ein ungültiges Symbol auf der Design-Canvas und im Projektbereich an. Klicken Sie auf das Symbol, um die spezifische Fehlermeldung anzuzeigen.

Die folgende Tabelle listet häufige Validierungsfehler und deren Lösungen auf:

HTTP-Validierungsregelfehler

Eine der HTTP-Validierungsregeln gilt für Operationen, die das Zwei-Ziel-Archivmuster verwenden, bei dem eine HTTP-Aktivität in der Position Ziel 1 eine Antwort in eine zweite Zielaktivität (Ziel 2) schreibt. In diesem Szenario erfordert die Validierungsregel, dass eine HTTP-Aktivität Ziel 1 nicht in anderen Zwei-Ziel-Archivmuster-Operationen verwendet werden darf, bei denen die HTTP-Aktivität Ziel 1 in eine andere zweite Zielaktivität schreibt.

Operationen, die gegen diese Validierungsregel verstoßen, werden als ungültig mit einer Fehlermeldung angezeigt, die dem folgenden Beispiel ähnelt:

HTTP-Validierungsfehler beheben

Befolgen Sie die Anweisungen in der Fehlermeldung, um die Operationen so zu korrigieren, dass sie gültig sind. Führen Sie die folgenden Schritte aus, um diese Fehler zu beheben:

1. Duplizieren Sie die HTTP-Zielaktivität in der Position Ziel 1 einer der Operationen, die das Zwei-Ziel-HTTP-Archivmuster verwendet.

2. Ersetzen Sie die HTTP-Zielaktivität in der Position Ziel 1 der identifizierten Operationen durch die duplizierte Kopie.

3. Wiederholen Sie den Vorgang für alle weiteren ungültigen Operationen. Nachdem Sie die Validierungsfehler behoben haben, stellen Sie die Operationen erneut bereit.

HTTP-Validierungsregel deaktivieren

In bestimmten Situationen möchten Sie diese HTTP-Validierungsregel möglicherweise deaktivieren. Führen Sie die folgenden Schritte aus, um die Regel zu deaktivieren:

1. Öffnen Sie die Projekteinstellungen:

   

2. Deaktivieren Sie auf der Registerkarte Bereitstellung die Option HTTP-Validierungsregel:

   

3. Klicken Sie auf Speichern.

Nachdem Sie die Einstellung deaktiviert und gespeichert haben, sollten die Operationsvalidierungsfehler aus dieser Regel behoben sein. Allerdings schreiben alle HTTP-Aktivitäten Ziel 1, die in einer Zwei-Ziel-Archivmuster-Operation verwendet werden, in die Aktivität Ziel 2 der zuletzt bereitgestellten Operation. Dieses Verhalten kann dazu führen, dass ungültige Daten geschrieben werden.

HTTP-Validierungsregel erneut aktivieren

Wenn Sie die HTTP-Validierungsregel zuvor deaktiviert haben und sie erneut aktivieren möchten, führen Sie die folgenden Schritte aus:

1. Öffnen Sie die Projekteinstellungen.

2. Aktivieren Sie auf der Registerkarte Bereitstellung die Option HTTP-Validierungsregel.

3. Klicken Sie auf Speichern. Diese Änderung ist eine Designzeitänderung und stellt keine Änderungen in der Harmony-Cloud bereit.

4. Beheben Sie alle HTTP-Validierungsfehler (siehe HTTP-Validierungsfehler beheben).

5. Stellen Sie das Projekt erneut bereit (siehe Projektbereitstellung).

   Hinweis

   Vor der erneuten Bereitstellung ermöglicht Harmony die Ausführung aller nun ungültigen Operationen, da Harmony die aktuell bereitgestellten Operationen ausführt. Eine erneute Bereitstellung der betroffenen Operationen ist erforderlich, damit die Änderungen an Harmony weitergegeben werden.

Komponentennamen müssen nach dem Projektimport eindeutig sein

• Symptom: Nach dem Importieren eines Projekts aus einer JSON-Exportdatei zeigen sich eine oder mehrere Komponenten als ungültig an und die Bereitstellung schlägt mit einer ähnlichen Meldung fehl:

  [Operation / Connection / Activity / Transformation / Script / Tool / Email / Variable] names must be unique.
  

• Mögliche Ursache: Das importierte Projekt enthält mehrere Komponenten desselben Typs mit identischen Namen. Studio verhindert das Erstellen doppelter Namen bei der direkten Konfiguration von Komponenten in der Benutzeroberfläche, aber ein vollständiger Projektimport wendet diese Prüfung nicht an.

• Lösung:
  1. Identifizieren Sie im Projektbereich die ungültigen Komponenten, die in roten Kursivbuchstaben mit einem Fehlersymbol angezeigt werden.
  2. Klicken Sie auf das Fehlersymbol, um den spezifischen doppelten Namen anzuzeigen, der den Konflikt verursacht.
  3. Benennen Sie eine der doppelten Komponenten um, sodass jeder Name innerhalb seines Typs eindeutig ist.
  4. Stellen Sie das Projekt erneut bereit, nachdem Sie alle Fehler mit doppelten Namen behoben haben.
  5. Um nur ausgewählte Komponenten in ein vorhandenes Projekt zu importieren, verwenden Sie selektiven Import, der Konflikte mit gleichnamigen Komponenten im Zielproject kennzeichnet und ermöglicht es Ihnen, diese zu ersetzen oder beide beizubehalten.

Connector nur für private Agenten blockiert Import in eine Cloud-Agent-Umgebung

• Symptom: Der Import oder die Migration eines Projekts in eine Umgebung, die einer Cloud-Agent-Gruppe zugeordnet ist, wird blockiert, da das Projekt einen Connector nur für private Agenten verwendet. Die Meldung listet die verantwortlichen Connectoren nur für private Agenten auf. Ein vollständiger Projektimport zeigt an:

  The project you are importing uses private agent only connectors and cannot be imported into a cloud environment.
  

  Ein selektiver Import zeigt einen Dialog Komponentenimport nicht zulässig an:

  The components you are importing uses private agent only connectors and cannot be imported into a cloud environment.
  

• Mögliche Ursache: Das Projekt verwendet einen oder mehrere Connectoren, die nur auf privaten Agenten verfügbar sind. Die Spalte Agent-Verfügbarkeit in der Connectorliste zeigt, welche Connectoren nur für private Agenten verfügbar sind. Cloud-Agenten unterstützen diese Connectoren nicht, daher verhindert Studio, dass das Projekt in eine Cloud-Agent-Umgebung importiert oder migriert wird.

• Lösung:
  • Importieren oder migrieren Sie das Projekt in eine Umgebung, die einer Gruppe privater Agenten zugeordnet ist und den erforderlichen Connector installiert hat.
  • Wenn das Projekt auf Cloud-Agenten ausgeführt werden muss, ersetzen Sie die Connector-Aktivitäten nur für private Agenten durch Cloud-kompatible Connectoren (z. B. HTTP v2 für REST-APIs oder den Database-Connector mit einem Cloud-zugänglichen Endpunkt), bevor Sie den Import durchführen.

Das Hochladen einer Schemadatei ersetzt sie projektübergreifend

• Symptom: Nach dem Hochladen einer neuen Schemadatei während der Transformationskonfiguration verhalten sich andere Transformationen im Projekt, die dasselbe Schema verwendet haben, unerwartet oder erzeugen Fehler.
• Mögliche Ursache: Wenn man eine Datei mit demselben Namen wie eine bereits im Projekt definierte Schemadatei hochlädt, zeigt Studio einen Dialog Datei überschreiben? an. Klickt man auf Weiter, wird die vorhandene Datei an jedem Ort, an dem sie verwendet wird, ersetzt. Diese Ersetzung ist projektübergreifend und nicht auf die aktuelle Transformation beschränkt.
• Lösung:
  1. Bevor man eine Ersatz-Schemadatei hochlädt, sollte man bestätigen, ob das vorhandene Schema gemeinsam genutzt wird: Öffnet man das Schema zur Bearbeitung und wird es von mehr als einer Komponente referenziert, zeigt Studio einen Dialog Schema wird von mehreren Komponenten verwendet an, der diese auflistet (siehe Transformationsdefinierte Schemas aktualisieren). Man sollte die Auswirkungen auf alle aufgelisteten Komponenten bewerten, bevor man fortfährt.
  2. Wenn nur eine Transformation das aktualisierte Schema verwenden soll, klickt man im Dialog Datei überschreiben? auf Abbrechen (oder benennt die neue Datei vor dem Hochladen um), damit die gemeinsam genutzte Datei nicht überschrieben wird.

Die Bereitstellung einer Marketplace-Prozessvorlage schlägt aufgrund eines Schemakonflikts fehl

• Symptom: Ein aus einer Marketplace-Prozessvorlage importiertes Projekt kann nicht bereitgestellt werden oder erzeugt Laufzeitfehler, da Felder in einer Transformation oder einer Quell- und Zielaktivitätsvalidierung fehlen.
• Mögliche Ursache: Prozessvorlagen werden für eine bestimmte Endpoint-Instanz entwickelt. Wenn sich die Instanz unterscheidet (z. B. wenn die Salesforce- oder NetSuite-Organisation unterschiedliche benutzerdefinierte oder Standardfelder hat), stimmen die in den Transformationen der Vorlage eingebetteten Schemas möglicherweise nicht mit dem Endpoint überein.
• Lösung:
  1. Öffnet man in der betroffenen Transformation die Schemaeinstellungen und klickt auf das Aktualisierungssymbol (oder das Wort Aktualisieren), wird das Schema von dem verbundenen Endpoint neu generiert.
  2. Wenn das Schema nach der Aktualisierung immer noch nicht übereinstimmt, löscht man das vorhandene Schema und spiegelt es erneut von einer aktuellen Beispieldatei oder direkt vom Endpoint.
  3. Man ordnet alle Felder neu zu, die während der Schemaneugenerierung hinzugefügt oder entfernt wurden.
  4. Man stellt das Projekt erneut bereit und führt den Vorgang erneut aus, um zu bestätigen, dass das Problem behoben ist.

Studio wird bei sehr großen Projekten langsam oder reagiert nicht

• Symptom: Studio reagiert langsam, wenn ein einzelner Workflow eine sehr große Anzahl von Operationen enthält, oder wenn man ein sehr großes Skript speichert.
• Mögliche Ursache: Die Design-Canvas rendert alle Operationen im aktiven Workflow auf einmal, daher stellt ein Workflow mit einer sehr großen Anzahl von Operationen hohe Speicheranforderungen an den Browser.
• Lösung:
  • Man teilt große Workflows in kleinere, verknüpfte Sub-Workflows auf. Studio rendert nur die aktive Workflow-Canvas, daher verbessern weniger Operationen pro Workflow die Reaktionsfähigkeit. Man verwendet Operationsaktionen, um Sub-Workflows miteinander zu verknüpfen.
  • Wenn die Langsamkeit speziell beim Speichern eines großen Skripts auftritt, teilt man das Skript in kleinere Skripts auf und ruft sie mit RunScript auf.

System- und Ressourcenfehler

Chunking wird nicht berücksichtigt, wenn die Quelle ein SDK-basierter Connector ist

• Symptom: Ein Vorgang mit aktiviertem Chunking sendet alle Datensätze in einem einzigen Batch an das Ziel, anstatt die konfigurierte Chunk-Größe zu berücksichtigen. Fehler vom Ziel deuten darauf hin, dass das Batch-Limit überschritten wurde (beispielsweise gibt Salesforce EXCEEDED_ID_LIMIT: record limit reached. cannot submit more than 200 records into this call zurück).
• Mögliche Ursache: Chunking wird nicht unterstützt, wenn die Quelle ein Connector SDK-basierter Connector ist (wie in der Spalte Connector-Typ der Connectors-Liste aufgeführt). Vorgänge mit Nicht-SDK-Quellen wie HTTP, Database, Variable und Local Storage berücksichtigen Chunking normalerweise.
• Lösung:
  • Wenn Chunking nicht erforderlich ist, deaktivieren Sie es in den Vorgangsoptionen.
  • Wenn Chunking erforderlich ist, teilen Sie den Vorgang in zwei auf:
    • Im ersten Vorgang lesen Sie aus der SDK-basierten Quelle und schreiben in eine Variable Write-Aktivität.
    • Im zweiten Vorgang lesen Sie aus einer Variable Read-Aktivität und schreiben mit aktiviertem Chunking in das ursprüngliche Ziel. Da der Variable-Connector nicht SDK-basiert ist, funktioniert Chunking in diesem Vorgang korrekt. Die Schritte zum Einrichten von Chunking finden Sie unter Configure operation chunking.

Variablenupdates gehen in mehrstufigen Vorgängen mit Chunking verloren

• Symptom: Wenn ein Vorgang mit aktiviertem Chunking und Max Number of Threads auf mehr als 1 ausgeführt wird, gehen Aktualisierungen globaler oder Projektvariablen, die während des Vorgangs vorgenommen werden, nach dessen Abschluss nicht vollständig verloren. Ein möglicher Fall ist das Auffüllen einer Dictionary- oder Array-Variable aus jedem Quelldatensatz und das anschließende Feststellen, dass sie nur einen Teil der Daten enthält (beispielsweise ungefähr die Hälfte der Datensätze, wenn zwei Threads ausgeführt werden). Dies kann bei Connectoren auftreten, deren Standardkonfiguration mehr als einen Thread verwendet, wie z. B. Salesforce-Aktivitäten, die standardmäßig 2 Threads verwenden.
• Mögliche Ursache: Jeder Thread erhält zu Beginn der Verarbeitung eine eigene Kopie der globalen und Projektvariablen. Thread-lokale Änderungen werden nicht wieder in den gemeinsamen Status zusammengeführt. Nur Änderungen des ersten Threads bleiben erhalten, wenn der Vorgang abgeschlossen ist. Änderungen aller anderen Threads werden verworfen.
• Lösung:
  • Wenn Korrektheit wichtiger ist als der Durchsatz pro Vorgang, setzen Sie Max Number of Threads auf 1. Jeder Chunk wird dann sequenziell verarbeitet, sodass Variablenupdates nicht auf mehrere Threads verteilt werden.
  • Wenn mehrstufiger Durchsatz erforderlich ist, sammeln Sie keinen Pro-Datensatz-Status in einer globalen oder Projektvariable an. Schreiben Sie stattdessen die Ausgabe jedes Threads in eine eindeutige Temporary Storage-Datei oder eine Staging-Datenbanktabelle, und konsolidieren Sie die Ergebnisse dann in einem nachfolgenden Single-Thread-Vorgang. Ein praktisches Beispiel des Staging-Musters finden Sie unter Variable scoping with chunking.
  • Verlassen Sie sich allgemein nicht auf Aktualisierungen globaler oder Projektvariablen aus mehrstufigen, Multi-Thread-Vorgängen in späteren Skripten oder Vorgängen. Wenn der Variablenstatus beibehalten werden muss, legen Sie diese Variablen in einem nicht mehrstufigen Vorgangsschritt fest, der vor oder nach der mehrstufigen Transformation ausgeführt wird. Weitere Informationen zum Chunking-Verhalten mit Variablen finden Sie unter Use variables with chunking.

Fehler beim Erstellen eines temporären Verzeichnisses

• Symptom: Ein Vorgang schlägt beim Erstellen eines temporären Verzeichnisses fehl und zeigt eine Fehlermeldung wie:

  Failed to create the directory '/tmp/jitterbit/...'. Reason: boost::filesystem::create_directories: Permission denied
  

  Bei einer Cloud-Agent-Gruppe kann stattdessen die Meldung No space left on device angezeigt werden.

• Mögliche Ursachen:

  • Bei einem privaten Agent verfügt das Jitterbit-Agent-Dienstkonto nicht über die erforderlichen Berechtigungen auf Betriebssystemebene für den Pfad der temporären Dateien, oder die Festplatte ist voll.
  • Bei einer Cloud-Agent-Gruppe liegt die Ursache auf der von Jitterbit verwalteten Agent-Seite und nicht in Ihrem Projekt oder Ihrer Konfiguration.

• Lösung:

  • Bestätigen Sie bei privaten Agents, dass das Agent-Dienstkonto ausreichende Berechtigungen für den Pfad der temporären Dateien (/tmp oder TemporaryFiles) hat, und überprüfen Sie, dass der Agent-Host über ausreichend freien Speicherplatz verfügt.
  • Bei Cloud-Agent-Gruppen deutet dies auf ein Agent-seitiges Problem hin, das Jitterbit behebt. Kontaktieren Sie den Jitterbit-Support und geben Sie die Fehlermeldung sowie den Zeitpunkt der Fehler an.

Vorgangsprotokolmeldungen bei etwa 100 KB gekürzt

• Symptom: Eine Vorgangsprotokolmeldung erscheint abgeschnitten und endet mit message truncated. Dies kann in den Vorgangsprotokollen oder beim Anzeigen eines Operation-Protokolleintrags auf der Seite API-Protokolle des API Manager auftreten.
• Mögliche Ursache: Vorgangsprotokolmeldungen, die etwa 100 KB (etwa 99.000 Zeichen) überschreiten, werden gekürzt. Der Kürzungspunkt ist am Ende der Meldung mit message truncated gekennzeichnet.
• Lösung: Wenn Sie den vollständigen Protokollinhalt benötigen, reduzieren Sie die Ausführlichkeit der Protokollierung des Vorgangs oder teilen Sie den Vorgang in kleinere Einheiten auf, die kürzere Protokollmeldungen erzeugen.

Vorgangs-Debug-Protokollierung offenbart PII und Anmeldedaten im Klartext

• Symptom: Vertrauliche Daten, Anmeldedaten oder personenbezogene Informationen (PII) werden in den Harmony-Cloud-Protokollen angezeigt.
• Mögliche Ursache: Wenn die Vorgangs-Debug-Protokollierung für einen Vorgang aktiviert ist, werden alle Anfrage- und Antwortdaten 30 Tage lang im Klartext in der Harmony-Cloud gespeichert.
• Lösung:
  • Verwenden Sie die Vorgangs-Debug-Protokollierung nur in kontrollierten, produktionsfremden Umgebungen oder für einen begrenzten Diagnosezeitraum.
  • Um die Generierung von Komponenteneingabe- und -ausgabedaten für eine private Agent-Gruppe zu deaktivieren, setzen Sie verbose.logging.enable=false im Abschnitt [VerboseLogging] der Agent-Konfigurationsdatei.