Fehlerbehebung in Jitterbit Harmony

Diese Anleitung behandelt häufige Probleme bei der Fehlerbehebung auf der einheitlichen Harmony-Plattform (Integration, Automation, API-Management, EDI und App-Entwicklung), organisiert nach Funktion, damit Sie Probleme überall finden und beheben können. Erweitern Sie die untenstehende Liste, um alle Einträge auf dieser Seite zu durchsuchen, oder nutzen Sie die Suchfunktion Ihres Browsers Strg + F (Windows oder Linux) oder Befehl + F (macOS), um nach einer bestimmten Fehlermeldung oder einem Symptom zu suchen.

Alle Fehlerbehebungseinträge auf dieser Seite

Plattformverwaltung
Integration und Automatisierung
API-Verwaltung
EDI
App-Entwicklung

API-Verwaltung
EDI
App-Entwicklung

Diagnoseabläufe

Überprüfe die Operationsprotokolle

Öffne in der Verwaltungskonsole die Seite Laufzeit und überprüfe den Protokolleintrag für die betroffene Operation. Der Status und alle Protokollmeldungen sind der Hauptindikator für die Ursache. Die Seite Laufzeit listet alle Operationen auf, einschließlich derer, die direkt ausgeführt werden, und derer, die durch eine API ausgelöst werden (in der Spalte Protokolltyp als Custom API, Proxy API oder OData API angezeigt), daher ist sie der Ausgangspunkt für die meisten Laufzeitprobleme.

Überprüfe die API-Protokolle

Für API-spezifische Details öffnest du die Seite API-Protokolle im API Manager. Sie zeigt für jeden API-Aufruf die Request- und Response-Daten (HTTP-Statuscode, Antwortzeit, Request-URI, Quell-IP) an und ermöglicht, falls aktiviert, Debug- und Verbose-Traces. Operationsprotokolle für durch APIs ausgelöste Operationen erscheinen hier auch neben der Laufzeitseite.

Überprüfe die Agent-Protokolle

Überprüfe bei Umgebungen, die auf privaten Agenten ausgeführt werden, die Agent-Protokolldateien auf Konnektivitäts-, Ressourcen- und Synchronisierungsfehler. Siehe Agent-Protokolle für Dateispeicherorte.

Harmony-Systemstatus prüfen

Falls ein Problem alle Vorgänge oder alle APIs statt nur einen einzelnen Workflow betrifft, prüfen Sie trust.jitterbit.com und die Seite Bekannte Probleme bevor Sie weiter untersuchen.

Plattformverwaltung

Dieser Abschnitt behandelt Probleme auf Harmony-Plattformebene: Authentifizierung, Benutzer- und Umgebungsverwaltung sowie Projektbereitstellung.

Symptom: Benutzer können sich nicht im Harmony-Portal anmelden.
Lösung:
- Prüfen Sie trust.jitterbit.com auf aktive Plattformausfälle.
- Löschen Sie den Browser-Cache und die Cookies, dann versuchen Sie es erneut oder verwenden Sie ein Inkognito- oder privates Fenster oder einen anderen Browser. Veraltete zwischengespeicherte Sitzungsdaten können dazu führen, dass das Portal zur Anmeldungsseite zurückspringt oder nach der Anmeldung nicht geladen wird.
- Falls SSO konfiguriert ist, muss ein Administrator die SSO-Konfiguration überprüfen. Weitere Informationen finden Sie unter Harmony SSO.
- Bestätigen Sie, dass das Benutzerkonto aktiv ist und nicht in der Management Console auf der Seite Benutzerverwaltung deaktiviert wurde.
- Falls die Anmeldung nach diesen Prüfungen immer noch fehlschlägt (z. B. wenn ein Passwort-Reset nicht abgeschlossen wird oder das Konto inaktiv angezeigt wird, obwohl es aktiv ist), wenden Sie sich an den Jitterbit Support.

Konto nach fehlgeschlagenen Anmeldeversuchen gesperrt

Symptom: Ein Benutzer kann sich nach Eingabe falscher Anmeldedaten nicht anmelden. Sein Status in der Management Console auf der Seite Benutzerverwaltung wird als Inaktiv angezeigt.
Mögliche Ursache: Nach 5 aufeinanderfolgenden fehlgeschlagenen Anmeldeversuchen wird das Konto für 30 Minuten gesperrt.
Lösung:
- Warten Sie 30 Minuten, dann versuchen Sie es mit den korrekten Anmeldedaten erneut.
- Verwenden Sie alternativ den Link Ich habe mein Passwort vergessen auf der Anmeldungsseite des Harmony-Portals, um das Passwort zurückzusetzen und die Sperre sofort zu löschen.

Benutzer kann nicht auf eine Umgebung oder deren Funktionen zugreifen

Symptom: Ein Benutzer kann sich anmelden, kann aber eine Umgebung nicht sehen, kann nicht darin bereitstellen oder es fehlen erwartete Funktionen.
Mögliche Ursache: Der Zugriff auf die Umgebung wird durch die dem Benutzer zugewiesenen Rollen gesteuert.
Lösung: Ein Administrator muss der Rolle des Benutzers den entsprechenden Umgebungszugriff in der Management Console gewähren. Überprüfen Sie die zugewiesenen Rollen des Benutzers und die Berechtigungen für diese Rollen.

Projektvariablen werden bei Umgebungspromotion nicht übernommen

Symptom: Nach der Übertragung eines Projekts in eine andere Umgebung fehlen einige Projektvariablenwerte im Ziel oder unterscheiden sich von den erwarteten Werten.
Mögliche Ursache: Ob ein Projektvariablenwert übernommen wird, hängt von der verwendeten Transferoption und den Variableneinstellungen ab:
- Bei einer vollständigen Projektübertragung (Dialog Migrieren) wird der erste Transfer standardmäßig auf Alle Variablenwerte migrieren eingestellt, aber später erfolgende Transfers werden standardmäßig auf Zu migrierende Variablenwerte auswählen eingestellt, wodurch alle Variablen ausgeschlossen werden, deren Wert sich geändert hat. Eine Variable, die nicht eingeschlossen ist und im Ziel noch nicht vorhanden ist, wird ohne Wert übertragen.
- Bei einer selektiven Übertragung steuert der Schritt Variablen konfigurieren, welche Variablen übertragen werden, und die Option Standardwert einschließen bestimmt, ob der Zielwert durch den Standardwert des Quellprojekts ersetzt wird.
Lösung:
- Wählen Sie im Dialog Migrieren die Option Alle Variablenwerte migrieren, oder wählen Sie Zu migrierende Variablenwerte auswählen und fügen Sie die Variablen, die Sie übernehmen möchten, zu Einschließen hinzu.
- Wählen Sie bei einer Selektiven Übertragung im Schritt Variablen konfigurieren die zu übertragenden Variablen aus und legen Sie Standardwert einschließen nach Bedarf fest.
- Alternativ können Sie die korrekten Variablenwerte für die Zielumgebung in Studio nach der Übertragung festlegen. Nehmen Sie diese Änderungen in Studio vor, nicht auf der Seite Projekte der Management Console, damit sie in der Projekthistorie erfasst werden.

Umschalten der Agent-Gruppe einer Umgebung schlägt mit Fehler für Mindestversion des Agenten fehl

Symptom: Das Ändern der Agent-Gruppe, die einer Umgebung in der Management Console zugeordnet ist, schlägt fehl mit:
```
MIN_RQRD_AGENT_VERSION_NOT_MET_CODE
```
Mögliche Ursache: Mindestens einer der Agenten in der Ziel-Agent-Gruppe führt eine Version aus, die unter der Mindestversion liegt, die die Umgebung erfordert, daher wird der Wechsel abgelehnt. Die Mindestversion wird durch die in der Umgebung bereitgestellten Projekte festgelegt: Wenn ein bereitgestelltes Projekt eine neuere Agent-Version erfordert, als die Zielgruppe bietet, schlägt der Wechsel fehl. Dies kann bei einer privaten Agent-Gruppe auftreten, deren Agent-Versionen du verwaltest, oder bei einer Cloud-Agent-Gruppe, die Jitterbit nach einem gestaffelten Zeitplan aktualisiert (Sandbox vor Produktion), sodass eine Ziel-Cloud-Agent-Gruppe während eines Release-Rollouts kurzzeitig eine Version verzögert sein kann.
Lösung:
- Private Agent-Gruppe: Identifiziere auf der Seite Agents der Management Console jeden Agent in der Zielgruppe und aktualisiere jeden auf eine Version, die die erforderliche Mindestversion der Umgebung erfüllt oder übersteigt (siehe Rollierendes Update). Wiederhole dann den Wechsel der Agent-Gruppe der Umgebung.
- Cloud-Agent-Gruppe: Cloud-Agenten werden von Jitterbit aktualisiert und können nicht manuell aktualisiert werden. Behalte die Umgebung in einer Agent-Gruppe, die bereits die erforderliche Version erfüllt, oder wiederhole den Wechsel, nachdem die Ziel-Cloud-Agent-Gruppe aktualisiert wurde.

Design Studio: SSO-Benutzer außerhalb der Region der Organisation können sich nicht anmelden

Symptom: Nachdem Harmony Single Sign-On (SSO) für die Organisation aktiviert wurde, können Benutzer, deren Harmony-Region sich von der Standardregion unterscheidet, mit der sich das Design Studio-Anmeldedialogfeld verbindet, die SSO-Anmeldung nicht abschließen. Benutzer in der Standardregion melden sich ohne Probleme an.
Mögliche Ursache: Design Studio verbindet sich standardmäßig mit einer einzelnen Harmony-Region-URL im Anmeldedialogfeld. Wenn SSO aktiviert ist, wird die SSO-Umleitung nur für die Harmony-Region aufgelöst, die die Organisation hostet. Benutzer müssen Design Studio daher auf die URL dieser Region verweisen, bevor sie sich anmelden.
Lösung:
- Drücken Sie im Design Studio-Anmeldedialogfeld Strg + Umschalt + U, um das URL-Feld zu öffnen. Geben Sie die URL für die Harmony-Region der Organisation ein (z. B. https://na-east.jitterbit.com für NA oder https://emea-west.jitterbit.com für EMEA), und schließen Sie dann die SSO-Anmeldung ab.
- Um die Änderung dauerhaft zu speichern, legen Sie die URL in der Konfigurationsdatei client.properties fest:
  - Öffnen Sie <Jitterbit Studio Home>\configuration\client.properties in einem Text-Editor (unter macOS ist der Pfad /Applications/Jitterbit Studio [version].app/Contents/Java/configuration/client.properties).
  - Heben Sie die Auskommentierung des Parameters cloud.url auf und setzen Sie ihn auf die regionale URL.
  - Speichern Sie die Datei und starten Sie Design Studio neu.

SSO-Konfigurationstest sperrt das Identitätsanbieter-Konto

Symptom: Ein Administrator wird aus seinem Identitätsanbieter-Konto gesperrt, während er eine SSO-Konfiguration in der Management Console testet.
Mögliche Ursache: Jeder Klick auf Test Configuration öffnet das Anmeldeportal des Identitätsanbieters und zählt als Authentifizierungsversuch gegen die Lockout-Richtlinie des IdP. Wiederholtes Klicken auf die Schaltfläche kann die Kontosperrung des IdP auslösen.
Lösung:
- Begrenzen Sie die Anzahl der Testversuche in einer einzelnen Sitzung.
- Falls du aus dem Identitätsanbieter gesperrt wirst, führe den Kontowiederherstellungsprozess des IdP durch, bevor du den SSO-Konfigurationstest wiederholst. Siehe SSO konfigurieren für vollständige Konfigurationsschritte.

IP-Zulassungsliste sperrt einen Administrator

Symptom: Du verlierst den Zugriff auf das Harmony-Portal unmittelbar nachdem ein anderer Administrator die Bereiche in Enable whitelist IP range ändert.
Mögliche Ursache: Die Richtlinie Enable whitelist IP range erfordert, dass die IP-Adresse jedes Benutzers im konfigurierten Bereich enthalten ist. Eine Validierungsmeldung verhindert, dass ein Administrator einen Bereich speichert, der seine eigene aktuelle IP ausschließt, prüft aber nicht die IP-Adressen anderer Administratoren. Wenn die Änderung eines anderen Administrators deine IP ausschließt, wirst du sofort gesperrt.
Lösung:
- Lasse einen anderen Administrator, dessen IP in der Zulassungsliste liegt, die Richtlinie aktualisieren oder deaktivieren, oder kontaktiere den Jitterbit-Support.

Ändern der API-Subdomain bricht bestehende API-Integrationen

Symptom: Nach dem Ändern der API subdomain einer Organisation in der Organisationsdetails der Management Console schlagen Aufrufe an den veröffentlichten APIs der Organisation von bestehenden Clients und Integrationen fehl.
Mögliche Ursache: Die API subdomain bildet die Basis-API-URL für jede API in der Organisation, daher wird durch das Ändern die URL aller API Manager APIs der Organisation neu geschrieben. Jeder Client oder jede Integration, der/die noch die vorherige URL aufruft, schlägt fehl.
Lösung:
1. Notiere in den Organisationsdetails die aktualisierte Basis-URL, die im Feld Base API URL preview angezeigt wird.
2. Aktualisiere alle Integrationen, Client-Anwendungen und Webhook-Konfigurationen, die die vorherige Basis-API-URL referenzieren.
3. Um Störungen zu vermeiden, plane Änderungen der Subdomain während eines Wartungsfensters und benachrichtige alle API-Consumer im Voraus.

Der Zugriff eines externen Benutzers auf das API Portal läuft zu einem unerwarteten Zeitpunkt ab

Symptom: Der Zugriff eines externen Benutzers auf das API Portal läuft früher oder später ab als der Administrator aufgrund des konfigurierten Datums erwartet.
Mögliche Ursache: Der Zugriff eines externen Benutzers läuft um 23:59 Uhr an dem ausgewählten Ablaufdatum in der Ortszeit des externen Benutzers ab. Wenn sich der Benutzer und der Administrator in verschiedenen Zeitzonen befinden, unterscheidet sich der effektive Ablaufzeitpunkt von dem, was der Administrator auf dem Konfigurationsbildschirm sieht.
Lösung:
- Berücksichtigen Sie beim Festlegen eines Ablaufdatums für einen externen Benutzer auf der Seite Benutzerverwaltung die Ortszeit des Benutzers bei der Auswahl des Datums.
- Um den Zugriff zu erweitern, bearbeiten Sie das Datum Zugriff läuft ab des Benutzers, bevor das aktuelle Datum abläuft.

Umgebungsänderungen werden nicht in Harmony-Anwendungen angezeigt

Symptom: Nach dem Vornehmen von Änderungen an einer Umgebung in der Management Console werden die Änderungen nicht in Studio oder anderen Harmony-Anwendungen angezeigt.
Lösung: Melden Sie sich vom Harmony-Portal ab und melden Sie sich erneut an. Umgebungsänderungen werden möglicherweise erst auf andere Harmony-Anwendungen übertragen, nachdem die Sitzung aktualisiert wird.

SSO-Konfiguration erfordert sowohl WMC- als auch Studio-Clients

Symptom: Die Harmony Single Sign-On (SSO)-Authentifizierung schlägt fehl oder funktioniert nur für einige Harmony-Anwendungen, nachdem ein SSO-Identitätsanbieter konfiguriert wurde.
Ursache: Harmony SSO erfordert, dass zwei separate Clientanwendungen im Identitätsanbieter konfiguriert werden: WMC (für das Harmony-Portal und alle Webanwendungen) und Studio (für Design Studio). Wenn nur ein Client konfiguriert wird, bleibt die andere Anwendung ohne SSO-Unterstützung.
Lösung: Konfigurieren Sie beide Clientanwendungen WMC und Studio in der Schublade SSO konfigurieren, auch wenn Sie Design Studio nicht verwenden. Für BMC-Kunden ist nur WMC erforderlich.

SSO-Umgehungsliste: Vorhandene Organisationsmitglieder können nicht direkt hinzugefügt werden

Symptom: Das Hinzufügen eines aktuellen Mitglieds einer SSO-fähigen Organisation zu deren SSO umgehen-Liste schlägt fehl, oder der Benutzer kann SSO immer noch nicht umgehen, nachdem er hinzugefügt wurde.
Ursache: Ein Benutzer muss zur Liste SSO umgehen hinzugefügt werden, bevor er der Organisation hinzugefügt wird. Ein Benutzer, der bereits Mitglied der Organisation ist, kann daher nicht direkt zu dessen Liste SSO umgehen hinzugefügt werden.
Lösung:
1. Entfernen Sie den Zugriff des Benutzers auf die Organisation.
2. Fügen Sie die E-Mail-Adresse des Benutzers zur Liste SSO umgehen hinzu.
3. Fügen Sie den Benutzer erneut zur Organisation hinzu.

SSO kann nicht aktiviert werden: Benutzer gehört zu mehreren Organisationen

Symptom: Das Aktivieren von Harmony Single Sign-On (SSO) für eine Harmony-Organisation schlägt mit dem folgenden Fehler fehl:
```
SSO_CANNOT_BE_ENABLED_FOR_MEMBERS_ASSOCIATED_WITH_MULTIPLE_ORGS
```
Mögliche Ursache: Ein oder mehrere Benutzer in der Organisation sind auch Mitglieder anderer Harmony-Organisationen, beispielsweise Test-Organisationen oder Cloud Data Loader-Organisationen.
Lösung:
1. Überprüfen Sie die Benutzerliste der Organisation in der Management Console, um Benutzer zu identifizieren, die zu mehr als einer Harmony-Organisation gehören.
2. Für jeden betroffenen Benutzer wählen Sie eine der folgenden Optionen:
  - Entfernen Sie ihn aus den anderen Organisationen, zu denen er gehört (einschließlich Harmony-Test- oder Cloud Data Loader-Organisationen), oder aus dieser Organisation, damit er nur zu einer Harmony-Organisation gehört.
  - Damit der Benutzer in mehreren Organisationen bleiben kann, fügen Sie ihn zur Liste SSO umgehen hinzu, die ihn von SSO ausschließt, damit er sich mit seinen Harmony-Anmeldedaten anmeldet. Da ein aktuelles Mitglied nicht direkt zur Liste hinzugefügt werden kann, entfernen Sie zunächst seinen Zugriff auf diese Organisation, fügen Sie ihn zur Liste SSO umgehen hinzu und fügen Sie ihn dann erneut hinzu.
Versuchen Sie die SSO-Konfiguration erneut, nachdem alle betroffenen Benutzer gelöscht oder zur Bypass-SSO-Liste hinzugefügt wurden.

SSO-Anmeldung leitet in einer Schleife um ohne Fehlermeldung

Symptom: Ein Benutzer, der sich über Single Sign-On (SSO) (z. B. mit Azure) bei Harmony anmeldet, wird kontinuierlich ohne Fehlermeldung auf die Anmeldeseite zurückgeleitet.
Mögliche Ursache: Ein veralteter Browser-Cache oder Cookies beeinträchtigen den SSO-Authentifizierungsfluss.
Lösung:
- Löschen Sie den Browser-Cache und alle Jitterbit-bezogenen Cookies, und versuchen Sie es erneut.
- Versuchen Sie sich in einem Inkognito- oder privaten Browserfenster anzumelden, um zwischengespeicherte Daten zu umgehen.
- Versuchen Sie einen anderen Browser, um Browser-spezifische Kompatibilitätsprobleme auszuschließen.

Das Löschen des Cloud-Datastore-Speichers schlägt mit der Fehlermeldung „cannot be excluded" fehl

Symptom: Das Löschen eines Cloud-Datastore-Statusspeichers oder Schlüsselspeichers schlägt fehl mit:

Failed to delete storage: <storage name> - Storage with ID <storage ID> cannot be excluded because it contains items.

Lösung: Löschen Sie alle Daten (z. B. Register) im Speicher, bevor Sie den Speicher selbst löschen, und versuchen Sie dann erneut, den Speicher zu löschen.

OAuth-Refresh-Token-Ablauf führt zu Fehler bei verbundenen Operationen

Symptom: Operationen, die einen Connector mit 3-legged OAuth 2.0 (3LO) authentifizieren, funktionieren nach einiger Zeit nicht mehr, mit Authentifizierungsfehlern wie Connector could not retrieve the access token to be used in the HTTP call oder einer Nachricht vom Identity Provider, dass das Refresh-Token ungültig gemacht oder bereits ausgetauscht wurde. Die Verbindung funktioniert häufig unmittelbar nach der Authentifizierung und schlägt dann bei einer späteren Ausführung fehl.
Mögliche Ursachen:
- Eine Token-Richtlinie auf der Seite App-Registrierungen der Management Console hat Enable refresh token expiration oder Enable refresh token inactivity expiration konfiguriert, sodass alle Operationen, die von dieser Verbindung abhängen, zur Laufzeit fehlschlagen, wenn das Token abläuft.
- Die Verbindung war länger untätig als die Lebensdauer des Refresh-Tokens des Identity Providers. Wie in den 3LO-Wichtigen Hinweisen beschrieben, werden Refresh-Tokens nur verwendet, wenn eine Operation Zugriff auf den Endpunkt benötigt: Der Connector erneuert das Access-Token reaktiv, wenn eine Operation ausgeführt wird, nicht durch einen Hintergrundprozess oder eine eigenständige geplante Token-Aktualisierung. Wenn keine Operation innerhalb der Lebensdauer des Refresh-Tokens auf den Endpunkt zugreift (was einige Provider auf nur 24 Stunden festlegen), läuft das Refresh-Token selbst ab und die Token-Kette wird unterbrochen, auch wenn Enable rotating refresh token ausgewählt ist.
- Die gleiche App-Registrierung und Benutzeranmeldeinformationen werden für 3LO in mehr als einem Projekt oder Endpunkt verwendet. Bei ausgewähltem Enable rotating refresh token gibt jede Token-Aktualisierung ein neues Refresh-Token aus und macht das vorherige ungültig. Wenn die freigegebenen Anmeldeinformationen an einer Stelle erneut authentifiziert oder aktualisiert werden, wird das Refresh-Token, das die anderen Operationen verwenden, ungültig gemacht, sodass diese Operationen fehlschlagen.
Lösung:
- Wenn eine Token-Richtlinie-Ablaufeinstellung die Ursache ist, überprüfen Sie die Richtlinie für die betroffene App-Registrierung, erneuern Sie das Refresh-Token über den Authentifizierungsfluss des Connectors, und aktivieren Sie Receive Expiration Notification in den Verbindungseinstellungen, um vor dem nächsten Ablauf des Tokens rechtzeitig benachrichtigt zu werden.
- Wenn ein Leerlaufzeitraum die Ursache ist, stellen Sie sicher, dass eine Operation, die die Verbindung verwendet, innerhalb der Lebensdauer des Refresh-Tokens ausgeführt wird. Das Planen einer eigenständigen Token-Aktualisierung, um ein Token aktiv zu halten oder einen Leerlaufzähler zurückzusetzen, wird nicht unterstützt (siehe 3LO-Wichtige Hinweise): Das Token wird nur als Nebeneffekt einer Operation erneuert, die tatsächlich auf den Endpunkt zugreift. Um dieses unterstützte Verhalten zu nutzen, fügen Sie eine einfache Operation nach einem wiederkehrenden Operationszeitplan hinzu, die einen einfachen Endpunkt in einem Intervall aufruft, das kürzer als die Lebensdauer des Refresh-Tokens ist (z. B. alle zwei Stunden), und verwendet denselben Connector und dieselbe App-Registrierung wie Ihre Hauptoperationen. Diese Operation sendet eine echte Anfrage an den Endpunkt, sodass jede Ausführung die Tokens als Teil der normalen Verwendung erneuert. Pro App-Registrierung ist nur eine solche Operation erforderlich. Wenn der Identity Provider dies zulässt, können Sie auch die Lebensdauer des Refresh-Tokens verlängern.
- Wenn mehr als ein Projekt oder Endpunkt die gleiche App-Registrierung und den gleichen Benutzer verwendet, geben Sie jedem eine eigene App-Registrierung (oder einen eigenen Benutzer), damit ihre Token-Ketten sich nicht gegenseitig ungültig machen, und vermeiden Sie eine erneute Authentifizierung der freigegebenen Verbindung, während andere Operationen davon abhängen.

Audit Log API: Token-Abruf schlägt fehl, wenn TFA aktiviert ist

Symptom: Eine Anfrage an die User Service Controller API zum Abrufen eines Authentifizierungstokens für die Audit Log Service API gibt einen Fehler zurück.
Ursache: Wenn die Zwei-Faktor-Authentifizierung (TFA) für die Organisation aktiviert ist, schlägt ein standardmäßiger Token-Abruf mit einer Anfrage fehl. TFA erfordert einen zweistufigen Authentifizierungsablauf.
Lösung: Folgen Sie dem TFA-Token-Abrufverfahren, um das Authentifizierungstoken mit dem zweistufigen Ablauf zu erhalten.

Das Hinzufügen eines externen Benutzers schlägt mit einem Fehler `409 conflict` fehl

Symptom: Das Hinzufügen eines externen Benutzers auf der Seite Benutzerverwaltung der Management Console schlägt fehl mit:
```
Failed to create new external user - 409 conflict error
```
Mögliche Ursache: Ein Benutzer mit dieser E-Mail-Adresse existiert bereits im Benutzersystem von Jitterbit, daher kann der externe Benutzer nicht erneut erstellt werden, auch wenn der Benutzer in der Zielorganisation nicht sichtbar ist.
Lösung: Kontaktieren Sie den Jitterbit-Support mit der E-Mail-Adresse. Das vorhandene Konto muss möglicherweise auf Plattformebene abgestimmt oder neu zugewiesen werden, bevor der externe Benutzer hinzugefügt werden kann.

Organisation-Region kann nicht vor Ort geändert werden

Symptom: Eine Organisation muss in eine andere Harmony-Region umziehen (z. B. von NA zu EMEA), um Anforderungen zur Datenspeicherung oder Compliance zu erfüllen, aber es gibt keine Einstellung zum Ändern der Region einer vorhandenen Organisation.
Mögliche Ursache: Die Region einer Organisation ist bei der Erstellung festgelegt. Harmony unterstützt keine Änderungen der Region vor Ort.
Lösung:
1. Erstellen Sie eine neue Harmony-Organisation in der Zielregion.
2. Exportieren Sie jedes Integrationsprojekt aus der Quellorganisation und importieren Sie es in die neue Organisation.
3. Konfigurieren Sie in der neuen Organisation umgebungsspezifische Einstellungen, Verbindungen, Zeitpläne, Projektvariablen und Sicherheitsprofile neu.
4. Aktualisieren Sie externe Clients, Integrationen oder Webhook-Konfigurationen so, dass sie auf die API-URLs der neuen Region verweisen.
5. Für eine koordinierte Migration kontaktieren Sie den Jitterbit-Support oder Professional Services, um den zeitlichen Ablauf zu planen und Ausfallzeiten zu minimieren.

Integration und Automatisierung

In diesem Abschnitt werden Probleme beim Verbinden mit externen Systemen, beim Transformieren und Verarbeiten von Daten und beim Ausführen von Integrationsvorgängen sowie mit den Agents, die diese ausführen, behandelt.

Vorgänge im Status „Submitted" oder „Running" feststecken

Symptom: Eine Operation wird nicht wie erwartet abgeschlossen. Sie bleibt im Status Submitted oder Running stecken und macht keinen Fortschritt, oder wird mit der Meldung abgebrochen:
```
Long running operation canceled by System
```
Der Abbruch kann erfolgen, nachdem die Operation eine Zeit lang ausgeführt wurde, oder kurz nach ihrem 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 bricht sie möglicherweise ab, als ob sie hängend wäre, auch wenn die Operation auf dem Agent abgeschlossen wurde. Dies kann Operationen betreffen, die normalerweise in Sekunden abgeschlossen sind.
- Die Operation wurde abgeschlossen, aber der endgültige Status wurde nicht an Harmony zurückgemeldet, daher wird sie weiterhin als Running angezeigt, bis sie ausläuft.
- Die Agent-Gruppe ist stark ausgelastet und verzögert sich beim Abholen oder Aktualisieren von Operationen in der Warteschlange.
- Die Operation steckt speziell im Status Submitted fest: Die Ausführungsmitteilung wurde in die Warteschlange eingereiht, aber kein Agent in der Gruppe hat sie akzeptiert, da die Agents offline, fehlerhaft oder keine freie Kapazität haben, um neue Operationen zu akzeptieren (z. B. ist jeder Worker-Thread beschäftigt).
Lösung:
- Bei privaten Agenten müssen Sie bestätigen, dass der Agent den Status Running auf der Seite Agents in der Management Console hat. Überprüfen Sie die Protokolle des privaten Agenten auf Verbindungsprobleme und stellen Sie sicher, dass die Netzwerkverbindung zwischen dem Agent und der Harmony-Plattform stabil ist.
- Überprüfen Sie die Vorgangsprotokolle, um zu bestätigen, was während der Ausführung passiert ist. Die Abbruchmeldung kann auch bei Vorgängen angezeigt werden, die nur kurz ausgeführt wurden. Dies deutet daher nicht unbedingt auf einen tatsächlich lange laufenden Vorgang hin. Die Protokolle können auch einen spezifischen Fehler offenbaren, z. B. 401 Unauthorized (Anmeldedaten überprüfen) oder 429 Too Many Requests. Ein 429 von einem Zielendpunkt kann durch Reduzierung der Anfragerate oder durch Hinzufügen von Wiederholungslogik verringert werden. Ein 429 vom von Jitterbit verwalteten Cloud-API-Gateway ist das Plattformlimit von 200 Anfragen pro Minute. Verteilen Sie daher die Aufrufe zeitlich oder führen Sie die betroffenen APIs auf privaten Agenten aus.
- Halten Sie private Agenten auf einer aktuellen Version. Neuere Agent-Versionen verbessern die Agent-Stabilität und reduzieren vorzeitige Abbrüche von Vorgängen.
- Versuchen Sie, die betroffenen Vorgänge abzubrechen. Der Abbruch ist für Vorgänge mit dem Status Submitted, Received, Pending oder Running verfügbar. Dies können Sie von der Seite Runtime in der Management Console, aus der Vorgangsprotokolltabelle oder vom Runtime-Status eines Vorgangs auf der Design-Canvas aus durchführen.
- Falls der betroffene Vorgang nach einem Zeitplan ausgeführt wird und nie startet, lesen Sie Geplante Vorgänge werden nicht ausgeführt.
- Falls die Vorgänge nicht abgebrochen werden können, falls das Problem erneut auftritt oder falls viele Vorgänge gleichzeitig betroffen sind, wenden Sie sich an den Jitterbit-Support. Diese Fälle erfordern möglicherweise eine Lösung auf Serverseite.

Hinweis

Die Einstellung MaxOperationRuntimeSeconds im Abschnitt [ProcessEngine] der jitterbit.conf-Datei des privaten Agenten begrenzt nur die Dauer der Ausführung eines Vorgangs, nachdem ein Agent mit der Ausführung begonnen hat. Sie hat daher keine Auswirkung auf Vorgänge, die sich noch in der Submitted-Warteschlange befinden. Die Vorgangseinstellung Operation Time Out begrenzt die Gesamtausführungszeit eines Vorgangs, kann aber nicht nur auf den Submitted-Status beschränkt werden. Wenn Sie diese Einstellung senken, um einen schnellen Abbruch zu erzwingen, werden auch Vorgänge abgebrochen, die noch legitim ausgeführt werden. Um in Submitted steckengebliebene Vorgänge zu löschen, stellen Sie die Agent-Kapazität und -Gesundheit wieder her, damit die Warteschlangen-Laufzeitnachrichten abgerufen werden, anstatt einen Timeout anzupassen.

Geplante Vorgänge werden nicht ausgeführt

Symptom: Ein Vorgang mit einem Operationszeitplan wird zur geplanten Zeit nicht ausgeführt oder wird versendet, bleibt aber in einem Status Pending oder Received stehen.
Mögliche Ursachen:
- Der Zeitplan wurde dem Vorgang in Studio zugewiesen, aber das Projekt wurde nicht bereitgestellt. In Studio zugewiesene Zeitpläne werden erst nach der Bereitstellung des Projekts wirksam.
- Der Zeitplan ist deaktiviert.
- Es liegt eine Fehlkonfiguration der Zeitzone in den Zeitplaneinstellungen vor.
- Bei privaten Agenten wird der Planungsdienst nicht ausgeführt.
- Der der Umgebung zugeordnete Agent ist offline oder fehlerhaft.
- Änderungen, die für ein Projekt bereitgestellt wurden, haben sich noch nicht vollständig mit dem Agent synchronisiert.
- Die Agent-Gruppe ist ressourcengesättigt. Ein Rückstau von lang laufenden Vorgängen oder eine anhaltend hohe CPU- oder Speichernutzung kann verhindern, dass eine Agent-Gruppe geplante Vorgänge rechtzeitig aufnimmt.
Lösung:
- Bestätigen Sie, dass das Projekt bereitgestellt wurde, seit der Zeitplan dem Vorgang zugewiesen wurde.
- Bestätigen Sie, dass der Zeitplan aktiviert ist. Zeitpläne können nur auf der Seite Projects in der Management Console aktiviert oder deaktiviert werden, und zwar auf den Registerkarten Operations und Schedules.
- Überprüfen Sie die Zeitplankonfiguration und achten Sie besonders auf die Zeitzoneneinstellung. Details finden Sie unter Operation time zones.
- Bei privaten Agenten überprüfen Sie, 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. Unter Windows überprüfen Sie im Task Manager, ob Jitterbit Scheduler und Jitterbit Scheduler Service ausgeführt werden. Unter Linux und Docker verwenden Sie den Befehl jitterbit status.
- Stellen Sie das Projekt erneut bereit, um die Neusynchronisierung des Zeitplans mit dem Agent zu erzwingen.
- Falls Vorgänge im Status Pending steckenbleiben, brechen Sie diese über die Seite Runtime in der Management Console ab und starten Sie den Agent-Dienst neu.
- Falls Zeitplanverluste mit der Last korrelieren, reduzieren Sie die Anzahl der gleichzeitigen lang laufenden Vorgänge. Überprüfen Sie auf privaten Agenten auch die CPU- und Speichernutzung und gleichen Sie geplante Vorgänge an die Kapazität des Agenten an (ein privater Agent kann bis zum Doppelten seiner CPU-Kernanzahl gleichzeitige Vorgänge ausführen).
- Falls ein geplanter Vorgang versendet wird, dann aber steckenbleibt, anstatt nie zu starten, lesen Sie Operations stuck in Submitted or Running state.

Wörterbuch oder globale Variable ist leer, nachdem ein Vorgang asynchron ausgeführt wird

Symptom: Ein Wörterbuch oder eine globale Variable, die in einer untergeordneten Operation gefüllt wurde, ist leer oder behält ihren früheren Wert, wenn die übergeordnete Operation sie nach dem asynchronen Aufrufen liest.
Mögliche Ursache: Wenn eine Operation asynchron aufgerufen wird (das Run type des Invoke Operation-Tools auf Asynchronously gesetzt oder RunOperation mit runSynchronously auf false aufgerufen), 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 thread-sicher. Daher werden Änderungen in der untergeordneten Operation nicht in der übergeordneten Operation berücksichtigt. Die übergeordnete Operation kann den Wert auch lesen, bevor die untergeordnete Operation abgeschlossen ist. Für das entsprechende Verhalten in aufgeteilten Multi-Thread-Operationen siehe Variablenupdates verloren in aufgeteilten Multi-Thread-Operationen.
Lösung:
- Wenn die übergeordnete Operation von Werten abhängt, die die untergeordnete Operation erzeugt, rufen Sie die untergeordnete Operation synchron auf (das Run type des Invoke Operation-Tools auf Synchronously gesetzt oder RunOperation synchron ausgeführt, was die Standardeinstellung ist), damit die untergeordnete Operation abgeschlossen wird und ihre globalen Variablenänderungen von der übergeordneten Operation geerbt werden.
- Um Daten zwischen Operationen gemeinsam zu nutzen, 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.
- Eine feste Verzögerung einfügen (z. B. mit der Sleep-Funktion) erhöht die Latenz und garantiert nicht, dass die untergeordnete Operation abgeschlossen ist. Führen Sie die Operation stattdessen synchron aus.

504 Gateway Timeout (API-ausgelöste Vorgänge)

Symptom: API-Aufrufe über das Cloud- oder Private-API-Gateway geben 504 Gateway Timeout zurück, normalerweise nach dem Timeout-Fenster des Gateways (30 bis 180 Sekunden).
Ursache und Lösung: Der zugrunde liegende Vorgang überschreitet das Timeout des API-Gateways, oder die Anfrage kann keinem verfügbaren Agent zugewiesen werden. Weitere Informationen zu den vollständigen Ursachen und Lösungen finden Sie unter HTTP 504 Gateway Timeout.

507 Speicher unzureichend

Symptom: Ein API-Aufruf gibt Folgendes zurück:
```
507 Insufficient Storage
```
Mögliche Ursachen:
- Der Agent oder die Gateway-Host verfügt über keinen Speicherplatz mehr.
- Bei einem Private-API-Gateway kann das Gateway seine gehostete Payload- oder Antwortdatei nicht öffnen und gibt einen 507 zurück, auch wenn ausreichend Speicherplatz verfügbar ist. Dies deutet in der Regel auf ein Problem mit der Registrierung der privaten Domain oder mit der Gateway-Konfiguration hin.
Lösung:
- Stelle sicher, dass der Agent oder die Gateway-Host über ausreichend freien Speicherplatz verfügt.
- Wenn ausreichend Speicherplatz vorhanden ist und die API über ein Private-API-Gateway bereitgestellt wird, siehe Private Gateway gibt HTTP 507 oder „No such file or directory" zurück 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-Dienst hat keine vollständige Antwort auf die Anforderung zurückgegeben, was zu einem 502 führt. Dieser Fehler ist in der Regel vorübergehend und kann möglicherweise nicht reproduziert werden.
Lösung:
1. Wiederhole den Vorgang.
2. Wenn der Fehler weiterhin auftritt, wende dich an den Jitterbit-Support.

Fehler beim Erstellen eines temporären Verzeichnisses

Symptom: Ein Operation schlägt beim Erstellen eines temporären Verzeichnisses fehl und gibt eine Fehlermeldung wie die folgende aus:
```
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 im Pfad der temporären Dateien, oder die Festplatte ist voll.
- Bei einer Cloud-Agent-Gruppe liegt die Ursache auf der Seite des von Jitterbit verwalteten Agents und nicht in deinem Projekt oder in der Konfiguration.
Lösung:
- Bei privaten Agents bestätigst du, dass das Agent-Dienstkonto ausreichende Berechtigungen im Pfad der temporären Dateien (/tmp oder TemporaryFiles) hat, und überprüfst, dass der Agent-Host ausreichend freien Speicherplatz hat.
- Bei Cloud-Agent-Gruppen deutet dies auf ein Problem auf der Agent-Seite hin, das Jitterbit behebt. Kontaktiere Jitterbit Support und gib die Fehlermeldung und den Zeitpunkt der Fehler an.

Operationsprotokolle auf etwa 100 KB gekürzt

Symptom: Eine Operation-Protokollmeldung erscheint abgeschnitten und endet mit message truncated. Dies kann in den Operation-Protokollen oder beim Anzeigen eines Operation-Protokolleintrags auf der Seite API-Protokolle des API Manager angezeigt werden.
Mögliche Ursache: Operation-Protokollmeldungen, die ca. 100 KB (ca. 99.000 Zeichen) überschreiten, werden gekürzt. Der Kürzungspunkt ist am Ende der Meldung mit message truncated gekennzeichnet.
Lösung: Falls du den vollständigen Protokollinhalt benötigst, reduzierst du die Ausführlichkeit der Protokollierung der Operation oder teilst die Operation in kleinere Einheiten auf, die kürzere Protokollmeldungen erzeugen.

Das Debugging-Protokoll für Operationen enthält personenbezogene Daten und Anmeldeinformationen im Klartext

Symptom: Sensible Daten, Anmeldeinformationen oder personenbezogene Informationen (PII) werden in den Harmony-Cloud-Protokollen angezeigt.
Mögliche Ursache: Wenn das Debug-Protokoll der Operation für eine Operation aktiviert ist, werden alle Request- und Response-Daten 30 Tage lang im Klartext in der Harmony-Cloud gespeichert.
Lösung:
- Verwende das Debug-Protokoll der Operation nur in kontrollierten, produktionsfremden Umgebungen oder während einer begrenzten Diagnosephase.
- Um die Generierung von Komponenteneingabe- und -ausgabedaten für eine private Agent-Gruppe zu deaktivieren, stellst du verbose.logging.enable=false im Abschnitt [VerboseLogging] der Agent-Konfigurationsdatei ein.

Verbindungsfehler bei der privaten Agent-Datenbank

Symptom: Operationen schlagen mit folgendem Fehler fehl:

Failed to connect to back-end database 'TranDb'

FATAL: query_wait_timeout

Mögliche Ursache: Die interne PostgreSQL-Datenbank des privaten Agenten ist nicht verfügbar oder der Verbindungspool ist erschöpft.
Lösung: Siehe TranDb-Verbindungsfehler für vollständige Lösungsschritte.

Clientzertifikat lässt sich auf Linux-Private-Agenten nicht laden

Symptom: Eine Operation, die einen ausgehenden gegenseitigen TLS-Webservice-Aufruf (Client-Zertifikat) tätigt, schlägt bei der Ausführung 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 bei der Ausführung fehl. Dieselbe Konfiguration hat möglicherweise zuvor auf einem Windows-Privatagenten funktioniert.
Mögliche Ursachen:
- Der Betriebssystembenutzer, der den Jitterbit-Agenten ausführt, hat keine Leseberechtigung für die Datei mit privatem Schlüssel oder deren übergeordnete Verzeichnisse.
- Ein Linux-Sicherheitsmodul wie SELinux oder AppArmor blockiert den Zugriff des Agenten auf die Datei mit privatem Schlüssel.
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.
- Prüfen Sie, ob SELinux oder AppArmor den Zugriff auf die Schlüsseldatei einschränkt, und passen Sie die Richtlinie oder den Dateikontexte entsprechend an.

Validierungsfehler für Operationen

Operationen müssen gültig sein, bevor sie bereitgestellt werden können. Die vollständige Liste der Validierungsfehlermeldungen und ihre Lösungen finden Sie unter Validierungsfehler für Operationen im Leitfaden zur Operationsfehlerbehebung.

Komponentennamen müssen nach dem Projektimport eindeutig sein

Symptom: Nach dem Importieren eines Projekts aus einer JSON-Exportdatei werden eine oder mehrere Komponenten als ungültig angezeigt, 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 die Erstellung von doppelten 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 roter Kursivschrift 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 nach der Behebung aller Fehler mit doppelten Namen erneut bereit.
5. Um nur ausgewählte Komponenten in ein vorhandenes Projekt zu importieren, verwenden Sie den selektiven Import, der Konflikte mit gleichnamigen Komponenten im Zielproject kennzeichnet und Ihnen ermöglicht, diese zu ersetzen oder beides beizubehalten.

Connector nur für Private Agent blockiert den Import in eine Cloud-Agent-Umgebung

Symptom: Das Importieren oder Migrieren eines Projekts in eine mit einer Cloud-Agent-Gruppe verknüpfte Umgebung wird blockiert, da das Projekt einen Connector verwendet, der nur für private Agents verfügbar ist. Die Meldung führt die Connectoren auf, die nur für private Agents verfügbar sind und für das Problem verantwortlich sind. Ein vollständiger Projektimport zeigt Folgendes 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 zum 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 Agents verfügbar sind. Die Spalte Agent-Verfügbarkeit in der Connectorliste zeigt an, welche Connectoren nur für private Agents verfügbar sind. Cloud-Agents 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 mit einer privaten Agent-Gruppe verknüpfte Umgebung, auf der der erforderliche Connector installiert ist.
- Wenn das Projekt auf Cloud-Agents ausgeführt werden muss, ersetzen Sie die Connector-Aktivitäten, die nur für private Agents verfügbar sind, durch Cloud-kompatible Connectoren (wie HTTP v2 für REST-APIs oder der Database-Connector mit einem Cloud-zugänglichen Endpunkt), bevor Sie das Projekt importieren.

Zielschleifenknoten mehreren Quellenschleifenknoten zugeordnet

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 verfügt über Feldzuordnungen, 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 in der Fehlermeldung angegebenen Zielschleifenknoten.
2. Überprüfen Sie die Zuordnungen unter diesem Knoten, um zu bestätigen, dass alle zugeordneten Felder aus demselben Quellschleifenknoten stammen.
3. Wenn Daten aus mehreren Quellknoten erforderlich sind, verarbeiten oder zusammenführen Sie die zusätzlichen Quelldaten vor der Transformation in einem Skriptschritt vor, sodass ein einzelner einheitlicher Quellknoten den Zielschleifenknoten speist.
4. Weitere Informationen zu gültigen Zuordnungsmustern finden Sie unter Transformationszuordnungsgültigkeit.

Erweiterte Konfigurationseigenschaften: Variablen mit unverarbeiteter JSON müssen mit Escape-Zeichen versehen werden

Symptom: Viele Connectors enthalten eine Tabelle Advanced Configurations Properties für optionale Verbindungseinstellungen. Variablen, die in diesen Feldern verwendet werden und unformatierten JSON enthalten, müssen das JSON maskiert haben. Das Übergeben von unmaschiertem unformatierten JSON über eine Variable führt dazu, dass der Feldwert malformed ist.
Mögliche Ursache: Felder in der Tabelle Advanced Configurations Properties unterstützen keine Variablen, die unformatierte JSON-Objekte enthalten.
Lösung:
- Bevor JSON-Inhalt über eine Variable in ein Feld Advanced Configurations Properties übermittelt wird, maskieren Sie das JSON. Beispiel: {"success": "true"} muss als {\"success\": \"true\"} maskiert werden, bevor es der Variablen zugewiesen wird.
- Wenn Sie den JSON-Wert direkt in das Feld eingeben (nicht über eine Variable), ist eine Maskierung nicht erforderlich.
- Variablen in Feldern Advanced Configurations Properties werden erst zur Laufzeit auf Agent-Version 10.75 / 11.13 oder später gefüllt. Wenn ein Variablenwert zur Laufzeit nicht angezeigt wird, bestätigen Sie, dass der Agent diese Mindestversion erfüllt.

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

Symptom: Character-Data-Abschnitte (CDATA) werden in XML, das in JSON eingebettet ist und durch eine Transformation verarbeitet wird, nicht unterstützt. Falls 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[ ... ]]>), durch ihre Escaped-Entsprechungen (&, <, >, ', ") zu Replace. Wenn eine Beschränkung auf nur den CDATA-Abschnitt nicht möglich ist, kann die gesamte XML-Zeichenfolge, die ihn enthält, ersetzt werden.

Das folgende Beispiel wird ohne diese Replacements als ungültig betrachtet:
```
{
  "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 Zeichenfolge die maximal zulässige Länge überschreitet, z. B.:
```
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 aktivierter Option Get response content in base64 string: Die Base64-Codierung vergrößert Binärinhalte (z. B. Audio- oder Mediendateien), daher kann die codierte Zeichenfolge die Grenze überschreiten, auch wenn die Originaldatei 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 dieser ist, schlägt beim Parsen durch den Agent fehl, bevor nachgelagerte Aktivitäten (z. B. ein Upload) ausgeführt werden.
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 50-MB-Grenze), und starten Sie den Agent neu. Dieser Schlüssel ist in Agent-Version 12.5 und später verfügbar. Führen Sie daher zunächst ein Upgrade durch, falls der Agent eine frühere Version hat.

Sonderzeichen in Connector-bereitgestellten JSON-Schemata

Symptom: Wenn eine Transformation ein von einer angrenzenden Connector-Aktivität geerbtes JSON-Schema verwendet, werden alle Sonderzeichen in einem Schemafeld- oder Knotennamen durch Unterstriche (_) ersetzt. Wenn Sie die Legacy-JSON-Verarbeitung verwenden (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 dem entsprechen, was er erwartet.

Wenn beispielsweise die Aktivität ein Feld mit dem Namen location_ids[] bereitstellt, wird dieses in location_ids__ konvertiert. Falls der Endpunkt immer noch den ursprünglichen Namen erwartet, kann er einen Fehler wie den folgenden zurückgeben:

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

Lösung:
1. Bestätigen Sie, dass in der betroffenen Aktivität ein JSON-Schema verwendet wird. Solche Schemas haben einen Stammknoten mit dem Namen json:
2. Aktivieren Sie die JSON-Namen beibehalten Projekteinstellung (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 Option zuvor deaktiviert war, gilt die neue Verarbeitungsmethode nur für Vorgänge und Schemas, die nach Aktivierung der Einstellung konfiguriert werden. Vorhandene Vorgänge und Schemas verwenden weiterhin die Legacy-JSON-Verarbeitung. Um Inkonsistenzen innerhalb eines Projekts zu vermeiden, konfigurieren Sie alle vorhandenen Vorgänge und Schemas erneut, nachdem Sie diese Einstellung aktiviert haben.

Überprüfen Sie zur Überprüfung des an den Endpunkt gesendeten Feldnamens den Wert jsonPropertyName in den Ein- oder Ausgabedaten der Aktivität mit Debug-Protokollierung aktiviert:

Mehrbyte-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 zu SÃ£o LuÃs). In der Regel ist nur ein Multibyte-Zeichen betroffen, das nach ungefähr den ersten 8 KB der Antwort erscheint; dasselbe 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 Zeichencodierungserkennung nur der Anfang der Antwort verwendet, um ihre Codierung zu bestimmen. Wenn dieses Beispiel nur ASCII-Zeichen enthält, wird die Antwort als Latin-1 (ISO-8859-1) statt als 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 Schemata 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 Problem mit einer Substitutionsgruppe hin.
Lösung: Falls 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.).

Das 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 dem folgenden fehl:
```
Failed to initialize transformation "<transformation name>". Failed to expand the target tree for the path: <path to node>. The node: <node name> cannot be created.
```

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

Mögliche Ursache: Beim Importieren einer Zuordnungsdatei, die doppelte Knoten zum Zielschema hinzugefügt hat, wurde die entsprechende Änderung nicht auf die Schemadefinition angewendet, die bei der Ausführung des Vorgangs verwendet wird, wodurch die beiden nicht synchronisiert wurden. 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 die Funktion Alle Zuordnungen unter diesem Knoten entfernen auf dem Stammknoten, um alle Zuordnungen zu entfernen, und importieren Sie die Zuordnungsdatei erneut. Durch das erneute Importieren wird die bei der Laufzeit verwendete Schemadefinition mit der Zuordnung neu synchronisiert. Falls der Fehler weiterhin besteht, konfigurieren Sie die Aktivität neu, die das Schema bereitstellt, und aktualisieren Sie das Schema in der Transformation.

Zusätzliche Unterelementwarnung in Operationsprotokollen

Symptom: Eine extra subelement-Meldung in den Operationsprotokollen ist eine Warnung, keine Fehler, 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 Antwortdatenschema definiert sind.
Lösung: Falls Sie die zusätzlichen Daten erfassen möchten, aktualisieren Sie das Schema, um die zusätzlichen Felder einzubeziehen.

Wiederholungsgrenzwert für Skriptschleife überschritten

Symptom: Ein Skript schlägt mit einem Fehler fehl, der 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:
- Die Skriptlogik überprüfen, um festzustellen, ob die Schleife optimiert werden kann, um die Anzahl der Iterationen zu verringern.
- Für JavaScript-Skripte auf privaten Agenten kann das Pro-Skript-Limit erhöht werden, indem JavaScriptMaxIterations=X (wobei X größer als 50000 ist) zum [Settings]-Bereich der Konfigurationsdatei des privaten Agenten hinzugefügt wird.
- Für Jitterbit Script auf privaten Agenten kann das Limit erhöht werden, indem jitterbit.scripting.while.max_iterations auf einen Wert größer als 50000 gesetzt wird.

`RunOperation` wird nach 50 synchronen Aufrufen in einer `While`-Schleife nicht mehr ausgeführt

Symptom: Nach einem Upgrade eines privaten Agenten auf Version 12.11 oder später verarbeitet ein Skript, das RunOperation, RunOperationFromProject oder ReRunOperation synchron innerhalb einer While-Schleife aufruft, weniger Datensätze als erwartet. Es tritt kein Fehler auf Operationsebene auf, es sei denn, das Skript selbst überprüft den Rückgabewert der Funktion oder ruft GetLastError auf. Das Operationsprotokoll zeigt einen Eintrag, der die aufgerufene Operation anhand ihres Namens identifiziert (und auf ihre GUID zurückgreift, wenn der Name nicht aufgelöst werden kann), wenn das Limit erreicht wurde, und GetLastError gibt diese gleichen Informationen zurück.
Mögliche Ursache: Ab Agent-Version 12.11 begrenzt ein Limit auf Agent-Ebene (MaxSynchronousRunOperationCallsInLoop im [OperationEngine]-Bereich der jitterbit.conf-Datei, Standardwert 50) die Anzahl der synchronen RunOperation-, RunOperationFromProject- und ReRunOperation-Aufrufe, die innerhalb einer einzelnen While-Schleife vorgenommen werden. Alle drei gemeinsam verwenden einen kumulativen Zähler pro Schleife. Sobald das Limit erreicht ist, gibt jeder weitere Aufruf false zurück, ohne einen Fehler auszulösen. Eine Schleife, die den Rückgabewert nicht überprüft, iteriert daher weiter, ohne zu bemerken, dass spätere Aufrufe keine Auswirkung hatten.
Lösung:
- Falls die Schleife den Rückgabewert nicht bereits prüft, wickeln Sie den Aufruf ein, damit eine Limitüberschreitung als Skriptfehler angezeigt wird, zum Beispiel: If(!RunOperation("<TAG>operation:MyOp</TAG>"), RaiseError(GetLastError()));.
- Um das Limit für einen bestimmten Vorgang zu erhöhen, legen Sie die Jitterbit-Variable jitterbit.operation.max_sync_runop_calls_in_loop vor der Ausführung der Schleife fest, sofern Überschreibungen pro Vorgang zulässig sind (MaxSynchronousRunOperationCallsInLoopOverrideAllowed).
- Um den agentweiten Standard zu erhöhen, erhöhen Sie MaxSynchronousRunOperationCallsInLoop im jitterbit.conf Datei-Abschnitt [OperationEngine].

Ein String wird mit einer Zahl verglichen und führt zu unerwarteten Ergebnissen

Symptom: Ein Vergleich zwischen einem String und einer Zahl liefert ein unerwartetes Ergebnis. Beispielsweise wird der Vergleich eines nicht numerischen Strings mit 0 als gleich bewertet, wodurch 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. Ein String, der keine Zahl darstellt, wird zu 0 konvertiert, daher wird "test" == 0 zu 0 == 0, was true ist. Dies ist das erwartete Verhalten.
Lösung: Vergleichen Sie Werte desselben Typs. Um einen String gegen einen bestimmten Wert zu testen, vergleichen Sie ihn mit einem String-Literal (zum Beispiel $value == "0" oder $value == "") anstatt mit einer Zahl. Falls ein Wert als beide Typen eingehen kann, konvertieren Sie beide Operanden vor dem Vergleich in denselben Typ (zum Beispiel mit String).

Neuverarbeitung 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 sich Projekte, die vor 10.25 erstellt wurden und gespiegelte XML-Schemas verwenden, unerwartet verhalten. Zuordnungen, die XML-Funktionen mit Namespaces (wie SelectNodes) verwendet haben, können jetzt ungültig sein.

Der Unterschied liegt in der Behandlung von Namespace-Präfixen:
- 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 der Import eines Projekts, dessen gespiegelte XML-Schemas vor 10.25 erstellt wurden, das ursprüngliche Namespace-Präfix bei, sodass das Schema identisch mit dem Zeitpunkt seiner Erstellung 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äfixverweise entsprechend.

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

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

Symptom: Ein Zielfeld mit dem Datentyp double im Schema erhält einen Wert von 0, obwohl das Zuordnungsskript einen nicht leeren Zeichenfolgenwert zurückgibt.
Mögliche Ursache: Wenn die Transformation eine Skriptausgabe verarbeitet, wird das Ergebnis in den Datentyp des Zielfelds konvertiert. Falls der Zeichenfolgenwert mit einem Nicht-Ziffern-Zeichen beginnt (z. B. "string1"), kann kein numerischer Teil extrahiert werden und das Feld erhält den Standardnumernwert von 0. Ein Wert wie "1string" würde hingegen 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. Falls das Zuordnungsskript eine nicht numerische Zeichenfolge zurückgeben kann, fügen Sie eine explizite Validierung hinzu, um sicherzustellen, dass nur numerische Werte zu numerischen Zielfeldern zugeordnet 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 am Anfang der Operation einen Skriptschritt 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.

Dateifunktionen: Der Betrieb 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 Vorgangsbericht.
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 Vorgangsbericht hinzugefügt, aber der Vorgang selbst schlägt nicht fehl und die folgenden Schritte werden fortgesetzt. Ab Agent-Version 12.5 gibt es eine Ausnahme: ArchiveFile wirft bei Aufruf mit deleteSource auf true einen auffangbaren Fehler, wenn die Quelldatei nicht gelöscht werden kann, anstatt schweigend 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, wickeln Sie den Aufruf in eine Eval-Funktion ein und rufen Sie RaiseError explizit auf, um die Warnung zu einem Vorgangsfehler zu befördern.

`ReadFile`: Teilweises Lesen mit Binärdateiinhalten

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

`ReadFile`-Inhalte mit nicht-UTF-8-Bytes schlagen fehl, wenn sie einer UTF-8-XML- oder JSON-Payload zugeordnet werden

Symptom: Eine Transformation, die Rohzieldateiinhalte mit ReadFile (z. B. eine unformatierte 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 Zeichenfolge ermöglicht den Abschluss des Vorgangs, was bestätigt, dass der Rohinhalt der Auslöser ist. Versuche, das problematische Zeichen anhand seines Unicode-Codepunkts zu entfernen (z. B. Replace($readFile, HexToString("2026"), "~") für die Auslassungspunkte U+2026), stimmen nicht überein, und der Aufruf 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 in UTF-8 codiert ist (z. B. das einzelne Byte 0x85, das einige EDI-Dateien als Segmenttrennzeichen verwenden). Dieses Rohbyte unterscheidet sich von der Multi-Byte-UTF-8-Codierung eines ähnlich aussehenden Unicode-Zeichens (die Auslassungspunkte U+2026 werden als drei Bytes codiert), weshalb ein Austausch, der auf den Unicode-Codepunkt abzielt, nie übereinstimmt. 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: Entsprechen und ersetzen Sie das Rohbyte mit deaktivierter Unicode-Hex-Unterstützung, sodass HexToString auf Rohbytes und nicht auf UTF-8-Zeichen arbeitet:
```
$jitterbit.scripting.hex.enable_unicode_support = false;
$badByte = HexToString("85");
$readFile = Replace($readFile, $badByte, "~");
```
Passen Sie den Hexwert (85) an das von StringToHex($readFile) gemeldete Byte an, und passen Sie die Ersatzzeichenfolge (~) nach Bedarf an, dann bilden Sie den bereinigten Wert ab.

`FlushFile` / `FlushAllFiles`: Fehler, wenn die 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 Zielort vorhanden ist.
Lösung:
- Fügen Sie einen DeleteFile oder DeleteFiles Aufruf vor dem Schreibvorgang hinzu, um die vorhandene Datei zu löschen.
- Verwenden Sie alternativ einen dynamischen Dateinamen, der einen Zeitstempel oder eine eindeutige Kennung enthält, um Konflikte zu vermeiden.

`DeleteFiles`: Fehler, wenn der Quellpfad nicht gefunden wird

Symptom: Ein Skript mit DeleteFiles schlägt mit einem Fehler fehl, wenn der angegebene Quellpfad oder das Verzeichnis nicht gefunden werden kann. (Ein Filter, der keine Dateien entspricht, 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 Ausfällen während des Vorgangs führen, wenn die zu löschende Datei nicht vorhanden ist.
Lösung: Schließen Sie den DeleteFiles-Aufruf in eine Eval-Funktion ein, um den Fehler zu erfassen und zu handhaben, ohne dass der Vorgang fehlschlägt.

`GetJSONString`: Die Ausführung wird 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. weil der Knoten fehlt oder ein Array leer ist). Die Fehlermeldung ist generisch und identifiziert den Pfad nicht als Ursache. Bei Aufrufen über eine API kann dies als irreführender Proxy Error [502] beim API-Aufrufer angezeigt werden.
Mögliche Ursache: Wenn das an GetJSONString übergebene path-Argument ungültig ist oder keine Daten entspricht, unterbricht die Funktion sofort die Ausführung und gibt einen Fehler zurück, was dazu führen kann, dass das gesamte Skript abbricht.
Lösung:
- Den JSON-Pfad vor der Übergabe an GetJSONString validieren, oder (ab Agent-Version 11.59 / 12.3) GetJSONStringEx verwenden, das einen anpassbaren Wert zurückgibt, anstatt die Ausführung zu unterbrechen, wenn der Pfad ungültig oder nicht vorhanden ist.
- Die JSON-Payload unmittelbar vor dem GetJSONString-Aufruf protokollieren, um die aktuelle Struktur zu überprüfen und den Pfad zu bestätigen.

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

Symptom: Der Mapping-Ausdruck eines Zielfeldes umfasst sowohl RunScript als auch Unmap, aber das Feld wird nicht unmapped. Bei einem JSON- oder XML-Ziel wird das Feld in der Ausgabe mit einem null-Wert angezeigt, anstatt weggelassen zu werden.
Mögliche Ursachen:
- RunScript steht Unmap im selben Mapping-Ausdruck voraus (zum Beispiel RunScript("<TAG>script:MyScript</TAG>"); Unmap();). In Agent-Versionen vor 12.9 hat diese Kombination das Feld nicht unmapped.
- Unmap wird innerhalb des von RunScript aufgerufenen Skripts aufgerufen, anstatt direkt im Mapping-Ausdruck des Zielfeldes selbst. RunScript gibt das Ergebnis des aufgerufenen Skripts als String zurück, anstatt ein Unmap-Signal zurück zum Mapping weiterzugeben, daher hat das Aufrufen von Unmap innerhalb des aufgerufenen Skripts keine Auswirkung, auf jeder Agent-Version, unabhängig von der bedingten Logik rund um den Aufruf. Dies ist das erwartete Verhalten.
Lösung:
- Falls RunScript und Unmap beide direkt im Mapping-Ausdruck des Zielfeldes aufgerufen werden, führen Sie ein Update auf Agent-Version 12.9 oder später durch.
- Falls Unmap innerhalb des von RunScript aufgerufenen Skripts aufgerufen wird, verschieben Sie den Unmap-Aufruf aus dem aufgerufenen Skript heraus und in den Mapping-Ausdruck des Zielfeldes selbst, zum Beispiel:
```
RunScript("<TAG>script:MyScript</TAG>"); If(<condition>, Unmap(), <value>);
```

`DBExecute`: Fehler, wenn `auto_commit` und `transaction` beide `true` sind

Symptom: Ein Vorgang, der DBExecute verwendet, 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 legen Sie dann nur die entsprechende Variable fest:
- 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 auf 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` ist mit ODBC-Treibern immer null

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-Datenbankentreibern unterstützt. Wenn der Datenbankendpunkt einen ODBC-Treiber verwendet, ist resultSet unabhängig von den Rückgabedaten der gespeicherten Prozedur immer null.
Lösung:
- Wenn das Resultset der gespeicherten Prozedur erforderlich ist, wechseln Sie den Datenbankendpunkt zu einem JDBC-Treiber statt ODBC.
- Wenn ein Wechsel des Treibers nicht möglich ist, rufen Sie Ausgabedaten über Ausgabeparameter statt über das Argument resultSet ab.

`CallStoredProcedure`: „Gespeicherte Prozedur oder Funktion konnte nicht gefunden werden" 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 es sich bei dem Datenbankdbjekt um eine PostgreSQL-Funktion statt einer Prozedur handelt, kann der Treiber sie nicht finden und gibt die Fehlermeldung „not found" zurück.
Lösung:
1. Bestimmen Sie, ob das aufgerufene Datenbankdbjekt 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 Dbjekttyp:
  - 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 ignoriert werden.

`DBLoad`: Erfordert einen JDBC-Datenbanktreiber

Symptom: Ein Vorgang mit DBLoad schlägt fehl oder produziert keine Ausgabe, wenn der Datenbankendpunkt einen ODBC-Treiber verwendet.
Mögliche Ursache: DBLoad funktioniert nur mit Datenbankendpunkten, die für die Verwendung eines JDBC-Treibers konfiguriert sind. Es wird nicht mit ODBC-Treibern unterstützt.
Lösung: Überprüfen Sie, dass der mit der Zielaktivität verknüpfte Datenbankendpunkt einen JDBC-Treiber verwendet. Wenn ein ODBC-Treiber verwendet wird, wechseln Sie zu JDBC.

`AESDecryption` schlägt fehl mit Daten, die unter OpenSSL 3 verschlüsselt wurden

Symptom: Ein Vorgang mit AESDecryption schlägt fehl oder gibt garbled Output zurück, wenn Daten entschlüsselt werden, die mit OpenSSL 3 verschlüsselt wurden.
Mögliche Ursache: AESDecryption verwendet standardmäßig einen Legacy-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 OpenSSL 3-Kompatibilität zu aktivieren.
- Alternativ ersetzen Sie AESDecryption durch AESDecryptionEx, die standardmäßig OpenSSL 3 auf Agent-Versionen 11.42 oder später unterstützt.

Variablenupdates gehen in mehrstufigen Multi-Thread-Vorgängen verloren

Symptom: Wenn ein Vorgang mit aktiviertem Chunking und Max Number of Threads auf mehr als 1 eingestellt ist, gehen Updates von globalen oder Projektvariablen, die während des Vorgangs vorgenommen wurden, nach dem Abschluss nicht vollständig verloren. Ein möglicher Fall ist das Ausfüllen einer Dictionary- oder Array-Variable aus jedem Quelldatensatz und die Feststellung, dass sie danach nur einen Teil der Daten enthält (beispielsweise ungefähr die Hälfte der Datensätze bei zwei Threads). Dies kann bei Connectors auftreten, deren Standardkonfiguration mehr als einen Thread verwendet, 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 integriert. 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 Pro-Vorgang-Durchsatz, stelle Max Number of Threads auf 1. Jeder Chunk wird dann sequenziell verarbeitet, sodass Variablenupdates nicht auf Threads verteilt werden.
- Wenn mehrstufiger Durchsatz erforderlich ist, speichere keinen Pro-Datensatz-Status in einer globalen oder Projektvariable. Schreibe stattdessen die Ausgabe jedes Threads in eine eindeutige Temporary Storage-Datei oder eine Staging-Datenbanktabelle, und konsolidiere die Ergebnisse dann in einem nachfolgenden Vorgang mit einem Thread. Ein praktisches Beispiel des Staging-Musters findest du unter Variable scoping with chunking.
- Allgemein gesagt solltest du dich nicht auf Variable-Updates aus Chunked-Vorgängen mit mehreren Threads in späteren Skripten oder Vorgängen verlassen. Wenn der Variablenstatus beibehalten werden muss, lege diese Variablen in einem Schritt ohne Chunking fest, der vor oder nach der Chunked-Transformation ausgeführt wird. Einzelheiten zum Chunking-Verhalten mit Variablen findest du unter Use variables with chunking.

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

Symptom: Eine Transformation, die eine CSV-Quelle liest und einer hierarchischen Ausgabe (z. B. JSON) zuordnet, löscht stillschweigend doppelte Datensätze. Datensätze mit identischen Feldwerten werden in der Ausgabe nur einmal angezeigt, 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 Umwandlung 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 Ausgabe. Wenn das Ausgabeschema flach ist, wird die Normalisierung nicht ausgeführt und alle Datensätze werden geschrieben.
- Die Transformations-Engine schneidet standardmäßig auch führende und nachfolgende Leerzeichen aus CSV-Feldwerten ab. Datensätze, die sich nur durch führende oder nachfolgende Leerzeichen unterscheiden, werden nach dem Trimmen identisch und unterliegen derselben Deduplizierung.
Lösung:
- Aktivieren Sie Chunking in den Operationsoptionen. Chunking verarbeitet Datensätze in Batches, was die Normalisierung umgeht und alle Datensätze einschließlich Duplikate beibehält.
- Verwenden Sie ein flaches Ausgabeschema in der Transformation statt eines hierarchischen. Die Normalisierung gilt nicht für flache Ausgabe, daher werden alle Datensätze beibehalten.
- Deaktivieren Sie die Normalisierung, indem Sie in einem Skriptschritt vor der Transformation eine Jitterbit-Variable setzen. Setzen Sie bei Flat-to-Flat-Transformationen jitterbit.transformation.disable_normalization auf true. Setzen Sie bei 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 Leerzeichenunterschiede verursacht werden, setzen Sie jitterbit.source.preserve_char_whitespace in einem Skriptschritt vor der Transformation auf true. Dies erhält die Leerzeichen beim Parsing, sodass betroffene Datensätze unterschiedlich bleiben.

Lange numerische IDs werden in der Transformationsausgabe beschädigt

Symptom: Ein langer numerischer Wert (z. B. eine Tracking-Nummer, Kontonummer oder externe ID) wird mit einem 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. Dies führt zu einem Überlauf und erzeugt einen falschen Wert am Ziel.
Mögliche Ursache: Das Quell- oder Zielfeld ist implizit als numerischer Datentyp typisiert, dessen Bereich den vollständigen Wert nicht aufnehmen kann. Dies verursacht einen Überlauf während der Konvertierung.
Lösung:
- Legen Sie in der Transformation den Datentyp des betroffenen Zielfelds auf String fest, anstatt einen numerischen Typ zu verwenden. Lange IDs, die nicht in Berechnungen verwendet werden, sollten als Strings behandelt werden.
- Wenn das Quellfeld ebenfalls numerisch typisiert ist, casten Sie den Wert explizit mit String, bevor Sie ihn zuordnen:
```
String($source.numericId)
```

JSON-Transformationsausgabe lässt `null`- und Leerstring-Felder weg

Symptom: Eine JSON-Transformation entfernt Felder, deren Wert null oder ein Leerstring ("") ist, aus der Ausgabe-Payload, obwohl diese Felder explizit zugeordnet sind. Das Zielsystem erhält eine Payload, die die ausgelassenen Felder nicht enthält. Dies kann zu Downstream-Validierungsfehlern führen, wenn das Ziel die Felder als vorhanden erfordert.
Mögliche Ursache: Der JSON-Ausgabe-Prozessor lässt Felder mit null- oder Leerstring-Werten standardmäßig aus.
Lösung:
- Legen Sie in einem Skriptschritt vor der Transformation jitterbit.target.xml.include_nil_attribute auf true fest. Ab Agent-Version 11.37 werden dadurch null-Werte und Leerstrings in der JSON-Ausgabe einbezogen, was der Eingabe entspricht. (Trotz xml im Namen gilt diese Variable für JSON-Ziele.)
- Wenn Sie vollständige Kontrolle darüber benötigen, welche Felder in der Payload enthalten sind, erstellen Sie den JSON-Body in einem Skriptschritt mit String-Verkettung 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 Telefonnummern-Zuordnung Folgendes:
```
<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 enthält die Transformation, wenn eine Zuordnung zu einem Zielknoten einen null- oder leeren Wert ergibt, den Knoten, kennzeichnet ihn aber als nil (xsi:nil="true"). Dies wird durch jitterbit.target.xml.include_null_xml gesteuert, deren Standard true ist.
Lösung: Legen Sie in einem Skriptschritt vor der Transformation $jitterbit.target.xml.include_null_xml = false fest, um Knoten mit null- oder leeren Werten vollständig aus der Ausgabe zu entfernen. Falls der Knoten stattdessen als leeres Element vorhanden sein muss, verwenden Sie die entsprechenden 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 enthalten sind.

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

Symptom: Wenn eine Quelldatei (z. B. eine CSV-Datei) mit einer UTF-8-Byte-Order-Mark (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. Aus Microsoft Excel als UTF-8 CSV exportierte Dateien 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 rohen Bytes des BOM werden Teil des Werts des ersten Felds, nachdem die Datei in Datensätze analysiert wurde.
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-Versionen 12.6 oder früher, bei denen UTF-8 nicht die Standardeinstellung ist, können Sie auch vor dem Ausführen der Quellaktivität explizit die Zeichencodierung auf UTF-8 setzen, z. B. $jitterbit.source.text.character_encoding = "utf-8";. Agent-Versionen 12.7 und später verwenden standardmäßig UTF-8.

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

Symptom: Beim Testen eines Script-Schritts oder einer Transformation in Studio gibt eine im Script oder Mapping referenzierte Projektvariable einen leeren Wert statt des konfigurierten Werts zurück. Der Test schlägt möglicherweise mit einem Fehler fehl, der nicht mit der Variable selbst zusammenhängt (beispielsweise ein Verbindungszeitüberschreitung durch eine leere Serveradresse).
Mögliche Ursache: Projektvariablenwerte werden zur Laufzeit von der Harmony-Plattform eingefügt. Während eines Design-Zeit-Tests existiert kein Laufzeitkontext, um diesen Wert einzufügen. Eine Projektvariablenreferenz gibt daher einen leeren Wert zurück, es sei denn, die Variable hat einen Standardwert konfiguriert, der als Fallback verwendet wird. Die eigene Verbindungsauflösung einer Funktion ist ein separater Fall, der den Standardwert überhaupt nicht verwendet. Siehe Eine Funktion schlägt fehl, wenn ihr Endpunkt-Verbindungsfeld auf eine Variable eingestellt ist.
Lösung:
- Einen Standardwert für die Projektvariable festlegen: Geben Sie in der Projektvariablenkonfiguration den während des Tests zu verwendenden Wert 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 Design-Zeit-Tests). Daher fungiert der Standardwert auch zur Laufzeit als Fallback, wenn die Variable anderweitig nicht gesetzt ist. Siehe Projektvariablen für Konfigurationsdetails.
- Eine globale Variable verwenden: Ersetzen Sie die Projektvariablenreferenz durch eine globale Variable und weisen Sie ihren Wert im Script selbst vor der Zeile zu, die sie verwendet. Weil eine globale Variable ihren Wert aus der Script-Ausführung statt aus Laufzeiteinspeisung erhält, macht das Zuweisen vor der Verwendung sie während eines Design-Zeit-Tests verfügbar. Dies ist vorzuziehen, wenn der Wert in einem Script abgeleitet wird oder wenn kein Laufzeit-Fallback-Wert gewünscht ist. Siehe Globale Variablen für Details. Wenn die globale Variable in einem Connector-Konfigurationsfeld statt direkt in einem Script referenziert wird, müssen Sie auch einen feldspezifischen Standardwert für dieses Feld definieren (siehe Einen Standardwert definieren, das sowohl die Variable-Pill-Methode als auch die Inline-Syntax-Methode für Felder ohne Pill abdeckt).

Eine Funktion schlägt fehl, wenn ihr Endpunktverbindungsfeld auf eine Variable gesetzt ist

Symptom: Das Testen eines Scripts (mit Test ausführen), das eine Funktion wie DBLookup, DBExecute oder SfLookup aufruft, schlägt fehl, beispielsweise mit:
```
No suitable driver found for [...]
```
oder ein Fehler, der einen unaufgelösten Variablenplatzhalter in der Endpunktadresse anzeigt. Das gleiche Script wird erfolgreich ausgeführt, wenn es bereitgestellt und in einem Operation ausgeführt wird.
Mögliche Ursache: Die von der Funktion verwendete Verbindung hat ein Feld (wie Anmeldung, Passwort, Verbindungszeichenfolge oder eine Serveradresse), das auf eine globale oder Projektvariable eingestellt ist. Das Testen eines Scripts führt nur das getestete Script aus, daher wurde die Variable ihren Laufzeitwert noch nicht zugewiesen, wenn die Funktion die Verbindung auflöst. Anders als eine Variable, die direkt in einem konfigurierten Feld einer Aktivität referenziert wird, wird dies nicht durch den Standardwert einer Variable abgedeckt. Eine Funktion wie diese liest den Standardwert nicht, wenn sie eine Verbindung auflöst. Für eine Variable, die direkt in einem Script oder Mapping referenziert wird und bei der ein Standardwert das Problem löst, siehe Projektvariablen geben während Script- und Transformation-Tests leere Werte zurück.
Lösung: Weisen Sie der globalen oder Projektvariablen vor dem Funktionsaufruf vorübergehend ihren aktuellen Wert direkt im getesteten Skript zu (beispielsweise $login = "value"; für eine Variable namens login), und entfernen Sie die Zuweisung dann vor der Bereitstellung des Vorgangs.

`IsNull` gibt false für leere Zeichenketten 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 von der Null-Prüfung 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 für ihn korrekterweise false zurück. Ab Agent 11.37 behält der Agent diese Unterscheidung korrekt bei. Skripte oder Transformationen, die sich zuvor darauf verlassen haben, dass IsNull für leere Strings true zurückgibt, waren auf ein früheres Verhalten angewiesen, das nicht länger korrekt ist.
Lösung:
- Verwenden Sie IfEmpty, um sowohl Null- als auch leere Strings zu behandeln: Die Funktion IfEmpty gibt einen Standardwert zurück, wenn das Argument null oder ein leerer String ist, und ist die empfohlene Lösung 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 leere Strings explizit zu testen: Wenn Sie nur überprüfen müssen, ob ein String leer ist (nicht null), verwenden Sie Length($myField) == 0.
- Reparieren Sie die Quelldaten: Wenn die JSON-Quelle keinen Wert anzeigen soll, aktualisieren Sie sie, um "field": null zu senden oder lassen Sie das Feld ganz weg, anstatt "field": "" zu verwenden.

Der Vergleich einer Zeichenkettenvariable 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 (beispielsweise "test"). If-Bedingungen und andere Logiken, die auf Null prüfen, erzeugen unerwartete Ergebnisse.
Mögliche Ursache: Wenn Jitterbit Script Werte verschiedener Datentypen vergleicht, versucht es, beide Operanden als letzten Schritt in Double umzuwandeln. Bei Anwendung auf einen nicht-numerischen String schlägt die Umwandlung 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 den gleichen Datentyp verwenden. Wenn die Absicht darin besteht zu überprüfen, ob eine String-Variable 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 String zugewiesen wird.

Dezimalarithmetik erzeugt unerwartete Gleitkommaaergebnisse

Symptom: Ein arithmetischer Ausdruck mit Dezimalliteralen erzeugt ein Ergebnis, das sehr leicht vom erwarteten Wert abweicht. Beispiel: Double(12.01) - Double(12.00) gibt 0.00999999999999979 statt 0.01 zurück, und (4.9 * 100) - 490 wird zu 5.6843418860808e-14 statt 0 ausgewertet.
Mögliche Ursache: Jitterbit Script speichert Zahlen als Gleitkommawerte. Die meisten Dezimalbruchteile können im binären Gleitkommaformat nicht exakt dargestellt werden, daher kann Arithmetik auf ihnen kleine Rundungsfehler ansammeln. Subtraktion, die den größten Teil eines Wertes aufhebt, macht diesen Rest sichtbar. Explizites Umwandeln von Werten als Double verhindert dies nicht: es legt den Datentyp fest, ä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

Dezimalliterale mit Float umwandeln: Umhüllen Sie das Dezimalliteral in 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 exakt Mitternacht eine vollständige Datums- und Zeitzeichenfolge zurück (z. B. 2026-01-01 00:00:00) statt einer reinen Datumszeichenfolge (2026-01-01), was die Downstream-Logik beschädigen kann, die das kürzere Format erwartet. CVTDate ist davon nicht betroffen.
Mögliche Ursache: Ab Agent-Version 12.8 behandeln diese Funktionen Mitternacht (00:00:00) als einen gültigen Zeitwert und behalten ihn im zurückgegebenen Wert, genau wie jede andere Zeit. Zuvor wurde ein Wert von exakt Mitternacht auf eine reine Datumszeichenfolge gekürzt, während jede andere Zeit korrekt beibehalten wurde.
Lösung: Wenn die Downstream-Logik einen reinen Datumswert erfordert, verwenden Sie FormatDate, um das Ergebnis explizit zu formatieren, anstatt sich auf das Standard-Ausgabeformat der Funktion zu verlassen.

Der zwischengespeicherte Wert läuft schneller ab als erwartet

Symptom: Ein in den Cache geschriebener Wert mit einer langen Ablaufzeit (z. B. 24 Stunden) verschwindet, bevor diese Zeit abläuft, oder läuft nach 30 Minuten ab, unabhängig von den Einstellungen in WriteCache.
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 Ablaufzeit von WriteCache gilt nur zum Zeitpunkt des Schreibens; nachfolgende Lesevorgänge ohne explizite Ablaufzeit verkürzen stillschweigend die verbleibende Lebensdauer.
Lösung:
- Legen Sie die Ablaufzeit in ReadCache fest: Übergeben Sie die gewünschte Anzahl von Sekunden als Parameter expirationSeconds, um die Lebensdauer des zwischengespeicherten Werts bei jedem Lesevorgang beizubehalten oder zu verlängern:
```
// Resets expiration to 24 hours on each read
testVal = ReadCache("CacheTest", 86400, "env");
```
- Übergeben Sie -1, um die Schreib-Ablaufzeit beizubehalten: Das Übergeben eines nicht positiven Werts führt dazu, dass ReadCache die durch den letzten WriteCache-Aufruf festgelegte Ablaufzeit beibehält, anstatt eine neue 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 der Fehlermeldung fehl:
```
Failed to execute xslt. XML version must be 1.0 or 1.1
```
obwohl die Eingabe-XML-Datei 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 Eingabe-XML.
Lösung:
- XSLT aktualisieren, um XML-Ausgabe zu erzeugen: Ändern Sie die Output-Deklaration des Stylesheets in <xsl:output method="xml"/>, oder entfernen Sie die xsl:output-Deklaration komplett (XML ist die Standardeinstellung). Dies ist der empfohlene Ansatz und funktioniert sowohl auf Cloud- als auch auf Private Agents.
- XSL Transform Plugin verwenden (nur Private Agents): Für Private Agent Groups unterstützt das veraltete XSL Transform Plugin den Saxon XSLT-Prozessor und ermöglicht Ausgabeformate außer XML, einschließlich HTML. Weitere Installationsdetails finden Sie unter Verfügbare Plugins.

`SelectSingleNode` gibt den falschen Knoten zurück, wenn dieser 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 mit // beginnend) als Path-Argument führt dazu, dass SelectSingleNode vom Root des ursprünglichen XML-Dokuments aus sucht, anstatt relativ zum aktuellen Knoten. Ein Ausdruck wie "//Item/ItemName" findet den ersten ItemName im gesamten Dokument, unabhängig davon, welches Item-Element aus dem Array abgerufen wurde.
Lösung:
- Relativen Pfad verwenden: Lassen Sie das führende // weg und geben Sie nur den Elementnamen oder einen Pfad relativ zum aktuellen Knoten an. Dadurch wird die Suche auf den als erstes Argument übergebenen Knoten beschränkt:
```
$itemName = SelectSingleNode($item, "ItemName");
```
- Alternative: Knoten in String einwrappen: Das Konvertieren des Array-Elements in einen String vor der Übergabe an SelectSingleNode liefert auch das richtige Ergebnis. Die Verwendung eines relativen Pfads ist jedoch der bevorzugte Ansatz:
```
$item = String($items[2]);
$itemName = SelectSingleNode($item, "//Item/ItemName");
```

Die Ausgabe von `HexToBinary` erscheint beim Protokollieren unverändert

Symptom: HexToBinary scheint keine Auswirkung zu haben: Der in das Operationsprotokoll geschriebene Wert sieht identisch mit der Hex-Eingabe 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 es diesen zur Anzeige zurück in Hexadezimal. Das gleiche Verhalten gilt im Script-Testfenster. Die Konvertierung funktioniert korrekt; nur die Anzeige ist betroffen.
Lösung: Um mit der Binärausgabe zu arbeiten oder diese zu überprüfen, schreiben Sie sie mithilfe von 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 der erwarteten chronologischen Reihenfolge, wenn Dateinamen eingebettete Datums- oder Zeitzeichenfolgen enthalten.
Mögliche Ursache: SortArray führt eine String- (lexikografische) Sortierung durch. Bei einem Dateinamen wie ordall_DDMMYYHHMMSS.txt steht der Tagteil vor dem Jahrteil im String, sodass eine alphabetische Sortierung nicht mit einer datumsbasierten Sortierung übereinstimmt.
Lösung:
- Wenn Sie die Dateinamenskonvention kontrollieren, wechseln Sie zu einem Format, das bei alphabetischer Sortierung korrekt sortiert, 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 Datumsanteil jedes Dateinamens in einen sortierbaren Schlüssel (z. B. YYYYMMDDHHMMSS) und sortieren Sie nach dem analysierten Schlüssel anstelle des unverarbeiteten Dateinamens.

`URLEncode` kodiert bestimmte „sichere" oder Multi-Byte-Zeichen nicht

Symptom: Ein Wert, der durch URLEncode geleitet wird, wird zum Ziel mit einigen uncodierten 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", sodass sie niemals codiert werden: $ - _ . + ! * ' ( ) ,. Ein Ziel, das erwartet, dass diese Zeichen prozentual codiert sind, empfängt stattdessen das Rohzeichen.
- Die Multibyte-Zeichenunterstützung in URLEncode erfordert Agent-Version 12.4 oder später. Bei früheren Agenten 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 mit +), verwenden Sie 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, überprüfen Sie, ob der Agent Version 12.4 oder später ausführt.

JavaScript: Fehler „Aufruf von Jitterbit Tomcat fehlgeschlagen"

Symptom: Ein komplexer oder langsam ausgeführter JavaScript-Schritt schlägt mit einem generischen Fehler fehl, der auf Tomcat verweist, obwohl sowohl die Jitterbit Apache- als auch die Jitterbit Tomcat-Dienste auf dem Agent ausgeführt werden. Das Skript wird möglicherweise erfolgreich ausgeführt, wenn seine Komplexität verringert wird (z. B. durch Reduzieren von Iterationszählern oder 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: Stark rekursives JavaScript kann das Rekursionstiefe-Limit der JavaScript-Engine des Agenten überschreiten, was zu einem Stack Overflow führt, der sich als dieser generische Tomcat-Fehler äußert. Dieses Rekursionslimit ist beabsichtigt. Das Skript wird in der Regel abgeschlossen, sobald die Rekursionstiefe verringert wird.
Lösung:
- Reduzieren Sie die Rekursionstiefe, oder schreiben Sie die rekursive Logik in eine iterative Schleife um.
- Wenn der Algorithmus tiefe Rekursion nicht vermeiden kann, verwenden Sie einen Ansatz, der nicht darauf beruht.
- Beachten Sie, dass das separate Pro-Skript-Schleife-Iterations-Limit (JavaScriptMaxIterations, siehe Skript-Schleife Iterationslimit überschritten) die Rekursionsobergrenze nicht anhebt, die nicht als konfigurierbare Einstellung verfügbar gemacht ist.

JavaScript: Änderungen an globalen Variablen gehen bei Scriptfehlern verloren

Symptom: Ein JavaScript-Skript, das globale Variablen ändert, wird in einigen Fällen ohne offensichtlichen Fehler ausgeführt, aber Änderungen an diesen globalen Variablen fehlen in nachfolgenden Skripten oder Operationen.
Mögliche Ursachen:
- In JavaScript werden Änderungen an globalen Variablen nur übernommen, wenn das Skript erfolgreich abgeschlossen wird. Wenn das Skript an einer beliebigen Stelle 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 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 die $variable-Syntax oder Jitterbit.SetVar/Jitterbit.GetVar, niemals beide. Wählen Sie eine aus 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 Schlüsselpunkten während der Ausführung zu protokollieren.

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

Symptom: Das Aufrufen von Jitterbit.GetVar für eine benutzerdefinierte Projektvariable in einem JavaScript-Skriptschritt gibt null statt des Wertes der Variablen zurück, ohne dass eine Fehlermeldung angezeigt wird.
Mögliche Ursache: Jitterbit.GetVar und Jitterbit.SetVar sind für Jitterbit-Systemvariablen (z. B. jitterbit.operation.name) und für Variablennamen mit einem Punkt vorgesehen, auf die die Punktnotation von JavaScript nicht direkt zugreifen kann. Sie lesen keine gewöhnlichen benutzerdefinierten Projektvariablen, deren Namen keinen Punkt enthalten; das Übergeben solcher Namen an GetVar gibt null zurück. Referenziere diese Variablen stattdessen direkt mit $name. Diese Funktionen konvertieren alle Werte auch in Strings, daher sind sie nicht für Arrays oder Objekte geeignet. Ein mit SetVar festgelegter Wert kann mit GetVar innerhalb desselben Skripts ausgelesen werden, bleibt aber nicht in späteren Skripts erhalten.
Lösung: Verwende die Syntax $variableName direkt in JavaScript, um auf benutzerdefinierte Projekt- und globale Variablen zuzugreifen, deren Namen keinen Punkt enthalten. Reserviere GetVar und SetVar für Jitterbit-Systemvariablen und für Variablen, deren Namen einen Punkt enthalten (z. B. $hello.world), auf die die Punktnotation von JavaScript nicht direkt zugreifen kann. Verwende für eine gegebene Variable entweder $-Präfix oder GetVar/SetVar, aber nicht beide. Siehe auch JavaScript: Änderungen an globalen Variablen 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
```

Das Hochladen einer Schemadatei ersetzt diese 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 allen Stellen ersetzt, an denen sie verwendet wird. Diese Ersetzung erfolgt projektweit und nicht nur im Umfang der aktuellen Transformation.
Lösung:
1. Bevor man eine Ersatzschemadatei hochlädt, sollte man überprüfen, ob das vorhandene Schema freigegeben ist: Öffne das Schema zum Bearbeiten. Falls es von mehr als einer Komponente referenziert wird, zeigt Studio einen Dialog Schema wird von mehreren Komponenten verwendet an, der diese auflistet (siehe Transformationsdefinierte Schemas aktualisieren). Bewerte die Auswirkungen auf alle aufgelisteten Komponenten, bevor du fortfährst.
2. Falls nur eine Transformation das aktualisierte Schema verwenden soll, klicke im Dialog Datei überschreiben? auf Abbrechen (oder benenne die neue Datei vor dem Hochladen um), damit die freigegebene Datei nicht überschrieben wird.

Die Bereitstellung der Marketplace-Prozessvorlage schlägt aufgrund von Schemainkompatibilität fehl

Symptom: Ein aus einer Marketplace-Prozessvorlage importiertes Projekt kann nicht bereitgestellt werden oder erzeugt Fehler zur Laufzeit, da Felder in einer Transformation oder einer Quell- und Zielaktivität fehlen und die Validierung fehlschlägt.
Mögliche Ursache: Prozessvorlagen werden für eine bestimmte Endpunkt-Instanz entwickelt. Wenn sich deine Instanz unterscheidet (z. B. wenn dein Salesforce- oder NetSuite-Org unterschiedliche benutzerdefinierte oder Standardfelder hat), stimmen die in den Transformationen der Vorlage eingebetteten Schemas möglicherweise nicht mit deinem Endpunkt überein.
Lösung:
1. Öffne in der betroffenen Transformation die Schemaeinstellungen und klicke auf das Aktualisierungssymbol (oder das Wort Aktualisieren), um das Schema von deinem verbundenen Endpunkt neu zu generieren.
2. Falls das Schema nach dem Aktualisieren immer noch nicht übereinstimmt, lösche das vorhandene Schema und spiegle es erneut von einer aktuellen Beispieldatei oder direkt vom Endpunkt.
3. Ordne alle Felder neu zu, die während der Schema-Neugenerierung hinzugefügt oder entfernt wurden.
4. Stelle das Projekt erneut bereit und führe den Vorgang erneut aus, um zu bestätigen, dass das Problem behoben ist.

Studio wird mit 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 gleichzeitig, daher stellt ein Workflow mit einer sehr großen Anzahl von Operationen hohe Speicheranforderungen an den Browser.
Lösung:
- Unterteile große Workflows in kleinere, verknüpfte Sub-Workflows. Studio rendert nur die aktive Workflow-Canvas, daher verbessert sich die Responsivität mit weniger Operationen pro Workflow. Verwende Operationsaktionen, um Sub-Workflows miteinander zu verknüpfen.
- Falls die Verlangsamung spezifisch beim Speichern eines großen Skripts auftritt, teile das Skript in kleinere Skripte auf und rufe sie mit RunScript auf.

Amazon Bedrock: Modellfehler „On-Demand-Durchsatz wird nicht unterstützt"

Symptom: Eine Amazon Bedrock-Aktivität schlägt mit folgendem Fehler fehl:

Invocation of model ID <model-name> with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model.

Mögliche Ursache: Einige Modelle, einschließlich OpenAI's GPT-5.6 Modelle, unterstützen keine On-Demand-Durchsätze und erfordern stattdessen die ID eines regionenübergreifenden Inferenzprofils anstelle der in der Liste Select a model zurückgegebenen Modell-ID.
Lösung:
1. Gehen Sie in der AWS Management Console zu Amazon Bedrock > Inference profiles und suchen Sie die Inferenzprofil-ID für das Modell. Beispiel: Die Inferenzprofil-ID für anthropic.claude-3-5-haiku-20241022-v1:0 in den USA ist us.anthropic.claude-3-5-haiku-20241022-v1:0. Bei OpenAI's GPT-5.6 Modellen variieren gültige Inferenzprofil-ID-Präfixe je nach Modell und Region (z. B. us. oder global.), wie beispielsweise us.openai.gpt-5.6-terra oder global.openai.gpt-5.6-terra. Die genaue Inferenzprofil-ID für Ihr Modell und Ihre Region finden Sie in AWS Modellkarten für GPT-5.6 Sol, GPT-5.6 Terra und GPT-5.6 Luna.
2. Geben Sie die Inferenzprofil-ID über die Option Enter model identifier in der Aktivitätskonfiguration ein.

Cloud Datastore: Query Items-Aktivität gibt nicht alle übereinstimmenden Datensätze bei der Filterung nach mehreren Werten desselben Feldes zurück

Symptom: Eine Query Items-Aktivität, die mehrere spezifische Datensätze gleichzeitig nachschlagen soll (z. B. anhand einer Liste von Key-Werten), gibt nur einen Datensatz zurück, obwohl alle Datensätze im Speicher vorhanden sind und dies auf der Cloud Datastore-Seite in der Management Console bestätigt werden kann.
Mögliche Ursache: Der Filter der Abfrage kombiniert mehrere Bedingungen für dasselbe Feld (z. B. mehrere unterschiedliche Key-Werte in einem einzelnen Filter). Cloud-Datastore-Filterbedingungen können nur kombiniert werden, wenn jede Bedingung ein anderes Feld angibt. Ein Filter kann dasselbe Feld nicht mehrfach angeben, und es können nicht mehrere Bedingungen oder Operatoren auf dasselbe Feld angewendet werden.
Lösung: Geben Sie für jeden Wert einen separaten Query Items-Aufruf aus, statt mehrere Werte desselben Feldes in einem Filter zu kombinieren. Einzelheiten zu unterstützten Filterbedingungen finden Sie unter Query Items-Aktivität.

Cloud Datastore: Delete Items-Aktivität meldet Erfolg, löscht den Datensatz aber nicht

Symptom: Eine Cloud-Datastore-Aktivität Delete Items meldet im Operationsprotokoll Erfolg, aber der Zieldatensatz existiert weiterhin, wenn er danach abgefragt wird.
Mögliche Ursache: Delete Items identifiziert Datensätze anhand des Key- (oder Alternative Key-) Wertes des Speichers, der im keys- oder ids-Array der Anforderung angegeben ist. (Beide Arrays akzeptieren Schlüssel- oder alternative Schlüsselwerte.) Wird statt des Schlüsselwertes die interne ID des Datensatzes angegeben, stimmt kein Element überein, und die Aktivität meldet Erfolg, ohne etwas zu löschen.
Lösung:
- In der Transformation, die die Delete Items-Anforderung vorbereitet, ordnen Sie den Key- (oder Alternative Key-) Wert des Speichers zu, nicht die interne Datensatz-ID.
- Wenn eine Verkettung von einer Query Items-Aktivität erfolgt, ordnen Sie den key-Wert aus der Abfrageantwort der Löschanforderung zu.

Coupa: API-Schlüsselauthentifizierung gibt 403 Forbidden zurück

Symptom: Eine Connector-Operation von Coupa schlägt mit einem Forbidden (403)-Fehler fehl, wenn API-Schlüssel-Authentifizierung verwendet wird.
Mögliche Ursache: Seit Coupa-Release R35 (Januar 2023) sind Coupa-API-Schlüssel veraltet und werden nicht mehr für die Authentifizierung unterstützt. Verbindungen, die für die Verwendung von API-Schlüssel-Authentifizierung konfiguriert sind, erhalten einen 403-Fehler.
Lösung:
1. Wechseln Sie in der Konfiguration der Coupa-Verbindung von der API-Schlüssel-Authentifizierung zu OAuth-2.0-Authentifizierung.
2. Erstellen Sie in Ihrer Coupa-Instanz eine OAuth-2.0-Clientanwendung und besorgen Sie sich die Client-Anmeldedaten.
3. Aktualisieren Sie die Verbindungskonfiguration mit den OAuth-2.0-Anmeldedaten, speichern Sie sie, und führen Sie einen erneuten Test durch.

Datenbank (JDBC): `DBLookup` oder `DBExecute` schlägt mit Base64-Decodierungsfehler fehl

Symptom: Eine DBLookup- oder DBExecute-Funktion für eine PostgreSQL- oder SQL Server-Datenbank über einen JDBC-Treiber schlägt zur Laufzeit fehl mit:
```
Base64 decoding failed. Reason: error:00000000:lib(0)::reason(0)
```
Dies tritt auf, wenn der zurückgegebene Wert Base64-codierten Daten ähnelt, wie etwa ein JWT oder anderer Zugriffstoken, obwohl die gleiche Abfrage bei direkter Ausführung gegen die Datenbank erfolgreich ist.
Mögliche Ursache: Agentversionen vor 12.9 versuchen möglicherweise fälschlicherweise, einen JDBC-Ergebniswert zu Base64-decodieren, der einem Base64-ähnlichen Muster entspricht, unabhängig davon, ob der Wert tatsächlich Base64-codierte Daten sind.
Lösung:
- Bei Private Agents wird auf Version 12.9 oder später aktualisiert. Cloud Agents erhalten das Update automatisch.
- Falls eine sofortige Aktualisierung nicht möglich ist, wird die Base64-Prüfung umgangen, indem der betroffene Wert in der SQL-Abfrage in Hexadezimalformat konvertiert wird und dann in einem Skriptschritt mit HexToString decodiert wird. Beispiel in PostgreSQL: SELECT encode(<column>, 'hex'). Bei dem Zurückschreiben des Werts in die Datenbank wird das entsprechende SQL decode(...,'hex') mit StringToHex verwendet.

Datenbank (ODBC): Mehrbyte-Zeichen werden nicht korrekt verarbeitet

Symptom: Beim Lesen oder Schreiben in eine Datenbank über den Datenbankconnector mit einem ODBC-Treiber werden Multibyte- oder Nicht-ASCII-Zeichen (beispielsweise Umlaute oder Nicht-Latin-Zeichen) nicht korrekt verarbeitet.
Mögliche Ursache: Die Unterstützung für Multibyte-Zeichen für den Datenbankconnector über einen ODBC-Treiber ist standardmäßig nicht aktiviert. Die Jitterbit-Variable jitterbit.scripting.db.multibyte.enable muss auf true gesetzt werden. Diese Unterstützung ist ab Agent-Version 12.6 verfügbar und wird bei Verwendung eines JDBC-Treibers nicht benötigt.
Lösung:
1. Bestätigung, dass der Agent Version 12.6 oder später ausführt.
2. Die Variable jitterbit.scripting.db.multibyte.enable wird auf true gesetzt, bevor der Datenbankvorgang ausgeführt wird. Beispiel in einem Skriptschritt:
```
$jitterbit.scripting.db.multibyte.enable = true;
```
Alternativ wird ein JDBC-Treiber für die Datenbankverbindung verwendet, welcher Multibyte-Zeichen ohne diese Variable verarbeitet.

Datenbank: Verbindung wird durch Sicherheitsrichtlinie blockiert

Symptom: Ein Datenbankconnector-Verbindungstest schlägt fehl mit:

HttpErrorResponse: The database connection could not be established due to a security policy violation.

mit einer Detailzeile, die entweder eine Loopback-Verbindung benennt:

Details: java.lang.IllegalArgumentException - JDBC connections to loopback addresses are not permitted.

oder einen bestimmten Verbindungsstring-Parameter:

Details: java.lang.IllegalArgumentException - JDBC connection parameter 'allowmultiqueries' cannot be enabled.

Mögliche Ursache: Agent-Version 12.10 und später beschränkt standardmäßig bestimmte Datenbankverbindungen und Verbindungsstring-Parameter aus Sicherheitsgründen. Dies umfasst Verbindungen zu localhost oder 127.0.0.1 sowie bestimmte Verbindungsstring-Parameter für MySQL-, PostgreSQL-, Oracle- und SQL Server-Treiber. Eine Verbindung, die vorher funktioniert hat, kann nach der Aktualisierung eines Private Agents auf Version 12.10 fehlschlagen, da die Beschränkung standardmäßig gilt, obwohl der Abschnitt [JdbcSecurity] nicht automatisch zu einer vorhandenen jitterbit.conf-Datei hinzugefügt wird.
Lösung: Konfigurieren Sie auf einem privaten Agent den Abschnitt [JdbcSecurity] der Agent-Konfigurationsdatei (jitterbit.conf), um die spezifische Verbindung oder den benötigten Parameter zuzulassen, und starten Sie den Agent neu.

Datenbank: Verbindungszeitüberschreitungen unter Last

Symptom: Datenquellen- oder Zieloperationen schlagen unter starker gleichzeitiger Last zeitweise fehl und zeigen eine ähnliche Ausnahme:
```
java.sql.SQLException: Network error IOException: Connection timed out
Caused by: java.net.ConnectException: Connection timed out
```
Mögliche Ursache: Jede Datenbankoperation öffnet eine neue physische JDBC-Verbindung und schließt sie anschließend, anstatt eine vorhandene wiederzuverwenden. Unter gleichzeitiger Last entsteht dadurch eine so hohe Verbindungsauslastung für die Zieldatenbank, dass es bei manchen Verbindungsversuchen zu Zeitüberschreitungen kommt.
Lösung: Agent-Version 12.11 und später können Verbindungen zusammenfassen und wiederverwenden, anstatt für jede Operation eine neue zu öffnen und zu schließen, wodurch diese Auslastung reduziert wird. Setzen Sie auf einem privaten Agent jdbc.hikari.enabled=true im Abschnitt [SourceTargetPooling] der Agent-Konfigurationsdatei (jitterbit.conf) und starten Sie den Agent neu.

Datenbank: Feldlängenfehler bei Insert, Update oder Upsert

Symptom: Eine Datenbank-Aktivität vom Typ Insert, Update oder Upsert schlägt mit dem Operationsstatus Fehler fehl, wenn ein zugeordneter Quellwert länger ist als die Zieldatenbank zulässt. Das Operationsprotokoll enthält eine der folgenden Meldungen:
```
One or more values were truncated when inserting and/or updating the field
```
```
Field value too long
FieldName: m_site  Length: 3  Length Allowed: 1
```
Mögliche Ursache: Standardmäßig lehnt die Aktivität die Zeile ab und meldet den Status Fehler, wenn ein zugeordneter Quellwert die definierte Länge der Zieldatenbank überschreitet, anstatt den Wert zu kürzen.
Lösung:
1. Aktivieren Sie in der Konfiguration der Datenbank-Aktivität Insert, Update oder Upsert die Option Kürzung von Textfeldern zulassen, um Feldlängenfehler zu vermeiden. Mit dieser Option werden Werte, die die Zielfeld-Länge überschreiten, gekürzt und die Operation meldet den Status Erfolg mit Info anstelle von Fehler.
2. Falls Kürzung nicht akzeptabel ist, kürzen oder transformieren Sie das Quellfeld in der Transformationszuordnung so, dass Werte die Zielspaltenlänge nie überschreiten, oder erweitern Sie die Zielspaltenlänge auf der Datenbankseite.
3. Stellen Sie die Operation erneut bereit und führen Sie sie erneut aus.

Datenbank: JDBC-Treiber-JAR wird bei Agent-Updates überschrieben

Symptom: Benutzerdefinierte JDBC-Treiber-JAR-Dateien, die für den Datenbank-Connector installiert wurden, werden gelöscht oder überschrieben, wenn der Agent aktualisiert wird.
Mögliche Ursache: Nur das Verzeichnis <JITTERBIT_HOME>/tomcat/drivers/lib/ wird bei Agent-Aktualisierungen beibehalten. Benutzerdefinierte Treiber-JAR-Dateien, die an anderen Stellen in den Agent-Verzeichnissen abgelegt werden, sind Teil der verwalteten Bereitstellung und können während einer Aktualisierung entfernt oder überschrieben werden.
Lösung:
- Platzieren Sie benutzerdefinierte JDBC-Treiber-JAR-Dateien stattdessen in <JITTERBIT_HOME>/tomcat/drivers/lib/. Dieses Verzeichnis wird bei Agent-Aktualisierungen beibehalten.
- Falls sich Treiber derzeit an der falschen Stelle befinden, verschieben Sie sie in das richtige Verzeichnis und starten Sie den Agent neu.

Datenbank: Sonderzeichen in Spaltennamen verursachen Abfragefehler

Symptom: Datenbankabfragen oder Transformationen schlagen fehl, wenn eine Quelltabelle Spaltennamen mit Sonderzeichen wie @ enthält.
Mögliche Ursache: ODBC-Treiber können bestimmte Sonderzeichen in Datenbankspaltennamen nicht verarbeiten.
Lösung:
1. Erstellen Sie eine Datenbankansicht in der physischen Tabelle, die die betroffene Spalte unter einem Namen bereitstellt, der keine Sonderzeichen enthält.
2. Richten Sie die Datenbankaktivität auf die Ansicht anstelle der ursprünglichen Tabelle.

Datenbank: SQL-Anweisung überschreitet 2.000-Zeichen-Limit

Symptom: Eine Datenbankaktivität Query schlägt fehl oder wird abgeschnitten, wenn die konfigurierte SQL-Anweisung sehr lang ist.
Mögliche Ursache: Das Feld SQL-Anweisung in einer Datenbankaktivität Query akzeptiert maximal 2.000 Zeichen.
Lösung:
1. Erstellen Sie eine Datenbankansicht, die die komplexe Abfragelogik kapselt.
2. Referenzieren Sie den Namen der Ansicht in der Aktivität Query anstelle der vollständigen SQL-Anweisung.

IBM DB2 on iSeries: JDBC-Verbindung schlägt fehl

Symptom: Eine Datenbankverbindung zu IBM DB2 unter iSeries (AS/400 oder IBM i) mit einem JDBC-Treiber kann keine Verbindung herstellen.
Mögliche Ursache: Bei einigen Verbindungen zu DB2 unter iSeries mit einem JDBC-Treiber treten Probleme auf, die bei einem ODBC-Treiber nicht auftreten.
Lösung: Wechseln Sie die Verbindung zu einem ODBC-Treiber anstelle von JDBC. ODBC-Verbindungen werden nur auf privaten Agenten unterstützt.

IBM DB2: JCC JDBC-Treiber-Setup (veraltete JAR und Lizenzdatei)

Symptom: Eine Datenbankverbindung mit dem IBM DB2 JCC JDBC-Treiber schlägt mit einer Fehlermeldung fehl, die auf eine fehlende Lizenz verweist, oder schlägt fehl oder verursacht Kompatibilitätsfehler mit neueren DB2-Versionen.
Mögliche Ursachen:
- Die Treiberdatei db2jcc.jar implementiert die veraltete JDBC-3-Spezifikation. Die aktuelle db2jcc4.jar implementiert JDBC 4, das neuere DB2-Versionen erfordern.
- Der JCC-Treiber benötigt eine separate Lizenz-JAR-Datei. Die Treiber-JAR allein ist nicht ausreichend.
Lösung:
- Verwenden Sie den Treiber db2jcc4.jar, nicht das veraltete db2jcc.jar. Installieren Sie diesen in <JITTERBIT_HOME>/tomcat/drivers/lib/ auf dem privaten Agent.
- Beziehen Sie die Lizenz-JAR-Datei von IBM (benannt db2jcc_license_cisuz-XX.jar, wobei XX die Versionsnummer ist) und kopieren Sie sie in <JITTERBIT_HOME>/tomcat/shared/lib/.
- Verwenden Sie alternativ die Open-Source-Bibliothek JTOpen (auch als AS400-Treiber bekannt), die weder den JCC-Treiber noch eine Lizenzdatei erfordert.

Kerberos: „Could not initialize class KerbAuthentication"

Symptom: Eine Datenbankverbindung mit Kerberos-Authentifizierung schlägt fehl mit:
```
Could not initialize class com.microsoft.sqlserver.jdbc.KerbAuthentication
```
Mögliche Ursache: Die Kerberos-Konfigurationsdateien auf dem Agent-Host haben nicht die richtigen Dateiberechtigungen.
Lösung:
1. Legen Sie auf dem privaten Agent-Host die Dateiberechtigungen für die Kerberos-Konfigurationsdateien (jaas.conf, krb5.conf und die Kerberos-Ticket-Cache-Datei) auf 644 fest:

chmod 644 jaas.conf krb5.conf krb5cc_agent

Starten Sie den Agent neu, nachdem Sie die Berechtigungsänderungen angewendet haben.

Kerberos: JGSS- oder GSS-Fehler während Verbindungstest

Symptom: Eine Database-Verbindung mit Kerberos-Authentifizierung schlägt mit Fehlern fehl, die auf jgss oder gss verweisen.
Mögliche Ursache: Die JVM ist mit -Dsun.security.jgss.native=true konfiguriert, wodurch sie die native GSSAPI-Bibliothek des Betriebssystems verwendet. Auf einigen Systemen führt dies zu Konflikten mit der Kerberos-Konfiguration.
Lösung:
1. Entfernen Sie den Parameter -Dsun.security.jgss.native=true aus den JVM-Argumenten des Agents.
2. Fügen Sie in krb5.conf unter dem Abschnitt [libdefaults] den Eintrag udp_preference_limit = 1 hinzu, um TCP statt UDP für Kerberos-Datenverkehr zu erzwingen.
3. Starten Sie den Agent neu.

Microsoft Excel: „Operation must use an updateable query"

Symptom: Eine Database-Aktivität vom Typ Insert oder Update für eine Microsoft-Excel-Datei (über ODBC) schlägt mit folgendem Fehler fehl:
```
[Microsoft][ODBC Excel Driver] Operation must use an updateable query
```
Mögliche Ursache: Der ODBC-Excel-Treiber öffnet die Excel-Datei standardmäßig im schreibgeschützten Modus, sofern die Verbindungszeichenfolge nicht explizit den Lese-/Schreibmodus festlegt.
Lösung: Fügen Sie im Feld Connection String der Datenbankverbindung (eingegeben unter Optional Settings mit ausgewählter Option Use Connection String) am Ende der Verbindungszeichenfolge ReadOnly=0; hinzu, um die Excel-Datei im Lese-/Schreibmodus zu öffnen.

MySQL: Zugriff verweigert trotz korrekter Anmeldedaten

Symptom: Das Verbinden mit einer MySQL-Datenbank mithilfe des Database Connectors schlägt mit folgendem Fehler fehl:
```
Access denied for user 'root'@'%' to database 'test'
```
obwohl der Benutzername und das Passwort korrekt sind.
Mögliche Ursache: MySQL kann je nach Client-IP-Adresse unterschiedliche Berechtigungen gewähren. Ein Benutzerkonto kann über bestimmte IP-Adressen die erforderlichen Berechtigungen haben, aber nicht über die IP-Adresse des privaten Agents.
Lösung:
- Überprüfen Sie in MySQL, dass das Benutzerkonto die erforderlichen Berechtigungen für Verbindungen von der IP-Adresse des privaten Agents hat. Die genaue Grant-Syntax ist je nach MySQL-Version unterschiedlich (siehe MySQL-Dokumentation oder kontaktieren Sie Ihren MySQL-Administrator), folgt aber grundsätzlich diesem Format:
```
GRANT ALL ON database.* TO 'user'@'agent-ip';
```
- Testen Sie die Verbindung mit einem MySQL-Client, der direkt auf dem Agent-Host installiert ist, um zu prüfen, ob das Problem netzwerkbasiert oder Jitterbit-spezifisch ist.

MySQL: Enable Batch verbessert Insert- oder Update-Leistung nicht

Symptom: Eine Database-Aktivität vom Typ Insert oder Update mit dem MySQL-JDBC-Treiber zeigt nach der Aktivierung von Enable Batch wenig oder keine Leistungsverbesserung, auch bei einer großen Anzahl von Datensätzen.
Mögliche Ursache: Der MySQL-JDBC-Treiber (Connector/J) sendet standardmäßig unabhängig von Enable Batch eine Anweisung pro Zeile, anstatt ein echtes serverseitiges Batch durchzuführen.
Lösung: Fügen Sie im Feld Additional Connection String Parameters der Verbindung rewriteBatchedStatements=true hinzu.

MySQL: ODBC-Treiber wird in Studio-Dropdown nicht aufgelistet

Symptom: Beim Konfigurieren einer Datenbankverbindung zu MySQL mit einem ODBC-Treiber auf einem privaten Agent wird der installierte Treiber nicht in der Dropdown-Liste Treiber in Studio angezeigt.
Mögliche Ursache: Der ODBC-Manager auf dem privaten Agent-Host zeigt den Treiber nicht an, normalerweise wegen eines Missverhältnisses zwischen 32-Bit und 64-Bit oder einer unvollständigen Treiberinstallation.
Lösung:
- Öffnen Sie auf dem privaten Agent-Host (Windows) Datenquellen (ODBC) (unter Verwaltungsprogramme) und bestätigen Sie, dass der MySQL ODBC-Treiber aufgeführt ist. Informationen zu MySQL-Treiberoptionen finden Sie unter Mit MySQL verbinden.
- Bestätigen Sie, dass der Agent sich mit dem richtigen Computer verbindet: Der ODBC-Treiber muss auf dem Agent-Host installiert sein, nicht auf dem Computer des Studio-Benutzers.

PostgreSQL: Client-Encoding-Fehler

Symptom: Ein Datenbankverbindungs-Test zu PostgreSQL schlägt mit einem Fehler "Client-Encoding-Mismatch" fehl.
Mögliche Ursache: Die vom PostgreSQL-Server verwendete Codierung unterscheidet sich von der Standardcodierung, die vom PostgreSQL ODBC-Treiber vorausgesetzt wird.
Lösung:
- Fügen Sie in den Datenbankverbindungseinstellungen ConnSettings=SET CLIENT_ENCODING to 'LATIN1' (ersetzen Sie durch die tatsächliche Codierung des Servers) zum Feld Zusätzliche Verbindungszeichenfolgen-Parameter hinzu.
- Legen Sie unter Windows, wenn der Server eine kyrillische Codierung wie WIN1251 verwendet, die Client-Codierung in den ODBC-Treibereinstellungen auch auf WIN1251 fest.

PostgreSQL: Verwenden Sie den von Jitterbit bereitgestellten Treiber unter Linux

Symptom: Operationen, die den Datenbankverbinder verwenden, um sich von einem privaten Linux-Agent aus mit PostgreSQL zu verbinden, schlagen fehl oder erzeugen Fehler, selbst wenn ein Treiber installiert zu sein scheint.
Mögliche Ursache: Viele Linux-Distributionen enthalten einen PostgreSQL ODBC-Treiber, der mit unixODBC verpackt ist und nicht zuverlässig mit Harmony funktioniert.
Lösung: Verwenden Sie nicht den von der Distribution verpackten PostgreSQL-Treiber. Verwenden Sie stattdessen den PostgreSQL ODBC-Treiber, der mit der Jitterbit-Agent-Installation gebündelt ist.

SQL Server JDBC: Windows-integrierte Authentifizierung schlägt fehl

Symptom: Bei privaten Agents schlägt eine Datenbankverbindung zu SQL Server mit einem JDBC-Treiber und Windows-integrierter Authentifizierung fehl mit:
```
This driver is not configured for integrated authentication. ClientConnectionId:...
```
Bei Verwendung des SQL Server MS JDBC-Treibers können die Agent-Protokolle auch Folgendes anzeigen:
```
java.lang.UnsatisfiedLinkError: no mssql-jdbc_auth-8.2.0.x64 in java.library.path
```
Mögliche Ursachen:
- Verwendung des SQL Server jTDS-Treibers: Die Datei ntlmauth.dll, die für die Windows-integrierte Authentifizierung erforderlich ist, fehlt im JRE-Verzeichnis, das der Jitterbit-Agent zur Laufzeit verwendet.
- Verwendung des SQL Server MS JDBC-Treibers oder eines neueren Microsoft JDBC Driver for SQL Server: Die Datei mssql-jdbc_auth DLL, die für die Windows-integrierte Authentifizierung erforderlich ist, fehlt in den JRE-Verzeichnissen, die der Jitterbit-Agent zur Laufzeit verwendet. Das Platzieren der DLL im gleichen Verzeichnis wie die JDBC JAR-Datei ist nicht ausreichend.
- Die Verbindungszeichenfolge enthält nicht die erforderlichen Parameter für Ihren Treiber.
Lösung: Wähle die Option, die zu deinem JDBC-Treiber passt:
- SQL Server jTDS:
  1. Kopiere auf dem Host des privaten Agenten ntlmauth.dll (aus dem Ordner x64/SSO des jTDS-Projektdownload-Pakets) in <JITTERBIT_HOME>/jre/bin.
  2. Füge in den Datenbankverbindungseinstellungen integratedSecurity=true zum Feld Zusätzliche Verbindungszeichenfolgen-Parameter hinzu.
  3. Starte den Jitterbit-Agent-Dienst neu.
- SQL Server MS JDBC oder neuere Microsoft JDBC Driver für SQL Server:
  1. Kopiere auf dem Host des privaten Agenten mssql-jdbc_auth-x.x.x.x64.dll (aus der JDBC-Treiberverteilung, mit der Version, die der JDBC-JAR-Datei gebündelt mit deinem Agent entspricht) in beide Verzeichnisse: <JITTERBIT_HOME>/jre/bin und <JITTERBIT_HOME>/jre/lib. Erstelle eine Sicherung der Datei, da diese während größerer Agent-Upgrades entfernt werden kann.
  2. Füge in den Datenbankverbindungseinstellungen integratedSecurity=true;trustServerCertificate=true zum Feld Zusätzliche Verbindungszeichenfolgen-Parameter hinzu.
  3. Starte den Jitterbit-Agent-Dienst neu.

SQL Server Windows-Authentifizierung: Unzureichende Berechtigungen

Symptom: Eine Datenbankverbindung mit SQL Server Windows-Authentifizierung schlägt fehl, obwohl die Domänenanmeldedaten korrekt zu sein scheinen.
Mögliche Ursache: Der Windows-Domänenbenutzer, der den Jitterbit-Agent-Dienst ausführt, verfügt nicht über die erforderlichen Berechtigungen auf Betriebssystemebene für Windows-integrierte Sicherheit.
Lösung:
1. Gewähre dem Domänenbenutzer auf dem Host des privaten Agenten die Windows-Berechtigungen Anmelden als Dienst und Agieren als Teil des Betriebssystems.
2. Bestätige, dass der Domänenbenutzer Lese- und Schreibberechtigungen für das Installationsverzeichnis des Jitterbit-Agenten hat.
3. Starte den Jitterbit-Agent-Dienst neu, nachdem du die Berechtigungen angewendet hast.

SQL Server: „Cannot insert explicit value for identity column" beim Einfügen in eine Identitätsspalte

Symptom: Ein Vorgang des Datenbankconnectors, der in eine SQL Server-Tabelle mit einer Identitätsspalte schreibt, schlägt fehl mit:
```
Database Error: Cannot insert explicit value for identity column in table '<table>' when IDENTITY_INSERT is set to OFF.
```
Mögliche Ursache: Die Identitätsspalte ist in der INSERT-Anweisung enthalten, die der Datenbankconnector für das Ziel generiert. SQL Server lehnt eine INSERT ab, die eine Identitätsspalte in ihrer Spaltenliste referenziert (mit einem expliziten Wert oder einem Nullwert), während IDENTITY_INSERT auf OFF gesetzt ist. Die Zuordnung des Felds zu einem Nullwert schließt es nicht aus: Ein Zielfeld wird aus der INSERT nur dann weggelassen, wenn es mit der Funktion Unmap zugeordnet ist.
Lösung:
- Um SQL Server die Identitätswert automatisch zuweisen zu lassen, schließe die Spalte aus der INSERT aus, indem du das Zielfeld der Identität mit der Funktion Unmap zuordnest. Um die Spalte nur auszuschließen, wenn die Quelle keinen Wert bereitstellt, verwende eine bedingte Zuordnung:
```
If($source.id != "", $source.id, Unmap())
```
  Wenn die Bedingung falsch ist, entfernt Unmap die Spalte aus der INSERT und SQL Server weist den nächsten Identitätswert zu. (Das Angeben eines expliziten Werts im wahren Zweig erfordert weiterhin, dass IDENTITY_INSERT auf ON gesetzt ist; siehe die nächste Option.)
- Wenn du explizite Werte in die Identitätsspalte einfügen musst, setze IDENTITY_INSERT auf der Zieltabelle in Pre- und Post-SQL-Skripten innerhalb der Aktivität:

SET IDENTITY_INSERT <table> ON;

SET IDENTITY_INSERT <table> OFF;

Verwenden Sie diese Option nur, wenn Sie absichtlich Identitätswerte von außerhalb der Datenbank steuern möchten. Dies ermöglicht es, explizite Werte in die Identitätsspalte einzufügen.

SQL Server: Verbindung schlägt mit einem PKIX-Zertifikatpfad-Fehler fehl

Symptom: Eine Datenbankverbindung zu SQL Server schlägt fehl mit:

"encrypt" property is set to "true" and "trustServerCertificate" property is set to "false" but the driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption: Error: (certificate_unknown) PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.

Eine Verbindung, die zuvor funktionierte, kann nach einem Agent-Upgrade auf Version 12.8 oder später fehlschlagen.

Mögliche Ursache: Aktuelle Versionen des SQL Server MS JDBC-Treibers fordern standardmäßig eine verschlüsselte Verbindung an und validieren das Zertifikat, das der Datenbankserver präsentiert. Die Verbindung schlägt fehl, wenn dieses Zertifikat nicht auf eine Zertifizierungsstelle (CA) zurückgeführt werden kann, der der Agent bereits vertraut, z. B. ein selbstsigniertes Zertifikat, ein intern ausgestelltes Zertifikat oder das Amazon-RDS-CA-Zertifikat, das eine Amazon RDS für SQL Server-Instanz präsentiert. Dies ist ein Fehler des Zertifikatvertrauens und nicht der Verschlüsselung, daher kann eine Datenbank Verschlüsselung aktiviert haben und ein gültiges Zertifikat installiert haben und trotzdem fehlschlagen. Agent-Version 12.8 hat den gebündelten Treiber auf eine Version aktualisiert, die standardmäßig Verschlüsselung anfordert, daher kann eine vor diesem Upgrade konfigurierte Verbindung danach fehlschlagen.
Lösung: Geben Sie encrypt=false; im Feld Zusätzliche Verbindungszeichenfolgen-Parameter unter Optionale Einstellungen der Datenbankverbindung ein, oder beziehen Sie es in eine manuelle Verbindungszeichenfolge ein. Dies funktioniert auf Cloud- und privaten Agenten. Weitere Informationen finden Sie unter Verbindungsverschlüsselung und Serverzertifikate.

Warnung

Bei encrypt=false werden Daten zwischen dem Agent und der Datenbank unverschlüsselt übertragen. Verwenden Sie diese Option nur, wenn dies für die betroffenen Daten und den Netzwerkpfad akzeptabel ist.

E-Mail: Send Email schlägt fehl, wenn dieselbe Adresse in mehreren Empfängerfeldern erscheint

Symptom: Eine E-Mail-Aktivität E-Mail senden schlägt zur Laufzeit fehl, wenn dieselbe E-Mail-Adresse in mehr als einem der Felder An, CC oder BCC vorhanden ist.
Mögliche Ursache: Der E-Mail-Connector lässt nicht zu, dass dieselbe Adresse in einer einzelnen Sendeanforderung in mehreren Empfängerfeldern angezeigt wird. Dies gilt für Adressen, die direkt in der Aktivität konfiguriert sind, und für Adressen, die dynamisch durch eine Transformationszuordnung bereitgestellt werden.
Lösung:
- Überprüfen Sie die Felder An, CC und BCC in der Aktivitätskonfiguration und in allen Transformationszuordnungen für die Aktivität, um zu bestätigen, dass keine Adresse in mehr als einem Feld angezeigt wird.
- Wenn Empfängerlisten dynamisch mit Variablen oder Skripten zusammengestellt werden, fügen Sie vor dem Übergeben von Adressen an die Aktivität eine Deduplizierungsprüfung hinzu.

E-Mail: Gmail-Verbindungstest schlägt mit Authentifizierungsfehler fehl

Symptom: Ein Verbindungstest zu einem Gmail-Konto mit Basis-Authentifizierung schlägt mit einem Authentifizierungsfehler fehl, auch wenn das richtige Google-Kontopasswort eingegeben wird.
Mögliche Ursache: Google erfordert ein App-Passwort für Konten mit aktivierter Zwei-Faktor-Authentifizierung. Das Google-Kontopasswort wird von SMTP oder IMAP nicht akzeptiert, wenn die Zwei-Faktor-Authentifizierung aktiv ist; nur App-Passwörter werden akzeptiert.
Lösung:
1. Generieren Sie in Ihrem Google-Konto ein App-Passwort für die Jitterbit-Anwendung (siehe Google's Mit App-Passwörtern anmelden-Seite).
2. Geben Sie in der E-Mail-Verbindungskonfiguration in Studio das App-Passwort im Feld SMTP-Passwort und/oder IMAP-Passwort statt des Google-Kontopassworts ein.

E-Mail: S/MIME-Signierung schlägt fehl oder wird von Cloud-E-Mail-Anbietern abgelehnt

Symptom: E-Mails, die mit S/MIME-Signierung konfiguriert sind, können nicht versendet werden, werden vom Server des Empfängers abgelehnt oder kommen unsigniert an, wenn ein Cloud-E-Mail-Anbieter wie Microsoft 365 oder Exchange Online verwendet wird.
Mögliche Ursachen:
- Cloud-Anbieter erfordern ein S/MIME-Zertifikat, das von einer vertrauenswürdigen Zertifizierungsstelle (CA) ausgestellt wurde. Selbstsignierte Zertifikate werden von Cloud-Anbietern wie Microsoft 365 (Exchange Online) nicht akzeptiert.
- S/MIME ist nur bei Verwendung von privaten Agenten funktionsfähig. Wenn der Vorgang auf einem Cloud-Agent ausgeführt wird, ist die S/MIME-Signierung unabhängig vom Zertifikattyp nicht anwendbar.
Lösung:
1. Besorgen Sie sich ein S/MIME-Zertifikat von einer vertrauenswürdigen CA. Let's Encrypt stellt kostenlose Zertifikate bereit, die von großen Cloud-Anbietern akzeptiert werden.
2. Ersetzen Sie das selbstsignierte Zertifikat in der E-Mail-Aktivität E-Mail senden durch das von der CA ausgestellte Zertifikat (siehe Voraussetzungen für S/MIME-Verschlüsselung).
3. Bestätigen Sie für private Agenten, dass das Zertifikat ordnungsgemäß in den Standard-Truststore des Agenten importiert wurde. Für Cloud-Agenten wird die S/MIME-Signierung nicht unterstützt.

E-Mail: Microsoft 365 (ROPC)-Authentifizierung schlägt fehl, wenn MFA aktiviert ist

Symptom: Eine Microsoft 365-OAuth-2.0-Verbindung, die die ROPC-Authentifizierung (Resource Owner Password Credentials) verwendet, kann sich nicht authentifizieren, auch wenn der Benutzername, das Kennwort, die Client-ID, die Mandanten-ID und das Client-Geheimnis alle korrekt sind.
Mögliche Ursache: Die ROPC-Authentifizierung erfordert, dass die mehrstufige Authentifizierung (MFA) für die Microsoft 365-Anmeldedaten deaktiviert ist, die mit dem Connector verwendet werden. Die ROPC-Bewilligung kann eine MFA-Anforderung nicht erfüllen, daher schlägt die Token-Anforderung fehl, wenn eine MFA-Richtlinie für das Konto gilt.
Lösung:
- Verwenden Sie ein Microsoft 365-Konto, dessen Anmeldedaten nicht einer MFA-Richtlinie unterliegen. Um die Sicherheit zu gewährleisten, erstellen Sie einen dedizierten Microsoft Entra ID-Mandanten oder ein Verzeichnis, das MFA nicht erzwingt, wie in Voraussetzungen für Microsoft 365 beschrieben.
- Wenn MFA nicht aus dem Konto entfernt werden kann, verwenden Sie für die Verbindung eine andere unterstützte Authentifizierungsmethode anstelle von ROPC.

Epicor Prophet 21: Operation schlägt bei der Ausführung mit mehreren Filterbedingungen fehl

Symptom: Eine Epicor Prophet 21 Query-Aktivität schlägt zur Laufzeit fehl, wenn der Filter String mehr als eine Filterbedingung enthält, obwohl die Aktivität in Studio gültig erscheint.
Mögliche Ursache: Eine Beschränkung der Epicor Prophet 21 Middleware API verhindert die Verarbeitung mehrerer Filterbedingungen. Der Vorgang erscheint in Studio gültig, schlägt jedoch zur Laufzeit fehl, wenn mehr als ein Filter vorhanden ist.
Lösung:
- Den Filter String auf eine einzelne Filterbedingung reduzieren.
- Falls mehrere Filterbedingungen erforderlich sind, ein breiteres Ergebnisset mit einem einzelnen Filter abrufen und die zusätzliche Filterung in einem Transformations- oder Skriptschritt nach der Aktivität anwenden.

FTP, Dateifreigabe und lokaler Speicher: „Keine Dateien entsprechen dem Dateifilter" bei Archiv- oder Folgenschritten

Symptom: Eine FTP-, File Share- oder Local Storage-Leseaktivität schlägt fehl, weil sich die zu lesende Datei nicht mehr im Quellpfad befindet:
```
Failed to read file from the source "Read". Reason: No files match the file filter "<filter>".
```
Die Aktivität, die die Datei zuvor verarbeitet hat, war erfolgreich. Der Fehler tritt bei einem späteren Schritt (häufig ein Archivierungs- oder Benachrichtigungsschritt) auf, der versucht, dieselbe Datei mit demselben Filter zu lesen.
Mögliche Ursachen:
- Die Verarbeitungsaktivität hat die Quelldatei bereits als Teil ihres After Processing-Verhaltens verschoben oder gelöscht, daher hat der Archivierungsschritt nichts mehr zum Abgleichen.
- Ein untergeordneter Vorgang wird asynchron gestartet und der übergeordnete Vorgang versucht, die Ausgabedatei des untergeordneten Vorgangs zu lesen, bevor dieser das Schreiben beendet hat.
- Eine FTP Write-Aktivität mit aktiviertem Use FTP Rename (Standard) schreibt die Datei unter einem temporären Namen und benennt sie bei Abschluss in den endgültigen Namen um. Ein nachgelagerter Lesevorgang, der vor Abschluss der Umbenennung ausgelöst wird, findet die Datei nicht.
Lösung:
- Bestätigen, ob der vorherige Schritt die Archivierung bereits über seine integrierten After Processing-Optionen (verschieben, umbenennen, löschen) durchgeführt hat. Falls ja, ist ein separater Archivierungsschritt redundant und sollte entfernt werden.
- Falls ein separater Archivierungsschritt erforderlich ist, die Kette neu gestalten, damit Verarbeitung und Archivierung gegen dieselbe In-Memory-Dateireferenz erfolgen, anstatt erneut aus der Quelle zu lesen. Beispielsweise den gelesenen Inhalt über Temporary Storage zum Archivierungsschritt durchreichen, anstatt den Quellpfad erneut zu lesen.
- Falls ein Folgeschritt eine Ausgabe liest, die von einem untergeordneten Vorgang produziert wird, den untergeordneten Vorgang synchron ausführen, sodass die Ausgabe vor dem Lesen vorhanden ist. Den Run type des Invoke Operation-Tools auf Synchronously setzen oder beim Aufrufen des Vorgangs aus einem Skript RunOperation synchron ausführen (Standard). Das Einfügen einer festen Verzögerung (z. B. mit der Sleep-Funktion) erhöht die Latenz und garantiert nicht, dass die Datei bereit ist.
- Falls eine FTP Write-Aktivität an denselben Speicherort schreibt, prüfen, ob Use FTP Rename auf der FTP Write-Aktivität aktiviert ist. Falls der nachgelagerte Lesevorgang vor Abschluss der Umbenennung ausgelöst wird, Use FTP Rename auf der Schreibaktivität deaktivieren oder sicherstellen, dass der Lesevorgang nicht ausgeführt wird, bis die Schreibaktivität vollständig abgeschlossen ist.

FTP, Dateifreigabe und lokaler Speicher: Fehlerordner wird bei Verbindungsfehler nicht geschrieben

Symptom: Nach einem Fehler bei einer FTP-, File Share- oder Local Storage-Aktivität erscheint keine Datei im konfigurierten Fehlerordner.
Mögliche Ursache: Der Fehlerordner ist dafür konzipiert, nach einer fehlgeschlagenen Verarbeitung eine Kopie der Quelldatei zu archivieren. Er erfasst Dateien nur, wenn die Aktivität ausgeführt wird und dann fehlschlägt (beispielsweise ein Schreibberechtigungsfehler auf dem Server). Wenn die Verbindung zum Server überhaupt nicht hergestellt werden kann, schlägt der Vorgang fehl, bevor die Aktivität eine Datei liest. Es gibt daher keine Datei, die in den Fehlerordner geschrieben werden kann.
Lösung:
- Wenn der Fehlerordner nach einem Fehler leer ist, überprüfen Sie die Vorgangsprotokolle auf einen Fehler auf Verbindungsebene (beispielsweise ein Authentifizierungsfehler oder eine Meldung, dass der Host unerreichbar ist).
- Verwenden Sie die Schaltfläche Testen für die Verbindung, um zu überprüfen, ob das Problem auf Netzwerk- oder Authentifizierungsebene liegt.

FTP, Dateifreigabe und lokaler Speicher: Dateinamenschlüsselwörter werden nicht in Erfolgreichs- und Fehlerordnerpfaden aufgelöst

Symptom: Vorgänge verschieben Dateien nach der Verarbeitung in Erfolgs- oder Fehlerordner, aber der Zielpfad enthält nicht erweiterten Schlüsselworttext anstelle aufgelöster Werte. Der Vorgang kann fehlschlagen oder Dateien an unerwartete Speicherorte schreiben.
Mögliche Ursachen:
- Die Felder für den Erfolgsordner und den Fehlerordnerpfad in FTP-, File Share- und Local Storage-Aktivitäten unterstützen keine Ersetzung von Dateiname-Schlüsselwörtern. Variablen werden in diesen Feldern nicht erweitert.
- Diese Felder verweisen auf Verzeichnisse auf dem Private-Agent-Computer und nicht auf dem Remote-Server. Relative Pfade werden relativ zum Dateisystem des Agent-Hosts interpretiert.
Lösung:
- Verwenden Sie nur wörtliche Pfade (ohne Dateiname-Schlüsselwortvariablen) für die Erfolgs- und Fehlerordnerfelder.
- Wenn dynamische Pfade erforderlich sind, fügen Sie nach der Aktivität einen Skriptschritt hinzu, um die verarbeitete Datei mithilfe von Dateienfunktionen an den gewünschten Speicherort zu verschieben oder umzubenennen.

FTP, Dateifreigabe, lokaler Speicher und temporärer Speicher: „Write Headers" erzeugt keine Datei nur mit Kopfzeilen, wenn die Quelle keine Datensätze zurückgibt

Symptom: Eine dateibasierte Schreibaktivität mit aktivierter Option Kopfzeilen schreiben (FTP Write, File Share Write, Local Storage Write oder Temporary Storage Write) schreibt keine Kopfzeilen, wenn die Quelle keine Datensätze zurückgibt. Es wird entweder eine leere Datei erstellt oder überhaupt keine Datei erstellt (wenn auch Keine leeren Dateien erstellen ausgewählt ist).
Ursache: Dies ist das erwartete Verhalten. Kopfzeilen werden als Teil der Transformationsausgabe geschrieben, und die Transformation wird nur ausgeführt, wenn die Quelle mindestens einen Datensatz zurückgibt. Wenn die Quelle keine Datensätze zurückgibt, wird die Transformation übersprungen, daher wird keine Ausgabe (einschließlich Kopfzeilen) geschrieben, und Studio protokolliert eine Warnung, dass die Quelle leer ist. Dies ist nicht spezifisch für einen bestimmten Quellkonnektor oder ein flaches Dateiziel.

FTP: Operation schlägt nach vielen schnellen Anmeldungen auf demselben Server fehl

Symptom: Eine Operation mit dem FTP-Connector (über das FTP- oder SFTP-Protokoll), der sich in schneller Folge mehrmals beim selben Server authentifiziert (z. B. beim Lesen von Hunderten von kleinen Dateien in einer Schleife oder bei vielen Operationen, die nach einem Zeitplan auf demselben Server ausgeführt werden), schlägt schließlich mit einer Anmeldungsverweigerung oder einem Verbindungsfehler fehl. Dieselbe Operation funktioniert unter leichterer Last.
Mögliche Ursachen:
- Der FTP-Connector öffnet und authentifiziert für jede Activity-Ausführung eine neue Verbindung und schließt sie, wenn die Operation endet; eine Session wird nicht über Activities, über Operation-Durchläufe oder über Projekte hinweg wiederverwendet. Dies ist beabsichtigt. Wenn viele Operationen auf demselben Server ausgeführt werden, beispielsweise mehrere geplante Operationen oder mehrere Projekte, die auf denselben Host abzielen, authentifiziert sich jeder Durchlauf unabhängig.
- Der Remote-Server ist mit einer maximalen Anzahl von Verbindungen, Authentifizierungen pro Minute oder gleichzeitigen Sessions pro Benutzer konfiguriert, und die kombinierte Jitterbit-Anmeldungsrate überschreitet diesen Grenzwert.
Lösung:
- Gestalten Sie die Operation nach Möglichkeit so um, dass weniger Verbindungen erforderlich sind. Ersetzen Sie eine Read-Activity in einer Schleife durch eine einzelne Read-Activity, die einen Platzhalter im Feld Get Files verwendet (z. B. *.xml oder data_*.csv), und teilen Sie die abgerufenen Daten dann in einzelne Records in einer Transformation auf.
- Wenn die Operation Dateien einzeln verarbeiten muss, bitten Sie den FTP-Server-Administrator, den Grenzwert pro Benutzer für gleichzeitige Verbindungen oder Authentifizierungen pro Minute zu erhöhen.

SFTP „Login denied. Authentication failure." bei Verwendung von SSH-Schlüsseln

Symptom: Eine SFTP-Operation mit SSH-Private-Key-Authentifizierung schlägt mit Login denied. Authentication failure. fehl, obwohl sich dieselben Schlüssel von einem interaktiven SFTP-Client aus erfolgreich authentifizieren.
```
Failed to get ftp directory list for url sftp://example.com:22/. Login denied. Authentication failure.
```
Mögliche Ursachen:
- Der private Schlüssel ist durch eine Passphrase geschützt, aber die PrivateKeyPassphrase-Einstellung fehlt in der [SSH]-Sektion der Datei jitterbit.conf des Agenten.
- Im FTP-Endpoint ist neben dem privaten Schlüssel ein Passwort konfiguriert. Das Vorhandensein eines Passworts in den Endpoint-Einstellungen beeinträchtigt die schlüsselbasierte Authentifizierung.
Lösung:
- Bestätigen Sie bei privaten Agenten, dass die [SSH]-Sektion von jitterbit.conf den korrekten PrivateKeyFile-Pfad und, falls der Schlüssel mit einer Passphrase geschützt ist, den entsprechenden PrivateKeyPassphrase-Wert enthält (siehe Verbindung zu SFTP mit SSH-Schlüsseln).
- Löschen Sie im FTP-Endpoint-Konfiguration das Feld Password, wenn die Authentifizierung per SSH-Schlüssel erfolgt.
- Bestätigen Sie, dass der Schlüssel in einem vom Agent unterstützten Format (OpenSSH) vorliegt. Konvertieren Sie den Schlüssel mit ssh-keygen, falls er im PuTTY-Format (.ppk) oder einem anderen nicht-OpenSSH-Format vorliegt.

FTP Write: „Use FTP Rename" schlägt beim Schreiben auf einen SFTP-Server fehl

Symptom: Eine FTP-Write-Activity mit der Option Use FTP Rename schlägt fehl, wenn das Ziel ein SFTP-Server ist, mit einem Fehler ähnlich wie:
```
Failed to put ... to the url ...
Quote command returned error. Rename command failed: <reason>.
```
<reason> ist normalerweise No such file or directory oder Permission denied für eine Datei, deren Name Multibyte-Zeichen enthält.
Mögliche Ursachen:
- Bei Agenten vor Version 11.56 funktioniert die Option Use FTP Rename beim Schreiben auf einen SFTP-Server nicht zuverlässig, besonders bei Archive-Pattern-Operationen.
Der Dateiname enthält Multibyte-Zeichen und der SFTP-Server unterstützt das Umbenennen von Dateien mit solchen Namen nicht. Ab Agent-Version 12.8 kann der FTP-Connector Dateien mit Multibyte-Namen lesen und schreiben. Bei Use FTP Rename lädt der Agent die Datei jedoch unter einem temporären Namen (Suffix -jbupload) hoch und benennt sie dann um, und wenn der Server die Multibyte-Namen nicht umbenennen kann, wird eine irreführende Fehlermeldung Permission denied zurückgegeben. Dateinamen mit nur ASCII-Zeichen sind nicht betroffen. Dies ist eine Beschränkung des SFTP-Servers und nicht von Jitterbit.
Lösung:
- Stellen Sie sicher, dass der Agent Version 11.56 oder höher ist, wobei Use FTP Rename mit SFTP wie erwartet funktioniert. Cloud-Agenten werden automatisch aktualisiert. Aktualisieren Sie private Agenten bei Bedarf.
- Deaktivieren Sie das Kontrollkästchen Use FTP Rename in der Aktivitätskonfiguration, damit der Agent direkt in den Zielpfad schreibt, anstatt unter einem temporären Namen hochzuladen und umzubenennen. Dies vermeidet den Umbenennungsschritt und behebt beide Ursachen.
- Für den Multibyte-Fall können Sie alternativ einen SFTP-Server verwenden, der das Umbenennen von Dateien mit Multibyte-Namen unterstützt.

SFTP: An Datei anhängen wird nicht unterstützt

Symptom: Eine FTP-Aktivität Schreiben, die mit der Option Append To File konfiguriert ist, fügt nicht an die bestehende Datei an, wenn das Ziel ein SFTP-Server ist.
Mögliche Ursache: Das SFTP-Protokoll unterstützt das Anfügen an bestehende Dateien nicht. Dies ist eine Beschränkung auf Protokollebene und kein Jitterbit-Konfigurationsproblem.
Lösung:
- Verwenden Sie FTP oder FTPS, wenn das Anfügeverhalten erforderlich ist.
- Wenn SFTP erforderlich ist, implementieren Sie die Anfügelog manuelle: Lesen Sie den Inhalt der bestehenden Datei, kombinieren Sie ihn mit den neuen Daten und schreiben Sie das vollständige Ergebnis als vollständige Datei zurück.

FTP: Dateinamen mit `#` werden nicht korrekt verarbeitet

Symptom: Eine FTP-Connector-Aktivität (über FTP- oder SFTP-Protokoll) schlägt fehl, wenn der Quell- oder Zieldateiname ein Hash-Zeichen (#) enthält. Das Lesen der Datei gibt einen Fehler wie No File with that name oder Error in SSH Layer zurück, und das Schreiben der Datei erzeugt einen abgeschnittenen Dateinamen.
Mögliche Ursache: Der FTP-Connector behandelt den Dateipfad als URL, in der das Hash-Zeichen ein reserviertes Fragment-Trennzeichen ist. Der Connector verarbeitet den Teil des Pfads vor dem # und verwirft den Rest.
Lösung:
- Benennen Sie die Dateien um, um das Zeichen # zu entfernen oder zu ersetzen, bevor Jitterbit sie liest oder schreibt.
- Um den Connector so zu verwenden, dass Namen mit Sonderzeichen wie # URL-kodiert werden, setzen Sie jitterbit.source.ftp.encode_url in einem Transformationsskript für Quellnamen auf true und jitterbit.target.ftp.encode_url auf true für Dateien, die ins Ziel geschrieben werden.

Symptom: Dateifreigabe-Verbindungen, die UNC-Pfade verwenden (z. B. \\server\share), können nicht verbunden werden, wenn der Vorgang auf einem Cloud-Agent ausgeführt wird.
Mögliche Ursache: Cloud-Agenten können UNC-Pfade mit einer öffentlichen IP-Adresse auflösen, können aber keine Servernamen in UNC-Pfaden auflösen.
Lösung:
- Ersetzen Sie den Servernamen im UNC-Pfad durch die öffentliche IP-Adresse des Servers (z. B. \\192.0.2.1\share).
- Wenn die Servername-Auflösung in UNC-Pfaden erforderlich ist, verwenden Sie stattdessen einen privaten Agent.

Symptom: Eine Dateifreigabe-Aktivität vom Typ Lesen kann möglicherweise einzelne Dateien größer als 2 GB nicht abrufen. Kleinere Dateien werden ohne Probleme abgerufen.
Mögliche Ursache: Der Dateifreigabe-Connector hat eine bekannte Einschränkung bei einzelnen Dateien größer als 2 GB.
Lösung: Es gibt keine Konfigurationsoption, die diese Grenze entfernt. Teilen Sie die Datei als Abhilfemaßnahme an der Quelle in kleinere Segmente auf, sodass jede Datei unter 2 GB liegt, bevor die Dateifreigabe-Aktivität Lesen sie abruft.

Lokaler Speicher: Auf Cloud-Agenten nicht verfügbar

Symptom: Ein Vorgang mit einem Lokaler Speicher-Connector schlägt fehl, wenn er auf einem Cloud-Agent ausgeführt wird.
Mögliche Ursache: Der lokale Speicher greift auf das Dateisystem auf dem Computer zu, auf dem der Agent installiert ist. Cloud-Agents werden in einer gehosteten Umgebung ausgeführt und stellen kein lokales Dateisystem für diesen Zweck bereit.
Lösung:
- Verwenden Sie private Agents für alle Vorgänge, die den Connector für lokalen Speicher erfordern. Der lokale Speicher ist auf privaten Agents standardmäßig deaktiviert. Aktivieren Sie ihn daher auch in der Konfigurationsdatei des privaten Agents (siehe Lokalen Dateispeicherort aktivieren).
- Ersetzen Sie für Cloud-Agent-Workflows den lokalen Speicher durch Temporärer Speicher oder einen externen Speicher-Connector (Dateifreigabe, FTP oder Cloud Datastore).

Temporärer Speicher: Dateien fehlen, wenn sie von einer späteren Operation gelesen werden

Symptom: Temporärer Speicher-Dateien, die von einem Vorgang geschrieben wurden, fehlen, wenn ein späterer Vorgang versucht, sie zu lesen.
Mögliche Ursachen:
- Der Cleanup-Service von Harmony löscht Dateien nach 24 Stunden standardmäßig aus dem temporären Speicher.
- Jeder Agent in einer Agent-Gruppe hat seinen eigenen lokalen temporären Speicher. Vorgänge in der gleichen Vorgangskette werden garantiert auf dem gleichen Agent ausgeführt. Ein späterer Vorgang, der sich nicht in der gleichen Kette befindet, kann jedoch auf einen anderen Agent verteilt werden und auf eine andere Instanz des temporären Speichers zugreifen. Daher findet er die Datei unabhängig vom 24-Stunden-Fenster nicht. Siehe Wichtige Hinweise.
Lösung:
- Verknüpfen Sie Vorgänge, die Dateien des temporären Speichers gemeinsam nutzen müssen, in die gleiche Vorgangskette mit Vorgangsaktionen, wobei das Verhalten des temporären Speichers konsistent und zuverlässig ist.
- Bei privaten Agents kann die Cleanup-Häufigkeit im Bereich [FileCleanup] der Datei jitterbit.conf angepasst werden. Siehe [FileCleanup].
- Falls Dateien nicht in der gleichen Kette verarbeitet werden können oder länger als 24 Stunden erhalten bleiben müssen, verwenden Sie stattdessen einen persistenten Speicher-Connector, auf den alle Agents zugreifen können (z. B. Dateifreigabe, FTP oder Cloud Datastore).

Temporärer Speicher: Eingeschränkte Zeichen in Dateipfaden

Symptom: Eine Aktivität zum Lesen oder Schreiben im temporären Speicher schlägt fehl, wenn der Dateipfad bestimmte Sonderzeichen enthält.
Mögliche Ursache: Die folgenden Zeichen werden in Dateipfaden des temporären Speichers nicht unterstützt: ~, %, $, ", <, >, :, ?
Lösung:
- Entfernen Sie oder ersetzen Sie die nicht unterstützten Zeichen im Dateipfad. Die folgenden Zeichen werden unterstützt: !, @, #, ^, &, *, (, ), [, ], ', ;
- Sowohl / als auch \ werden als Pfadtrennzeichen akzeptiert.

Temporärer Speicher: Limit von 50 GB Dateigröße auf Cloud-Agenten

Symptom: Eine Temporärer Speicher-Write-Aktivität schlägt fehl, wenn große Dateien über einen Cloud-Agenten geschrieben werden.
Mögliche Ursache: Cloud-Agenten setzen eine maximale Dateigröße von 50 GB pro Datei für Temporären Speicher durch.
Lösung:
- Verwenden Sie einen privaten Agenten für Workflows, die einzelne Dateien größer als 50 GB in den Temporären Speicher schreiben müssen.
- Falls nur Cloud-Agenten verfügbar sind, teilen Sie große Datenmengen in mehrere Dateien von weniger als 50 GB auf, bevor Sie diese in den Temporären Speicher schreiben.

HTTP v2: Leerzeichen werden als `+` statt `%20` codiert

Symptom: REST-API-Aufrufe mit dem HTTP v2-Connector schlagen im Zielsystem fehl, weil Leerzeichen in der URL als + statt als %20 kodiert werden, was dazu führt, dass das Ziel einen Fehler „Ressource nicht gefunden" zurückgibt.
Lösung:
- Aktivieren Sie in der HTTP v2-Verbindung die Option Anfrage-URL kodieren. Der Connector kodiert dann die Anfrage-URL mit URL-Kodierung und kodiert Leerzeichen als %20.
- Geben Sie die Anfrage-URL vollständig unkodiert an. Kodieren Sie Zeichen nicht vorab und wenden Sie die Funktion URLEncode nicht auf die URL an, da bereits kodierte Zeichen doppelt kodiert werden, wenn Anfrage-URL kodieren aktiviert ist (beispielsweise wird example+string%20value zu example%20string%2520value).

HTTP v2: Antwortstatus-Code nicht in Jitterbit-Variablen verfügbar

Symptom: Skripte, die Jitterbit-Quell- oder Zielvariablen auslesen, um den HTTP-Antwortstatus-Code nach Ausführung einer HTTP v2-Aktivität zu erfassen, erhalten keinen Wert. Der gleiche Ansatz funktioniert mit dem HTTP-Connector, aber nicht mit HTTP v2.
Mögliche Ursache: Der HTTP v2-Connector füllt Jitterbit Quell- oder Zielvariablen nicht auf. Antwortdaten, einschließlich des HTTP-Status-Codes, werden stattdessen durch das Antwortschemata der Aktivität zurückgegeben.
Lösung:
- Um den Status-Code mit dem Standard-Antwortschemata zu erfassen, ordnen Sie das Feld statusCode zu, das sich unter dem Knoten responseItem/error der Antwort befindet und den HTTP-Status-Code enthält (z. B. 200, 403). Details zur Struktur des Antwortschematas finden Sie in der Aktivitätskonfigurationsdokumentation für jede HTTP v2-Aktivität.
- Um den Status-Code bei Verwendung eines benutzerdefinierten Antwortschematas zu erfassen, aktivieren Sie Zusätzliche Eigenschaften aus der HTTP-Antwort in das Schema einschließen in der Aktivitätskonfiguration. Dies umhüllt das Schema mit einer von Jitterbit definierten Struktur, die __jitterbit_api_statuscode__ (der Status-Code) und __jitterbit_api_errorbody__ (der Antwortkörper bei fehlgeschlagenen Anfragen) enthält.
- Damit der Status-Code verfügbar ist, wenn die API eine nicht erfolgreiche Antwort zurückgibt, aktivieren Sie Operationsfehler bei nicht erfolgreichem Status-Code ignorieren in den optionalen Einstellungen der Aktivität. Ohne diese Einstellung schlägt die Operation bei nicht erfolgreichen Antworten fehl, bevor die Antwortdaten zugeordnet werden können.

HTTP v2: XML-Namespaces werden bei Verwendung eines benutzerdefinierten Anforderungsschemas umgeschrieben

Symptom: Eine HTTP v2-Operation, die eine XML-Nutzlast an einen SOAP- oder XML-Webdienst sendet, schlägt mit einem Serverfehler (z. B. 500 Internal Server Error) fehl, obwohl die gleiche Nutzlast erfolgreich vom Postman oder SoapUI gesendet wird. Bei der Überprüfung des Anfragekörpers, den das Ziel empfängt, wird deutlich, dass XML-Namespace-Deklarationen auf das Wurzelelement konsolidiert wurden und die ursprünglichen Namespace-Präfixe durch generische ersetzt wurden (z. B. wird soapenv:Envelope zu Envelope xmlns="...", und Element-Präfixe werden als ns, ns1, ns2 umnummeriert).
Mögliche Ursache: Wenn in der HTTP v2-Aktivitätskonfiguration ein benutzerdefiniertes Anforderungsschema verwendet wird, normalisiert die Transformation standardmäßig die XML-Datei, indem alle Namespace-Deklarationen auf den Wurzelknoten verschoben und ihre Präfixe neu zugewiesen werden. SOAP-Dienste und andere XML-Endpunkte, die die Konsistenz von Namespace-Präfixen validieren, lehnen die geänderte Nutzlast ab.
Lösung:
- Bei Agent-Version 12.8 oder später legen Sie jitterbit.target.xml.preserve.namespace.prefix in einem Skriptschritt vor der Transformation auf true fest, um die Namespace-Präfixe des Quell-XML beizubehalten, anstatt generische zuzuweisen:
```
$jitterbit.target.xml.preserve.namespace.prefix = true;
```
- Wenn Ihre privaten Agents älter als 12.8 sind, oder wenn das Ziel auch die Konsolidierung von Namespace-Deklarationen auf dem Wurzelelement ablehnt, verwenden Sie das Standard-Anforderungsschema anstelle eines benutzerdefinierten und ordnen Sie die komplette XML-Nutzlast als Zeichenfolge dem Feld body des Schemas zu. Die Nutzlast wird dann als Zeichenfolge behandelt und nicht als XML analysiert, sodass ihre Namespace-Deklarationen beibehalten bleiben. Das Antwortschemata kann weiterhin ein benutzerdefiniertes Schema sein.

HTTP v2: Doppelter Authorization-Header verursacht 400 Bad Request

Symptom: HTTP v2-Connector-Operationen schlagen mit einem 400-Fehler fehl, wenn sowohl die Authentifizierung auf Verbindungsebene als auch ein manuell definierter Authorization-Request-Header auf derselben Verbindung oder Aktivität konfiguriert sind.
Mögliche Ursache: Wenn die Authentifizierung bei einer HTTP v2-Verbindung konfiguriert ist (z. B. Basic oder OAuth), fügt der Connector automatisch einen Authorization-Header zu jeder Anfrage hinzu. Das Hinzufügen eines zweiten Authorization-Headers manuell führt zu zwei widersprechenden Headern, die die meisten Server mit einem 400-Fehler ablehnen.
Lösung:
- Entfernen Sie alle manuell hinzugefügten Authorization-Header aus den Request-Headern in der Aktivitäts- oder Verbindungskonfiguration.
- Verwenden Sie nur die integrierten Authentifizierungseinstellungen in der Verbindung zur Handhabung der Authentifizierung. Fügen Sie neben der konfigurierten Authentifizierung keinen manuellen Authorization-Header hinzu.
- Wenn Sie den Authorization-Header auf der Aktivitätsebene dynamisch setzen müssen, legen Sie den Authentifizierungstyp der Verbindung auf No Auth fest und konfigurieren Sie den Authorization-Request-Header der Aktivität wie erforderlich.

HTTP v2: JSON-Wert in einer Request-Header-Projektvariablen schlägt beim Parsing fehl

Symptom: Eine HTTP v2-Aktivität, die einen Request-Header-Wert aus einer Projektvariablen mit einem JSON-String liest, schlägt mit einem Parse-Fehler fehl:
```
Expected a ',' or ']' at 139 [character 140 line 1]
```
Derselbe JSON funktioniert, wenn er direkt in die Spalte Value der Tabelle Request Headers eingefügt wird.
Mögliche Ursache: Wenn ein Request-Header-Wert aus einer Projektvariablen gelesen wird, maskiert der HTTP v2-Connector die eingebetteten Anführungszeichen nicht so, wie es der Fall ist, wenn Sie den Wert direkt in die Tabelle Request Headers eingeben. Die unmaskierten Anführungszeichen unterbrechen die Header-Zeichenfolge, bevor sie das Ziel erreicht.
Lösung:
- Wenn Sie JSON in einer Projektvariablen speichern, das als Header-Wert verwendet wird, maskieren Sie jedes doppelte Anführungszeichen mit einem Backslash. Speichern Sie den Wert beispielsweise als {\"success\": \"true\"} statt {"success": "true"}.
- Falls der JSON-Inhalt statisch ist, fügen Sie ihn direkt in die Spalte Value der Tabelle Request Headers ein, statt eine Variable zu verwenden. Der Connector wendet die erforderliche Maskierung in diesem Fall automatisch an.

HTTP und HTTP v2: URL enthält mehrere `?`-Zeichen

Symptom: Ein HTTP- oder HTTP v2-Vorgang schlägt im Zielsystem fehl. Die Agent-Logs zeigen, dass die Anfrage-URL mehr als ein ? zwischen Segmenten enthält, beispielsweise https://api.example.com/endpoint?param1=A?param2=B.
Mögliche Ursache: Abfrageparameter wurden an zwei Stellen deklariert: direkt an den URL-Pfad angehängt und auch zur Tabelle Request Parameters der Aktivität hinzugefügt. Der Connector verkettet beide Sätze und fügt statt eines & ein zweites ? ein.
Lösung:
- Entfernen Sie jeden Abfrage-String-Segment aus dem URL-Pfad. Die Basis-URL sollte nur den Pfad selbst enthalten (beispielsweise https://api.example.com/endpoint).
- Definieren Sie jeden Abfrageparameter in der Tabelle Request Parameters der Aktivität. Der Connector fügt die Zeichen ? und & automatisch beim Konstruieren der endgültigen URL ein.

HTTP v2: Doppelte URL-Codierung, wenn „Encode request URL" aktiviert ist

Symptom: REST-API-Aufrufe über den HTTP v2-Connector schlagen im Zielsystem fehl, da URL-Parameter in der ausgehenden Anfrage doppelt codiert sind (beispielsweise wird ein %20-Leerzeichen zu %2520).
Mögliche Ursache: Wenn Encode request URL in den HTTP v2-Verbindungseinstellungen aktiviert ist, codiert der Connector die gesamte URL vor dem Senden. Falls URL-Parameter bereits Prozentzeichen-codierte Zeichen enthalten, werden diese Zeichen ein zweites Mal codiert.
Lösung:
- Deaktivieren Sie Encode request URL in den HTTP v2-Verbindungseinstellungen, wenn die URL oder Parameter bereits codiert sind oder mithilfe der Funktion URLEncode konstruiert werden.
- Falls Encode request URL aktiviert bleiben muss, stellen Sie sicher, dass Parameter, die in die URL übergeben werden, nicht vorcodiert sind, bevor sie die Verbindung erreichen.

HTTP v2: Operation schlägt fehl, wenn die Basis-URL umgeleitet wird

Symptom: Ein HTTP v2-Vorgang schlägt sofort fehl, wenn die konfigurierte Base URL eine Umleitungsantwort (3xx) zurückgibt.
Mögliche Ursache: Follow redirects ist in den HTTP v2-Verbindungseinstellungen deaktiviert, daher werden Umleitungsantworten als Fehler behandelt, anstatt automatisch befolgt zu werden.
Lösung: Aktivieren Sie in den HTTP v2-Verbindungseinstellungen Follow redirects, um dem Connector zu ermöglichen, Umleitungsantworten automatisch zur endgültigen Ziel-URL zu befolgen.

HTTP v2: Variablen im Aktivitätspfad werden nicht aufgelöst

Symptom: Eine HTTP v2-Aktivität verwendet eine globale, Projekt- oder Jitterbit-Variable im Feld Path, doch zur Laufzeit wird die Variable buchstäblich (unaufgelöst) gesendet, anstatt durch ihren Wert ersetzt zu werden.
Mögliche Ursache: Eine vollständige URL (eine, die Protokoll und Host enthält, wie https://api.example.com/...) wurde im Feld Path eingegeben. Variablen werden in vollständigen URLs nicht unterstützt. Sie werden nur in einem Teilpfad aufgelöst, der an die Base URL der Verbindung angehängt wird.
Lösung:
1. Legen Sie in der HTTP v2-Verbindung die Base URL auf den Protokoll- und Hostteil des Endpunkts fest (beispielsweise https://api.example.com).
2. Geben Sie im Feld Path der Aktivität nur den Teilpfad ein, der der Basis-URL folgt, und platzieren Sie die Variable innerhalb dieses Teilpfads (beispielsweise /records/[recordId]). Der Connector löst die Variable auf und hängt das Ergebnis zur Laufzeit an die Base URL an.

HTTP: Sendet `null` als die Zeichenkette `"null"`

Symptom: Eine HTTP-POST- oder PUT-Aktivität sendet Felder, die mit der Funktion Null zugeordnet sind, als die Zeichenkette "null" (oder lässt sie weg), anstatt ein JSON-null-Literal auszugeben. Dies tritt auf, wenn das Anforderungsschema in der Aktivität definiert ist.
Mögliche Ursache: Wenn das Anforderungsschema in der HTTP-Aktivität definiert ist, serialisiert der Connector ein zugeordnetes Null nicht als JSON-null. Wenn das Schema stattdessen in der Transformation definiert ist und in der Aktivität kein Anforderungsschema vorhanden ist, sendet der Connector ein zugeordnetes Null korrekt als JSON-null.
Lösung:
- Migrieren Sie die Aktivität zum HTTP v2-Connector, der Null korrekt serialisiert. Jitterbit empfiehlt, vorhandene HTTP-Verbindungen und -Aktivitäten zu HTTP v2 zu konvertieren.
- Falls die Aktivität auf HTTP verbleiben muss, definieren Sie das Anforderungsschema in der Transformation anstelle der Aktivität, und lassen Sie das Anforderungsschema der Aktivität ungesetzt. Mit dem in der Transformation definierten Schema serialisiert der Connector ein zugeordnetes Null korrekt zu einem JSON-null.

LDAP Delete Entry schlägt fehl, wenn der Zieleingang untergeordnete Einträge hat

Symptom: Eine LDAP-Aktivität Eintrag löschen schlägt mit einem Fehler vom LDAP-Server fehl (beispielsweise notAllowedOnNonLeaf oder eine Meldung, die angibt, dass der Eintrag kein Blattknoten ist).
Mögliche Ursache: Das LDAP-Protokoll erlaubt nicht das Löschen eines Eintrags, der untergeordnete Einträge hat (Untergeordnete). Der Eintrag muss ein Blattknoten ohne Kinder sein, damit das Löschen erfolgreich ist.
Lösung:
- Löschen Sie vor dem Löschen des übergeordneten Eintrags zunächst alle untergeordneten Einträge. Durchlaufen Sie die Hierarchie von den tiefsten Einträgen aufwärts.
- Wenn das Löschen eines gesamten Teilbaums erforderlich ist, implementieren Sie ein Skript, das Einträge von unten des Baums aufwärts identifiziert und löscht, indem Sie RunOperation mit der LDAP-Aktivität Eintrag löschen für jeden Eintrag verwenden.

LDAP Search Entry: Filterausdruck ist auf einigen Servern Groß-/Kleinschreibung beachtet

Symptom: Eine LDAP-Aktivität Eintrag suchen gibt keine Ergebnisse oder einen Fehler zurück, obwohl die abgefragten Einträge im Verzeichnis vorhanden sind.
Mögliche Ursache: Einige LDAP-Server erfordern, dass Attributnamen in Filterausdrücken exakt der Groß-/Kleinschreibung entsprechen, die das Schema des Servers verwendet. Der von Studio vorausgefüllte Filterausdruck verwendet Titelschreibweise für die strukturelle Klasse (beispielsweise ObjectClass), aber einige Server erfordern eine andere Groß-/Kleinschreibung (beispielsweise objectClass).
Lösung:
1. Überprüfen Sie in der LDAP-Aktivitätskonfiguration Sucheintrag das vorausgefüllte Feld Filterausdruck.
2. Passen Sie die Groß-/Kleinschreibung von Attributnamen an das an, was der LDAP-Zielserver erwartet. Ändern Sie beispielsweise ObjectClass zu objectClass, wenn der Server Kleinbuchstaben erfordert.
3. Konsultieren Sie die Dokumentation oder Schemadefinition Ihres LDAP-Servers für die erforderlichen Namenskonventionen für Attribute.

Microsoft SharePoint Online: SOAP-Schema-Verbindungen schlagen nach IDCRL-Einstellung fehl

Symptom: Vorgänge mit einem Microsoft SharePoint Server-Connector mit dem Verbindungstyp SOAP-Schema schlagen fehl oder geben Authentifizierungsfehler zurück, wenn eine Verbindung zu SharePoint Online hergestellt wird.
Mögliche Ursache: Microsoft hat die IDCRL-Methode (Identity Client Runtime Library) eingestellt, die von SOAP-Schema-Verbindungen zu SharePoint Online verwendet wurde. Nach dem 1. Mai 2026 wird erwartet, dass Vorgänge mit dem SharePoint-SOAP-Schema für SharePoint Online-Verbindungen fehlschlagen.
Lösung:
1. Öffne in Studio jede betroffene SharePoint-Verbindung und ändere die Schema-Einstellung von SOAP zu REST.
2. Konfiguriere alle Aktivitäten, die das SOAP-Schema verwendet haben, neu, um entsprechende REST-Vorgänge zu verwenden.
3. Teste und stellen die betroffenen Vorgänge erneut bereit.
4. Weitere Informationen zur Migration findest du in der Dokumentation des Microsoft SharePoint Server-Connectors.

Microsoft Dynamics 365 Business Central v2: Typnamen nicht kompatibel mit Metadaten

Symptom: Vorgänge mit dem Microsoft Dynamics 365 Business Central v2-Connector schlagen mit Fehlern fehl, die darauf hindeuten, dass Typnamen in der Payload nicht mit den OData-Metadaten kompatibel sind.
Mögliche Ursache: Bestimmte Dynamics 365 Business Central OData API-Endpunkte erfordern OData-Typ-Anmerkungen in der Request-Payload. Der Connector enthält diese Anmerkungen standardmäßig nicht, was zu Typ-Inkompatibilitätsfehlern für diese Endpunkte führt.
Lösung:
1. Öffne die Microsoft Dynamics 365 Business Central v2 Update-Aktivitätskonfiguration.
2. Aktiviere in Optionale Einstellungen die Option OData-Typ in Payload setzen.
3. Speichere die Aktivität und teste die betroffenen Vorgänge erneut.

Microsoft Entra ID: Erweiterungsattribute nicht als Abfragefilterbedingungen auswählbar

Symptom: Beim Konfigurieren einer Microsoft Entra ID Query-Aktivität erscheinen das Feld onPremisesExtensionAttributes und seine untergeordneten Erweiterungsattributfelder (z. B. extensionAttribute1 bis extensionAttribute15) nicht in der Auswahl Objektfelder in Schritt 3 und können nicht als Filterbedingungen in bedingten Klauseln ausgewählt werden.
Mögliche Ursache: onPremisesExtensionAttributes ist ein komplexer Typ (verschachteltes Objekt). Die Auswahl Objektfelder in Schritt 3 zeigt nur primitive Datentypen; komplexe Typen sind von der Auswahliste ausgeschlossen.
Lösung: Die Felder onPremisesExtensionAttributes müssen nicht in Schritt 3 ausgewählt werden, um zurückgegeben zu werden. Sie erscheinen im Ausgabeschema der Aktivität in Schritt 4 und werden zur Laufzeit ausgefüllt, wenn der Vorgang ausgeführt wird. Um auf Erweiterungsattributwerte zuzugreifen, verbinde mit onPremisesExtensionAttributes und seinen untergeordneten Feldern in der Transformation.

Microsoft Entra ID Update-Aktivität: DateTime-Felder mit `Edm.String`-Typkonflikt abgelehnt

Symptom: Eine Microsoft Entra ID Update-Aktivität schlägt mit folgendem Fehler fehl:

Ein Wert wurde erkannt, dessen Typname nicht mit den Metadaten kompatibel ist.
Der Wert hat den Typ 'Edm.String' angegeben, aber der in den Metadaten angegebene Typ ist 'Edm.DateTimeOffset'.
[HTTP/1.1 400 Bad Request]

Mögliche Ursache: Der Connector sendet DateTime-Feldwerte (z. B. employeeHireDate) ohne die für die Microsoft Graph API erforderliche @odata.type-Anmerkung. Ohne die Anmerkung wird der Wert als Edm.String statt als Edm.DateTimeOffset interpretiert, was zu einem 400-Fehler führt.
Lösung:
1. Öffnen Sie die Konfiguration der Microsoft Entra ID Update-Aktivität.
2. Erweitern Sie in Schritt 1 Optionale Einstellungen und aktivieren Sie OData-Typ für Payload festlegen.
3. Speichern Sie die Aktivität, stellen Sie sie erneut bereit und führen Sie den Vorgang aus.

Microsoft Entra ID-Abfrage: „Nicht unterstützte oder ungültige Abfragefilterbedingung" bei gefilterten Eigenschaften

Symptom: Eine Microsoft Entra ID Query-Aktivität schlägt fehl, wenn in Schritt 3 eine Filterbedingung angewendet wird:
```
(Request_UnsupportedQuery) Unsupported or invalid query filter clause specified for property '<property>' of resource '<object>'. [HTTP/1.1 400 Bad Request]
```
Die gleiche Abfrage erfolgt erfolgreich, wenn kein Filter angewendet wird.
Mögliche Ursache: Das Filtern nach bestimmten Microsoft Entra ID-Eigenschaften (z. B. companyName und createdDateTime) nutzt die erweiterte Abfragefunktion der Microsoft Graph API, die $count=true in der Abfragezeichenfolge erfordert. Ohne diese lehnt die API den Filter ab, auch wenn die Syntax sonst korrekt ist. Der Connector fügt automatisch den erforderlichen ConsistencyLevel: eventual-Header hinzu, aber $count=true muss separat hinzugefügt werden.
Lösung: Wählen Sie eine der folgenden Optionen je nach der in Schritt 3 verwendeten Registerkarte:
- Registerkarte „Basis": Aktivieren Sie das Kontrollkästchen Anzahl einbeziehen. Dies fügt $count=true automatisch zur Abfrage hinzu.
- Registerkarte „Erweitert": Fügen Sie &$count=true manuell an die Filterzeichenfolge an. Beispiel:
```
$filter=companyName eq 'Example Corp'&$count=true
```

Eine Liste der Eigenschaften, die erweiterte Abfragesyntax erfordern, finden Sie unter Advanced query capabilities on Microsoft Entra ID objects in der Microsoft Graph-Dokumentation.

Microsoft Dynamics AX 2012-Vorgänge schlagen mit „Anmeldung fehlgeschlagen" fehl

Symptom: Vorgänge mit dem Microsoft Dynamics AX-Connector für AX 2012 schlagen zur Laufzeit fehl, obwohl der Verbindungstest in Studio erfolgreich ist. Das Protokoll des Jitterbit Dynamics AX 2012 Connector REST Service enthält:
```
The server has rejected the client credentials.
```
```
The logon attempt failed
```
Ursache: Das Feld Domain Name in der AX 2012-Verbindung ist nicht auf den korrekten Wert gesetzt. Die AX 2012-Authentifizierung erfordert, dass Domain Name die DNS-Domain-Namenserweiterung ist (z. B. yourcompany.com), nicht ein kurzer oder NetBIOS-Domain-Name. Ein falscher Domain-Wert führt dazu, dass AX ansonsten gültige Anmeldeinformationen mit einem Anmeldefehler ablehnt, auch wenn der Verbindungstest erfolgreich ist.
Lösung:
1. Öffnen Sie die Dynamics AX 2012-Verbindung in Studio.
2. Legen Sie das Feld Domain Name auf Ihre DNS-Domain-Namenserweiterung (z. B. yourcompany.com) fest, nicht auf einen kurzen/NetBIOS-Domain-Namen.
3. Bestätigen Sie, dass der Login der AX-Dienstkontobenutzername mit den erforderlichen Berechtigungen ist, und geben Sie das Passwort erneut ein, um einen veralteten Wert auszuschließen.
4. Testen Sie die Verbindung und führen Sie dann den Vorgang erneut aus.

NetSuite: Datencenter-URL-Fehler

Symptom: Eine NetSuite-Verbindung, die zuvor erfolgreich getestet wurde, schlägt jetzt mit diesem Fehler fehl:

Connector Error: Error getting the data center URL.

Caused by: org.jitterbit.integration.server.engine.connector.exception.NetSuiteWebServiceRuntimeException: FaultString:

In this account, you must use account-specific domains with this SOAP web services endpoint. You can use the SOAP getDataCenterUrls operation to obtain the correct domain. Or, go to Setup > Company > Company Information in the NetSuite UI. Your domains are listed on the Company URLs tab.

Unter bestimmten Umständen kann stattdessen dieser Fehler auftreten:

You are not requesting the correct data center for your company.
Ursache: Aufgrund von Änderungen durch NetSuite werden einige zuvor zulässige WSDL-URL-Formate nicht mehr akzeptiert, darunter generische und rechenzentrumsspezifische WSDL-URLs. Zum Beispiel:
- Generische WSDL-URL: https://webservices.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
- Rechenzentrumsspezifische WSDL-URL: https://webservices.na3.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
Workaround: Ändern Sie die WSDL-URL, um eine kontospezifische Domäne zu verwenden:
- Kontospezifische WSDL-URL: https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
Anweisungen zum Suchen der kontospezifischen NetSuite-Domäne und zu deren Verwendung in der WSDL-URL finden Sie unter Verwenden einer kontospezifischen NetSuite-WSDL-URL.

NetSuite: `INSUFFICIENT_PERMISSION` trotz erfolgreichem Verbindungstest

Symptom: Auch wenn das Testen einer NetSuite-Verbindung erfolgreich ist, erhalten Sie beim Ausführen von Vorgängen mit Aktivitäten, die diese Verbindung verwenden, möglicherweise einen INSUFFICIENT_PERMISSION-Fehler.
Workaround: Verwenden Sie beim Generieren von Zugriffstoken entweder die Rolle Full Access oder Administrator, oder stellen Sie sicher, dass die entsprechenden Berechtigungen für die verwendete Rolle zulässig sind. Detaillierte Anweisungen finden Sie in der NetSuite-Dokumentation Erste Schritte mit der tokenbasierten Authentifizierung.

NetSuite: Sandbox-Verbindung schlägt nach Sandbox-Aktualisierung fehl

Symptom: Eine NetSuite-Verbindung, die für ein NetSuite-Sandbox-Konto konfiguriert ist, schlägt nach der Aktualisierung der Sandbox-Umgebung mit einem Authentifizierungsfehler fehl.
Ursache: Bei jeder Aktualisierung einer NetSuite-Sandbox werden alle mit dieser Sandbox verknüpften TBA-Tokens (Token-basierte Authentifizierung) ungültig. Die Verbindung verwendet weiterhin die alten Tokens, die von NetSuite nicht mehr akzeptiert werden.
Lösung: Generieren Sie nach jeder Sandbox-Aktualisierung neue TBA-Tokens für das Sandbox-Konto, und aktualisieren Sie die Felder Token Key und Token Secret in der NetSuite-Verbindung. Anweisungen zum Abrufen neuer Token-Werte finden Sie unter Werte für die Verwendung von NetSuite TBA sammeln.

NetSuite: Benutzerdefinierte Felder werden nicht im Activity-Schema angezeigt

Symptom: Benutzerdefinierte Felder für ein NetSuite-Objekt sind auf einem privaten Agenten nicht im Transformationsschema vorhanden, obwohl diese Felder in NetSuite existieren.
Ursache: Der NetSuite-Connector stellt standardmäßig benutzerdefinierte Felder für viele Objekte bereit, aber einige Objekte erfordern eine explizite Konfiguration in der NetSuite-Connector-Konfigurationsdatei des Agenten.
Lösung: Fügen Sie das Objekt zur Konfigurationsdatei netsuiteconfig.xml auf dem privaten Agenten hinzu. Vollständige Anweisungen, einschließlich der Behandlung von Objekten mit mehr als 1.000 benutzerdefinierten Feldern, finden Sie unter Benutzerdefinierte Felder im NetSuite-Connector verfügbar machen.

NetSuite: Benutzerdefinierte Segmente werden nicht angezeigt oder nicht in erweiterten Suchen unterstützt

Symptom: Benutzerdefinierte Segmente sind im Aktivitätsschema nicht sichtbar, oder benutzerdefinierte Segmente des Typs List/Record sind in einer erweiterten Suche nicht verfügbar.
Ursache: Benutzerdefinierte Segmente erfordern bestimmte Berechtigungen für das NetSuite-Benutzerkonto. Außerdem wird der Segmenttyp List/Record in erweiterten Suchen nicht unterstützt, nur der Typ Multiple Select wird unterstützt.
Lösung: Berechtigungsanforderungen und bekannte Einschränkungen finden Sie unter Benutzerdefinierte Segmente auf der Seite der NetSuite Such-Aktivität.

NetSuite: Benutzerdefinierte Body-Felder sind aufgrund fehlender Rollenberechtigung nicht sichtbar

Symptom: Benutzerdefinierte Textkörperfelder von Transaktionen (zum Beispiel Felder, die einer Sales Order oder einem anderen Transaktionsdatensatz hinzugefügt wurden) erscheinen nicht im Ausgabeschema der NetSuite-Suchaktivität, obwohl die Felder in der NetSuite-Instanz existieren und der Verbindungstest erfolgreich ist.
Mögliche Ursache: Die für die Integration verwendete NetSuite-Rolle verfügt nicht über die Berechtigung View für Custom Body Fields. Der NetSuite-Connector ruft die SOAP-Aktion getList auf, um Definitionen benutzerdefinierter Felder abzurufen. Eine Berechtigungsverletzung bei diesem Aufruf führt dazu, dass die Felder vollständig aus dem Schema ausgelassen werden.
Lösung:
1. Öffnen Sie in Ihrem NetSuite-Konto die Rolle, die dem Integrationsbenutzer zugewiesen ist, und gewähren Sie mindestens View-Zugriff auf die Berechtigung Custom Body Fields.
2. Speichern Sie die Rolle, und warten Sie einige Minuten, bis die Berechtigungsänderung wirksam wird.
3. Erstellen Sie in Studio eine neue NetSuite Such-Aktivität, oder importieren Sie das Projekt in eine neue Projektumgebung, um das zwischengespeicherte Schema zu löschen. Die benutzerdefinierten Textkörperfelder sollten jetzt im Ausgabeschema angezeigt werden.

Symptom: Bei der Konfiguration einer NetSuite-Suchaktivität mit dem Suchtyp Gespeicherte Suche erscheint das Dropdown-Menü Gespeicherte Suche auswählen leer oder listet nicht alle erwarteten gespeicherten Suchen auf.
Ursache: Die NetSuite-API begrenzt Antworten auf 1.000 Datensätze pro Anfrage. Wenn ein Objekt mehr als 1.000 gespeicherte Suchen hat, kann das Dropdown-Menü nicht alle davon auflisten und erscheint möglicherweise leer.
Lösung: Verwenden Sie die Option Gespeicherte Suchskript-ID bereitstellen, um das Dropdown-Menü zu umgehen:
1. Wählen Sie im Abschnitt Gespeicherte Suche auswählen der Aktivitätskonfiguration die Option Gespeicherte Suchskript-ID bereitstellen aus.
2. Geben Sie die Skript-ID der gewünschten gespeicherten Suche direkt ein. Die Skript-ID finden Sie in der NetSuite-Benutzeroberfläche auf der Detailseite der gespeicherten Suche.

NetSuite: Schaltfläche „Erweiterte Suche – Testabfrage" ist deaktiviert

Symptom: Bei der Konfiguration einer erweiterten Suche in der NetSuite-Suchaktivität ist die Schaltfläche Abfrage testen ausgegraut und kann nicht angeklickt werden.
Ursache: Eine erweiterte Suche erfordert eine Abfragebedingung für ein verwandtes Objekt. Die Schaltfläche Abfrage testen ist deaktiviert, solange keine Bedingung für ein verwandtes Objekt hinzugefügt wurde.
Lösung: Fügen Sie mindestens eine Bedingung hinzu, die nach einem verwandten Objekt filtert. Wenn die Suche nur nach den eigenen Feldern des aktuellen Objekts filtern muss, verwenden Sie eine einfache Suche anstelle einer erweiterten Suche.

NetSuite: Formelfelder gespeicherter Suchen fehlen in der Activity-Ausgabe

Symptom: Eine NetSuite-Suchaktivität, die eine gespeicherte Suche verwendet, gibt bei Abfrage testen die erwartete Datensatzanzahl zurück, aber formelbasierte Spalten oder Spalten mit komplexen Joins (zum Beispiel customSearchJoin-Felder) fehlen in der Aktivitätsausgabe und im Transformationsmapping, obwohl diese Spalten in der gespeicherten Suche in der NetSuite-Benutzeroberfläche angezeigt werden.
Ursache: Formelbasierte Spalten einer gespeicherten Suche werden auf der Ebene der NetSuite-Benutzeroberfläche berechnet und sind nicht in der SOAP-Antwort enthalten, die der Connector liest. Infolgedessen erscheinen diese Werte nicht in der Aktivitätsausgabe, selbst wenn die Suche Datensätze zurückgibt.
Lösung:
1. Erstellen Sie die gespeicherte Suche, wenn möglich, mit gespeicherten (nicht formelbasierten) Feldern neu, da formelberechnete Werte möglicherweise nicht über die API zurückgegeben werden.
2. Öffnen Sie in Studio die NetSuite-Suchaktivität, und wählen Sie auf der ersten Konfigurationsseite die Option Gespeicherte Suche (verwendet eine zuvor in NetSuite gespeicherte, wiederverwendbare Suchdefinition) aus.
3. Wählen Sie die gespeicherte Suche aus dem Dropdown-Menü Gespeicherte Suche auswählen aus.
4. Durchlaufen Sie die verbleibenden Seiten, und führen Sie den Vorgang aus, um die vollständigen Daten abzurufen.

NetSuite: Testabfrage-Analysefehler, wenn der Filter eine Projektvariable verwendet

Symptom: Wenn ein Filter der NetSuite-Suchaktivität eine Projektvariable für einen Datums- oder Datetime-Wert verwendet (wie lastModifiedDate), gibt das Klicken auf Abfrage testen in der Aktivitätskonfiguration einen 500-Fehler zurück, der auf ein ungültiges Datumsformat verweist. Derselbe Vorgang wird zur Laufzeit erfolgreich ausgeführt.
```
Connector Error: FaultString: java.text.ParseException: Invalid dateTime format: [lastModifiedDate]
```
Ursache: Abfrage testen löst Projektvariablen nicht auf. Es sendet den wörtlichen Variablenverweis (zum Beispiel [lastModifiedDate]) als Filterwert, den NetSuite als ungültiges Datum ablehnt. Zur Laufzeit ersetzt der Agent den tatsächlichen Wert der Variable, sodass der Vorgang selbst erfolgreich ist.
Lösung: Um die Aktivität zu testen oder Änderungen daran zu speichern, ohne die Variable zu entfernen, fügen Sie dem Variablenverweis in der Filterbedingung einen temporären Standardwert hinzu:
1. Ändern Sie im Filter den Variablenverweis von [my_date_variable] zu [my_date_variable{2023-01-01T00:00:00.000Z}] (unter Verwendung der passenden ISO-8601-Datumszeit als Standardwert).
2. Klicken Sie auf Abfrage testen. Der Test ist jetzt erfolgreich, da anstelle der nicht aufgelösten Variable ein gültiges Datum eingesetzt wird.
3. Speichern Sie alle weiteren Änderungen an der Aktivität. Der Standardwert kann bestehen bleiben; zur Laufzeit verwendet der Agent immer den aktuellen Wert der Projektvariable.

NetSuite: Gespeicherte Suche mit Ergebniswerten als Ausgabe erfordert Agent 11.49 oder höher

Symptom: In der NetSuite-Suchaktivität ist die Option Gespeicherte Suche mit Ergebnisfeldern als Ausgabe in der Aktivitätsoberfläche sichtbar, aber Vorgänge, die sie verwenden, schlagen mit einem 500-Fehler fehl, wenn sie auf einem älteren privaten Agenten ausgeführt werden.
Ursache: Die Funktion Gespeicherte Suche mit Ergebnisfeldern als Ausgabe wurde in Agent-Version 11.49 eingeführt. Private Agenten mit früheren Versionen zeigen die Option in der Benutzeroberfläche an, verfügen jedoch nicht über die Laufzeitunterstützung, um sie auszuführen.
Lösung:
1. Bestätigen Sie die Agent-Version auf der Management Console-Seite Agents.
2. Aktualisieren Sie private Agenten auf Version 11.49 oder höher, um diese Option zu verwenden. Cloud-Agenten werden automatisch aktuell gehalten.
3. Wenn eine Aktualisierung des privaten Agenten nicht möglich ist, konfigurieren Sie die Aktivität stattdessen für die Verwendung von Gespeicherte Suche. Dieser Modus wird von früheren Agent-Versionen unterstützt.

NetSuite: Update-Activity gibt `INVALID_KEY_OR_REF` zurück, wenn die Quell-XML `internalId` verliert

Symptom: Eine NetSuite Update-Aktivität wird ohne Ausnahmefehler abgeschlossen, aber es wird kein Datensatz in NetSuite aktualisiert. Die Antwort-Payload enthält den SOAP-Status INVALID_KEY_OR_REF. Das Problem tritt häufig auf, wenn ein Transformationsskript GetXMLString verwendet, um die Update-Payload aus einer vorherigen Suchantwort zu erstellen.

<writeResponse>
  <platformCore:status isSuccess="false">
    <platformCore:statusDetail type="ERROR">
      <platformCore:code>INVALID_KEY_OR_REF</platformCore:code>
      <platformCore:message>The specified key is invalid.</platformCore:message>
    </platformCore:statusDetail>
  </platformCore:status>
  <baseRef>
    <platformCore:RecordRef type="invoice"></platformCore:RecordRef>
  </baseRef>
</writeResponse>

Ursache: GetXMLString serialisiert einen XML-Knoten, behält aber keine Attribute des Root-Elements bei. Wenn die internalId des Quelldatensatzes als Attribut des NetSuite-Root-Datensatzknotens gespeichert ist (zum Beispiel im Invoice-Element), wird sie aus der resultierenden Zeichenkette entfernt, und die Update-Aktivität erhält eine leere Datensatzreferenz.
Lösung: Erfassen Sie die internalId des Quelldatensatzes separat, und fügen Sie sie dann vor der Übergabe der Payload an die Update-Aktivität wieder in das serialisierte XML ein:
1. Weisen Sie im Transformationsskript die Quell-internalId einer Variable zu.
2. Rufen Sie GetXMLString auf, um das Datensatz-XML zu erstellen.
3. Verwenden Sie Replace, um internalId="..." in das Root-Element einzufügen. Für einen Invoice-Datensatz:
```
<trans>
$invoiceInternalId = searchResponse$searchResult$recordList$record.Invoice$internalId;
$MyRecord = GetXMLString([searchResponse$searchResult$recordList$record.]);
$MyRecord = Replace($MyRecord, "<Invoice>", '<Invoice internalId="' + $invoiceInternalId + '">');
</trans>
```
4. Übergeben Sie MyRecord an den nächsten Schritt.

NetSuite: Vorgänge schlagen aufgrund von API-Datensatzlimits fehl

Symptom: Ein Vorgang, der den NetSuite-Connector verwendet, schlägt fehl oder verarbeitet weniger Datensätze als erwartet, weil die Quelldaten das von der NetSuite-API pro Aufruf auferlegte Datensatzlimit überschreiten.
Ursache: Die NetSuite-API erzwingt Größenbeschränkungen für die Anzahl der Datensätze pro Anfrage. Wenn in einem einzelnen Aufruf mehr Datensätze gesendet werden, als das Limit erlaubt, lehnt NetSuite den Überschuss ab.
Lösung:
1. Aktivieren Sie Chunking für den Vorgang unter den Vorgangsoptionen. Wenn die Quelle eine NetSuite-Aktivität ist, teilt Chunking die Daten während der Transformation auf, statt beim Abrufen. Jeder Chunk wird in eine temporäre Datei geschrieben, und die Dateien werden nach der Verarbeitung aller Chunks zum endgültigen Ziel kombiniert.
2. Wenn das Ziel eine NetSuite-Aktivität ist, erzeugt jeder Quell-Chunk einen Ziel-Chunk, wobei die Transformation für jeden separat angewendet wird. Die resultierenden Ziel-Chunks werden anschließend kombiniert.
3. Anweisungen und bewährte Verfahren finden Sie unter Chunking aktivieren.
4. Weitere Details finden Sie unter Detaillierte Chunking-Informationen.

NetSuite: Grenzwert für gleichzeitige Anfragen überschritten

Symptom: Hochvolumige NetSuite-Vorgänge schlagen mit einem der folgenden Fehler fehl:
- RESTlet-Anfragen: HTTP error code: 400 Bad Request / SuiteScript error code: SSS_REQUEST_LIMIT_EXCEEDED
- Webdienstanfragen: ExceededConcurrentRequestLimitFault oder ExceededRequestLimitFault
Ursache: NetSuite erzwingt Concurrency Governance pro Konto und begrenzt damit die Gesamtzahl gleichzeitiger Webdienst- und RESTlet-Anfragen. Das Limit hängt von Ihrem Service Tier und der Anzahl der SuiteCloud Plus-Lizenzen ab. Zum Beispiel erlaubt Service Tier 1 mit fünf SuiteCloud Plus-Lizenzen 65 gleichzeitige Anfragen (15 + (5 × 10)). Wird dieses Limit überschritten, lehnt NetSuite die überschüssigen Anfragen ab.
Lösung:
1. Legen Sie für private Agenten MaxNumberOfOperationThreads im Abschnitt [OperationEngine] von jitterbit.conf auf einen Wert fest, der die Gesamtzahl der gleichzeitigen NetSuite-Anfragen innerhalb des Governance-Limits Ihres Kontos hält.
2. Gestalten Sie Vorgänge so, dass Anfragen wenn möglich seriell verarbeitet werden, oder implementieren Sie eine Wiederholungslogik, die wartet und erneut versucht, wenn die Antwort WS_CONCUR_SESSION_DISALLOWED empfangen wird.
3. Überprüfen Sie Ihre NetSuite-Clientanwendungen, um sicherzustellen, dass sie die Fehlercodes für Parallelität ordnungsgemäß verarbeiten.
4. Weitere Details zu den Governance-Limits nach Tier finden Sie in den Versionshinweisen zu NetSuite 2017.2 (Seiten 71–72).

NetSuite: Vorgänge schlagen nach Aktualisierung der WSDL-URL fehl

Symptom: Nach der Aktualisierung der WSDL-Download-URL in einer NetSuite-Verbindung auf eine neuere WSDL-Version schlagen alle Vorgänge fehl, die die Aktivitäten dieser Verbindung zur Laufzeit verwenden.
Ursache: Das Ändern der WSDL-Download-URL aktualisiert die Verbindung, aktualisiert jedoch nicht die Datenschemas, die von vorhandenen Transformationen verwendet werden. Die Transformationen verweisen weiterhin auf Schemafelder der vorherigen WSDL-Version, die mit der neuen Version nicht kompatibel sind.
Lösung: Um die WSDL-Version korrekt zu aktualisieren, folgen Sie den Schritten unter Ändern der WSDL-Version. Dieses Verfahren aktualisiert sowohl die Verbindungs-URL als auch die von allen betroffenen Aktivitäten verwendeten Datenschemas und verhindert so Laufzeitfehler durch Schema-Inkompatibilitäten.

NetSuite Create, Update oder Upsert schlägt mit „ist kein gültiger Wert für Land" fehl

Symptom: Eine NetSuite Create-, Update- oder Upsert-Aktivität schlägt fehl, wenn der Quellwert für ein Länderfeld keinem NetSuite-Country-Enum-Wert entspricht:
```
FaultString: org.xml.sax.SAXException: <country_value> is not a legal value for {urn:types.common_<version>.platform.webservices.netsuite.com}Country
```
Mögliche Ursache: Die NetSuite SuiteTalk API erfordert, dass Country (und andere aufgezählte Felder) einen der im WSDL vordefinierten Enum-Werte hat (z. B. _unitedStates). Ein Ländername, ein ISO-Ländercode oder ein beliebiger Wert, der nicht exakt mit dem WSDL-Enum übereinstimmt, wird abgelehnt.
Lösung:
- Übersetzen Sie in der Transformation, die zum NetSuite-Ziel zugeordnet wird, den Quellländerwert vor dem Schreiben in den entsprechenden NetSuite-Enum-Wert. Dafür eignen sich ein Querverweisverzeichnis, eine Case-Anweisung oder eine Nachschlagetabelle.
- Erstellen Sie den Querverweis aus dem Country-Enum, das im NetSuite SuiteTalk WSDL definiert ist, den Ihr Connector verwendet. Die gültigen Werte unterscheiden sich zwischen WSDL-Versionen. Prüfen Sie daher immer gegen die WSDL-Version, die derzeit auf der Verbindung konfiguriert ist.
- Wenden Sie denselben Ansatz auf alle anderen Felder an, die auf einem NetSuite-Enum basieren (z. B. State, Currency), wenn die Quellwerte nicht bereits mit dem WSDL-Enum übereinstimmen.

OData v2-Entitätsmengen können mit „Keine Entitätsmengen gefunden" nicht geladen werden

Symptom: Das Konfigurieren einer OData Query-Aktivität, die auf einen OData v2.0-Service verweist, gibt einen Fehler beim Abrufen der Objektliste zurück, obwohl der Verbindungstest erfolgreich ist:
```
An error occurred while fetching the data:
Error while generating for query activity object list. The Exception is No entity sets found for the address provided.
```
Mögliche Ursache: Die Unterstützung für OData V2-Services wurde in Agent-Version 11.59 dem OData-Connector durch die Verbindungseinstellung OData version hinzugefügt. Bei Agents vor Version 11.59 unterstützt der Connector nur OData V4, daher kann eine Verbindung, die auf einen OData V2-Service verweist, die Objektliste nicht ausfüllen. Der gleiche Fehler tritt auch bei Version 11.59 oder später auf, wenn OData version für einen OData V2-Service auf V4 belassen wird.
Lösung:
1. Aktualisieren Sie für private Agents auf Version 11.59 oder später. Cloud Agents erhalten das Update automatisch.
2. Legen Sie in der OData-Verbindung OData version auf V2 fest (Standard ist V4). Speichern Sie und testen Sie die Verbindung erneut.
3. Öffnen Sie die OData Query-Aktivität erneut. Die Entity Sets sollten nun geladen werden.

OData: Microsoft Dynamics 365 gibt nur die Daten des Standardunternehmens zurück

Symptom: Eine OData-Verbindung zu einem Microsoft Dynamics 365 Finance and Operations-Endpunkt gibt nur Daten des Standardunternehmens des Benutzers zurück, sodass Datensätze von anderen Unternehmen in den Ergebnissen fehlen.
Mögliche Ursache: Ein Dynamics 365 Finance and Operations OData-Endpunkt gibt standardmäßig nur die Daten des Standardunternehmens des Benutzers zurück. Um der Verbindung einen unternehmensübergreifenden (erweiterten) Bereich zu geben, muss eine unternehmensübergreifende Filterklausel an die OData-Metadaten-URL der Verbindung angehängt werden (die $metadata-URL). Auf der Metadaten-URL wird ?cross-company=true allein den erweiterten Bereich nicht anwenden.
Lösung: Hängen Sie in der OData-Verbindung eine dataAreaId-Filterklausel an die OData-Metadaten-URL an, ersetzen Sie usrt durch Ihre Datenbereiche-ID und speichern Sie dann die Änderungen und testen Sie erneut:

?$filter=dataAreaId eq 'usrt'&cross-company=true

Informationen zur Verwaltung von OData-Daten nach Unternehmen in Dynamics 365 finden Sie in der Microsoft-Dokumentation zum Cross-Company-Verhalten.

Oracle EBS: Verbindungsfehler „benutzerdefinierte Provider-JAR-Datei ist nicht vorhanden"

Symptom: Die Verbindung zu einer Oracle E-Business Suite (EBS)-Instanz schlägt fehl mit:

Error connecting to Oracle EBS instance. Error is: The custom provider JAR file is not present in the Jitterbit Private Agent or it is not in the right location ($JITTERBIT_HOME/Connectors/Providers)

Mögliche Ursache: Der Oracle EBS-Konnektor erfordert, dass der Oracle JDBC-Treiber (ojdbc8.jar) manuell auf dem privaten Agent platziert wird. Diese Datei wird nicht mit dem Agent gebündelt und muss vor der erfolgreichen Verbindung hinzugefügt werden.
Lösung:
1. Laden Sie ojdbc8.jar von der Oracle-Website herunter (ein Oracle-Konto ist erforderlich).
2. Platzieren Sie ojdbc8.jar im Verzeichnis $JITTERBIT_HOME/Connectors/Providers/ auf dem Host des privaten Agents.
3. Starten Sie alle Agents in der Agent-Gruppe neu.
4. Testen Sie die Oracle EBS-Verbindung erneut.

Salesforce: Operationen schlagen aufgrund von API-Datensatzlimits fehl

Symptom: Eine Salesforce-Standardaktivität (z. B. Upsert) schlägt fehl oder verarbeitet weniger Datensätze als erwartet, da die Quelldaten das Datensatzlimit pro Aufruf überschreiten. Die Operation kann mit folgendem Fehler fehlschlagen:
```
EXCEEDED_ID_LIMIT: record limit reached. cannot submit more than 200 records into this call
```
Ursache: Salesforce-Standardaktivitäten akzeptieren maximal 200 Datensätze pro Aufruf. Wenn mehr Datensätze in einem einzelnen Aufruf gesendet werden, lehnt Salesforce die überschüssigen ab. Dies kann auf zwei Arten geschehen: Chunking ist nicht aktiviert, oder Chunking ist aktiviert, aber die Quelle kann es nicht berücksichtigen. Chunking wird nur berücksichtigt, wenn die Quelle ein nativer Connector ist. Bei jeder anderen Quelle, z. B. HTTP v2, werden alle Datensätze in einem einzelnen Aufruf gesendet, unabhängig von der konfigurierten Chunk-Größe. Siehe Chunking erfordert einen nativen Connector als Quelle.
Lösung:
- Aktivieren Sie Chunking für die Operation und setzen Sie die Chunk-Größe auf 200 oder weniger. Anweisungen finden Sie unter Chunking aktivieren.
- Bestätigen Sie, dass die Chunk-Größe tatsächlich auf die Quelldaten angewendet wird. Wenn die Quelle eine große Nutzlast ist, die von einer anderen Aktivität erzeugt wird, überprüfen Sie, ob die Operation sie in Aufrufe von 200 Datensätzen oder weniger aufteilt. Wenn das Limit trotz einer korrekten Chunk-Größe immer noch überschritten wird, wenden Sie sich an den Jitterbit-Support.
- Erhöhen Sie für Salesforce-Massenaktivitäten die standardmäßige Chunk-Größe von 200 auf einen größeren Wert wie 10.000, da Massenaktivitäten für die Verarbeitung großer Datensatzmengen ausgelegt sind.

Chunking teilt die Daten während der Transformation auf, nicht beim Abrufen. Wenn die Quelle eine Salesforce-Aktivität ist, wird jeder Chunk in eine temporäre Datei geschrieben und die Dateien werden nach der Verarbeitung aller Chunks in das endgültige Ziel kombiniert. Wenn das Ziel eine Salesforce-Aktivität ist, erzeugt jeder Quell-Chunk einen Ziel-Chunk, wobei die Transformation separat auf jeden angewendet wird, und die resultierenden Ziel-Chunks werden dann kombiniert. Weitere Informationen finden Sie unter Detaillierte Chunking-Informationen.

Salesforce, Service Cloud und ServiceMax: Mehrstufige Authentifizierung verhindert Basiseauthentifizierungsverbindungen

Symptom: Eine Verbindung, die Basic Auth mit dem Connector Salesforce, Salesforce Service Cloud oder ServiceMax verwendet, schlägt beim Verbindungstest fehl oder verbindet sich, schlägt aber bei Operationen mit einem Authentifizierungsfehler fehl.
Ursache: Diese Connectoren nutzen dieselbe Codebasis und authentifizieren sich bei einer Salesforce-Organisation. Die Basic-Authentifizierung erfordert ein Salesforce-Konto, dessen zugewiesener Berechtigungssatz die Berechtigung Multi-Faktor-Authentifizierung für API-Logins nicht enthält. Wenn diese Berechtigung zugewiesen ist (MFA für das Konto aktiv), schlagen Basic-Auth-Verbindungen fehl.
Lösung:
- Überprüfen Sie in Salesforce den Berechtigungssatz, der dem Systemintegrations-Anmeldekonto zugewiesen ist, und bestätigen Sie, dass Multi-Faktor-Authentifizierung für API-Logins nicht ausgewählt ist. Systemintegrations-Anmeldetypen sind von der MFA-Anforderung von Salesforce ausgenommen. Weitere Informationen finden Sie in den Häufig gestellten Fragen zur Multi-Faktor-Authentifizierung von Salesforce.
- Wenn MFA nicht vom Integrationskonto entfernt werden kann, wechseln Sie die Verbindung zu 2-legged OAuth 2.0-Authentifizierung.

Hinweis

Die Verwendung von 2-legged OAuth 2.0 erfordert Agent-Version 11.59 oder später. Bei 12.x-Agenten ist Version 12.3 oder später für den Salesforce-Connector und 12.4 oder später für die Connectoren Salesforce Service Cloud und ServiceMax erforderlich.

Salesforce-Zertifikat: Fehltreffer bei Subject Alternative Name (SAN)

Symptom: Eine Salesforce-Verbindung zu einer Sandbox oder einer Organisation mit aktivierten Enhanced Domains schlägt fehl mit:
```
Certificate for <url> doesn't match any of the subject alternative names
```
Mögliche Ursachen:
- Das Zertifikat enthält die Salesforce MyDomain oder Sandbox-URL nicht in seinen Subject Alternative Names.
- Das Kontrollkästchen Sandbox in den Salesforce-Verbindungseinstellungen ist nicht korrekt aktiviert.
Lösung:
- Überprüfen Sie die SAN-Einträge des Zertifikats mit OpenSSL: openssl x509 -in cert.crt -text -noout. Bestätigen Sie, dass der Abschnitt Subject Alternative Name Ihre Salesforce MyDomain-URL enthält.
- Überprüfen Sie in den Salesforce-Verbindungseinstellungen in Studio, dass das Kontrollkästchen Sandbox für Ihre Zielorganisation korrekt eingestellt ist.
- Wenn die Salesforce-URL in den SANs fehlt, generieren Sie das Zertifikat neu, um die spezifische Domäne einzuschließen.
- Wenn dieselbe Verbindung in einer Cloud-Agent-Gruppe erfolgreich ist, aber in einem privaten Agent fehlschlägt, kann die Ursache stattdessen eine fehlende SNI-Erweiterung im TLS-Handshake des Agenten sein. Siehe Salesforce-Sandbox-Verbindung schlägt mit Zertifikatkonflikt fehl.

Salesforce-Verbindung, -Konfiguration oder -Operation schlägt intermittierend mit `SERVER_UNAVAILABLE` fehl

Symptom: Ein Salesforce-Verbindungstest, eine Aktivitätskonfiguration oder ein Vorgangsablauf schlägt intermittierend fehl mit:
```
SERVER_UNAVAILABLE: server temporarily unavailable
```
Dies kann beispielsweise beim Auswählen eines Objekts während der Aktivitätskonfiguration auftreten.
Mögliche Ursache: Salesforce gibt diesen Fehlercode zurück, wenn der eigene Server die Anfrage vorübergehend nicht verarbeiten kann. Der Connector meldet dies mit dieser generischen Meldung, anstatt spezifischere Texte von Salesforce weiterzuleiten.
Lösung: Wiederholen Sie den Verbindungstest, den Konfigurationsschritt oder den Vorgang, und warten Sie zwischen den einzelnen Versuchen länger, wenn der Fehler weiterhin auftritt. Wenn der Fehler weiterhin besteht oder häufig auftritt, überprüfen Sie Salesforce Trust auf einen gemeldeten Incident, der Ihre Instanz betrifft, oder kontaktieren Sie den Salesforce-Support. Ein verwandtes Szenario wird im Salesforce-Artikel SERVER_UNAVAILABLE: Too Many Requests Waiting for Connections beschrieben.

Salesforce: Datenschema enthält kürzlich hinzugefügte Felder nicht

Symptom: Ein Feld, das kürzlich zu einem Salesforce-Objekt hinzugefügt wurde, wird im Transformationsschema bei der Konfiguration einer Salesforce-Aktivität nicht angezeigt.
Ursache: Das Datenschema wird aus dem Zeitpunkt zwischengespeichert, als die Aktivität zuletzt konfiguriert wurde, und wird nicht automatisch aktualisiert.
Lösung: Öffnen Sie die Aktivitätskonfiguration und durchlaufen Sie jeden Schritt. Nehmen Sie mindestens eine kleine Änderung vor (z. B. Hinzufügen und Entfernen eines Zeichens aus dem Aktivitätsnamen), um ein Neuladen des Schemas zu erzwingen. Klicken Sie auf Fertig, um die aktualisierte Konfiguration zu speichern.

Salesforce: Automap ordnet Felder nicht zu, wenn eine Salesforce-Aktivität das Ziel ist

Symptom: Wenn eine Salesforce-Aktivität (z. B. Einfügen oder Upsert) als Ziel einer Transformation verwendet wird, werden mit Automap keine Felder zugeordnet.
Ursache: Das Salesforce-Aktivitätsschema enthält einen zusätzlichen Stammknoten über den Objektfeldern, wenn das Schema gespiegelt wird. Dieser zusätzliche Stammknoten verhindert, dass Automap Quellfelder den richtigen Zielfeldern zuordnet.
Lösung:
1. Suchen Sie auf der Transformations-Canvas den Objektknoten auf oberster Ebene auf der Zielseite (z. B. Konto).
2. Ziehen Sie den entsprechenden Quellknoten manuell, um ihn auszurichten.
3. Wenn die Knoten ausgerichtet sind, führen Sie Automap erneut aus. Felder unter dem Knoten werden automatisch zugeordnet.

Salesforce Query-Aktivität: Übergeordnete-untergeordnete Abfrage generiert hierarchisches Schema

Symptom: Eine Salesforce-Query-Aktivität mit einer übergeordnet-untergeordneten SOQL-Abfrage generiert ein hierarchisches Antwortschema. Wenn dieses Schema auf der Zielseite einer Transformation gespiegelt wird, ist die Ausgabe hierarchisches XML anstelle einer flachen Struktur.
Ursache: Das hierarchische Schema spiegelt die übergeordnet-untergeordnete Beziehung in der Abfrage wider. Das Spiegeln des Quellschemas auf dem Transformationsziel bewahrt diese Hierarchie in der Ausgabe.
Lösung:
- Um eine flache Ausgabe zu erzeugen, definieren Sie ein flaches Schema auf der Zielseite der Transformation, anstatt das Quellschema zu spiegeln.
- Wenn auf Abfrageergebnisse in einem Skript zugegriffen wird, sind die Daten bereits ohne zusätzliche Konfiguration als flache Struktur verfügbar.

Salesforce: Upsert schlägt für einige Datensätze fehl (doppelte externe ID)

Symptom: Ein Salesforce Upsert- oder Bulk Upsert-Vorgang wird abgeschlossen, meldet aber Fehler für einige Datensätze.
Ursache: Mehrere Quelldatensätze teilen denselben externen ID-Wert. Wenn die externe ID nicht eindeutig ist, gibt Salesforce einen Fehler zurück und der Upsert schlägt für diese Datensätze fehl.
Lösung:
- Überprüfen Sie die Fehlerdatei auf der Seite Runtime der Management Console (Registerkarte Activity Logs), um zu ermitteln, welche Datensätze fehlgeschlagen sind.
- Stellen Sie sicher, dass das als externe ID verwendete Feld für jeden Datensatz einen eindeutigen Wert hat. Siehe Erstellen einer Salesforce-externen ID für Jitterbit.

Salesforce Insert- oder Update-Aktivität: Datensatz-ID-Feld kann nicht zugeordnet werden

Symptom: Eine Transformation enthält eine Zuordnung zum Salesforce Datensatz-ID-Feld in einer Insert- oder Update-Aktivität, aber der Vorgang verwendet den zugeordneten Wert nicht.
Ursache: Das Salesforce Datensatz-ID-Feld kann in Insert- und Update-Aktivitäten keine Zuordnung enthalten. Salesforce weist die Datensatz-ID beim Einfügen automatisch zu; die Update-Aktivität identifiziert Datensätze anhand ihrer vorhandenen Salesforce-ID, die kein zuordnungsfähiges Zielfeld ist.
Lösung: Entfernen Sie die Zuordnung zum Datensatz-ID-Feld aus der Transformation. Wenn das Ziel darin besteht, einen bestimmten Datensatz anhand seiner Salesforce-ID zu aktualisieren, überprüfen Sie, dass die Quelldaten diese ID bereitstellen und dass die Update-Aktivität so konfiguriert ist, dass sie Datensätze dagegen abgleicht.

Salesforce Bulk-Write-Aktivitäten: Erster Datensatz wird übersprungen, wenn die Quelle keine Kopfzeile hat

Symptom: Eine Salesforce Bulk-Schreibaktivität (Bulk Insert, Bulk Upsert, Bulk Update, Bulk Delete oder Bulk Hard Delete) wird ohne Fehler ausgeführt, aber weniger Datensätze als erwartet werden in Salesforce geschrieben. Wenn die Quelle nur einen Datensatz enthält, werden überhaupt keine Datensätze geschrieben.
Ursache: Salesforce Bulk-Schreibaktivitäten behandeln die erste Zeile der Quelldaten immer als Spaltenüberschriftszeile. Dieses Verhalten kann nicht geändert werden. Wenn die Quelldatei keine dedizierte Kopfzeile enthält, wird der erste Datensatz als Kopfzeile verbraucht und nicht in Salesforce geschrieben.
Lösung:
- Stellen Sie sicher, dass die Quelldaten eine Kopfzeile als erste Zeile enthalten. Die Kopfzeilenwerte müssen mit den in der Feldzuordnung der Aktivität definierten Spaltennamen übereinstimmen.
- Überprüfen Sie, dass Datenzeilen in der zweiten Zeile beginnen, unmittelbar nach der Kopfzeile.

Operationsschritte der Salesforce Bulk-Aktivität werden als „Unvollständig" angezeigt, ohne Ein- oder Ausgabedaten

Symptom: Beim Anzeigen eines Vorgangsprotokolls, das eine Salesforce Bulk-Aktivität (Bulk Insert, Bulk Upsert, Bulk Update, Bulk Delete oder Bulk Hard Delete) enthält, zeigt der Vorgangssschriteintrag der Bulk-Aktivität einen Status von Unvollständig an und zeigt keine Ein- oder Ausgabedaten an, auch wenn der Vorgang erfolgreich abgeschlossen wurde und Datensätze verarbeitet wurden.
Ursache: Salesforce Bulk-Aktivitäten generieren keine Komponenteneingabe- und -ausgabedaten im Vorgangsprotokolle. Der Status Unvollständig im Aktivitätsschritt und das Fehlen von Ein- und Ausgabedaten sind erwartetes Verhalten für alle Bulk-Aktivitäten, unabhängig davon, ob die Verarbeitung erfolgreich war.
Lösung:
- Um zu ermitteln, ob Datensätze verarbeitet wurden und ob Fehler aufgetreten sind, überprüfen Sie die Texteinträge im Vorgangsprotokolle auf Fehlermeldungen oder Bestätigung einer erfolgreichen Verarbeitung.
- Bei privaten Agenten können Sie auch detaillierte Ergebnisse pro Datensatz herunterladen: Gehen Sie in der Management Console zur Seite Runtime, wählen Sie die Ausführung aus, öffnen Sie die Registerkarte Activity Logs und laden Sie die Ergebnisdatei herunter.

Salesforce Bulk-Aktivitäten schlagen fehl, wenn sie durch eine API- oder SOAP-Anforderung ausgelöst werden

Symptom: Eine Salesforce Bulk-Aktivität (Bulk Query, Bulk Update, Bulk Insert, Bulk Upsert, Bulk Delete oder Bulk Hard Delete) schlägt sofort bei der Initialisierung fehl mit:
```
Failed to initialize the operation: Failed to get the operation with OperationID = [ID].
A database exception occurred. The reported error was:
ERROR: null value in column "organization_id" of relation "bulkloadinstancetab" violates not-null constraint
```
Die gleiche Bulk-Aktivität wird ohne Probleme ausgeführt, wenn sie unabhängig oder auf andere Weise ausgelöst wird.
Mögliche Ursache: Operationen, die über eine API- oder SOAP-Anfrage ausgelöst werden (z. B. ein Salesforce-Outbound-Message-Flow), unterstützen keine Salesforce Bulk-Aktivitäten. In diesem Kontext ist die Organisations-ID für das Bulk-Load-Subsystem nicht verfügbar, was zum Datenbankconstraint-Fehler bei der Initialisierung führt.
Lösung: Ersetzen Sie die Bulk-Aktivität durch die entsprechende Standard-Salesforce-Aktivität in Operationen, die Teil einer API- oder SOAP-ausgelösten Kette sind. Ersetzen Sie beispielsweise eine Bulk Query durch eine Standard-Query-Aktivität oder ein Bulk Update durch eine Standard-Update-Aktivität. Standard-Aktivitäten funktionieren in diesem Kontext ordnungsgemäß.

Salesforce Events: Events können nach Neustarten des Agenten nicht aktiviert werden

Symptom: Nach dem Neustart oder der Neuinstallation eines privaten Agents können Salesforce Events-Konnektor-Events nicht aktiviert werden, selbst wenn die Verbindungsanmeldedaten korrekt sind.
Mögliche Ursache: Nach einem Neustart ist die Konnektor-JAR-Datei möglicherweise noch nicht auf dem Agent vorhanden. Um ein Event zu aktivieren, muss der Konnektor zunächst auf den Agent heruntergeladen werden.
Lösung:
1. Öffnen Sie die Salesforce Events-Verbindungskonfiguration in Studio.
2. Klicken Sie auf Test, um die Verbindung zu testen. Dies erzwingt den Download der Konnektor-JAR auf den Agent.
3. Nach erfolgreicherem Verbindungstest versuchen Sie erneut, das Event zu aktivieren.

Salesforce Events: Einschränkungen der Listening-Aktivität

Die folgenden Verhaltensweisen von Salesforce Events-Listening-Aktivitäten (Subscribe Event und die Subscribe-Aktivitäten für Insert, Update und Delete CDC Event) sind normal und deuten nicht auf einen Konnektor-Fehler hin:

Events können nicht aktiviert werden, da die maximale Anzahl von Abonnenten erreicht ist. Die Salesforce-Instanz beschränkt die Anzahl gleichzeitiger Clients (Abonnenten). Wenn dieses Limit erreicht ist, können keine weiteren Events aktiviert werden. Reduzieren Sie die Anzahl der aktiven Abonnenten, die mit der Instanz verbunden sind.
Messsymbole wie $ und % fehlen in der Antwort. Diese Symbole werden vom Salesforce API-Design nicht zurückgegeben.
Unveränderte Felder werden in Change Data Capture (CDC)-Antworten als null zurückgegeben. Bei CDC-Aktivitäten werden nur geänderte Felder gefüllt; unveränderte Felder werden vom Salesforce API-Design als null zurückgegeben.

Mehrere SAP-Aktivitäten in einer Operation schlagen zur Laufzeit fehl

Symptom: Ein Vorgang, der mehr als eine SAP-Aktivität enthält oder eine SAP-Aktivität mit einer NetSuite-, Salesforce-, Salesforce Service Cloud-, ServiceMax- oder SOAP-Aktivität kombiniert, wird ohne Validierungsfehler bereitgestellt, schlägt aber bei der Ausführung fehl.
Mögliche Ursache: Vorgänge, die diese Aktivitätstypen mischen, wirken in Studio gültig und können erfolgreich bereitgestellt werden, aber diese Kombinationen werden zur Laufzeit nicht unterstützt. Die Validierungsregeln des Vorgangs kennzeichnen dieses Muster zur Entwurfszeit nicht als Fehler. Dies ist ein dokumentiertes bekanntes Problem in Studio.
Lösung:
- Gestalten jeden Vorgang so, dass er nur eine einzelne SAP-Aktivität enthält, ohne weitere SAP-, NetSuite-, Salesforce-, Salesforce Service Cloud-, ServiceMax- oder SOAP-Aktivitäten im selben Vorgang.
- Falls Daten aus mehreren Systemen in einem einzelnen Workflow erforderlich sind, teilen Sie die Logik auf separate Vorgänge auf und verknüpfen Sie diese mit Vorgangsaktionen.

SAP RFC: „Keine RFC-Berechtigung für Funktionsmodul BAPI_TRANSACTION_COMMIT"

Symptom: Eine SAP-RFC-Aktivität schlägt zur Laufzeit fehl mit:

JCoException occurred No RFC authorization for function module BAPI_TRANSACTION_COMMIT

Mögliche Ursachen:
- Das SAP-Benutzerkonto in der Verbindung besitzt keine S_RFC-Berechtigung für BAPI_TRANSACTION_COMMIT oder die zugehörigen Funktionsgruppen.
- Das Funktionsmodul BAPI_TRANSACTION_COMMIT ist im SAP-System nicht als remote-aktiviert konfiguriert.
- Die Anforderungstransformation vor der Aktivität setzt das Commit-Kontrollfeld nicht.
Lösung:
- Bestätigen Sie im SAP-System, dass das Funktionsmodul BAPI_TRANSACTION_COMMIT remote-aktiviert ist.
- Setzen Sie in der Anforderungstransformation vor der SAP-RFC-Aktivität das Feld BAPI_COMMIT auf true.
- Überprüfen Sie, dass das SAP-Benutzerkonto, auf das in der Verbindung verwiesen wird, S_RFC-Berechtigung für BAPI_TRANSACTION_COMMIT und alle zugehörigen Funktionsgruppen besitzt.
- Falls das Problem weiterhin besteht, wenden Sie sich an Ihren SAP-BASIS-Administrator, um die Berechtigungsobjektzuweisungen des Benutzers zu überprüfen.

SAP-Verbindung schlägt mit „Ungültiger Sprachschlüssel" fehl

Symptom: Eine SAP-Verbindung schlägt während der Initialisierung mit einem Fehler zum Sprachschlüssel fehl:

Connector Error: AdapterResourceException: Error while creating Destination. 00024Invalid language key when configuring the text environment.

Mögliche Ursache: Der im SAP-Endpunkt konfigurierte Sprachcode ist nicht gültig für das Ziel-SAP-System: Der Code ist nicht installiert oder wird auf diesem System nicht unterstützt, oder er ist falsch geschrieben oder falsch geschrieben (z. B. en statt EN). SAP lehnt den ungültigen Schlüssel ab, wenn die Textumgebung des Ziels initialisiert wird.
Lösung:
1. Bearbeiten Sie den SAP-Endpunkt in Studio und setzen Sie das Feld Language auf einen unterstützten zweistelligen Sprachcode (z. B. EN für Englisch).
2. Überprüfen Sie, dass der Wert einem auf dem Ziel-SAP-System installierten und aktiven Sprachcode entspricht. Wenn Sie sich nicht sicher sind, bestätigen Sie die Standardsprache des Integrationsbenutzers im SAP-Benutzerprofil und verwenden Sie diese.
3. Testen Sie die Verbindung aus Studio, um zu bestätigen, dass die Initialisierung erfolgreich ist, bevor Sie den Vorgang erneut bereitstellen.

ServiceNow: Erste Operationsläufe sind nach Neustarten des Agenten oder auf Cloud-Agenten langsam

Symptom: Operationen mit dem ServiceNow-Connector laufen in zwei Szenarien langsam:
- Bei privaten Agents kann die erste Operation nach dem Agent-Neustart mehrere Minuten dauern; nachfolgende Ausführungen sind schnell.
- Bei Cloud-Agents sind Ausführungen zeitweilig langsam und dauern Minuten, wenn sich der Metadaten-Cache des Connectors aktualisiert.
Dies kann zu nachgelagerten API-Timeouts führen.
Mögliche Ursache: Der Connector speichert ServiceNow-Metadaten aggressiv. Nach einem Agent-Neustart bei einem privaten Agent (oder bei jedem Durchlauf für einen Cloud-Agent, der den Cache nicht beibehalten hat), muss die erste Operation den Cache neu erstellen, was mehrere Minuten dauert.
Lösung:
- Bei einem privaten Agent kann die Verlangsamung nach dem Neustart durch Hinzufügen von getcolumnsmetadata=onUse zu den Erweiterten Optionen des ServiceNow-Endpunkts gemildert werden. Diese Einstellung ist nur bei privaten Agents wirksam.
- Für konsistente Leistung bei Cloud-Agents rufen Sie die ServiceNow REST API über den HTTP v2-Connector auf, anstatt den ServiceNow-Connector zu verwenden. Der HTTP v2-Connector speichert keine Metadaten und vermeidet die Neuerstellungsverzögerung.

ServiceNow v2: Ein Objekt wird nicht nach seinem ServiceNow-Connectornamen aufgelistet

Symptom: Ein Objekt, das im ServiceNow-Connector unter einem bekannten Namen auswählbar ist, kann im ServiceNow v2-Connector nicht unter demselben Namen gefunden werden.
Ursache: Der ServiceNow v2-Connector gibt durch die Verwendung der ServiceNow REST API Objekte mit ServiceNows tatsächlichem Backend-Tabellennamen an, der sich vom Namen desselben Objekts im ServiceNow-Connector unterscheiden kann. Beispielsweise entspricht das im ServiceNow-Connector mit System benannte Objekt im ServiceNow v2-Connector Sys.
Lösung: Schlagen Sie in ServiceNow unter System Definition > Tables den tatsächlichen Tabellennamen des Objekts nach und suchen Sie dann nach diesem Namen in der Aktivitätskonfiguration des ServiceNow v2-Connectors.

Shopify: Aktivitätsobjektauswahlen können sich nach API-Versionsaktualisierung ändern

Symptom: Nach Änderung der API-Version für eine Shopify-Verbindung geben eine oder mehrere Shopify-Aktivitäten Fehler zurück oder verhalten sich unerwartet, und ein konfiguriertes Objekt oder Unterobjekt scheint sich geändert zu haben.
Mögliche Ursache: Shopify gibt vierteljährlich neue API-Versionen frei und stellt ältere Versionen nach 12 Monaten ein. Wenn Sie zu einer anderen API-Version wechseln, sind Objekte oder Unterobjekte, die in der neuen Version nicht verfügbar sind, möglicherweise nicht mehr auswählbar, wodurch sich die konfigurierte Auswahl der Aktivität bei der Aktualisierung der Konfiguration ändern kann.
Lösung:
1. Nachdem Sie die Shopify API-Version in der Verbindung geändert haben, öffnen Sie die Konfiguration jeder betroffenen Shopify-Aktivität.
2. Klicken Sie auf Aktualisieren, um die verfügbaren Objekte für die neue API-Version neu zu laden.
3. Überprüfen Sie die Objekt- und Unterobjektauswahl, um zu bestätigen, dass diese Ihre Absicht in der neuen Version widerspiegeln.
4. Aktualisieren Sie alle geänderten Auswahlen zu den richtigen Ersatzobjekten.
5. Stellen Sie die betroffenen Operationen erneut bereit und testen Sie sie erneut.
6. Weitere Informationen zu Shopify-Versionsdeprecation-Zeitplänen finden Sie unter Shopifys Änderungsprotokoll.

Snowflake: Java-Heap-Speicherfehler beim Abfragen großer Datenmengen

Symptom: Eine Snowflake-Aktivität vom Typ Query schlägt mit dem folgenden Fehler fehl, wenn die Abfrage eine große Anzahl von Zeilen zurückgibt:
```
Error executing query activity. Exception is Java heap space
```
Der Connector meldet den Fehler in dieser Form, weil er den zugrunde liegenden Java-Fehler umhüllt, der weiter unten in der Stack-Trace angezeigt wird:
```
Caused by: java.lang.OutOfMemoryError: Java heap space
```
Wenn dieser Fehler bei Abfragen auftritt, die nur wenige Zeilen zurückgeben, oder wenn derselbe Agent auch durch andere Connectors mit Heap-Fehlern fehlschlägt, ist die Ursache eher die Gesamtheap-Zuordnung des Agenten als die Größe des Ergebnissatzes. Weitere Informationen finden Sie unter Java-Heap-Speicherfehler: OutOfMemoryError.
Mögliche Ursache: Der Snowflake-Connector lädt den gesamten Abfrageergebnissatz in den JVM-Speicher, bevor er ihn an die Transformation übergibt. Bei sehr großen Ergebnissätzen wird damit der Tomcat-JVM-Heap auf dem Private Agent erschöpft.
Lösung: Verwenden Sie für große Abfragemengen den Database-Connector mit einem Snowflake-JDBC-Treiber anstelle des Snowflake-Connectors. Der Database-Connector puffert das vollständige Resultset nicht im Speicher, sodass er wesentlich größere Abfragemengen verarbeiten kann. Installieren Sie den Snowflake-JDBC-Treiber auf dem privaten Agent und konfigurieren Sie dann eine Datenbankverbindung, die diesen verwendet. Bei Agent 12.x und höher benötigt diese Datenbankverbindung auch enableArrowResultFormat=false&jdbc_query_result_format=json in der Verbindungszeichenfolge; siehe Snowflake: Operationen schlagen bei Agent 12.x fehl.

Wenn Sie beim Snowflake-Connector bleiben möchten, können Sie mit einer der folgenden Optionen den Speicherdruck verringern, obwohl keine davon garantiert für Datenmengen im Millionenbereich ausreichend ist:
- Teilen Sie die Abfrage mit SQL-Klauseln LIMIT und OFFSET in Batches auf und führen Sie die Operation wiederholt mit inkrementierenden Offsets aus, bis alle Zeilen verarbeitet sind.
- Erhöhen Sie die Tomcat-JVM-Heap-Größe auf dem privaten Agent (siehe Tomcat-Heap-Speicher).

Snowflake: Vorgänge schlagen bei Agent 12.x fehl

Symptom: Bei einem privaten Agent mit Version 12.x schlagen Operationen, die über einen Snowflake-JDBC-Treiber (eine Datenbankverbindung oder ein DBExecute-Skript) Snowflake abfragen, zur Laufzeit fehl, obwohl der Verbindungstest erfolgreich ist. Der Fehler bezieht sich auf die Arrow-Speicherschicht des Treibers, zum Beispiel:

JDBC driver internal error: exception creating result java.lang.ExceptionInInitializerError at net.snowflake.client.jdbc.internal.apache.arrow.memory.unsafe.UnsafeAllocationManager

oder:

JDBC driver internal error: exception creating result java.lang.NoClassDefFoundError: Could not initialize class net.snowflake.client.jdbc.internal.apache.arrow.memory.RootAllocator

Mögliche Ursache: Der Snowflake-JDBC-Treiber gibt Abfrageergebnisse standardmäßig im Apache-Arrow-Format zurück, das mit Agent-Version 12.x und höher nicht kompatibel ist. Details finden Sie in Snowflakes Artikel zur Fehlerbehebung dieses Java-Modulfehlers. Der Verbindungstest gibt kein Resultset zurück, daher ist er weiterhin erfolgreich, während Abfragen fehlschlagen. Ein Upgrade der JDBC-Treiberversion behebt das Problem nicht.
Lösung: Setzen Sie enableArrowResultFormat auf false und jdbc_query_result_format (oder JDBC_QUERY_RESULT_FORMAT) auf json, damit der Treiber Ergebnisse im JSON-Format anstelle von Arrow zurückgibt:
- Database-Connector: Fügen Sie enableArrowResultFormat=false&jdbc_query_result_format=json zur Snowflake-Verbindungszeichenfolge im Feld Zusätzliche Verbindungszeichenfolge-Parameter hinzu (oder im Feld Verbindungszeichenfolge, wenn Verbindungszeichenfolge verwenden ausgewählt ist).
- Snowflake-Connector: Fügen Sie unter Optionale Einstellungen > Verbindung benutzerdefinierte Eigenschaften die Option enableArrowResultFormat mit dem Wert false hinzu. Eine Zeile JDBC_QUERY_RESULT_FORMAT mit dem Wert JSON ist dort bereits standardmäßig vorhanden.
Speichern Sie dann, testen Sie die Verbindung erneut und führen Sie die Operation erneut aus.

Auf einem privaten Agent können Sie die Reparatur stattdessen auf JVM-Ebene anwenden, sodass sie nicht pro Verbindung wiederholt werden muss, indem Sie --add-opens=java.base/java.nio=ALL-UNNAMED zu CATALINA_OPTS hinzufügen:
LinuxWindows
Fügen Sie die folgende Zeile zu /opt/jitterbit/tomcat/bin/setenv.sh hinzu:
export CATALINA_OPTS="$CATALINA_OPTS --add-opens=java.base/java.nio=ALL-UNNAMED"
Starten Sie dann den Agent neu.
1. Öffnen Sie den Registry Editor und suchen Sie den folgenden Schlüssel:

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\Jitterbit Tomcat Server\Parameters\Java

Öffnen Sie den Unterschlüssel Options.
Fügen Sie im Feld Value data den Wert --add-opens=java.base/java.nio=ALL-UNNAMED zu den vorhandenen Java-Optionen hinzu.
Klicken Sie auf Ok.
Starten Sie den Agent neu.

Docker

Verwenden Sie eine der folgenden Strategien, um die Einstellung anzuwenden:

Aktualisieren Sie die Dockerfile und erstellen Sie das Docker-Image neu:
```
docker build -t my-agent .
```

Fügen Sie es im Docker-Befehl run ein:

docker run -e CATALINA_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED" my-agent

Fügen Sie es in docker-compose.yml ein und starten Sie den Container neu:

environment:
  - CATALINA_OPTS=--add-opens=java.base/java.nio=ALL-UNNAMED

Snowflake: Kennwortbasierte Verbindungen schlagen nach Authentifizierungsverwerfung fehl

Symptom: Operationen, die sich mit Snowflake über den Authentifizierungstyp Password (Deprecated) verbinden, schlagen fehl, nachdem sie zuvor funktioniert haben, z. B. mit:

HttpErrorResponse: Error opening connection. Exception is Failed to authenticate: MFA authentication is required, but none of your current MFA methods are supported for programmatic authentication.

Mögliche Ursache: Snowflake stellt die Single-Factor-Authentifizierung (nur Passwort) ein, einschließlich der Konten vom Typ LEGACY_SERVICE, die für diesen Authentifizierungstyp erforderlich sind. Snowflake migriert LEGACY_SERVICE-Konten auf schrittweiser, kontospezifischer Basis zu TYPE=SERVICE, was passwortbasierte Authentifizierung vollständig blockiert. Bei einigen Konten ist auch die Multi-Faktor-Authentifizierung (MFA) aktiviert, die mit dieser vollständig automatisierten, programmgesteuerten Verbindung nicht kompatibel ist, da MFA eine Person im Prozess erfordert. Siehe Password (Deprecated) für den Abschaffungsplan.
Lösung: Aktualisiere die Snowflake-Connector-Verbindung in Studio auf OAuth oder Key-Pair-Authentifizierung und konfiguriere das Snowflake-Benutzerkonto entsprechend. Stelle sicher, dass es nicht in MFA registriert ist.

Snowflake: Entwicklerinstanz schläft, Metadatentabellen werden nicht gefüllt

Symptom: Beim Konfigurieren einer Snowflake-Aktivität wird die Liste der verfügbaren Objekte nicht aufgefüllt oder ist leer, obwohl der Verbindungstest erfolgreich ist.
Mögliche Ursache: Snowflake-Entwicklerinstanzen wechseln in den Schlafmodus, wenn auf sie kürzlich nicht zugegriffen wurde. Obwohl der Verbindungstest gegen eine schlafende Instanz erfolgreich sein kann, gibt die Instanz möglicherweise keine Tabellen- und Objektmetadaten zurück.
Lösung:
1. Melde dich in der Snowflake-Weboberfläche an, um die Instanz aufzuwecken.
2. Öffne die Snowflake-Verbindung in Studio erneut und klicke auf Test, um die Anmeldedaten erneut zu testen.
3. Öffne die Aktivitätskonfiguration erneut, um die Liste der verfügbaren Objekte zu aktualisieren.

Snowflake Query: Nichtübereinstimmung der Stammknotengröße bei flachem Schema verursacht `ProcessFlatStream`-Fehler

Symptom: Eine Snowflake-Query-Aktivität mit flachem Schema schlägt zur Laufzeit fehl mit:
```
StartElement() error, starting element does not match with the root.
qName= "<table_name_lowercase>", root name="<TABLE_NAME_UPPERCASE>"

ProcessFlatStream error
```
Dieser Fehler tritt auf, wenn die Abfrage eine WHERE-Klausel, eine LIMIT-Klausel oder einen Variablenverweis in einer WHERE-Klausel enthält.
Mögliche Ursache: Der Snowflake-Connector gibt den Tabellennamen in Kleinbuchstaben in der XML-Antwort zurück. Wenn Studio ein flaches Schema aus der Abfrage generiert, wird der Name des Stammknotens in Großbuchstaben erstellt. Die Abweichung zwischen dem Stammknoten des Schemas (Großbuchstaben) und dem Stammknoten der XML-Antwort (Kleinbuchstaben) verursacht, dass die Verarbeitung des flachen Streams fehlschlägt.
Lösung: Wähle eine der folgenden Optionen:
- Ändere im flachen Schema den Namen des Stammknotens in Kleinbuchstaben, um die Connector-Ausgabe zu entsprechen. Benenne z. B. SALES_ORDERS in sales_orders um.
- Verwende das Mirror-Schema mit Standardzuordnung statt eines manuell erstellten flachen Schemas. Das Mirror-Schema leitet seine Struktur direkt aus der Connector-Antwort ab und weist diese Abweichung nicht auf.

Snowflake Merge: `stageName` und `fileContent` fehlen im Anforderungsschema für externe Stages

Symptom: Eine Snowflake-Merge-Aktivität, die für eine externe Stage konfiguriert ist, zeigt ein Request-Schema ohne die Felder stageName und fileContent an. Die gleiche Aktivität, die für eine interne Stage konfiguriert ist, zeigt beide Felder an.
Mögliche Ursache: Externe Stages sind schreibgeschützte Verweise auf Dateien, die bereits im externen Cloud-Speicher (S3, GCS oder Azure Blob) vorhanden sind. Die Merge-Aktivität kann keinen Dateiinhalt in eine externe Stage hochladen, daher fehlen im Schema die Felder, die diesen Upload steuern.
Lösung:
- Wenn die Aktivität auf eine externe Stage abzielt, stellen Sie sicher, dass die Datendateien bereits am Cloud-Speicherort vorhanden sind, auf den die Stage verweist. Die Merge-Aktivität liest direkt aus diesen Dateien; kein fileContent-Feld ist erforderlich.
- Wenn Sie Dateiinhalte aus der Operation übertragen müssen, konfigurieren Sie die Merge-Aktivität für die Verwendung einer internen Stage. Das Schema zeigt dann stageName und fileContent an.

Snowflake Insert or Merge: SQL-Syntaxfehler durch Sonderzeichen

Symptom: Eine Snowflake-Aktivität vom Typ Insert oder Merge schlägt mit einem SQL-Kompilierungsfehler fehl, z. B.:
```
SQL compilation error:
syntax error line 1 at position <n> unexpected '<token>'.
```
Spaltenwerte können auch falsch zugeordnet sein, wobei Daten aus einem Feld in der falschen Spalte angezeigt werden.
Mögliche Ursachen:
- Feldwerte mit einfachen Anführungszeichen (z. B. ein Wert wie corner's) werden nicht escaped, bevor sie in die SQL-Payload aufgenommen werden. Das ungeescapte Anführungszeichen beendet die Zeichenkette vorzeitig, wodurch der Rest des Wertes als SQL-Syntax statt als Daten interpretiert wird.
- Ein Zielspaltennamen enthält ein Sonderzeichen, z. B. einen Bindestrich (z. B. Zip-Code). Snowflake erfordert, dass ein Bezeichner mit einem Sonderzeichen in Anführungszeichen gesetzt wird. Ohne Anführungszeichen erzeugt es einen Syntaxfehler am Bindestrich.
Lösung:
- Für Werte mit einfachen Anführungszeichen: Aktivieren Sie in den Optionalen Einstellungen der Snowflake-Verbindung die Option Sonderzeichen escapen. Dies escaped automatisch einfache Anführungszeichen in Insert- und Invoke Stored Procedure-Aktivitätspayloads. Verwenden Sie für Merge-Aktivitäten oder als Alternative für Insert SQLEscape in der Transformationszuordnung, um einfache Anführungszeichen in betroffenen Feldwerten zu escapen, bevor sie die Aktivität erreichen.
- Für Spaltennamen mit Sonderzeichen: Bestätigen Sie, dass Anführungszeichen für Snowflake-Bezeichner verwenden in der Verbindung aktiviert ist (standardmäßig aktiviert).

SOAP-Bereitstellungsfehler: „Keine WSDL mit Locator"

Symptom: Die Bereitstellung eines Projekts, das eine SOAP-Verbindung oder eine API-Aktivität SOAP Request oder SOAP Response enthält, schlägt fehl mit:
```
Failed to deploy - Internal Error: No WSDL with locator
```
Mögliche Ursachen:
- Die WSDL wurde entfernt, erneut importiert oder ihre interne Referenz wurde beschädigt, sodass das Projekt auf eine WSDL-Kennung verweist, die nicht mehr vorhanden ist.
- Das Projekt wurde vor der Version Harmony 12.9 bereitgestellt oder in eine andere Umgebung übertragen, als die Bereitstellung eines Projekts WSDL-Dateien löschen konnte, die noch verwendet wurden. Mit Version 12.9 wird das Löschen verhindert, aber eine WSDL, die vorher gelöscht wurde, muss erneut hochgeladen werden.
Lösung:
1. Laden Sie die WSDL für die betroffene Komponente erneut hoch:
  - Öffnen Sie für eine SOAP-Verbindung die Verbindung und wählen Sie Upload URL oder Upload file (nicht Select existing), laden Sie die WSDL erneut hoch, überprüfen Sie die Einstellungen unter Port und Select methods, und klicken Sie dann auf Save Changes.
  - Öffnen Sie für eine API-Aktivität SOAP Request oder SOAP Response die Aktivität und laden Sie die WSDL in Schritt 1 der Konfiguration erneut hoch.
2. Überprüfen Sie alle Transformationen, die Schemas von der erneut hochgeladenen WSDL erben, und regenerieren Sie diese bei Bedarf.
3. Stellen Sie das Projekt erneut bereit.
4. Wenn das Projekt mehrere WSDLs enthält und unklar ist, welche betroffen ist, konsultieren Sie SOAP-Verbindungsfehlerbehebung, um sie aus einem JSON-Export zu identifizieren.

SOAP WSDL: schemaLocation muss relative Verweise verwenden

Symptom: Eine SOAP-Verbindung, die auf eine WSDL mit importierten XSD-Schemadateien verweist, kann nicht geladen werden oder führt zu Schemaauflösungsfehlern zur Designzeit.
Mögliche Ursache: Die WSDL verwendet absolute URLs in ihren schemaLocation-Attributen für importierte XSD-Dateien (z. B. http://example.com/schema.xsd). Der Agent kann Schemas von absoluten Remote-URLs nicht abrufen, wenn eine lokal importierte WSDL geladen wird.
Lösung:
1. Bearbeiten Sie die WSDL so, dass alle schemaLocation-Verweise relative Pfade verwenden (z. B. schema.xsd statt http://example.com/schema.xsd).
2. Platzieren Sie alle referenzierten XSD-Dateien im selben Verzeichnis wie die WSDL und importieren Sie die WSDL erneut in die SOAP-Verbindung.

SOAP-Connector schreibt XML-Namespace-Präfixe und Struktur um

Symptom: Die vom SOAP-Connector generierte XML-Datei stimmt nicht mit den literalen Namespace-Präfixen oder der Struktur des Quell-WSDL überein (beispielsweise ersetzt der Connector xmlns:ns1 durch xmlns:glob). Strikte SOAP-Services, die den exakten Präfix-Text vergleichen, lehnen die Anfrage ab.
Mögliche Ursache: Die Transformations-Engine verarbeitet SOAP-Nachrichten als strukturierte XML, nicht als Literaltext. Sie erzeugt eine semantisch gleichwertige Payload, die möglicherweise andere Namespace-Präfixe als das Quell-WSDL verwendet.
Lösung: Für SOAP-Services, die eine literale XML-Struktur erfordern, umgehen Sie den SOAP-Connector und erstellen Sie die Request-Payload als String:
1. Erstellen Sie eine HTTP v2-Verbindung, die auf die SOAP-Service-URL zeigt.
2. Erstellen Sie in einer Transformation die SOAP-Datei als String, indem Sie String-Literale und zugeordnete Werte mit dem Operator + verketten. Alternativ können Sie eine Vorlage aus einer Datei lesen und dynamische Werte mit Replace ersetzen.
3. Verwenden Sie in der HTTP v2 POST-Aktivität das Standard-Request-Schema (laden Sie kein benutzerdefiniertes Request-Schema hoch) und ordnen Sie die konstruierte SOAP-Datei dem body-Feld dieses Schemas zu. Der Connector sendet den body-Wert unverändert und behält die literale XML bei.
4. Setzen Sie den Content-Type-Header auf text/xml oder application/soap+xml, und setzen Sie den SOAPAction-Header, falls der Service dies erfordert.
5. Lesen Sie die Antwort des Service aus dem responseContent-Feld des Standard-Response-Schemas der Aktivität.

SOAP: MTOM/XOP-Meldungen werden nicht unterstützt

Symptom: Der SOAP-Connector unterstützt SOAP-MTOM/XOP-Nachrichten (Message Transmission Optimization Mechanism) nicht.
Lösung: Verwenden Sie die Problemumgehung in Unterstützung für SOAP-MTOM/XOP-Nachrichten mit Jitterbit Studio, die die MTOM-Anfrage außerhalb des SOAP-Connectors erstellt.

VTEX: Verbindungstest schlägt mit „Sie haben keine Berechtigung für den Zugriff auf diese Ressource" fehl

Symptom: Ein VTEX-Verbindungstest schlägt in Studio mit einem Berechtigungsfehler fehl, obwohl die gleichen Anmeldedaten in externen Tools wie Postman funktionieren.
```
You don't have permission to access this resource
```
Mögliche Ursache: Der VTEX-Benutzer oder Anwendungsschlüssel, der der Verbindung zugeordnet ist, verfügt über fehlende Berechtigungen, die der Connector zur Validierung der Verbindung verwendet. Diese Berechtigungen sind strenger als diejenigen, die für den grundlegenden Datenzugriff erforderlich sind.
Lösung:
1. Öffnen Sie im VTEX-Admin-Portal das Zugriffsprofil, das dem Benutzer oder Anwendungsschlüssel zugewiesen ist, den Jitterbit verwendet.
2. Bestätigen Sie, dass das Zugriffsprofil die Funktion License Manager mit Zugriff auf die Ressource Get account by identifier enthält.
3. Speichern Sie das Profil und testen Sie die VTEX-Verbindung in Studio erneut.

Workday: WSDL v42.0 und v42.1 geben Fehler für bestimmte Services zurück

Symptom: Operationen, die den Workday-Connector mit WSDL-Version 42.0 oder 42.1 verwenden, schlagen beim Zugriff auf die Web-Services Human_Resources oder Resource_Management fehl.
Mögliche Ursache: WSDL v42.0 gibt bekanntermaßen Fehler für die Services Human_Resources (v42.0) und Resource_Management (v42.0) zurück. WSDL v42.1 gibt bekanntermaßen Fehler für den Service Human_Resources (v42.1) zurück. Dies sind bekannte Probleme, die für diese WSDL-Versionen spezifisch sind.
Lösung:
1. Ändern Sie in der Workday-Verbindungskonfiguration die WSDL-Version auf 41.x oder 43.0 oder später für Operationen, die die Services Human_Resources oder Resource_Management verwenden.
2. Testen Sie die Verbindung und führen Sie die betroffenen Operationen erneut aus, um zu bestätigen, dass das Problem behoben ist.

Workday: Verbindungstest schlägt mit „Die eingereichte Aufgabe ist nicht autorisiert" fehl

Symptom: Ein Workday-Verbindungstest schlägt mit folgender Fehlermeldung fehl:
```
Error occurred while opening connection. The Exception is Processing error occurred. The task submitted is not authorized.
```
Dieser Fehler kann bei beiden Authentifizierungstypen (Basic Auth und JWT Bearer) auftreten. Beachte, dass Vorgänge zur Laufzeit möglicherweise erfolgreich ausgeführt werden, auch wenn der Verbindungstest diese Fehlermeldung zurückgibt. Das liegt daran, dass der Test einen bestimmten Workday-Dienst (Get_Message_Template_Translation_Request) aufruft, der eine Berechtigung erfordert, die der ISU möglicherweise nicht zugewiesen ist, während die tatsächlichen Integrationsvorgänge andere Dienste aufrufen.
Mögliche Ursachen:
- Der Integration System User (ISU) wurde nicht der Sicherheitsgruppe Setup Administrator in Workday zugewiesen. Der Verbindungstest des Connectors wird abgelehnt, wenn dem ISU diese Sicherheitsgruppenzugehörigkeit fehlt.
- Das Feld Workday Host enthält einen falschen Wert. Ein falscher Host führt dazu, dass die Verbindung fehlschlägt, bevor die Authentifizierung versucht wird.
Lösung:
1. Überprüfe, dass der Wert Workday Host in der Verbindungskonfiguration korrekt ist. Der Host sollte die Basis-URL deines Workday-Mandanten sein (z. B. https://wd5-impl-services1.workday.com/). Den korrekten Wert kannst du auf der Workday-Seite View API Client bestätigen.
2. Öffne in der Workday-Instanz die Aufgabe Assign Users to User-based Security Group, wähle Setup Administrator aus und überprüfe, ob der ISU unter System Users aufgeführt ist. Falls nicht, füge den ISU hinzu. Vollständige Schritte findest du unter Voraussetzungen.
3. Bestätige, dass auch die Aufgabe Configure Web Service Security für den ISU abgeschlossen wurde, wie auf der Seite Voraussetzungen beschrieben.
4. Teste die Verbindung erneut.

Chunking erfordert einen nativen Connector als Quelle

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 zeigen an, dass die Batch-Grenze ü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 nur berücksichtigt, wenn die Quelle ein nativer Connector ist. Vorgänge, die native Quellen wie HTTP, Database, Variable und Local Storage verwenden, berücksichtigen Chunking normalerweise.
Lösung:
- Deaktiviere Chunking in den Vorgangsoptionen, falls es nicht erforderlich ist.
- Falls Chunking erforderlich ist, teile den Vorgang in zwei auf:
  - Im ersten Vorgang liest man aus der ursprünglichen Quelle und schreibt in eine Variable Write-Aktivität.
  - Im zweiten Vorgang liest man aus einer Variable Read-Aktivität und schreibt mit aktiviertem Chunking in das ursprüngliche Ziel. Da der Variable-Connector nativ ist, funktioniert Chunking in diesem Vorgang korrekt. Die Schritte zur Einrichtung von Chunking findest du unter Configure operation chunking.

Agent offline oder unerreichbar

Symptom: Die Registerkarte Private der Seite Agents der Management Console zeigt den Agent als Unknown oder Stopped an, oder Studio zeigt einen Agent Not Running or Unreachable-Fehler an.
Mögliche Ursachen:
- Die Jitterbit-Services werden nicht ausgeführt.
- Die Services werden ausgeführt, aber der Agent-Host kann die Harmony Cloud nicht erreichen.
- Ein Unternehmens-Proxy verhindert die Verbindung des Agents.
Lösung:
- Falls die Jitterbit-Services nicht ausgeführt werden, starten Sie diese:
  - Windows: Siehe Windows-Agent starten.
  - Linux: Siehe Linux-Agent starten.
  Falls der Service nicht startet, überprüfen Sie folgende Speicherorte auf Fehlermeldungen:
  - Windows: C:\Program Files (x86)\Jitterbit Agent\log und das Windows-Protokoll Event Viewer Application.
  - Linux: /opt/jitterbit/log.
  Das Konto, das Jitterbit-Services ausführt, benötigt lokale Administratorrechte unter Windows und vollständigen Zugriff auf das Jitterbit-Installationsverzeichnis.
- Falls die Services ausgeführt werden, aber die Harmony Cloud nicht erreichen können, überprüfen Sie folgende Punkte:
  - Die Internetverbindung vom Agent-Host funktioniert.
  - Das Agent-Protokoll (jitterbit-agent.log) enthält keine Fehlermeldungen zur Cloud-Konnektivität.
  - Der Agent kann das Harmony-Portal auf Port 443 erreichen.
- Falls der Agent sich über einen Unternehmens-Proxy verbindet, überprüfen Sie, dass der Proxy korrekt für den Agent konfiguriert ist, einschließlich der NTLM-Domäne, falls der Proxy NTLM-Authentifizierung verwendet. Siehe Proxy-Server für private Jitterbit-Agenten. Das Ablehnungsprotokoll des Proxy-Servers ist hilfreich zur Diagnose, was der Proxy blockiert.
- Falls die Services des Agents auf dem Host fehlerfrei sind (jitterbit status zeigt alle Services als ausgeführt an), der Agent aber wiederholt zu Unknown wechselt oder zwischen Running, Unknown und Stopped wechselt, wird die Verbindung oder der Prozess des Agents wahrscheinlich zwischen den Heartbeats unterbrochen. Überprüfen Sie folgende mögliche Ursachen:
  - Ein Netzwerkgerät (Firewall, NAT-Gateway oder Cloud-VM-Idle-Timeout) kann die ausgehende Verbindung des Agents zwischen den Heartbeats schließen. Versuchen Sie, das Heartbeat-Intervall des Agents (agent.heart.beat.interval) zu reduzieren. Für Cloud-gehostete Agenten siehe Azure VM: Verlorene Verbindungen und WebSocket-/E-A-Fehler, was auch für andere eingeschränkte Netzwerke wie AWS gilt.
  - Der Agent kann unter Speicherdruck abgestürzt sein. Überprüfen Sie auf OutOfMemoryError- oder hs_err_pid-Crash-Dump-Dateien. Siehe Java-Heap-Speicher: OutOfMemoryError.
  - Falls Agenten kürzlich zu einem neuen Betriebssystem migriert wurden und dabei eine Agent-Gruppe wiederverwendet wurde, die zuvor Agenten auf dem alten Betriebssystem gehostet hat, kann die wiederverwendete Gruppe die Ursache sein. Siehe Agent zeigt Unknown oder Stopped nach Wiederverwendung einer Agent-Gruppe über Betriebssysteme hinweg.

Agent zeigt unterschiedliche Versionen oder IP-Adressen an

Symptom: Die Registerkarte Privat der Seite Agents der Management Console zeigt unterschiedliche Versionen oder IP-Adressen für einen privaten Agent an, oder die Werte wechseln nach dem Neustart der Services hin und her.
Mögliche Ursache: Die Host-Maschine des Agents wurde möglicherweise auf Infrastrukturebene dupliziert (z. B. ein VM-Klon, ein Disk-Image, eine Maschinenvorlage oder ein Snapshot, der nach der Installation und Registrierung des Agents erstellt wurde). Der duplizierte Host trägt die gleichen Agent-credentials.txt, sodass sich beide Hosts bei Harmony als derselbe Agent authentifizieren und parallel ausgeführt werden, was zu Kollisionen führt. Zwei Agents können nicht gleichzeitig unter denselben Anmeldedaten ausgeführt werden.
Lösung:
1. Bestätigen Sie, dass ein Duplikat ausgeführt wird. Beenden Sie den Agent auf dem Host, den Sie behalten möchten, warten Sie 10 Minuten, und aktualisieren Sie dann die Registerkarte Privat der Seite Agents der Management Console. Wenn der Agent von Beendet zurück zu Wird ausgeführt wechselt, meldet sich ein anderer Host unter derselben Identität an.
2. Identifizieren und fahren Sie den doppelten Host herunter.
3. Wenn der duplizierte Host nicht heruntergefahren werden kann, deinstallieren Sie den Agent, erstellen Sie einen neuen Agent mit einem anderen Namen, und installieren Sie ihn auf dem Host neu, den Sie behalten möchten.
4. Überprüfen Sie, ob der neue Agent auf der Registerkarte Privat der Seite Agents der Management Console als Wird ausgeführt aufgelistet ist.
5. Löschen Sie den alten Agent-Eintrag mit Actions > Remove.

Agent-Synchronisierungsfehler: Projektänderungen werden nicht angewendet

Symptom: Nach der Bereitstellung von Änderungen in Studio führt der Agent weiterhin die vorherige Version des Projekts aus, oder eine Operation schlägt fehl, weil eine neu hinzugefügte Verbindung auf dem Agent nicht gefunden wird.
Mögliche Ursachen:
- Die Bereitstellung verwendete Configurable Deploy, das nur die ausgewählten Workflows und Operationen bereitstellt. Alle Teile des Projekts außerhalb dieser Auswahl bleiben in ihrer zuvor bereitgestellten Version auf dem Agent.
- Die Komponente wird nicht im logischen Ablauf eines bereitgestellten Workflows verwendet. Nicht verwendete Komponenten werden nicht bereitgestellt, daher wird eine Verbindung, auf die keine bereitgestellte Operation verweist, nicht an den Agent gesendet.
- Während der Synchronisierung ist ein Netzwerk-Timeout oder ein Autorisierungsfehler aufgetreten.
- Wenig Speicherplatz auf dem Agent-Host hat verhindert, dass die synchronisierten Projektdateien geschrieben werden.
Lösung:
- Stellen Sie das vollständige Projekt erneut bereit: Verwenden Sie in Studio Deploy, das alle Operationen des Projekts bereitstellt, anstatt ein Configurable Deploy nur ausgewählter Workflows oder Operationen durchzuführen.
- Starten Sie die Agent-Services neu, um eine Neusynchronisierung aller bereitgestellten Projekte zu erzwingen.
- Überprüfen Sie die Agent-Protokolle auf synchronisierungsbezogene Netzwerk-Timeouts oder Autorisierungsfehler.
- Überprüfen Sie den verfügbaren Speicherplatz auf dem Agent-Host. Ein voller oder fast voller Datenträger kann verhindern, dass der Agent synchronisierte Projektdateien schreibt. Siehe Speicherplatz und Protokollakkumulation.

Fehler 1722 bei Windows-Installation

Symptom: Die Installation des privaten Windows-Agenten schlägt teilweise fehl und zeigt einen dieser Windows Installer-Fehler:
```
Error 1722. There is a problem with this Windows Installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vendor. ...
```
```
Error 1720. There is a problem with this Windows Installer package. A script required for this install to complete could not be run.
```
Beide Fehler bedeuten, dass ein Schritt im Installer (eine benutzerdefinierte Aktion, die in der Fehlermeldung 1722 genannt wird) nicht abgeschlossen wurde. Meistens ist der fehlgeschlagene Schritt das im Installer enthaltene PostgreSQL-Setup. In diesem Fall kann das Installer-Protokoll auch einen KoGetDbService- oder KoInstallPostgreSQLNew-Skriptfehler oder [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified anzeigen, und die im Installer enthaltene PostgreSQL-Datenbank sowie der Windows-Dienst jitterbitpostgres werden möglicherweise nicht vollständig erstellt. Die Meldung kann stattdessen eine andere Aktion benennen, z. B. InstallVerboseLogShipper.
Mögliche Ursachen:
- Ein fehlendes oder in Konflikt stehendes Microsoft Visual C++ Redistributable (das im Installer enthaltene PostgreSQL benötigt es).
- Unzulässige Zeichen im PostgreSQL-Passwort.
- Bei einer Neuinstallation verbleibende PostgreSQL-Komponenten von einem vorherigen Agenten. Das Agent-Deinstallationsprogramm entfernt PostgreSQL, den Windows-Benutzer jitterbitpostgres oder seine Registrierungseinträge absichtlich nicht, und diese Reste können verhindern, dass das neue PostgreSQL-Setup abgeschlossen wird (z. B. kann das Dienstkonto jitterbitpostgres nicht neu erstellt werden).
- Bei einer Neuinstallation oder einem Upgrade verbleibende Komponenten des ausführlichen Log Shippers von einem vorherigen Agenten. Wie bei PostgreSQL entfernt eine Standarddeinstallation den Dienst des ausführlichen Log Shippers oder seine Dateien nicht, und diese Reste können dazu führen, dass die Aktion InstallVerboseLogShipper des Installers fehlschlägt.
- Bei einem Upgrade von einer vorherigen erweiterten Installation, bei der PostgreSQL für die Ausführung unter einem Windows-Dienstkonto konfiguriert wurde, das nicht jitterbitpostgres ist (z. B. NT AUTHORITY\NetworkService), könnte das Upgrade bei Agent-Versionen vor 12.10 mit Fehler 1720 fehlschlagen.
Lösung:
- Installieren Sie das 64-Bit-Microsoft Visual C++ Redistributable für Visual Studio mit vc_redist.x64.exe (deckt Visual Studio 2015, 2017 und 2019 ab), bevor Sie den Agent installieren, und halten Sie es installiert, da das Entfernen während einer Bereinigung auch die Installation beschädigt.
- Wenn das PostgreSQL-Passwort verbotene Zeichen enthält, ändern Sie das Passwort in ein gültiges, bevor Sie die Installation erneut versuchen.
  
  Hinweis
  
  Bei privaten Agents 12.8 und später validiert das Installationsprogramm das Passwort des PostgreSQL-Dienstkontos (jitterbitpostgres) bei der Eingabe gegen Zeichenbeschränkungen und fordert Sie auf, es zu korrigieren, bevor PostgreSQL installiert wird.
- Wenn Sie nach einem vorherigen Agent neu installieren, entfernen Sie zunächst das verbleibende PostgreSQL vollständig: Folgen Sie Deinstallieren eines privaten Windows-Agents, und bestätigen Sie dann, dass der Windows-Benutzer jitterbitpostgres, das PostgreSQL-Programm und die Datenverzeichnisse sowie die PostgreSQL-Registrierungsschlüssel entfernt sind.
- Wenn die Fehlermeldung 1722 die Aktion InstallVerboseLogShipper nennt, entfernen Sie den verbleibenden Verbose-Log-Shipper-Dienst und seine Dateien vom vorherigen Agent, deinstallieren Sie den Agent erneut und installieren Sie ihn neu.
- Wenn die vorherige Installation eine erweiterte Installation mit PostgreSQL ist, das unter einem anderen Dienstkonto als jitterbitpostgres ausgeführt wird, führen Sie ein Upgrade auf Agent-Version 12.10 oder später durch, was dieses Problem behebt. Bei einer früheren Agent-Version konfigurieren Sie den vorhandenen PostgreSQL-Dienst so um, dass er unter dem Windows-Dienstkonto jitterbitpostgres ausgeführt wird, bevor Sie das Upgrade durchführen.
  
  Wenn die Installation nach einer gründlichen Bereinigung immer noch fehlschlägt, wenden Sie sich an den Jitterbit-Support.

PostgreSQL-Service nach fehlgeschlagenem Upgrade unter Windows entfernt

Symptom: Nach einem fehlgeschlagenen Upgrade eines privaten Agents unter Windows wird der PostgreSQL-Dienst (postgresql-x64-<VERSION>) nicht mehr in den Windows-Diensten angezeigt, und die Jitterbit-Agent-Dienste können nicht gestartet werden, da eine Abhängigkeit fehlt.
Ursache: Dies tritt bei privaten Agent-Versionen vor 11.59 / 12.3 auf, wenn während des Upgrades ein falsches Passwort eingegeben wird und das Installationsprogramm nicht ordnungsgemäß zurückgerollt wird. Dieses Problem ist in privatem Agent 11.59 / 12.3 und später behoben, wo ein falsches Passwort das Upgrade im selben Dialog blockiert und eine erneute Eingabe oder einen Abbruch ermöglicht, ohne die vorhandene Installation zu beeinträchtigen.
Lösung:
1. Öffnen Sie eine Eingabeaufforderung als Administrator.
2. Registrieren Sie den PostgreSQL-Dienst erneut:
```
"C:\Program Files\PostgreSQL\<VERSION>\bin\pg_ctl.exe" register -N "postgresql-x64-<VERSION>" -D "C:\Program Files\PostgreSQL\<VERSION>\data"
```
  Ersetzen Sie <VERSION> durch Ihre PostgreSQL-Versionsnummer. Um diese zu finden, siehe PostgreSQL-Version im privaten Agent enthalten.
3. Starten Sie die PostgreSQL- und PgBouncer-Dienste:
```
net start postgresql-x64-<VERSION>
net start JitterbitPgbouncer
```
4. Starten Sie alle Jitterbit-Agent-Dienste:
```
"C:\Program Files\Jitterbit Agent\StartServices.bat"
```
5. Sobald der Agent ausgeführt wird, setzen Sie die PostgreSQL-Admin- und Dienstkonto-Passwörter zurück, bevor Sie das Upgrade erneut versuchen.

Agent-Services starten nach dem Neustart von Windows nach einem Upgrade nicht

Symptom: Ein Upgrade eines privaten Windows-Agents von einem 11.x-Agent zu einem 12.x-Agent vor Version 12.10 wird erfolgreich abgeschlossen, aber die Jitterbit-Agent-Dienste können beim nächsten Neustart des Host-Systems nicht gestartet werden.
Mögliche Ursache: Das Upgrade hinterlässt den vorherigen PostgreSQL-Windows-Dienst (postgresql-x64-<VERSION>, wobei <VERSION> die vom vorherigen Agent installierte Version ist) mit dem Starttyp Automatisch. Beim Neustart startet dieser ältere Dienst vor dem PostgreSQL-Dienst, der durch das Upgrade installiert wurde, und belegt denselben Port, was verhindert, dass der neue PostgreSQL-Dienst und damit der Agent gestartet werden.
Lösung:
- Upgrade auf Agent-Version 12.10 oder später durchführen, die den vorherigen PostgreSQL-Dienst während des Upgrades entfernt.
- Bei einer früheren Agent-Version nach dem Upgrade Windows-Dienste öffnen, den älteren postgresql-x64-<VERSION>-Dienst identifizieren (denjenigen, der dem Upgrade vorausgeht), seinen Starttyp auf Manuell oder Deaktiviert setzen oder ihn deinstallieren, bevor das Hostsystem neu gestartet wird. Um zu überprüfen, welche Version derzeit mit dem Agent gebündelt ist, führen Sie den Befehl in Gleiche Version wie die gebündelte aus.

TFA verhindert die Installation des 64-Bit-Windows-Agents

Symptom: Die Installation eines privaten 64-Bit-Windows-Agents schlägt fehl, wenn die Zwei-Faktor-Authentifizierung (TFA) für die Organisation aktiviert ist.
Lösung: TFA vorübergehend deaktivieren, den Agent installieren und dann TFA erneut aktivieren. Die Einstellung Zwei-Faktor-Authentifizierung (TFA) erforderlich befindet sich auf der Registerkarte Benutzerverwaltung der Organisationsrichtlinien, auf die über die Seite Organisationen der Management Console zugegriffen wird.

Linux-Installation ohne Root-Berechtigung schlägt fehl

Symptom: Das Installationsprogramm Linux Redhat Non-Root (x64) schlägt fehl.
Lösung: Überprüfen Sie Folgendes:
- Der Benutzer ohne Root-Berechtigung verfügt über sudo-Berechtigungen. Ein Systemadministrator muss den Benutzer zur Gruppe wheel hinzufügen. Um die aktuelle Gruppenmitgliedschaft zu überprüfen, führen Sie groups aus.
- Wenn Sie als Benutzer jitterbit angemeldet sind, ist die Umgebungsvariable JITTERBIT_HOME auf den Installationsort gesetzt:
```
echo $JITTERBIT_HOME
```
  Das Ergebnis sollte /opt/jitterbit sein. Dies wird durch $HOME/.bashrc.d/jitterbit gesetzt, wenn die Installationsanweisungen befolgt werden. Um es manuell zu setzen, führen Sie aus:
```
. /opt/jitterbit/scripts/set.env
```
- Wenn das Installationsprogramm stattdessen mit einem OPENSSL_3.4.0-Fehler fehlschlägt, ist dies ein bekanntes Problem bei RHEL 9.7 und später. Siehe RHEL 9.7 und später zeigen einen OpenSSL-Fehler bei der Installation des privaten Agents ohne Root-Berechtigung in den bekannten Problemen des privaten Agents für eine Problemumgehung.

JDBC-Treiber: „Kein geeigneter Treiber gefunden"

Symptom: Eine Datenbankverbindung schlägt fehl, weil der erforderliche JDBC-Treiber nicht auf dem Agent installiert ist, mit einem Fehler wie No suitable driver found for jdbc:<subprotocol>://....
Ursache: Jitterbit wird nicht mit allen JDBC-Treibern ausgeliefert. Der erforderliche Treiber muss manuell installiert werden.
Lösung: Den erforderlichen Treiber manuell installieren: ihn in JdbcDrivers.conf registrieren und die Treiber-.jar-Datei in JITTERBIT_HOME/tomcat/drivers/lib/ kopieren, dann den Agent neu starten. Die vollständigen Schritte finden Sie unter JDBC-Treiber installieren.

Java-Heap-Speicher: `OutOfMemoryError`

Symptom: Operationen, die große Dateien verarbeiten oder viele Operationen gleichzeitig ausführen, schlagen fehl mit:
```
java.lang.OutOfMemoryError: Java heap space
```
Ursache: Die maximale Java-Heap-Größe (-Xmx) des privaten Agenten ist für die Workload (große Dateien oder hohe Job-Parallelität) zu klein.
Lösung:
1. Erhöhen Sie den maximalen Java-Heap des privaten Agenten. Siehe Tomcat heap memory, um den -Xmx-Wert zu ändern (z. B. von -Xmx1024m zu -Xmx4096m).
2. Starten Sie die Agent-Services nach der Änderung neu.
3. Konfigurieren Sie für Operationen, die große Dateien verarbeiten, chunking, um die Speichernutzung pro Job zu reduzieren. Studio wendet Streaming-Transformationen automatisch an, wo sie zutreffen.
4. Wenn native observability aktiviert ist, verwenden Sie das Diagramm System Resource Capability auf der Registerkarte Metrics der Seite Agents der Management Console, um die Speichernutzung im Laufe der Zeit zu überwachen und den Heap für die Workload richtig zu dimensionieren.

Speicherplatz und Protokollakkumulation

Symptom: Der Host des privaten Agenten läuft aus Speicherplatz aus, was dazu führen kann, dass PostgreSQL heruntergefahren wird oder Operationen mit Berechtigungsfehlern fehlschlagen. Log- und temporäre Dateien sammeln sich in den Agent-Verzeichnissen an, besonders auf Agenten, die hohe Volumen verarbeiten.
Lösung:
- Überprüfen Sie den verfügbaren Speicherplatz auf dem Agent-Host.
- Identifizieren Sie große Dateien. Agent-Logs und temporäre Dateien befinden sich unter JITTERBIT_HOME/log, JITTERBIT_HOME/tomcat/logs (catalina.out) und JITTERBIT_HOME/DataInterchange/Temp. Siehe Log files für die vollständige Liste. Eine einzelne Log-Datei kann mehrere Gigabyte groß werden, wenn eine Komponente übermäßig protokolliert (z. B. ein ausführlicher Connector, der catalina.out überschwemmt) oder wenn ein Fehler sich wiederholt (z. B. eine fehlgeschlagene Datenbankverbindung, die sich in ProcessEngine.log wiederholt). Löschen Sie übergroße Dateien, wenn der Speicherplatz kritisch niedrig ist. Das Löschen der Datei und der Neustart des Agenten können auch den zugrunde liegenden Fehler beheben.
- Bestätigen Sie, dass der Cleanup-Service ausgeführt wird und seine Aufbewahrung eingehalten wird. Überprüfen Sie im Abschnitt [FileCleanup] von jitterbit.conf, dass AutoStart auf true gesetzt ist, und überprüfen Sie FrequencyInHours. Die Aufbewahrung pro Verzeichnis wird in CleanupRules.xml mit NumDays oder NumOfHours festgelegt.
- Wenn der Cleanup-Service aktive Log-Dateien nicht löschen kann (Tomcat hält seine stdout- und stderr-Logs unter Windows offen), erhöhen Sie FileAge für dieses Verzeichnis in CleanupRules.xml auf mindestens einen Tag, damit Cleanup keine Dateien anvisiert, die noch geschrieben werden.
- Wenn große .dmp-Crash-Dump-Dateien den Speicher des Agenten verbrauchen, siehe JVM mini-dump files fill the agent's disk.

`TranDb`-Verbindungsfehler

Symptom: Operationen schlagen mit Fehlern fehl, die auf die interne PostgreSQL-Datenbank des privaten Agenten verweisen, oder interne Agent-Services können nicht gestartet werden, da das Verbindungslimit erreicht wurde. Wiederholte Fehler können auch ProcessEngine.log überfluten und es auf mehrere GB anwachsen lassen:
```
Failed to connect to back-end database 'TranDb'
```
```
FATAL: query_wait_timeout
```
```
FATAL: remaining connection slots are reserved for non-replication superuser connections
```
Mögliche Ursachen:
- Das Limit max_connections der internen PostgreSQL oder das Limit max_db_connections von PgBouncer ist für die Workload des Agenten zu niedrig.
- Operationen stauen sich unter hoher Last oder aufgrund einer Netzwerk- oder Endpoint-Verlangsamung auf und halten Datenbankverbindungen, bis der PgBouncer-Pool erschöpft ist (query_wait_timeout).
- Bei einem Windows-Agent beeinträchtigt IP Helper die lokalen Datenbankverbindungen des Agenten.
Lösung:
- Aktuelle Agent-Versionen werden standardmäßig mit höheren PostgreSQL- und PgBouncer-Verbindungslimits ausgeliefert. Bestätigen Sie daher zunächst, dass der Agent eine aktuelle Version hat. Falls ein aktueller Agent sein Verbindungslimit trotzdem ausschöpft, kontaktieren Sie den Jitterbit-Support, um es unter Support-Anleitung zu erhöhen. Die gebündelten PostgreSQL- und PgBouncer-Instanzen sollten nur unter Support-Anleitung geändert werden.
- Falls die Limits bereits ausreichend sind, untersuchen Sie, was Verbindungen offen hält: Überprüfen Sie die Agent-Host-Last und mögliche Netzwerk- oder Endpoint-Verzögerungen, die Operationen aufstauen.
- Deaktivieren Sie auf einem Windows-Agent IP Helper. Siehe IPv6-Problem unter Windows.

PostgreSQL: Schnelles administratives Herunterfahren

Symptom: Alle Operationen schlagen fehl, weil die Datenbank des Agenten nicht verfügbar ist (Operationen können im Status Ausstehend steckenbleiben), und das PostgreSQL-Protokoll zeichnet ein schnelles Herunterfahren auf:
```
received fast shutdown request
```
Verbindungsoperationen können auch FATAL: terminating connection due to administrator command melden.
Mögliche Ursachen:
- Eine externe oder Systemoperation hat PostgreSQL gestoppt oder neu gestartet: ein Betriebssystem-Neustart, ein Windows-Update oder eine geplante Aufgabe, oder ein Überwachungs- oder Sicherungstool, das Dienste neu startet.
- Der Agent-Host hatte wenig CPU oder Speicher, was Tomcat zum Absturz brachte und PostgreSQL mit sich zog.
Lösung:
- Starten Sie die PostgreSQL- und Jitterbit-Agent-Dienste neu (oder starten Sie den Agent-Host neu), um die Wiederherstellung durchzuführen. Falls Operationen nach der Wiederherstellung von PostgreSQL im Status Ausstehend oder Wird ausgeführt steckenbleiben, kontaktieren Sie den Jitterbit-Support, da der Datenbankverbindungspool des Agenten möglicherweise nicht wiederhergestellt wurde.
- Ermitteln Sie, was PostgreSQL gestoppt hat: Überprüfen Sie das Betriebssystem-Ereignisprotokoll (unter Windows Ereignisanzeige) um den Zeitpunkt des Fehlers auf Neustarts, Updates, geplante Aufgaben, Dienstabstürze oder Sicherungs- und Überwachungstools, die Dienste neu starten. Verhindern Sie oder verschieben Sie, was es stoppt, und stellen Sie den PostgreSQL-Dienst so ein, dass er bei Fehler automatisch neu startet.
- Überprüfen Sie CPU und Speicher des Agent-Hosts. Falls die Jitterbit-Dienste unter Last abstürzen, siehe Agent-Dienst-Neustartschleife und Java-Heap-Speicher: OutOfMemoryError.

Fehler beim Zertifikat-Handshake (TLS)

Symptom: Operationen, die sich mit sicheren Endpunkten verbinden, schlagen während des TLS-Handshakes fehl, mit Fehlern wie:

error:0A000152:SSL routines::unsafe legacy renegotiation disabled

SSLHandshakeException: Received fatal alert: protocol_version

PKIX path building failed: unable to find valid certification path to requested target

Mögliche Ursachen:
- Der Endpunkt verwendet TLS-Legacy-Renegotiation, die der Agent standardmäßig blockiert.
- Der Agent und der Endpunkt können keine gemeinsame TLS-Version oder Cipher aushandeln. Agent-Versionen 11.x und 12.x werden mit unterschiedlichen Sicherheitsbibliotheken ausgeliefert, daher kann ein Endpunkt, der sich auf einem 11.x-Agent nicht verbindet, auf einem 12.x-Agent erfolgreich sein.
- Das Zertifikat des Endpunkts (oder eines seiner Zwischenzertifikate) wird vom Agent nicht vertraut, da die ausstellende CA nicht im cacerts-Truststore der Agent-JRE enthalten ist.
Lösung: Führen Sie vom Agent-Host aus Folgendes aus, um zu bestätigen, welche TLS-Version der Endpunkt aushandelt und ob der Handshake auf Netzwerkebene erfolgreich ist:
```
openssl s_client -connect hostname:port
```
Wenden Sie dann die Lösung an, die dem Fehler entspricht:
- Wenn der Fehler unsafe legacy renegotiation disabled ist, setzen Sie AllowUnsafeLegacyRenegotiation=true im Abschnitt [Settings] von jitterbit.conf und starten Sie den Agent neu. Diese Einstellung erfordert Agent-Version 11.39 oder später.
- Wenn der Fehler PKIX path building failed: unable to find valid certification path to requested target ist, befindet sich das Zertifikat des Endpunkts (oder eines seiner Zwischenzertifikate) nicht im cacerts-Truststore der Agent-JRE. Verwenden Sie keytool -import im cacerts der Agent-JRE (Standardpasswort changeit), um die fehlenden Zertifikate zu importieren, und starten Sie dann die Agent-Services neu. Für eine SQL Server-Datenbank, auf die über eine Database-Verbindung zugegriffen wird, können Sie dies auch in den Treibereinstellungen der Verbindung statt im Truststore lösen, sowohl auf Cloud- als auch auf Private Agents. Siehe SQL Server: Verbindung schlägt mit PKIX-Zertifikatpfad-Fehler fehl.
- Wenn ein TLS-Aushandlungs- oder Handshake-Fehler bestehen bleibt, besonders auf einem 11.x-Agent, führen Sie ein Upgrade auf einen aktuellen 12.x-Agent durch, der aktualisierte Sicherheitsbibliotheken und einen aktualisierten Zertifikat-Truststore enthält.

FTP: Datenverbindung hat das Zeitlimit überschritten

Symptom: FTP-Anmeldung erfolgreich, aber Dateiauflistung oder Dateiübertragung hängt und überschreitet das Zeitlimit.
Mögliche Ursachen:
- Der FTP-Verbindungsmodus (aktiv vs. passiv) ist mit der Netzwerk- oder Firewall-Konfiguration nicht kompatibel.
- Der auf dem FTP-Server definierte passive Portbereich ist in der Unternehmens-Firewall nicht offen.
Lösung:
- Aktivieren oder deaktivieren Sie in den FTP-Verbindungseinstellungen das Kontrollkästchen Passiver Modus. Der passive Modus wird im Allgemeinen für Agenten hinter einer Firewall bevorzugt.
- Bestätigen Sie mit Ihrem Netzwerk-Team, dass der auf dem FTP-Server konfigurierte passive Portbereich in der Firewall zwischen dem Agent und dem FTP-Server offen ist.
- Um detaillierte Protokolle auf Verbindungsebene zu erfassen, aktivieren Sie das Curl-Debug-Logging, indem Sie CurlDebugDir im Abschnitt [Settings] von jitterbit.conf setzen. Siehe Curl-Protokolle.

IPv6-Problem unter Windows

Symptom: Einige Agents treten auf Konnektivitätsprobleme auf, wenn IPv6 auf dem Windows-Host aktiviert ist. Dies kann sich beispielsweise als Operationen manifestieren, die im Status Ausstehend stecken bleiben, mit einem schnell wachsenden ProcessEngine.log, wenn der IP-Hilfsdienst abstürzt und der Agent seine Verbindung zur internen Datenbank verliert.
Lösung: Deaktivieren Sie sowohl IPv6 als auch IP Helper auf dem Windows-Host.

Deaktivieren Sie IPv6 wie folgt:
1. Öffnen Sie Systemsteuerung > Netzwerk und Internet > Netzwerkverbindungen.
2. Öffnen Sie die Eigenschaften der Netzwerkverbindung.
3. Deaktivieren Sie das Kontrollkästchen für Internetprotokoll Version 6 (TCP/IPv6):
Deaktivieren Sie IP Helper wie folgt:
1. Öffnen Sie Dienste.
2. Suchen Sie IP Helper, klicken Sie mit der rechten Maustaste darauf, und wählen Sie Eigenschaften.
3. Klicken Sie auf Beenden, und setzen Sie dann Starttyp auf Deaktiviert:

attachment

Azure VM: Verlorene Verbindungen und WebSocket/I/O-Fehler

Symptom: Private Agents, die auf Azure-VMs installiert sind, erleben Verbindungsabbrüche oder WebSocket/I/O-Fehler.
Lösung: Reduzieren Sie das Heartbeat-Intervall des Agents und erhöhen Sie die Idle- und Flow-Timeouts der Azure-VM. Weitere Informationen finden Sie unter Azure VM: Verlorene Verbindungen und WebSocket/I/O-Fehler im Leitfaden zur Agent-Fehlerbehebung.

Apache: Keine installierten `ConfigArgs`

Symptom: Der Agent gibt folgende Meldung zurück:

No Installed ConfigArgs for the Service "Jitterbit Apache Server"

Ursache: Das Konto, das den Jitterbit Apache-Server ausführt, hat keinen vollständigen Zugriff auf das Jitterbit-Installationsverzeichnis.
Lösung: Gewähren Sie dem Dienstkonto vollständigen Zugriff auf den Jitterbit-Installationsordner und starten Sie die Dienste neu.

Apache/Tomcat: `APPARENT DEADLOCK`

Symptom: Unter anhaltender Last stoppt der Agent die Verarbeitung von Operationen und kann in der Management Console als stoppend angezeigt werden. Das Agent-Protokoll enthält:
```
ThreadPoolAsynchronousRunner: APPARENT DEADLOCK
```
Das Protokoll kann auch An existing connection was forcibly closed by the remote host für die PostgreSQL-Datenbank des Agents anzeigen. Ein Neustart des Agents stellt den normalen Betrieb vorübergehend wieder her, woraufhin der Deadlock unter Last erneut auftritt.
Mögliche Ursachen:
- Der Connection Pool der Agent-Datenbank verursacht einen Deadlock, wenn die interne PostgreSQL-Datenbank unter hoher Last keine verfügbaren Verbindungen mehr hat.
- Der Java-Datenbankverbindungs-Pool des Agents (im Protokoll als c3p0 angezeigt) kann sich nach einem kurzzeitigen Datenbankverbindungsverlust nicht wiederherstellen, beispielsweise während einer vorübergehenden Netzwerkunterbrechung, obwohl PostgreSQL selbst mit Standard-Timeouts fehlerfrei und responsiv bleibt.
- Veraltete Jitterbit-Prozesse halten Threads und Datenbankverbindungen. Dies kann auftreten, wenn ein Agent aktualisiert wird, während noch Operationen ausgeführt werden, oder wenn die Dienste beendet werden, ohne dass alle Jitterbit-Prozesse sauber beendet werden.
- Der Agent-Host ist durch Spitzenaktivität überlastet oder seine CPU wird gedrosselt. Beispielsweise drosselt eine burstable Cloud-Instanz (z. B. ein AWS t3-Typ) ihre CPU, sobald ihre Burst-Credits aufgebraucht sind, was die interne PostgreSQL unter Last aushungern kann.
Lösung:
- Alle Jitterbit-Dienste beenden, alle noch laufenden Jitterbit-Prozesse beenden und dann die Dienste neu starten, um den Deadlock zu beheben.
- Falls der Deadlock im Java-Verbindungspool (c3p0) auftritt und PostgreSQL selbst funktioniert einwandfrei, den Agent auf seinen internen C++-Verbindungspool umschalten, indem man UseInternalPooling=true im Abschnitt [DbInfo] von jitterbit.conf setzt, und dann den Agent neu starten. Der interne Pool erholt sich zuverlässiger von unterbrochenen oder veralteten Verbindungen. Bei Neuinstallationen von Windows-Private-Agents ab Version 12.5 ist dies bereits standardmäßig aktiviert.
- Die Last auf dem Agent reduzieren: Operationen planen, um Spitzenlastspitzen zu vermeiden, Agents zur Agent-Gruppe hinzufügen, um die Last zu verteilen, und bestätigen, dass der Host die Systemanforderungen erfüllt. Für Cloud-Hosts eine Instanzart mit konstanter (nicht burstfähiger) CPU-Leistung verwenden.
- Vor dem Upgrade eines Agents diesen drain stop durchführen und laufende Operationen beenden lassen, damit während des Upgrades keine Prozesse Datenbankverbindungen halten. In ausgelasteten Umgebungen zusätzliche Zeit für den Abschluss des Drain Stop einplanen.

Apache stürzt unter gleichzeitiger Last unerwartet ab

Symptom: Unter gleichzeitiger Last stürzt der Apache-Prozess des Agents unerwartet ab und wird neu gestartet. Der Agent kann in der Management Console kurzzeitig als stoppend oder neu startend angezeigt werden. Operationen, die zu diesem Zeitpunkt ausgeführt wurden, können fehlschlagen oder in einem unvollständigen Zustand verbleiben.
Mögliche Ursachen:
- Ein Skript verwendet verschachtelte RunOperation-Aufrufe, um eine untergeordnete Operation synchron (Standard) von einer übergeordneten Operation aus auszuführen, und beide Operationen lesen oder schreiben gleichzeitig auf dieselbe globale Variable.
- Eine Transformation ist mit Chunking und mehreren Threads konfiguriert, und ein Thread wird beendet, bevor ein anderer Thread, der zur gleichen Zeit gestartet wurde, beendet wird.
- Mehrere Operationen mit aktivierter Datengenerierung für Komponenteneingabe und -ausgabe werden gleichzeitig ausgeführt.
Lösung: Den Private Agent auf Version 12.10 oder später aktualisieren, was diese Probleme behebt. Auf früheren Versionen gibt es keine Problemumgehung.

Cleanup-Dienst kann gesperrte Protokolldateien unter Windows nicht entfernen

Symptom: Protokolldateien auf einem Windows-Private-Agent wachsen unbegrenzt, und der Cleanup-Dienst entfernt sie nicht. Das Cleanup-Dienst-Protokoll meldet einen Fehler wie:

Failed to remove file, retries (10) exhausted: '...\jitterbit tomcat server-stdout.<date>.log'. Reason: The process cannot access the file because it is being used by another process.

Mögliche Ursachen:
- Ein Agent-Prozess hält die Datei offen. Unter Windows kann der Cleanup-Dienst eine Datei, die in Gebrauch ist, nicht entfernen, und Tomcat hält seine stdout- und stderr-Protokolldateien während der Ausführung offen.
- Software von Drittanbietern (Antivirus oder ein Überwachungs-Agent) hält eine Sperre auf Dateien im Protokollverzeichnis des Agents.
Lösung:
- CleanupRules.xml bearbeiten, um die Aufbewahrung (FileAge) für die betroffenen Protokollverzeichnisse zu verkürzen, damit Dateien umgehend entfernt werden, sobald sie nicht mehr in Gebrauch sind. Den Agent nach dem Bearbeiten der Datei neu starten.
- Die kontinuierlich geschriebenen Tomcat-stdout- und stderr-Protokolle aus den Cleanup-Regeln ausschließen, damit der Dienst nicht wiederholt Dateien erneut versucht, die während der Agent-Ausführung gesperrt bleiben.
- Falls Software von Drittanbietern beteiligt ist, das Jitterbit-Installationsverzeichnis und die Protokollverzeichnisse zur Ausschlussliste hinzufügen.
- Falls Protokolle weiterhin wachsen, obwohl gültige Cleanup-Regeln vorhanden sind, den Jitterbit-Support kontaktieren.

Agent kann nach der Abmeldung nicht mit Authentifizierungsfehlern neu gestartet werden

Symptom: Ein Agent, der mit deregisterAgentOnDrainstop=true (oder der Umgebungsvariable AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP) konfiguriert ist, kann nach dem Stoppen nicht neu gestartet werden. Dies gilt für Docker-Agenten, die ein persistentes Volume für /opt/jitterbit/Resources verwenden, und für nicht containerisierte Linux-Agenten.
Ursache: Wenn der Agent mit deregisterAgentOnDrainstop=true stoppt, wird er aus Harmony deregistriert, aber die nun ungültige Datei credentials.txt bleibt auf der Festplatte. Beim Neustart versucht der Agent, die veralteten Anmeldedaten zu verwenden, und kann sich nicht authentifizieren.

Hinweis

Ab Docker-Agent-Version 12.4 wird beim Neustart des Containers mit aktiviertem deregisterAgentOnDrainstop=true der vorhandene Agent automatisch deregistriert und ein neuer registriert. Die folgenden Schritte gelten für Docker-Agenten in früheren Versionen und für Linux-Agenten in jeder Version.
Lösung: Entfernen Sie die veraltete Datei credentials.txt und starten Sie den Agent neu, um eine neue Registrierung auszulösen.

Auf einem nicht containerisierten Linux-Agent entfernen Sie die Datei direkt:
```
rm /opt/jitterbit/Resources/credentials.txt
```
Auf einem Docker-Agent entfernen Sie die Datei aus dem bereitgestellten Volume:
```
docker run -i --rm -v VOLUME_NAME:/opt/jitterbit/Resources jitterbit/agent rm -i /opt/jitterbit/Resources/credentials.txt
```
Ersetzen Sie VOLUME_NAME durch den Namen des Docker-Volumes, unter dem /opt/jitterbit/Resources bereitgestellt wird.

Änderung der Cloud-Protokollierung erfordert Neustart des privaten Agents

Symptom: Nach dem Umschalten von Cloud-Protokollierung für eine private Agent-Gruppe ein oder aus ändert sich das Protokollverhalten auf der Seite Runtime der Management Console nicht.
Lösung: Nachdem Sie die Einstellung Cloud-Protokollierung auf der Seite Agents geändert haben, starten Sie alle privaten Agents in der Gruppe neu, damit die Änderung wirksam wird.

Das Hinzufügen eines zweiten Agents zu einer Standard-Agent-Gruppe ist nicht zulässig

Symptom: Der Versuch, einen zweiten privaten Agent zu einer vorhandenen Gruppe hinzuzufügen, schlägt fehl, oder die Gruppe zeigt eine Warnung nach dem Hinzufügen an.
Mögliche Ursache: Eine Standard-Agent-Gruppe erlaubt maximal einen Agent. Das Ausführen von mehr als einem Agent in einer Gruppe erfordert die Klasse Hochverfügbarkeit, die eine Lizenz für Agent-Gruppierung für HA erfordert.
Lösung:
- Bearbeiten Sie auf der Seite Agents die Agent-Gruppe und ändern Sie die Agent-Gruppenklasse in Hochverfügbarkeit.
- Bestätigen Sie, dass Ihre Organisation eine Lizenz für Agent-Gruppierung für HA hat. Lizenzdetails finden Sie auf der Seite Dashboard der Management Console.
- Wenn Sie eine Lizenz hinzufügen müssen, wenden Sie sich an Ihren Jitterbit-Vertreter.

Das Hinzufügen eines privaten Agenten schlägt mit einem Fehler zur maximalen Agentenbegrenzung fehl

Symptom: In der Schublade Agent group details einer Agent-Gruppe ist das Symbol Create verfügbar, aber das Speichern des neuen privaten Agenten schlägt mit einem Fehler zur maximalen Agentenbegrenzung fehl. Zwei separate Limits führen zu diesem Fehler, jedes mit eigenem Fehlertext.
Mögliche Ursachen:
- Die Agent-Gruppe ist voll. Die Gruppe hat die maximale Anzahl von Agenten erreicht, die standardmäßig 10 beträgt:
```
You have reached the maximum agents limit allowed for your organization. Contact your Jitterbit representative to increase the limit.
```
  Dieses Limit gilt für Gruppen mit der Agent-Gruppenklasse High Availability. Eine Standard-Gruppe erlaubt nur einen Agent, wie unter Das Hinzufügen eines zweiten Agenten zu einer Standard-Agent-Gruppe ist nicht zulässig beschrieben.
- Das Limit für private Agenten der Organisation ist erreicht. Alle privaten Agenten, die der Abonnementplan der Organisation zulässt, wurden hinzugefügt:
```
HttpErrorResponse: You've reached the maximum number of agent(s) configured for your Jitterbit organization. Please directly contact the Jitterbit Customer Success Manager assigned to you or send an email to success@jitterbit.com to review your needs and configure your organization appropriately.
```
  Dieses Limit gilt unabhängig davon, zu welcher Agent-Gruppe der Agent hinzugefügt wird, und ein Agent zählt dazu, sobald er hinzugefügt wird, auch wenn er nie registriert wird.
Lösung:
- Um zu bestätigen, welches Limit zutrifft, vergleichen Sie die Agentenzahl der Agent-Gruppe mit ihrem Maximum auf der Seite Agents, und die hinzugefügten privaten Agenten der Organisation mit ihrer lizenzierten Gesamtzahl auf der Seite Management Console Dashboard.
- Wenn die Agent-Gruppe voll ist, fügen Sie den Agent zu einer anderen Agent-Gruppe hinzu, oder löschen Sie einen nicht mehr verwendeten Agent aus der Gruppe.
- Um eines der beiden Limits zu erhöhen, kontaktieren Sie Ihren Jitterbit-Vertreter oder den Customer Success Manager.

Privater Agent kann nicht gelöscht werden

Symptom: Der Versuch, einen privaten Agenten zu löschen, schlägt fehl.
Ursache: Ein Agent kann nur gelöscht werden, wenn sein Status einer der folgenden ist: Starting, Stopped, Unregistered oder Unknown. Agenten im Status Running oder Stopping können nicht gelöscht werden.
Lösung:
1. Überprüfen Sie auf der Seite Agenten den aktuellen Status des Agenten.
2. Beenden Sie den Agenten und warten Sie, bis sich sein Status ändert, bevor Sie versuchen, ihn zu löschen.

Private Agentgruppe kann nicht gelöscht werden

Symptom: Der Versuch, eine private Agentgruppe zu löschen, schlägt fehl.
Ursache: Eine private Agentgruppe kann nicht gelöscht werden, während sie einer Umgebung zugeordnet ist.
Lösung:
1. Bearbeiten Sie auf der Seite Agenten die Agentgruppe und entfernen Sie alle Umgebungszuordnungen.
2. Versuchen Sie erneut zu löschen.

Auto-Connector-Update deaktivieren wird durch Agent-Aktionen umgangen

Symptom: Connectors werden auf privaten Agenten aktualisiert, obwohl Disable Auto Connector Update in den Organisationsrichtlinien aktiviert ist.
Ursache: Die Organisationsrichtlinie Disable Auto Connector Update verhindert, dass private Agenten bereits installierte Connectors automatisch auf neuere Versionen aktualisieren (beispielsweise lädt die Schaltfläche Test einer Verbindung nicht mehr die neueste Connector-Version herunter). Sie behält Connectors in jeder Situation nicht auf einer festen Version. Connectors werden trotzdem heruntergeladen oder aktualisiert, unabhängig von der Richtlinie, wenn eines der folgenden Ereignisse auftritt:
- Action > Update connectors ist für die Agentgruppe auf der Management Console Agenten-Seite ausgewählt. Diese Aktion überschreibt die Richtlinie explizit.
- Ein privater Agent wird neu installiert oder seine PostgreSQL-Datenbank wird zurückgesetzt (auch durch ein Upgrade, das die gebündelte PostgreSQL-Datenbank aktualisiert, z. B. durch ein Upgrade von Agent 11.x zu Agent 12.x). Der Agent hat dann keinen gespeicherten Datensatz zuvor installierter Connector-Versionen, daher lädt er die aktuellen Connectors aus der Cloud herunter.
- Ein privater Agent wird von Version 11.48 oder früher auf Version 11.49 oder später aktualisiert, was ein einmaliges erforderliches Connector-Update beinhaltet. Sie werden während des Upgrades benachrichtigt, dass Connectors aktualisiert werden. Siehe die Upgrade-Hinweise für Windows und Linux.
Lösung: Es ist keine Aktion erforderlich. Die Richtlinie Disable Auto Connector Update verhindert automatische Connector-Updates während des normalen Betriebs, gilt aber nicht für die oben genannten Aktionen und Ereignisse.

Agent zeigt Unknown oder Stopped an, nachdem eine Agent-Gruppe über Betriebssysteme hinweg wiederverwendet wurde

Symptom: Nach der Migration privater Agents auf ein anderes Betriebssystem (z. B. Windows zu Linux) bei Wiederverwendung derselben Agent-Gruppe zeigen die migrierten Agents auf der Registerkarte Privat der Seite Agents der Management Console zeitweise als Unbekannt oder Beendet an, obwohl jitterbit status zeigt, dass die Services ausgeführt werden und Operationen normal ausgeführt werden.
Mögliche Ursache: Die Wiederverwendung einer Agent-Gruppe aus dem vorherigen Betriebssystem kann Metadaten hinterlassen, die die Statusberichterstellung für die neuen Agents beeinträchtigen. Der Effekt ist typischerweise kosmetisch: Services und Operationen werden weiterhin normal ausgeführt.
Lösung: Erstellen Sie stattdessen eine neue, saubere Agent-Gruppe für die migrierten Agents, anstatt die Gruppe aus dem vorherigen Betriebssystem wiederzuverwenden, und registrieren Sie die Agents dort.

Operationen verzögert oder in der Warteschlange nach Projektbereitstellung

Symptom: Nach der Bereitstellung eines Projekts in Studio starten ausgelöste Operationen nicht sofort, oder es entsteht kurzzeitig ein Rückstau von Operationen in der Warteschlange.
Ursache: Die Umgebung ist gesperrt, während der Agent das bereitgestellte Projekt synchronisiert. Während dieses Zeitfensters können keine Operationen ausgeführt werden.
Lösung:
1. Um zu messen, wie lange Synchronisierungssperren andauern, durchsuchen Sie jitterbit-agent.log nach environment-deploy. Jeder Logeintrag enthält die Umgebungs-ID und die Synchronisierungsdauer in Millisekunden.
2. Konsistent lange Synchronisierungszeiten deuten auf ein großes Projekt oder langsame Konnektivität zu Harmony hin. Informationen zum Reduzieren von Synchronisierungszeiten finden Sie unter Leistungsoptimierung der Umgebungssynchronisierung.
3. Wenn Synchronisierungsdauern konsistent übermäßig lang sind (mehr als einige Minuten), wenden Sie sich an den Jitterbit-Support.

Agent zeigt sich als nicht leistungsfähig

Symptom: An die Agent-Gruppe übermittelte Operationen werden wiederholt oder verzögert, anstatt sofort ausgeführt zu werden. ProcessEngine.log enthält wiederholte Meldungen wie:
```
Agent (Id: ...) is incapable to process this message. Message will be auto-retried.
```
```
Capability status changed from true to false
```
Mögliche Ursachen:
- Alle Worker-Threads im Process Engine des Agents sind bereits in Verwendung, daher kann der Agent keine weitere Operation akzeptieren, bis ein Thread freigegeben wird. Die Pool-Größe wird durch MaxNumberOfWorkerThreads im Abschnitt [ProcessEngine] von jitterbit.conf festgelegt.
- Eine optionale Leistungsmetrik ist aktiviert und hat ihren Schwellenwert erreicht. CPU-Auslastung, Speicherauslastung und Apache-Thread-Auslastung können jeweils zum Leistungsstatus beitragen, aber alle drei sind standardmäßig deaktiviert und gelten nur, wenn sie im Abschnitt [AgentCapability] von jitterbit.conf aktiviert werden. Die Speicherauslastung wird nur auf Windows-Agents erfasst, daher trägt sie nicht zum Leistungsstatus auf einem Linux-Agent bei, auch wenn die Speichereinstellungen aktiviert sind. Apache bedient nur API-Anfragen, daher ist die Apache-Thread-Auslastung nur auf einem Agent relevant, der APIs verarbeitet.
- Ein einzelner Agent in der Gruppe verarbeitet mehr Last, als er bewältigen kann, während andere Agents in der Gruppe untätig sind oder unterausgelastet sind.
Lösung: Überprüfen Sie ProcessEngine.log auf lange Sequenzen von Leistungsstatusänderungen, um zu bestätigen, dass der Agent zwischen leistungsfähigen und nicht leistungsfähigen Zuständen wechselt, und untersuchen Sie dann Folgendes:
- Wenn viele Operationen konsistent gleichzeitig ausgeführt werden, überprüfen Sie MaxNumberOfWorkerThreads im Abschnitt [ProcessEngine] von jitterbit.conf. Eine Erhöhung dieses Werts ermöglicht mehr gleichzeitige Operationen, erhöht aber auch die CPU- und Speicheranforderungen. Legen Sie ihn daher konservativ fest.
- Bestimmen Sie, welche Leistungsmetriken im Abschnitt [AgentCapability] aktiviert sind. Wenn keine aktiviert sind, sind CPU- und Speicherlast nicht das, was den Leistungsstatus des Agents geändert hat, und die Thread-Verfügbarkeit ist der wahrscheinlichere Auslöser. Wenn CPU- oder Speicherauslastung aktiviert ist, überprüfen Sie diese vor den Thread-Metriken: Wenn einer dieser Werte seinen Schwellenwert überschreitet, wird der Agent unabhängig von der Thread-Verfügbarkeit nicht leistungsfähig. Auf einem Linux-Agent ist die CPU-Auslastung die einzige Systemressourcen-Metrik, die gilt.
- Überprüfen Sie CPU- und Speicherauslastung auf dem Agent-Host zum Zeitpunkt des Problems. Wenn native Observability aktiviert ist, überprüfen Sie die Diagramme System Resource Capability, Apache Threads und Tomcat Threads auf der Registerkarte Metriken der Seite Agents der Management Console. Verwenden Sie bei der Überprüfung von Diagrammen für eine Multi-Agent-Gruppe Spitzen- oder Maximalwerte anstelle von Durchschnittswerten, da Durchschnittswerte einen einzelnen überbelasteten Agent maskieren können, während der Rest der Gruppe gesund aussieht.
- Wenn die Agent-Gruppe mehrere Agents enthält, überprüfen Sie ProcessEngine.log auf allen Agents in der Gruppe, um zu bestimmen, ob alle Agents gleichzeitig nicht leistungsfähig waren, als die Operation fehlgeschlagen ist. Wenn nur ein Agent nicht leistungsfähig war, sollte die Operation an einen leistungsfähigen Agent weitergeleitet werden. Überprüfen Sie, ob der Lastenausgleich für die Gruppe korrekt konfiguriert ist.
- Wenn Ressourcenlimits konsistent erreicht werden, fügen Sie Agents zur Gruppe hinzu, um die Last zu verteilen.
- Wenn Speicherdruck der Auslöser ist, siehe Java heap space: OutOfMemoryError.

Transformation fehlgeschlagen: „Datei im lokalen Dateispeicher nicht gefunden"

Symptom: Ein Vorgang schlägt während einer Transformation mit einer Fehlermeldung fehl, die angibt, dass eine Datei im lokalen Dateispeicher des Agenten fehlt:

Failed to find file in the local file store. Will attempt a re-sync the files in the environment the next time the operation runs.
There is no file in the local file store. File_ID = ...
Failed to find file in the local file store. TransformID: ..., FileID: ..., Error: There is no file in the local file store. File_ID = ... [CODE:10808]

Mögliche Ursache: Die Bereitstellungsmetadaten einer Datei wurden nicht vollständig von der Harmony Cloud zum Agenten synchronisiert, sodass der Agent die Datei zur Laufzeit nicht finden kann. Dies ist normalerweise vorübergehend (z. B. eine kurze Synchronisierungsunterbrechung), kann aber auch nach dem Exportieren und erneuten Importieren eines Projekts zwischen Umgebungen auftreten.
Lösung:
1. Führen Sie den Vorgang erneut aus. Bei Agent-Version 11.38 und später behebt der Agent diesen Zustand selbst: Der Fehler tritt pro Datei-ID auf einem bestimmten Agenten höchstens einmal auf, und der Agent stellt die fehlenden Metadaten bei der nächsten Umgebungssynchronisierung wieder her (nächster Vorgangslauf oder Bereitstellung). In den meisten Fällen wird das Problem durch erneutes Ausführen des Vorgangs behoben.
2. Wenn dieselbe Datei bei mehreren Ausführungen auf einem aktuellen Agenten weiterhin fehlschlägt, liegt wahrscheinlich ein tieferes Problem vor, z. B. eine Umgebung, die ihre Bereitstellungsdatensatzgrenze erreicht hat, oder eine versionsspezifische Regression. Kontaktieren Sie den Jitterbit-Support mit dem Namen des fehlgeschlagenen Vorgangs und der TransformID sowie der File_ID aus der Fehlermeldung.

Fehlgeschlagene Windows-Installation wiederherstellen

Symptom: Die Installation oder das Upgrade eines privaten Windows-Agents schlägt fehl oder hinterlässt den Agent in einem fehlerhaften Zustand.
Lösung: Den Agent vollständig deinstallieren und dann die Agent-Software neu installieren.

Connector nicht zum Agent heruntergeladen

Symptom: Operationen schlagen mit Fehlern fehl, die darauf hindeuten, dass ein Connector auf dem Agent nicht verfügbar oder nicht vorhanden ist. Dies tritt typischerweise nach der Veröffentlichung einer neuen Connector-Version oder nach der Bereitstellung eines Projekts auf, das einen Connector verwendet, den der Agent noch nicht heruntergeladen hat:
```
This connector was not found on the Jitterbit Agent. Please be patient with us while the connector is downloaded across the agents. This may take up to several minutes
```
Mögliche Ursachen:
- Die vom Projekt erforderliche Connector-Version wurde noch nicht aus der Cloud auf den Agent heruntergeladen. Dies ist oft vorübergehend und wird innerhalb weniger Minuten behoben.
- Bei privaten Agents: Der Agent kann die Harmony Cloud nicht erreichen, um den Connector herunterzuladen.
Lösung:
- Öffnen Sie in Studio die betroffene Verbindung und klicken Sie auf Test. Dies veranlasst den Agent, die neueste Connector-Version aus der Cloud herunterzuladen.
- Wenn der Connector immer noch nicht heruntergeladen wird, überprüfen Sie, ob die Organisationsrichtlinie Disable Auto Connector Update aktiviert ist. Wenn dies der Fall ist, lädt die Schaltfläche Test keine Connector-Versionen herunter. Siehe Agent Management.
- Um den Connector herunterzuladen, ohne die Richtlinie zu ändern, gehen Sie zur Seite Agents in der Management Console, wählen Sie die Agent-Gruppe aus und wählen Sie Action > Update connectors. Dies erzwingt ein Connector-Update in der Gruppe und wird durch die Richtlinie Disable Auto Connector Update nicht beeinflusst.
- Überprüfen Sie bei privaten Agents, ob der Agent-Host die Harmony Cloud erreichen kann. Siehe Agent offline oder nicht erreichbar.

Hinweis

Die Microsoft Excel- und Excel v2-Connectors können diesen Fehler speziell auf privaten Agents der Version 12.x nicht laden. Dies ist ein bekanntes Problem mit einer separaten Problemumgehung. Siehe Excel- und Excel v2-Connectors können nicht geladen werden in den bekannten Problemen für private Agents.

Agent-Installation kann sich nicht über einen Unternehmens-Proxy registrieren

Symptom: Eine Installation eines privaten Agents auf einem Host hinter einem Unternehmens-Proxy schlägt während des anfänglichen Registrierungsschritts fehl, und das Installationsprogramm meldet, dass es die Harmony Cloud nicht erreichen konnte:
```
Could not connect to Jitterbit Harmony cloud
```
Mögliche Ursachen:
- Der Proxy blockiert die Verbindung des Agents zur Harmony Cloud während der Registrierung.
- Der Proxy erfordert eine Authentifizierung, die die Proxy-Konfiguration des Agents nicht bereitstellt. Private Agents unterstützen Proxy-Authentifizierung, einschließlich einer NTLM-Domäne. Siehe Proxy-Server für private Jitterbit-Agents.
Lösung:
1. Konfigurieren Sie den Proxy während der Agent-Einrichtung, damit das Installationsprogramm die Harmony Cloud über ihn erreichen kann. Geben Sie dabei die Proxy-Anmeldedaten (und die NTLM-Domäne, falls der Proxy diese erfordert) an. Siehe Proxy während der Agent-Einrichtung konfigurieren.
2. Wenn die Registrierung über den Proxy immer noch fehlschlägt, bitten Sie Ihr Netzwerk-Team, die Jitterbit-Domänen und IP-Adressen durch den Proxy zuzulassen oder den Proxy für diese zu umgehen. Die regionsspezifischen Harmony-URLs sind in Allowlist-Informationen dokumentiert.
3. Führen Sie das Installationsprogramm erneut aus, sobald der Proxy konfiguriert ist oder der Host die Harmony Cloud erreichen kann.

Neustartschleife des Agent-Dienstes

Symptom: Die Services des Agenten stürzen wiederholt ab und werden neu gestartet. Tomcat oder die Process Engine stoppt und startet in einer Schleife, ohne online zu bleiben, und Operationen schlagen mit Fehlern wie Tomcat service is not running fehl. Wenn jitterbit status alle Services auf dem Host als fehlerfrei anzeigt, aber der angezeigte Status nur zwischen Running, Unknown und Stopped flattert, ist dies ein Konnektivitätsproblem und keine Absturzschleife. Siehe Agent offline oder nicht erreichbar.
Mögliche Ursachen:
- Ein verwaister Jitterbit-Prozess aus einem vorherigen Lauf (ein Tomcat-, Process Engine- oder Scheduler-Prozess) hält noch den Service-Port, sodass jeder Neustart mit java.net.BindException: Address already in use fehlschlägt und der Agent zyklisch läuft.
- Der Host läuft aus Speicher aus und das Betriebssystem beendet den Prozess. Dies kann vorkommen, wenn der Host zu wenig Speicher für die Workload hat oder wenn das Speicherlimit eines Containers zu niedrig gesetzt ist.
- Der Agent-Host hat wenig Speicherplatz, oder die interne PostgreSQL-Datenbank ist groß genug geworden, um beim Start fehlzuschlagen.
- Die Process Engine stürzt unter anhaltender Last wiederholt ab.
Lösung:
- Bestätigen Sie, dass es sich um eine echte Crash-Schleife handelt. Überprüfen Sie die Tomcat-Protokolle in JITTERBIT_HOME/tomcat/logs/ und ProcessEngine.log auf die bei jedem Neustart protokollierte Ausnahme. Ein java.net.BindException: Address already in use deutet darauf hin, dass ein verwaister Prozess den Port belegt.
- Beenden Sie den Agent und alle verbleibenden Jitterbit-Prozesse, bevor Sie ihn neu starten. Wenn der Agent beendet ist, suchen Sie nach verwaisten Prozessen: Führen Sie unter Linux ps aux | grep -E 'tomcat|jitterbit' aus und kill alle verbleibenden Prozess-IDs; unter Windows beenden Sie alle verwaisten Jitterbit- oder Tomcat-Prozesse im Task-Manager. Starten Sie den Agent neu, sobald keine mehr vorhanden sind.
- Überprüfen Sie auf Speichererschöpfungsereignisse. Unter Windows überprüfen Sie die Protokolle Anwendung und System in der Ereignisanzeige; unter Linux führen Sie journalctl -u jitterbit aus oder überprüfen Sie /var/log/syslog auf OOM-Killer-Ereignisse. Wenn dem Host der Speicher ausgeht, erhöhen Sie den verfügbaren Speicher (oder das Speicherlimit des Containers). Siehe Java-Heap-Speicher: OutOfMemoryError.
- Überprüfen Sie den Festplattenspeicher und die interne Datenbank. Eine volle Festplatte oder eine überladene PostgreSQL-Datenbank können dazu führen, dass die Dienste bei jedem Neustart abstürzen. Siehe Festplattenspeicher und Protokollakkumulation.
- Wenn die Protokolle zeigen, dass die Process Engine bei einem bestimmten Vorgang abstürzt, kontaktieren Sie den Jitterbit-Support mit den Vorgangsdetails und den Agent-Protokollen.
- Wenn die native Observability aktiviert ist, öffnen Sie die Registerkarte Metriken der Seite Agents der Management Console und überprüfen Sie die Service-Diagramme Tomcat und Process Engine, um zu ermitteln, wann die Dienste ausfallen begannen.

Operationen überschreiten Timeout oder ignorieren Timeout-Einstellungen

Symptom: Vorgänge werden unbegrenzt oder länger als erwartet ausgeführt. Bei API-gesteuerten Vorgängen scheinen die in Studio konfigurierten Timeout-Einstellungen keine Auswirkung zu haben, und Vorgänge können im Status Wird ausgeführt steckenbleiben.
Mögliche Ursachen:
- Standardmäßig ignorieren von API Manager-APIs ausgelöste Vorgänge die Timeout-Einstellungen für Studio-Vorgänge. Die Einstellung EnableAPITimeout in jitterbit.conf muss explizit aktiviert werden, damit API-Vorgänge Timeout-Werte berücksichtigen.
- Es ist keine maximale Laufzeit für Vorgänge festgelegt, daher werden Vorgänge ohne zeitliche Obergrenze ausgeführt.
Lösung:
1. Um Timeout-Einstellungen für API-gesteuerte Vorgänge zu erzwingen, setzen Sie EnableAPITimeout=true im Abschnitt [Settings] von jitterbit.conf.
2. Um die Gesamtlaufzeit eines Vorgangs zu begrenzen, setzen Sie MaxOperationRuntimeSeconds im Abschnitt [ProcessEngine] von jitterbit.conf. Dies erfordert, dass RunOperationsInSeparateProcess auf true (Standard) gesetzt ist.
3. Starten Sie die Agent-Dienste nach Änderungen an jitterbit.conf neu.

Agent-Durchsatz unverändert nach Erhöhung von `max.concurrent.requests`

Symptom: Nach Erhöhung von max.concurrent.requests in jitterbit-agent-config.properties verbessert sich der Durchsatz des Agents nicht.
Mögliche Ursachen:
- Nur max.concurrent.requests wurde geändert. Der Agent-Durchsatz hängt auch von den Tomcat- und Apache-Thread-Pools sowie den HTTP-Verbindungs-Pools ab. Eine Erhöhung dieser einen Einstellung ohne gleichzeitige Skalierung der anderen bringt keinen Gewinn.
- Der Agent-Host verfügt nicht über genug CPU oder Speicher für die zusätzliche Parallelität, oder der Agent wechselt unter Last in einen unfähigen Zustand.
Lösung:
- Folgen Sie dem vollständigen Tuning-Verfahren, anstatt nur max.concurrent.requests zu ändern, und skalieren Sie die zugehörigen Thread-Pool- und Verbindungs-Pool-Einstellungen zusammen. Siehe Agent-Leistung und Tuning.
- Bestätigen Sie, dass der Agent-Host ausreichend CPU- und Speicherreserven für die höhere Parallelität hat. Wenn der Agent unter Last abstürzt oder in einen unfähigen Zustand wechselt, siehe Agent-Dienst-Neustartschleife und Java-Heap-Speicher: OutOfMemoryError.

XML-Transformationsverlangsamung nach Upgrade auf Agent 11.45 oder später

Symptom: Nach dem Upgrade eines privaten Agenten auf Version 11.45 oder später dauert eine Transformation, die über ein großes Array iteriert, länger als in Version 11.44. Die Verlangsamung tritt speziell bei Zuordnungspfaden auf, die die #-Notation verwenden, um über jedes Element eines großen Arrays zu iterieren (ungefähr mehrere hundert bis einige tausend Datensätze). Transformationen, die nicht über große Arrays iterieren, sind nicht betroffen.
Mögliche Ursache: Die vom Agent verwendete XML-Parsing-Bibliothek wurde in Version 11.45 aktualisiert, und die aktualisierte Version analysiert große XML-Daten langsamer. Dies wirkt sich auf Transformationen aus, die über ein großes Array iterieren, da die Zuordnung die analysierten Daten wiederholt durchläuft.
Lösung:
- Überprüfen Sie die Zuordnungspfade der Transformation auf die #-Notation. Wenn ein Pfad # verwendet, um über ein Array zu iterieren, aber nur das erste Element benötigt wird, entfernen Sie # und stellen Sie erneut bereit. Das Entfernen von # ordnet nur das erste Element zu, daher wenden Sie dies nur an, wenn eine Iteration über das gesamte Array nicht erforderlich ist.
- Wenn die Zuordnung über das gesamte Array iterieren muss, verarbeiten Sie weniger Datensätze pro Durchlauf, indem Sie einen großen Datensatz in kleinere Batches aufteilen, sodass jede Transformation ein kleineres Array durchläuft.

JVM-Mini-Dump-Dateien füllen die Festplatte des Agents

Symptom: Der Agent generiert kontinuierlich große JVM-Crash-Dateien (.dmp- und .mdmp-Mini-Dumps sowie hs_err_pid*.log-Dateien) unter <JITTERBIT_HOME>/Tomcat/temp (oder bei älteren Builds direkt im Tomcat-Ordner) und verbraucht damit den Festplattenspeicher des Agent-Hosts. Dies wirkt sich auf Windows-Private-Agenten in Versionen vor 11.49 aus.
Mögliche Ursachen:
- Der AgentStats-Festplattenstatistik-Collector des Agenten stürzt die JVM ab, während Festplattenmetriken erfasst werden. Dies wirkt sich auf Agenten in Versionen vor 11.49 aus.
- Bei Agenten mit Version 11.47 oder 11.48 kann ein separater Crash in der Process Engine die gleichen Crash-Dateien erzeugen.
Lösung: Aktualisieren Sie den privaten Agenten auf Version 11.49 oder später, was beide Ursachen behebt.

Wenn ein sofortiges Upgrade nicht möglich ist und die Crash-Dateien aus der Festplattenstatistik-Erfassung stammen, können Sie diese Erfassung als Workaround deaktivieren (das Flag DiskStatsEnabled ist ab Agent 11.44.1 verfügbar):
1. Fügen Sie in jitterbit.conf Folgendes hinzu:
```
[AgentStats]
DiskStatsEnabled=false
```
2. Starten Sie die Agent-Services neu. Vorhandene Crash-Dateien können dann sicher gelöscht werden, um Festplattenspeicher freizugeben.
3. Wenn Sie Version 11.47 oder 11.48 verwenden und die Crash-Dateien weiterhin auftreten, aktualisieren Sie auf 11.49 oder kontaktieren Sie den Jitterbit-Support für einen Workaround.

Gebündelte PostgreSQL unter Linux verwendet MD5 statt SCRAM-SHA-256

Symptom: Sie möchten die Authentifizierungsmethode der gebündelten PostgreSQL auf einem privaten Linux-Agent von MD5 zu SCRAM-SHA-256 ändern, aber der Agent verwendet weiterhin MD5.
Mögliche Ursachen:
- MD5 ist die Standard-Passwortverschlüsselung für die gebündelte PostgreSQL auf privaten Linux-Agenten. SCRAM-SHA-256 war nur in den Versionen 12.6 und 12.7 Standard; Version 12.8 hat den Standard auf MD5 zurückgesetzt. Wenn Sie einen Linux-Agent von 12.6 oder 12.7 aktualisieren, fordert das Installationsprogramm Sie auf, die Verschlüsselung auf MD5 zurückzusetzen oder SCRAM-SHA-256 beizubehalten; siehe Linux-Agent aktualisieren.
- Das alleinige Bearbeiten von pg_hba.conf und postgresql.conf führt nicht zum Wechsel. PgBouncer muss auch mit dem SCRAM-Verifier-Hash neu konfiguriert werden, sonst startet der Agent nicht.
Lösung: Um einen privaten Linux-Agent zu SCRAM-SHA-256 zu wechseln, folgen Sie dem SCRAM auf PostgreSQL-Leitfaden. SCRAM-SHA-256 ist eine stärkere Authentifizierungsmethode, während MD5 performanter ist, daher ist der Wechsel eine bewusste, mehrstufige Änderung: Der Leitfaden konfiguriert die gebündelte PostgreSQL neu, aktualisiert die Benutzerkennwörter und konfiguriert PgBouncer mit dem neuen Hash neu. Das Neukonfigurieren der gebündelten Instanz ist die unterstützte Methode, um SCRAM zu aktivieren. Ersetzen Sie die gebündelte Instanz nicht durch Ihren eigenen PostgreSQL-Server, um SCRAM zu erhalten: Agenten, die eine andere PostgreSQL-Instanz als die gebündelte verwenden, werden nicht unterstützt.

Salesforce Sandbox-Verbindung schlägt mit Zertifikatkonflikt fehl

Symptom: Eine Private-Agent-Verbindung zu einem Endpunkt, der Server Name Indication (SNI) erfordert, schlägt mit einer Zertifikat-Nichtübereinstimmung fehl, während die gleiche Verbindung von einer Cloud-Agent-Gruppe oder von einem direkten openssl- oder curl-Test auf dem Agent-Host erfolgreich ist. Der häufigste Fall ist eine Salesforce-Sandbox-URL, die auf .sandbox.my.salesforce.com endet:
```
Certificate for <your-domain.sandbox.my.salesforce.com> doesn't match any of the subject alternative names: ...
```
Andere betroffene Endpunkte sind Hosts, die eine einzelne IP hinter Virtual Hosting teilen.
Ursache: Der TLS-Handshake enthält nicht die SNI-Erweiterung, daher gibt der Server ein Standardzertifikat zurück, anstatt das für den angeforderten Host. Für eine Salesforce-Sandbox gibt der Load Balancer das Produktionszertifikat zurück, dessen Namen *.sandbox.my.salesforce.com nicht abdecken. SNI wird standardmäßig gesendet, daher unterdrückt oder entfernt etwas SNI, wenn es fehlt.

Lösung:

Bestätigen Sie, dass SNI die Ursache ist. Vergleichen Sie vom Agent-Host aus das zurückgegebene Zertifikat mit und ohne SNI:

openssl s_client -connect HOST:443 -servername HOST   # Zertifikat, wenn SNI gesendet wird
openssl s_client -connect HOST:443                    # Zertifikat, wenn SNI weggelassen wird

Wenn der erste das richtige Zertifikat zurückgibt und der zweite das nicht übereinstimmende, ist SNI die Ursache.

Prüfen Sie, ob SNI in den Java-Optionen des Agenten explizit deaktiviert ist, und entfernen Sie es gegebenenfalls. Öffnen Sie unter Windows den Registry Editor unter HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\Jitterbit Tomcat Server\Parameters\Java und bearbeiten Sie den Wert Options. Unter Linux prüfen Sie JAVA_OPTS in /etc/sysconfig/jitterbit. Entfernen Sie -Djsse.enableSNIExtension=false, falls vorhanden (diese Einstellung unterdrückt SNI). Starten Sie die Agent-Services neu.
Falls SNI danach immer noch fehlt, entfernt ein Netzwerkgerät, ein Proxy oder ein VM-Netzwerk-Stack zwischen dem Agent und dem Endpunkt die SNI-Erweiterung. Ihr Netzwerk-Team muss die SNI-Erweiterung zulassen.

Wenn die Verbindung auch von einer Cloud-Agent-Gruppe aus fehlschlägt, ist SNI nicht die Ursache. Das Zertifikat des Servers listet den Host möglicherweise nicht in seinen Subject Alternative Names auf. Fügen Sie für Salesforce die Sandbox-MyDomain-URL zum Salesforce-Zertifikat hinzu, oder siehe Certificate Subject Alternative Name (SAN) mismatch.

SSH: SFTP-Verbindung schlägt aufgrund eines falschen Dateipfads fehl

Symptom: SFTP-Operationen schlagen auf einem Windows-Agent fehl, obwohl die SSH-Schlüsseldateien korrekt installiert sind.
Ursache: Die Pfadwerte PrivateKeyFile und PublicKeyFile im Abschnitt [SSH] von jitterbit.conf verwenden Windows-Backslash-Trennzeichen (\), die nicht unterstützt werden.
Lösung: Verwenden Sie Schrägstriche in allen SSH-Schlüsseldateipfaden in jitterbit.conf, auch unter Windows (z. B. C:/jitterbit/keys/id_rsa). Siehe [SSH].

SFTP SSH-Einstellungen fehlen oder befinden sich im falschen `jitterbit.conf`-Bereich

Symptom: SFTP-Operationen, die einen privaten Schlüssel zur Authentifizierung verwenden, schlagen nach einem Agent-Upgrade oder -Neustart mit einem Fehler für eine leere private Schlüsseldatei fehl. SSH-Schlüssel-Einstellungen, die zur lokalen jitterbit.conf hinzugefügt wurden, funktionieren möglicherweise auch nach dem Neustart des Agenten nicht mehr.
```
CURL_DEBUG_TEXT: Using SSH private key file ''
CURL_DEBUG_TEXT: SSH public key authentication failed: Unable to extract public key from private key file
```
Mögliche Ursachen:
- Die Remote-Agent-Konfiguration ist aktiviert (standardmäßig der Fall), daher haben Einstellungen, die über die Registerkarte Jitterbit Configuration der Management Console verwaltet werden, Vorrang. SSH-Schlüssel-Einstellungen, die nur zur lokalen jitterbit.conf hinzugefügt wurden, funktionieren möglicherweise nicht oder werden nach dem Neustart des Agenten nicht beibehalten.
- Die SSH-Schlüssel-Einstellungen (PrivateKeyFile, PrivateKeyPassphrase, PublicKeyFile) befinden sich im falschen Abschnitt. Neuere Agent-Versionen analysieren streng und ignorieren SSH-Einstellungen, die außerhalb des Abschnitts [SSH] platziert sind (z. B. unter [SSL]).
Lösung:
1. Wenn die Remote-Konfiguration aktiviert ist, fügen Sie die SSH-Schlüssel-Einstellungen dort hinzu: Öffnen Sie die Schublade Agent group details für die Agent-Gruppe, wählen Sie die Registerkarte Jitterbit Configuration aus, und fügen Sie sie unter dem Abschnitt SSH hinzu. Siehe Jitterbit configuration.
2. Wenn die lokale jitterbit.conf die Konfigurationsquelle ist, bestätigen Sie, dass die SSH-Schlüssel-Einstellungen unter [SSH] platziert sind (nicht [SSL]).
3. Starten Sie die Agent-Services neu.
4. Weitere Informationen zur Fehlerbehebung bei SFTP-Schlüsselauthentifizierung (Passwortfelder, Passphrase, Schlüsselformat) finden Sie unter SFTP „Login denied. Authentication failure." bei Verwendung von SSH-Schlüsseln.

SFTP-Authentifizierungsfehler bei einem bestimmten Server (cURL Cipher-Konflikt)

Symptom: Eine SFTP-Verbindung mit SSH-Schlüsselauthentifizierung schlägt auf einem privaten Agent mit Login denied. Authentication failure. fehl, aber andere SFTP-Verbindungen vom gleichen Agent (mit dem gleichen Schlüssel) sind erfolgreich, und die Verbindung zum fehlgeschlagenen Server über die Befehlszeile des Betriebssystems ist ebenfalls erfolgreich.
```
Failed to get ftp directory list for url sftp://... Login denied. Authentication failure.
```
Ursache: Der SFTP-Server erfordert neuere SSH-Cipher, Key-Exchange- oder Host-Key-Algorithmen, die die cURL-Bibliothek in älteren Agent-Versionen nicht unterstützt. Server, die die älteren Algorithmen noch akzeptieren, funktionieren weiterhin, weshalb der gleiche Schlüssel bei anderen Hosts und über die Befehlszeile des Betriebssystems erfolgreich ist.
Lösung: Aktualisieren Sie den privaten Agent auf Version 11.37 oder später, die eine aktualisierte cURL-Bibliothek mit Unterstützung für aktuelle SSH-Cipher, Key-Exchange- und Host-Key-Algorithmen enthält.

HTTPS-Proxy: Basis-Authentifizierung über Proxy-Tunnel schlägt fehl

Symptom: Wenn der Agent sich über einen HTTPS-Proxy verbindet, der Basis-Authentifizierung erfordert, schlagen Verbindungen durch den Proxy-Tunnel mit einem Authentifizierungsfehler fehl.
Ursache: Moderne JDK-Versionen deaktivieren die Basis-Authentifizierung während HTTPS-Proxy-Tunneling standardmäßig. Die JVM-Eigenschaft jdk.http.auth.tunneling.disabledSchemes blockiert die Basis-Authentifizierung, sofern sie nicht explizit gelöscht wird.
Lösung: Fügen Sie -Djdk.http.auth.tunneling.disabledSchemes="" zu CATALINA_OPTS hinzu, bevor Sie Tomcat starten. Schritt-für-Schritt-Anweisungen für Windows, Linux und Docker finden Sie unter Basis-Authentifizierung während HTTPS-Proxy-Tunneling zulassen.

Private Agents in eingeschränkten Netzwerken: Nur ausgehende Verbindung

Symptom: Bei der Bereitstellung privater Agents hinter einer strikten Unternehmens-Firewall oder in einer eingeschränkten Umgebung (z. B. OpenShift) zusammen mit einem privaten API-Gateway fragen Netzwerk-Teams manchmal, welche eingehenden Ports auf dem Agent für Harmony oder das Gateway geöffnet werden müssen, um es zu erreichen.
Ursache: Private Agents erfordern keine geöffneten eingehenden Ports, da die Agent-Konnektivität wie folgt funktioniert:
- Private Agents akzeptieren keine eingehenden Verbindungen von Harmony oder von einem privaten API-Gateway. Der Agent stellt eine ausgehende WebSocket-Verbindung zu Harmony über HTTPS (Port 443) her. Der gesamte Datenverkehr von Harmony und vom Gateway zum Agent wird über diese vorher etablierte Verbindung zurückgeleitet.
- Ein privates API-Gateway sendet API-Anfragen an Harmony, und Harmony leitet die Anfrage über die vorhandene ausgehende WebSocket zum entsprechenden Agent weiter. Der Agent leitet die API-Antwort-Nutzlast zurück an das private API-Gateway, daher muss der Agent auch in der Lage sein, das Gateway zu erreichen (direkt oder über seinen Load Balancer in einer Multi-Gateway-Bereitstellung).
Lösung:
- Öffnen Sie ausgehende HTTPS (Port 443) vom Agent-Host zu den Harmony-Region-URLs. Die Verbindung wird auf WSS (sicheres WebSocket) für die laufende bidirektionale Kommunikation aktualisiert. Auf dem Agent-Host müssen keine eingehenden Ports für Harmony oder das Gateway geöffnet werden.
- Konfigurieren Sie beim Einrichten der Firewall die regionsspezifischen Jitterbit-Services, die unter Ausgehende Kommunikation aufgelistet sind, auf die Allowlist. Dies ist der Abschnitt, der für einen privaten Agent hinter einer Firewall gilt.
- Falls der Agent für die Verwendung von nicht standardmäßigen (benutzerdefinierten) Ports konfiguriert wurde, lassen Sie diese auch durch die Unternehmens-Firewall zu. Siehe Netzwerk-Ports.
- Falls ein privates API-Gateway bereitgestellt wird, lassen Sie auch ausgehende Konnektivität von jedem Agent-Host zum Gateway zu (direkt oder über seinen Load Balancer bei einer Multi-Gateway-Bereitstellung). Der Agent verbindet sich mit dem Gateway, um die API-Antwort-Payload zurückzugeben. Den vollständigen Request-Flow finden Sie unter Systemarchitektur des privaten API-Gateways.

Custom API gibt 504 zurück, aber das Operationsprotokoll zeigt Erfolg

Symptom: Eine benutzerdefinierte API gibt einen 504-Gateway-Timeout zurück, aber das Operationsprotokoll auf der Seite Runtime der Management Console zeigt, dass die Operation erfolgreich abgeschlossen wurde.
Ursache: Wenn eine Request- oder Response-Payload (Header plus Body, komprimiert) etwa 1 KB überschreitet, speichert das Jitterbit-Cloud-API-Gateway die Payload, und der private Agent stellt eine ausgehende Verbindung zum jitterbitsysservice-Host seiner Region her, um die Request-Payload herunterzuladen (oder die Response-Payload hochzuladen), bevor der Vorgang abgeschlossen wird. Falls der Agent-Host diesen Host nicht erreichen kann, tritt bei der Übertragung ein Timeout auf und die API gibt einen 504 zurück, obwohl der Vorgang selbst ausgeführt wurde. Die standardmäßige Agent-Verbindungsprüfung überprüft nicht die Konnektivität zum jitterbitsysservice-Host, daher kann der Agent vollständig verbunden erscheinen, während dieser Host blockiert bleibt.
Lösung:
1. Fügen Sie den jitterbitsysservice-Host für Ihre Region (z. B. jitterbitsysservice.jitterbit.net) und seine statischen IP-Adressen zur ausgehenden Allowlist in der Firewall des Agent-Hosts hinzu. Siehe Jitterbit-Allowlist-Informationen für die regionsspezifischen URLs und IPs.
2. Überprüfen Sie die Konnektivität, indem Sie einen HTTP-Test vom Agent-Host zur jitterbitsysservice-URL Ihrer Region ausführen, und bestätigen Sie dann, dass die API nicht mehr das Timeout überschreitet.

Native Observability zeigt keine Daten an

Symptom: Nach dem Aktivieren von Native Observability zeigt die Registerkarte Metriken der Seite Agents der Management Console keine Daten an, zeigt unvollständige Daten an, oder Diagramme bleiben nach mehreren Minuten leer.
Mögliche Ursachen:
- Der Abschnitt [AgentMetrics] in jitterbit.conf hat nicht Enabled=true, was verhindert, dass der Metrik-Service ausgeführt wird.
- Nicht alle erforderlichen Einstellungen im Abschnitt [AgentCapability] sind auf true gesetzt.
- Die Agent-Services wurden nach Konfigurationsänderungen nicht neu gestartet.
- Der Agent-Host kann die Harmony Cloud nicht erreichen, was verhindert, dass Metriken eingereicht werden.
- Vor Agent-Version 12.10 wurde beim Upgrade eines Windows Private Agent, dessen PgBouncer-Port bereits 6434 war (siehe PgBouncer-Ports), die Verbindung des Metrik-Service nicht aktualisiert, sodass sie auf dem alten Port 6432 blieb und die PgBouncer-Metrik möglicherweise falsch gemeldet wurde.
- Vor Agent-Version 12.9 wurde beim Installieren eines Private Agent als Nicht-Root-Benutzer unter Linux PgBouncer nicht bereitgestellt, sodass der Service nie gestartet wurde und sein Status immer als fehlerhaft angezeigt wird.
Lösung:
- Überprüfen Sie, dass jitterbit.conf alle erforderlichen Einstellungen aus den Abschnitten [AgentMetrics] und [AgentCapability] enthält. Siehe das vollständige Konfigurationsbeispiel in Native Observability Setup.
- Überprüfen Sie metrics.log und metrics_service.log im Agent-Protokollverzeichnis auf Fehler. Diese Protokolle zeichnen den Status des Metrik-Service auf und zeigen an, ob Metriken erfasst und eingereicht werden.
- Starten Sie die Agent-Services neu, wenn Konfigurationsänderungen vorgenommen wurden.
- Überprüfen Sie, dass der Agent-Host die Harmony Cloud erreichen kann. Siehe Agent offline oder nicht erreichbar. Wenn der Agent über einen Proxy verbunden ist, siehe Agent-Metriken fehlen, wenn der Agent über einen HTTP-Proxy verbunden ist.
- Für einen Agent, der von der Port-Nichtübereinstimmung betroffen ist, führen Sie ein Upgrade auf Agent-Version 12.10 oder später durch, das den PgBouncer-Verbindungsport des Metrik-Service automatisch korrigiert. Wenn die Nichtübereinstimmung nach dem Upgrade bestehen bleibt, wenden Sie sich an den Jitterbit-Support, um den Port zu überprüfen.
- Für einen neuen Nicht-Root-Linux Private Agent verwenden Sie Version 12.9 oder später, bei der PgBouncer während der Installation korrekt bereitgestellt wird. Das Upgrade eines vorhandenen Nicht-Root-Linux-Agent auf 12.9 oder später stellt PgBouncer nicht rückwirkend bereit; der Agent muss neu installiert werden.

Agent-Metriken fehlen, wenn sich der Agent über einen HTTP-Proxy verbindet

Symptom: Der private Agent verbindet sich erfolgreich mit Harmony über einen konfigurierten HTTP-Proxy, aber die Registerkarte Metrics der Seite Agents der Management Console zeigt keine Daten an. Die Datei metrics.log kann Einträge wie Client.Timeout exceeded while awaiting headers enthalten.
Ursache: Der Agent sendet Metriken über HTTPS mit einer separaten Verbindung, die die Proxy-Konfiguration des Agents nicht übernimmt. Wenn der Proxy nur HTTP unterstützt oder nicht für den Metrics-Traffic des Agents konfiguriert ist, können Metriken Harmony nicht erreichen, obwohl sich der Agent selbst erfolgreich verbindet.
Lösung:
1. Bestätigen Sie, dass der Proxy HTTPS unterstützt. Agent-Metriken werden über HTTPS übermittelt, daher blockiert ein Proxy, der nur HTTP-Traffic verarbeitet, diese. Das Aktivieren von HTTPS auf dem Proxy behebt das Problem.
2. Wenn Sie HTTPS auf dem Proxy nicht aktivieren können oder Metriken nach dem Aktivieren weiterhin fehlen, benötigt der Metrics-Traffic des Agents eine eigene Proxy-Konfiguration, getrennt von der des Agents. Kontaktieren Sie den Jitterbit-Support, um dies einzurichten.

Datadog Agent startet nach Docker-Installation nicht („postmaster.pid existiert nicht")

Symptom: Nach der Installation des Datadog-Agenten in einem Docker-Container als Teil des Datadog-Observability-Setups startet der Datadog-Agent nicht.
Ursache: Ein bekanntes Datadog-Problem führt dazu, dass der Agent beim Start fehlschlägt, wenn die Konfigurationsdatei des Security-Agenten nicht vorhanden ist.
Lösung: Kopieren Sie die Beispielkonfigurationsdatei des Security-Agenten:
```
cp /etc/datadog-agent/security-agent.yaml.example /etc/datadog-agent/security-agent.yaml
```
Starten Sie dann den Datadog-Agent. Beachten Sie, dass der Datadog-Agent auf Docker nicht automatisch mit dem Container startet und nach jedem Container-Start manuell gestartet werden muss:
```
sudo datadog-agent run
```

Linux: Agent-Dienste starten nach einem Neustart nicht („postmaster.pid existiert nicht")

Symptom: Nach dem Neustart eines Linux-Private-Agent-Hosts starten die Agent-Services nicht. Das Ausführen von sudo jitterbit status zeigt, dass der Scheduler und andere Services nicht ausgeführt werden, und die Agent-Logs (oder die Konsole) enthalten Fehler wie:
```
postmaster.pid does not exist
```
```
reindexdb: could not connect to database template1: could not connect to server: No such file or directory
```
Ursache: Die Dateiberechtigungen im gebündelten PostgreSQL-Datenverzeichnis sind zu permissiv. PostgreSQL erfordert, dass das Datenverzeichnis 700 (nur Eigentümer) ist. Wenn die Berechtigungen lockerer sind (z. B. 755 oder 777), weigert sich PostgreSQL zu starten, was verhindert, dass der Rest des Agents startet.
Lösung:
1. Bestätigen Sie, dass /opt/jitterbit und seine Unterverzeichnisse dem Benutzer und der Gruppe jitterbit gehören:
```
sudo chown -R jitterbit:jitterbit /opt/jitterbit
```
2. Setzen Sie das PostgreSQL-Datenverzeichnis auf 700:
```
sudo chmod 700 /opt/jitterbit/DataInterchange/pgsql/data
```
3. Starten Sie die Agent-Services:
```
sudo /etc/init.d/jitterbit start
```

Linux: Antivirus entfernt PgBouncer, Agent kann sich nicht bei der gebündelte Datenbank authentifizieren

Symptom: Nach der Migration eines Linux-Private-Agents auf einen neuen Host (oder nach einer Neuinstallation) starten die Agent-Services nicht. Das postgresql.log zeigt:
```
[FATAL] password authentication failed for user "jitterbit"
```
Das Agent-Log zeigt, dass es sich nicht mit der Datenbank verbinden kann. Der Fehler bleibt über eine vollständige Deinstallation und Neuinstallation hinweg bestehen.
Ursache: Ein hostbasiertes Antivirus- oder Endpoint-Protection-Produkt erkennt die gebündelte PgBouncer-Binärdatei als verdächtig und entfernt oder isoliert sie. Ohne PgBouncer kann sich der Agent nicht bei seiner internen PostgreSQL-Datenbank authentifizieren.
Lösung:
1. Deaktivieren Sie das Antivirus- oder Endpoint-Protection-Produkt auf dem Agent-Host vorübergehend.
2. Fügen Sie das Jitterbit-Installationsverzeichnis (normalerweise /opt/jitterbit) zur Ausschlussliste des Antivirus hinzu.
3. Installieren Sie den Agent neu. Auf RHEL/CentOS:
```
sudo dnf reinstall jitterbit-agent
```
4. Starten Sie die Agent-Services und bestätigen Sie den normalen Betrieb, aktivieren Sie dann das Antivirus mit der Ausschlussliste erneut.

Sicherheitsscans flaggen `log4j-over-slf4j.jar` als Log4j 1.x Sicherheitslücke

Symptom: Ein Security-Scan einer Private-Agent-Installation kennzeichnet Dateien wie log4j-over-slf4j-1.7.21.jar als End-of-Life-Log4j-1.x-Sicherheitslücke.
Lösung: Es ist keine Maßnahme erforderlich. log4j-over-slf4j.jar ist nicht Log4j 1.x. Es ist Teil des SLF4J-Logging-Frameworks und fungiert als Bridge, die Aufrufe von Drittanbieter-Bibliotheken, die gegen die Log4j-1.x-API geschrieben wurden, zum aktuellen, unterstützten Logging-Framework des Agents umleitet. Die Datei enthält nicht den anfälligen Log4j-1.x-Code. Ihre Anwesenheit ist die Risikominderung des Agents gegen Log4j-1.x-Exposition, nicht eine Instanz der Sicherheitslücke.

Listening-Service „Cluster hat die erforderliche Mindestgröße nicht erreicht"

Symptom: Operationen, die den Listening-Service verwenden, schlagen mit folgendem Fehler fehl:
```
Failed to enable events for operation. Cluster has not met the minimum required size.
```
Mögliche Ursachen:
- Zu wenige Agenten in der Agent-Gruppe werden ausgeführt und sind dem Cluster beigetreten. Bei einer Gruppe von $N$ Agenten, unabhängig davon, ob jeder Agent ausgeführt wird, müssen $(N / 2) + 1$ Agenten (abgerundet) ausgeführt werden und Teil des Clusters sein.
- Ein oder mehrere Agenten haben ihre Verbindung zum Cluster verloren und konnten nicht erneut beitreten, wodurch die Anzahl der ausgeführten, beigetretenen Agenten unter die erforderliche $(N / 2) + 1$ fiel.
- Eine Netzwerkunterbrechung hat die Agent-Gruppe in mehrere kleinere Cluster aufgeteilt. Beispielsweise kann eine Netzwerkaufteilung in einer Gruppe von 4 Agenten zwei Cluster mit je 2 Agenten erzeugen; keiner erfüllt die erforderliche $(N / 2) + 1$ von 3, daher melden beide den Fehler, obwohl jeder Agent ausgeführt wird.
Lösung:
- Bestätigen Sie, dass $(N / 2) + 1$ der Agenten in der Gruppe ausgeführt werden und Teil des Clusters sind, wobei $N$ die Anzahl der in der Agent-Gruppe registrierten Agenten ist, unabhängig davon, ob jeder ausgeführt wird. Beispielsweise erfordert eine Gruppe von 4 Agenten 3, und eine Gruppe von 5 Agenten erfordert ebenfalls 3. Um zu sehen, welche Agenten beigetreten sind, verwenden Sie die Listening-Service-REST-API, um den Cluster-Status anzuzeigen.
- Überprüfen Sie, dass die TCP-Ports 5701 und 5801 zwischen allen Agent-Hosts offen sind und nicht durch Antivirus- oder Firewall-Regeln blockiert werden.
- Wenn der Cluster ausfällt und Nachrichten mit aktivierter Persistierung unverarbeitet bleiben, stellen Sie den Cluster manuell wieder her. Siehe Cluster-Wiederherstellung nach Agent-Fehler.
Hinweis

Eine ungerade Anzahl von Agenten in der Agent-Gruppe wird empfohlen, ist aber nicht erforderlich. Bei einer geraden Anzahl kann eine Netzwerkunterbrechung die Gruppe in zwei Hälften aufteilen, von denen keine groß genug ist, um den Cluster am Laufen zu halten.

Nachrichten des Listening-Service werden nicht zugestellt

Symptom: Der Wiederholungsmechanismus des Clusters verwirft unzugestellte Meldungen nach einem konfigurierten Zeitraum stillschweigend, wodurch abhängige Operationen nicht ausgeführt werden.
Lösung: Um das Aufbewahrungsfenster zu erweitern oder das Löschen zu verhindern, bearbeite JITTERBIT_HOME/Resources/jitterbit-agent-config.properties und setze agent.sdk_framework.retry.deleteRetryableMessageAfter auf einen höheren Wert (in Minuten). Um alle Meldungen unbegrenzt beizubehalten, setze den Wert auf -1. Starte den Agent nach den Änderungen neu.

Custom-API-Operationsprotokolle werden nicht angezeigt

Symptom: Eine Operation, die durch eine benutzerdefinierte API ausgelöst wird, läuft ohne Fehler ab, aber es wird kein Protokolleintrag in Studio oder auf der Seite Runtime der Management Console angezeigt.
Ursache: Wenn eine benutzerdefinierte API eine Operation auslöst, werden Operationsprotokolle nur generiert, wenn die Operation fehlschlägt. Erfolgreiche benutzerdefinierte API-Operationen erzeugen standardmäßig keinen Protokolleintrag.
Lösung: Um Protokolle für erfolgreiche benutzerdefinierte API-Operationen zu erfassen, aktiviere Operation Debug Logging für die Operation. Beachte, dass API Manager eine eigene separate Protokollansicht für API-Anfragen hat.

Operationsdebug-Protokollierung stoppt vor dem ausgewählten Enddatum

Symptom: Operation Debug Logging wurde mit einem zukünftigen Enddatum aktiviert, aber die Protokollgenerierung stoppt vor diesem Datum.
Ursache: Bei Cloud-Agent-Gruppen ist das Enddatum der Operation Debug Logging-Einstellung unzuverlässig. Die Protokollgenerierung kann vor dem konfigurierten Zeitraum beendet werden.
Lösung: Aktiviere Operation Debug Logging nach Bedarf erneut.

Operationsdebug-Protokolldateien fehlen `.input`- oder `.output`-Daten

Symptom: Bei einem privaten Agent ist für eine Operation Operation Debug Logging mit aktivierten Komponenteneingabe- und -ausgabedaten aktiviert. Der Debug Log-Ordner in DataInterchange/Temp/Debug enthält die .jtr-Dateien für jeden Schritt, aber die entsprechenden .input- und .output-Datendateien fehlen.
Mögliche Ursachen:
- Der Cleanup-Service des Agents löscht .input- und .output-Dateien, bevor sie überprüft werden können.
- Der Agent wurde neu gestartet, während die Operation noch lief, sodass die Dateien nie vollständig geschrieben wurden. Siehe Komponenteneingabe-/Ausgabedaten nicht generiert für dieses Szenario.
Lösung:
1. Öffne auf dem Agent-Host CleanupRules.xml im Agent-Installationsverzeichnis.
2. Suche die Cleanup-Regel für das Verzeichnis DataInterchange/Temp/Debug und erhöhe den Wert <FileAge NumDays = "2"...> auf ein längeres Aufbewahrungsfenster (z. B. 7).
```
<CleanupRule>
  <DirectoryPath SearchSubDirectory = "YES" >DataInterchange/Temp/Debug</DirectoryPath>
  <Pattern>*</Pattern>
  <FileAge NumDays = "7" Comparator = "GE"/>
  <FileSize Size = "0" Comparator = "GE"/>
</CleanupRule>
```
3. Starte die Agent-Services neu.

Komponenten-Input-/Output-Daten werden nicht generiert

Symptom: Operation Debug Logging ist aktiviert, die Generierung von Komponenteneingabe- und -ausgabedaten ist aktiviert, aber es werden keine Eingabe-/Ausgabedatendateien für Private-Agent-Operationen angezeigt.
Lösung: Überprüfe das Verbose Log Shipper-Serviceprotokoll auf dem Agent:
```
<JITTERBIT_HOME>/VerboseLogShipper/verbose-log-shipper.out.log
```
Wenn das Protokoll Fehler anzeigt, starte den Verbose Log Shipper-Service neu. Unter Linux kann dies ohne einen vollständigen Agent-Neustart durchgeführt werden:
```
jitterbit stop verboselogshipper
jitterbit start verboselogshipper
```
Unter Windows und Linux werden beim Neustart aller Jitterbit-Agent-Dienste auch die Verbose Log Shipper-Dienste neu gestartet.

Jitterbit MQ: Quorum-Queue-Nachrichten werden nach 20 NACK-Versuchen stillschweigend gelöscht

Symptom: Nachrichten in einer Quorum-Warteschlange verschwinden ohne Fehlermeldung, obwohl sie über die NACK-Aktivität wiederholt erneut in die Warteschlange eingereiht werden.
Mögliche Ursache: Quorum-Warteschlangen setzen ein Zustellungslimit von 20 Versuchen pro Nachricht durch. Nachdem eine Nachricht 20 Mal negativ bestätigt wurde, ohne eine erfolgreiche Bestätigung zu erhalten, wird sie permanent aus der Warteschlange entfernt, ohne einen Fehler zu erzeugen.
Lösung:
- Konfigurieren Sie eine Unzustellbar-Warteschlange, um Nachrichten zu erfassen, die das Zustellungslimit überschreiten und stille Datenverluste zu verhindern.
- Falls wiederholte Neuverarbeitung über 20 Versuche hinaus erforderlich ist, verwenden Sie beim Erstellen der Warteschlange auf der Seite Nachrichtenwarteschlangen einen Classic-Warteschlangen-Typ statt Quorum.

Jitterbit MQ: Umgebung nicht für Messaging aktiviert

Symptom: Operationen, die den Jitterbit-MQ-Connector verwenden, schlagen fehl beim Verbinden oder Senden von Nachrichten, obwohl die Warteschlange in der Management Console existiert.
Mögliche Ursache: Alle Umgebungen sind standardmäßig für Messaging deaktiviert. Eine Nachrichtenwarteschlange kann in einer Umgebung erstellt werden, die noch nicht für Messaging aktiviert wurde.
Lösung:
1. Gehen Sie in der Management Console zur Seite Nachrichtenwarteschlangen und klicken Sie auf das Einstellungssymbol .
2. Aktivieren Sie im Bereich Environments Permission das Messaging für die betroffene Umgebung und klicken Sie auf Save.

Jitterbit MQ: Nachrichtenlimit überschritten verursacht „Error sending message"

Symptom: Operationen, die den Jitterbit-MQ-Connector verwenden, schlagen fehl mit:
```
"statuscode":500,"Error":"Error sending message."
```
Mögliche Ursache: Die Anzahl der Nachrichten in der Warteschlange hat das konfigurierte Limit erreicht. Wenn das Limit überschritten wird, lehnt der Service neue Nachrichten mit einem 500-Fehler ab.
Lösung:
- Bestätigen oder verarbeiten Sie vorhandene Nachrichten in der Warteschlange, um die Anzahl unter das Limit zu bringen.
- Alternativ können Sie auf der Seite Nachrichtenwarteschlangen der Management Console die betroffene Warteschlange öffnen, Advanced Options erweitern und den Wert Message Limit erhöhen.

Jitterbit MQ: NACK-Nachrichten blockieren den Warteschlangen-Fortschritt bei Requeuing

Symptom: Bei Verwendung einer NACK-Aktivität mit ausgewähltem Requeue Messages After NACK werden Nachrichten statt am Ende an die Vorderseite der Warteschlange zurückgesetzt. Wenn Nachrichten wiederholt fehlschlagen und erneut eingereicht werden, werden dieselben fehlgeschlagenen Nachrichten bei jedem nachfolgenden Abruf erneut zugestellt, was verhindert, dass andere Nachrichten in der Warteschlange verarbeitet werden.
Ursache: Der zugrunde liegende Message Broker platziert eine erneut eingereichte Nachricht am Anfang der Warteschlange zur sofortigen Zustellung. Dieses Verhalten kann nicht über den Connector geändert werden.
Lösung: Um zu verhindern, dass fehlerhafte Nachrichten den Warteschlangen-Fortschritt blockieren, verwenden Sie einen der folgenden Ansätze:
- Unzustellbar-Warteschlange: Konfigurieren Sie die NACK-Aktivität für die Verwendung von Reject Messages After NACK und richten Sie eine Unzustellbar-Warteschlange ein, um abgelehnte Nachrichten zu erfassen. Verarbeiten Sie die Unzustellbar-Warteschlange separat, mit einer Verzögerung falls erforderlich, um die fehlgeschlagenen Nachrichten erneut zu versuchen, ohne die Hauptwarteschlange zu blockieren.
- Manuelles erneutes Veröffentlichen: Konfigurieren Sie die NACK-Aktivität für die Verwendung von Reject Messages After NACK, und verwenden Sie dann eine Send-Aktivität, um die Nachricht erneut in der ursprünglichen Warteschlange zu veröffentlichen. Eine erneut veröffentlichte Nachricht wird am Ende der Warteschlange platziert, sodass andere Nachrichten zuerst verarbeitet werden können.

Design Studio-Anmeldung: SSL-Zertifikat- oder Proxy-Filterfehler

Symptom: Design Studio zeigt einen SSL-Zertifikat- oder Proxy-Filterfehler beim Anmeldeversuch an.
Mögliche Ursachen:
- Ein signiertes SSL- oder CA-Zertifikat, das von Ihrem Netzwerk verwendet wird (z. B. von einem Web-Filter, Proxy oder VPN), ist nicht im Jitterbit Java KeyStore vorhanden.
- Die IP-Zulassungsliste für Ihren Netzwerk-Proxy oder Web-Filter enthält nicht die erforderlichen Jitterbit-Adressen. Siehe Zulassungslisten-Informationen.
Lösung: Vollständige Lösungsschritte, einschließlich Anweisungen zum Hinzufügen von Zertifikaten zum Jitterbit Java KeyStore, finden Sie unter SSL-Zertifikat oder Proxy-Filterkonfigurationsfehler.

Design Studio auf macOS Sequoia als Malware gekennzeichnet

Symptom: Unter macOS 15 (Sequoia) zeigt macOS eine Warnung an, dass Design Studio Malware ist, und verhindert das Öffnen.
Mögliche Ursache: macOS Gatekeeper warnt vor Anwendungen, die nicht von Apple beglaubigt sind und außerhalb des Mac App Store verteilt werden. Da Design Studio über die Seite Downloads des Harmony-Portals verteilt wird, meldet macOS, dass es nicht auf Malware überprüft werden kann. Dies ist normales macOS-Verhalten und kein tatsächliches Problem mit dem Installer.
Lösung:
1. Bestätigen Sie, dass Design Studio vom offiziellen Harmony-Portal auf der Seite Downloads heruntergeladen wurde.
2. Falls die Malware-Warnung für eine vom Portal heruntergeladene Installation angezeigt wird, kann die Warnung ignoriert werden: Sie deutet nicht auf ein tatsächliches Sicherheitsrisiko mit dem Jitterbit-Installer hin.

Design Studio: Unscharfe oder kleine Benutzeroberfläche auf Windows 10 hochauflösenden Displays

Symptom: Design Studio-Elemente erscheinen unscharf oder zu klein, wenn sie unter Windows 10 mit einem hochauflösenden Display wie einem 4K-Monitor ausgeführt werden.
Mögliche Ursache: Eine standardmäßige Windows 10-DPI-Skalierungseinstellung, die nicht mit Design Studio kompatibel ist.
Lösung: Lösungsschritte finden Sie unter Windows 10 – Skalierungsfehler bei hochauflösenden Displays.

Design Studio: Lange Projektladzeiten bei Verwendung eines Proxys

Symptom: Das Öffnen eines Design Studio-Projekts dauert mehrere Minuten, wenn die Verbindung über einen Proxy erfolgt. Dies kann von einem Fehler wie dem folgenden begleitet werden:
```
Message: Unable to load image icon at this address: https://citizen.jitterbit.eu/v1/endpoints/s3images/financialforce.png
Details: Can't get input stream from URL!
```
Mögliche Ursache: Die Verzögerung wird normalerweise dadurch verursacht, dass Design Studio versucht, Citizen Integrator-Rezeptsymbole über einen Proxy abzurufen, der den externen Bildserver nicht erreichen kann.
Lösung: Lösungsschritte finden Sie unter Lange Ladezeiten bei Verwendung eines Proxys.

Design Studio macOS: Fehler „Client Properties Do Not Exist" beim Start

Symptom: Design Studio startet unter macOS nicht und zeigt einen Fehler an, dass Client-Eigenschaften nicht vorhanden sind.
Mögliche Ursache: Design Studio wurde direkt vom Disk-Image (.dmg) statt aus dem Ordner Programme gestartet. Die Anwendung muss in den Ordner Programme kopiert werden, damit sie ihre Konfigurationsdateien finden kann.
Lösung:
1. Beenden Sie Design Studio, falls es ausgeführt wird.
2. Öffnen Sie die .dmg-Installerdatei.
3. Ziehen Sie das Jitterbit Studio-Symbol in die Verknüpfung zum Ordner Programme im Installerfenster.
4. Starten Sie Design Studio aus dem Ordner Programme (oder über Spotlight/Launchpad), nicht vom Disk-Image.

Design Studio: Transformation mit Skript schlägt mit Fehler „/PRESCRIPT/ node" fehl

Symptom: Eine Transformation, die ein Skript verwendet, schlägt zur Laufzeit fehl mit:

Zielknoten kann nicht gefunden werden (/PRESCRIPT/).
Die Struktur hat sich möglicherweise geändert. Versuchen Sie, die Transformation 'example' zu öffnen und die Strukturbäume zu aktualisieren.

Mögliche Ursache: Die interne XML-Struktur der Transformation ist inkonsistent mit dem aktuellen Zielschema geworden, typischerweise nach einer Schemaänderung.
Lösung:
1. Öffnen Sie die fehlerhafte Transformation in Design Studio.
2. Klicken Sie auf der Target-Seite auf die Schaltfläche zum Aktualisieren oben im Strukturbaum. Dies liest das Schema erneut ein und erstellt die interne Struktur der Transformation neu.
3. Speichern und stellen Sie die Transformation bereit.

Symptom: Ein Design Studio-Projekt, das auf einer Netzwerkfreigabe gespeichert ist (anstatt lokal oder im Harmony-Cloud-Speicher), zeigt Datenverluste, bei denen UI-Änderungen nach dem erneuten Öffnen des Projekts nicht beibehalten werden, oder die Leistung ist deutlich langsamer als erwartet.
Mögliche Ursache: Jitterbit empfiehlt nicht, Design Studio-Projektarbeitsbereiche auf einer Netzwerkfreigabe zu speichern. Der Netzwerkfreigabe-Speicher verfügt nicht über die Dateisperrmechanismen, die Design Studio benötigt, was zu inkonsistenten Speicherungen und möglichem Datenverlust führt.
Lösung: Verschieben Sie den Projektarbeitsbereich in den lokalen Speicher oder verwenden Sie stattdessen Harmony-Cloud-Speicher anstelle einer Netzwerkfreigabe.

Design Studio: Projektdownload schlägt mit Fehler `Invalid XML character` fehl

Symptom: Das Herunterladen eines Projekts in Design Studio schlägt mit einem Fehler fehl, der angibt, dass ein ungültiges XML-Zeichen im Elementinhalt gefunden wurde, z. B.:

An invalid XML character (Unicode: 0x15) was found in the element content of the document

oder:

org.xml.sax.SAXParseException; lineNumber: 17499; columnNumber: 21; An invalid XML character (Unicode: 0x5) was found in the element content of the document.

Mögliche Ursache: Die Projektmetadaten enthalten ein Steuerzeichen (z. B. 0x05 oder 0x15), das in XML nicht gültig ist. Dies kann aus einer beschädigten Endpunkt-URL oder aus ungewöhnlichen Zeichen resultieren, die in Skripte, Notizen oder andere Textfelder eingefügt wurden.
Lösung:
1. Öffnen Sie das Projekt in Design Studio (oder verwenden Sie eine aktuelle lokale Sicherung), um die Metadaten zu überprüfen.
2. Überprüfen Sie Endpunkt-URLs, Skripte und Notizen auf unsichtbare oder ungewöhnliche Zeichen und entfernen oder ersetzen Sie diese. Die Zeilennummer in der Fehlermeldung kann helfen, den betroffenen Bereich in der exportierten XML zu lokalisieren.
3. Speichern und stellen Sie das korrigierte Projekt bereit, und versuchen Sie dann erneut, es von Design Studio herunterzuladen.
4. Wenn der problematische Inhalt nicht identifiziert werden kann, wenden Sie sich an den Jitterbit-Support mit der vollständigen Fehlermeldung und der Projekt-ID für eine mögliche Metadaten-Reparatur im Backend.

Design Studio: Projektkomponenten nach Download oder Import fehlend

Symptom: Das Öffnen oder Importieren eines Projekts zeigt Operationen in der Liste, aber es werden keine Komponenten (Transformationen, Skripte, Schemas) angezeigt, oder eine Projektexport-Datei .json kann nicht importiert werden. Die Ursache ist normalerweise eine einzelne beschädigte Komponente im Projektexport, die das Parsing der gesamten Datei unterbricht.
Mögliche Ursache: Eine Komponente im Projektexport hat fehlerhaftes JSON, z. B. einen leeren Body oder ungewöhnliche Zeichen, die die Datei ungültig machen.
Lösung:
1. Exportieren Sie das Projekt aus dem Harmony-Portal, um eine .json-Datei zu erstellen.
2. Öffnen Sie die .json-Datei in einem Texteditor und überprüfen Sie das components-Array auf Einträge, die leer, fehlerhaft oder ungewöhnliche Zeichen enthalten.
3. Entfernen Sie das vollständige JSON-Objekt der verdächtigen Komponente aus dem components-Array.
4. Speichern Sie die Datei und importieren Sie sie zurück in Harmony.
5. Wenn die Beschädigung nicht identifizierbar ist, senden Sie den Projektexport an den Jitterbit-Support zur Analyse.

Design Studio: Doppelte Operationen oder Transformationen werden in einem heruntergeladenen Projekt angezeigt

Symptom: Einige Benutzer, die dasselbe Projekt herunterladen, sehen duplizierte Operationen oder Transformationen mit identischen Namen und Schemas, und diese Duplikate werden in Design Studio als ungültig (rot markiert) gekennzeichnet. Andere Benutzer sehen eine saubere Version desselben Projekts.
Mögliche Ursache: Das Projekt wurde auf Operationsebene (anstatt auf Projektebene) migriert, und die Migration hat duplizierte Kopien von Abhängigkeiten (wie Transformationen) zum ursprünglichen Projekt hinzugefügt.
Lösung:
1. Erstellen Sie eine Sicherung des Projekts, bevor Sie Änderungen vornehmen.
2. Identifizieren Sie die duplizierte Operationen oder Transformationen. Löschen Sie die Duplikate und behalten Sie die Originale.
3. Stellen Sie das bereinigte Projekt bereit. Alle Benutzer, die das Projekt erneut herunterladen, erhalten die bereinigte Version.
4. Um dies in Zukunft zu vermeiden, vermeiden Sie die Migration auf Operationsebene in ein Projekt, das bereits die Quellkomponenten enthält. Verwenden Sie die Migration auf Projektebene oder migrieren Sie selektiv nur die Abhängigkeiten, die noch nicht vorhanden sind.

Design Studio: Salesforce-Projektimport schlägt mit falscher Versionsanforderung fehl

Symptom: Das Importieren oder Öffnen eines Projekts mit einem Salesforce-Endpunkt schlägt mit einem Fehler wie dem folgenden fehl:
```
The Jitterpak requires version 12.7.0.0 or higher. The Studio is currently running version [your Design Studio version]. This means that the Jitterpak cannot be opened by this Studio.
```
Dies kann auch bei einer aktuellen, unterstützten Design Studio-Version auftreten, da Design Studio nie eine 12.x-Version hatte.
Mögliche Ursache: Das Projekt wurde aus Design Studio 11.63 oder 11.64 exportiert. Diese Versionen kennzeichnen ein Projekt mit einem Salesforce-Endpunkt mit einer falschen erforderlichen Version (12.7.0.0) anstelle der korrekten Mindestversion. Design Studio 11.64.1 und später exportieren die korrekte erforderliche Version.
Lösung:
- Wenn das Projekt in eine lokale .jpk-Datei exportiert wurde:
  1. Benennen Sie die .jpk-Datei in .zip um und extrahieren Sie sie.
  2. Ändern Sie in environment.properties den Wert requires-version so, dass er Ihrer installierten Design Studio-Version entspricht, z. B.: requires-version=11.63.0.0.
  3. Ändern Sie in jitterpak.properties den Wert required_version in den entsprechenden codierten Wert. Verwenden Sie für Design Studio 11.63.0.0 required_version=110630000000000. Exportieren Sie für jede andere Version ein neues, leeres Projekt aus Ihrer installierten Design Studio und kopieren Sie stattdessen die Werte required_version und requires-version aus den Dateien dieses Projekts.
  4. Komprimieren Sie die extrahierten Dateien zurück in ein .zip-Archiv, benennen Sie es in .jpk um und importieren Sie es.
  Diese Schritte korrigieren nur die .jpk-Datei, die Sie bearbeiten. Das erneute Exportieren des Projekts aus Design Studio 11.63 oder 11.64 schreibt die falsche Versionsanforderung erneut, daher führen Sie ein Upgrade auf Design Studio 11.64.1 oder später durch, um dies zu vermeiden.
- Wenn der Fehler beim Herunterladen oder Öffnen eines in der Harmony-Cloud bereitgestellten Projekts auftritt anstatt beim Importieren einer lokalen .jpk-Datei:
  1. Führen Sie ein Upgrade auf Design Studio 11.64.1 oder später durch.
  2. Kontaktieren Sie den Jitterbit-Support, um eine Backend-Korrektur der gespeicherten Versionsanforderung des Projekts anzufordern, die in der Design Studio-Benutzeroberfläche nicht verfügbar ist. Fordern Sie die Korrektur erst nach dem Upgrade an: Das Öffnen oder erneute Exportieren des Projekts mit einer älteren, betroffenen Version danach kann die falsche Versionsanforderung zurück in das Projekt schreiben.

Design Studio: SOAP Fault schlägt bei direkter E-Mail-Auslösung nicht bereit

Symptom: Das Konfigurieren eines SOAP-Fehlers zum direkten Auslösen einer E-Mail-Benachrichtigung schlägt bei der Bereitstellung fehl oder funktioniert nicht wie erwartet.
Mögliche Ursache: Das Bereitstellen einer Operation, bei der ein SOAP-Fehler direkt eine E-Mail auslöst, kann einen Fehler verursachen.
Lösung:
1. Konfigurieren Sie den SOAP-Fehler so, dass stattdessen eine Operation ausgelöst wird.
2. Verwenden Sie in dieser Operation die Funktion SendEmailMessage in einem Skript, um die Benachrichtigungs-E-Mail zu senden.

Design Studio: Dateiübertragungen wiederholen sich unerwartet

Symptom: Ein Vorgang überträgt eine Quelldatei erneut, die bereits in einem vorherigen Durchlauf verarbeitet wurde.
Mögliche Ursache: Design Studio verfolgt drei Kriterien, um festzustellen, ob eine Datei bereits übertragen wurde: Dateiname, Änderungsdatum und Vorgangs-ID. Wenn sich einer dieser Werte seit der letzten Übertragung geändert hat, behandelt Design Studio die Datei als neu und überträgt sie erneut.
Lösung: Um zu verhindern, dass eine bestimmte Datei erneut übertragen wird, löschen Sie ihren Eintrag aus der Übertragungsverlaufsliste: Aktivieren Sie das Kontrollkästchen neben dem Eintrag im unteren Bereich und klicken Sie auf Löschen.

Design Studio: FTP-Passivmodus und Firewall-Einschränkungen für hohe Ports

Symptom: Eine FTP-Quelle verbindet sich erfolgreich von einer Arbeitsstation, schlägt aber fehl, wenn der Vorgang auf dem privaten Agenten ausgeführt wird, oder Dateiübertragungen treten in Timeout auf, obwohl der Agent den FTP-Server erreichen kann.
Mögliche Ursache: Der passive FTP-Modus verwendet dynamisch zugewiesene Ports mit hohen Nummern für Datenübertragungen. Firewalls, die ausgehende Verbindungen zu bekannten Ports beschränken, blockieren diese Datenkanalverbindungen, auch wenn der Steuerkanal (Port 21) offen ist.
Lösung:
- Bestätigen Sie, dass der passive Modus in der FTP-Quellenkonfiguration aktiviert ist (standardmäßig aktiviert).
- Arbeiten Sie mit Ihrem Netzwerkadministrator zusammen, um den Bereich der Ports mit hohen Nummern zu öffnen, den Ihr FTP-Server für passive Datenverbindungen in der Firewall zwischen dem privaten Agenten-Host und dem FTP-Server verwendet.

Design Studio: FTP Erfolgs- und Fehlerordnerpfade befinden sich auf dem Agent, nicht auf dem FTP-Server

Symptom: Dateien werden nach der Ausführung eines FTP-Vorgangs nicht im konfigurierten Erfolgs- oder Fehlerordner angezeigt, oder die Pfade scheinen sich zu unerwarteten Speicherorten aufzulösen.
Mögliche Ursachen:
- Die Felder für den Erfolgsordner und den Fehlerordnerpfad in einer FTP-Quelle beziehen sich auf Verzeichnisse auf dem privaten Agenten-Computer, nicht auf dem Remote-FTP-Server. Relative Pfade werden relativ zum Dateisystem des Agenten-Hosts interpretiert.
- Dateiname-Schlüsselvariablen werden in diesen Feldern nicht aufgelöst.
Lösung:
- Geben Sie absolute Pfade auf dem privaten Agenten-Host für die Erfolgs- und Fehlerordnerfelder ein (z. B. C:\Jitterbit\processed\ unter Windows oder /var/jitterbit/processed/ unter Linux).
- Verwenden Sie keine Dateiname-Schlüsselwörter oder Sonderzeichen wie * in diesen Pfadfeldern.
- Bestätigen Sie, dass das Agent-Dienstkonto Schreibberechtigungen für die konfigurierten Verzeichnisse hat.

Design Studio: FTP-Verzeichnisauflistung kann nicht analysiert werden

Symptom: Eine FTP-Quelle kann Dateien nicht auflisten, oder bekannte Dateien fehlen in der Quelle, obwohl sie auf dem FTP-Server vorhanden sind.
Mögliche Ursache: Einige FTP-Server geben Verzeichnislisten in einem nicht standardisierten Format zurück, das Design Studio mit seinem Standard-Parser nicht analysieren kann.
Lösung:
- Aktivieren Sie in der FTP-Quellenkonfiguration List only filenames (Nur Dateinamen auflisten). Dies führt dazu, dass die Quelle den NLST-Befehl verwendet, der nur Dateinamen statt einer vollständigen Verzeichnisliste zurückgibt und auf FTP-Servern breiter unterstützt wird.
- Alternativ können Sie die Jitterbit-Variable jitterbit.source.ftp.enable_regex_parser vor dem FTP-Leseschritt auf true setzen, um einen flexibleren Auflistungs-Parser zu aktivieren.

Design Studio: FTP-Ziel „Use FTP Rename" funktioniert nicht mit SFTP-Archivvorgängen

Symptom: Dateien, die mit einem FTP-Ziel mit aktiviertem Use FTP Rename auf einen SFTP-Server geschrieben werden, schlagen fehl oder werden nicht korrekt geschrieben, wenn der Vorgangstyp Archivierung ist.
Mögliche Ursache: Die Option Use FTP Rename funktioniert nicht beim Schreiben auf einen SFTP-Server in einem Archivierungsvorgang.
Lösung: Deaktivieren Sie in der FTP-Zielkonfiguration das Kontrollkästchen Use FTP Rename, wenn der Zielserver ein SFTP-Server ist und der Vorgang eine Archivdatei schreibt.

Design Studio: FTP-Ziel „Auto Create Directories" ist unzuverlässig

Symptom: Ein FTP-Zielvorgang schlägt fehl, weil ein Zielverzeichnis nicht vorhanden ist, obwohl Auto Create Directories aktiviert ist.
Mögliche Ursache: Es ist ein bekanntes Problem, dass die Option Auto Create Directories inkonsistent funktioniert. Je nach FTP-Server wird das Verzeichnis möglicherweise nicht erstellt.
Lösung:
- Erstellen Sie die erforderlichen Verzeichnisse manuell auf dem FTP-Server, bevor Sie den Vorgang ausführen.
- Wenn Sie Auto Create Directories verwenden, bestätigen Sie, dass das Verzeichnis erstellt wurde, bevor Sie sich in der Produktion darauf verlassen.

Symptom: Das Abrufen einer großen Datei aus einer File Share-Quelle schlägt fehl, obwohl die Datei vorhanden ist und die Quellenverbindung korrekt konfiguriert ist.
Mögliche Ursache: File Share-Quellen haben eine bekannte Einschränkung, bei der einzelne Dateien größer als 2 GB möglicherweise nicht abrufbar sind.
Lösung: Teilen Sie Dateien größer als 2 GB in kleinere Segmente auf, bevor Sie sie in der Dateifreigabe zur Abholung platzieren.

Design Studio: HTTP-Quellenverbindungstest schlägt fehl, obwohl der Endpunkt erreichbar ist

Symptom: Das Testen einer HTTP-Quellenverbindung schlägt mit einem Verbindungs- oder Autorisierungsfehler fehl, aber der Endpunkt ist erreichbar und gibt Daten zurück, wenn er direkt in einem Browser oder API-Client aufgerufen wird.
Mögliche Ursache: Die Schaltfläche Test Connection in der HTTP-Quellenkonfiguration sendet eine HTTP HEAD-Anfrage. Einige Server unterstützen die HEAD-Methode nicht und geben einen Fehler 405 oder ähnliches zurück, obwohl GET- und POST-Anfragen erfolgreich sind.
Lösung:
1. Wenn der Endpunkt in einem Browser oder über eine direkte GET-/POST-Anfrage erreichbar ist, kann der fehlgeschlagene Verbindungstest ignoriert werden. Fahren Sie mit der Bereitstellung und Ausführung des Vorgangs fort, um die tatsächliche Konnektivität zu überprüfen.
2. Wenn der Vorgang auch zur Laufzeit fehlschlägt, untersuchen Sie das Problem weiter mithilfe der Vorgangsprotokolle.

Design Studio: NetSuite-Rechenzentrum-URL-Fehler, verwenden Sie die kontospezifische WSDL-URL

Symptom: Ein NetSuite-Endpunkt, der zuvor erfolgreich verbunden war, schlägt jetzt fehl mit:

Connector Error: Error getting the data center URL.
...
In this account, you must use account-specific domains with this SOAP web services endpoint.

oder:

You are not requesting the correct data center for your company.

Mögliche Ursache: NetSuite akzeptiert generische WSDL-URLs (z. B. https://webservices.netsuite.com/...) oder datencenter-spezifische WSDL-URLs (z. B. https://webservices.na3.netsuite.com/...) nicht mehr. Der Endpunkt muss eine kontospezifische WSDL-URL verwenden.
Lösung:
1. Gehen Sie in NetSuite zu Setup > Company > Company Information und öffnen Sie die Registerkarte Company URLs, um die kontospezifische Domain zu finden.
2. Erstellen Sie die kontospezifische WSDL-URL im Format https://<account-id>.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl.
3. Aktualisieren Sie das Feld WSDL Download URL in der NetSuite-Endpunktkonfiguration mit der kontospezifischen URL.
4. Vollständige Anweisungen finden Sie unter NetSuite-Konto-spezifische WSDL-URL.

Design Studio: NetSuite-TFA-Benutzer dürfen nicht SSO-Authentifizierungstyp verwenden

Symptom: Ein NetSuite-Endpunkt, der mit Single Sign-On (SSO)-Authentifizierung konfiguriert ist, schlägt fehl oder verhält sich unerwartet für einen Benutzer mit aktivierter Zwei-Faktor-Authentifizierung (TFA oder 2FA) auf seinem NetSuite-Konto.
Mögliche Ursache: NetSuite-Benutzer mit aktivierter TFA sollten den SSO-Authentifizierungstyp nicht verwenden, wenn ein NetSuite-Endpunkt konfiguriert wird. Diese Kombination kann zum Fehlschlag des Endpunkts führen. Der SSO-Authentifizierungstyp wird auch von NetSuite schrittweise eingestellt.
Lösung:
1. Aktivieren Sie Token-basierte Authentifizierung (TBA) auf dem NetSuite-Konto.
2. Konfigurieren Sie den NetSuite-Endpunkt neu, um TBA statt SSO zu verwenden.

Design Studio: NetSuite TBA `INSUFFICIENT_PERMISSION`-Fehler zur Laufzeit trotz erfolgreichem Verbindungstest

Symptom: Ein NetSuite-Endpunkt, der mit Token-basierter Authentifizierung (TBA) konfiguriert ist, testet die Verbindung erfolgreich, aber Operationen schlagen zur Laufzeit fehl mit:
```
INSUFFICIENT_PERMISSION
```
Mögliche Ursache: Die Rolle, die zum Generieren der TBA-Zugriffstokens verwendet wird, verfügt nicht über ausreichende Berechtigungen für die ausgeführten Operationen. Der Verbindungstest ist erfolgreich, auch mit einer unterberechtigten Rolle, aber die Berechtigungsprüfungen zur Laufzeit schlagen fehl.
Lösung:
1. Wechseln Sie in NetSuite zu einer Rolle mit vollständigem Zugriff oder Administrator-Rolle, wenn Sie die Zugriffstokens generieren, oder fügen Sie der aktuellen Rolle die erforderlichen Berechtigungen hinzu.
2. Generieren Sie die Zugriffstokens mit der aktualisierten Rolle neu und konfigurieren Sie den NetSuite-Endpunkt neu.

Design Studio: NetSuite gespeicherte Suchdropdown ist leer, wenn das Objekt mehr als 1.000 gespeicherte Suchen enthält

Symptom: Das Dropdown-Menü für gespeicherte Suche in der NetSuite-Aktivitätskonfiguration wird nicht mit Optionen gefüllt, obwohl gespeicherte Suchen für das Objekt in NetSuite vorhanden sind.
Mögliche Ursache: NetSuite setzt ein Limit von 1.000 Datensätzen für API-Anfragen durch. Wenn ein Objekt mehr als 1.000 gespeicherte Suchen hat, überschreitet die API-Anfrage zum Abrufen dieser das Limit und gibt keine Ergebnisse zurück, wodurch das Dropdown-Menü leer bleibt.
Lösung: Löschen oder archivieren Sie in NetSuite gespeicherte Suchen, die nicht mehr verwendet werden, um die Gesamtanzahl unter 1.000 für das betroffene Objekt zu reduzieren. Das Dropdown-Menü wird gefüllt, sobald die Anzahl reduziert ist. Weitere Details finden Sie unter NetSuite-Einschränkungen für gespeicherte Suchen.

Design Studio: NetSuite NULL oder leere Werte können nicht an benutzerdefinierte Felder übergeben werden

Symptom: Das Zuordnen eines NULL- oder Leerzeichenwerts (leere Zeichenkette) zu einem benutzerdefinierten NetSuite-Feld löscht das Feld in NetSuite nicht.
Mögliche Ursache: Die NetSuite-API akzeptiert NULL- oder Leerzeichenwerte für benutzerdefinierte Felder nicht über den standardmäßigen Feldzuordnungsansatz.
Lösung: Um NULL- oder Leerzeichenwerte an ein benutzerdefiniertes Feld zu übergeben, ordnen Sie das Quellfeld sowohl den untergeordneten Feldern externalId als auch name des Zielknotens des benutzerdefinierten Felds in der Transformation zu. Weitere Informationen finden Sie unter Passing null values to custom fields.

Design Studio: NetSuite benutzerdefinierte Segmente werden nicht in der Aktivitätskonfiguration angezeigt

Symptom: Benutzerdefinierte Segmente werden auf dem Konfigurationsbildschirm der NetSuite-Aktivität nicht angezeigt, obwohl sie für die Zuordnung verfügbar sein sollten.
Mögliche Ursache: Das NetSuite-Benutzerkonto, das im Endpunkt konfiguriert ist, verfügt nicht über ausreichende Berechtigungen für den Zugriff auf das benutzerdefinierte Segment oder das zugehörige Objekt.
Lösung:
1. Überprüfen Sie in NetSuite, dass das Benutzerkonto, das im NetSuite-Endpunkt konfiguriert ist, über die erforderlichen Berechtigungen für die Interaktion mit dem benutzerdefinierten Segment und dem zugehörigen Objekt verfügt.
2. Wenn die Berechtigungen unzureichend sind, aktualisieren Sie die Benutzerrolle in NetSuite, um den erforderlichen Zugriff auf benutzerdefinierte Segmente einzuschließen.

Design Studio: Salesforce OAuth 2.0-Verbindungsbearbeitungen werden möglicherweise vor dem Testen oder Bereitstellen nicht gespeichert

Symptom: Nach dem Ändern des Felds Instance URL, Client ID oder Client secret einer vorhandenen Salesforce Org, die mit 2-legged OAuth 2.0-Clientauthentifizierung konfiguriert ist, kann das Klicken auf Test Salesforce Login ein irreführendes Erfolgs- oder Fehlerergebnis basierend auf den vorherigen Feldwerten anstelle der gerade eingegebenen Werte zurückgeben.
Mögliche Ursache: Vor Design Studio 11.67 wurden Änderungen an diesen Feldern nicht zuverlässig gespeichert, bevor der Verbindungstest ausgeführt wurde.
Lösung: Führen Sie ein Upgrade auf Design Studio 11.67 oder höher durch. Bei Verwendung eines privaten Agenten führen Sie auch ein Upgrade auf Version 12.11 oder höher durch. Cloud-Agent-Gruppen erhalten diesen Fix automatisch.

Design Studio: SAP IDocs nicht gefunden, wenn ein geplanter Vorgang auf einem anderen Agent ausgeführt wird

Symptom: In einer Multi-Agent-Gruppe mit IDoc-Verarbeitung nach dem Store-and-Forward-Prinzip findet die geplante Operation, die nach gespeicherten IDoc-Dateien sucht, bei einigen Durchläufen keine Dateien zur Verarbeitung, und die IDoc-Verarbeitung wird verzögert oder erfolgt in falscher Reihenfolge.
Mögliche Ursache: Bei der Store-and-Forward-Verarbeitung speichert der SAP Event Listener jede empfangene IDoc auf dem lokalen Dateisystem des Agenten, der sie empfangen hat. Eine separate Operation mit schnellem Zeitplan sucht dann nach diesen Dateien und verarbeitet sie. Harmony kann diese geplante Operation jedoch an jeden Agent in der Gruppe verteilen. Jeder Agent verarbeitet nur die auf ihm selbst gespeicherten Dateien, daher werden Dateien, die auf einem Agent gespeichert sind, erst verarbeitet, wenn der Zeitplan diesen Agent das nächste Mal auswählt.
Lösung: Jeder Agent verarbeitet seine eigenen gespeicherten Dateien beim nächsten Durchlauf der geplanten Operation auf ihm, daher werden die Dateien schließlich verarbeitet. Wenn IDocs in garantierter Reihenfolge verarbeitet werden müssen oder ohne Warten auf den nächsten geplanten Durchlauf des speichernden Agenten, schreiben Sie die IDoc-Dateien in eine gemeinsame Ressource, auf die alle Agenten zugreifen können, z. B. eine FTP-Website, ein gemeinsames Dateisystem oder eine Datenbank. Beachten Sie, dass ein externer Datenspeicher einen Ausfallpunkt darstellt. Agent-Cluster werden ansonsten für Failover und Lastverteilung verwendet.

Design Studio: SAP Massen-IDoc-Sendungen können die Verbindungslimits des Zielendpunkts überschreiten

Symptom: Nach einer großen SAP-Massenoperation, die Tausende von IDocs sendet, schlagen Operationen gegen ein nachgelagertes Zielsystem (z. B. Salesforce) intermittierend mit Verbindungs- oder Anmeldefehlern fehl.
Mögliche Ursache: IDocs werden asynchron gesendet. Wenn eine Massenaktualisierung Tausende von IDocs generiert, versuchen alle gleichzeitig, ihre nachgelagerten Operationen auszulösen. Systeme wie Salesforce erzwingen Limits für gleichzeitige API-Verbindungen, und eine plötzliche Flut von IDoc-gesteuerten Operationen kann diese Limits überschreiten.
Lösung:
- Verwenden Sie ein Store-and-Forward-Muster: Konfigurieren Sie den IDoc-Listener so, dass eingehende IDocs in temporäre Dateien geschrieben werden, und verwenden Sie dann eine geplante Operation, um diese in kontrollierten Batches mit vorhersehbarer Rate zu verarbeiten.
- Überprüfen Sie die Limits für gleichzeitige Verbindungen und API-Aufrufe des Zielendpunkts und konfigurieren Sie die Design-Studio-Operation so, dass diese Limits eingehalten werden, indem Sie die Anzahl der gleichzeitigen Operationen drosseln.

Design Studio: SAP IDoc Nutzlast verloren, wenn Zielendpunkt nicht erreichbar ist

Symptom: Ein IDoc wird vom SAP Event Listener empfangen, aber die Daten kommen nicht beim Zielendpunkt an und können nicht wiederhergestellt werden.
Mögliche Ursache: Bei der direkten Verarbeitung geht die Payload verloren und wird dauerhaft gelöscht, wenn der Zielendpunkt beim Verarbeiten des IDoc nicht erreichbar ist. Es gibt keinen automatischen Wiederholungsmechanismus bei der direkten Verarbeitung.
Lösung: Verwenden Sie stattdessen Store-and-Forward-Verarbeitung: Konfigurieren Sie die erste Operation so, dass das eingehende IDoc in eine temporäre Datei geschrieben wird, und verwenden Sie dann eine geplante Operation, um die Datei zu verarbeiten. Wenn das Ziel nicht erreichbar ist, wird die Datei beibehalten und beim nächsten geplanten Lauf erneut verarbeitet. Anleitungen zur Implementierung von Store-and-Forward-Verarbeitung finden Sie unter Best Practices für SAP.

Design Studio: SAP IDoc Store-and-Forward Temporärdateien werden nach 24 Stunden gelöscht

Symptom: In einem Store-and-Forward-IDoc-Workflow fehlen temporäre Dateien, die nicht verarbeitet wurden, im Speicherverzeichnis, bevor die Verarbeitungsoperation ausgeführt wurde.
Mögliche Ursache: Standardmäßig werden temporäre IDoc-Dateien in der Store-and-Forward-Verarbeitung nach 24 Stunden automatisch gelöscht. Wenn die geplante Verarbeitungsoperation nicht innerhalb dieses Zeitfensters ausgeführt wird (z. B. aufgrund von Agent-Ausfallzeiten), werden die Dateien gelöscht, bevor sie verarbeitet werden können.
Lösung:
- Stellen Sie sicher, dass die geplante Verarbeitungsoperation mindestens alle 24 Stunden ausgeführt wird, um Dateien zu verarbeiten, bevor sie ablaufen.
- Alternativ können Sie die Aufbewahrungsdauer verlängern, wenn ein längeres Zeitfenster erforderlich ist. Weitere Informationen finden Sie unter Best Practices für SAP.

Design Studio: SAP BAPI-Vorgang erfolgreich, aber Transaktion wird nicht bestätigt

Symptom: Das Ausführen einer BAPI scheint fehlerfrei zu erfolgen, aber die erwartete Transaktion wird nicht in SAP angezeigt.
Mögliche Ursache: Der SAP Connector gibt einen BAPI-Transaktions-Commit nur aus, wenn die BAPI einen Antworttyp von S (Success) zurückgibt. Wenn die BAPI einen Antworttyp von I (Information), E (Error) oder W (Warning) zurückgibt, wird kein Commit ausgegeben und die Transaktion wird nicht in SAP gespeichert.
Lösung:
1. Überprüfen Sie das Feld TYPE des Knotens RETURN in der BAPI-Antwort, um den zurückgegebenen Antworttyp zu bestätigen.
2. Wenn Sie eine benutzerdefinierte BAPI verwenden, aktualisieren Sie diese so, dass sie einen Antworttyp von S zurückgibt, wenn die Transaktion übernommen werden soll. Weitere Informationen finden Sie unter Troubleshooting BAPI-Commits.

Design Studio: SAP Event Listener greift IDocs unter Windows nicht auf

Symptom: Der SAP Event Listener-Service wird ausgeführt, das SAP-System meldet ausgehende IDocs als erfolgreich versendet, aber es werden keine Operationen ausgelöst. Agent-Logs zeigen Verbindungsfehler für die RFC-Programm-ID, z. B.:
```
serverException occured on [Program ID] connection null
```
Mögliche Ursache: Die Windows-Services-Datei auf dem Agent-Host enthält keinen Eintrag für den SAP-Gateway-Service. Ohne diesen Eintrag kann der RFC-Programm-ID-Listener den SAP-Gateway-Hostnamen und -Port nicht auflösen, was verhindert, dass IDocs an Design Studio übermittelt werden.
Lösung:
1. Öffnen Sie auf dem Windows-Host, auf dem der private Agent ausgeführt wird, %WINDIR%\System32\drivers\etc\services als Administrator.
2. Fügen Sie die folgenden Zeilen hinzu:
```
sapgw00 3300/tcp
sapgw00 3300/udp
```
3. Speichern Sie die Datei, starten Sie den SAP Event Listener-Service und den Agent neu, und führen Sie einen Test durch, indem Sie einen IDoc von SAP versenden.

Der Service-Name sapgw00 und der Port 3300 entsprechen dem Standard-SAP-Gateway-Service für die Systemnummer 00. Wenn Ihr SAP-System eine andere Systemnummer verwendet, passen Sie die Einträge entsprechend an (z. B. sapgw01 3301/tcp und sapgw01 3301/udp für die Systemnummer 01).

API-Verwaltung

Dieser Abschnitt behandelt Probleme mit der API-Verwaltungsfunktion von Harmony: Erstellen, Veröffentlichen und Sichern von APIs.

API kann nicht veröffentlicht werden: Abonnement-API-Limit erreicht

Symptom: Das Erstellen oder Veröffentlichen einer API schlägt mit einer Fehlermeldung wie dieser fehl:
```
You have reached Maximum no of API Service configured for your Jitterbit organization
```
Ursache: Die Organisation hat die maximale Anzahl veröffentlichter API-URLs erreicht, die das Abonnement zulässt. Jede veröffentlichte Custom API, jeder OData-Service oder jede Proxy-API (und jeweils ihre veröffentlichten Klone) nutzt eine API-URL. Entwurf-APIs werden nicht mitgezählt.
Lösung: Überprüfen Sie auf der Seite APIs des API Managers die Anzahl Custom API URLs used (genutzte Custom-API-URLs) und Proxy API URLs used (genutzte Proxy-API-URLs), die oben auf der Seite angezeigt werden, gegen die Gesamtzahl, die Ihr Abonnement zulässt. Heben Sie die Veröffentlichung nicht mehr benötigter APIs auf oder löschen Sie diese, um API-URLs freizugeben. Entwurf-APIs werden nicht auf das Limit angerechnet. Um das Limit zu erhöhen, wenden Sie sich an Ihren Customer Success Manager.

Veröffentlichte API gibt 404 Nicht Gefunden zurück

Symptom: Der Aufruf einer veröffentlichten API gibt einen 404-Fehler zurück.
Mögliche Ursachen:
- Das Limit Hits per minute (Hits pro Minute) im zugewiesenen Sicherheitsprofil ist auf null gesetzt, was alle Anfragen blockiert. Eine Änderung der Abonnementebene der Organisation kann dieses Limit zurücksetzen, sodass eine API, die zuvor funktioniert hat, beginnen kann, 404s zurückzugeben.
- Die Konfiguration, die Basis-URL oder die Sichtbarkeitseinstellungen der API sind fehlerhaft.
- Ein privates API-Gateway erkennt die API nach der Bereitstellung nicht.
- Die API wurde nicht vollständig veröffentlicht oder ihre Metadaten sind unvollständig.
Lösung:
- Öffnen Sie das Sicherheitsprofil, das der API zugewiesen ist, und bestätigen Sie, dass der Wert Hits per minute auf eine Zahl ungleich null gesetzt ist. Wenn das Limit kürzlich zurückgesetzt wurde (beispielsweise nach einer Abonnementänderung), stellen Sie es auf den beabsichtigten Wert wieder her.
- Überprüfen Sie auf der Seite APIs, dass die API erfolgreich veröffentlicht wurde und dass ihre URL und Sichtbarkeitseinstellungen korrekt sind.
- Wenn die API über ein privates API-Gateway bereitgestellt wird, überprüfen Sie die Gateway-Installation und Konnektivität auf Fehler oder Fehlkonfigurationen.

HTTP 504 Gateway Timeout

Symptom: API-Aufrufe geben folgende Fehlermeldung zurück:
```
504 Gateway Timeout
```
Dies tritt normalerweise nach dem Timeout-Fenster des Gateways auf (30 bis 180 Sekunden, abhängig von der Timeout-Einstellung der API).
Mögliche Ursachen:
- Die API-URL ist fehlerhaft formatiert oder Path-Parameter werden nicht korrekt verarbeitet, was dazu führt, dass das Gateway beim Routing der Anfrage fehlschlägt.
- Der Backend-Betrieb oder der externe Service antwortet zu langsam, um innerhalb des Gateway-Timeout-Fensters zu antworten, beispielsweise aufgrund großer Payloads oder komplexer Transformationslogik.
- Die Anfrage kann keinem verfügbaren Agent zugewiesen werden, beispielsweise weil die Agent-Gruppe vollständig ausgelastet ist oder unter hoher Last steht, weshalb sie beim Gateway auslöst, bevor der Betrieb ausgeführt wird. Ein Zeichen dafür ist, dass die fehlgeschlagene Anfrage keinen entsprechenden Eintrag in den Betriebsprotokollen hat.
Lösung:
- Überprüfen Sie, dass die API-URL korrekt formatiert ist. Falls die API Path-Parameter verwendet, sollten Sie erwägen, dem Betrieb ein Skript hinzuzufügen, das die URL explizit analysiert und die Parameterwerte erfasst.
- Wenn das Timeout durch einen langsamen Backend verursacht wird, überprüfen Sie den Betrieb und seine Transformationslogik auf Performance-Engpässe, besonders große Datenmengen oder langsame externe Aufrufe, und reduzieren Sie den langsamen Schritt.
- Falls der Betrieb zeitlich mehr benötigt als die aktuelle Einstellung erlaubt, erhöhen Sie das Timeout auf der API-Einstellungsregisterkarte. Das API-Timeout (Standard 30 Sekunden, Maximum 180 Sekunden) ist unabhängig vom Studio-Betriebstimeout. Das Betriebstimeout wird nur auf privaten Agents verwendet, wenn die Einstellung EnableAPITimeout in der Agent-Konfiguration aktiviert ist.
- Falls der Betrieb nicht innerhalb des maximalen Timeouts abgeschlossen werden kann oder eine Echtzeitantwort nicht erforderlich ist, gestalten Sie den Betrieb der API so um, dass die langwierige Arbeit asynchron gestartet wird (beispielsweise durch Aufrufen mit RunOperation im asynchronen Modus), damit die API eine Antwort zurückgeben kann, ohne auf deren Abschluss zu warten. Siehe Asynchrone Operationen verwalten.
- Für gelegentliche Timeouts fügen Sie Wiederholungen hinzu, um transiente Fehler erneut zu versuchen: Verwenden Sie die integrierten Wiederholungseinstellungen der HTTP v2-Verbindung für ausgehende Aufrufe oder eine skriptgesteuerte RunOperation-Wiederholungsschleife mit einer Verzögerung zwischen den Versuchen.
- Falls Timeouts mit Agent-Last korrelieren, überprüfen Sie die Agent-Kapazität: Führen Sie API-verwaltende Operationen auf Agents getrennt von schweren ETL-Workloads aus und fügen Sie der Gruppe Agents hinzu, wenn diese überlastet ist. Siehe Optimieren und verbessern Sie die Leistung von Jitterbit Private Agents.

API-Portal spiegelt Projektänderungen nicht wider

Symptom: Das API Portal zeigt veraltete Projektnamen oder Attribute an, nachdem ein Projekt umbenannt oder aktualisiert wurde.
Mögliche Ursache: Das API Portal wurde nach der Projektänderung nicht automatisch synchronisiert.
Lösung:
1. Um alle benutzerdefinierten und Proxy-APIs in der Umgebung zu aktualisieren, öffnen Sie den Portal Manager und klicken Sie auf Regenerate Docs. Um eine einzelne API zu aktualisieren, öffnen Sie deren Registerkarte Documentation auf der Seite APIs und klicken Sie auf Save & Publish.
2. Überprüfen Sie, dass die aktualisierten Informationen korrekt auf dem API Portal angezeigt werden.

Microsoft Entra ID OAuth: Sicherheitsprofilname darf keine Leerzeichen enthalten

Symptom: API-Aufrufe mit einem Microsoft Entra ID (Azure AD) OAuth 2.0-Sicherheitsprofil mit drei Beinen schlagen fehl mit einem Fehler von Microsoft, der eine Unübereinstimmung der Reply-URL anzeigt:
```
The reply URL specified in the request does not match the reply URLs configured for the application.
```
Mögliche Ursache: Der Sicherheitsprofilname enthält Leerzeichen. Leerzeichen im Profilnamen führen dazu, dass der OAuth-Redirect-URI fehlerhaft konstruiert wird und keiner der in der Azure-App-Registrierung registrierten Reply-URLs entspricht.
Lösung:
1. Öffne das Sicherheitsprofil im API Manager und benenne es so um, dass alle Leerzeichen entfernt werden (ändere z. B. My Profile in MyProfile oder my-profile).
2. Überprüfe in der Azure-App-Registrierung, dass die dort registrierten Reply-URLs dem Redirect-URI entsprechen, den der API Manager für das umbenannte Profil generiert.

Microsoft Entra ID 2-beiniger OAuth: `OAUTH_INVALID_TOKEN_CODE`-Fehler

Symptom: API-Aufrufe, die durch ein Microsoft Entra ID OAuth 2.0-Sicherheitsprofil mit zwei Beinen geschützt sind, schlagen fehl mit:
```
Failed to validate authentication token - HttpErrorResponse: OAUTH_INVALID_TOKEN_CODE
```
Mögliche Ursache: Der aud-Anspruch im JWT, das von Entra ID ausgestellt wurde, stimmt nicht mit der im API Manager-Sicherheitsprofil konfigurierten Zielgruppe überein. Dies deutet normalerweise darauf hin, dass die Application ID URI in der Azure-App-Registrierung falsch konfiguriert ist oder dass der OAuth-Bereich, den der Client anfordert, nicht mit der registrierten URI übereinstimmt.
Lösung:
1. Öffnen Sie im Azure-Portal die App-Registrierung, die diesem Sicherheitsprofil zugeordnet ist, und gehen Sie zu API verfügbar machen.
2. Vergewissern Sie sich, dass die Application ID URI auf eine gültige URI im Format api://<Application (client) ID> eingestellt ist.
3. Im Sicherheitsprofil überprüfen Sie, dass der OAuth-Bereich auf api://<Application (client) ID>/.default eingestellt ist.
4. Aktualisieren Sie die Client-Anwendung, um ein Token mit diesem exakten Bereich anzufordern.
5. Falls die Validierung weiterhin fehlschlägt, nachdem Zielgruppe und Bereich korrekt eingestellt sind, öffnen Sie das Manifest der App-Registrierung und vergewissern Sie sich, dass requestedAccessTokenVersion auf 2 eingestellt ist. Ein fehlender oder anderer Wert kann ebenfalls zu Fehlern bei der Token-Validierung führen.

Azure AD Graph API wurde stillgelegt

Symptom: API-Aufrufe, die zuvor mit einem Microsoft Entra ID (Azure AD)-Sicherheitsprofil funktioniert haben, schlagen mit Authentifizierungsfehlern fehl.
Mögliche Ursache: Die App-Registrierung des Sicherheitsprofils ist noch für die Verwendung der Azure AD Graph API konfiguriert, die Microsoft am 30. Juni 2025 eingestellt hat. App-Registrierungen, die nicht zu Microsoft Graph migriert wurden, schlagen bei Anfragen fehl.
Lösung:
1. Migrieren Sie im Azure-Portal die App-Registrierung zu Microsoft Graph.
2. Aktualisieren Sie nach der Migration das App-Manifest, indem Sie die Schritte für API-Berechtigungen in der Konfiguration des Microsoft Entra ID-2-teiligen OAuth-Sicherheitsprofils befolgen.

Google oder Salesforce Identitätsanbieter: 2-beiniger OAuth wird nicht unterstützt

Symptom: Ein API-Sicherheitsprofil, das mit Google oder Salesforce als OAuth 2.0-Identitätsanbieter konfiguriert ist, schlägt fehl, wenn es für 2-teiliges OAuth konfiguriert ist.
Mögliche Ursache: OAuth 2.0-API-Sicherheitsprofile von Google und Salesforce unterstützen 2-teiliges OAuth nicht.
Lösung: Verwenden Sie ein 3-teiliges OAuth 2.0-Sicherheitsprofil für APIs, die sich mit Google oder Salesforce als Identitätsanbieter authentifizieren.

Microsoft Copilot Studio: Standardauthentifizierung wird nicht unterstützt

Symptom: Das Verbinden einer benutzerdefinierten Jitterbit-API mit Microsoft Copilot Studio (als REST-API-Tool) schlägt fehl, wenn das Sicherheitsprofil der API Standardauthentifizierung verwendet.
Mögliche Ursache: Microsoft Copilot Studio unterstützt Standardauthentifizierung nicht. Eine benutzerdefinierte Jitterbit-API, deren Sicherheitsprofil Standardauthentifizierung verwendet, kann nicht von Copilot Studio aufgerufen werden.
Lösung:
1. Öffnen Sie im API Manager das Sicherheitsprofil, das der API zugeordnet ist.
2. Ändern Sie den Authentifizierungstyp zu API-Schlüssel oder OAuth 2.0, oder entfernen Sie das Sicherheitsprofil aus der API, falls der Endpunkt keine Authentifizierung erfordert.
3. Veröffentlichen Sie die API erneut und verbinden Sie sie dann in Microsoft Copilot Studio erneut. Siehe Jitterbit-KI-Agent mit Microsoft Copilot Studio verbinden.

Schaltfläche „Neue API" nicht sichtbar trotz korrekter Organisationsrolle

Symptom: Die Schaltfläche Neue API wird im API Manager für einen Benutzer nicht angezeigt, der eine Rolle auf Organisationsebene hat, aber kein Organisationsadministrator ist. Wenn man dem Benutzer die Berechtigung Admin auf Organisationsebene gewährt, wird die Schaltfläche zwar angezeigt, macht aber auch alle Umgebungen für den Benutzer sichtbar.
Mögliche Ursache: Eine Rolle auf Organisationsebene allein reicht nicht aus, um APIs zu erstellen. Die Rolle muss auch Schreibzugriff auf Umgebungsebene für die spezifische Umgebung haben, in der der Benutzer APIs erstellen muss.
Lösung:
1. Wechseln Sie in der Management Console zu Umgebungen und öffnen Sie die Umgebung, in der der Benutzer APIs erstellen muss.
2. Bestätigen Sie, dass für die Rolle des Benutzers in dieser Umgebung der Schreibzugriff aktiviert ist. Ist das nicht der Fall, aktivieren Sie ihn und speichern Sie.
3. Die Schaltfläche Neue API sollte jetzt für diese Umgebung sichtbar sein.

Symptom: Anmeldedaten für die Basic-Authentifizierung aus dem Cache eines früheren Requests können einen späteren API-Aufruf auf eine der folgenden Arten beeinflussen:
- Eine API mit zwei oder mehr zugewiesenen Basic-Auth-Sicherheitsprofilen zeigt in den API-Protokollen unerwartete Benutzernamen an, darunter Benutzernamen, die keinem der Profile angehören. Einige Anfragen schlagen mit einem Fehler 401 Unauthorized fehl.
- Eine Proxy-API oder ein OData-Service mit einem zugewiesenen Basic-Auth-Sicherheitsprofil gibt eine erfolgreiche Antwort zurück, ohne zur Eingabe von Anmeldedaten aufzufordern.
Mögliche Ursache: Der Browser oder API-Client (z. B. Postman) hat Basic-Auth-Anmeldedaten aus einer früheren Sitzung als Cookie im Cache gespeichert. Wenn die API erneut aufgerufen wird, sendet der Client zunächst den im Cache gespeicherten Cookie. Wenn die zwischengespeicherten Anmeldedaten keinem zugewiesenen Sicherheitsprofil entsprechen, wird die Anfrage abgelehnt und der unerwartete Benutzername wird in den Protokollen angezeigt, bevor die Authentifizierung mit den richtigen Anmeldedaten erfolgreich ist. Wenn sie übereinstimmen, ist die Anfrage erfolgreich, ohne dass eine neue Aufforderung angezeigt wird.
Lösung:
1. Löschen Sie vor erneutem Testen der API die Cookies und den Cache des Browsers, oder wechseln Sie zu einem Inkognito- oder privatem Browserfenster.
2. Bestätigen Sie, dass das Verhalten nicht vorhanden ist, wenn eine neue Anfrage ohne vorherige Sitzungs-Cookies gestellt wird. Wenn das Verhalten verschwindet, handelt es sich um clientseitiges Zwischenspeichern von Anmeldedaten und nicht um ein Konfigurationsproblem.
Beachten Sie, dass jeder HTTP-Client, der Cookies speichert (einschließlich browsergestützter Tools und API-Testprogramme), das gleiche Verhalten aufweisen kann.

`INVALID_TRIGGER_USER` oder `TRIGGER_USER_TOO_LONG` Fehler

Symptom: Ein API-Aufruf mit einem Sicherheitsprofil mit Basic-Authentifizierung oder einer benutzerdefinierten Protokollierung schlägt mit einem Fehler INVALID_TRIGGER_USER oder TRIGGER_USER_TOO_LONG fehl, obwohl die gleichen Anmeldedaten oder der gleiche Header-Wert zuvor funktioniert haben.
Mögliche Ursache: Der Wert, der zur Identifizierung des Aufrufers der Anfrage verwendet wird, verstößt gegen eine Validierungsregel: Er enthält ein nicht zulässiges Zeichen (INVALID_TRIGGER_USER) oder überschreitet 256 Zeichen (TRIGGER_USER_TOO_LONG).
- Bei Basic-Authentifizierung mit der Standard-Protokollierung ist dieser Wert das Feld Benutzername des Sicherheitsprofils.
- Bei einer benutzerdefinierten Protokollierung ist es der Wert, den die aufrufende Anwendung im konfigurierten Header sendet.

Character Validation wurde in der 12.10 Harmony-Version hinzugefügt, und das Längenlimit wurde in der 12.11 Harmony-Version hinzugefügt. Ein privates API-Gateway, das eine frühere Version ausführt, erzwingt die entsprechende Validierung nicht. Daher können beide Fehler zum ersten Mal nach dem Upgrade des Gateways auftreten, obwohl sich die Konfiguration des Sicherheitsprofils nicht geändert hat.

Ab der 12.12 Harmony-Version lehnt das Feld Benutzername des Sicherheitsprofils die nicht zulässigen Zeichen ab. Es ist daher nicht mehr möglich, ein Sicherheitsprofil zu speichern, das diese enthält. Für Basic-Authentifizierung mit der standardmäßigen Protokollierungseinstellung gilt INVALID_TRIGGER_USER daher nur für Sicherheitsprofile, die vor dieser Version gespeichert wurden.

Lösung:
- Für Basic-Authentifizierung mit der standardmäßigen Protokollierungseinstellung: Bearbeiten Sie das Feld Benutzername des Sicherheitsprofils, um die nicht zulässigen Zeichen zu entfernen oder es auf 256 Zeichen oder weniger zu kürzen, je nach Bedarf. Aktualisieren Sie dann die Anmeldedaten in jeder aufrufenden Anwendung, die den vorherigen Benutzernamen referenziert.
- Für eine Custom-Protokollierungseinstellung: Aktualisieren Sie die aufrufende Anwendung so, dass sie einen Header-Wert sendet, der keine nicht zulässigen Zeichen enthält und 256 Zeichen oder weniger ist.

401 Unauthorized mit einer gültigen IP-Allowlist (veralteter Cache)

Symptom: API-Aufrufe geben 401 Unauthorized zurück, obwohl die Client-IP korrekt in den vertrauenswürdigen IP-Gruppen des Sicherheitsprofils aufgeführt ist.
Mögliche Ursache: Ein veralteter Cache von Einträgen des alten IP-Bereichs im Sicherheitsprofil überschreibt die aktiven vertrauenswürdigen IP-Gruppen.
Lösung: Migrieren Sie das Sicherheitsprofil von alten IP-Bereichen zum Modell Vertrauenswürdige IP-Gruppen, dem aktuellen Allowlist-Mechanismus: Definieren Sie die IPs als vertrauenswürdige IP-Gruppe und weisen Sie sie dem Profil zu. Das Deaktivieren der Einstellung Anfragen nur von den folgenden IP-Bereichen vertrauen bei einem Profil, das noch ältere IP-Bereiche verwendet, entfernt diese Bereiche dauerhaft (eine Bestätigungsmeldung warnt davor). Migrieren Sie die IPs daher zu einer vertrauenswürdigen IP-Gruppe, anstatt die Einstellung auszuschalten, um den Cache zu leeren.

Salesforce on Hyperforce: API-Aufrufe werden nach Änderung der Salesforce-IP-Adressen abgelehnt

Symptom: Callouts von Salesforce zu einer API (ausgehende Nachrichten, Apex-Callouts, Salesforce Connect oder aufrufbare Aktionen) werden nach der Migration der Salesforce-Organisation zu Hyperforce, Salesforces öffentlicher Cloud-Infrastruktur, abgelehnt. Das Sicherheitsprofil der API hat Anfragen nur von den folgenden IP-Bereichen vertrauen aktiviert mit einer vertrauenswürdigen IP-Gruppe, die Salesforce-IP-Adressen auflistet.
Mögliche Ursache: Vertrauenswürdige IP-Gruppen ordnen die Quell-IP-Adresse einer Anfrage zu, und die Adressen, die eine Salesforce-Organisation auf Hyperforce für ausgehende Callouts verwendet, ändern sich im Laufe der Zeit. Eine Gruppe, die einen festen Satz von Salesforce-Adressen auflistet, passt nicht mehr.
Lösung: Salesforce empfiehlt, Callouts in Ihr Netzwerk zu authentifizieren, anstatt ihre Quell-IP-Adressen in die Allowlist aufzunehmen:
1. Öffnen Sie das Sicherheitsprofil, das der API zugewiesen ist, und setzen Sie seinen Authentifizierungstyp auf API Key. Konfigurieren Sie den Salesforce-Callout so, dass der Schlüssel in einem Request-Header gesendet wird, nicht in einem Abfrageparameter, damit er nicht in Request-URLs aufgezeichnet wird. OAuth 2.0 ist auch verfügbar, obwohl mit Salesforce als Identitätsanbieter der einzige Flow 3-legged ist, was manuelle Interaktion erfordert.
Nachdem der Callout erfolgreich authentifiziert wurde, heben Sie die Zuweisung der vertrauenswürdigen IP-Gruppe auf, die die Salesforce-Adressen auflistet, damit spätere Adressänderungen die API nicht mehr beeinflussen. Heben Sie die Zuweisung der Gruppe auf, anstatt Anfragen nur von den folgenden IP-Bereichen vertrauen zu deaktivieren, was dauerhaft alle noch auf dem Profil gespeicherten Legacy-IP-Bereiche entfernt.

Wenn Ihre Organisation IP-Allowlisting benötigt, veröffentlicht Salesforce seine Hyperforce-Bereiche als dynamische Liste unter ip-ranges.salesforce.com/ip-ranges.json und kündigt Ergänzungen im Voraus an. Diese Liste ändert sich jedes Mal, wenn Salesforce seine Adressen ändert. Die Allowlist aktuell zu halten bedeutet daher, die Datei zu verfolgen und die vertrauenswürdige IP-Gruppe entsprechend zu aktualisieren. Callouts von einer Adresse, die hinzugefügt wurde, nachdem die Gruppe zuletzt aktualisiert wurde, werden abgelehnt. Diese Adressen werden auch organisationsübergreifend bei Salesforce freigegeben, sodass das Allowlisten dieser Adressen bestätigt, woher eine Anfrage stammt, nicht, dass sie von Ihrer Organisation stammt. Vollständige Anleitung von Salesforce, einschließlich bidirektionales SSL (mTLS), Auth Providers und verbundene Apps, finden Sie unter Retain uninterrupted access to Salesforce services on Hyperforce.

Service-URL überschreitet maximale Länge (HTTP 414)

Symptom: Das API-Gateway gibt folgende Meldung zurück:
```
414 URI Too Large
```
Mögliche Ursache: Die konstruierte Service-URL (einschließlich Basis-URL, Service-Pfad und aller Pfad- oder Abfrageparameter) überschreitet 8.000 Zeichen.
Lösung:
- Reduziere die Länge der Service-URL, indem du den Service-Pfad verkürzest oder die API in mehrere Endpunkte aufteilst.
- Überprüfe bei Proxy-APIs, dass die Kombination aus Basis-URL und allen definierten Service-Pfaden das 8.000-Zeichen-Limit nicht überschreitet.

Proxy-API: Service-Pfadparameter erfordern ein OpenAPI-Dokument

Symptom: Die Konfiguration eines Proxy-API-Service-Pfads mit Pfadparametern (beispielsweise /resource/{id}) schlägt fehl, wenn man diese manuell eingibt, da das Feld keine geschweiften Klammern akzeptiert.
Mögliche Ursache: Manuell definierte Service-Pfade in Proxy-APIs unterstützen nicht die Zeichen { und }, die zur Definition von Pfadparametern verwendet werden.
Lösung: Um Pfadparameter in einem Proxy-API-Service-Pfad zu verwenden, stelle ein OpenAPI-Dokument bereit, das die Pfade und ihre Parameter definiert. API Manager erkennt die Pfade und ihre Parameter automatisch aus der OpenAPI-Spezifikation, anstatt sie manuell eingeben zu müssen.

API in API Manager kann nicht gelöscht werden

Symptom: Das Löschen einer API in API Manager schlägt fehl: Die Benutzeroberfläche zeigt eine generische Fehlermeldung an und die API wird nicht entfernt. Der Fehler tritt im Browser auf, bevor eine Löschanforderung den Server erreicht, und wird in der Browser-Entwicklerkonsole als JavaScript-TypeError angezeigt.
Mögliche Ursache: Die Rolle des Benutzers verfügt nicht über die Berechtigung Admin. Beim Löschen einer API wird zunächst überprüft, welche API-Gruppen der API zugeordnet sind. Das Anzeigen der Seite API-Gruppen erfordert die Berechtigung Admin: Eine Rolle mit nur Write-Umgebungszugriff kann die Seite öffnen, kann aber deren Inhalte nicht lesen. Wenn die Rolle die API-Gruppen nicht lesen kann, erhält diese Überprüfung einen Wert, den die Benutzeroberfläche nicht verarbeiten kann, und das Löschen wird nicht abgeschlossen.
Lösung: Lasse einen Benutzer, dessen Rolle die Berechtigung Admin Rollenberechtigung hat, das Löschen durchführen. Das Erteilen der Berechtigung Admin für die betroffene Rolle funktioniert ebenfalls, aber das ist eine umfassende Erhöhung auf Organisationsebene. Bevorzuge daher, dass ein vorhandener Administrator die API löscht.

API-Umgebung kann nach der Erstellung nicht geändert werden

Symptom: Eine API wurde in der falschen Umgebung erstellt und muss verschoben werden, aber das Feld Umgebung ist nicht bearbeitbar.
Mögliche Ursache: Die Umgebung wird bei der API-Erstellung festgelegt und kann danach nicht geändert werden.
Lösung:
- Um eine benutzerdefinierte oder Proxy-API in eine andere Umgebung zu verschieben, klone die API von der Seite APIs und wähle während des Klonens die richtige Umgebung.
- Alternativ kannst du die API aus ihrer aktuellen Umgebung exportieren und in die Zielumgebung importieren.

CORS aktiviert: `OPTIONS` Anfragen werden ohne Authentifizierung ausgeführt

Symptom: Nach der Aktivierung von CORS auf einer benutzerdefinierten oder Proxy-API verarbeitet die HTTP-Methode OPTIONS Anfragen ohne Authentifizierung.
Mögliche Ursache: Die Aktivierung von CORS führt dazu, dass Operationen mit der Methode OPTIONS ohne Authentifizierung ausgeführt werden. Dies ist erforderlich, um Preflight-Anfragen von Browsern zu unterstützen, bedeutet aber auch, dass jede OPTIONS-Anfrage die Operation erreicht, ohne ein Sicherheitsprofil zu durchlaufen.
Lösung:
- Wenn die API OPTIONS nicht für vertrauliche Operationen nutzt, ist keine Aktion erforderlich. Dies ist das erwartete Verhalten, wenn CORS aktiviert ist.
- Falls eine authentifizierte Behandlung von OPTIONS erforderlich ist, deaktiviere CORS auf der API oder strukturiere die Operation so um, dass sie unauthentifizierte Preflight-Anfragen explizit erkannt und bearbeitet.

Cloud-Proxy-API: Ziel-API muss öffentlich zugänglich sein

Symptom: Eine Proxy-API, die das von Jitterbit gehostete Cloud-API-Gateway nutzt, gibt Fehler zurück oder kann die Ziel-API nicht erreichen.
Mögliche Ursache: Bei Verwendung des Cloud-API-Gateways muss die zu proxying-betreibende API aus dem öffentlichen Internet erreichbar sein. APIs hinter einer Firewall oder in einem privaten Netzwerk können vom Cloud-Gateway nicht erreicht werden.
Lösung:
- Bestätigen Sie, dass die Ziel-API aus dem öffentlichen Internet erreichbar ist, auch wenn sie gesichert ist.
- Falls die Ziel-API hinter einer Firewall bleiben muss, stellen Sie stattdessen ein privates API-Gateway im selben privaten Netzwerk bereit, anstatt das Cloud-API-Gateway zu verwenden.
- Um die IP-Adressen des Cloud-Gateways auf die Zulassungsliste zu setzen, damit das Gateway auf die Proxy-API zugreifen kann, siehe Informationen zur Zulassungsliste.

Einstellung „Request & Response Payloads anzeigen" hat keine Auswirkung auf Proxy-APIs

Symptom: Der Toggle Request & Response Payloads in Logs anzeigen erscheint in den Einstellungen einer Proxy-API, aber das Aktivieren hat keine Auswirkung auf die Log-Ausgabe.
Mögliche Ursache: Request- und Response-Payload-Protokollierung wird für Proxy-APIs nicht unterstützt. Der Toggle ist in der Konfigurationsoberfläche sichtbar, funktioniert aber nicht für diesen API-Typ.
Lösung: Um Request- und Response-Payloads zu erfassen, verwenden Sie eine benutzerdefinierte API, die denselben Endpoint aufruft, wobei die Einstellung Request & Response Payloads in Logs anzeigen unterstützt wird.

Private Gateway gibt eine 400 „Jitterbit Services überprüfen"-Seite ohne API-Logeintrag zurück

Symptom: Anfragen über ein privates API-Gateway schlagen zeitweilig mit einer HTTP-400-Antwort fehl. Der Aufrufer erhält statt einer normalen API-Antwort eine HTML-Fehlerseite ähnlich wie:
```
Error connecting to Jitterbit Services. Please verify that all Jitterbit Services are running on your Jitterbit Agent machine - including the Apache server and Process Engine.
```
Es erscheint kein Eintrag in den API-Protokollen für die fehlgeschlagene Anfrage, da die Anfrage nie eine Operation erreicht hat.
Mögliche Ursache: Die private Agent-Gruppe ist überlastet und hat keine verfügbaren Apache-Worker-Threads, um Jobs vom privaten API-Gateway anzunehmen. Wenn kein Worker-Thread frei ist, schlägt die Gateway-zu-Agent-Übergabe mit einem Verbindungsabbruch fehl, bevor die Anfrage protokolliert oder ausgeführt werden kann.
Lösung:
1. Fügen Sie mehr Agents zur Agent-Gruppe hinzu, um die Last zu verteilen, und bestätigen Sie, dass die Agent-Hosts über ausreichend CPU und Speicher verfügen.
2. Überwachen Sie die Apache-Worker-Thread-Nutzung der Agents. Wenn native Observability aktiviert ist, überprüfen Sie die Diagramme Apache Thread Capability, Apache idle workers und Apache busy workers (siehe Dashboards), um zu bestätigen, ob Threads während der Fehler erschöpft sind.
3. Wenn die Agents auch nach einer Skalierung durchgehend aus Apache-Worker-Threads ausgelastet sind, wenden Sie sich an den Jitterbit-Support, um die Apache-Worker-Thread-Kapazität der Agents zu überprüfen (die MaxRequestWorkers-Einstellung). Ändern Sie die Jitterbit-Apache-Konfigurationsdateien nicht, wenn dies nicht vom Jitterbit-Support angewiesen wird. Siehe Apache-Konfigurationsdateien.

Änderungen am Sicherheitsprofil benötigen mehrere Minuten, um wirksam zu werden

Symptom: Eine API verhält sich weiterhin so, als ob eine alte Sicherheitsprofilkonfiguration aktiv ist, selbst nachdem das Profil aktualisiert und gespeichert wurde.
Mögliche Ursache: Sicherheitsprofile werden auf dem API-Gateway zwischengespeichert. Änderungen an einem aktiven Sicherheitsprofil werden nicht sofort wirksam.
Lösung:
1. Warten Sie mehrere Minuten nach dem Speichern einer Sicherheitsprofiländerung, bevor Sie die betroffene API testen.
2. Wenn das Problem nach 10 Minuten noch auftritt, bestätigen Sie, dass die Änderung korrekt gespeichert wurde, indem Sie das Sicherheitsprofil erneut öffnen.

Das Löschen einer API aktualisiert die API-Portal-Dokumentation nicht

Symptom: Nach dem Löschen einer API bleibt ihre OpenAPI-Dokumentation auf dem API Portal sichtbar.
Mögliche Ursache: Die API Portal-Dokumentation wird nicht automatisch aktualisiert, wenn eine API aus dem API Manager gelöscht wird.
Lösung:
- Öffnen Sie nach dem Löschen einer API den Portal Manager und entfernen oder aktualisieren Sie den Dokumentationseintrag der API dort manuell.
- Alternativ können Sie die Registerkarte Documentation für die API vor dem Löschen verwenden, um den Portal-Eintrag zuerst zu entfernen.

Sicherheitsprofil kann nicht gelöscht werden, solange es einer veröffentlichten API zugeordnet ist

Symptom: Der Versuch, ein Sicherheitsprofil zu löschen, schlägt fehl oder die Löschoption ist nicht verfügbar, auch nachdem das Profil von einem API entfernt wurde.
Mögliche Ursache: Nachdem ein Sicherheitsprofil aus der API-Konfiguration entfernt wurde, muss das API gespeichert und erneut veröffentlicht werden, bevor das Profil als vollständig entfernt gilt. Bis das API erneut veröffentlicht wird, behandelt API Manager das Profil weiterhin als aktiv.
Lösung:
1. Nachdem das Sicherheitsprofil vom API entfernt wurde, klicken Sie auf Speichern und dann auf Veröffentlichen.
2. Sobald das API mit der aktualisierten Konfiguration erneut veröffentlicht wurde, zeigt das Sicherheitsprofil nicht mehr an, dass es aktiv ist, und kann gelöscht werden.

2-legged OAuth fällt auf Private-Gateway-Versionen vor 10.48 auf 3-legged zurück

Symptom: Ein Sicherheitsprofil, das für 2-Legged-OAuth konfiguriert ist, nutzt stattdessen 3-Legged-OAuth, wenn es über ein privates API-Gateway bereitgestellt wird.
Mögliche Ursache: Private API-Gateways mit einer Version früher als 10.48 unterstützen 2-Legged-OAuth nicht. Wenn die Gateway-Version unter 10.48 liegt, fällt das Sicherheitsprofil auf 3-Legged-OAuth zurück, auch wenn 2-Legged-OAuth konfiguriert ist.
Lösung:
1. Überprüfen Sie die Version des privaten API-Gateways, das das API bereitstellt.
2. Aktualisieren Sie das Gateway auf Version 10.48 oder später, um die Unterstützung für 2-Legged-OAuth zu aktivieren.

Multi-Gateway ALB: Alle Container müssen auf demselben Host sein

Symptom: In einer containerisierten Multi-Gateway-Umgebung hinter einem Application Load Balancer (ALB) schlagen API-Aufrufe zeitweise fehl oder Payloads können nicht abgerufen werden, obwohl die einzelnen Gateways den Anschein machen, fehlerfrei zu sein.
Mögliche Ursache: Bei Verwendung eines containerisierten privaten API-Gateways mit einem ALB müssen alle Gateway-Container auf der gleichen Host-Maschine ausgeführt werden. Container, die auf verschiedenen Hosts bereitgestellt werden, können die Payload-Abrufung nicht koordinieren, was zu zeitweisen Fehlern führt.
Lösung:
1. Bestätigen Sie, dass alle privaten API-Gateway-Container in der Gruppe auf dem gleichen physischen oder virtuellen Host ausgeführt werden.
2. Wenn Container auf mehrere Hosts verteilt sind, konsolidieren Sie diese auf einem einzelnen Host.
3. Für Multi-Host-Bereitstellungen überprüfen Sie die ALB-Konfiguration im Gateway-Installationsleitfaden auf weitere Konfigurationsanforderungen.

Private Gateway: Benutzerdefinierte SSL-Konfiguration wird durch Upgrades überschrieben

Symptom: Nach einem Upgrade eines privaten API-Gateways werden benutzerdefinierte SSL-Protokoll- oder Cipher-Einstellungen nicht mehr angewendet und das Gateway kehrt zum Standard-TLS-Verhalten zurück.
Mögliche Ursache: Der Upgrade-Prozess des privaten API-Gateways überschreibt die On-Premise-Konfigurationsdatei (/usr/local/openresty/nginx/conf/onpremise.conf). Alle manuellen Änderungen an dieser Datei, einschließlich benutzerdefinierter SSL-Protokollbeschränkungen oder Cipher-Listen, gehen während des Upgrades verloren.
Lösung:
1. Erstellen Sie vor dem Upgrade des privaten API-Gateways eine Sicherungskopie der On-Premise-Konfigurationsdatei.
2. Nach Abschluss des Upgrades wenden Sie Ihre benutzerdefinierten SSL-Einstellungen auf die neue Konfigurationsdatei an.

Private Gateway gibt HTTP 507 oder „Datei oder Verzeichnis nicht vorhanden" zurück

Symptom: Private API-Gateway-Endpunkte geben 507 Insufficient Storage zurück. Gateway-Protokolle zeigen:
```
could not open payload file: No such file or directory
```
auch wenn auf den Gateway-Hosts ausreichend Speicherplatz verfügbar ist.
Mögliche Ursache: Hier bedeutet 507, dass das Gateway die gehostete Payload- oder Antwortdatei für die Anfrage nicht öffnen konnte; dies bedeutet nicht unbedingt, dass der Host keinen Speicherplatz mehr hat. In einem Multi-Node-Private-API-Gateway hinter einem Load Balancer kann dies passieren, wenn der Node, der eine Anfrage verarbeitet, nicht auf eine gehostete Datei zugreifen kann, die ein anderer Node erstellt hat, da diese Dateien lokal für jeden Node sind.
Lösung:
1. Bestätigen Sie, dass die Gateway-Hosts nicht wirklich keinen Speicherplatz mehr haben, indem Sie die Festplatte und inode-Nutzung überprüfen (df -h und df -i). Geben Sie Speicherplatz frei und führen Sie den Test erneut durch, nur wenn diese wirklich voll sind.
2. Falls das Gateway als mehrere Nodes hinter einem Load Balancer ausgeführt wird, bestätigen Sie, dass der Load Balancer jede Anfrage und deren Antwort konsistent zum gleichen Node leitet, da gehostete Payload- und Antwortdateien lokal für den Node sind, der sie erstellt hat. Für Container-Gateways siehe Multi-Gateway ALB: Alle Container müssen auf demselben Host sein.
3. Falls der Fehler weiterhin auftritt, aktivieren Sie die Trace-Protokollierung auf dem Gateway (setzen Sie traceLogsEnabled auf true in der Gateway-Konfiguration) und kontaktieren Sie den Jitterbit-Support mit den resultierenden Trace-Protokollen, den Gateway-Protokollen (/opt/jitterbit/var/log/api-gateway), den NGINX- oder OpenResty-Protokollen sowie der ls -lR-Ausgabe für die hosted-files-Verzeichnisse auf jedem Node. Der Support kann serverbasierte Bedingungen überprüfen, die nicht vom Kunden konfigurierbar sind, wie die Host-zu-Umgebungs-Zuordnung, veraltete Private-Domain-Einträge und Dateiberechtigungen.

Private Gateway Installation oder Upgrade schlägt mit fehlenden Abhängigkeiten fehl

Symptom: Das Ausführen von yum install zum Installieren oder Upgraden eines Linux-Private-API-Gateways (RPM) auf Version 10.62 oder später schlägt mit fehlenden Abhängigkeitsfehlern fehl:
```
Nothing provides geoip-devel needed by jitterbit-api-gateway-11.x.x-x.x86_64
Nothing provides libGeoIP.so.1()(64bit) needed by jitterbit-api-gateway-11.x.x-x.x86_64
```
Mögliche Ursache: Private API Gateway Version 10.62 und später erfordern die Pakete geoip-devel und libGeoIP, die von der EPEL-Repository bereitgestellt werden. Die dokumentierte Installation aktiviert EPEL vor der Installation des Gateways. Der Fehler tritt auf, wenn dieser Schritt übersprungen wird, oder wenn der Gateway-Host keinen Internetzugriff hat und EPEL nicht erreichen kann, um die Pakete herunterzuladen.
Lösung:
- Aktivieren Sie auf einem Gateway-Host mit Internetzugriff die EPEL-Repository vor der Installation des Gateways, wie beschrieben in Installieren Sie ein Private-API-Gateway: Führen Sie yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm aus, und führen Sie dann die Gateway-Installation erneut durch.
- Auf einem isolierten Host ohne Internetzugriff wird durch die Installation des epel-release-Pakets allein nur die Repository-Definition hinzugefügt; die Pakete geoip-devel und libGeoIP werden nicht heruntergeladen. Laden Sie auf einem Computer mit Internetzugriff diese Pakete und ihre transitiven Abhängigkeiten herunter, übertragen Sie sie auf den Gateway-Host, und installieren Sie sie in Abhängigkeitsreihenfolge mit yum install <package.rpm>, bevor Sie die Gateway-Installation erneut durchführen.

Private Gateway Selbsttest gibt „Fehler, Testaufruf zur API fehlgeschlagen" zurück

Symptom: Das Befehlszeilen-Selbsttest-Hilfsprogramm des Private-API-Gateways gibt Folgendes zurück:
```
Failure, test call to API failed
```
Mögliche Ursache: Bei den Private-API-Gateway-Versionen 11.30 und früher erstellt das Selbsttest-Hilfsprogramm eine Test-API, der erforderliche Felder fehlen (Service Name und Path), was dazu führt, dass der Testaufruf fehlschlägt.
Lösung:
- Führen Sie ein Upgrade des Private-API-Gateways auf Version 11.31 oder später durch, um dies automatisch zu beheben.
- Falls ein sofortiges Upgrade nicht möglich ist: Öffnen Sie die API-Konfiguration für die API namens ApiGatewayTest, füllen Sie das Feld Service Name mit einem beliebigen Wert aus (z. B. service), setzen Sie Path auf /, speichern und veröffentlichen Sie, führen Sie dann das Selbsttest-Hilfsprogramm erneut aus.

OData $count oder $inlinecount gibt einen Fehler zurück, wenn keine Datensätze übereinstimmen

Symptom: Eine OData-Serviceabfrage mit den Systemabfrageopionen $count oder $inlinecount gibt einen Fehler statt 0 zurück, wenn keine Datensätze dem Filter entsprechen.
Mögliche Ursache: Ein OData-Service gibt standardmäßig einen Fehler statt 0 zurück, wenn eine $count- oder $inlinecount-Abfrage keine Datensätze findet.
Lösung: Auf Private Agents mit Version 11.32 oder später den OData-Parameter $noErrorOnZeroCount in der OData-Service-Konfiguration auf true setzen. Dies führt dazu, dass $count-Abfragen 0 statt eines Fehlers zurückgeben, wenn keine Datensätze übereinstimmen.

Proxy-API: Request-Header-Bindestriche werden durch Unterstriche ersetzt

Symptom: Eine Proxy-API-Operation erhält Request-Header, bei denen Bindestriche durch Unterstriche ersetzt werden (z. B. kommt X-Custom-Header als X_Custom_Header an), was dazu führt, dass Header-Abfragen fehlschlagen.
Mögliche Ursache: Proxy APIs haben eine disable-hyphen-replacement-Einstellung, die steuert, ob Bindestriche in Request-Header-Namen durch Unterstriche ersetzt werden. Bei neuen Proxy APIs ist diese Einstellung standardmäßig auf true gesetzt (Ersetzung deaktiviert). Ältere Proxy APIs können sie auf false gesetzt haben, was die Ersetzung verursacht.
Lösung:
- In der Proxy-API-Konfiguration die Header-Einstellung disable-hyphen-replacement überprüfen. Um Bindestriche in Header-Namen beizubehalten, die Einstellung auf true stellen.
- Wenn die Proxy API vor Einführung dieses Standards erstellt wurde und die Ersetzung unerwartet auftritt, die Einstellung auf true aktualisieren und die API erneut veröffentlichen.

Operationsprotokolle sind für API-gesteuerte Operationen nicht sichtbar, wenn der Debug-Modus deaktiviert ist

Symptom: Nach dem Aufrufen einer API zeigt das API-Protokoll an, dass der Aufruf erfolgreich war, aber auf der Seite Runtime ist kein Operationsprotokoll für die von der API ausgelöste Operation sichtbar. Aufrufe von WriteToOperationLog aus der Operation heraus erzeugen ebenfalls keine sichtbaren Protokolleinträge.
Mögliche Ursache: Wenn eine Operation über eine veröffentlichte API ausgelöst wird, erscheinen erfolgreiche Ausführungen standardmäßig nicht in den Operationsprotokollen. Fehlerhafte Operationen werden immer protokolliert; nur erfolgreiche Operationsprotokolle und alle WriteToOperationLog-Ausgaben aus erfolgreichen Ausführungen werden ausgeblendet. Erfolgreiche Ausführungen erscheinen nur, wenn Enable debug mode until (eine API-Manager-Einstellung) oder Operation debug logging (eine Agent-Einstellung) aktiv ist.
Lösung:
1. Um erfolgreiche Operationsprotokolle und WriteToOperationLog-Ausgaben anzuzeigen, Enable debug mode until für die API auf der Registerkarte API-Einstellungen aktivieren oder Operation debug logging auf dem Agent aktivieren.
2. Um auch die rohen Request- und Response-Daten sowie Nutzlasten zu erfassen, entweder Enable debug mode until aktivieren (wie in Schritt 1) oder Operation debug logging mit beiden Show Request & Response Payloads in Logs und Verbose logging kombinieren. Welche Daten jede Einstellung erfasst, hängt von der aktivierten Kombination ab; eine vollständige Übersicht finden Sie unter API-Request- und Response-Daten.
3. Debug-Modus nach dem Erfassen der benötigten Protokolle deaktivieren, da das Aktivieren das Protokollvolumen erhöht.

API-Payload ist 2 Tage lang auf dem Agent verfügbar

Symptom: Ein Workflow, der eine API-Request-Payload vom Agent mehr als 2 Tage nach dem API-Aufruf abruft, kann die Payload nicht finden.
Mögliche Ursache: API-Request-Payloads für benutzerdefinierte APIs und OData-Services werden maximal 2 Tage auf dem Agent gespeichert. Nach diesem Zeitraum ist die Payload nur verfügbar, wenn die Operation sie bereits in einen persistenten Storage-Connector (wie Temporary Storage, File Share oder eine Datenbank) geschrieben hat.
Lösung:
- Gestalten Sie Operationen so, dass sie API-Request-Payloads unmittelbar bei dem API-Aufruf verarbeiten, anstatt den Payload-Abruf zu verschieben.
- Wenn die Payload für längere Verarbeitung beibehalten werden muss, schreiben Sie sie in der initial API-gesteuerten Operation in einen persistenten Storage-Ort.

API-Protokollseite behält vorherige Filterauswahl bei

Symptom: Die Seite API Logs zeigt nicht die erwarteten Protokolleinträge an, obwohl die API erfolgreich ausgeführt wird.
Mögliche Ursache: Die Seite API Logs speichert Filterauswahlen aus der vorherigen Sitzung. Ein zuvor angewendeter Filter kann die erwarteten Ergebnisse verbergen.
Lösung: Überprüfen Sie auf der Seite API Logs alle aktiven Filter und löschen Sie alle, die die erwarteten Einträge möglicherweise ausschließen.

Nicht veröffentlichte APIs werden nicht in der Analytics-APIs-Dropdown angezeigt

Symptom: Eine API wird nicht in der Dropdown-Liste APIs auf der Seite Analytics angezeigt, daher können Analysedaten für diese API nicht gefiltert werden.
Mögliche Ursache: Nur aktuell veröffentlichte APIs werden in der Dropdown-Liste APIs angezeigt. APIs, die nicht veröffentlicht wurden, werden in der Dropdown-Liste ausgeschlossen, auch wenn API-Protokolle für diese APIs vorhanden sind.
Lösung:
- Bestätigen Sie, dass die API veröffentlicht wurde. Um Analysedaten anzuzeigen, muss sich die API in einem veröffentlichten Zustand befinden.
- Um Protokolleinträge für eine unveröffentlichte API anzuzeigen, verwenden Sie stattdessen die Seite API Logs. Protokolldaten bleiben dort verfügbar, können aber nicht nach API-Name gefiltert werden.

Fehler 429: Monatliche API-Hit-Grenze überschritten

Symptom: Alle APIs in der Organisation geben plötzlich HTTP-429-Fehler zurück.
Mögliche Ursache: Die Organisation hat ihr monatliches API-Hit-Kontingent gemäß ihrer Lizenz ausgeschöpft. Wenn das Kontingent überschritten wird, werden alle API-Aufrufe für den Rest des Monats mit einer 429-Antwort abgelehnt.
Lösung:
- Überprüfen Sie die aktuelle Hit-Anzahl gegen Ihr monatliches Kontingent auf der APIs-Seite. Das Kontingent wird am ersten Tag des folgenden Monats zurückgesetzt.
- Um die Grenze zu vermeiden, konfigurieren Sie Ratenbegrenzungen auf Umgebungs- oder Sicherheitsprofilleene mit der Einstellung Hits pro Minute, um die Last zu verteilen und Verbrauchsgrenzen pro Consumer durchzusetzen.
- Um das monatliche Kontingent Ihrer Organisation zu erhöhen, wenden Sie sich an Ihren Customer Success Manager.

Fehler 429: Consumer-IP nicht im Bereich vertrauenswürdiger IPs

Symptom: Ein bestimmter Consumer oder eine Anwendung erhält HTTP-429-Fehler beim Aufrufen einer API, während andere Consumer dieselbe API erfolgreich aufrufen können.
Mögliche Ursache: Das der API zugewiesene Sicherheitsprofil hat vertrauenswürdige IP-Gruppen konfiguriert. Anfragen von IP-Adressen außerhalb der zulässigen Bereiche werden mit einer 429-Antwort abgelehnt.
Lösung:
1. Öffnen Sie das Sicherheitsprofil, das der API zugewiesen ist, und überprüfen Sie die Konfiguration seiner vertrauenswürdigen IP-Gruppe.
2. Fügen Sie die IP-Adresse oder den Adressbereich des Consumers zu einer bestehenden vertrauenswürdigen IP-Gruppe hinzu, oder erstellen Sie eine neue vertrauenswürdige IP-Gruppe, die die erforderlichen Adressen enthält.

Plattformweites Ratenlimit: 200 Anfragen pro Minute

Symptom: APIs, die auf dem von Jitterbit verwalteten Cloud-API-Gateway gehostet werden, werden bei hohem Datenverkehr gedrosselt oder mit einer 429 Too Many Requests-Antwort abgelehnt, selbst wenn die Rate Limits des Sicherheitsprofils nicht erreicht wurden.
Mögliche Ursache: Das von Jitterbit verwaltete Cloud-API-Gateway erzwingt ein plattformweites Limit von 200 API-Anfragen pro Minute pro Organisation, das über alle API-Typen (Custom, Proxy und OData) verteilt ist. Dieses Limit gilt nicht für private API-Gateways.
Lösung:
- Überprüfe die API-Verkehrsmuster und verteile Aufrufe zeitlich, falls möglich, um das Limit von 200 Anfragen pro Minute einzuhalten.
- Falls der Anwendungsfall einen anhaltenden Durchsatz über diesem Limit erfordert, stelle ein privates API-Gateway bereit, bei dem der Durchsatz durch die Kapazität des Host-Servers und nicht durch eine plattformweite Obergrenze bestimmt wird.

Zscaler oder SSL-abfangende Firewall blockiert API-Zugriff

Symptom: API-Aufrufe schlagen mit Zertifikatfehlern fehl, oder Backend-Endpunkte können nicht auf APIs zugreifen, die mit TLS gesichert sind, wenn sie durch ein von Zscaler verwaltetes oder ähnliches SSL-inspizierendes Netzwerk geleitet werden.
Mögliche Ursachen:
- Zscaler und ähnliche Sicherheitsproxys führen SSL/TLS-Inspektionen durch, indem sie HTTPS-Datenverkehr abfangen und ihn mit ihrem eigenen CA-Zertifikat neu signieren. Clientsysteme, die der Zscaler-Root-CA nicht vertrauen, lehnen die Verbindung ab.
- Das manuelle Importieren des Jitterbit-Zertifikats in den Vertrauensspeicher ist keine zuverlässige Lösung: Wenn Jitterbit sein Zertifikat erneuert, wird die manuell importierte Kopie veraltet und unterbricht die Verbindung erneut.
Lösung:
- Installiere das Zscaler-Root-CA-Zertifikat im Betriebssystem oder Browser-Vertrauensspeicher auf den Systemen, die die API-Aufrufe durchführen, damit von Zscaler neu signierte Zertifikate vertraut wird.
- Für Tools wie curl, wget oder openssl konfiguriere diese so, dass sie den im Zscaler-Umfeld definierten HTTP-Proxy verwenden.
- Fordere eine Zscaler-Richtlinienausnahme für die Jitterbit-API-Gateway-Hostnamen an, um die SSL-Inspektion für diese spezifischen Ziele zu umgehen.
- Überprüfe die Regeln in der PAC-Datei (Proxy Auto-Configuration) der Organisation, um zu bestätigen, dass Jitterbit-Endpunkte korrekt verarbeitet werden.
- Importiere das Jitterbit-Blatt-Zertifikat nicht manuell als Lösung in einen Vertrauensspeicher: Verwende stattdessen die Zscaler-Root-CA, um Probleme bei der Zertifikaterneurung durch Jitterbit zu vermeiden.

EDI

In diesem Abschnitt werden Probleme mit der EDI-Funktionalität von Harmony behandelt: die Kommunikation mit Handelspartnern und die Verarbeitung von EDI-Dokumenten.

AS2-Verbindungs- oder Zertifikatsfehler

Symptom: Ausgehende AS2-Übertragungen schlagen fehl oder Bestätigungen des Handelspartners werden nicht empfangen.
Mögliche Ursachen:
- Das AS2-Zertifikat ist abgelaufen oder wird vom Handelspartner nicht mehr als vertrauenswürdig eingestuft.
- Der Zertifikatsalgorithmus stimmt nicht mit den Anforderungen des Handelspartners überein (z. B. SHA-1 vs. SHA-256).
- Die AS2-Endpunkt-URL, die Partner-ID oder andere Verbindungsparameter sind falsch.
- Eine Firewall oder Netzwerkbeschränkung blockiert ausgehenden AS2-Datenverkehr auf Port 443 oder dem konfigurierten AS2-Port.
Lösung:
- Überprüfen Sie die AS2-Kommunikationseinstellungen für den betroffenen Handelspartner und bestätigen Sie, dass die Endpunkt-URL, Partner-IDs und Zertifikatseinstellungen korrekt sind.
- Überprüfen Sie das Zertifikatsverfallsdatum und erneuern Sie es, falls es abgelaufen ist. Tauschen Sie das aktualisierte Zertifikat mit dem Handelspartner aus.
- Bestätigen Sie, dass der Zertifikatsalgorithmus den Anforderungen des Handelspartners entspricht. Aktualisieren Sie den Algorithmus in den AS2-Einstellungen, falls erforderlich.
- Überprüfen Sie, dass ausgehender Datenverkehr zum AS2-Endpunkt des Handelspartners von Ihrer Netzwerk-Firewall zugelassen wird.

FTP- oder SFTP-Verbindungsfehler

Symptom: FTP- oder SFTP-Übertragungen zu oder von einem Handelspartner schlagen fehl oder Dateiübertragungen hängen fest und laufen ab.
Mögliche Ursachen:
- Die Serveradresse, der Port, die Anmeldedaten oder die Authentifizierungsmethode (Passwort vs. SSH-Schlüssel) sind falsch oder veraltet.
- Eine Firewall oder Netzwerkbeschränkung blockiert den erforderlichen Port zwischen Jitterbit EDI und dem FTP-/SFTP-Server.
- Das Zielverzeichnis existiert nicht oder das Dienstkonto hat keine Lese-/Schreibberechtigungen dafür.
- Der Host-Schlüssel auf dem SFTP-Server hat sich geändert, was zu einem Konflikt führt.
Lösung:
- Überprüfen Sie die FTP-Kommunikationseinstellungen für den betroffenen Handelspartner und überprüfen Sie alle Verbindungsparameter.
- Bestätigen Sie, dass die Konnektivität zur FTP-/SFTP-Serveradresse und zum Port durch die relevanten Firewalls zugelassen wird.
- Überprüfen Sie, dass das Dienstkonto die erforderlichen Berechtigungen für das Zielverzeichnis hat.
- Wenn Sie SSH-Schlüssel-Authentifizierung verwenden, bestätigen Sie, dass der Schlüssel aktuell ist und vom Server akzeptiert wird. Wenn sich der Host-Schlüssel geändert hat, aktualisieren Sie den Eintrag der bekannten Hosts.

VAN-Konnektivitätsprobleme

Symptom: EDI-Dokumente werden nicht über ein Value Added Network (VAN) zugestellt oder empfangen.
Mögliche Ursache: Eine VAN-Verbindung ist eine verwaltete Verbindung, die Jitterbit einrichtet; Sie können sie nicht selbst erstellen oder konfigurieren. Zustellungsfehler betreffen typischerweise die VAN-Verbindung, das Mailbox-Routing oder die Partnereinrichtung auf der Seite des Anbieters, nicht eine Self-Service-Einstellung in Jitterbit EDI.
Lösung:
- Bestätigen Sie, dass die richtige VAN-Verbindung dem betroffenen Handelspartner zugewiesen ist.
- Da die VAN-Verbindung nicht direkt von Jitterbit EDI aus konfiguriert werden kann, kontaktieren Sie den Jitterbit-Support oder Ihren Customer Success Manager, um die VAN-Verbindung und das Dokument-Routing zu überprüfen.
- Koordinieren Sie mit dem VAN-Anbieter, um zu bestätigen, dass die Mailbox-Identifikatoren und das Routing des Handelspartners auf der VAN-Seite korrekt sind.

Dokument abgelehnt: Ungültige oder fehlende Daten

Symptom: Ein ausgehendes EDI-Dokument wird vom Handelspartner abgelehnt oder validiert nicht, oder ein eingehendes Dokument erzeugt eine negative Bestätigung.
Mögliche Ursachen:
- Ein erforderliches Segment oder Datenelement fehlt im Dokument.
- Ein Feldwert überschreitet die zulässige Länge, verwendet einen falschen Datentyp oder enthält ungültige Zeichen.
- Der Interchange-Nutzungsindikator (ISA15) ist auf T (Test) statt auf P (Produktion) eingestellt, sodass der Handelspartner das Dokument ablehnt.
- Das Dokument entspricht nicht dem Implementierungsleitfaden des Handelspartners.
Lösung: Überprüfen Sie die abgelehnte Transaktion auf der Seite Transaktionen auf das im Fehler angegebene Segment oder Element, und führen Sie dann folgende Schritte durch:
- Für ein von Ihnen gesendetes Dokument vergleichen Sie es mit dem Implementierungsleitfaden des Handelspartners, um fehlende oder nicht konforme Felder zu identifizieren, und aktualisieren Sie dann die EDI-Zuordnung und die Einstellungen für den betroffenen Dokumenttyp, um konforme Ausgaben zu erzeugen.
- Für ein eingehendes Dokument, das vom Handelspartner gesendet wurde, teilen Sie den Validierungsfehler mit ihm, damit er sein ausgehendes Format korrigieren kann.

EDI-Zuordnungs- oder Schemafehler

Symptom: EDI-Dokumente werden mit falschen Inhalten, fehlenden Feldern oder einer unerwarteten Struktur generiert, oder eingehende Dokumente können nicht korrekt verarbeitet werden.
Mögliche Ursachen:
- Die EDI-Zuordnung oder das Schema ist veraltet und spiegelt nicht den aktuellen Implementierungsleitfaden oder die Anforderungen des Handelspartners wider.
- Quelldatenfelder sind falsch zugeordnet und erzeugen falsche Werte im Ausgabedokument.
- Datentypkonflikte, Sonderzeichen oder Codierungsprobleme in den Quelldaten verursachen Transformationsfehler.
Lösung:
1. Überprüfen Sie die EDI-Einstellungen für den betroffenen Handelspartner unter EDI-Einstellungen und stellen Sie sicher, dass die Zuordnung den aktuellen Implementierungsleitfaden widerspiegelt.
2. Validieren Sie, dass Quelldatenfelder den korrekten EDI-Segmenten und -Elementen zugeordnet sind.
3. Überprüfen Sie die Quelldaten auf Sonderzeichen, Codierungsprobleme oder unerwartete Werte, die Transformationsfehler verursachen könnten, und fügen Sie bei Bedarf Datenbereinigungs-Schritte hinzu.
4. Testen Sie mit einem repräsentativen Beispieldokument und verwenden Sie das Archiv, um die generierte Ausgabe mit der erwarteten Struktur zu vergleichen.

Falsche Handelspartner-Kennungen

Symptom: Dokumente werden falsch weitergeleitet, auf Umschlagebene abgelehnt oder vom Handelspartner nicht erkannt.
Mögliche Ursachen:
- Die Absender- oder Empfänger-EDI-ID, der Qualifizierer-Code oder andere Identifikatoren auf Umschlagebene stimmen nicht mit dem überein, was der Handelspartner erwartet.
- Die Konfiguration des Handelspartners wurde kürzlich aktualisiert, aber die Änderung wurde in Jitterbit EDI nicht angewendet.
Lösung:
1. Überprüfen Sie die Konfiguration des Handelspartners und bestätigen Sie, dass die EDI-ID und Qualifizierer-Codes mit den Werten übereinstimmen, die in der Einrichtungsdokumentation des Handelspartners angegeben sind.
2. Vergleichen Sie die Umschlag-Identifikatoren in einem abgelehnten Dokument (sichtbar im Archiv) mit den erwarteten Werten.
3. Aktualisieren Sie die Handelspartner-Einstellungen, wenn Identifikatoren falsch sind, und verarbeiten Sie dann die betroffenen Dokumente erneut oder senden Sie sie erneut.

Bestätigungen nicht konfiguriert oder nicht empfangen

Symptom: Erwartete 997 (X12) oder CONTRL (EDIFACT) Funktionsbestätigungen werden nicht gesendet oder empfangen, oder die Bestätigungsverarbeitung funktioniert nicht wie erwartet.
Mögliche Ursachen:
- Die Bestätigungsgenerierung oder -verarbeitung ist in den EDI-Einstellungen des Handelspartners deaktiviert.
- Der Bestätigungsdokumenttyp ist nicht in der Workflow-Konfiguration des Handelspartners enthalten.
- Der Handelspartner sendet keine Bestätigungen, oder seine Bestätigungen werden falsch weitergeleitet.
Lösung:
- Bestätigen Sie in den EDI-Einstellungen des Handelspartners, dass die Bestätigungsgenerierung und -verarbeitung für die relevanten Dokumenttypen aktiviert sind.
- Überprüfen Sie die Workflows verwalten-Konfiguration, um zu bestätigen, dass der Bestätigungsdokumenttyp im Workflow enthalten ist.
- Überprüfen Sie das Archiv, um festzustellen, ob Bestätigungen vom Handelspartner empfangen, aber nicht verarbeitet werden, oder überhaupt nicht ankommen.
- Wenn Bestätigungen nicht ankommen, koordinieren Sie mit dem Handelspartner, um zu bestätigen, dass diese an den korrekten Endpunkt gesendet werden.

AS2: Die Firewall des Handelspartners muss Jitterbit-IP-Adressen auf die Whitelist setzen

Symptom: Ein Handelspartner meldet, dass er Ihre AS2-Übertragungen nicht empfangen kann oder deren AS2-Bestätigungen kommen nie an, obwohl Ihre ausgehenden AS2-Einstellungen korrekt zu sein scheinen.
Mögliche Ursache: Die Firewall des Handelspartners erfordert eine explizite Allowlist für eingehenden Datenverkehr und hat die Jitterbit-EDI-IP-Adressen nicht hinzugefügt.
Lösung:
- Geben Sie die folgenden Jitterbit-EDI-IP-Adressen an Ihren Handelspartner weiter und fordern Sie ihn auf, diese für ein- und ausgehenden AS2-Datenverkehr auf die Allowlist zu setzen:
  - Nordamerika: 40.71.22.62
  - EMEA und APAC: 20.166.31.85
- Informationen zu Ihrer eingehenden AS2-Empfangs-URL und der entsprechenden IP-Adresse, die Sie Handelspartnern mitteilen können, finden Sie auf der Seite AS2-Kommunikationseinstellungen für Ihre Region.

Duplikatsprüfung gilt nicht für EDIXml- oder XCBL-Format

Symptom: Doppelte eingehende Dokumente werden mehrfach verarbeitet, obwohl die Einstellung Duplikatprüfung für die AS2-Verbindung des Handelspartners aktiviert ist.
Mögliche Ursache: Die Duplikatprüfung gilt nur für EDI-Format-Dokumente. Sie filtert keine Duplikate für EDIXml- oder XCBL-Austauschformate.
Lösung: Wenn eine Deduplizierung für EDIXml- oder XCBL-Workflows erforderlich ist, implementieren Sie Deduplizierungslogik in der Studio-Operation, die die eingehenden Dokumente verarbeitet (z. B. durch Überprüfung einer Transaktions-ID gegen einen Datensatz in einer Datenbank oder Cloud Datastore vor der Verarbeitung).

EDI für Cloud v2 schlägt auf einem privaten Agent hinter einer Firewall oder Proxy fehl

Symptom: Auf einem privaten Agent schlägt eine EDI for Cloud v2-Aktivität wie Get Document fehl, um Daten abzurufen (z. B. mit einem Fehler „Daten können nicht abgerufen werden"), obwohl der Verbindungstest erfolgreich ist und das gleiche Projekt auf einer Cloud-Agent-Gruppe funktioniert.
Mögliche Ursache: Der private Agent befindet sich hinter einer Firewall oder einem Proxy, der den ausgehenden Zugriff auf den Jitterbit eiCloud EDI-Service unter eicloudservice.com blockiert. Der EDI for Cloud v2-Connector ruft diesen Service auf (z. B. unter *.transactionapi.eicloudservice.com), um Daten abzurufen. Das Blockieren führt zum Fehler der Aktivität. Cloud-Agents sind nicht betroffen.
Lösung:
1. Fügen Sie eicloudservice.com und seine Subdomänen für den ausgehenden Zugriff auf der Firewall und dem Proxy des privaten Agents auf die Whitelist. Weitere Jitterbit-Domänen und IP-Adressen, die ein privater Agent für den ausgehenden Zugriff benötigt, finden Sie unter Whitelist-Informationen.
2. Wenn ein Proxy verwendet wird, bestätigen Sie, dass er auf dem privaten Agent korrekt konfiguriert ist und die Verbindung nicht beeinträchtigt.

Deaktiviertes EDI-Zugriffstoken führt zu `INVALID_TOKEN`-Fehler

Symptom: Operationen, die den EDI for Cloud v2-Connector verwenden, schlagen fehl mit:
```
Error opening connection. Exception is: Error code: INVALID_TOKEN
```
Mögliche Ursache: Das von der EDI for Cloud v2-Verbindung verwendete Zugriffstoken wurde auf der Seite „Zugriffstokens" der Management Console auf Inaktiv gesetzt.
Lösung: Suchen Sie auf der Seite „Zugriffstokens" das Token und setzen Sie seinen Status auf Aktiv.

Transformationsfehler: Nicht erkanntes Feld in EDI-Aktivität

Symptom: Eine Transformation mit einer EDI for Cloud v2-Aktivität (z. B. Transaktionen auflisten) schlägt mit einem JSON-Parsing-Fehler fehl, der auf einen nicht erkannten Feldnamen verweist, z. B.:
```
Unrecognized field "user_defined_field_1"
```
Mögliche Ursache: Die Version des auf dem Agent installierten EDI for Cloud v2-Connectors ist veraltet. Der Backend-EDI-Service gibt ein Feld zurück (z. B. user_defined_field_1), das die ältere Connector-Version nicht erkennt, sodass der Connector die Antwort nicht analysieren kann.
Lösung: Aktualisieren Sie den EDI for Cloud v2-Connector auf dem Agent auf die neueste Version, indem Sie Connector-Verfügbarkeit bestätigen und aktuell halten im Connector-Troubleshooting-Leitfaden befolgen. Wenn Sie auf der EDI for Cloud v2-Verbindung auf Verbindung testen klicken, wird die neueste Connector-Version auf den Agent heruntergeladen. Wenn die Organisationsrichtlinie Automatische Connector-Aktualisierung deaktivieren aktiviert ist, aktualisieren Sie stattdessen den Connector für die Agent-Gruppe auf der Seite Agents der Management Console.

Wiederholtes EDI-Segment oder -Schleife ordnet nur die letzte Iteration zu

Symptom: In einer Studio-Transformation werden wiederholte Segmente oder Schleifen in einem EDI-Dokument, das über den EDI for Cloud v2-Connector verarbeitet wird, nur in ihrer letzten Iteration abgebildet (frühere Iterationen werden verworfen), da die Kardinalität des Knotens im Aktivitätsschema des Connectors einfach (z. B. (0,1)) statt wiederholend ((1,many)) ist. Dies betrifft sowohl X12 (z. B. ein N9-Segment verschachtelt in einer LX-Schleife in einer 945) als auch EDIFACT (z. B. eine wiederholte CNI-Gruppe in einem IFCSUM).
Mögliche Ursache: Das vom EDI for Cloud v2-Connector bereitgestellte automatisch generierte Schema spiegelt nicht die korrekte Kardinalität für das betroffene Segment oder die Schleife wider. Das Rohdokument im EDI-Transaktionsspeicher enthält alle Iterationen, und ein manuell aus diesem Roh-XML erstelltes Schema bildet diese korrekt ab, was das Antwortschema des Connectors (nicht die Daten) als Ursache bestätigt.
Lösung:
1. Öffnen Sie die EDI for Cloud v2-Verbindung in Studio und aktualisieren Sie die Metadaten, um zu überprüfen, ob eine Schemakorrektur veröffentlicht wurde.
2. Wenn die Kardinalität nach der Aktualisierung immer noch falsch ist, exportieren Sie das Schema, aktualisieren Sie manuell das maxOccurs-Attribut des betroffenen Segments in einem externen XML-Editor und importieren Sie es als benutzerdefiniertes XSD erneut.

Hinzufügen von verschachtelten hierarchischen Schleifenebenen (HL) zu einer EDI-Transformation

Symptom: Beim Erstellen einer Studio-Transformation für einen EDI-Transaktionssatz, der hierarchische Schleifen verwendet (z. B. X12 870 4010VICS, das ähnlich wie die 856 strukturiert ist), zeigt das Schema aus der Send Document-Aktivität des EDI for Cloud v2-Connectors eine einzelne HL-Ebene, aber das Dokument, das Sie erstellen müssen, erfordert verschachtelte HL-Ebenen (z. B. eine HL-O-Bestellebene mit einer untergeordneten HL-I-Artikelebene).
Mögliche Ursache: Hierarchische Dokumente können HL-Ebenen in unterschiedliche Tiefen verschachteln, daher stellt das Schema des Connectors eine einzelne HL-Ebene bereit, die Sie in der Transformation replizieren, um die zusätzlichen Ebenen zu erstellen, die Ihr Dokument benötigt.
Lösung:
1. Klicken Sie im Zielschema-Baum der Transformation mit der rechten Maustaste auf den vorhandenen HL-Knoten und wählen Sie Knoten duplizieren, um die verschachtelte HL-Ebene hinzuzufügen (z. B. eine untergeordnete HL-I-Ebene unter HL-O).
2. Ordnen Sie den duplizierten Knoten Ihren Quelldaten zu. Fügen Sie eine Bedingung auf dem duplizierten Knoten hinzu, wenn dieser nur unter bestimmten Umständen in der Ausgabe erstellt werden soll.

EDI-ID-Überschreibungswerte werden nicht auf ausgehende Transaktionen angewendet

Symptom: Ausgehende Transaktionen verwenden die Standard-Sender- oder Empfänger-EDI-IDs aus der Handelspartnerkonfiguration anstelle der bevorzugten Überschreibungs-IDs, die in den EDI-ID-Einstellungen konfiguriert sind.
Mögliche Ursache: EDI-ID-Überschreibungen werden nicht automatisch angewendet. Die bevorzugten IDs müssen explizit in der Request-Transformation des Studio-Vorgangs zugeordnet werden, der das ausgehende Dokument mit dem EDI for Cloud v2-Connector sendet.
Lösung: Ordnen Sie in dieser Request-Transformation Werte diesen Feldern zu, um die bevorzugten IDs anzuwenden (siehe EDI-ID-Einstellungen-Seite für die genauen zu verwendenden Werte):
- ISA05_ID_Qualifier: Sender-ID-Qualifizierer
- ISA06_Sender_ID: Sender-EDI-ID
- ISA07_ID_Qualifier: Empfänger-ID-Qualifizierer
- ISA08_Receiver_ID: Empfänger-EDI-ID

Zugewiesene Kommunikationsverbindung kann nicht gelöscht werden

Symptom: Der Versuch, eine AS2- oder FTP-Verbindung in den Kommunikationseinstellungen zu löschen, schlägt fehl oder die Löschoption ist nicht verfügbar.
Mögliche Ursache: Zugewiesene Verbindungen können nicht gelöscht werden. Eine Verbindung, die derzeit einem Handelspartner zugewiesen ist, muss vor dem Löschen entfernt werden.
Lösung:
1. Wählen Sie in Kommunikationseinstellungen den Handelspartner aus, der die Verbindung nutzt, und weisen Sie diesem Partner eine andere Verbindung zu.
2. Sobald kein Partner die Verbindung mehr nutzt, wird die Löschoption verfügbar.

FTP-„Nächste Ausführungszeit" wird ohne Seitenaktualisierung nicht aktualisiert

Symptom: Die Nächste Ausführungszeit, die in den FTP-Kommunikationseinstellungen eines Handelspartners angezeigt wird, bleibt veraltet, nachdem der geplante FTP-Job ausgeführt wurde, obwohl der Zeitplan korrekt funktioniert.
Mögliche Ursache: Die Benutzeroberfläche aktualisiert den Status geplanter Aufträge nur beim Laden der Seite oder wenn eine manuelle Aktion ein Neuladen der Daten auslöst. Sie fragt die Engine nicht in Echtzeit ab.
Lösung:
- Aktualisieren Sie die Browserseite, um die Anzeige der Nächsten Ausführungszeit zu aktualisieren.
- Alternativ können Sie die FTP-Einstellungen verlassen und zurückkehren, um ein Neuladen zu erzwingen.

EDI-ID oder bevorzugte ID hinzufügen schlägt fehl: ID wird bereits verwendet

Symptom: Das Hinzufügen einer EDI-ID oder einer bevorzugten ID zu einem Handelspartner schlägt fehl, auch wenn die ID in der aktuellen Umgebung nicht verwendet zu werden scheint. Eine der folgenden Meldungen wird angezeigt:

EDI-ID [ID] kann nicht hinzugefügt werden, da es derzeit verwendet wird. Bitte bestätigen Sie und geben Sie eine eindeutige ID an.

Preferred ID [ID] kann nicht hinzugefügt werden, da es derzeit verwendet wird. Bitte bestätigen Sie und geben Sie eine eindeutige ID an.

Mögliche Ursachen:
- Jede EDI-ID muss in allen Harmony-Umgebungen eindeutig sein, in denen Jitterbit EDI aktiviert ist. Wenn dieselbe ID bereits einem Handelspartner in einer anderen Umgebung zugewiesen ist, schlägt das Hinzufügen fehl.
- Eine Preferred ID muss innerhalb der Umgebung eindeutig sein. Sie wird abgelehnt, wenn sie bereits demselben Handelspartner oder einem anderen Handelspartner in derselben Umgebung zugewiesen ist.
Lösung:
- Bei einer doppelten EDI-ID überprüfen Sie alle anderen Harmony-Umgebungen, in denen EDI aktiviert ist, um zu bestätigen, ob die ID dort bereits zugewiesen ist. Arbeiten Sie mit Ihrem Handelspartner zusammen, um eine eindeutige EDI-ID für jede Umgebung festzulegen, in der Sie Dokumente austauschen, und verwenden Sie eine unterschiedliche ID für Nicht-Produktionsumgebungen, die sich von Ihrer Produktions-EDI-ID unterscheidet.
- Bei einer doppelten Preferred ID überprüfen Sie die Liste Preferred ID (ISA ID's) für den aktuellen Handelspartner und für andere Handelspartner in derselben Umgebung, und wählen Sie dann eine eindeutige ID.

Ausgehende Dokumente bestehen die lokale Validierung, schlagen aber beim Test des Handelspartners fehl

Symptom: Ausgehende EDI-Dokumente bestehen die lokale Validierungsprüfung in Jitterbit EDI, werden aber beim Testen oder der Zertifizierung mit Handelspartnern abgelehnt, oft mit Fehlern zu fehlenden oder nicht konformen Elementen.
Mögliche Ursachen:
- Die ausgehende Validierung ist in der Workflow-Konfiguration deaktiviert. Jitterbit EDI ermöglicht die Generierung von Dokumenten ohne Validierung, aber ohne diese können Dokumente Elemente vermissen, die das Implementierungshandbuch des Handelspartners erfordert.
- Die EDI-Einstellungen decken die wesentlichen Elemente des Standards ab, aber das Implementierungshandbuch des Handelspartners kann zusätzliche obligatorische Elemente erfordern, die nicht durch Standardeinstellungen erzwungen werden.
Lösung:
- Aktivieren Sie in der Konfiguration Workflows verwalten die Validierung für den ausgehenden Workflow.
- Überprüfen Sie das Implementierungshandbuch des Handelspartners auf obligatorische Elemente über die Standard-EDI-Einstellungen hinaus und fügen Sie diese zur Zuordnung hinzu.
- Aktivieren Sie die Validierung immer vor dem Testen mit einem Handelspartner, es sei denn, Sie haben ein gründliches Verständnis der spezifischen EDI-Transaktion und der Anforderungen des Handelspartners.

Transaktion früher oder später als erwartet archiviert

Symptom: Eine Transaktion wird archiviert, bevor die erwartete Aufbewahrungsfrist endet, oder sie bleibt länger als erwartet verfügbar.
Mögliche Ursache: Transaktionen werden basierend auf dem späteren der beiden Daten archiviert: das Transaktionsdatum und das Dokumentdatum. Wenn das Dokumentdatum aktueller ist als das Transaktionsdatum, wird die Archivierung vom Dokumentdatum berechnet, was die Aufbewahrungsfrist verlängern kann.
Lösung:
- Überprüfen Sie bei der Untersuchung unerwarteter Archivierungszeitpunkte sowohl das Transaktionsdatum als auch das Dokumentdatum für die betroffene Transaktion.
- Überprüfen Sie die Aufbewahrungsfrist-Einstellungen, um die konfigurierte Anzahl von Tagen (30, 60 oder 90) zu bestätigen.

Zugriff auf EDI-Funktionen nicht möglich

Symptom: Ein Benutzer kann EDI-Seiten nicht anzeigen oder mit ihnen interagieren, oder bestimmte EDI-Aktionen sind nicht verfügbar.
Mögliche Ursachen:
- Der EDI-Zugriff erfordert sowohl eine EDI-spezifische Rollenberechtigung (Admin, EDI User oder EDI Viewer) als auch eine Umgebungszugriffsrolle auf Write-Ebene. Das Fehlen einer dieser Rollen verhindert den Zugriff.
- Die Rollen EDI User und EDI Viewer unterscheiden sich in ihren Berechtigungen. EDI Viewer kann Transaktionen erneut verarbeiten, Bestätigungen erneut senden und Seiten lesen, kann aber keine Konfigurationen erstellen oder aktualisieren oder Dateien hochladen. Das Erstellen oder Aktualisieren von Konfigurationen und das Hochladen von Dateien zur Verarbeitung erfordern die Rolle EDI User. Administrative Aktionen wie das Archivieren von Transaktionen, das Aktivieren von PII und das Ändern von Löscheinstellungen erfordern die Rolle Admin.
Lösung:
- Überprüfen Sie in der Management Console, dass der Benutzer eine Rolle mit der Berechtigung Admin, EDI User oder EDI Viewer hat.
- Bestätigen Sie, dass die Umgebungszugriffsstufe des Benutzers Write-Zugriff für die Umgebung umfasst, in der EDI konfiguriert ist.
- Wenn der Benutzer Schreibvorgänge durchführen muss (z. B. Handelspartner erstellen oder Dokumente hochladen), weisen Sie die Rolle EDI User statt EDI Viewer zu. Siehe EDI-Berechtigungen für die vollständige Berechtigungsmatrix.

PII-Einstellungen können nicht aktiviert werden

Symptom: Die Option zum Aktivieren von PII-Einstellungen (persönlich identifizierbare Informationen) für einen Handelspartner ist nicht verfügbar oder ausgegraut.
Mögliche Ursache: Das Aktivieren von PII-Einstellungen erfordert die Admin-Berechtigung. Weder die Rolle EDI User noch EDI Viewer kann PII-Einstellungen aktivieren.
Lösung:
- Bestätigen Sie, dass die Rolle des Benutzers die Admin-Berechtigung umfasst, nicht nur EDI User oder EDI Viewer.
- Wenn der Benutzer PII-Einstellungen regelmäßig verwalten muss, aktualisieren Sie die Rollenzuweisung entsprechend.

App-Entwicklung

In diesem Abschnitt werden Probleme mit der App-Entwicklungsfunktionalität von Harmony behandelt: Entwicklung, Bereitstellung und Ausführung von Anwendungen im App Builder.

App Builder startet nicht mit einem 500-Fehler

Symptom: App Builder startet nicht auf IIS und gibt einen HTTP 500-Fehler zurück.
Mögliche Ursache: Das ASP.NET Core Runtime Hosting Bundle, das App Builder benötigt, ist nicht auf dem Windows-Server installiert, daher kann IIS die Anwendung nicht starten.
Lösung:
1. Installieren Sie das von App Builder benötigte ASP.NET Core Runtime Hosting Bundle, wie in den Systemanforderungen aufgeführt.
2. Starten Sie IIS neu und überprüfen Sie, ob App Builder korrekt geladen wird.

App Builder startet nicht mit einem HTTP 500.30-Fehler

Symptom: App Builder startet nicht und gibt Folgendes zurück:
```
HTTP Error 500.30 - ASP.NET Core app failed to start
```
Mögliche Ursache: Die Identität des IIS-Anwendungspools hat keinen vollständigen Zugriff auf den App Builder-Stammordner, daher kann die Anwendung nicht starten.
Lösung:
1. Gewähren Sie der Identität des App Builder-Anwendungspools (standardmäßig IIS AppPool\Vinyl) Vollzugriff auf den App Builder-Stammordner. Siehe Berechtigungen festlegen.
2. Starten Sie den Anwendungspool neu und laden Sie App Builder dann neu.

App Builder gibt einen HTTP 503-Fehler zurück

Symptom: Das Öffnen von App Builder gibt folgende Meldung zurück:
```
HTTP Error 503. The service is unavailable.
```
Mögliche Ursache: Der IIS-Anwendungspool für App Builder ist beendet.
Lösung:
1. Öffnen Sie IIS Manager und wählen Sie Application Pools aus.
2. Wählen Sie den App Builder-Anwendungspool aus (standardmäßig Vinyl), und wählen Sie dann Start aus.
Hinweis

Wenn der Anwendungspool unmittelbar nach dem Start erneut beendet wird, schlägt App Builder wahrscheinlich beim Start fehl. Überprüfen Sie die Anwendungsprotokolle und die Windows-Ereignisanzeige auf den zugrunde liegenden Fehler.

App Builder startet, erstellt aber keine Datenbanken

Symptom: App Builder startet erfolgreich, aber es werden keine Datenbanken auf dem SQL Server erstellt.
Mögliche Ursache: Die Verbindungsdatei hat eine falsche Erweiterung (z. B. .txt statt .xml).
Lösung: Suchen Sie die App Builder-Verbindungsdatei und bestätigen Sie, dass sie die Erweiterung .xml verwendet. Benennen Sie die Datei um, wenn die Erweiterung falsch ist, und starten Sie App Builder neu. Wenn App Builder startet, aber einen Verbindungsfehler zurückgibt, anstatt stillschweigend keine Datenbanken zu erstellen, siehe Fehler beim Laden der Datenbankverbindungsinformationen.

Fehler beim Laden der Datenbankverbindungsinformationen

Symptom: App Builder gibt den folgenden Fehler zurück:

An error occurred while attempting to load the database connection information.

Mögliche Ursache: Die Datei Connection.xml fehlt oder enthält falsche Verbindungsdaten.
Lösung:
- Ersetzen oder aktualisieren Sie Connection.xml mit den korrekten Verbindungsdaten, und starten Sie App Builder neu. Siehe Verbindungsdatei erstellen.
- Wenn App Builder ohne Fehler startet, aber keine Datenbanken erstellt, siehe App Builder startet, erstellt aber keine Datenbanken.

App Builder lädt mit fehlender oder beschädigter Formatierung

Symptom: App Builder startet, aber Seiten werden mit fehlenden oder beschädigten Stilen (CSS) angezeigt.
Mögliche Ursache: Die Installations-ZIP-Datei wurde nicht entsperrt, bevor sie extrahiert wurde. Windows kennzeichnet Dateien, die von einem anderen Computer heruntergeladen wurden, als blockiert (das „Mark of the Web"), und das Extrahieren eines noch blockierten Archivs überträgt diese Kennzeichnung auf die extrahierten Dateien, was verhindern kann, dass die Style-Assets von App Builder korrekt geladen werden.
Lösung:
1. Löschen Sie die extrahierten Dateien.
2. Entsperren Sie die ursprüngliche ZIP-Datei: Klicken Sie mit der rechten Maustaste darauf, wählen Sie Eigenschaften aus, öffnen Sie die Registerkarte Sicherheit, und wählen Sie Entsperren aus. Siehe Software abrufen und entpacken.
3. Extrahieren Sie die ZIP-Datei erneut, und starten Sie dann die Installation oder das Upgrade neu.

Lizenz-Upload fehlgeschlagen

Symptom: Das Hochladen einer Lizenzdatei schlägt mit einem der folgenden Fehler fehl:

An unknown error occurred.

405 POST Method not allowed

Failed to deserialize license (d3fc6d4e835e)

Mögliche Ursache: WebDAV ist auf IIS installiert oder aktiviert und kann die POST-Anfrage beeinträchtigen, die zum Hochladen der Lizenz verwendet wird.
Lösung:
1. Deinstallieren oder deaktivieren Sie das WebDAV-Modul in IIS.
2. Versuchen Sie, die Lizenz erneut hochzuladen.
3. Wenn WebDAV für andere Anwendungen auf dem Server erforderlich ist, wenden Sie sich an den Jitterbit-Support, um Anleitung zur Konfiguration beider Dienste für die Koexistenz zu erhalten.

App Builder startet nach einem Serverneustart nicht automatisch

Symptom: App Builder wird nach einem Neustart des Windows-Servers nicht automatisch verfügbar und erfordert eine manuelle erste Anfrage zum Initialisieren der Anwendung.
Lösung: Weitere Schritte finden Sie unter Troubleshoot auto start behavior.

Docker-Bereitstellung: App Builder 4.x-Lizenz kann nicht in der Benutzeroberfläche hochgeladen werden

Symptom: Nach dem Upgrade von Vinyl 3.3 auf App Builder 4.x auf Docker schlägt das Hochladen der App Builder-Lizenz über die App Builder-Benutzeroberfläche fehl oder die Option ist nicht verfügbar.
Mögliche Ursache: App Builder 4.x Docker-Bereitstellungen unterstützen das Hochladen von Lizenzen über die Benutzeroberfläche nicht.
Lösung: Stellen Sie die Lizenz mit einer der folgenden Methoden bereit:
- Legen Sie in der Datei docker-compose.yml die Umgebungsvariable License__LicenseKey auf den base64-codierten App Builder 4.x-Lizenzschlüssel fest.
- Fügen Sie den Lizenzschlüssel zur Datei appsettings.json im Unterverzeichnis data des Docker Compose-Verzeichnisses hinzu.

Hochverfügbarkeit: Alle Instanzen müssen dieselbe `appsettings.json` verwenden

Symptom: Bei einer Hochverfügbarkeits-Bereitstellung verhalten sich einige App Builder-Knoten anders als andere (z. B. funktioniert die Authentifizierung auf einigen Knoten, aber nicht auf anderen, oder die Datenverschlüsselungsschlüssel sind über Knoten hinweg inkonsistent).
Mögliche Ursache: Jede Instanz von App Builder in einer Hochverfügbarkeitsbereitstellung muss eine identische appsettings.json-Konfigurationsdatei verwenden. Wenn sich die Dateien zwischen Instanzen unterscheiden, ist das Verhalten über Knoten hinweg inkonsistent.
Lösung:
- Bestätigen Sie, dass alle App Builder-Instanzen in der HA-Bereitstellung identische appsettings.json-Dateien haben.
- Wenden Sie nach einer Konfigurationsänderung auf einer Instanz die gleiche Änderung auf alle anderen Instanzen an und starten Sie jede neu.

SSO-Anmeldung fehlgeschlagen oder umgeleitet auf falsche URL

Symptom: Benutzer, die sich über Single Sign-On (SSO) anmelden möchten, erhalten einen Umleitungsfehler oder werden zu einer unerwarteten URL weitergeleitet.
Mögliche Ursachen:
- Der im Identity Provider (IdP) konfigurierte Redirect URI stimmt nicht mit der URL überein, die App Builder verwendet.
- Ein Reverse Proxy oder Load Balancer vor App Builder (z. B. IIS hinter einem F5) beendet TLS, sodass App Builder http sieht, während die öffentliche URL https verwendet. Der Redirect URI verwendet dann das falsche Protokoll und stimmt nicht mit dem im IdP registrierten Wert überein.
- Die SSO-Integrations-URL in App Builder verweist auf eine veraltete oder falsche Adresse.
- Der OpenID Connect-Sicherheitsanbieter in App Builder ist falsch konfiguriert.
Lösung:
- Bestätigen Sie im IdP (z. B. Okta oder Azure AD), dass der Redirect URI genau mit der App Builder-Anwendungs-URL übereinstimmt, einschließlich des Protokolls (https://) und aller Pfade.
- Überprüfen Sie in App Builder die Konfiguration des Sicherheitsanbieters in IDE > Security Providers und stellen Sie sicher, dass die OpenID Connect-Einstellungen mit den erwarteten Werten des IdP übereinstimmen.
- Wenn sich die App Builder-URL geändert hat (z. B. nach einer Migration oder Domänenaktualisierung), aktualisieren Sie den Redirect URI sowohl in App Builder als auch im IdP.

Symptom: Das Öffnen der Basis-URL einer App Builder-Umgebung (z. B. https://example.com/) leitet nicht zur Anmeldeseite um. Nicht authentifizierte Besucher werden direkt zu einer App weitergeleitet.
Mögliche Ursache: Der integrierte Benutzer anonymous hat Zugriff auf die Startseite einer App. App Builder leitet jeden Benutzer automatisch zu einer Startseite um, auf die er zugreifen kann. Wenn der Benutzer anonymous die Startseite einer App erreichen kann, werden alle nicht authentifizierten Besucher stattdessen dorthin umgeleitet, anstatt zur Anmeldeseite.
Lösung: Entfernen Sie den Zugriff des Benutzers anonymous auf die Startseite der App, damit nicht authentifizierte Besucher zur Anmeldeseite weitergeleitet werden.

Lokale Benutzer können ein vergessenes Passwort nicht zurücksetzen

Symptom: Lokale Benutzer können ein vergessenes Passwort nicht zurücksetzen. Der Link Passwort vergessen auf dem Anmeldebildschirm fehlt oder das Zurücksetzen wird nicht abgeschlossen.
Mögliche Ursache: Der Gruppe Anonyme Benutzer wurde kein Zugriff auf die Passwort-Zurücksetzen-Anwendung gewährt, daher können nicht authentifizierte Benutzer den Passwort-Zurücksetzen-Workflow nicht erreichen.
Lösung: Gewähren Sie der Gruppe Anonyme Benutzer Zugriff auf die Anwendung App Builder - Passwort zurücksetzen und fügen Sie sie zur Rolle Passwort zurücksetzen hinzu. Weitere Informationen finden Sie unter Passwort zurücksetzen mit den vollständigen Konfigurationsschritten, einschließlich der erforderlichen SMTP-Einrichtung.

App Builder ist langsam oder reagiert nicht

Symptom: App Builder reagiert langsam auf Benutzerinteraktionen, oder Seitenladezeiten und Abfragen überschreiten das Zeitlimit.
Mögliche Ursachen:
- Der App Builder-Server verfügt nicht über ausreichende CPU- oder Speicherressourcen für die aktuelle Last.
- Ein Netzwerkproblem zwischen dem Benutzer und dem App Builder-Server, z. B. begrenzte Bandbreite, Paketverlust oder eine Firewall, verlangsamt die Datenübertragung.
- Nicht optimierte Abfragen oder Anwendungslogik führen zu langsamen Seiten, oder ein Hintergrunddienst verbraucht übermäßig viele Ressourcen.
- Der IIS-Arbeitsprozess hat einen fehlerhaften Zustand erreicht.
- Ein lang laufender Vorgang hat das Zeitlimit eines Proxys, eines Load Balancers oder eines anderen Netzwerkgeräts zwischen dem Browser und App Builder überschritten, das dann die Verbindung zum Browser getrennt hat. Der Browser meldet einen Fehler wie 504 Gateway Timeout, aber der Vorgang wird weiterhin auf dem Server ausgeführt und kann nach dem Trennen des Browsers noch erfolgreich sein oder fehlschlagen.
Lösung:
- Überprüfen Sie die Ressourcenauslastung des Servers (CPU, Speicher, Festplatten-E/A), um eine Ressourcenauslastung zu ermitteln.
- Um ein Netzwerkproblem auszuschließen, stellen Sie eine Verbindung von einem anderen Netzwerk her (z. B. ein anderes WLAN oder ein Mobilgerät mit Mobilfunkverbindung) und führen Sie einen Internetgeschwindigkeitstest durch. Wenn sich die Leistung in einem anderen Netzwerk verbessert, ist die Ursache wahrscheinlich begrenzte Bandbreite, ein ISP-Problem oder eine Firewall und nicht App Builder selbst.
- Überprüfen Sie die Anwendungsprotokolle auf wiederkehrende Fehler, Zeitüberschreitungen oder Warnungen, die auf die Ursache hindeuten können.
- Wenn der Browser ein Gateway-Timeout gemeldet hat, verwenden Sie die Ereignisverlauf, um zu ermitteln, ob der Vorgang auf dem Server abgeschlossen wurde, bevor Sie ihn erneut versuchen. Da der Vorgang nach dem Trennen des Browsers weiterhin ausgeführt wird, kann ein erneuter Versuch die Arbeit duplizieren.
- Überprüfen Sie aktive Hintergrunddienste und den Ereignisverlauf auf lang laufende oder hängende Aufträge. Um langsame SQL-Abfragen speziell zu identifizieren, siehe Langsame Abfragen erfassen und analysieren.
- Bei langsamen Seiten, die durch nicht optimierte Abfragen oder Anwendungslogik verursacht werden, siehe App Builder-Leistungsoptimierung für Abfrageoptimierung, Indizierung und Anwendungsdesign-Richtlinien.
- Wenn der Server fehlerfrei aussieht, aber App Builder nicht reagiert, recyceln Sie den IIS-Anwendungspool für App Builder.
- Wenn das Problem zeitweilig auftritt und schwer zu diagnostizieren ist, rufen Sie einen Prozess-Dump zur weiteren Analyse ab. Siehe Dump-Datei abrufen.

Salesforce OAuth-Authentifizierung fehlgeschlagen oder authentifiziert mit der falschen Instanz

Symptom: Benutzer, die sich mit Salesforce SSO anmelden, werden unerwartet mit der falschen Salesforce-Instanz authentifiziert, oder Salesforce-Token funktionieren nicht mehr und Benutzer werden wiederholt zur erneuten Authentifizierung aufgefordert.
Mögliche Ursachen:
- Mehrere App Builder-Instanzen nutzen die gleiche Salesforce Connected App. Salesforce speichert nur die vier neuesten Aktualisierungstoken pro Connected App. Wenn ein fünftes Token ausgestellt wird, wird das älteste ungültig, wodurch die Instanz, die dieses Token hält, die Authentifizierung verliert.
- Mehrere Salesforce-Instanzen sind in App Builder konfiguriert, und der Browser des Benutzers hat bereits eine aktive Sitzung mit einer Salesforce-Instanz. Wenn der Benutzer versucht, sich bei einer zweiten Instanz anzumelden, verwendet Salesforce die vorhandene Sitzung erneut und meldet den Benutzer stattdessen bei der ersten Instanz an.
Lösung:
- Weisen Sie jeder App Builder-Instanz eine separate Salesforce Connected App zu, um Aktualisierungstokenkonfikte zu vermeiden. Weitere Informationen finden Sie in der Dokumentation zum Salesforce-Sicherheitsanbieter.
- Wenn ein Benutzer mit der falschen Salesforce-Instanz authentifiziert wird, melden Sie den Benutzer von allen aktiven Salesforce-Sitzungen im Browser ab, bevor Sie sich erneut anmelden.

Verschlüsselte Spaltenwerte erscheinen nach Neukonfiguration der Datenquelle leer

Symptom: Werte in einer verschlüsselten Spalte erscheinen in der Anwendung leer (null), nachdem eine Datenquelle, Tabelle oder Spalte gelöscht und neu erstellt wurde oder nachdem die App Builder-Umgebung aktualisiert oder migriert wurde.
Mögliche Ursachen:
- App Builder leitet den Verschlüsselungsschlüssel jeder Spalte aus den Werten DataSourceId, TableId und ColumnId im logischen Modell ab. Wenn sich einer dieser Identifizierer ändert (z. B. nach dem Löschen und Neuerstellen einer Datenquelle, Tabelle oder Spalte), können vorhandene verschlüsselte Werte nicht mehr entschlüsselt werden. Es wird kein Fehler angezeigt: Der Wert erscheint stillschweigend als null.
- Bei einer Aktualisierung oder Migration wurde der Ordner keys aus der vorherigen Installation nicht in den neuen Installationsordner kopiert, sodass App Builder nicht auf das Schlüsselmaterial zugreifen kann, das zum Entschlüsseln vorhandener Werte erforderlich ist.
Lösung:
- Wenn verschlüsselte Werte nach einer Aktualisierung oder Migration leer erscheinen, bestätigen Sie, dass der Inhalt des Ordners keys aus dem vorherigen Installationsordner in den neuen kopiert wurde. Siehe Schritt 5 von Einstellungen wiederherstellen.
- Um Datenverluste durch Identifiziereränderungen zu vermeiden, vermeiden Sie das Löschen und Neuerstellen von Datenquellen, Tabellen oder verschlüsselten Spalten, die Daten enthalten. Eine vollständige Liste der Verschlüsselungsbeschränkungen finden Sie unter Verschlüsselung auf Anwendungsebene.
- Exportieren oder sichern Sie vor strukturellen Änderungen alle verschlüsselten Spaltenwerte.
- Wenn sich die Identifizierer bereits geändert haben und die Daten nicht aus einer Sicherung wiederhergestellt werden können, kontaktieren Sie den Jitterbit-Support mit Details der ursprünglichen Konfiguration.

Audit-Protokoll-Grundlinie wird nicht gefüllt

Symptom: Das Füllen der Vollständigen Audit-Baseline wirft einen Fehler aus und die Baseline wird nicht erstellt.
Mögliche Ursache: Die Tabelle hat keinen einteiligen UUID-Primärschlüssel. Vollständiges Audit erfordert eine eindeutige UUID für jeden Datensatz, daher werden Tabellen mit einem zusammengesetzten (mehrteiligen) Primärschlüssel standardmäßig nicht überwacht. Um eine solche Tabelle zu überwachen, müssen Sie zunächst eine UUID-Auditspalte hinzufügen.
Lösung:
1. Fügen Sie der Tabelle eine UUID-Spalte hinzu und legen Sie ihren Spaltennutzungstyp auf Audit fest. Füllen Sie sie dann für vorhandene Datensätze auf. Das vollständige Verfahren finden Sie unter Andere Primärschlüsselkonfigurationen.
2. Navigieren Sie zu Aktionsleiste > IDE > Zusätzliche Einstellungen und klicken Sie auf die Schaltfläche Audit-Datensätze füllen.
3. Suchen Sie die Datenquelle der App, klicken Sie auf Alle füllen (oder Füllen bei einzelnen Tabellen) und klicken Sie dann auf Fortfahren, um es erneut zu versuchen.

Hinweis

Full Audit schlägt bei großen oder binären Spalten nicht fehl. Zeichenkettenwerte, die länger als 700 Zeichen sind, werden geprüft, aber über 700 Zeichen hinaus gekürzt, und binäre Spalten werden nach Dateigröße statt nach Inhalt geprüft.

SharePoint-Dateisystem: OAuth-Authentifizierung ab April 2026 erforderlich

Symptom: SharePoint-Dateisystem-Verbindungen können sich nicht authentifizieren oder lassen sich nicht erstellen.
Mögliche Ursache: Ab dem 30. April 2026 erfordern SharePoint-Dateisystem-Verbindungen OAuth-Authentifizierung. Verbindungen mit Legacy-Authentifizierung funktionieren nicht mehr.
Lösung:
1. Aktualisieren Sie auf App Builder 4.61 oder später.
2. Folgen Sie dem Microsoft SharePoint OAuth-Verbindungsleitfaden, um einen OAuth-Sicherheitsanbieter zu konfigurieren, bevor Sie den Datenserver erstellen oder aktualisieren.

SharePoint-Dateisystem: Dateien nicht angezeigt oder Pfade geben Fehler zurück

Symptom: Eine SharePoint-Dateisystem-Datenquelle ist erfolgreich verbunden, aber Dateien werden nicht angezeigt, Inhalte werden nicht gerendert, oder ein Verzeichnispfad verursacht einen Fehler.
Mögliche Ursachen:
- App Builder kann nur auf Dateien zugreifen, die im Verzeichnis Dokumente gespeichert sind. Dateien in anderen SharePoint-Verzeichnissen sind nicht zugänglich.
- Dateinamen unterscheiden zwischen Groß- und Kleinschreibung beim Binden zwischen Datenquellen. Eine Abweichung in der Schreibweise zwischen dem SharePoint-Dateinamen und dem in einer anderen Datenquelle verwendeten Namen verhindert das Rendern von Inhalten.
- Die Verwendung eines Schrägstrichs (/) in einem Verzeichnispfad in einem Geschäftsobjekt verursacht einen Fehler.
Lösung:
- Bestätigen Sie, dass die Dateien im Verzeichnis Dokumente in SharePoint gespeichert sind.
- Überprüfen Sie, dass Dateinamen, die in Geschäftsobjekten und Datenquellenbindungen verwendet werden, exakt der Schreibweise der SharePoint-Dateinamen entsprechen.
- Verwenden Sie beim Angeben eines Verzeichnispfads in einem Geschäftsobjekt Backslashes (\\) statt Schrägstriche (/). Verwenden Sie beispielsweise \documents\employees statt /documents/employees.

App Builder Connector: Generierter API-Schlüssel kann nach Verlassen des Bildschirms nicht abgerufen werden

Symptom: Ein Connector-Benutzer hat den App Builder Connector eingerichtet, aber der API-Schlüsselwert ist nach dem Navigieren weg vom Bildschirm zur Schlüsselerzeugung nicht mehr verfügbar.
Mögliche Ursache: Der generierte API-Schlüssel wird nur einmal auf dem Bildschirm Schlüssel generieren angezeigt. Nach dem Verlassen des Bildschirms kann der Wert nicht abgerufen werden.
Lösung:
- Kopieren Sie den Schlüsselwert sofort nach der Generierung in die Zwischenablage, bevor Sie navigieren.
- Wenn der Schlüssel nicht kopiert wurde, generieren Sie einen neuen Schlüssel.

App Builder Connector: 403 Forbidden-Fehler

Symptom: Die Verbindung zu einer Remote-App Builder-Umgebung mit dem App Builder Connector gibt einen Fehler 403 Forbidden zurück.
Mögliche Ursache: Das für den Connector konfigurierte Benutzerkonto wurde in der Quell-App Builder-Umgebung nicht die Rolle App Builder Remote Connector zugewiesen.
Lösung:
1. Öffnen Sie in der Quell-App Builder-Umgebung das vom Connector verwendete Benutzerkonto.
2. Weisen Sie diesem Benutzer die Rolle App Builder Remote Connector zu.

Webhook: HTTP Basic Auth erfordert den Authorization-Header in der Payload

Symptom: Ein Webhook mit HTTP Basic Auth verarbeitet eingehende Payloads nicht korrekt.
Mögliche Ursache: Die HTTP Basic Auth-Methode erfordert, dass der Authorization-Header in der empfangenen Payload vorhanden ist. Systeme von Drittanbietern, die diesen Header weglassen, authentifizieren sich nicht korrekt.
Lösung: Verwenden Sie stattdessen die API Key-Authentifizierungsmethode für den Webhook-Sicherheitsanbieter. Die API Key-Methode erfordert den Authorization-Header nicht und ist breiter kompatibel mit externen Webhook-Sendern.

Datumsmigration läuft bei großen Datenmengen ab

Symptom: Ein Datenmigrations-Vorgang wird nicht abgeschlossen und schlägt mit einem Timeout-Fehler fehl.
Mögliche Ursache: Datenmigrationen werden während eines App- oder Datenquellen-Upgrades als einzelne Datenbanktransaktion ausgeführt. Bei großen Datenmengen kann die Transaktion das Standard-Befehlstimeout der Datenbank überschreiten.
Lösung: Erhöhen Sie in der App Builder-Datei Connection.xml den Wert CommandTimeOut, um mehr Zeit für die Migrationstransaktion zu ermöglichen.

App Builder-Anwendungsserver und Datenbankserver müssen die gleiche Zeitzone verwenden

Symptom: DateTime-Werte in der Anwendung sind um unerwartete Offsets verschoben, oder in App Builder angezeigte Zeiten unterscheiden sich von denen in der Datenbank.
Mögliche Ursache: Der App Builder-Anwendungsserver und der Datenbankserver sind mit unterschiedlichen Zeitzonen konfiguriert. Diese Server müssen synchronisiert sein, damit DateTime-Werte korrekt angezeigt werden.
Lösung:
1. Bestätigen Sie, dass der App Builder-Anwendungsserver und alle Datenbankserver auf die gleiche Zeitzone eingestellt sind.
2. Legen Sie in App Builder die Default Data Source Time Zone auf jedem Datenbankserver und die Time Zone auf jeder Datenquelle fest, um die Zeitzone des Datenbankservers zu entsprechen. Siehe Zeitzonen für Konfigurationsschritte.

SMTP-Konfigurationsfehler

Symptom: App Builder kann E-Mail-Benachrichtigungen nicht senden, und die Anwendungsprotokolle oder die Ausgabe von Test Email zeigen einen der folgenden Fehler:

Argument passed in is not serializable. Parameter name: value

Value cannot be null. ParameterName: From Address

Unknown URI scheme. Parameter name: uri

Authentication required

Mögliche Ursachen:
- Das Feld From Address des SMTP-Benachrichtigungsservers ist leer, null oder verwendet eine ungültige E-Mail-Adresse (erzeugt die ersten beiden oben genannten Fehler).
- Das Feld URI verwendet ein ungültiges Format oder ein nicht unterstütztes Schema (erzeugt den Fehler „Unknown URI scheme"). Der URI muss das Schema smtp:// oder smtps:// verwenden, z. B. smtp://mail.example.com:587.
- Die Felder UserName oder Password enthalten falsche Anmeldedaten (erzeugt den Fehler „Authentication required").
Lösung: Öffnen Sie in der IDE aus den Connect-Optionen Notification Servers, öffnen Sie dann den SMTP-Serverdatensatz und überprüfen Sie das Feld, das dem erhaltenen Fehler entspricht:
- Überprüfen Sie, dass die From Address eine gültige E-Mail-Adresse ist, die zum Versenden von E-Mails über den konfigurierten SMTP-Host berechtigt ist.
- Überprüfen Sie, dass der URI das Format smtp://<hostname>:<port> oder smtps://<hostname>:<port> verwendet. Siehe SMTP konfigurieren für unterstützte Protokolle und Format.
- Überprüfen Sie, dass UserName und Password den SMTP-Serveranmeldedaten entsprechen.
- Verwenden Sie nach einer Änderung die Funktion Test Email im Benachrichtigungsserver-Popup, um die Einstellungen zu bestätigen, bevor Sie sie in einem Workflow bereitstellen.

Deep Links funktionieren nicht mehr, nachdem eine App oder Seite umbenannt wurde

Symptom: Ein Deep Link, der Benutzer zuvor zu einer bestimmten Anwendung oder Seite geleitet hat, funktioniert nicht mehr.
Mögliche Ursache: Das Umbenennen einer Anwendung oder Seite im App Builder ändert den URL-Pfad, der in Deep Links verwendet wird. Alle vorhandenen Links, die den alten Anwendungs- oder Seitennamen enthalten, sind nicht mehr gültig.
Lösung:
- Aktualisieren Sie alle externen Systeme, E-Mails, Portale oder Lesezeichen, die die alte Deep-Link-URL enthalten, um den neuen Anwendungs- oder Seitennamen zu verwenden.
- Erstellen Sie den neuen Deep Link, indem Sie im App Builder zur Zielseite navigieren, die URL aus der Adressleiste des Browsers kopieren und dann die Abfragezeichenfolge (alles ab ? an) entfernen, um die kanonische URL zu erhalten.
- Um dieses Problem in Zukunft zu vermeiden, verwenden Sie das Feld Label für Anzeigenamen und halten Sie das Feld Name (das den URL-Pfad bestimmt) kurz und stabil.

Ein Ereignis wird mehrfach beim Speichern, Einfügen, Aktualisieren oder Löschen ausgelöst

Symptom: Ein Ereignis, das einmal ausgelöst werden sollte, wird bei derselben Benutzeraktion mehrmals ausgelöst, was zu doppelten Datensätzen, doppelten Benachrichtigungen oder anderen wiederholten Nebenwirkungen führt.
Mögliche Ursachen:
- Die Aktion oder Validierung des Ereignisses ist gleichzeitig in der Datenschicht und der Geschäftslogikschicht registriert. Der App Builder erlaubt diese Konfiguration, löst das Ereignis aber einmal pro Schichtregistrierung aus.
- Die Bindung der Aktion ist ungebunden oder an mehr als einen Datensatz gebunden. Die Aktion wird einmal für jeden Datensatz im Gültigkeitsbereich ausgelöst.
Lösung: Öffnen Sie die App Workbench, suchen Sie die Konfiguration des Ereignisses und beheben Sie die zutreffende Ursache:
- Bestimmen Sie, ob die Logik in der Datenschicht (für tabellenweites Verhalten) oder in der Geschäftslogikschicht (für seitenbezogenes Verhalten) gehört. Weitere Informationen finden Sie unter Ereignisse konfigurieren, und entfernen Sie die doppelte Registrierung aus der Schicht, zu der sie nicht gehört.
- Überprüfen Sie die Bindung der Aktion. Wenn sie ungebunden oder an mehr als einen Datensatz gebunden ist, beschränken Sie sie auf den einzelnen beabsichtigten Datensatz. Siehe Implizite und explizite Bindung.

Benutzer können auf erwartete Seiten oder Funktionen nicht zugreifen

Symptom: Ein HTML-Icon-Steuerelement auf einer Seite respektiert die Rollenberechtigung eines Benutzers nicht. Beispielsweise bleibt ein Symbol, das für Benutzer ohne Berechtigung deaktiviert sein sollte, aktiv.
Mögliche Ursache: HTML-Icons verhalten sich wie Schaltflächen. Ohne ein zugeordnetes Ereignis gelten rollenbasierte Berechtigungen nicht für das Symbol, daher bleibt es unabhängig von der Benutzerrolle sichtbar und aktiv.
Lösung:
1. Ordnen Sie dem HTML-Icon-Steuerelement ein leeres Ereignis zu, damit die rollenbasierte Sichtbarkeit gilt.
2. Geben Sie die entsprechende Zugriffsberechtigung (beispielsweise Aktualisieren) in der Rolle für die Benutzer an, die das Symbol sehen sollen.

Audit-Symbol wird auf einer Seite nicht angezeigt

Symptom: Die Schaltfläche oder das Symbol „Audit" zum Anzeigen von Vollständigen Audit-Protokollen ist auf einem Formular- oder Raster-Panel nicht sichtbar.
Mögliche Ursachen:
- Der Benutzer gehört nicht zur Rolle App Builder - Administratoren oder App Builder - Audit an.
- Das Seiten-Panel hat Audit anzeigen nicht aktiviert, oder das Panel ist kein Formular- oder Raster-Panel.
Lösung:
- Bestätigen Sie, dass der Benutzer zur Rolle App Builder - Administratoren oder App Builder - Audit gehört. Siehe Sicherheit.
- Aktivieren Sie auf einem Formular- oder Raster-Panel die Option Audit anzeigen für das Seiten-Panel. Siehe Vollständiges Audit auf einer Seite aktivieren.

Offline-App: Lokale Datenbank wird beim App-Update gelöscht

Symptom: Nach dem Upgrade einer Offline-App sind alle lokal gespeicherten Daten auf dem Mobilgerät weg.
Mögliche Ursache: Die lokale Datenbank einer Offline-App wird bei jedem App-Upgrade gelöscht. Dies ist eine bekannte Einschränkung von Offline-Apps.
Lösung:
- Stellen Sie sicher, dass alle lokal erfassten Daten vollständig mit dem Server synchronisiert werden, bevor ein App-Upgrade bereitgestellt wird.
- Informieren Sie Benutzer im Voraus über geplante Upgrades, damit diese vor dem Upgrade synchronisieren können.

Offline-App: Hintergrund-Zeitpläne werden nicht ausgeführt, wenn die App geschlossen ist

Symptom: Geplante Aufgaben oder Hintergrundprozesse in einer Offline-App werden auf einem Mobilgerät nicht wie erwartet ausgeführt.
Mögliche Ursache: Hintergrundpläne werden nicht ausgeführt, wenn die App Builder App auf dem Mobilgerät geschlossen ist. Pläne werden nur ausgeführt, während die App offen ist.
Lösung:
- Informieren Sie Benutzer, dass die geplante Hintergrundverarbeitung erfordert, dass die App offen bleibt.
- Gestalten Sie Workflows, die von Hintergrundplänen abhängen, so um, dass sie durch Benutzerinteraktion ausgelöst werden, oder verschieben Sie die geplante Verarbeitung auf die Serverseite.

Mobile App friert ein, stürzt ab oder hat Linkprobleme

Informationen zu Problemen mit der mobilen App Builder-App finden Sie unter Fehlerbehebung für mobile Apps.

Informationen zu Widget-Konfiguration und ZIP-Datei-Problemen finden Sie unter Widget-Fehlerbehebung.

Fehlerbehebung in Jitterbit Harmony

Diagnoseabläufe

Überprüfe die Operationsprotokolle

Überprüfe die API-Protokolle

Überprüfe die Agent-Protokolle

Harmony-Systemstatus prüfen

Plattformverwaltung

Anmeldung bei Harmony nicht möglich

Konto nach fehlgeschlagenen Anmeldeversuchen gesperrt

Benutzer kann nicht auf eine Umgebung oder deren Funktionen zugreifen

Projektvariablen werden bei Umgebungspromotion nicht übernommen

Umschalten der Agent-Gruppe einer Umgebung schlägt mit Fehler für Mindestversion des Agenten fehl

Design Studio: SSO-Benutzer außerhalb der Region der Organisation können sich nicht anmelden

SSO-Konfigurationstest sperrt das Identitätsanbieter-Konto

IP-Zulassungsliste sperrt einen Administrator

Ändern der API-Subdomain bricht bestehende API-Integrationen

Der Zugriff eines externen Benutzers auf das API Portal läuft zu einem unerwarteten Zeitpunkt ab

Umgebungsänderungen werden nicht in Harmony-Anwendungen angezeigt

SSO-Konfiguration erfordert sowohl WMC- als auch Studio-Clients

SSO-Umgehungsliste: Vorhandene Organisationsmitglieder können nicht direkt hinzugefügt werden

SSO kann nicht aktiviert werden: Benutzer gehört zu mehreren Organisationen

SSO-Anmeldung leitet in einer Schleife um ohne Fehlermeldung

Das Löschen des Cloud-Datastore-Speichers schlägt mit der Fehlermeldung „cannot be excluded" fehl

OAuth-Refresh-Token-Ablauf führt zu Fehler bei verbundenen Operationen

Audit Log API: Token-Abruf schlägt fehl, wenn TFA aktiviert ist

Das Hinzufügen eines externen Benutzers schlägt mit einem Fehler 409 conflict fehl

Organisation-Region kann nicht vor Ort geändert werden

Integration und Automatisierung

Vorgänge im Status „Submitted" oder „Running" feststecken

Geplante Vorgänge werden nicht ausgeführt

Wörterbuch oder globale Variable ist leer, nachdem ein Vorgang asynchron ausgeführt wird

504 Gateway Timeout (API-ausgelöste Vorgänge)

507 Speicher unzureichend

502 Bad Gateway

Fehler beim Erstellen eines temporären Verzeichnisses

Operationsprotokolle auf etwa 100 KB gekürzt

Das Debugging-Protokoll für Operationen enthält personenbezogene Daten und Anmeldeinformationen im Klartext

Verbindungsfehler bei der privaten Agent-Datenbank

Clientzertifikat lässt sich auf Linux-Private-Agenten nicht laden

Validierungsfehler für Operationen

Komponentennamen müssen nach dem Projektimport eindeutig sein

Connector nur für Private Agent blockiert den Import in eine Cloud-Agent-Umgebung

Zielschleifenknoten mehreren Quellenschleifenknoten zugeordnet

Erweiterte Konfigurationseigenschaften: Variablen mit unverarbeiteter JSON müssen mit Escape-Zeichen versehen werden

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

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

Sonderzeichen in Connector-bereitgestellten JSON-Schemata

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

Gespiegelte Schemata mit Substitutionsgruppen

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

Zusätzliche Unterelementwarnung in Operationsprotokollen

Wiederholungsgrenzwert für Skriptschleife überschritten

RunOperation wird nach 50 synchronen Aufrufen in einer While-Schleife nicht mehr ausgeführt

Ein String wird mit einer Zahl verglichen und führt zu unerwarteten Ergebnissen

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

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

Leere zugeordnete Felder mit flachen Quellschemas

Dateifunktionen: Der Betrieb wird nach ArchiveFile- oder ReadFile-Fehler fortgesetzt

ReadFile: Teilweises Lesen mit Binärdateiinhalten

ReadFile-Inhalte mit nicht-UTF-8-Bytes schlagen fehl, wenn sie einer UTF-8-XML- oder JSON-Payload zugeordnet werden

FlushFile / FlushAllFiles: Fehler, wenn die Zieldatei bereits vorhanden ist

DeleteFiles: Fehler, wenn der Quellpfad nicht gefunden wird

GetJSONString: Die Ausführung wird bei ungültigem Pfad unterbrochen

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

DBExecute: Fehler, wenn auto_commit und transaction beide true sind

CallStoredProcedure: resultSet ist mit ODBC-Treibern immer null

CallStoredProcedure: „Gespeicherte Prozedur oder Funktion konnte nicht gefunden werden" mit PostgreSQL JDBC

DBLoad: Erfordert einen JDBC-Datenbanktreiber

AESDecryption schlägt fehl mit Daten, die unter OpenSSL 3 verschlüsselt wurden

Variablenupdates gehen in mehrstufigen Multi-Thread-Vorgängen verloren

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

Lange numerische IDs werden in der Transformationsausgabe beschädigt

JSON-Transformationsausgabe lässt null- und Leerstring-Felder weg

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

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

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

Eine Funktion schlägt fehl, wenn ihr Endpunktverbindungsfeld auf eine Variable gesetzt ist

IsNull gibt false für leere Zeichenketten aus JSON-Quelldaten zurück

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

Dezimalarithmetik erzeugt unerwartete Gleitkommaaergebnisse

Das Hinzufügen eines externen Benutzers schlägt mit einem Fehler `409 conflict` fehl

`RunOperation` wird nach 50 synchronen Aufrufen in einer `While`-Schleife nicht mehr ausgeführt

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

Dateifunktionen: Der Betrieb wird nach `ArchiveFile`- oder `ReadFile`-Fehler fortgesetzt

`ReadFile`: Teilweises Lesen mit Binärdateiinhalten

`ReadFile`-Inhalte mit nicht-UTF-8-Bytes schlagen fehl, wenn sie einer UTF-8-XML- oder JSON-Payload zugeordnet werden

`FlushFile` / `FlushAllFiles`: Fehler, wenn die Zieldatei bereits vorhanden ist

`DeleteFiles`: Fehler, wenn der Quellpfad nicht gefunden wird

`GetJSONString`: Die Ausführung wird bei ungültigem Pfad unterbrochen

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

`DBExecute`: Fehler, wenn `auto_commit` und `transaction` beide `true` sind

`CallStoredProcedure`: `resultSet` ist mit ODBC-Treibern immer null

`CallStoredProcedure`: „Gespeicherte Prozedur oder Funktion konnte nicht gefunden werden" mit PostgreSQL JDBC

`DBLoad`: Erfordert einen JDBC-Datenbanktreiber

`AESDecryption` schlägt fehl mit Daten, die unter OpenSSL 3 verschlüsselt wurden

JSON-Transformationsausgabe lässt `null`- und Leerstring-Felder weg

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

`IsNull` gibt false für leere Zeichenketten aus JSON-Quelldaten zurück

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

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

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

Die Ausgabe von `HexToBinary` erscheint beim Protokollieren unverändert

`SortArray` sortiert Dateinamen lexikografisch, nicht chronologisch

`URLEncode` kodiert bestimmte „sichere" oder Multi-Byte-Zeichen nicht

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

Datenbank (JDBC): `DBLookup` oder `DBExecute` schlägt mit Base64-Decodierungsfehler fehl

FTP: Dateinamen mit `#` werden nicht korrekt verarbeitet

HTTP v2: Leerzeichen werden als `+` statt `%20` codiert

HTTP und HTTP v2: URL enthält mehrere `?`-Zeichen

HTTP: Sendet `null` als die Zeichenkette `"null"`