Fehlerbehebung in Jitterbit Harmony

Dieser Leitfaden behandelt häufige Probleme bei der Fehlerbehebung auf der einheitlichen Harmony-Plattform (Integration, Automatisierung, API-Verwaltung, EDI und App-Entwicklung), organisiert nach Funktionen, damit Sie Probleme überall finden und beheben können. Erweitern Sie die Liste unten, um jeden Eintrag auf dieser Seite zu durchsuchen, oder verwenden 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 Einträge zur Fehlerbehebung auf dieser Seite

Plattformverwaltung
Integration und Automatisierung

API-Verwaltung
EDI
App-Entwicklung

Diagnoseschritte

Betriebsprotokolle prüfen

Öffnen Sie in der Management Console die Seite Runtime und überprüfen Sie den Logeintrag für den betroffenen Vorgang. Der Status und alle Loggingmeldungen sind der primäre Indikator für die Ursache. Die Seite Runtime listet alle Vorgänge auf, einschließlich derjenigen, die direkt ausgeführt werden, und derjenigen, die durch eine API ausgelöst werden (in der Spalte Log Type als Custom API, Proxy API oder OData API angezeigt), daher ist sie der Ausgangspunkt für die meisten Laufzeitprobleme.

API-Protokolle prüfen

Für API-spezifische Details öffnen Sie die Seite API Logs im API Manager. Sie zeigt die Request- und Response-Daten jedes API-Aufrufs (HTTP-Statuscode, Antwortzeit, Request-URI, Quell-IP) und bei Aktivierung Debug- und ausführliche Traces. Betriebsprotokolle für API-ausgelöste Vorgänge erscheinen hier auch neben der Runtime-Seite.

Agent-Protokolle prüfen

Überprüfen Sie für 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 Operationen oder alle APIs statt nur einen einzelnen Workflow zu beeinträchtigen scheint, prüfen Sie trust.jitterbit.com und die Seite Bekannte Probleme bevor Sie weitere Untersuchungen durchführen.

Plattformverwaltung

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

Symptom: Benutzer können sich nicht beim Harmony-Portal anmelden.
Lösung:
- Prüfen Sie trust.jitterbit.com auf aktive Plattformausfälle.
- Löschen Sie den Browser-Cache und die Cookies, 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 Anmeldeseite zurückspringt oder nach der Anmeldung nicht geladen wird.
- Falls SSO konfiguriert ist, lassen Sie einen Administrator die SSO-Konfiguration überprüfen. Siehe 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 Überprüfungen weiterhin fehlschlägt (z. B. ein Passwort-Reset wird nicht abgeschlossen oder das Konto wird als inaktiv angezeigt, obwohl es aktiv ist), kontaktieren Sie den Jitterbit-Support.

Konto nach fehlgeschlagenen Anmeldeversuchen gesperrt

Symptom: Ein Benutzer kann sich nach Eingabe falscher Anmeldedaten nicht anmelden. Sein Status auf der Seite Benutzerverwaltung der Management Console 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 und versuchen Sie es dann mit den korrekten Anmeldedaten erneut.
- Alternativ können Sie den Link Passwort vergessen auf der Anmeldeseite des Harmony-Portals verwenden, um das Passwort zurückzusetzen und die Sperrung sofort aufzuheben.

Benutzer kann nicht auf eine Umgebung oder deren Funktionen zugreifen

Symptom: Ein Benutzer kann sich anmelden, sieht aber eine Umgebung nicht, kann nicht darin bereitstellen oder vermisst 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, die diesen Rollen gewährt wurden.

Projektvariablen werden bei der Umgebungsförderung nicht übernommen

Symptom: Nach der Übertragung eines Projekts in eine andere Umgebung fehlen einige Projektvariablenwerte im Ziel oder entsprechen nicht den erwarteten Werten.
Mögliche Ursache: Ob ein Projektvariablenwert übernommen wird, hängt von der verwendeten Übertragungsoption und den Variableneinstellungen ab:
- Bei einer vollständigen Projektübertragung (Dialog Migrieren) wird die erste Übertragung standardmäßig auf Alle Variablenwerte migrieren gesetzt, spätere Übertragungen werden jedoch standardmäßig auf Variablenwerte zum Migrieren auswählen gesetzt, was alle Variablen ausschließt, deren Wert sich geändert hat. Eine Variable, die nicht enthalten 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 Variablenwerte zum Migrieren 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 und nicht auf der Seite Projekte der Management Console, damit sie im Projektverlauf erfasst werden.

Umschalten einer Agent-Gruppe der Umgebung schlägt mit Fehler zur 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: Ein oder mehrere Agenten in der Ziel-Agent-Gruppe führen 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 bereitstellt, schlägt der Wechsel fehl. Dies kann bei einer privaten Agent-Gruppe auftreten, deren Agent-Versionen Sie verwalten, oder bei einer Cloud-Agent-Gruppe, die Jitterbit nach einem gestaffelten Plan aktualisiert (Sandbox vor Produktion). Eine Ziel-Cloud-Agent-Gruppe kann während eines Release-Rollouts daher kurzzeitig eine Version hinter sich haben.
Lösung:
- Private Agent-Gruppe: Identifizieren Sie auf der Seite Agenten der Management Console jeden Agenten in der Zielgruppe und aktualisieren Sie jeden auf eine Version, die die erforderliche Mindestversion der Umgebung erfüllt oder überschreitet (siehe Rollendes Upgrade). Versuchen Sie dann erneut, die Agent-Gruppe der Umgebung zu wechseln.
- Cloud-Agent-Gruppe: Cloud-Agenten werden von Jitterbit aktualisiert und können nicht manuell aktualisiert werden. Behalten Sie die Umgebung in einer Agent-Gruppe, die bereits die erforderliche Version erfüllt, oder versuchen Sie den Wechsel erneut, 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 stellt sich standardmäßig auf eine einzelne Harmony-Region-URL im Anmeldedialogfeld ein. Wenn SSO aktiviert ist, wird die SSO-Umleitung nur gegen 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).
  - Kommentieren Sie den Parameter cloud.url aus und setzen Sie ihn auf die regionale URL.
  - Speichern Sie die Datei und starten Sie Design Studio neu.

SSO-Konfigurationstest sperrt das Konto des Identitätsanbieters

Symptom: Ein Administrator wird aus seinem Konto beim Identitätsanbieter gesperrt, während er eine SSO-Konfiguration in der Management Console testet.
Mögliche Ursache: Jeder Klick auf Konfiguration testen öffnet das Anmeldeportal des Identitätsanbieters und zählt als Authentifizierungsversuch gegen die Sperrrichtlinie 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 Sie aus dem Konto des Identitätsanbieters gesperrt sind, führen Sie den Kontowiederherstellungsprozess des IdP durch, bevor Sie den SSO-Konfigurationstest erneut versuchen. Siehe SSO konfigurieren für vollständige Konfigurationsschritte.

IP-Zulassungsliste sperrt einen Administrator

Symptom: Sie verlieren unmittelbar nach dem Ändern der Bereiche durch einen anderen Administrator in Whitelist-IP-Bereich aktivieren den Zugriff auf das Harmony-Portal.
Mögliche Ursache: Die Richtlinie Whitelist-IP-Bereich aktivieren erfordert, dass die IP-Adresse jedes Benutzers im konfigurierten Bereich enthalten ist. Eine Validierungsmeldung hindert einen Administrator daran, einen Bereich zu speichern, der seine eigene aktuelle IP ausschließt, prüft aber nicht die IP-Adressen anderer Administratoren. Wenn die Änderung eines anderen Administrators Ihre IP ausschließt, werden Sie sofort gesperrt.
Lösung:
- Lassen Sie einen anderen Administrator, dessen IP in der Zulassungsliste enthalten ist, die Richtlinie aktualisieren oder deaktivieren, oder kontaktieren Sie den Jitterbit-Support.

Ändern der API-Subdomain unterbricht vorhandene API-Integrationen

Symptom: Nach dem Ändern der API-Subdomain einer Organisation in den Organisationsdetails der Management Console schlagen Aufrufe an die veröffentlichten APIs der Organisation von vorhandenen Clients und Integrationen fehl.
Mögliche Ursache: Die API-Subdomain bildet die Basis-API-URL für jede API in der Organisation. Wenn Sie sie ändern, wird die URL aller API-Manager-APIs der Organisation neu geschrieben. Jeder Client oder jede Integration, der/die die vorherige URL aufruft, schlägt fehl.
Lösung:
1. Notieren Sie sich in den Organisationsdetails die aktualisierte Basis-URL, die im Feld Vorschau der Basis-API-URL angezeigt wird.
2. Aktualisieren Sie alle Integrationen, Client-Anwendungen und Webhook-Konfigurationen, die auf die vorherige Basis-API-URL verweisen.
3. Um Störungen zu vermeiden, planen Sie Subdomain-Änderungen während eines Wartungsfensters und benachrichtigen Sie alle API-Verbraucher 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 basierend auf dem konfigurierten Datum erwartet.
Mögliche Ursache: Der Zugriff eines externen Benutzers läuft um 23:59 Uhr am ausgewählten Ablaufdatum in der lokalen Zeitzone des externen Benutzers ab. Wenn sich der Benutzer und der Administrator in verschiedenen Zeitzonen befinden, unterscheidet sich die tatsächliche Ablaufzeit 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 lokale Zeitzone des Benutzers bei der Auswahl des Datums.
- Um den Zugriff zu verlängern, bearbeiten Sie das Datum Zugriff läuft ab des Benutzers, bevor das aktuelle Datum abläuft.

Umgebungsänderungen werden in Harmony-Anwendungen nicht 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, wenn 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 nach der Konfiguration eines SSO-Identitätsanbieters.
Ursache: Harmony SSO erfordert zwei separate Clientanwendungen, die beim Identitätsanbieter konfiguriert werden: WMC (für das Harmony-Portal und alle Webanwendungen) und Studio (für Design Studio). Die Konfiguration nur eines Clients lässt die andere Anwendung ohne SSO-Unterstützung.
Lösung: Konfigurieren Sie sowohl die Clientanwendungen WMC als auch 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-aktivierten Organisation zu seiner SSO umgehen-Liste schlägt fehl, oder der Benutzer kann SSO nach dem Hinzufügen immer noch nicht umgehen.
Ursache: Ein Benutzer muss der Liste SSO umgehen vor dem Hinzufügen zur Organisation hinzugefügt werden. Ein Benutzer, der bereits Mitglied der Organisation ist, kann daher nicht direkt zur 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 folgendem 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, z. B. Testorganisationen 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. Wählen Sie für jeden betroffenen Benutzer eine der folgenden Optionen:
  - Entfernen Sie ihn aus den anderen Organisationen, denen er angehört (einschließlich Harmony-Test- oder Cloud Data Loader-Organisationen), oder aus dieser Organisation, damit er nur zu einer Harmony-Organisation gehört.
  - Um dem Benutzer zu ermöglichen, in mehreren Organisationen zu bleiben, 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 wird in einer Schleife umgeleitet ohne Fehlermeldung

Symptom: Ein Benutzer, der sich bei Harmony über Single Sign-On (SSO) anmelden möchte (z. B. mit Azure), wird kontinuierlich ohne Fehlermeldung zur Anmeldeseite zurückgeleitet.
Mögliche Ursache: Ein veralteter Browser-Cache oder Cookies beeinträchtigen den SSO-Authentifizierungsablauf.
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 browserspezifische Kompatibilitätsprobleme auszuschließen.

Cloud Datastore-Speicherlöschung schlägt mit Fehler „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 die Löschung erneut.

Zugriffstoken kann nach dem Löschen seiner Umgebung nicht bearbeitet werden

Symptom: Ein Zugriffstoken kann nicht bearbeitet oder kopiert werden, obwohl es immer noch auf der Management Console-Seite Access Tokens angezeigt wird.
Ursache: Wenn die dem Token zugeordnete Umgebung gelöscht wurde, können Sie das Token nicht mehr bearbeiten oder kopieren, obwohl Sie es immer noch löschen können.
Lösung: Löschen Sie das Token und erstellen Sie ein Ersatz-Zugriffstoken in einer vorhandenen Umgebung.

OAuth-Aktualisierungstoken-Ablauf führt zum Fehler verbundener 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 Meldung des Identitätsanbieters, dass das Aktualisierungstoken ungültig gemacht oder bereits ausgetauscht wurde. Die Verbindung funktioniert oft unmittelbar nach der Authentifizierung und schlägt dann bei einer späteren Ausführung fehl.
Mögliche Ursachen:
- Eine Token policy auf der Management Console-Seite App Registrations hat Enable refresh token expiration oder Enable refresh token inactivity expiration konfiguriert, sodass alle von dieser Verbindung abhängigen Operationen zur Laufzeit fehlschlagen, wenn das Token abläuft.
- Die Verbindung war länger untätig als die Lebensdauer des Aktualisierungstokens des Identitätsanbieters. Wie in den 3LO-Wichtigen Hinweisen beschrieben, werden Aktualisierungstoken nur verwendet, wenn eine Operation Zugriff auf den Endpunkt benötigt: Der Connector erneuert das Zugriffstoken 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 Aktualisierungstokens auf den Endpunkt zugreift (die einige Anbieter auf nur 24 Stunden setzen), läuft das Aktualisierungstoken selbst ab und die Token-Kette bricht, auch wenn Enable rotating refresh token ausgewählt ist.
- Die gleiche App-Registrierung und Benutzeranmeldedaten werden für 3LO in mehr als einem Projekt oder Endpunkt verwendet. Mit Enable rotating refresh token ausgewählt, gibt jede Token-Aktualisierung ein neues Aktualisierungstoken aus und macht das vorherige ungültig. Wenn die gemeinsamen Anmeldedaten an einer Stelle erneut authentifiziert oder aktualisiert werden, wird das Aktualisierungstoken, das die anderen Operationen halten, ungültig gemacht, sodass diese Operationen fehlschlagen.
Lösung:
- Wenn eine Token-Richtlinie mit 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 Tokenablauf benachrichtigt zu werden.
- Wenn eine Inaktivitätsphase die Ursache ist, stellen Sie sicher, dass ein Vorgang, der die Verbindung nutzt, innerhalb der Lebensdauer des Refresh-Tokens ausgeführt wird. Das Planen einer eigenständigen Token-Aktualisierung, um ein Token am Leben zu erhalten oder eine Inaktivitätsuhr zurückzusetzen, wird nicht unterstützt (siehe die 3LO Wichtige Hinweise): Das Token wird nur als Nebeneffekt eines Vorgangs erneuert, der tatsächlich auf den Endpunkt zugreift. Um dieses unterstützte Verhalten zu nutzen, fügen Sie einen einfachen Vorgang in einem wiederkehrenden Operationsplan hinzu, der einen einfachen Endpunkt in einem Intervall aufruft, das kürzer als die Lebensdauer des Refresh-Tokens ist (z. B. alle zwei Stunden), und verwenden Sie denselben Connector und dieselbe App-Registrierung wie Ihre Hauptvorgänge. Dieser Vorgang führt eine echte Anfrage an den Endpunkt durch, sodass jede Ausführung die Tokens als Teil der normalen Nutzung erneuert. Pro App-Registrierung ist nur ein solcher Vorgang erforderlich. Falls der Identitätsanbieter dies zulässt, können Sie auch die Lebensdauer des Refresh-Tokens verlängern.
- Wenn mehr als ein Projekt oder Endpunkt dieselbe App-Registrierung und denselben Benutzer nutzt, 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 gemeinsamen Verbindung, während andere Vorgänge 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 Authentifizierungsfluss.
Lösung: Folgen Sie dem TFA-Token-Abrufverfahren, um das Authentifizierungstoken mit dem zweistufigen Fluss zu erhalten.

Hinzufügen eines externen Benutzers schlägt mit einem `409 conflict`-Fehler 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.

Organisationsregion kann nicht direkt geändert werden

Symptom: Eine Organisation muss sich in eine andere Harmony-Region verschieben (z. B. von NA zu EMEA) aus Gründen der Datenspeicherung oder Compliance, aber es gibt keine Einstellung zum Ändern der Region einer vorhandenen Organisation.
Mögliche Ursache: Die Region einer Organisation wird bei der Erstellung festgelegt. Harmony unterstützt keine direkten Regionswechsel.
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, Pläne, Projektvariablen und Sicherheitsprofile neu.
4. Aktualisieren Sie alle externen Clients, Integrationen oder Webhook-Konfigurationen, um auf die API-URLs der neuen Region zu verweisen.
5. Kontaktieren Sie für eine koordinierte Migration den Jitterbit-Support oder Professional Services, um den Zeitplan zu planen und Ausfallzeiten zu minimieren.

Integration und Automatisierung

Dieser Abschnitt behandelt Probleme beim Verbinden mit externen Systemen, beim Transformieren und Verarbeiten von Daten sowie beim Ausführen von Integrationsoperationen und den Agenten, die diese ausführen.

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

Symptom: Eine Operation wird nicht wie erwartet abgeschlossen. Sie bleibt im Status Submitted oder Running stecken und macht keine Fortschritte, oder wird mit der Meldung abgebrochen:
```
Long running operation canceled by System
```
Der Abbruch kann erfolgen, nachdem die Operation eine Weile ausgeführt wurde, oder kurz nach dem Start, und spiegelt nicht unbedingt wider, wie lange die Operation tatsächlich ausgeführt wurde.
Mögliche Ursachen:
- Ein privater Agent hat die Verbindung zur Harmony-Plattform verloren und konnte den Operationsstatus nicht melden. Die Plattform zeigt die Operation weiterhin als Running an und kann sie als anscheinend hängend abbrechen, auch wenn die Operation auf dem Agent abgeschlossen wurde. Dies kann Operationen beeinflussen, die normalerweise in Sekunden abgeschlossen werden.
- Die Operation wurde abgeschlossen, aber ihr endgültiger Status wurde nicht an Harmony zurückgemeldet, sodass sie weiterhin als Running angezeigt wird, bis sie abläuft.
- Die Agent-Gruppe ist stark belastet und langsam beim Abholen oder Aktualisieren von Warteschlangen-Operationen.
- Die Operation bleibt speziell im Status Submitted stecken: Die Ausführungsmeldung wurde in die Warteschlange eingereiht, aber kein Agent in der Gruppe hat sie akzeptiert, da die Agents offline sind, fehlerhaft sind oder keine freie Kapazität haben, um neue Operationen zu akzeptieren (z. B. ist jeder Worker-Thread belegt).
Lösung:
- Bestätigen Sie bei privaten Agents, dass der Agent auf der Seite Agents in der Management Console den Status Running hat, überprüfen Sie die Protokolle des privaten Agents auf Verbindungsprobleme, und stellen Sie sicher, dass die Netzwerkverbindung zwischen dem Agent und der Harmony-Plattform stabil ist.
- Überprüfen Sie die Operationsprotokolle, um zu bestätigen, was während der Ausführung passiert ist. Die Abbruchmeldung kann auch bei Operationen angezeigt werden, die nur kurz ausgeführt wurden, daher deutet sie nicht unbedingt auf eine echte lange laufende Operation hin. Die Protokolle können auch einen spezifischen Fehler offenbaren, den man beheben kann, z. B. 401 Unauthorized (Anmeldedaten überprüfen) oder 429 Too Many Requests. Ein 429 von einem Ziel-Endpoint kann durch Reduzierung der Anfragerate oder durch Hinzufügen von Wiederholungslogik gelindert werden; ein 429 vom von Jitterbit verwalteten Cloud-API-Gateway ist sein Plattformlimit von 200 Anfragen pro Minute, daher verteilen Sie die Aufrufe über die Zeit oder führen Sie die betroffenen APIs auf privaten Agents aus.
- Halten Sie private Agents auf einer aktuellen Version. Neuere Agent-Versionen verbessern die Agent-Ausfallsicherheit und reduzieren vorzeitige Abbrüche von Operationen.
- Versuchen Sie, die betroffenen Operationen abzubrechen. Der Abbruch ist für Operationen mit dem Status Submitted, Received, Pending oder Running über die Seite Runtime der Management Console, die Operationsprotokolltabelle oder den Laufzeitstatus einer Operation auf der Design-Canvas verfügbar.
- Wenn die betroffene Operation nach einem Zeitplan ausgeführt wird und nie startet, siehe Geplante Operationen werden nicht ausgeführt.
- Wenn die Operationen nicht abgebrochen werden können, wenn das Problem erneut auftritt oder wenn viele Operationen gleichzeitig betroffen sind, kontaktieren Sie den Jitterbit-Support, da diese Fälle möglicherweise eine serverseitige Lösung erfordern.

Hinweis

Die Einstellung MaxOperationRuntimeSeconds im Abschnitt [ProcessEngine] der Datei jitterbit.conf des privaten Agents begrenzt nur, wie lange eine Operation ausgeführt wird, nachdem ein Agent mit der Ausführung begonnen hat, daher hat sie keine Auswirkung auf Operationen, die sich noch in der Submitted-Warteschlange befinden. Die Operationseinstellung Operation Time Out begrenzt die Gesamtlaufzeit einer Operation, kann aber nicht nur auf den Submitted-Status beschränkt werden, daher würde eine Reduzierung, um einen schnellen Abbruch zu erzwingen, auch Operationen abbrechen, die noch legitim ausgeführt werden. Um in Submitted steckengebliebene Operationen zu löschen, stellen Sie die Agent-Kapazität und -Integrität wieder her, damit die warteschlangenbefindlichen Ausführungsmeldungen abgerufen werden, anstatt ein Timeout anzupassen.

Geplante Operationen werden nicht ausgeführt

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

Wörterbuch oder globale Variable ist leer, nachdem eine Operation asynchron ausgeführt wird

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

504 Gateway Timeout (API-ausgelöste Operationen)

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: Die zugrunde liegende Operation überschreitet das Timeout des API-Gateways, oder die Anfrage kann keinem verfügbaren Agent zugewiesen werden. Siehe HTTP 504 Gateway Timeout für die vollständigen Ursachen und Lösungen.

507 Unzureichender Speicher

Symptom: Ein API-Aufruf gibt folgende Meldung zurück:
```
507 Insufficient Storage
```
Mögliche Ursachen:
- Der Agent oder Gateway-Host hat keinen Speicherplatz mehr.
- Bei einem privaten API-Gateway kann das Gateway seine gehostete Payload- oder Antwortdatei nicht öffnen und gibt einen 507-Fehler zurück, auch wenn ausreichend Speicherplatz verfügbar ist. Dies deutet normalerweise auf ein Problem mit der privaten Domain-Registrierung oder der Gateway-Konfiguration hin.
Lösung:
- Bestätigen Sie, dass der Agent oder Gateway-Host über ausreichend freien Speicherplatz verfügt.
- Wenn ausreichend Speicherplatz vorhanden ist und die API über ein privates API-Gateway bereitgestellt wird, siehe Private gateway returns HTTP 507 or "No such file or directory" für die Ursache und Lösung.

502 Bad Gateway

Symptom: Ein Vorgang, der Jitterbit Message Queue (JBMQ) verwendet, schlägt fehl mit:
```
502 Bad Gateway
```
Der Server hat eine ungültige oder unvollständige Antwort zurückgegeben.
Mögliche Ursache: Der JBMQ-Service hat keine vollständige Antwort auf die Anfrage zurückgegeben, was zu einem 502-Fehler führt. Dieser Fehler ist normalerweise vorübergehend und möglicherweise nicht reproduzierbar.
Lösung:
1. Wiederholen Sie den Vorgang.
2. Wenn der Fehler weiterhin auftritt, kontaktieren Sie den Jitterbit-Support.

Fehler beim Erstellen des temporären Verzeichnisses

Symptom: Ein Vorgang schlägt beim Erstellen eines temporären Verzeichnisses fehl und zeigt eine Fehlermeldung wie:
```
Failed to create the directory '/tmp/jitterbit/...'. Reason: boost::filesystem::create_directories: Permission denied
```
Bei einer Cloud-Agent-Gruppe kann stattdessen die Meldung No space left on device angezeigt werden.
Mögliche Ursachen:
- Bei einem privaten Agent verfügt das Jitterbit-Agent-Dienstkonto nicht über die erforderlichen Berechtigungen auf Betriebssystemebene für den Pfad der temporären Dateien, oder die Festplatte ist voll.
- Bei einer Cloud-Agent-Gruppe liegt die Ursache auf der von Jitterbit verwalteten Agent-Seite und nicht in Ihrem Projekt oder Ihrer Konfiguration.
Lösung:
- Bestätigen Sie bei privaten Agents, dass das Agent-Dienstkonto ausreichende Berechtigungen für den Pfad der temporären Dateien (/tmp oder TemporaryFiles) hat, und überprüfen Sie, dass der Agent-Host über ausreichend freien Speicherplatz verfügt.
- Bei Cloud-Agent-Gruppen deutet dies auf ein Agent-seitiges Problem hin, das Jitterbit behebt. Kontaktieren Sie den Jitterbit-Support und geben Sie die Fehlermeldung sowie den Zeitpunkt der Fehler an.

Operationsprotokollmeldungen werden bei etwa 100 KB gekürzt

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

Das Debug-Logging der Operation zeigt PII und Anmeldedaten im Klartext

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

Fehler bei der Datenbankverbindung des Private Agent

Symptom: Operationen schlagen fehl mit:

Failed to connect to back-end database 'TranDb'

FATAL: query_wait_timeout

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

Clientzertifikat kann auf Linux Private Agents nicht geladen werden

Symptom: Eine Operation, die einen ausgehenden gegenseitigen TLS-Webservice-Aufruf (Client-Zertifikat) durchführt, schlägt zur Laufzeit auf einem Linux-Privatagenten fehl, mit einem Fehler wie:
```
Problem with the local SSL certificate. Unable to set private key file: '<path>.key' type PEM.
```
Das Zertifikat wird erfolgreich in Studio hochgeladen, aber die Operation schlägt fehl, wenn sie ausgeführt wird. Die gleiche Konfiguration hat möglicherweise zuvor auf einem Windows-Privatagenten funktioniert.
Mögliche Ursachen:
- Der Betriebssystembenutzer, der den Jitterbit-Agent ausführt, hat keine Leseberechtigung für die private Schlüsseldatei oder deren übergeordnete Verzeichnisse.
- Ein Linux-Sicherheitsmodul wie SELinux oder AppArmor blockiert den Zugriff des Agents auf die private Schlüsseldatei.
Lösung:
- Stellen Sie sicher, dass das Konto, das den Jitterbit-Agent ausführt, Lesezugriff auf die private Schlüsseldatei und alle übergeordneten Verzeichnisse hat.
- Überprüfen Sie, ob SELinux oder AppArmor den Zugriff auf die Schlüsseldatei einschränkt, und passen Sie die Richtlinie oder den Dateikontext entsprechend an.

Validierungsfehler bei Operationen

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

Komponentennamen müssen nach dem Projektimport eindeutig sein

Symptom: Nach dem Importieren eines Projekts aus einer JSON-Exportdatei zeigen sich eine oder mehrere Komponenten als ungültig an und die Bereitstellung schlägt mit einer ähnlichen Meldung fehl:
```
[Operation / Connection / Activity / Transformation / Script / Tool / Email / Variable] names must be unique.
```
Mögliche Ursache: Das importierte Projekt enthält mehrere Komponenten desselben Typs mit identischen Namen. Studio verhindert das Erstellen doppelter Namen bei der direkten Konfiguration von Komponenten in der Benutzeroberfläche, aber ein vollständiger Projektimport wendet diese Prüfung nicht an.
Lösung:
1. Identifizieren Sie im Projektbereich die ungültigen Komponenten, die in roten Kursivbuchstaben mit einem Fehlersymbol angezeigt werden.
2. Klicken Sie auf das Fehlersymbol, um den spezifischen doppelten Namen anzuzeigen, der den Konflikt verursacht.
3. Benennen Sie eine der doppelten Komponenten um, sodass jeder Name innerhalb seines Typs eindeutig ist.
4. Stellen Sie das Projekt erneut bereit, nachdem Sie alle Fehler mit doppelten Namen behoben haben.
5. Um nur ausgewählte Komponenten in ein vorhandenes Projekt zu importieren, verwenden Sie selektiven Import, der Konflikte mit gleichnamigen Komponenten im Zielproject kennzeichnet und ermöglicht es Ihnen, diese zu ersetzen oder beide beizubehalten.

Nur Private Agent-Connector blockiert den Import in eine Cloud-Agent-Umgebung

Symptom: Der Import oder die Migration eines Projekts in eine Umgebung, die einer Cloud-Agent-Gruppe zugeordnet ist, wird blockiert, da das Projekt einen Connector nur für private Agenten verwendet. Die Meldung listet die verantwortlichen Connectoren nur für private Agenten auf. Ein vollständiger Projektimport zeigt an:
```
The project you are importing uses private agent only connectors and cannot be imported into a cloud environment.
```
Ein selektiver Import zeigt einen Dialog Komponentenimport nicht zulässig an:
```
The components you are importing uses private agent only connectors and cannot be imported into a cloud environment.
```
Mögliche Ursache: Das Projekt verwendet einen oder mehrere Connectoren, die nur auf privaten Agenten verfügbar sind. Die Spalte Agent-Verfügbarkeit in der Connectorliste zeigt, welche Connectoren nur für private Agenten verfügbar sind. Cloud-Agenten unterstützen diese Connectoren nicht, daher verhindert Studio, dass das Projekt in eine Cloud-Agent-Umgebung importiert oder migriert wird.
Lösung:
- Importieren oder migrieren Sie das Projekt in eine Umgebung, die einer Gruppe privater Agenten zugeordnet ist und den erforderlichen Connector installiert hat.
- Wenn das Projekt auf Cloud-Agenten ausgeführt werden muss, ersetzen Sie die Connector-Aktivitäten nur für private Agenten durch Cloud-kompatible Connectoren (z. B. HTTP v2 für REST-APIs oder den Database-Connector mit einem Cloud-zugänglichen Endpunkt), bevor Sie den Import durchführen.

Zielschleifenknoten ist mehreren Quellschleifenknoten 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 hat Feldmappings, die auf zwei oder mehr verschiedene Quellschleifenknoten verweisen. Jeder Zielschleifenknoten kann nur über einen einzelnen Quellschleifenknoten iterieren.
Lösung:
1. Öffnen Sie die Transformation und identifizieren Sie den Zielschleifenknoten, der im Fehler gekennzeichnet ist.
2. Überprüfen Sie die Mappings unter diesem Knoten, um zu bestätigen, dass alle zugeordneten Felder vom gleichen Quellschleifenknoten stammen.
3. Wenn Daten aus mehreren Quellknoten erforderlich sind, verarbeiten oder führen Sie die zusätzlichen Quelldaten in einem Skriptschritt vor der Transformation vor, damit ein einzelner einheitlicher Quellknoten das Zielschleifenknoten speist.
4. Weitere Details zu gültigen Mapping-Mustern finden Sie unter Transformations-Mapping-Gültigkeit.

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

Symptom: Viele Connectoren enthalten eine Tabelle Erweiterte Konfigurationseigenschaften für optionale Verbindungseinstellungen. Variablen, die in diesen Feldern verwendet werden und unformatiertes JSON enthalten, müssen das JSON maskiert haben. Das Übergeben von unformatiertem JSON über eine Variable führt dazu, dass der Feldwert fehlerhaft wird.
Mögliche Ursache: Felder in der Tabelle Erweiterte Konfigurationseigenschaften unterstützen keine Variablen, die unformatierte JSON-Objekte enthalten.
Lösung:
- Maskieren Sie das JSON, bevor Sie JSON-Inhalte über eine Variable in ein Feld Erweiterte Konfigurationseigenschaften übergeben. 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 Erweiterte Konfigurationseigenschaften werden nur 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 (CDATA) Abschnitte werden in XML, das in JSON eingebettet ist und durch eine Transformation verarbeitet wird, nicht unterstützt. Wenn vorhanden, wird der folgende Fehler im Operationsprotokoll angezeigt:
```
Transformation failed. Error: The operation "Operation" failed.
Error: Failed to convert XML file to JSON.
org.jitterbit.integration.server.engine.EngineSessionException: org.xml.sax.SAXParseException ...
```
Lösung: Verwenden Sie ein Jitterbit-Skript, um die Zeichen &, <, >, ' und " im CDATA-Abschnitt, einschließlich der CDATA-Trennzeichen (<![CDATA[ ... ]]>), mit ihren Escape-Äquivalenten (&, <, >, ', ") zu Replace. Wenn es nicht möglich ist, nur den CDATA-Abschnitt anzusteuern, kann die gesamte XML-Zeichenkette, die ihn enthält, ersetzt werden.

Das folgende Beispiel gilt ohne diese Ersetzungen als ungültig:
```
{
  "name": "Jitterbit",
  "data": "<xml><content><![CDATA[<greeting>Hello, world!</greeting>]]></content></xml>"
}
```

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

Symptom: Eine Transformation, die einen großen JSON-Zeichenfolgenwert verarbeitet, schlägt mit einem Fehler fehl, der meldet, dass die Zeichenkette die maximal zulässige Länge überschreitet, zum Beispiel:
```
Transformation failed. Error: Error Code: String value length (20054016) exceeds the maximum allowed (20000000, from StreamReadConstraints.getMaxStringLength())
```
Die Stack-Trace verweist auf StreamConstraintsException und den JSON-Parser des Agents. Ein häufiger Auslöser ist eine HTTP v2-Antwort mit aktiviertem Get response content in base64 string: Base64-Codierung vergrößert binäre Inhalte (wie eine Audio- oder Mediendatei), sodass die codierte Zeichenkette die Grenze überschreiten kann, selbst wenn die ursprüngliche Datei kleiner ist.
Ursache: Der JSON-Parser des Agents begrenzt einen einzelnen JSON-Zeichenfolgenwert standardmäßig auf 20 MB (20000000 Zeichen). Ein Wert, der größer als diese Grenze ist, schlägt fehl, während der Agent ihn analysiert, bevor eine nachgelagerte Aktivität (wie ein Upload) ausgeführt wird.
Lösung: Erhöhen Sie auf einem privaten Agent mit Version 12.5 oder später die Grenze mit dem Schlüssel MaxStringLength im Abschnitt [JsonParser] der Konfigurationsdatei jitterbit.conf (setzen Sie ihn beispielsweise auf 50000000 für eine Grenze von 50 MB), und starten Sie den Agent neu. Dieser Schlüssel ist in Agent-Version 12.5 und später verfügbar. Aktualisieren Sie den Agent daher zuerst, wenn er eine frühere Version hat.

Sonderzeichen in von Connectoren bereitgestellten JSON-Schemas

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

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

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

Gespiegelte Schemas mit Substitutionsgruppen

Symptom: Gespiegelte Schemas, die XML-Substitutionsgruppen verwenden, werden nicht unterstützt. Die Verwendung führt zu einem Laufzeitfehler:
```
Failed to initialize transformation "<transformation name>". Failed to expand the (source|target) tree for the path: <path to substitution head node>.
```
Dieser Fehler kann auch aus anderen Gründen auftreten, z. B. beim Importieren einer Transformationszuordnung mit doppelten Knoten, und deutet nicht unbedingt auf ein Substitutionsgruppenprobleme hin.
Lösung: Wenn Substitutionsgruppen die bestätigte Ursache sind, löschen Sie das gespiegelte Schema und erstellen Sie es mit einer anderen Methode neu (Hochladen, Erstellen eines benutzerdefinierten Schemas usw.).

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

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

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

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

Mögliche Ursache: Das Importieren einer Zuordnungsdatei, die doppelte Knoten zum Zielschema hinzugefügt hat, hat die entsprechende Änderung an der Schemadefinition, die bei der Ausführung des Vorgangs verwendet wird, nicht angewendet, wodurch die beiden nicht mehr synchron sind. Dies wurde behoben, aber eine Transformation, deren Zuordnung vor der Behebung importiert wurde, kann weiterhin betroffen sein.
Lösung: Verwenden Sie in der betroffenen Transformation Alle Zuordnungen unter diesem Knoten entfernen auf dem Stammknoten, um alle Zuordnungen zu entfernen, und importieren Sie die Zuordnungsdatei erneut. Das erneute Importieren synchronisiert die bei der Laufzeit verwendete Schemadefinition mit der Zuordnung. Wenn der Fehler weiterhin besteht, konfigurieren Sie die Aktivität neu, die das Schema bereitstellt, und aktualisieren Sie das Schema in der Transformation.

Warnung zu zusätzlichen Unterelementen in Operationsprotokollen

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

Iterationslimit für Skriptschleife überschritten

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

Der Vergleich einer Zeichenkette mit einer Zahl liefert unerwartete Ergebnisse

Symptom: Ein Vergleich zwischen einer Zeichenkette und einer Zahl liefert ein unerwartetes Ergebnis. Beispielsweise wird der Vergleich einer nicht-numerischen Zeichenkette mit 0 als gleich ausgewertet, sodass der falsche Zweig ausgeführt wird:
```
$value = "test";
If($value == 0, WriteToOperationLog("equal"), WriteToOperationLog("not equal"));
// logs "equal", even though "test" is not 0
```
Ursache: Wenn die beiden Operanden unterschiedliche Typen haben, konvertiert Jitterbit Script beide in Zahlen, um sie zu vergleichen. Eine Zeichenkette, die keine Zahl darstellt, wird in 0 konvertiert, sodass "test" == 0 zu 0 == 0 wird, was true ist. Dies ist das erwartete Verhalten.
Lösung: Vergleichen Sie Werte desselben Typs. Um eine Zeichenkette gegen einen bestimmten Wert zu testen, vergleichen Sie sie mit einem Zeichenkettenliteral (z. B. $value == "0" oder $value == ""), anstatt mit einer Zahl. Wenn ein Wert als beide Typen ankommen kann, konvertieren Sie beide Operanden vor dem Vergleich in denselben Typ (z. B. mit String).

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

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

Der Unterschied liegt in der Namespace-Präfix-Behandlung:
- Vor 10.25: Gespiegelte XML-Schemas verwendeten das Standard-Namespace-Präfix xsi.
- 10.25 und später: Gespiegelte XML-Schemas verwenden das qualifizierte Namespace-Präfix ns. Nicht zugeordnete Felder werden im Schema nicht angezeigt.
Lösung: Ab Version 10.27 behält das Importieren eines Projekts, dessen gespiegelte XML-Schemas vor 10.25 erstellt wurden, das ursprüngliche Namespace-Präfix bei, sodass das Schema mit dem Zeitpunkt der Erstellung identisch ist. Um ein Update auf das aktuelle Namespace-Präfix zu erzwingen, generieren Sie das Schema neu, indem Sie es aktualisieren oder die Aktivität, die es bereitstellt, neu konfigurieren. Überprüfen Sie nach der erneuten Generierung alle betroffenen XML-Namespace-Funktionsaufrufe und aktualisieren Sie die Präfix-Verweise entsprechend.

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

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

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

Leere zugeordnete Felder mit flachen Quellschemas

Symptom: Zielfelder erscheinen in der Operationsausgabe leer, obwohl die Quelldaten Werte enthalten. Dieses Problem tritt speziell bei Verwendung eines flachen Quellschemas auf. Es tritt nicht bei gespiegelten Schemas oder JSON-Schemas auf.
Mögliche Ursache: Der Standard-Streaming-Transformationsmodus verarbeitet Datensätze inkrementell, was dazu führen kann, dass zugeordnete Felder bei Verwendung mit flachen Quellschemas keine Werte erhalten.
Lösung:
1. Fügen Sie einen Skriptschritt am Anfang der Operation hinzu, der Streaming-Transformationen deaktiviert, indem Sie jitterbit.transformation.auto_streaming auf false setzen:
```
$jitterbit.transformation.auto_streaming = false;
```
2. Stellen Sie die Operation bereit und führen Sie sie erneut aus. Weitere Informationen zu Streaming und Transformationsverarbeitung finden Sie unter Transformationsverarbeitung.

Dateifunktionen: Operation wird nach Fehler bei `ArchiveFile` oder `ReadFile` fortgesetzt

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

`ReadFile`: Teilweise Lesevorgänge mit Binärdateiinhalt

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

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

Symptom: Eine Transformation, die Rohdateiinhalte, die mit ReadFile gelesen werden (z. B. eine Raw-EDI-Datei), in ein UTF-8-XML- oder JSON-Zielfeld abbildet, schlägt während der XML- oder JSON-Konvertierung fehl. Das Ersetzen des abgebildeten Werts durch eine hartcodierte Zeichenkette ermöglicht den Abschluss des Vorgangs, was bestätigt, dass der Rohinhalte der Auslöser ist. Versuche, das problematische Zeichen mithilfe seines Unicode-Codepunkts zu entfernen (z. B. Replace($readFile, HexToString("2026"), "~") für die Ellipse U+2026), stimmen nicht überein, und das Aufrufen von StringToHex für den Inhalt mit aktivierter Unicode-Unterstützung wirft:
```
not a UTF-8 string, byte not in range: 13
```
Ursache: Der Dateiinhalt enthält ein Byte, das nicht gültig UTF-8 ist (z. B. das einzelne Byte 0x85, das einige EDI-Dateien als Segmenttrennzeichen verwenden). Dieses Rohe Byte ist nicht dasselbe wie die Multi-Byte-UTF-8-Codierung eines ähnlich aussehenden Unicode-Zeichens (die Ellipse U+2026 wird als drei Bytes codiert), daher stimmt ein Ersatz, der auf den Unicode-Codepunkt abzielt, nie überein. Wenn jitterbit.scripting.hex.enable_unicode_support auf true gesetzt ist, interpretieren die Hex-Funktionen den Inhalt als UTF-8 und schlagen beim ungültigen Byte fehl.
Lösung: Stimmen Sie das Rohe Byte ab und ersetzen Sie es mit deaktivierter Unicode-Hex-Unterstützung, damit HexToString auf Rohe Bytes statt auf UTF-8-Zeichen arbeitet:
```
$jitterbit.scripting.hex.enable_unicode_support = false;
$badByte = HexToString("85");
$readFile = Replace($readFile, $badByte, "~");
```
Passen Sie den Hex-Wert (85) an das Byte an, das von StringToHex($readFile) gemeldet wird, und die Ersatzzeichenkette (~) nach Bedarf an, und bilden Sie dann den bereinigten Wert ab.

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

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

`DeleteFiles`: Fehler, wenn Quellpfad nicht gefunden werden kann

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

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

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

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

Symptom: Der Zuordnungsausdruck eines Zielfeldes umfasst sowohl RunScript als auch Unmap, aber das Feld wird nicht aufgehoben. Bei einem JSON- oder XML-Ziel erscheint das Feld in der Ausgabe mit einem null-Wert, anstatt weggelassen zu werden.
Mögliche Ursachen:
- RunScript steht vor Unmap im selben Zuordnungsausdruck (z. B. RunScript("<TAG>script:MyScript</TAG>"); Unmap();). Bei Agent-Versionen vor 12.9 hob diese Kombination das Feld nicht auf.
- Unmap wird aus dem von RunScript aufgerufenen Skript aufgerufen, anstatt direkt im eigenen Zuordnungsausdruck des Zielfeldes. RunScript gibt das Ergebnis des aufgerufenen Skripts als Zeichenkette zurück, anstatt ein Unmap-Signal zurück zur Zuordnung zu propagieren. Das Aufrufen von Unmap aus dem aufgerufenen Skript hat daher keine Auswirkung, unabhängig von der Agent-Version und unabhängig von bedingter Logik um den Aufruf. Dies ist das erwartete Verhalten.
Lösung:
- Wenn RunScript und Unmap beide direkt im Zuordnungsausdruck des Zielfeldes aufgerufen werden, führen Sie ein Upgrade auf Agent-Version 12.9 oder später durch.
- Wenn Unmap aus dem von RunScript aufgerufenen Skript aufgerufen wird, verschieben Sie den Unmap-Aufruf aus dem aufgerufenen Skript in den eigenen Zuordnungsausdruck des Zielfeldes, z. B.:
```
RunScript("<TAG>script:MyScript</TAG>"); If(<condition>, Unmap(), <value>);
```

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

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

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

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

`CallStoredProcedure`: „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 das Datenbankobjekt eine PostgreSQL-Funktion statt einer Prozedur ist, kann der Treiber es nicht finden und gibt die Fehlermeldung „nicht gefunden" zurück.
Lösung:
1. Bestimmen Sie, ob das aufgerufene Datenbankobjekt eine PostgreSQL-Funktion (gibt einen Wert zurück) oder eine Prozedur (kein Rückgabewert) ist.
2. Ersetzen Sie CallStoredProcedure durch DBExecute und verwenden Sie die korrekte SQL-Syntax für den Objekttyp:
  - Funktion: verwenden Sie SELECT.
```
$result = DBExecute("<TAG>Sources/My DB Connection</TAG>", "SELECT my_function(arg1, arg2)");
```
    DBExecute gibt ein Resultset zurück. Verwenden Sie eine While-Schleife mit Get, um die zurückgegebenen Werte zu lesen.
  - Prozedur: verwenden Sie CALL.
```
DBExecute("<TAG>Sources/My DB Connection</TAG>", "CALL my_procedure(arg1, arg2)");
```
    PostgreSQL-Prozeduren geben keinen Wert zurück; der Rückgabewert von DBExecute kann verworfen werden.

`DBLoad`: Erfordert einen JDBC-Datenbanktreiber

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

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

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

Variablenupdates gehen in segmentierten Multi-Thread-Operationen verloren

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

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

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

Lange numerische IDs werden in der Transformationsausgabe beschädigt

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

JSON-Transformationsausgabe lässt `null`- und leere Stringfelder aus

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

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

Symptom: In einer XML- oder SOAP-Transformation wird ein zugeordnetes Feld mit einem leeren Wert als nil-Element ausgegeben, und der Ziel-Endpunkt lehnt die Anfrage ab. Beispielsweise erzeugt eine leere Telefonnummernzuordnung:
```
<ns1:Phone_Number xsi:nil="true"/>
```
Einige Endpunkte (z. B. Workday SOAP-Services) behandeln dies als ungültig und geben einen Fehler zurück.
Ursache: Standardmäßig wird bei einer Zuordnung zu einem Zielknoten, die zu einem Null- oder leeren Wert führt, der Knoten in die Transformation einbezogen, aber als nil markiert (xsi:nil="true"). Dies wird durch jitterbit.target.xml.include_null_xml gesteuert, dessen Standardwert true ist.
Lösung: Legen Sie in einem Skriptschritt vor der Transformation $jitterbit.target.xml.include_null_xml = false fest, um Knoten mit einem Null- oder leeren Wert vollständig aus der Ausgabe zu entfernen. Wenn der Knoten stattdessen als leeres Element vorhanden sein muss, verwenden Sie die zugehörigen Ziel-Jitterbit-Variablen jitterbit.target.xml.include_empty_xml und jitterbit.target.xml.include_nil_attribute, die steuern, ob leere und Null-Werte in der Ausgabe einbezogen werden.

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

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

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

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

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

Symptom: IsNull gibt false für ein Feld zurück, das aus einer JSON-Quelle zugeordnet ist, auch wenn das Feld keinen Wert zu haben scheint. Nachgelagerte Logik, die vom Null-Check abhängt, verhält sich unerwartet oder erzeugt falsche Ergebnisse.
Mögliche Ursache: JSON unterscheidet zwischen einem fehlenden oder expliziten null-Wert und einem leeren String (""). Ein Feld, das in JSON auf "" gesetzt ist, ist ein leerer String, kein Null-Wert. Daher gibt IsNull korrekt false dafür zurück. Ab Agent 11.37 behält der Agent diese Unterscheidung genau bei. Skripte oder Transformationen, die sich früher darauf verlassen haben, dass IsNull für leere Strings true zurückgibt, hingen von früherem Verhalten ab, das nicht mehr korrekt ist.
Lösung:
- Verwenden Sie IfEmpty, um sowohl Null als auch leere Strings zu verarbeiten: Die Funktion IfEmpty gibt einen Standardwert zurück, wenn das Argument null oder ein leerer String ist, und ist die empfohlene Ersetzung für dieses Szenario:
```
// Gibt "default" zurück, wenn das Feld null oder ein leerer String ist
result = IfEmpty($myField, "default");
```
- Verwenden Sie Length, um explizit auf leere Strings zu prüfen: Wenn Sie nur prüfen müssen, ob ein String leer ist (nicht null), verwenden Sie Length($myField) == 0.
- Beheben Sie die Quelldaten: Wenn die JSON-Quelle keinen Wert angeben soll, aktualisieren Sie sie so, dass sie "field": null sendet oder das Feld ganz weglässt, statt "field": "".

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

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

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

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

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

Dezimalarithmetik erzeugt unerwartete Gleitkommawerte

Symptom: Ein arithmetischer Ausdruck mit Dezimalliteralen erzeugt ein Ergebnis, das leicht vom erwarteten Wert abweicht. Beispielsweise gibt Double(12.01) - Double(12.00) statt 0.01 den Wert 0.00999999999999979 zurück, und (4.9 * 100) - 490 ergibt statt 0 den Wert 5.6843418860808e-14.
Mögliche Ursache: Jitterbit Script speichert Zahlen als Gleitkommawerte. Die meisten Dezimalbrüche können in binärer Gleitkommadarstellung nicht exakt dargestellt werden, daher können arithmetische Operationen kleine Rundungsfehler ansammeln. Subtraktionen, die den Großteil eines Wertes aufheben, machen diesen Rest sichtbar. Das explizite Umwandeln von Werten als Double verhindert dies nicht: Es gibt den Datentyp an, ändert aber nicht, wie der Wert gespeichert oder berechnet wird.
Lösung:
- Wenden Sie Round auf das Ergebnis an: Verwenden Sie Round mit der für die Berechnung erforderlichen Anzahl von Dezimalstellen:
```
$a = Round(Double(12.01) - Double(12.00), 2); // returns 0.01
```
- Wandeln Sie Dezimalliterale mit Float um: Umhüllen Sie das Dezimalliteral mit Float vor der Berechnung:
```
$a = (Float(4.9) * 100) - 490;
WriteToOperationLog($a);
```

Datumsfunktionen geben Mitternacht statt eines reinen Datumswerts zurück

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

Zwischengespeicherter Wert läuft früher als erwartet ab

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

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

Übergeben Sie -1, um das Schreibablaufdatum beizubehalten: Wenn Sie einen nicht-positiven Wert übergeben, behält ReadCache das Ablaufdatum bei, das durch den letzten WriteCache-Aufruf festgelegt wurde, anstatt ein neues anzuwenden:
```
testVal = ReadCache("CacheTest", -1, "env");
```

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

Symptom: RunXSLT schlägt mit dem Fehler fehl:
```
Failed to execute xslt. XML version must be 1.0 or 1.1
```
obwohl die XML-Eingabedatei eine gültige <?xml version="1.0"?>-Deklaration enthält.
Mögliche Ursache: Das XSLT-Stylesheet ist so konfiguriert, dass es HTML-Ausgabe erzeugt (z. B. <xsl:output method="html"/>). RunXSLT unterstützt nur XML als Ausgabe. Wenn das Stylesheet HTML erzeugt, generiert die Funktion ein leeres Ergebnis, das diesen Fehler auslöst. Die Fehlermeldung bezieht sich auf die fehlende XML-Deklaration in der (leeren) Ausgabe, nicht auf die XML-Eingabe.
Lösung:
- Aktualisieren Sie das XSLT, um XML-Ausgabe zu erzeugen: Ändern Sie die Ausgabeerklärung des Stylesheets in <xsl:output method="xml"/> oder entfernen Sie die xsl:output-Deklaration vollständig (XML ist die Standardeinstellung). Dies ist der empfohlene Ansatz und funktioniert sowohl auf Cloud- als auch auf privaten Agenten.
- Verwenden Sie das XSL Transform-Plugin (nur private Agenten): Für private Agent-Gruppen verwendet das veraltete XSL Transform-Plugin den Saxon-XSLT-Prozessor und unterstützt Nicht-XML-Ausgabeformate einschließlich HTML. Siehe Verfügbare Plugins für Installationsdetails.

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

Symptom: SelectSingleNode gibt Daten aus dem falschen Element zurück (z. B. immer die erste Übereinstimmung im Dokument), wenn es auf ein Element aufgerufen wird, das aus einem SelectNodes-Array abgerufen wurde.
Mögliche Ursache: Die Verwendung eines absoluten XPath-Ausdrucks (einer, der mit // beginnt) als Pfadargument führt dazu, dass SelectSingleNode vom Stamm des ursprünglichen XML-Dokuments aus sucht, anstatt relativ zum aktuellen Knoten. Ein Ausdruck wie "//Item/ItemName" stimmt mit dem ersten ItemName überein, das sich irgendwo im Dokument befindet, unabhängig davon, welches Item-Element aus dem Array abgerufen wurde.
Lösung:
- Verwenden Sie einen relativen Pfad: Lassen Sie das führende // weg und geben Sie nur den Elementnamen oder einen Pfad relativ zum aktuellen Knoten an. Dies beschränkt die Suche auf den Knoten, der als erstes Argument übergeben wird:
```
$itemName = SelectSingleNode($item, "ItemName");
```
- Alternative: Wickeln Sie den Knoten in String: Das Konvertieren des Array-Elements in einen String, bevor es an SelectSingleNode übergeben wird, erzeugt auch das richtige Ergebnis, obwohl die Verwendung eines relativen Pfads der bevorzugte Ansatz ist:
```
$item = String($items[2]);
$itemName = SelectSingleNode($item, "//Item/ItemName");
```

`HexToBinary`-Ausgabe erscheint unverändert, wenn protokolliert

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

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

`SortArray` sortiert Dateinamen lexikografisch, nicht chronologisch

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

`URLEncode` codiert bestimmte „sichere" oder Multibyte-Zeichen nicht

Symptom: Ein Wert, der durch URLEncode geleitet wird, wird an das Ziel mit einigen nicht codierten Zeichen gesendet, was dazu führt, dass das empfangende System die Anfrage ablehnt oder den Wert falsch interpretiert. Dies betrifft häufig Anmeldedaten oder Abfragewerte, die Zeichen wie $, + oder ! enthalten.
Mögliche Ursachen:
- URLEncode folgt RFC 1738 und behandelt diese Zeichen als „sicher", daher codiert es sie nie: $ - _ . + ! * ' ( ) ,. Ein Ziel, das erwartet, dass diese Zeichen prozentual codiert werden, erhält stattdessen das Rohzeichen.
- Die Multibyte-Zeichenunterstützung in URLEncode erfordert Agent-Version 12.4 oder später. Bei früheren Agents werden Multibyte-Zeichen möglicherweise nicht wie erwartet codiert.
Lösung:
- Wenn „sichere" Zeichen codiert werden müssen (z. B. in einem OAuth-Passwort oder einem Wert, der + enthält), verwenden Sie stattdessen die JavaScript-Funktion encodeURIComponent in einem JavaScript-Skriptschritt anstelle von URLEncode:
```
<javascript>
$my_username = "$Example+User";
$loginValue = encodeURIComponent($my_username);
</javascript>
```
  Dies gibt %24Example%2BUser zurück.
- Um Multibyte-Zeichen mit URLEncode zu codieren, bestätigen Sie, dass sich der Agent in Version 12.4 oder später befindet.

JavaScript: Fehler „Call to Jitterbit Tomcat failed"

Symptom: Ein komplexer oder lange laufender JavaScript-Schritt schlägt mit einem generischen Fehler fehl, der auf Tomcat verweist, obwohl beide Jitterbit Apache- und Jitterbit Tomcat-Dienste auf dem Agent ausgeführt werden. Das Skript kann erfolgreich sein, wenn seine Komplexität reduziert wird (z. B. durch Verringern der Iterationszählungen oder der Rekursionstiefen).
```
Call to Jitterbit Tomcat failed (null response). Make sure the Jitterbit Apache and Jitterbit Tomcat services are both running.
Failed to execute script
```
Mögliche Ursache: Tiefe rekursive JavaScript-Aufrufe können das Rekursionstiefe-Limit der JavaScript-Engine des Agents überschreiten und einen Stack-Overflow verursachen, der sich als dieser generische Tomcat-Fehler äußert. Dieses Rekursionslimit ist beabsichtigt. Das Skript wird normalerweise abgeschlossen, sobald die Rekursionstiefe reduziert wird.
Lösung:
- Reduzieren Sie die Rekursionstiefe, oder schreiben Sie die rekursive Logik als iterative Schleife um.
- Wenn der Algorithmus tiefe Rekursion nicht vermeiden kann, verwenden Sie einen Ansatz, der sich nicht darauf verlässt.
- Beachten Sie, dass das separate Pro-Skript-Schleifeniterationslimit (JavaScriptMaxIterations, siehe Script loop iteration limit exceeded) die Rekursionsobergrenze nicht erhöht, die nicht als konfigurierbare Einstellung verfügbar gemacht wird.

JavaScript: Änderungen an globalen Variablen gehen bei Scriptfehlern verloren

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

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

Symptom: Der Aufruf von Jitterbit.GetVar auf einer benutzerdefinierten Projektvariablen in einem JavaScript-Skriptschritt gibt null statt des Variablenwerts zurück, ohne Fehlermeldung.
Mögliche Ursache: Jitterbit.GetVar und Jitterbit.SetVar sind für Jitterbit-Systemvariablen (z. B. jitterbit.operation.name) und für Variablennamen mit Punkt vorgesehen, auf die JavaScripts Punktnotation nicht direkt zugreifen kann. Sie lesen keine gewöhnlichen benutzerdefinierten Projektvariablen, deren Namen keinen Punkt enthalten; die Übergabe eines solchen Namens an GetVar gibt null zurück. Referenzieren Sie diese Variablen stattdessen direkt mit $name. Diese Funktionen konvertieren auch alle Werte in Strings, daher sind sie nicht für Arrays oder Objekte geeignet. Ein mit SetVar gesetzter Wert kann mit GetVar innerhalb desselben Skripts gelesen werden, bleibt aber nicht in späteren Skripten erhalten.
Lösung: Verwenden Sie die $variableName-Syntax direkt in JavaScript, um auf benutzerdefinierte Projekt- und globale Variablen zuzugreifen, deren Namen keinen Punkt enthalten. Reservieren Sie GetVar und SetVar für Jitterbit-Systemvariablen und für Variablen, deren Namen einen Punkt enthalten (z. B. $hello.world), auf die JavaScripts Punktnotation nicht direkt zugreifen kann. Verwenden Sie für eine bestimmte Variable entweder $-Präfix oder GetVar/SetVar, nicht beides. Siehe auch JavaScript: Globale Variablenänderungen gehen bei Skriptfehlern verloren.
```
// Correct: access a user-defined project variable directly
var value = $myProjectVar;

// Incorrect for user-defined variables without periods:
var value = Jitterbit.GetVar("$myProjectVar"); // returns null
```

Schema-Datei hochladen ersetzt sie projektübergreifend

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

Bereitstellung von Marketplace-Prozessvorlagen schlägt aufgrund von Schema-Nichtübereinstimmung fehl

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

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

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

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

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

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 sind nur in bestimmten Regionen verfügbar und erfordern ein Regionspräfix in der Modell-ID.
Lösung:
1. Fügen Sie das Regionspräfix zur Modell-ID hinzu. Beispiel: anthropic.claude-3-5-haiku-20241022-v1:0 wird zu us-anthropic.claude-3-5-haiku-20241022-v1:0.
2. Geben Sie die Modell-ID mit Präfix mithilfe der Option Modellkennung eingeben in der Aktivitätskonfiguration ein.

Cloud Datastore: Die Aktivität „Elemente löschen" meldet Erfolg, löscht den Datensatz aber nicht

Symptom: Eine Cloud Datastore-Aktivität Elemente löschen meldet Erfolg im Operationsprotokoll, aber der Zieldatensatz existiert noch, wenn er danach abgefragt wird.
Mögliche Ursache: Elemente löschen identifiziert Datensätze anhand des Schlüssel-Werts (oder Alternativer Schlüssel) des Speichers, der im Array keys oder ids der Anfrage bereitgestellt wird. (Beide Arrays akzeptieren Schlüssel- oder alternative Schlüsselwerte.) Wenn statt des Schlüsselwerts die interne ID des Datensatzes bereitgestellt wird, stimmt kein Element überein, und die Aktivität meldet Erfolg, ohne etwas zu löschen.
Lösung:
- Ordnen Sie in der Transformation, die die Anfrage Elemente löschen vorbereitet, den Schlüssel-Wert (oder Alternativer Schlüssel) des Speichers zu, nicht die interne Datensatz-ID.
- Wenn Sie von einer Aktivität Elemente abfragen verketten, ordnen Sie den key-Wert aus der Abfrageantwort der Löschanfrage zu.

Coupa: API-Schlüssel-Authentifizierung gibt 403 Forbidden zurück

Symptom: Ein Coupa-Connector-Vorgang schlägt mit einem Forbidden (403)-Fehler fehl, wenn die API-Schlüssel-Authentifizierung verwendet wird.
Mögliche Ursache: Seit Coupa Release R35 (Januar 2023) sind Coupa API-Schlüssel veraltet und werden für die Authentifizierung nicht mehr unterstützt. Verbindungen, die für die API-Schlüssel-Authentifizierung konfiguriert sind, erhalten einen 403-Fehler.
Lösung:
1. Wechseln Sie in der Coupa-Verbindungskonfiguration von der API-Schlüssel-Authentifizierung zur 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, z. B. ein JWT oder ein anderes Zugriffstoken, obwohl die gleiche Abfrage bei direkter Ausführung gegen die Datenbank erfolgreich ist.
Mögliche Ursache: Versionen des Agenten 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:
- Aktualisieren Sie für private Agenten auf Version 12.9 oder später. Cloud-Agenten erhalten das Update automatisch.
- Wenn Sie nicht sofort aktualisieren können, vermeiden Sie die Base64-Prüfung, indem Sie den betroffenen Wert in der SQL-Abfrage in Hexadezimal konvertieren und dann in einem Skriptschritt mit HexToString decodieren. Beispiel in PostgreSQL: SELECT encode(<column>, 'hex'). Verwenden Sie das entsprechende SQL decode(...,'hex') mit StringToHex, wenn Sie den Wert zurück in die Datenbank schreiben.

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

Symptom: Beim Lesen aus oder Schreiben in eine Datenbank über den Database-Connector mit einem ODBC-Treiber werden Mehrbyte- oder Nicht-ASCII-Zeichen (z. B. Zeichen mit Akzenten oder Nicht-Lateinzeichen) nicht korrekt verarbeitet.
Mögliche Ursache: Die Unterstützung für Mehrbyte-Zeichen für den Database-Connector ü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 ist nicht erforderlich, wenn ein JDBC-Treiber verwendet wird.
Lösung:
1. Bestätigen Sie, dass der Agent Version 12.6 oder später ist.
2. Setzen Sie die Variable jitterbit.scripting.db.multibyte.enable auf true, bevor der Datenbankvorgang ausgeführt wird. Beispiel in einem Skriptschritt:
```
$jitterbit.scripting.db.multibyte.enable = true;
```

Alternativ können Sie einen JDBC-Treiber für die Datenbankverbindung verwenden, der Multibyte-Zeichen ohne diese Variable verarbeitet.

Datenbank: Verbindung 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 spezifischen Verbindungsstringparameter:

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

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

Datenbank: `DBLookup` oder `DBExecute` schlägt beim Testen eines Skripts mit „Kein geeigneter Treiber gefunden" fehl

Symptom: Das Testen eines Skripts (mit Run test), das DBLookup oder DBExecute aufruft, schlägt fehl mit:
```
No suitable driver found for [...]
```
Das gleiche Skript wird erfolgreich ausgeführt, wenn es bereitgestellt und in einem Vorgang ausgeführt wird.
Mögliche Ursache: Die Datenbankverbindung, die von der Funktion verwendet wird, hat ihr Feld Login, Password oder Connection String auf eine globale oder Projektvariable gesetzt. Ein Skripttest führt nur das getestete Skript aus, daher hat die Variable ihren Laufzeitwert noch nicht zugewiesen, wenn die Funktion die Verbindung auflöst. Im Gegensatz zu einer Variablen, auf die in einem konfigurierten Feld einer Aktivität selbst verwiesen wird, wird dies nicht durch den Standardwert einer Variablen abgedeckt; eine Datenbankfunktion liest den Standardwert nicht beim Auflösen einer Verbindung.
Lösung: Weisen Sie vor dem Funktionsaufruf die gleiche globale oder Projektvariable temporär ihren tatsächlichen Wert direkt im getesteten Skript zu (z. B. $login = "value"; für eine Variable namens login), und entfernen Sie dann die Zuweisung vor der Bereitstellung des Vorgangs.

Datenbank: Feldlängenfehler bei Insert, Update oder Upsert

Symptom: Eine Datenbank-Aktivität Insert, Update oder Upsert schlägt mit dem Betriebsstatus Error fehl, wenn ein zugeordneter Quellwert länger ist als die Zielpalte zulässt. Das Operationsprotokoll enthält eines der folgenden Elemente:
```
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 einen Fehler-Status, wenn ein zugeordneter Quellwert die definierte Länge der Zielspalte überschreitet, anstatt den Wert zu kürzen.
Lösung:
1. Aktivieren Sie in der Konfiguration der Datenbankaktivität Insert, Update oder Upsert die Option Kürzung von Zeichenfeldern zulassen, um Feldlängenfehler zu vermeiden. Mit dieser Option werden Werte, die die Zielfeld-Länge überschreiten, gekürzt und der Vorgang meldet einen Erfolg mit Info-Status statt eines Fehler-Status.
2. Falls eine Kürzung nicht akzeptabel ist, kürzen oder transformieren Sie das Quellfeld in der Transformationszuordnung, damit Werte die Zielspaltenlänge nie überschreiten, oder vergrößern Sie die Zielspalte auf der Datenbankseite.
3. Stellen Sie den Vorgang erneut bereit und führen Sie ihn erneut aus.

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

Symptom: Benutzerdefinierte JDBC-Treiber-JAR-Dateien, die für den Datenbankconnector 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-Upgrades beibehalten. Benutzerdefinierte Treiber-JAR-Dateien, die an anderen Stellen in den Agent-Verzeichnissen platziert werden, sind Teil der verwalteten Bereitstellung und können während eines Upgrades 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-Upgrades beibehalten.
- Falls sich Treiber derzeit am falschen Ort befinden, verschieben Sie diese 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 für die physische Tabelle, die die betroffene Spalte unter einem Namen verfügbar macht, der keine Sonderzeichen enthält.
2. Verweisen Sie die Datenbankaktivität auf die Ansicht statt auf die ursprüngliche Tabelle.

Datenbank: SQL-Anweisung überschreitet Limit von 2.000 Zeichen

Symptom: Eine Datenbankaktivität Query schlägt fehl oder wird gekürzt, wenn die konfigurierte SQL-Anweisung sehr lang ist.
Mögliche Ursache: Das SQL-Anweisungsfeld in einer Datenbankaktivität Query akzeptiert maximal 2.000 Zeichen.
Lösung:
1. Erstellen Sie eine Datenbankansicht, die die komplexe Abfragelogik kapselt.
2. Verweisen Sie in der Aktivität Query auf den Ansichtsnamen statt auf die vollständige SQL-Anweisung.

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

Symptom: Eine Datenbankverbindung zu IBM DB2 auf iSeries (AS/400 oder IBM i) mit einem JDBC-Treiber kann keine Verbindung herstellen.
Mögliche Ursache: Einige Verbindungen zu DB2 auf iSeries mit einem JDBC-Treiber treten auf Probleme auf, die bei einem ODBC-Treiber nicht auftreten.
Lösung: Wechseln Sie die Verbindung, um statt JDBC einen ODBC-Treiber zu verwenden. ODBC-Verbindungen werden nur auf privaten Agents 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 einem Fehler fehl, der auf eine fehlende Lizenz verweist, oder schlägt fehl oder erzeugt 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 erfordert eine separate Lizenz-JAR-Datei. Die Treiber-JAR allein ist nicht ausreichend.
Lösung:
- Verwenden Sie den db2jcc4.jar-Treiber, nicht die veraltete db2jcc.jar. Installieren Sie ihn in <JITTERBIT_HOME>/tomcat/drivers/lib/ auf dem privaten Agent.
- Besorgen Sie sich die Lizenz-JAR-Datei von IBM (benannt db2jcc_license_cisuz-XX.jar, wobei XX die Versionsnummer ist) und kopieren Sie sie nach <JITTERBIT_HOME>/tomcat/shared/lib/.
- Verwenden Sie alternativ die JTOpen Open-Source-Bibliothek (auch als AS400-Treiber bekannt), die weder den JCC-Treiber noch eine Lizenzdatei erfordert.

Kerberos: „Klasse KerbAuthentication konnte nicht initialisiert werden"

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 korrekten 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
```
2. Starten Sie den Agent nach dem Ändern der Berechtigungen neu.

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

Symptom: Eine Datenbankverbindung 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, was sie anweist, die native GSSAPI-Bibliothek des Betriebssystems zu verwenden. 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: „Vorgang muss eine aktualisierbare Abfrage verwenden"

Symptom: Eine Datenbankaktivität vom Typ Einfügen oder Aktualisieren für eine Microsoft Excel-Datei (über ODBC) schlägt fehl mit:
```
[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, es sei denn, die Verbindungszeichenfolge legt explizit den Lese-/Schreibmodus fest.
Lösung: Fügen Sie im Feld Verbindungszeichenfolge der Datenbankverbindung (eingegeben unter Optionale Einstellungen mit ausgewählter Option Verbindungszeichenfolge verwenden) am Ende der Verbindungszeichenfolge ReadOnly=0; hinzu, um die Excel-Datei im Lese-/Schreibmodus zu öffnen.

MySQL: Zugriff verweigert trotz korrekter Anmeldedaten

Symptom: Die Verbindung zu einer MySQL-Datenbank mit dem Database-Connector schlägt fehl mit:
```
Access denied for user 'root'@'%' to database 'test'
```
auch wenn Benutzername und Passwort korrekt sind.
Mögliche Ursache: MySQL kann unterschiedliche Berechtigungen basierend auf der Client-IP-Adresse gewähren. Ein Benutzerkonto kann die erforderlichen Berechtigungen von bestimmten IP-Adressen haben, aber nicht von der IP-Adresse des privaten Agenten.
Lösung:
- Überprüfen Sie in MySQL, dass das Benutzerkonto die erforderlichen Berechtigungen für Verbindungen von der IP-Adresse des privaten Agenten hat. Die genaue Grant-Syntax variiert je nach MySQL-Version (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 Konnektivität mit einem MySQL-Client, der direkt auf dem Agent-Host installiert ist, um festzustellen, ob das Problem netzwerkbasiert oder Jitterbit-spezifisch ist.

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

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

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

Symptom: Beim Konfigurieren einer Database-Verbindung zu MySQL mit einem ODBC-Treiber auf einem privaten Agenten wird der installierte Treiber nicht im Dropdown Driver in Studio angezeigt.
Mögliche Ursache: Der ODBC-Manager auf dem privaten Agent-Host zeigt den Treiber nicht an, normalerweise aufgrund einer 32-Bit- vs. 64-Bit-Nichtübereinstimmung oder einer unvollständigen Treiberinstallation.
Lösung:
- Öffnen Sie auf dem privaten Agent-Host (Windows) Data Sources (ODBC) (unter Administrative Tools) und bestätigen Sie, dass der MySQL ODBC-Treiber aufgelistet ist. Informationen zu MySQL-Treiberoptionen finden Sie unter Connect to MySQL.
- 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: Fehler bei Client-Encoding-Nichtübereinstimmung

Symptom: Ein Verbindungstest des Database-Connectors zu PostgreSQL schlägt mit einem Fehler „client encoding mismatch" fehl.
Mögliche Ursache: Das Encoding, das der PostgreSQL-Server verwendet, unterscheidet sich vom Standard-Encoding, das der PostgreSQL ODBC-Treiber annimmt.
Lösung:
- Fügen Sie in den Database-Verbindungseinstellungen ConnSettings=SET CLIENT_ENCODING to 'LATIN1' (ersetzen Sie das tatsächliche Encoding des Servers) zum Feld Additional Connection String Parameters hinzu.
- Wenn der Server unter Windows ein kyrillisches Encoding wie WIN1251 verwendet, stellen Sie das Client-Encoding auch in den ODBC-Treibereinstellungen auf WIN1251 ein.

PostgreSQL: Jitterbit-bereitgestellten Treiber unter Linux verwenden

Symptom: Operationen, die den Database-Connector verwenden, um sich von einem privaten Linux-Agent aus mit PostgreSQL zu verbinden, schlagen fehl oder erzeugen Fehler, auch 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 bereitgestellten 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 Database-Verbindung zu SQL Server mit einem JDBC-Treiber und Windows-integrierter Authentifizierung fehl mit:
```
This driver is not configured for integrated authentication. ClientConnectionId:...
```
Die Agent-Protokolle können auch Folgendes anzeigen:
```
java.lang.UnsatisfiedLinkError: no mssql-jdbc_auth-8.2.0.x64 in java.library.path
```
Mögliche Ursachen:
- Die für die Windows-integrierte Authentifizierung erforderliche mssql-jdbc_auth-DLL fehlt in den JRE-Verzeichnissen, die der Jitterbit-Agent zur Laufzeit verwendet. Das Platzieren der DLL im selben Verzeichnis wie die JDBC-JAR-Datei ist nicht ausreichend.
- Die Verbindungszeichenfolge enthält nicht den Parameter integratedSecurity=true.
Lösung:
1. Kopieren Sie auf dem Host des privaten Agents mssql-jdbc_auth-x.x.x.x64.dll (aus der JDBC-Treiberverteilung, mit der Version, die der mit Ihrem Agent gebündelten JDBC-JAR-Datei entspricht) in beide Verzeichnisse <JITTERBIT_HOME>/jre/bin und <JITTERBIT_HOME>/jre/lib. Sichern Sie die Datei, da sie bei größeren Agent-Upgrades möglicherweise entfernt wird.
2. Fügen Sie in den Database-Verbindungseinstellungen integratedSecurity=true zum Feld Zusätzliche Verbindungszeichenfolgen-Parameter hinzu.
3. Starten Sie den Jitterbit-Agent-Dienst neu.

SQL Server Windows-Authentifizierung: Unzureichende Berechtigungen

Symptom: Eine Database-Verbindung mit SQL Server Windows-Authentifizierung schlägt fehl, auch wenn 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 Integrated Security.
Lösung:
1. Gewähren Sie dem Domänenbenutzer die Windows-Berechtigungen Als Dienst anmelden und Als Teil des Betriebssystems fungieren auf dem Host des privaten Agents.
2. Bestätigen Sie, dass der Domänenbenutzer Lese- und Schreibberechtigungen für das Installationsverzeichnis des Jitterbit-Agents hat.
3. Starten Sie den Jitterbit-Agent-Dienst neu, nachdem Sie Berechtigungsänderungen angewendet haben.

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

Symptom: Eine Database-Connector-Operation, die 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 Database-Connector für das Ziel generiert. SQL Server lehnt ein INSERT ab, das auf eine Identitätsspalte in seiner Spaltenliste verweist (mit einem expliziten Wert oder null), während IDENTITY_INSERT auf OFF gesetzt ist. Das Zuordnen des Felds zu einem Nullwert schließt es nicht aus: Ein Zielfeld wird aus dem INSERT nur ausgelassen, wenn es mit der Funktion Unmap zugeordnet ist.
Lösung:
- Um SQL Server den Identitätswert automatisch zuweisen zu lassen, schließen Sie die Spalte aus dem INSERT aus, indem Sie das Identitätszielfeld mit der Funktion Unmap zuordnen. Um die Spalte nur auszuschließen, wenn die Quelle keinen Wert bereitstellt, verwenden Sie eine bedingte Zuordnung:

If($source.id != "", $source.id, Unmap())

Wenn die Bedingung falsch ist, entfernt Unmap die Spalte aus dem INSERT und SQL Server weist den nächsten Identitätswert zu. (Das Angeben eines expliziten Werts im true-Branch erfordert weiterhin, dass IDENTITY_INSERT ON ist; siehe die nächste Option.)

Wenn Sie explizite Werte in die Identitätsspalte einfügen müssen, setzen Sie 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 Identitätswerte von außerhalb der Datenbank steuern möchten. Sie ermöglicht das Einfügen expliziter Werte in die Identitätsspalte.

SQL Server: Verbindung schlägt mit 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 funktioniert hat, 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 for 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 aktualisierte den gebündelten Treiber auf eine Version, 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 fügen Sie es in eine manuelle Verbindungszeichenfolge ein. Dies funktioniert auf Cloud- und Private Agents. Weitere Informationen finden Sie unter Verbindungsverschlüsselung und Serverzertifikate.

Warnung

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

E-Mail senden schlägt fehl, wenn dieselbe Adresse in mehreren Empfängerfeldern angezeigt wird

Symptom: Eine Email-Aktivität Email 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 Email-Connector erlaubt nicht, dass dieselbe Adresse in mehreren Empfängerfeldern in einer einzelnen Sendeanfrage erscheint. 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 jeder Transformationszuordnung für die Aktivität, um sicherzustellen, dass keine Adresse in mehr als einem Feld erscheint.
- Wenn Empfängerlisten dynamisch mit Variablen oder Skripten zusammengestellt werden, fügen Sie eine Deduplizierungsprüfung hinzu, bevor Sie Adressen an die Aktivität übergeben.

Gmail-Verbindungstest schlägt mit Authentifizierungsfehler fehl

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

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 funktioniert nur bei Verwendung von privaten Agenten. Wenn der Vorgang auf einem Cloud-Agent ausgeführt wird, gilt die S/MIME-Signierung unabhängig vom Zertifikattyp nicht.
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 bei privaten Agenten, dass das Zertifikat korrekt in den Standard-Truststore des Agenten importiert wurde. Bei Cloud-Agenten wird die S/MIME-Signierung nicht unterstützt.

Microsoft 365-E-Mail-Verbindung mit ROPC-Authentifizierung schlägt fehl, wenn MFA aktiviert ist

Symptom: Eine Microsoft 365-OAuth 2.0-Verbindung, die den ROPC-Grant (Resource Owner Password Credentials) verwendet, schlägt bei der Authentifizierung fehl, auch wenn Benutzername, Passwort, Client-ID, Mandanten-ID und Client-Geheimnis alle korrekt sind.
Mögliche Ursache: Die ROPC-Authentifizierung erfordert, dass die Multi-Faktor-Authentifizierung (MFA) für die Microsoft 365-Anmeldedaten, die mit dem Connector verwendet werden, deaktiviert ist. Der ROPC-Grant kann eine MFA-Abfrage 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 unter Voraussetzungen für Microsoft 365 beschrieben.
- Wenn MFA nicht aus dem Konto entfernt werden kann, verwenden Sie eine andere unterstützte Authentifizierungsmethode für die Verbindung anstelle von ROPC.

Epicor Prophet 21: Operation schlägt zur Laufzeit 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 Einschränkung in der Epicor Prophet 21 Middleware API verhindert die Verarbeitung mehrerer Filterbedingungen. Der Vorgang erscheint in Studio gültig, schlägt aber zur Laufzeit fehl, wenn mehr als ein Filter vorhanden ist.
Lösung:
- Reduzieren Sie den Filter String auf eine einzelne Filterbedingung.
- Wenn mehrere Filterbedingungen erforderlich sind, rufen Sie einen breiteren Ergebnissatz mit einem einzelnen Filter ab und wenden Sie die zusätzliche Filterung in einem Transformations- oder Skriptschritt nach der Aktivität an.

FTP, File Share und Local Storage: „Keine Dateien entsprechen dem Dateifilter" bei Archiv- oder Folgenschritten

Symptom: Eine FTP-, File Share- oder Local Storage-Lesaktivität schlägt fehl, weil sich die Datei, die gelesen werden soll, 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 auf (häufig ein Archiv- oder Benachrichtigungsschritt), 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, sodass der Archivschritt nichts zum Abgleichen hat.
- 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 nach 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 Sie, ob der vorherige Schritt die Archivierung bereits über seine integrierten After Processing-Optionen (verschieben, umbenennen, löschen) durchgeführt hat. Wenn ja, ist ein separater Archivschritt redundant und sollte entfernt werden.
- Wenn ein separater Archivschritt erforderlich ist, gestalten Sie die Kette so um, dass Verarbeitung und Archivierung gegen dieselbe In-Memory-Dateireferenz erfolgen, anstatt erneut aus der Quelle zu lesen. Übergeben Sie beispielsweise den gelesenen Inhalt über Temporary Storage an den Archivschritt, anstatt den Quellpfad erneut zu lesen.
- Wenn ein Folgenschritt eine Ausgabe liest, die von einem untergeordneten Vorgang erzeugt wird, führen Sie den untergeordneten Vorgang synchron aus, damit seine Ausgabe vor dem Lesen vorhanden ist. Stellen Sie den Run type des Invoke Operation-Tools auf Synchronously ein, oder führen Sie beim Aufrufen des Vorgangs aus einem Skript RunOperation synchron aus (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.
- Wenn eine FTP-Write-Aktivität in denselben Speicherort schreibt, überprüfen Sie, ob Use FTP Rename in der FTP Write-Aktivität aktiviert ist. Wenn der nachgelagerte Lesevorgang vor Abschluss der Umbenennung ausgelöst wird, deaktivieren Sie Use FTP Rename in der Schreibaktivität, oder stellen Sie sicher, dass der Lesevorgang erst ausgeführt wird, wenn die Schreibaktivität vollständig abgeschlossen ist.

FTP, File Share und Local Storage: Fehlerordner wird bei Verbindungsfehler nicht geschrieben

Symptom: Nachdem eine FTP-, File Share- oder Local Storage-Aktivität fehlschlägt, wird keine Datei im konfigurierten Fehlerordner angezeigt.
Mögliche Ursache: Der Fehlerordner dient dazu, eine Kopie der Quelldatei nach erfolgloser Verarbeitung zu archivieren. Er erfasst Dateien nur, wenn die Aktivität ausgeführt wird und dann fehlschlägt (z. B. 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 (z. B. ein Authentifizierungsfehler oder eine Meldung, dass der Host nicht erreichbar ist).
- Verwenden Sie die Schaltfläche Test für die Verbindung, um zu bestätigen, ob das Problem auf Netzwerk- oder Authentifizierungsebene liegt.

FTP, File Share und Local Storage: Dateinamen-Schlüsselwörter werden in Erfolgs- und Fehlerordnerpfaden nicht aufgelöst

Symptom: Vorgänge verschieben Dateien nach der Verarbeitung in Erfolgs- oder Fehlerordner, aber der Zielpfad enthält unerweiterten Schlüsselworttext statt aufgelöster Werte. Der Vorgang kann fehlschlagen oder Dateien an unerwartete Orte 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 Dateinamen-Schlüsselwortsubstitution. Variablen werden in diesen Feldern nicht erweitert.
- Diese Felder beziehen sich auf Verzeichnisse auf dem Private Agent-Computer, nicht auf dem Remote-Server. Relative Pfade werden relativ zum Dateisystem des Agent-Hosts interpretiert.
Lösung:
- Verwenden Sie nur literale Pfade (ohne Dateinamen-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 mit Dateifunktionen an den gewünschten Ort zu verschieben oder umzubenennen.

FTP, File Share, Local Storage und Temporary Storage: „Write Headers" erstellt keine reine Header-Datei, wenn die Quelle keine Datensätze zurückgibt

Symptom: Eine dateibasierte Schreibaktivität mit aktivierter Option Write Headers (FTP Write, File Share Write, Local Storage Write oder Temporary Storage Write) schreibt keine Header, wenn die Quelle keine Datensätze zurückgibt. Es wird entweder eine leere Datei erstellt oder überhaupt keine Datei (wenn auch Do not create empty files ausgewählt ist).
Ursache: Dies ist das erwartete Verhalten. Header 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, sodass keine Ausgabe (einschließlich Header) geschrieben wird und Studio eine Warnung protokolliert, dass die Quelle leer ist. Dies ist nicht spezifisch für einen bestimmten Quell-Connector oder ein bestimmtes Flat-File-Ziel.

FTP: Operation schlägt nach vielen schnellen Anmeldungen beim gleichen Server fehl

Symptom: Eine Operation mit dem FTP-Connector (über FTP oder SFTP-Protokoll), die sich in schneller Abfolge mehrmals beim gleichen Server authentifiziert (beispielsweise beim Lesen von Hunderten kleiner Dateien in einer Schleife oder bei vielen Operationen, die nach einem Zeitplan gegen den gleichen Server laufen), schlägt schließlich mit einer Anmeldungsverweigerung oder einem Verbindungsfehler fehl. Die gleiche Operation läuft unter geringerer Last erfolgreich.
Mögliche Ursachen:
- Der FTP-Connector öffnet für jede Aktivitätsausführung eine neue Verbindung, authentifiziert sich und schließt sie, wenn die Operation endet. Eine Sitzung wird nicht über Aktivitäten, Operationsausführungen oder Projekte hinweg wiederverwendet. Dies ist beabsichtigt. Wenn viele Operationen gegen den gleichen Server laufen, beispielsweise mehrere geplante Operationen oder mehrere Projekte, die auf den gleichen Host abzielen, authentifiziert sich jede Ausführung unabhängig.
- Der Remote-Server ist mit einer maximalen Anzahl von Verbindungen, Authentifizierungen pro Minute oder gleichzeitigen Sitzungen 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-Aktivität in einer Schleife durch eine einzelne Read-Aktivität, die einen Platzhalter im Feld Get Files verwendet (beispielsweise *.xml oder data_*.csv), und teilen Sie die abgerufenen Daten dann in einzelne Datensätze in einer Transformation auf.
- Wenn die Operation Dateien einzeln verarbeiten muss, bitten Sie den FTP-Server-Administrator, den Grenzwert für gleichzeitige Verbindungen oder Authentifizierungen pro Minute pro Benutzer zu erhöhen.

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

Symptom: Eine SFTP-Operation mit SSH-Authentifizierung mit privatem Schlüssel schlägt mit Login denied. Authentication failure. fehl, obwohl sich die gleichen Schlüssel erfolgreich von einem interaktiven SFTP-Client aus 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 Einstellung PrivateKeyPassphrase fehlt im Abschnitt [SSH] der Agent-Datei jitterbit.conf.
- Ein Passwort ist im FTP-Endpoint zusammen mit dem privaten Schlüssel konfiguriert. Das Vorhandensein eines Passworts in den Endpoint-Einstellungen beeinträchtigt die schlüsselbasierte Authentifizierung.
Lösung:
- Bestätigen Sie für private Agents, dass der Abschnitt [SSH] von jitterbit.conf den korrekten Pfad PrivateKeyFile und, falls der Schlüssel durch eine Passphrase geschützt ist, den entsprechenden Wert PrivateKeyPassphrase enthält (siehe Connecting to SFTP with SSH keys).
- Löschen Sie in der FTP-Endpoint-Konfiguration das Feld Password, wenn die Authentifizierung über SSH-Schlüssel erfolgt.
- Bestätigen Sie, dass der Schlüssel in einem vom Agent unterstützten Format vorliegt (OpenSSH). 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-Aktivität, die mit der Option Use FTP Rename konfiguriert ist, 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>.
```
Der <reason> ist typischerweise No such file or directory oder Permission denied für eine Datei, deren Name Multibyte-Zeichen enthält.
Mögliche Ursachen:
- Bei Agents vor Version 11.56 hat die Option Use FTP Rename den Umbenennungsschritt beim Schreiben auf einen SFTP-Server nicht zuverlässig berücksichtigt, besonders bei Operationen mit archive pattern.
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 (außer auf Windows-Private-Agents ab Agent-Version 12.10; siehe Zeichenkodierung und Multibyte-Unterstützung); bei aktiviertem Use FTP Rename lädt der Agent die Datei jedoch unter einem temporären Namen (Suffix -jbupload) hoch und benennt sie dann in den endgültigen Namen um. Wenn der Server den Multibyte-Namen nicht umbenennen kann, gibt er eine irreführende Fehlermeldung Permission denied zurück. Dateinamen mit nur ASCII-Zeichen sind nicht betroffen. Dies ist eine Einschränkung des SFTP-Servers, nicht von Jitterbit.
Lösung:
- Stellen Sie sicher, dass der Agent Version 11.56 oder später ist, bei der Use FTP Rename mit SFTP wie erwartet funktioniert. Cloud-Agents werden automatisch aktualisiert; aktualisieren Sie Private-Agents 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.
- Verwenden Sie für den Multibyte-Fall alternativ einen SFTP-Server, der das Umbenennen von Dateien mit Multibyte-Namen unterstützt.

SFTP: Anfügen an Datei nicht unterstützt

Symptom: Eine FTP-Write-Aktivität, die mit der Option Append To File konfiguriert ist, fügt nicht an die vorhandene Datei an, wenn das Ziel ein SFTP-Server ist.
Mögliche Ursache: Das SFTP-Protokoll unterstützt das Anfügen an vorhandene Dateien nicht. Dies ist eine Einschränkung auf Protokollebene, kein Jitterbit-Konfigurationsproblem.
Lösung:
- Verwenden Sie FTP oder FTPS, wenn das Anfügeverhalten erforderlich ist.
- Wenn SFTP erforderlich ist, implementieren Sie die Anfüglogik manuell: Lesen Sie den vorhandenen Dateiinhalt, 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 abgekürzten Dateinamen.
Mögliche Ursache: Der FTP-Connector behandelt den Dateipfad als URL, in der das Hash-Zeichen ein reserviertes Fragment-Trennzeichen ist. Der Connector analysiert 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 dazu zu bringen, Namen mit Sonderzeichen wie # URL-zu-kodieren, setzen Sie jitterbit.source.ftp.encode_url in einem Transformationsskript für Quell-Datei- oder Ordnernamen auf true, und jitterbit.target.ftp.encode_url auf true für Dateien, die in das Ziel geschrieben werden.

Symptom: File Share-Verbindungen, die UNC-Pfade verwenden (z. B. \\server\share), können sich nicht verbinden, wenn der Vorgang auf einem Cloud-Agent ausgeführt wird.
Mögliche Ursache: Cloud-Agents können UNC-Pfade mit einer öffentlichen IP-Adresse auflösen, können aber Servernamen in UNC-Pfaden nicht 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 Servernamenauflösung in UNC-Pfaden erforderlich ist, verwenden Sie stattdessen einen Private-Agent.

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

Lokaler Speicher: Nicht auf Cloud-Agenten verfügbar

Symptom: Ein Vorgang mit einem Local Storage-Connector schlägt fehl, wenn er auf einem Cloud-Agent ausgeführt wird.
Mögliche Ursache: Local Storage greift auf das Dateisystem des Computers zu, auf dem der Agent installiert ist. Cloud-Agenten 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 Local Storage-Connector erfordern. Local Storage ist auf Private Agents standardmäßig deaktiviert, daher aktivieren Sie es auch in der Konfigurationsdatei des Private Agent (siehe Enable local file location).
- Ersetzen Sie Local Storage für Cloud Agent-Workflows durch Temporary Storage oder einen externen Speicher-Connector (File Share, FTP oder Cloud Datastore).

Temporärer Speicher: Dateien fehlen, wenn sie von einem späteren Vorgang gelesen werden

Symptom: Temporary Storage-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 aus Temporary Storage standardmäßig nach 24 Stunden.
- Jeder Agent in einer Agent-Gruppe hat seinen eigenen lokalen Temporary Storage. Vorgänge in der gleichen Vorgangskette werden garantiert auf dem gleichen Agent ausgeführt, aber ein späterer Vorgang, der sich nicht in der gleichen Kette befindet, kann an einen anderen Agent verteilt werden und auf eine andere Temporary Storage-Instanz zugreifen, sodass die Datei nicht gefunden wird, unabhängig vom 24-Stunden-Fenster. Siehe Important notes.
Lösung:
- Verknüpfen Sie Vorgänge, die Temporary Storage-Dateien gemeinsam nutzen müssen, in die gleiche operation chain mit operation actions, wobei das Temporary Storage-Verhalten konsistent und zuverlässig ist.
- Für Private Agents kann die Cleanup-Häufigkeit im Abschnitt [FileCleanup] von jitterbit.conf angepasst werden. Siehe [FileCleanup].
- Wenn Dateien nicht innerhalb der gleichen Kette verarbeitet werden können oder länger als 24 Stunden bestehen bleiben müssen, verwenden Sie stattdessen einen persistenten Speicher-Connector, auf den alle Agenten zugreifen können (z. B. File Share, FTP oder Cloud Datastore).

Temporärer Speicher: Eingeschränkte Zeichen in Dateipfaden

Symptom: Eine Temporary Storage Read- oder Write-Aktivität schlägt fehl, wenn der Dateipfad bestimmte Sonderzeichen enthält.
Mögliche Ursache: Die folgenden Zeichen werden in Temporary Storage-Dateipfaden nicht unterstützt: ~, %, $, ", <, >, :, ?
Lösung:
- Entfernen 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: Größenlimit von 50 GB auf Cloud-Agenten

Symptom: Eine Temporary Storage Write-Aktivität schlägt beim Schreiben großer Dateien über einen Cloud-Agenten fehl.
Mögliche Ursache: Cloud-Agenten setzen eine maximale Dateigröße von 50 GB pro Datei für Temporary Storage durch.
Lösung:
- Verwenden Sie einen privaten Agenten für Workflows, die einzelne Dateien größer als 50 GB in Temporary Storage schreiben müssen.
- Wenn nur Cloud-Agenten verfügbar sind, teilen Sie große Datensätze in mehrere Dateien unter 50 GB auf, bevor Sie sie in Temporary Storage 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 codiert 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 Request-URL codieren. Der Connector codiert dann die Request-URL URL-konform und codiert Leerzeichen als %20.
- Geben Sie die Request-URL vollständig uncodiert an. Codieren Sie Zeichen nicht vorab und wenden Sie die Funktion URLEncode nicht auf die URL an, da bereits codierte Zeichen doppelt codiert werden, wenn Request-URL codieren aktiviert ist (z. B. wird example+string%20value zu example%20string%2520value).

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

Symptom: Skripte, die Jitterbit-Quell- oder Zielvariaablen lesen, 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 Zielvariaablen nicht auf. Antwortdaten, einschließlich des HTTP-Status-Codes, werden stattdessen über das Antwortsschema der Aktivität zurückgegeben.
Lösung:
- Um den Status-Code mit dem Standard-Antwortsschema 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). Weitere Informationen zur Struktur des Antwortsschemas finden Sie in der Aktivitätskonfigurationsdokumentation für jede HTTP v2-Aktivität.
- Um den Status-Code bei Verwendung eines benutzerdefinierten Antwortsschemas zu erfassen, aktivieren Sie Include Additional Properties from HTTP Response in the Schema in der Aktivitätskonfiguration. Dies umhüllt das Schema mit einer von Jitterbit definierten Struktur, die __jitterbit_api_statuscode__ (den Status-Code) und __jitterbit_api_errorbody__ (den Antwortkörper für erfolglose Anfragen) enthält.
- Damit der Status-Code verfügbar ist, wenn die API eine erfolglose Antwort zurückgibt, aktivieren Sie Ignore operation error in case of non-successful status code in den optionalen Einstellungen der Aktivität. Ohne diese Einstellung schlägt der Vorgang bei erfolglosen Antworten fehl, bevor die Antwortdaten zugeordnet werden können.

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

Symptom: Ein HTTP v2-Vorgang, der eine XML-Payload an einen SOAP- oder XML-Webservice sendet, schlägt mit einem Serverfehler fehl (z. B. 500 Internal Server Error), obwohl die gleiche Payload erfolgreich von Postman oder SoapUI gesendet wird. Eine Überprüfung des vom Ziel empfangenen Request-Body zeigt, dass XML-Namespace-Deklarationen auf dem Root-Element 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 neu nummeriert).
Mögliche Ursache: Wenn in der HTTP v2-Aktivitätskonfiguration ein benutzerdefiniertes Request-Schema verwendet wird, normalisiert die Transformation standardmäßig die XML, indem alle Namespace-Deklarationen zum Root-Knoten verschoben und ihre Präfixe neu zugewiesen werden. SOAP-Services und andere XML-Endpunkte, die die Konsistenz von Namespace-Präfixen validieren, lehnen die geänderte Payload ab.
Lösung:
- Bei Agent-Version 12.8 oder später setzen Sie jitterbit.target.xml.preserve.namespace.prefix in einem Skriptschritt vor der Transformation auf true, um die Namespace-Präfixe der Quell-XML beizubehalten, anstatt generische zuzuweisen:
```
$jitterbit.target.xml.preserve.namespace.prefix = true;
```
- Wenn Ihre Private Agents älter als 12.8 sind oder das Ziel auch die Konsolidierung von Namespace-Deklarationen auf dem Root-Element ablehnt, verwenden Sie stattdessen das Standard-Request-Schema und ordnen Sie die vollständige XML-Payload als String in das Feld body des Schemas zu. Die Payload wird dann als String behandelt und nicht als XML geparst, sodass ihre Namespace-Deklarationen erhalten bleiben. Das Antwortsschema 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 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 auf einer HTTP v2-Verbindung konfiguriert ist (z. B. Basic oder OAuth), fügt der Connector automatisch einen Authorization-Header zu jeder Anfrage hinzu. Das manuelle Hinzufügen eines zweiten Authorization-Headers führt zu zwei widersprüchlichen 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 Authentifizierungsverwaltung. Fügen Sie keinen manuellen Authorization-Header neben der konfigurierten Authentifizierung hinzu.
- Wenn Sie den Authorization-Header dynamisch auf Aktivitätsebene festlegen müssen, setzen Sie den Authentifizierungstyp der Verbindung auf No Auth und konfigurieren Sie den Authorization-Request-Header der Aktivität nach Bedarf.

HTTP v2: JSON-Wert in einer Request-Header-Projektvariable kann nicht geparst werden

Symptom: Eine HTTP v2-Aktivität, die einen Request-Header-Wert aus einer Projektvariablen mit einer JSON-Zeichenkette liest, schlägt mit einem Parse-Fehler fehl:
```
Expected a ',' or ']' at 139 [character 140 line 1]
```
Dieselbe JSON funktioniert, wenn sie 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, escaped 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 nicht escapten Anführungszeichen unterbrechen die Header-Zeichenkette, bevor sie das Ziel erreicht.
Lösung:
- Wenn Sie JSON in einer Projektvariablen speichern, die als Header-Wert verwendet wird, escapen Sie jedes doppelte Anführungszeichen mit einem Backslash. Speichern Sie den Wert beispielsweise als {\"success\": \"true\"} statt als {"success": "true"}.
- Wenn der JSON-Inhalt statisch ist, fügen Sie ihn direkt in die Spalte Value der Tabelle Request Headers ein, anstatt eine Variable zu verwenden. Der Connector wendet das erforderliche Escaping in diesem Pfad an.

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

Symptom: Ein HTTP- oder HTTP v2-Vorgang schlägt beim Zielsystem fehl. Die Agent-Protokolle zeigen, dass die Anfrage-URL mehr als ein ? zwischen Segmenten enthält, z. B. 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 alle Abfragezeichenfolgen-Segmente aus dem URL-Pfad. Die Basis-URL sollte nur den Pfad selbst enthalten (z. B. 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 Erstellen der endgültigen URL ein.

HTTP v2: Doppelte URL-Codierung, wenn „Request-URL codieren" aktiviert ist

Symptom: REST-API-Aufrufe über den HTTP v2-Connector schlagen beim Zielsystem fehl, da URL-Parameter in der ausgehenden Anfrage doppelt codiert sind (z. B. 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. Wenn URL-Parameter bereits prozentcodierte 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 mit der Funktion URLEncode erstellt wurden.
- Wenn 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: Vorgang schlägt fehl, wenn die Basis-URL umleitet

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 in ihrem Feld Path, aber 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 das Protokoll und den Host enthält, z. B. https://api.example.com/...) wurde in das 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 Host-Teil des Endpunkts fest (z. B. 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 in diesem Teilpfad (z. B. /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 String `"null"`

Symptom: Eine HTTP-POST- oder PUT-Aktivität sendet Felder, die mit der Funktion Null zugeordnet sind, als String "null" (oder lässt sie weg), statt ein JSON-Literal null auszugeben. Dies tritt auf, wenn das Request-Schema in der Aktivität definiert ist.
Mögliche Ursache: Wenn das Request-Schema 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 kein Request-Schema in der Aktivität bereitgestellt wird, 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, bestehende HTTP-Verbindungen und -Aktivitäten zu HTTP v2 zu konvertieren.
- Wenn die Aktivität auf HTTP bleiben muss, definieren Sie das Request-Schema in der Transformation statt in der Aktivität, und lassen Sie das Request-Schema 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 Ziel-Eintrag untergeordnete Einträge hat

Symptom: Eine LDAP-Aktivität Delete Entry schlägt mit einem Fehler vom LDAP-Server fehl (z. B. 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 (Unterordnungen) hat. 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 einer gesamten Teilstruktur erforderlich ist, implementieren Sie ein Skript, das Einträge von unten nach oben identifiziert und löscht, indem Sie RunOperation mit der LDAP-Aktivität Delete Entry für jeden Eintrag verwenden.

LDAP Search Entry: Filterausdruck ist auf einigen Servern case-sensitiv

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

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

Symptom: Operationen, die einen Microsoft SharePoint Server-Konnektor mit dem SOAP-Schema-Verbindungstyp verwenden, 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 wird. Nach dem 1. Mai 2026 wird erwartet, dass Operationen, die das SharePoint-SOAP-Schema für SharePoint Online-Verbindungen verwenden, fehlschlagen.
Lösung:
1. Öffnen Sie in Studio jede betroffene SharePoint-Verbindung und ändern Sie die Schema-Einstellung von SOAP zu REST.
2. Konfigurieren Sie alle Aktivitäten, die das SOAP-Schema verwendet haben, so um, dass sie entsprechende REST-Operationen verwenden.
3. Testen und stellen Sie die betroffenen Operationen erneut bereit.
4. Weitere Informationen zur Migration finden Sie in der Dokumentation zum Microsoft SharePoint Server-Konnektor.

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

Symptom: Operationen, die den Microsoft Dynamics 365 Business Central v2-Konnektor verwenden, schlagen mit Fehlern fehl, die darauf hindeuten, dass Typnamen in der Nutzlast nicht mit den OData-Metadaten kompatibel sind.
Mögliche Ursache: Bestimmte Dynamics 365 Business Central OData-API-Endpunkte erfordern OData-Typanmerkungen in der Anfragenutzlast. Standardmäßig enthält der Konnektor diese Anmerkungen nicht, was zu Typinkompatibilitätsfehlern bei diesen Endpunkten führt.
Lösung:
1. Öffnen Sie die Konfiguration der Microsoft Dynamics 365 Business Central v2-Aktivität Aktualisieren.
2. Aktivieren Sie unter Optionale Einstellungen die Option OData-Typ in Nutzlast festlegen.
3. Speichern Sie die Aktivität und testen Sie die betroffenen Operationen erneut.

Microsoft Entra ID: Erweiterungsattribute nicht als Abfragefilter-Bedingungen wählbar

Symptom: Beim Konfigurieren einer Microsoft Entra ID-Aktivität Abfrage werden das Feld onPremisesExtensionAttributes und seine untergeordneten Erweiterungsattributfelder (z. B. extensionAttribute1 bis extensionAttribute15) nicht in der Auswahl Objektfelder in Schritt 3 angezeigt und können nicht als Bedingungsklausel-Filterbedingungen ausgewählt werden.
Mögliche Ursache: onPremisesExtensionAttributes ist ein komplexer Typ (verschachteltes) Objekt. Die Auswahl Objektfelder in Schritt 3 zeigt nur primitive Datentypen an; komplexe Typfelder 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 werden im Ausgabeschema der Aktivität in Schritt 4 angezeigt und zur Laufzeit aufgefüllt, wenn die Operation ausgeführt wird. Um auf Erweiterungsattributwerte zuzugreifen, ordnen Sie sie von onPremisesExtensionAttributes und seinen untergeordneten Feldern in der Transformation zu.

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

Symptom: Eine Microsoft Entra ID-Aktivität Aktualisieren schlägt fehl mit:

Ein Wert wurde gefunden, dessen Typname mit den Metadaten nicht kompatibel ist.
Der Wert gibt seinen Typ als „Edm.String" an, 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 von der 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-Aktivität Update.
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 erneut aus.

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

Symptom: Eine Microsoft Entra ID-Aktivität Query 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 ist 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 ansonsten korrekt ist. Der Connector fügt automatisch den erforderlichen Header ConsistencyLevel: eventual ein, aber $count=true muss separat hinzugefügt werden.
Lösung: Wählen Sie je nach verwendetem Tab in Schritt 3 eine der folgenden Optionen:
- Tab „Basic": Aktivieren Sie das Kontrollkästchen Include Count. Dies fügt $count=true automatisch zur Abfrage hinzu.
- Tab „Advanced": Fügen Sie &$count=true manuell an die Filterzeichenfolge an. Beispiel:
```
$filter=companyName eq 'Example Corp'&$count=true
```

Die Liste der Eigenschaften, die eine 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 Jitterbit Dynamics AX 2012 Connector REST Service-Protokoll 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 eingestellt. Die AX 2012-Authentifizierung erfordert, dass Domain Name die DNS-Domänennamenserweiterung ist (z. B. yourcompany.com), nicht ein kurzer oder NetBIOS-Domänenname. Ein falscher Domänenwert führt dazu, dass AX ansonsten gültige Anmeldedaten 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-Domänennamenserweiterung fest (z. B. yourcompany.com), nicht auf einen kurzen/NetBIOS-Domänennamen.
3. Bestätigen Sie, dass Login der Benutzername des AX-Dienstkontos mit den erforderlichen Berechtigungen ist, und geben Sie das Password erneut ein, um einen veralteten Wert auszuschließen.
4. Testen Sie die Verbindung und führen Sie den Vorgang erneut aus.

NetSuite: Fehler bei der Datencenter-URL

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 erscheinen nicht im Aktivitätsschema

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 erscheinen nicht oder werden in erweiterten Suchen nicht 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 Textfelder 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: Die Schaltfläche „Erweiterte Suche – Test Query" 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 der gespeicherten Suche fehlen in der Aktivitätsausgabe

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: Test Query-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 Ergebnisfeldern als Ausgabe erfordert Agent 11.49 oder später

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-Aktivität 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: Limit 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 Country" fehl

Symptom: Eine NetSuite Create-, Update- oder Upsert-Aktivität schlägt fehl, wenn der Quellwert für ein Länderfeld nicht mit einem NetSuite-Country-Enum-Wert übereinstimmt:
```
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) einer der vordefinierten Enum-Werte der WSDL entsprechen (z. B. _unitedStates). Ein Länderanzeigename, ein ISO-Ländercode oder ein beliebiger Wert, der nicht exakt dem WSDL-Enum entspricht, wird abgelehnt.
Lösung:
- Übersetzen Sie in der Transformation, die dem NetSuite-Ziel zugeordnet ist, den Quellländerwert vor dem Schreiben in den entsprechenden NetSuite-Enum-Wert. Ein Kreuzverweis-Wörterbuch, eine Case-Anweisung oder eine Nachschlagetabelle funktionieren alle.
- Erstellen Sie den Kreuzverweis aus dem Country-Enum, das in der NetSuite SuiteTalk WSDL definiert ist, die Ihr Connector verwendet. Die gültigen Werte unterscheiden sich zwischen WSDL-Versionen. Überprüfen Sie daher immer die WSDL-Version, die derzeit für die Verbindung konfiguriert ist.
- Wenden Sie denselben Ansatz auf alle anderen Felder an, die durch ein NetSuite-Enum gestützt werden (z. B. State, Currency), bei denen Quellwerte nicht bereits dem WSDL-Enum entsprechen.

OData v2-Entitätsmengen können nicht mit „Keine Entitätsmengen gefunden" 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 über die Verbindungseinstellung OData version zum OData-Connector hinzugefügt. Bei Agents vor Version 11.59 unterstützt der Connector nur OData V4, daher kann eine Verbindung zu einem OData V2-Service die Objektliste nicht auffüllen. Der gleiche Fehler tritt in 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 und testen Sie die Verbindung erneut.
3. Öffnen Sie die OData-Query-Aktivität erneut. Die Entitätsmengen sollten jetzt 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 Daten nur für das Standardunternehmen des Benutzers zurück, daher fehlen Datensätze aus anderen Unternehmen in den Ergebnissen.
Mögliche Ursache: Ein Dynamics 365 Finance and Operations-OData-Endpunkt gibt standardmäßig nur die Daten zurück, die zum Standardunternehmen des Benutzers gehören. Um der Verbindung einen unternehmensübergreifenden (erweiterten) Umfang zu geben, muss eine unternehmensübergreifende Filterklausel an die OData metadata URL der Verbindung (die $metadata-URL) angehängt werden. Auf der Metadaten-URL wird ?cross-company=true allein nicht den erweiterten Umfang angewendet.
Lösung: Hängen Sie in der OData-Verbindung eine dataAreaId-Filterklausel an die OData metadata URL an, ersetzen Sie usrt durch Ihre Datenbereichskennung und speichern Sie dann und testen Sie erneut:

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

Hintergrundinformationen zur Bereichsverwaltung von OData-Daten nach Unternehmen in Dynamics 365 finden Sie in der Microsoft-Dokumentation zum Thema unternehmensübergreifendes Verhalten.

Oracle EBS: Verbindungsfehler „Custom-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-Connector erfordert, dass der Oracle JDBC-Treiber (ojdbc8.jar) manuell auf dem Private Agent platziert wird. Diese Datei ist nicht im Agent enthalten 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 Private Agent-Host.
3. Starten Sie alle Agents in der Agent-Gruppe neu.
4. Testen Sie die Oracle EBS-Verbindung erneut.

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

Symptom: Eine Salesforce-Standardaktivität (wie Upsert) des Salesforce-Connectors schlägt fehl oder verarbeitet weniger Datensätze als erwartet, weil die Quelldaten das Datensatzlimit pro Aufruf überschreiten. Der Vorgang 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 in einem einzelnen Aufruf mehr Datensätze gesendet werden, lehnt Salesforce den Überschuss ab. Dies kann passieren, wenn Chunking nicht aktiviert ist, oder wenn Chunking aktiviert, aber nicht berücksichtigt wird, weil die Quelle ein Connector-SDK-basierter Connector wie HTTP v2 ist. Chunking wird bei SDK-basierten Quellen nicht unterstützt, sodass alle Datensätze unabhängig von der konfigurierten Chunk-Größe in einem einzigen Aufruf gesendet werden (siehe Chunking wird nicht berücksichtigt, wenn die Quelle ein SDK-basierter Connector ist).
Lösung:
- Aktivieren Sie Chunking für den Vorgang, und legen Sie die Chunk-Größe auf 200 oder weniger fest. 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 Payload ist, die von einer anderen Aktivität erzeugt wurde, überprüfen Sie, ob der Vorgang sie in Aufrufe von 200 Datensätzen oder weniger aufteilt. Wenn das Limit trotz korrekter Chunk-Größe weiterhin überschritten wird, kontaktieren Sie den Jitterbit-Support.
- Erhöhen Sie für Salesforce-Bulk-Aktivitäten die Standard-Chunk-Größe von 200 auf einen größeren Wert wie 10.000, da Bulk-Aktivitäten für hohe Datensatzvolumen 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 zum endgültigen Ziel kombiniert. Wenn das Ziel eine Salesforce-Aktivität ist, erzeugt jeder Quell-Chunk einen Ziel-Chunk, wobei die Transformation für jeden separat angewendet wird, und die resultierenden Ziel-Chunks werden anschließend kombiniert. Weitere Details finden Sie unter Detaillierte Chunking-Informationen.

Salesforce, Service Cloud und ServiceMax: Multi-Faktor-Authentifizierung verhindert Verbindungen mit Standardauthentifizierung

Symptom: Eine Verbindung, die Basic Auth mit dem Salesforce-, Salesforce Service Cloud- oder ServiceMax-Connector verwendet, schlägt beim Verbindungstest fehl oder verbindet sich, schlägt aber bei Vorgängen mit einem Authentifizierungsfehler fehl.
Ursache: Diese Connectors verwenden dieselbe Codebasis und authentifizieren sich bei einer Salesforce-Organisation. Die Basisauthentifizierung erfordert ein Salesforce-Konto, dessen zugewiesenes Berechtigungsset nicht die Berechtigung Multi-Factor Authentication for API Logins enthält. Wenn diese Berechtigung zugewiesen ist (MFA für das Konto aktiv), schlagen Verbindungen mit Basisauthentifizierung fehl.
Lösung:
- Überprüfen Sie in Salesforce das Berechtigungsset, das dem Systemintegrations-Login-Benutzer zugewiesen ist, und stellen Sie sicher, dass Multi-Factor Authentication for API Logins nicht ausgewählt ist. Systemintegrations-Login-Typen sind von der MFA-Anforderung von Salesforce ausgenommen. Details finden Sie in Salesforces Multi-Factor Authentication FAQ.
- Wenn MFA nicht vom Integrationsbenutzer entfernt werden kann, wechseln Sie die Verbindung zur 2-beinigen OAuth 2.0-Authentifizierung.

Hinweis

Die Verwendung von 2-beinigem OAuth 2.0 erfordert Agent-Version 11.59 oder höher. Bei 12.x-Agenten ist Version 12.3 oder höher für den Salesforce-Connector und Version 12.4 oder höher für die Salesforce Service Cloud- und ServiceMax-Connectors erforderlich.

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

Symptom: Eine Salesforce-Verbindung zu einer Sandbox oder einer Organisation mit aktivierten Enhanced Domains schlägt mit folgendem Fehler fehl:
```
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, ob das Kontrollkästchen Sandbox für Ihre Zielorganisation korrekt gesetzt ist.
- Wenn die Salesforce-URL in den SANs fehlt, generieren Sie das Zertifikat neu, um die spezifische Domäne einzuschließen.
- Wenn dieselbe Verbindung bei einer Cloud-Agent-Gruppe erfolgreich ist, aber bei einem privaten Agenten fehlschlägt, kann die Ursache stattdessen eine fehlende SNI-Erweiterung im TLS-Handshake des Agenten sein. Siehe Salesforce-Sandbox-Verbindung schlägt mit Zertifikat-Nichtübereinstimmung fehl.

Salesforce-Verbindung, -Konfiguration oder -Vorgang schlägt zeitweise mit `SERVER_UNAVAILABLE` fehl

Symptom: Ein Salesforce-Verbindungstest, eine Aktivitätskonfiguration oder ein Vorgangslauf schlägt zeitweise 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 einen spezifischeren Text von Salesforce weiterzugeben.
Lösung: Wiederholen Sie den Verbindungstest, den Konfigurationsschritt oder den Vorgang, und warten Sie bei anhaltenden Fehlschlägen zwischen den Versuchen jeweils länger. Wenn der Fehler anhält oder häufig auftritt, prüfen Sie Salesforce Trust auf einen gemeldeten Vorfall für Ihre Instanz, oder wenden Sie sich an 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, erscheint bei der Konfiguration einer Salesforce-Aktivität nicht im Transformationsschema.
Ursache: Das Datenschema wird zwischengespeichert, als die Aktivität zuletzt konfiguriert wurde, und wird nicht automatisch aktualisiert.
Lösung: Öffnen Sie die Aktivitätskonfiguration, und gehen Sie jeden Schritt durch. Nehmen Sie mindestens eine kleine Änderung vor (zum Beispiel ein Zeichen am Ende des Aktivitätsnamens hinzufügen und wieder entfernen), um ein erneutes Laden des Schemas zu erzwingen. Klicken Sie auf Fertig, um die aktualisierte Konfiguration zu speichern.

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

Symptom: Wenn eine Salesforce-Aktivität (wie Insert oder Upsert) als Ziel einer Transformation verwendet wird, ordnet Automap keine Felder zu.
Ursache: Das Schema der Salesforce-Aktivität enthält einen zusätzlichen Root-Knoten über den Objektfeldern, wenn das Schema gespiegelt wird. Dieser zusätzliche Root-Knoten verhindert, dass Automap die Quellfelder den richtigen Zielfeldern zuordnet.
Lösung:
1. Suchen Sie in der Transformationsansicht den obersten Objektknoten auf der Zielseite (zum Beispiel Account).
2. Ziehen Sie den entsprechenden Quellknoten manuell so, dass er damit übereinstimmt.
3. Führen Sie mit den ausgerichteten Knoten Automap erneut aus. Die Felder unter dem Knoten werden dann automatisch zugeordnet.

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

Symptom: Eine Salesforce-Abfrageaktivität, die eine übergeordnete/untergeordnete SOQL-Abfrage verwendet, erzeugt ein hierarchisches Antwortschema. Wenn dieses Schema auf der Zielseite einer Transformation gespiegelt wird, ist die Ausgabe hierarchisches XML statt einer flachen Struktur.
Ursache: Das hierarchische Schema spiegelt die übergeordnete/untergeordnete Beziehung in der Abfrage wider. Die Spiegelung des Quellschemas auf der Zielseite der Transformation bewahrt diese Hierarchie in der Ausgabe.
Lösung:
- Um eine flache Ausgabe zu erzeugen, definieren Sie auf der Zielseite der Transformation ein flaches Schema, statt das Quellschema zu spiegeln.
- Wenn Sie auf Abfrageergebnisse in einem Skript zugreifen, stehen die Daten bereits ohne zusätzliche Konfiguration als flache Struktur zur Verfügung.

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

Symptom: Ein Salesforce-Upsert- oder Bulk Upsert-Vorgang wird abgeschlossen, meldet jedoch Fehler für einige Datensätze.
Ursache: Mehrere Quelldatensätze verwenden denselben Wert für die externe ID. 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 Management Console-Seite Runtime (Tab 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 externen Salesforce 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 Datensatz-ID-Feld von Salesforce 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 zuordenbares 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, stellen Sie sicher, dass die Quelldaten diese ID liefern und dass die Update-Aktivität so konfiguriert ist, dass sie Datensätze anhand dieser ID abgleicht.

Salesforce-Massenwrite-Aktivitäten: Erster Datensatz ü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 es werden weniger Datensätze als erwartet in Salesforce geschrieben. Wenn die Quelle nur einen Datensatz enthält, werden überhaupt keine Datensätze geschrieben.
Ursache: Salesforce-Bulk-Schreibaktivitäten behandeln immer die erste Zeile der Quelldaten als Kopfzeile mit den Spaltennamen. Dieses Verhalten kann nicht geändert werden. Wenn die Quelldatei keine eigene Kopfzeile enthält, wird der erste Datensatz als Kopfzeile verwendet und nicht nach Salesforce geschrieben.
Lösung:
- Stellen Sie sicher, dass die Quelldaten als erste Zeile eine Kopfzeile enthalten. Die Werte in der Kopfzeile müssen mit den in der Feldzuordnung der Aktivität definierten Spaltennamen übereinstimmen.
- Überprüfen Sie, dass die Datenzeilen unmittelbar nach der Kopfzeile in der zweiten Zeile beginnen.

Salesforce-Massenaktivitäts-Operationsschritte werden als „Unvollständig" ohne Ein- oder Ausgabedaten angezeigt

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 Vorgangsschritt-Eintrag der Bulk-Aktivität den Status Incomplete an und enthält keine Eingabe- oder Ausgabedaten, selbst wenn der Vorgang erfolgreich abgeschlossen und Datensätze verarbeitet wurden.
Ursache: Salesforce-Bulk-Aktivitäten erzeugen keine Komponenteneingabe- und -ausgabedaten im Vorgangsprotokoll. Der Status Incomplete beim Aktivitätsschritt und das Fehlen von Eingabe- und Ausgabedaten sind für alle Bulk-Aktivitäten das erwartete Verhalten, unabhängig davon, ob die Verarbeitung erfolgreich war.
Lösung:
- Um festzustellen, ob Datensätze verarbeitet wurden und ob Fehler aufgetreten sind, überprüfen Sie die Texteinträge im Vorgangsprotokoll auf Fehlermeldungen oder Bestätigungen einer erfolgreichen Verarbeitung.
- Bei privaten Agenten können Sie zudem detaillierte Ergebnisse pro Datensatz herunterladen: Gehen Sie in der Management Console zur Seite Runtime, wählen Sie die Ausführung aus, öffnen Sie den Tab Activity Logs, und laden Sie die Ergebnisdatei herunter.

Salesforce-Massenaktivitäten schlagen fehl, wenn sie durch eine API- oder SOAP-Anfrage 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
```
Dieselbe Bulk-Aktivität wird ohne Probleme ausgeführt, wenn sie unabhängig oder auf andere Weise ausgelöst wird.
Mögliche Ursache: Vorgänge, die durch eine API- oder SOAP-Anfrage ausgelöst werden (wie einen Salesforce Outbound Message-Ablauf), unterstützen keine Salesforce-Bulk-Aktivitäten. In diesem Kontext steht dem Bulk-Ladesubsystem die Organisations-ID nicht zur Verfügung, was den Datenbank-Constraint-Fehler bei der Initialisierung verursacht.
Lösung: Ersetzen Sie die Bulk-Aktivität in Vorgängen, die Teil einer API- oder SOAP-ausgelösten Kette sind, durch die entsprechende Salesforce-Standardaktivität. Ersetzen Sie zum Beispiel eine Bulk Query durch eine standardmäßige Abfrage-Aktivität, oder ein Bulk Update durch eine standardmäßige Update-Aktivität. Standardaktivitäten funktionieren in diesem Kontext korrekt.

Salesforce Events: Events können nach Agent-Neustart nicht aktiviert werden

Symptom: Nach dem Neustart oder der Neuinstallation eines Private Agent schlagen Salesforce Events-Connector-Events fehl, auch wenn die Verbindungsanmeldedaten korrekt sind.
Mögliche Ursache: Nach einem Neustart ist die Connector JAR-Datei möglicherweise noch nicht auf dem Agent vorhanden. Das Aktivieren eines Events erfordert, dass der Connector zunächst auf den Agent heruntergeladen wird.
Lösung:
1. Öffnen Sie die Salesforce Events-Verbindungskonfiguration in Studio.
2. Klicken Sie auf Test, um die Verbindung zu testen. Dies erzwingt das Herunterladen der Connector JAR auf den Agent.
3. Nachdem der Verbindungstest erfolgreich ist, 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 Insert, Update und Delete CDC Event) sind zu erwarten und deuten nicht auf einen Connector-Fehler hin:

Events können nicht aktiviert werden, da die maximale Anzahl von Abonnenten erreicht ist. Die Salesforce-Instanz begrenzt die Anzahl der gleichzeitigen Clients (Abonnenten). Wenn diese Grenze 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 von der Salesforce API absichtlich 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 von der Salesforce API absichtlich als null zurückgegeben.

Mehrere SAP-Aktivitäten in einem Vorgang 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, erscheinen in Studio als 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 Studio-bekanntes Problem.
Lösung:
- Gestalten Sie 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.
- Wenn Daten aus mehreren Systemen in einem einzelnen Workflow erforderlich sind, teilen Sie die Logik auf separate Vorgänge auf und verketten Sie diese mithilfe von 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 verfügt nicht über 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-fähig konfiguriert.
- Die der Aktivität vorausgehende Anfragetransformation setzt das Commit-Steuerfeld nicht.
Lösung:
- Bestätigen Sie im SAP-System, dass das Funktionsmodul BAPI_TRANSACTION_COMMIT Remote-fähig ist.
- Setzen Sie in der Anfragetransformation, die der SAP-Aktivität RFC vorausgeht, das Feld BAPI_COMMIT auf true.
- Überprüfen Sie, dass das in der Verbindung referenzierte SAP-Benutzerkonto S_RFC-Berechtigung für BAPI_TRANSACTION_COMMIT und alle zugehörigen Funktionsgruppen hat.
- Wenn 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 für das SAP-Zielsystem nicht gültig: Der Code ist auf diesem System nicht installiert oder wird 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 Sprache auf einen unterstützten zweistelligen Sprachcode (z. B. EN für Englisch).
2. Überprüfen Sie, dass der Wert einem auf dem SAP-Zielsystem 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 von Studio aus, um zu bestätigen, dass die Initialisierung erfolgreich ist, bevor Sie den Vorgang erneut bereitstellen.

Erste Operationen laufen nach Agent-Neustart oder auf Cloud-Agenten langsam

Symptom: Operationen mit dem ServiceNow-Connector laufen in zwei Szenarien langsam:
- Auf privaten Agenten kann die erste Operation nach dem Agent-Neustart mehrere Minuten dauern; nachfolgende Ausführungen sind schnell.
- Auf Cloud-Agenten laufen die Operationen zeitweise 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 auf 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 aufbauen, was mehrere Minuten dauert.
Lösung:
- Auf einem privaten Agent können Sie die Langsamkeit nach dem Neustart verringern, indem Sie getcolumnsmetadata=onUse zu den Erweiterten Optionen des ServiceNow-Endpunkts hinzufügen. Diese Einstellung ist nur auf privaten Agenten wirksam.
- Für konsistente Leistung auf Cloud-Agenten 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 Verzögerung beim Neuaufbau.

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

Symptom: Nach dem Ändern 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 veröffentlicht vierteljährlich neue API-Versionen 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, was dazu führt, dass sich die konfigurierte Auswahl der Aktivität ändert, wenn die Konfiguration aktualisiert wird.
Lösung:
1. Öffnen Sie nach dem Ändern der Shopify-API-Version in der Verbindung jede betroffene Shopify-Aktivitätskonfiguration.
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 Unterobjektauswahlen, um sicherzustellen, dass sie Ihre Absicht unter der neuen Version widerspiegeln.
4. Aktualisieren Sie alle Auswahlen, die sich geändert haben, auf die korrekten Ersatzobjekte.
5. Stellen Sie die betroffenen Operationen erneut bereit und testen Sie sie erneut.
6. Informationen zu den Abschreibungszeitplänen der Shopify-API-Version finden Sie im Shopify-Änderungsprotokoll.

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

Symptom: Eine Snowflake-Aktivität 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, da 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 über andere Connectoren mit Heap-Fehlern fehlschlägt, ist die Ursache wahrscheinlicher die Gesamtheap-Zuordnung des Agenten als die Größe des Ergebnissatzes. Siehe Java-Heap-Speicher: 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 der Tomcat-JVM-Heap auf dem privaten Agent erschöpft.
Lösung: Verwenden Sie für große Abfragevolumina den Database-Connector mit einem Snowflake-JDBC-Treiber statt des Snowflake-Connectors. Der Database-Connector puffert den vollständigen Ergebnissatz nicht im Speicher, daher kann er viel größere Abfragevolumina verarbeiten. Installieren Sie den Snowflake-JDBC-Treiber auf dem privaten Agent und konfigurieren Sie dann eine Database-Verbindung, die ihn verwendet. Bei Agent 12.x und später benötigt diese Database-Verbindung auch enableArrowResultFormat=false&jdbc_query_result_format=json in ihrer Verbindungszeichenkette; siehe Snowflake: Operationen schlagen auf Agent 12.x fehl.

Wenn Sie beim Snowflake-Connector bleiben müssen, können beide folgenden Maßnahmen den Speicherdruck verringern, obwohl keine garantiert ausreichend für Datenmengen im Millionenbereich ist:
- Teilen Sie die Abfrage in Batches mit SQL-Klauseln LIMIT und OFFSET auf und führen Sie die Operation wiederholt mit inkrementellen 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: Operationen schlagen auf Agent 12.x fehl

Symptom: Auf einem privaten Agent mit Version 12.x schlagen Operationen, die Snowflake über einen Snowflake-JDBC-Treiber abfragen (eine Database-Verbindung oder ein DBExecute-Skript), zur Laufzeit fehl, obwohl der Verbindungstest erfolgreich ist. Der Fehler verweist auf die Arrow-Speicherschicht des Treibers, z. B.:

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 nicht mit Agent-Version 12.x und später kompatibel ist. Weitere Informationen finden Sie in Snowflakes Artikel zur Fehlerbehebung bei diesem Java-Modulfehler. Der Verbindungstest gibt kein Resultset zurück, daher wird er trotzdem bestanden, 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 statt im Arrow-Format zurückgibt:
- Database Connector: Fügen Sie enableArrowResultFormat=false&jdbc_query_result_format=json zur Snowflake-Verbindungszeichenfolge im Feld Zusätzliche Verbindungszeichenfolgen-Parameter hinzu (oder im Feld Verbindungszeichenfolge, wenn Verbindungszeichenfolge verwenden ausgewählt ist).
- Snowflake Connector: Fügen Sie unter Optionale Einstellungen > Benutzerdefinierte Verbindungseigenschaften 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 den Vorgang erneut aus.

Bei einem privaten Agent können Sie die Korrektur stattdessen auf JVM-Ebene anwenden, damit sie nicht pro Verbindung wiederholt werden muss, indem Sie --add-opens=java.base/java.nio=ALL-UNNAMED zu CATALINA_OPTS hinzufügen:
LinuxWindowsDocker
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
2. Öffnen Sie den Unterschlüssel Options.
3. Fügen Sie im Feld Wertdaten --add-opens=java.base/java.nio=ALL-UNNAMED zu den vorhandenen Java-Optionen hinzu.
4. Klicken Sie auf OK.
5. Starten Sie den Agent neu.
Verwenden Sie eine der folgenden Strategien, um die Einstellung anzuwenden:
1. Aktualisieren Sie die Dockerfile und erstellen Sie das Docker-Image neu:
  
  docker build -t my-agent .
2. Fügen Sie es in den Docker-Befehl run ein:
  
  docker run -e CATALINA_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED" my-agent
3. 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 Authentifizierungsabschaffung fehl

Symptom: Operationen, die sich mit Snowflake über den Authentifizierungstyp Kennwort (Veraltet) verbinden, schlagen fehl, nachdem sie zuvor funktioniert haben.
Mögliche Ursache: Snowflake stellt die Authentifizierung mit einem Faktor (nur Kennwort) ein. Kennwortbasierte Verbindungen schlagen fehl, es sei denn, die TYPE-Eigenschaft des Snowflake-Benutzerkontos ist auf LEGACY_SERVICE gesetzt.
Lösung: Wählen Sie eine der folgenden Optionen:
- Temporäre Problemumgehung: Setzen Sie in Snowflake die TYPE-Eigenschaft des Benutzerkontos auf LEGACY_SERVICE, um die kennwortbasierte Konnektivität wiederherzustellen:
```
ALTER USER <username> SET TYPE = LEGACY_SERVICE;
```
  Diese Problemumgehung ist keine langfristige Lösung, da Snowflake die Unterstützung für LEGACY_SERVICE in einer zukünftigen Version möglicherweise einstellt.
- Empfohlene Migration: Aktualisieren Sie die Snowflake-Connector-Verbindung in Studio, um OAuth oder Key-Pair-Authentifizierung zu verwenden, und konfigurieren Sie das Snowflake-Benutzerkonto entsprechend.

Snowflake: Developer-Instanz schläft, Metadatentabellen werden nicht gefüllt

Symptom: Beim Konfigurieren einer Snowflake-Aktivität wird die Liste der verfügbaren Objekte nicht gefüllt oder erscheint leer, obwohl der Verbindungstest erfolgreich ist.
Mögliche Ursache: Snowflake Developer Instances wechseln in einen Ruhezustand, wenn sie längere Zeit nicht aufgerufen wurden. Während der Verbindungstest gegen eine ruhende Instanz erfolgreich sein kann, gibt die Instanz möglicherweise keine Tabellen- und Objektmetadaten zurück.
Lösung:
1. Melden Sie sich in der Snowflake-Weboberfläche an, um die Instanz zu aktivieren.
2. Öffnen Sie die Snowflake-Verbindung in Studio erneut und klicken Sie auf Test, um die Anmeldedaten erneut zu testen.
3. Öffnen Sie die Aktivitätskonfiguration erneut, um die Liste der verfügbaren Objekte zu aktualisieren.

Snowflake Query: Schreibweise des Flat-Schema-Stammknotens stimmt nicht überein und verursacht `ProcessFlatStream`-Fehler

Symptom: Eine Snowflake-Query-Aktivität mit einem Flat-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 Flat-Schema aus der Abfrage generiert, wird der Stammknotenname in Großbuchstaben erstellt. Die Schreibweiteabweichung zwischen dem Schema-Stammknoten (Großbuchstaben) und dem XML-Antwort-Stammknoten (Kleinbuchstaben) führt dazu, dass die Flat-Stream-Verarbeitung fehlschlägt.
Lösung: Wählen Sie eine der folgenden Optionen:
- Ändern Sie im Flat-Schema den Namen des Stammknotens in Kleinbuchstaben, um die Connector-Ausgabe zu entsprechen. Benennen Sie beispielsweise SALES_ORDERS in sales_orders um.
- Verwenden Sie das Mirror-Schema mit Standardzuordnung anstelle eines manuell erstellten Flat-Schemas. Das Mirror-Schema leitet seine Struktur direkt aus der Connector-Antwort ab und weist diese Schreibweiteabweichung nicht auf.

Snowflake Merge: `stageName` und `fileContent` fehlen im Request-Schema 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. Dieselbe Aktivität, die für eine interne Stage konfiguriert ist, zeigt beide Felder.
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 werden die Felder, die diesen Upload steuern, aus dem Schema weggelassen.
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 Dateiinhalt aus dem Vorgang übertragen müssen, konfigurieren Sie die Merge-Aktivität für die Verwendung einer internen Stage. Das Schema zeigt dann stageName und fileContent.

Snowflake Insert oder Merge: SQL-Syntaxfehler durch Sonderzeichen

Symptom: Eine Snowflake-Insert- oder Merge-Aktivität 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 erscheinen, wobei Daten aus einem Feld in der falschen Spalte angezeigt werden.

Mögliche Ursachen:
- Feldwerte, die einfache Anführungszeichen enthalten (z. B. ein Wert wie corner's), werden nicht maskiert, bevor sie in die SQL-Nutzlast aufgenommen werden. Das nicht maskierte Anführungszeichen beendet die Zeichenkette vorzeitig, wodurch der Rest des Werts 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 führt dies zu einem Syntaxfehler beim Bindestrich.
Lösung:
- Für Werte, die einfache Anführungszeichen enthalten: Aktivieren Sie in den Optionalen Einstellungen der Snowflake-Verbindung die Option Sonderzeichen maskieren. Dies maskiert automatisch einfache Anführungszeichen in den Nutzlasten der Aktivitäten Insert und Invoke Stored Procedure. Verwenden Sie für Merge-Aktivitäten oder als Alternative für Insert die Funktion SQLEscape in der Transformationszuordnung, um einfache Anführungszeichen in betroffenen Feldwerten zu maskieren, 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: „No WSDL with 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 unterbrochen, sodass das Projekt auf eine WSDL-ID verweist, die nicht mehr vorhanden ist.
Das Projekt wurde vor der Harmony 12.9-Version bereitgestellt oder in eine andere Umgebung übertragen, als das Löschen eines Projekts noch WSDL-Dateien entfernen konnte, die noch verwendet wurden. Die 12.9-Version verhindert das Löschen, aber eine vorher gelöschte WSDL muss trotzdem erneut hochgeladen werden.
Lösung:
1. WSDL für die betroffene Komponente erneut hochladen:
  - Für eine SOAP-Verbindung die Verbindung öffnen und URL hochladen oder Datei hochladen wählen (nicht Vorhandene auswählen), die WSDL erneut hochladen, die Einstellungen Port und Methoden auswählen überprüfen und dann Änderungen speichern klicken.
  - Für eine API-Aktivität SOAP Request oder SOAP Response die Aktivität öffnen und die WSDL in Schritt 1 der Konfiguration erneut hochladen.
2. Alle Transformationen überprüfen, die Schemas von der erneut hochgeladenen WSDL erben, und diese bei Bedarf neu generieren.
3. Das Projekt erneut bereitstellen.
4. Falls das Projekt mehrere WSDLs hat und nicht klar ist, welche betroffen ist, siehe SOAP-Verbindung – Fehlerbehebung, um diese 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 erzeugt Schemaauflösungsfehler zur Entwurfszeit.
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. Die WSDL bearbeiten, sodass alle schemaLocation-Verweise relative Pfade verwenden (z. B. schema.xsd statt http://example.com/schema.xsd).
2. Alle referenzierten XSD-Dateien im selben Verzeichnis wie die WSDL platzieren und die WSDL in der SOAP-Verbindung erneut importieren.

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

Symptom: Die von einer SOAP-Aktivität erzeugte XML-Envelope stimmt nicht mit den literalen Namespace-Präfixen oder der Struktur der Quell-WSDL überein (z. B. ersetzt der Connector xmlns:ns1 durch xmlns:glob). Strikte SOAP-Services, die den genauen Präfixtext vergleichen, lehnen die Anfrage ab.
Mögliche Ursache: Die Transformations-Engine verarbeitet SOAP-Nachrichten als strukturiertes XML, nicht als literalen Text. Sie erzeugt eine semantisch äquivalente Payload, die möglicherweise andere Namespace-Präfixe als die Quell-WSDL verwendet.
Lösung: Für SOAP-Services, die eine literale XML-Struktur erfordern, den SOAP-Connector umgehen und die Request-Payload als String erstellen:
1. Eine HTTP v2-Verbindung erstellen, die auf die SOAP-Service-URL verweist.
2. In einer Transformation die SOAP-Envelope als String erstellen, String-Literale und zugeordnete Werte mit dem +-Operator verketten. Alternativ eine Vorlage aus einer Datei lesen und dynamische Werte mit Replace ersetzen.
3. In der HTTP v2-Aktivität POST das Standard-Request-Schema verwenden (kein benutzerdefiniertes Request-Schema hochladen) und die konstruierte SOAP-Envelope-String dem body-Feld dieses Schemas zuordnen. Der Connector sendet den body-Wert unverändert und bewahrt das literale XML.
4. Den Content-Type-Header auf text/xml oder application/soap+xml setzen und den SOAPAction-Header setzen, falls der Service dies erfordert.
5. Die Antwort des Service aus dem responseContent-Feld des Standard-Response-Schemas der Aktivität lesen.

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

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

Verbindungstest schlägt mit „Sie haben keine Berechtigung, auf diese Ressource zuzugreifen" 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: Dem VTEX-Benutzer oder dem Anwendungsschlüssel, der der Verbindung zugeordnet ist, fehlen eine oder mehrere Berechtigungen, die der Connector zur Validierung der Verbindung verwendet. Diese Berechtigungen sind strenger als die für den grundlegenden Datenzugriff erforderlichen.
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 spezifisch für diese WSDL-Versionen auftreten.
Lösung:
1. Ändern Sie in der Workday-Verbindungskonfiguration die WSDL-Version auf 41.x oder 43.0 oder höher 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 folgendem Fehler 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. Beachten Sie, dass Operationen zur Laufzeit erfolgreich ausgeführt werden können, auch wenn der Verbindungstest diesen Fehler zurückgibt, da der Test einen bestimmten Workday-Service (Get_Message_Template_Translation_Request) aufruft, der eine Berechtigung erfordert, die der ISU möglicherweise nicht hat, während die tatsächlichen Integrationsoperationen andere Services aufrufen.
Mögliche Ursachen:
- Der Integration System User (ISU) wurde nicht der Sicherheitsgruppe Setup Administrator in Workday zugewiesen. Der Testverbindungsaufruf des Connectors wird abgelehnt, wenn dem ISU diese Sicherheitsgruppenmitgliedschaft 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üfen Sie, dass der Wert Workday Host in der Verbindungskonfiguration korrekt ist. Der Host sollte die Basis-URL Ihres Workday-Mandanten sein (z. B. https://wd5-impl-services1.workday.com/). Sie können den korrekten Wert auf der Workday-Seite View API Client bestätigen.
2. Öffnen Sie in der Workday-Instanz die Aufgabe Assign Users to User-based Security Group, wählen Sie Setup Administrator aus, und bestätigen Sie, dass der ISU unter System Users aufgeführt ist. Falls nicht, fügen Sie den ISU hinzu. Vollständige Schritte finden Sie unter Voraussetzungen.
3. Bestätigen Sie, dass die Aufgabe Configure Web Service Security auch für den ISU abgeschlossen wurde, wie auf der Seite Voraussetzungen beschrieben.
4. Testen Sie die Verbindung erneut.

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

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

Agent offline oder nicht erreichbar

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 Agenten.
Lösung:
- Wenn die Jitterbit-Services nicht ausgeführt werden, starten Sie diese:
  - Windows: Siehe Windows-Agent starten.
  - Linux: Siehe Linux-Agent starten.
  Wenn der Service nicht startet, überprüfen Sie die folgenden 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.
- Wenn die Services ausgeführt werden, aber die Harmony-Cloud nicht erreichen können, überprüfen Sie Folgendes:
  - 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.
- Wenn der Agent sich über einen Unternehmens-Proxy verbindet, überprüfen Sie, ob der Proxy korrekt für den Agent konfiguriert ist, einschließlich der NTLM-Domäne, wenn der Proxy NTLM-Authentifizierung verwendet. Siehe Proxy-Server für private Jitterbit-Agenten. Das Ablehnungsprotokoll des Proxy-Servers ist hilfreich bei der Diagnose, was der Proxy blockiert.
- Wenn die Services des Agenten auf dem Host fehlerfrei sind (jitterbit status zeigt alle Services als ausgeführt an), aber der Agent wiederholt zu Unknown wechselt oder zwischen Running, Unknown und Stopped wechselt, wird die Verbindung oder der Prozess des Agenten wahrscheinlich zwischen den Heartbeats unterbrochen. Überprüfen Sie die folgenden möglichen Ursachen:
  - Ein Netzwerkgerät (Firewall, NAT-Gateway oder Cloud-VM-Idle-Timeout) kann die ausgehende Verbindung des Agenten zwischen den Heartbeats schließen. Versuchen Sie, das Heartbeat-Intervall des Agenten zu reduzieren (agent.heart.beat.interval). Für Cloud-gehostete Agenten siehe Azure VM: Verlorene Verbindungen und WebSocket/I/O-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.
  - Wenn die 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 Private 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 Agenten wurde möglicherweise auf Infrastrukturebene dupliziert (z. B. ein VM-Klon, Disk-Image, Machine-Template oder Snapshot, der nach der Installation und Registrierung des Agenten erstellt wurde). Der duplizierte Host trägt die gleichen Agent-credentials.txt, daher authentifizieren sich beide Hosts bei Harmony als derselbe Agent und laufen parallel, was zu Kollisionen führt. Zwei Agenten können nicht gleichzeitig unter den gleichen Anmeldedaten ausgeführt werden.
Lösung:
1. Bestätigen Sie, dass ein Duplikat ausgeführt wird. Stoppen Sie den Agent auf dem Host, den Sie behalten möchten, warten Sie 10 Minuten, und aktualisieren Sie dann die Registerkarte Private der Seite Agents der Management Console. Wenn der Agent von Stopped zurück zu Running wechselt, meldet sich ein anderer Host unter der gleichen Identität.
2. Identifizieren und fahren Sie den doppelten Host herunter.
3. Wenn der doppelte 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, den Sie behalten möchten.
4. Überprüfen Sie, dass der neue Agent auf der Registerkarte Private der Seite Agents der Management Console als Running aufgeführt ist.
5. Löschen Sie den alten Agent-Eintrag mit Actions > Remove.

Agent-Synchronisierungsfehler: Projektänderungen werden nicht angewendet

Symptom: Nach dem Bereitstellen 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.
- Ein Netzwerk-Timeout oder Autorisierungsfehler ist während der Synchronisierung aufgetreten.
- Unzureichender Speicherplatz auf dem Agent-Host hat verhindert, dass die synchronisierten Projektdateien geschrieben werden.
Lösung:
- Stelle das vollständige Projekt erneut bereit: Verwende in Studio Deploy, das alle Operationen des Projekts bereitstellt, anstatt ein Configurable Deploy nur ausgewählter Workflows oder Operationen.
- Starte die Agent-Services neu, um eine Neusynchronisierung aller bereitgestellten Projekte zu erzwingen.
- Überprüfe die Agent-Protokolle auf synchronisierungsbezogene Netzwerk-Timeouts oder Autorisierungsfehler.
- Überprüfe den verfügbaren Speicherplatz auf dem Agent-Host. Ein voller oder fast voller Speicher kann den Agent daran hindern, synchronisierte Projektdateien zu schreiben. Siehe Speicherplatz und Protokollakkumulation.

Fehler 1720 oder 1722 bei Windows-Installation

Symptom: Die Installation des privaten Windows-Agents bricht teilweise ab 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 enthaltene PostgreSQL-Datenbank sowie der Windows-Dienst jitterbitpostgres werden möglicherweise nicht vollständig erstellt. Die Meldung kann stattdessen eine andere Aktion nennen, z. B. InstallVerboseLogShipper.
Mögliche Ursachen:
- Ein fehlendes oder in Konflikt stehendes Microsoft Visual C++ Redistributable (das enthaltene PostgreSQL benötigt es).
- Unzulässige Zeichen im PostgreSQL-Passwort.
- Bei einer Neuinstallation verbleibende PostgreSQL-Komponenten von einem vorherigen Agent. 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 Agent. 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.
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 unzulässige 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 vollständig die verbleibenden PostgreSQL-Komponenten: Folgen Sie Deinstallieren eines privaten Windows-Agents, und bestätigen Sie dann, dass der Windows-Benutzer jitterbitpostgres, die PostgreSQL-Programm- und Datenverzeichnisse sowie die PostgreSQL-Registrierungsschlüssel gelöscht sind.
- Wenn die Fehlermeldung 1722 die Aktion InstallVerboseLogShipper nennt, entfernen Sie den verbleibenden Dienst des ausführlichen Log Shippers und seine Dateien vom vorherigen Agent, deinstallieren Sie den Agent dann erneut und installieren Sie ihn neu.

Wenn die Installation auch nach einer gründlichen Bereinigung fehlschlägt, wenden Sie sich an den Jitterbit-Support.

PostgreSQL-Dienst nach fehlgeschlagenem Upgrade unter Windows entfernt

Symptom: Nach einem fehlgeschlagenen Upgrade des privaten Agenten 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ückgesetzt 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 Service-Kontokennwörter zurück, bevor Sie das Upgrade erneut versuchen.

Agent-Dienste können nach dem Neustart von Windows nach einem Upgrade nicht gestartet werden

Symptom: Ein Upgrade eines Windows-basierten privaten Agenten von einem 11.x-Agenten auf einen 12.x-Agenten vor 12.10 wird erfolgreich abgeschlossen, aber die Jitterbit-Agent-Dienste können beim nächsten Neustart des Hostsystems nicht gestartet werden.
Mögliche Ursache: Das Upgrade belässt den vorherigen PostgreSQL-Windows-Dienst (postgresql-x64-<VERSION>, wobei <VERSION> die vom vorherigen Agenten installierte Version ist) mit dem Starttyp weiterhin auf Automatisch. Beim Neustart startet dieser ältere Dienst vor dem durch das Upgrade installierten PostgreSQL-Dienst und belegt denselben Port, wodurch der neue PostgreSQL-Dienst und damit der Agent nicht gestartet werden können.
Lösung:
- Führen Sie ein Upgrade auf Agent-Version 12.10 oder höher durch, wodurch der vorherige PostgreSQL-Dienst während des Upgrades entfernt wird.
- Öffnen Sie bei einer früheren Agent-Version nach dem Upgrade die Windows-Dienste, identifizieren Sie den älteren postgresql-x64-<VERSION>-Dienst (den, der vor dem Upgrade bestand), und setzen Sie dessen Starttyp auf Manuell oder Deaktiviert, oder deinstallieren Sie ihn, bevor Sie das Hostsystem neu starten. Um zu prüfen, welche Version derzeit mit dem Agenten gebündelt ist, führen Sie den Befehl unter Gleiche Version wie gebündelt aus.

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

Symptom: Die Installation eines 64-Bit-Windows-Privatagenten schlägt fehl, wenn die Zwei-Faktor-Authentifizierung (TFA) für die Organisation aktiviert ist.
Lösung: Deaktivieren Sie TFA vorübergehend, installieren Sie den Agent, und aktivieren Sie TFA dann erneut. 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 hat sudo-Privilegien. Ein Systemadministrator muss den Benutzer zur wheel-Gruppe hinzufügen. Um die aktuelle Gruppenmitgliedschaft zu überprüfen, führen Sie groups aus.
- Wenn Sie als jitterbit-Benutzer 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 unter RHEL 9.7 und später. Siehe RHEL 9.7 und später zeigen einen OpenSSL-Fehler bei der Installation des privaten Agenten ohne Root-Berechtigung in den bekannten Problemen des privaten Agenten 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. Die Fehlermeldung lautet beispielsweise 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: Installieren Sie den erforderlichen Treiber manuell: Registrieren Sie ihn in JdbcDrivers.conf und kopieren Sie die Treiber-.jar-Datei nach JITTERBIT_HOME/tomcat/drivers/lib/. Starten Sie dann den Agent neu. Die vollständigen Schritte finden Sie unter Install a JDBC driver.

Java-Heap-Speicher: `OutOfMemoryError`

Symptom: Operationen, die große Dateien verarbeiten oder viele Operationen gleichzeitig ausführen, schlagen mit folgendem Fehler fehl:
```
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-Speicher, 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 die Heap-Größe für die Workload richtig zu dimensionieren.

Festplattenspeicher und Protokollakkumulation

Symptom: Dem Host des privaten Agenten geht der Festplattenspeicher 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 Festplattenspeicher 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-Dateien 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 wiederholt auftritt (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 die Festplatte des Agenten verbrauchen, siehe JVM-Mini-Dump-Dateien füllen die Festplatte des Agenten.

`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 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-Agenten beeinträchtigt IP Helper die lokalen Datenbankverbindungen des Agenten.

PostgreSQL: Administratives schnelles 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 gestartet wird.
- Überprüfen Sie Agent-Host-CPU und Speicher. 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-Version 11.x und Version 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 seine ausstellende CA nicht im cacerts-Vertrauensspeicher 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-Vertrauensspeicher der Agent-JRE. Verwenden Sie keytool -import im cacerts-Vertrauensspeicher 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 Vertrauensspeicher lösen, sowohl auf Cloud- als auch auf privaten Agents. Siehe SQL Server: Verbindung schlägt mit PKIX-Zertifikatpfadfehler 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-Vertrauensspeicher 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 nicht mit der Netzwerk- oder Firewall-Konfiguration 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-Helper-Service 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 Starttyp auf Deaktiviert:

attachment

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

Symptom: Private Agenten, die auf Azure-VMs installiert sind, erleben Verbindungsabbrüche oder WebSocket/I/O-Fehler.
Lösung: Reduzieren Sie das Heartbeat-Intervall des Agenten 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 Fehlerbehebungsleitfaden für Agenten.

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-Log enthält:
```
ThreadPoolAsynchronousRunner: APPARENT DEADLOCK
```
Das Log kann auch An existing connection was forcibly closed by the remote host für die PostgreSQL-Datenbank des Agents anzeigen. Ein Neustart des Agenten 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 Agenten (im Log als c3p0 angezeigt) kann sich nach einem kurzzeitigen Datenbankverbindungsverlust nicht wiederherstellen, beispielsweise während einer vorübergehenden Netzwerkunterbrechung, obwohl PostgreSQL selbst mit Standard-Timeouts gesund und reaktionsfähig bleibt.
- Veraltete Jitterbit-Prozesse halten Threads und Datenbankverbindungen. Dies kann auftreten, wenn ein Agent aktualisiert wird, während Operationen noch 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 burstfähige Cloud-Instanz (wie ein AWS t3-Typ) ihre CPU, sobald ihre Burst-Guthaben 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 das Deadlock zu beheben.
- Falls das Deadlock im Java-Verbindungspool (c3p0) liegt 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 Version 12.5 und später 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 dauerhafter (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.

Der 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 Protokoll des Cleanup-Diensts 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) sperrt Dateien im Protokollverzeichnis des Agents.
Lösung:
- CleanupRules.xml bearbeiten, um die Aufbewahrung (FileAge) für die betroffenen Protokollverzeichnisse zu verkürzen, damit Dateien schnell 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 auch mit gültigen Cleanup-Regeln weiter wachsen, 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 von Harmony abgemeldet, aber die nun ungültige credentials.txt-Datei 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 abgemeldet 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 credentials.txt-Datei, 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 Agenten

Symptom: Nach dem Umschalten der 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 Agenten geändert haben, starten Sie alle privaten Agenten in der Gruppe neu, damit die Änderung wirksam wird.

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

Symptom: Der Versuch, einen zweiten privaten Agenten zu einer vorhandenen Gruppe hinzuzufügen, schlägt fehl, oder die Gruppe zeigt nach dem Hinzufügen eine Warnung an.
Mögliche Ursache: Eine Standard-Agent-Gruppe erlaubt maximal einen Agenten. Das Ausführen von mehr als einem Agenten 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 Agenten 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 Agent-Grenze fehl

Symptom: In der Schublade Agent-Gruppendetails einer Agent-Gruppe ist das Symbol Erstellen verfügbar, aber das Speichern des neuen privaten Agenten schlägt mit einem Fehler zur maximalen Agent-Grenze 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 Agents 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 High Availability Agent-Gruppenklasse. Eine Standard-Gruppe erlaubt nur einen Agent, wie unter Adding a second agent to a Standard agent group is not permitted beschrieben.
- Das Limit für private Agents der Organisation ist erreicht. Alle privaten Agents, die der Abonnementplan Ihrer 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 Agent-Anzahl der Gruppe mit ihrem Maximum auf der Seite Agents und die hinzugefügten privaten Agents Ihrer Organisation mit der lizenzierten Gesamtzahl auf der Seite Dashboard der Management Console.
- 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 Agent 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. Agents im Status Running oder Stopping können nicht gelöscht werden.
Lösung:
1. Überprüfen Sie auf der Seite Agents den aktuellen Status des Agents.
2. Stoppen Sie den Agent und warten Sie, bis sich sein Status ändert, bevor Sie den Löschvorgang erneut versuchen.

Private Agent-Gruppe kann nicht gelöscht werden

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

Automatisches Connector-Update deaktivieren wird durch Agent-Aktionen umgangen

Symptom: Connectors werden auf privaten Agents aktualisiert, obwohl Disable Auto Connector Update in den Organisationsrichtlinien aktiviert ist.
Ursache: Die Organisationsrichtlinie Disable Auto Connector Update verhindert, dass private Agents 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 hält Connectors nicht in jeder Situation auf einer festen Version. Connectors werden weiterhin heruntergeladen oder aktualisiert, unabhängig von der Richtlinie, wenn eines der folgenden Ereignisse eintritt:
- Action > Update connectors wird für die Agent-Gruppe auf der Seite Agents der Management Console ausgewählt. Diese Aktion setzt die Richtlinie explizit außer Kraft.
- 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. ein Upgrade von einem 11.x-Agent auf einen 12.x-Agent). Der Agent hat dann keinen gespeicherten Datensatz über zuvor installierte 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 von privaten Agents auf ein anderes Betriebssystem (z. B. Windows zu Linux) bei Wiederverwendung derselben Agent-Gruppe zeigen die migrierten Agents auf der Registerkarte Private der Seite Agents der Management Console intermittierend als Unknown oder Stopped an, obwohl jitterbit status zeigt, dass die Services laufen und Operationen normal ausgeführt werden.
Mögliche Ursache: Die Wiederverwendung einer Agent-Gruppe aus dem vorherigen Betriebssystem kann Metadaten hinterlassen, die die Statusmeldung für die neuen Agents beeinträchtigen. Der Effekt ist typischerweise kosmetisch: Services und Operationen laufen weiterhin normal.
Lösung: Erstelle stattdessen eine neue, saubere Agent-Gruppe für die migrierten Agents, anstatt die Gruppe aus dem vorherigen Betriebssystem wiederzuverwenden, und registriere 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 erscheint ein kurzer 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, durchsuche jitterbit-agent.log nach environment-deploy. Jeder Protokolleintrag 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. Um die Synchronisierungszeiten zu verkürzen, siehe Leistungsoptimierung der Umgebungssynchronisierung.
3. Wenn die Synchronisierungsdauern konsistent übermäßig lang sind (mehr als ein paar Minuten), kontaktiere den Jitterbit-Support.

Agent zeigt sich als nicht fähig an

Symptom: Operationen, die an die Agent-Gruppe übermittelt werden, 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 in der Process Engine des Agenten sind bereits in Gebrauch, 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 Capability-Metrik ist aktiviert und hat ihren Schwellenwert erreicht. CPU-Auslastung, Speicherauslastung und Apache-Thread-Auslastung können jeweils zum Capability-Status 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-Agenten erfasst, daher trägt sie nicht zum Capability-Status 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 Agenten in der Gruppe untätig sind oder unterausgelastet sind.
Lösung: Überprüfen Sie ProcessEngine.log auf lange Sequenzen von Capability-Status-Änderungen, um zu bestätigen, dass der Agent zwischen fähigen und unfähigen Zuständen wechselt. 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 den Wert daher konservativ fest.
- Bestimmen Sie, welche Capability-Metriken im Abschnitt [AgentCapability] aktiviert sind. Wenn keine aktiviert sind, sind CPU- und Speicherlast nicht der Grund für die Änderung des Capability-Status des Agenten, 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 eine den Schwellenwert überschreitet, wird der Agent unfähig, unabhängig von der Thread-Verfügbarkeit. 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 Metrics 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 Agenten enthält, überprüfen Sie ProcessEngine.log auf allen Agenten in der Gruppe, um festzustellen, ob alle Agenten gleichzeitig unfähig waren, als die Operation fehlgeschlagen ist. Wenn nur ein Agent unfähig war, sollte die Operation an einen fähigen Agent weitergeleitet werden. Überprüfen Sie, ob der Load Balancing für die Gruppe korrekt konfiguriert ist.
- Wenn Ressourcenlimits konsistent erreicht werden, fügen Sie Agenten zur Gruppe hinzu, um die Last zu verteilen.
- Wenn Speicherdruck der Auslöser ist, siehe Java heap space: OutOfMemoryError.

Transformation schlägt fehl: „Datei im lokalen Dateispeicher nicht gefunden"

Symptom: Eine Operation schlägt während einer Transformation mit einem Fehler fehl, der anzeigt, 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 aus der Harmony Cloud mit dem Agent synchronisiert, daher kann der Agent die Datei zur Laufzeit nicht finden. 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 Agent höchstens einmal auf, und der Agent stellt die fehlenden Metadaten bei der nächsten Umgebungssynchronisierung wieder her (nächste Vorgangsausführung 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 Agent weiterhin fehlschlägt, liegt wahrscheinlich ein tieferes Problem vor, z. B. eine Umgebung, die ihr Bereitstellungsdatensatz-Limit erreicht hat, oder eine versionsspezifische Regression. Kontaktieren Sie den Jitterbit-Support mit dem Namen des fehlgeschlagenen Vorgangs sowie TransformID und File_ID aus der Fehlermeldung.

Fehlgeschlagene Windows-Installation wiederherstellen

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

Connector nicht auf Agent heruntergeladen

Symptom: Operationen schlagen mit Fehlern fehl, die darauf hindeuten, dass ein Connector nicht verfügbar oder auf dem Agent nicht vorhanden ist. Dies tritt typischerweise nach der Veröffentlichung einer neuen Connector-Version oder nach der Bereitstellung eines Projekts auf, das einen auf dem Connector SDK basierenden Connector verwendet:
```
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 der Management Console, wählen Sie die Agent-Gruppe aus und wählen Sie Action > Update connectors. Dies erzwingt ein Connector-Update über die Gruppe hinweg 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 or unreachable.

Hinweis

Die Microsoft Excel- und Excel v2-Connectoren können mit diesem Fehler speziell auf der privaten Agent-Version 12.x nicht geladen werden. Dies ist ein bekanntes Problem mit einer separaten Problemumgehung. Siehe Excel and Excel v2 connectors fail to load in den bekannten Problemen für private Agents.

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

Symptom: Die 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 die Proxy-Authentifizierung, einschließlich einer NTLM-Domäne. Siehe Proxy server for Jitterbit private 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 die Proxy-Anmeldedaten an (und die NTLM-Domäne, falls der Proxy diese erfordert). Siehe Configure a proxy during agent setup.
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 information dokumentiert.
3. Führen Sie das Installationsprogramm erneut aus, sobald der Proxy konfiguriert ist oder der Host die Harmony-Cloud erreichen kann.

Agent-Dienst-Neustartschleife

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 wechselt, handelt es sich um ein Konnektivitätsproblem und nicht um eine Absturzschleife. Siehe Agent offline oder nicht erreichbar.
Mögliche Ursachen:
- Ein verwaister Jitterbit-Prozess aus einem vorherigen Durchlauf (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.
- Dem Host geht der 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 Festplattenspeicher, oder die interne PostgreSQL-Datenbank ist groß genug geworden, um beim Start fehlzuschlagen.
- Die Process Engine stürzt unter anhaltender Last wiederholt ab.

Operationen zeitüberschritten 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 durch 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 Vorgangslaufzeit 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 genügend 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 space: 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 erforderlich ist, entfernen Sie # und stellen Sie erneut bereit. Das Entfernen von # ordnet nur das erste Element zu, daher wenden Sie dies nur an, wenn das Iterieren ü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 betrifft Windows-Private-Agenten in Versionen vor 11.49.
Mögliche Ursachen:
- Der AgentStats-Festplattenstatistik-Collector des Agenten stürzt die JVM ab, während er Festplattenmetriken erfasst. Dies betrifft Agenten in Versionen vor 11.49.
- 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, wodurch beide Ursachen behoben werden.

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ündeltes 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 schließt den Wechsel nicht ab. PgBouncer muss auch mit dem SCRAM-Verifier-Hash neu konfiguriert werden, sonst kann der Agent nicht gestartet werden.
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. Der Wechsel ist daher 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 gemeinsam nutzen.
Ursache: Der TLS-Handshake enthält nicht die SNI-Erweiterung, daher gibt der Server ein Standardzertifikat statt des für den angeforderten Host zurück. 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 die erste das richtige Zertifikat zurückgibt und die zweite das nicht übereinstimmende zurückgibt, 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.
Wenn 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 möglicherweise den Host nicht in seinen Subject Alternative Names auf. Fügen Sie für Salesforce die Sandbox-MyDomain-URL zum Salesforce-Zertifikat hinzu, oder siehe Zertifikat: Nichtübereinstimmung des Subject Alternative Name (SAN).

SSH: SFTP-Verbindung schlägt aufgrund eines falschen Schlüsseldateipfads 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`-Abschnitt

Symptom: SFTP-Operationen, die einen privaten Schlüssel zur Authentifizierung verwenden, schlagen mit einem Fehler für eine leere private Schlüsseldatei fehl, nachdem ein Agent-Upgrade oder -Neustart durchgeführt wurde. 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 aktiviert), 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 werden (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." when using SSH keys.

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 selben Agent (mit demselben 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, Schlüsselaustausch- oder Host-Schlüssel-Algorithmen, die die cURL-Bibliothek in älteren Agent-Versionen nicht unterstützt. Server, die die älteren Algorithmen noch akzeptieren, funktionieren weiterhin, weshalb derselbe 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, Schlüsselaustausch- und Host-Schlüssel-Algorithmen enthält.

HTTPS-Proxy: Standardauthentifizierung durch 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 standardmäßig die Basis-Authentifizierung während des HTTPS-Proxy-Tunneling. 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 Allow basic authentication during HTTPS proxy tunneling.

Private Agents in eingeschränkten Netzwerken: Nur ausgehende Konnektivität

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 das Gateway erreichen können (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. Verwenden Sie den 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 durchfü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 die 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.
- Der Metrik-Service ist so konfiguriert, dass er sich mit der gebündelten PgBouncer-Instanz des Private Agent auf einem anderen Port verbindet als PgBouncer tatsächlich verwendet, sodass der Metrik-Service keine Verbindung herstellen kann und Metriken nur teilweise erfasst werden. Diese Port-Nichtübereinstimmung kann nach bestimmten Agent-Installationen oder -Upgrades auftreten.
- Vor Agent-Version 12.9 wurde bei der Installation 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 geben 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.
- Wenn Metriken nur teilweise erfasst werden und die obigen Schritte das Problem nicht beheben, wenden Sie sich an den Jitterbit-Support, um zu überprüfen, dass der Verbindungsport des Metrik-Service für PgBouncer mit dem konfigurierten Port von PgBouncer übereinstimmt.
- Verwenden Sie für einen neuen Nicht-Root-Linux-Private-Agent 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 der Agent sich ü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 die 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 immer noch 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

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-Dienste nicht. Das Ausführen von sudo jitterbit status zeigt, dass der Scheduler und andere Dienste nicht laufen, und die Agent-Protokolle (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 Verzeichnis der gebündelten PostgreSQL-Daten sind zu permissiv. PostgreSQL erfordert, dass das Datenverzeichnis 700 (nur Eigentümer) ist. Falls 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, dass /opt/jitterbit und seine Unterverzeichnisse dem Benutzer und der Gruppe jitterbit gehören:
```
sudo chown -R jitterbit:jitterbit /opt/jitterbit
```

Setzen Sie das PostgreSQL-Datenverzeichnis auf 700:

```sh
sudo chmod 700 /opt/jitterbit/DataInterchange/pgsql/data
```

Starten Sie die Agent-Services:
```
sudo /etc/init.d/jitterbit start
```

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

Symptom: Nach der Migration eines privaten Linux-Agenten auf einen neuen Host (oder nach einer Neuinstallation) können die Agent-Services nicht gestartet werden. Das postgresql.log zeigt:
```
[FATAL] password authentication failed for user "jitterbit"
```
Das Agent-Protokoll zeigt, dass es keine Verbindung zur Datenbank herstellen kann. Der Fehler bleibt auch nach vollständiger Deinstallation und Neuinstallation 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 kennzeichnen `log4j-over-slf4j.jar` als Log4j-1.x-Sicherheitslücke

Symptom: Ein Sicherheitsscan einer privaten Agent-Installation kennzeichnet Dateien wie log4j-over-slf4j-1.7.21.jar als veraltete 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 Agenten umleitet. Die Datei enthält nicht den anfälligen Log4j-1.x-Code. Ihre Anwesenheit ist die Risikominderung des Agenten 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-Dienst 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 Agents in der Agent-Gruppe werden ausgeführt und sind dem Cluster beigetreten. Bei einer Gruppe von $N$ Agents, unabhängig davon, ob jeder Agent ausgeführt wird, müssen $(N / 2) + 1$ Agents (abgerundet) ausgeführt werden und Teil des Clusters sein.
- Ein oder mehrere Agents haben ihre Verbindung zum Cluster verloren und konnten nicht erneut beitreten, wodurch die Anzahl der laufenden, beigetretenen Agents 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 Agents zwei Cluster mit je 2 Agents 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 Agents in der Gruppe ausgeführt werden und Teil des Clusters sind, wobei $N$ die Anzahl der in der Agent-Gruppe registrierten Agents ist, unabhängig davon, ob jeder ausgeführt wird. Beispielsweise erfordert eine Gruppe von 4 Agents 3, und eine Gruppe von 5 Agents erfordert ebenfalls 3. Um zu sehen, welche Agents beigetreten sind, verwenden Sie die Listening-Dienst-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 Persistenz unverarbeitet bleiben, stellen Sie den Cluster manuell wieder her. Siehe Cluster-Wiederherstellung nach Agent-Fehler.
Hinweis

Eine ungerade Anzahl von Agents 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.

Listening-Service-Nachrichten nicht zugestellt

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

Custom-API-Operationsprotokolle werden nicht angezeigt

Symptom: Eine Operation, die durch eine benutzerdefinierte API ausgelöst wird, wird ohne Fehler ausgeführt, aber es wird kein Protokolleintrag in Studio oder auf der Seite Laufzeit der Management Console angezeigt.
Ursache: Wenn eine benutzerdefinierte API eine Operation auslöst, werden Operationsprotokolle nur generiert, wenn die Operation erfolglos ist. Erfolgreiche benutzerdefinierte API-Operationen erzeugen standardmäßig keinen Protokolleintrag.
Lösung: Um Protokolle für erfolgreiche benutzerdefinierte API-Operationen zu erfassen, aktivieren Sie Operationsdebug-Protokollierung für die Operation. Beachten Sie, dass API Manager eine eigene separate Protokollierungsansicht für API-Anfragen hat.

Operationsdebug-Protokollierung endet vor dem ausgewählten Enddatum

Symptom: Operation debug logging wurde mit einem zukünftigen Enddatum aktiviert, aber die Protokollgenerierung stoppt vor diesem Datum.
Cause: Bei Cloud-Agent-Gruppen ist das Enddatum der Operation-Debug-Logging-Einstellung unzuverlässig. Die Protokollgenerierung kann vor dem konfigurierten Zeitraum enden.
Resolution: Aktivieren Sie Operation debug logging nach Bedarf erneut.

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

Symptom: Auf einem privaten Agent hat eine Operation operation debug logging aktiviert, wobei Komponenteneingabe- und Ausgabedaten aktiviert sind. 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.
Possible causes:
- Der cleanup service des Agenten löscht .input- und .output-Dateien, bevor diese überprüft werden können.
- Der Agent wurde neu gestartet, während die Operation noch ausgeführt wurde, sodass die Dateien nie vollständig geschrieben wurden. Siehe Component input/output data not generated für dieses Szenario.
Resolution:
1. Öffnen Sie auf dem Agent-Host CleanupRules.xml im Agent-Installationsverzeichnis.
2. Suchen Sie die Cleanup-Regel für das Verzeichnis DataInterchange/Temp/Debug und erhöhen Sie 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. Starten Sie die Agent-Services neu.

Komponenteneingabe-/Ausgabedaten 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.
Resolution: Überprüfen Sie das Verbose Log Shipper-Service-Protokoll auf dem Agent:
```
<JITTERBIT_HOME>/VerboseLogShipper/verbose-log-shipper.out.log
```
Wenn das Protokoll Fehler anzeigt, starten Sie 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 wird der Verbose Log Shipper-Service auch durch einen Neustart aller Jitterbit-Agent-Services neu gestartet.

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

Symptom: Nachrichten in einer Quorum-Nachrichtenwarteschlange verschwinden ohne Fehler, obwohl sie wiederholt über die NACK-Aktivität erneut in die Warteschlange eingereiht werden.
Mögliche Ursache: Quorum-Warteschlangen erzwingen ein Zustellungslimit von 20 Versuchen pro Nachricht. Nachdem eine Nachricht 20-mal negativ bestätigt wurde, ohne dass eine erfolgreiche Bestätigung erfolgt, wird sie dauerhaft aus der Warteschlange entfernt, ohne einen Fehler zu generieren.
Lösung:
- Konfigurieren Sie eine Dead Letter Queue, um Nachrichten zu erfassen, die das Zustellungslimit überschreiten, und um einen stillen Datenverlust zu verhindern.
- Wenn wiederholte Verarbeitung über 20 Versuche hinaus erforderlich ist, verwenden Sie beim Erstellen der Warteschlange auf der Seite Message Queues einen Classic-Warteschlangen-Typ statt Quorum.

Jitterbit MQ: Umgebung nicht für Messaging aktiviert

Symptom: Operationen, die den Jitterbit MQ-Connector verwenden, können keine Verbindung herstellen oder Nachrichten senden, obwohl die Warteschlange in der Management Console vorhanden ist.
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 Message Queues und klicken Sie auf das Einstellungssymbol .
2. Aktivieren Sie im Abschnitt Environments Permission das Messaging für die betroffene Umgebung und klicken Sie dann auf Save.

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

Symptom: Operationen, die den Jitterbit MQ-Connector verwenden, schlagen mit folgendem Fehler fehl:
```
"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 Message Queues der Management Console die betroffene Warteschlange öffnen, Advanced Options erweitern und den Wert Message Limit erhöhen.

Jitterbit MQ: NACK-Nachrichten blockieren Warteschlangen-Fortschritt bei erneuter Einreihung

Symptom: Wenn eine NACK-Aktivität mit ausgewählter Option Requeue Messages After NACK verwendet wird, kehren Nachrichten an den Anfang der Warteschlange zurück, anstatt am Ende eingefügt zu werden. Wenn Nachrichten wiederholt fehlschlagen und erneut eingefügt 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 eingefügte Nachricht am Anfang der Warteschlange für sofortige Zustellung. Dieses Verhalten kann nicht über den Connector geändert werden.
Lösung: Um zu verhindern, dass fehlgeschlagene Nachrichten den Warteschlangen-Fortschritt blockieren, verwenden Sie einen der folgenden Ansätze:
- Dead Letter Queue: Konfigurieren Sie die NACK-Aktivität so, dass Reject Messages After NACK verwendet wird, und richten Sie eine Dead Letter Queue ein, um abgelehnte Nachrichten zu erfassen. Verarbeiten Sie die Dead Letter Queue separat, mit einer Verzögerung bei Bedarf, um die fehlgeschlagenen Nachrichten erneut zu versuchen, ohne die Hauptwarteschlange zu blockieren.
- Manuelle Wiederveröffentlichung: Konfigurieren Sie die NACK-Aktivität so, dass Reject Messages After NACK verwendet wird, 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-Allowlist für Ihren Netzwerk-Proxy oder Web-Filter enthält nicht die erforderlichen Jitterbit-Adressen. Siehe Allowlist-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 standardmäßiges macOS-Verhalten und kein tatsächliches Problem mit dem Installer.
Lösung:
1. Bestätigen Sie, dass Design Studio von der offiziellen Seite Downloads des Harmony-Portals heruntergeladen wurde.
2. Falls die Malware-Warnung für eine vom Portal heruntergeladene Installation angezeigt wird, kann die Warnung ignoriert werden: Sie weist nicht auf ein tatsächliches Sicherheitsrisiko mit dem Jitterbit-Installer hin.

Design Studio: Unscharfe oder kleine Benutzeroberfläche auf Windows 10-Displays mit hoher Pixeldichte

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-Fehler bei der Skalierung hochauflösender Displays.

Design Studio: Lange Projektladezeit 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 kann unter macOS nicht gestartet werden, und es wird eine Fehlermeldung angezeigt, die besagt, dass Client-Eigenschaften nicht vorhanden sind.
Mögliche Ursache: Design Studio wurde direkt vom Disk-Image (.dmg) aus gestartet, anstatt vom Ordner Applications. Die Anwendung muss in den Ordner Applications kopiert werden, bevor 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 des Ordners Applications im Installerfenster.
4. Starten Sie Design Studio vom Ordner Applications (oder von Spotlight/Launchpad) aus, 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:

Can not find target node (/PRESCRIPT/).
The structure may have changed so try to open the transformation 'example' and refresh the structure trees.

Mögliche Ursache: Die interne XML-Struktur der Transformation ist inkonsistent mit dem aktuellen Zielschema geworden, normalerweise nach einer Schemaänderung.
Lösung:
1. Öffnen Sie die fehlerhafte Transformation in Design Studio.
2. Klicken Sie auf der Seite Target auf die Schaltfläche „Aktualisieren" oben im Strukturbaum. Dies liest das Schema erneut 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 (anstatt lokal oder im Harmony-Cloud-Speicher) gespeichert ist, zeigt Datenverlust, bei dem 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-Projekt-Arbeitsbereiche 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 Projekt-Arbeitsbereich 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 zu Design Studio schlägt mit einem Fehler fehl, der angibt, dass ein ungültiges XML-Zeichen im Elementinhalt gefunden wurde, zum Beispiel:

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 Projekt-Metadaten enthalten ein Steuerzeichen (wie 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, kontaktieren Sie den Jitterbit-Support mit der vollständigen Fehlermeldung und Projekt-ID für mögliche Metadaten-Reparatur im Backend.

Design Studio: Projektkomponenten fehlen nach Download oder Import

Symptom: Das Öffnen oder Importieren eines Projekts zeigt Operationen in der Liste, aber es werden keine Komponenten (Transformationen, Skripte, Schemas) angezeigt, oder eine Projekt-Export-Datei .json kann nicht importiert werden. Die Ursache ist normalerweise eine einzelne beschädigte Komponente im Projekt-Export, die das Parsen der gesamten Datei unterbricht.
Mögliche Ursache: Eine Komponente im Projekt-Export hat fehlerhaftes JSON, wie 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 Text-Editor und überprüfen Sie das Array components auf Einträge, die leer, fehlerhaft oder mit ungewöhnlichen Zeichen versehen sind.
3. Entfernen Sie das vollständige JSON-Objekt der verdächtigen Komponente aus dem Array components.
4. Speichern Sie die Datei und importieren Sie sie zurück in Harmony.
5. Wenn die Beschädigung nicht identifizierbar ist, senden Sie den Projekt-Export an den Jitterbit-Support zur Analyse.

Design Studio: Doppelte Operationen oder Transformationen erscheinen in einem heruntergeladenen Projekt

Symptom: Einige Benutzer, die dasselbe Projekt herunterladen, sehen doppelte Operationen oder Transformationen mit identischen Namen und Schemas, und diese Duplikate sind 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 doppelte Kopien von Abhängigkeiten (wie Transformationen) in das ursprüngliche Projekt eingefügt.
Lösung:
1. Erstellen Sie eine Sicherung des Projekts, bevor Sie Änderungen vornehmen.
2. Identifizieren Sie die doppelten Operationen oder Transformationen. Löschen Sie die Duplikate, während Sie die Originale beibehalten.
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 Verwendung von Operationsmigration in ein Projekt, das bereits die Quellkomponenten enthält. Verwenden Sie stattdessen Projektmigration 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-Endpoint schlägt mit einer Fehlermeldung wie der 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 versehen ein Projekt mit einem Salesforce-Endpoint mit einer falschen erforderlichen Version (12.7.0.0) statt 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. Für Design Studio 11.63.0.0 verwenden Sie required_version=110630000000000. Für jede andere Version exportieren Sie ein neues, leeres Projekt aus Ihrer installierten Design Studio und kopieren Sie die Werte required_version und requires-version aus den Dateien dieses Projekts stattdessen.
  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 verhindern.
- Wenn der Fehler beim Herunterladen oder Öffnen eines in der Harmony-Cloud bereitgestellten Projekts auftritt statt 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 die 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-Fehler kann nicht bereitgestellt werden, wenn er direkt eine E-Mail auslösen soll

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 eines Vorgangs, bei dem ein SOAP-Fehler direkt eine E-Mail auslöst, kann einen Fehler verursachen.
Lösung:
1. Konfigurieren Sie den SOAP-Fehler so, dass er stattdessen einen Vorgang auslöst.
2. Verwenden Sie in diesem Vorgang die Funktion SendEmailMessage in einem Skript, um die Benachrichtigungs-E-Mail zu versenden.

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-Beschränkungen für hohe Ports

Symptom: Eine FTP-Quelle verbindet sich erfolgreich von einer Workstation, schlägt aber fehl, wenn der Vorgang auf dem privaten Agenten ausgeführt wird, oder Dateiübertragungen werden unterbrochen, 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-Archivierungsvorgä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-Quellverbindungstest 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 bestätigt 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 bestätigt 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 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 den 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 Rolle mit unzureichenden Berechtigungen, 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 die erforderlichen Berechtigungen zur aktuellen Rolle hinzu.
2. Generieren Sie die Zugriffstokens mit der aktualisierten Rolle neu und konfigurieren Sie den NetSuite-Endpunkt neu.

Design Studio: NetSuite-Dropdown für gespeicherte Suchen 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 wird. Weitere Details finden Sie unter NetSuite-Einschränkungen für gespeicherte Suchen.

Design Studio: NetSuite NULL- oder Leerwerte 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-Benutzersegmente werden nicht in der Aktivitätskonfiguration angezeigt

Symptom: Benutzerdefinierte Segmente werden im NetSuite-Aktivitätskonfigurationsbildschirm nicht angezeigt, wenn 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 damit verbundene 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 damit verbundenen 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: SAP IDocs werden nicht gefunden, wenn ein geplanter Vorgang auf einem anderen Agent ausgeführt wird

Symptom: In einer Multi-Agent-Gruppe mit Store-and-Forward-IDoc-Verarbeitung findet der geplante Vorgang, der nach gespeicherten IDoc-Dateien sucht, bei einigen Ausführungen 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 im lokalen Dateisystem des Agents, der sie empfangen hat. Ein separater Vorgang mit schnellem Zeitplan sucht dann nach diesen Dateien und verarbeitet sie. Harmony kann diesen geplanten Vorgang 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 das nächste Mal diesen Agent auswählt.
Lösung: Jeder Agent verarbeitet seine eigenen gespeicherten Dateien beim nächsten Ausführen des geplanten Vorgangs, daher werden die Dateien schließlich verarbeitet. Wenn IDocs in garantierter Reihenfolge verarbeitet werden müssen oder ohne Warten auf die nächste geplante Ausführung des speichernden Agents, schreiben Sie die IDoc-Dateien in eine gemeinsame Ressource, auf die alle Agents 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 einem großen SAP-Massenvorgang, der Tausende von IDocs sendet, schlagen Vorgänge gegen ein nachgelagertes Zielsystem (z. B. Salesforce) intermittierend mit Verbindungs- oder Anmeldelimitfehlern fehl.
Mögliche Ursache: IDocs werden asynchron gesendet. Wenn Tausende von IDocs durch eine Massenaktualisierung generiert werden, versuchen alle, ihre nachgelagerten Vorgänge gleichzeitig auszulösen. Systeme wie Salesforce erzwingen Limits für gleichzeitige API-Verbindungen, und eine plötzliche Flut von IDoc-ausgelösten Vorgängen 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 einen geplanten Vorgang, um sie 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 den Design-Studio-Vorgang so, dass er innerhalb dieser Limits bleibt, indem Sie die Anzahl der gleichzeitigen Vorgänge drosseln.

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

Symptom: Ein IDoc wird vom SAP Event Listener empfangen, die Daten erreichen jedoch nicht den Zielendpunkt 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 die Speicher- und Weiterleitungsverarbeitung: Konfigurieren Sie die erste Operation so, dass das eingehende IDoc in eine temporäre Datei geschrieben wird, und verwenden Sie dann eine geplante Operation zur Verarbeitung der Datei. Wenn das Ziel nicht erreichbar ist, wird die Datei beibehalten und bei der nächsten geplanten Ausführung erneut verarbeitet. Anleitungen zur Implementierung der Speicher- und Weiterleitungsverarbeitung finden Sie unter Best Practices für SAP.

Design Studio: Temporäre SAP-IDoc-Speicher- und Weiterleitungsdateien werden nach 24 Stunden gelöscht

Symptom: In einem Speicher- und Weiterleitungs-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 bei der Speicher- und Weiterleitungsverarbeitung automatisch nach 24 Stunden 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 in SAP nicht 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 nimmt iDocs unter Windows nicht auf

Symptom: Der SAP Event Listener-Service wird ausgeführt, das SAP-System meldet ausgehende IDocs als erfolgreich gesendet, aber es werden keine Operationen ausgelöst. Agent-Protokolle zeigen Verbindungsfehler für die RFC-Programm-ID, z. B.:
```
serverException occured on [Program ID] connection null
```
Mögliche Ursache: Die Windows-Datei „services" 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 senden.

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: Limit für Abonnement-APIs erreicht

Symptom: Das Erstellen oder Veröffentlichen einer API schlägt mit einem Fehler wie dem folgenden fehl:
```
You have reached Maximum no of API Service configured for your Jitterbit organization
```
Ursache: Die Organisation hat die maximale Anzahl von veröffentlichten API-URLs erreicht, die von ihrem Abonnement zulässig sind. Jede veröffentlichte benutzerdefinierte API, jeder OData-Service oder jede Proxy-API (und jeder ihrer veröffentlichten Klone) verwendet eine API-URL; Entwurf-APIs zählen nicht.
Lösung: Überprüfen Sie auf der Seite APIs des API Manager die Zählerstände Custom API URLs used und Proxy API URLs used, die oben auf der Seite angezeigt werden, anhand der von Ihrem Abonnement zulässigen Gesamtzahl. Heben Sie die Veröffentlichung von APIs auf oder löschen Sie APIs, die nicht mehr benötigt werden, um API-URLs freizugeben (Entwurf-APIs zählen nicht gegen das Limit). Um das Limit zu erhöhen, wenden Sie sich an Ihren Customer Success Manager.

Veröffentlichte API gibt 404 Not Found zurück

Symptom: Der Aufruf einer veröffentlichten API gibt einen 404-Fehler zurück.
Mögliche Ursachen:
- Das Limit Hits pro Minute im zugewiesenen Sicherheitsprofil ist auf null gesetzt und blockiert alle Anfragen. Eine Änderung des Abonnementniveaus der Organisation kann dieses Limit zurücksetzen, sodass eine API, die zuvor funktioniert hat, 404-Fehler zurückgeben kann.
- Die Konfiguration, die Basis-URL oder die Sichtbarkeitseinstellungen der API sind falsch.
- 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 pro 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 zurück.
- Überprüfen Sie auf der APIs-Seite, ob die API erfolgreich veröffentlicht wurde und ob 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 Folgendes zurück:

504 Gateway Timeout

Dies tritt normalerweise auf, nachdem das Timeout-Fenster des Gateways (30 bis 180 Sekunden, je nach Timeout-Einstellung der API) abgelaufen ist.

Mögliche Ursachen:
- Die API-URL ist fehlerhaft oder Pfadparameter werden nicht korrekt verarbeitet, wodurch das Gateway beim Routing der Anfrage fehlschlägt.
- Der Backend-Vorgang oder der externe Service antwortet zu langsam innerhalb des Timeout-Fensters des Gateways, beispielsweise aufgrund großer Payloads oder komplexer Transformationslogik.
- Die Anfrage kann keinem verfügbaren Agent zugewiesen werden, beispielsweise weil die Agent-Gruppe die maximale Parallelität erreicht hat oder stark belastet ist, sodass ein Timeout am Gateway auftritt, bevor der Vorgang ausgeführt wird. Ein Zeichen dafür ist, dass die fehlgeschlagene Anfrage keinen entsprechenden Eintrag in den Vorgangslogs hat.
Lösung:
- Überprüfen Sie, dass die API-URL korrekt formatiert ist. Falls die API Pfadparameter verwendet, erwägen Sie, ein Skript zum Vorgang hinzuzufügen, das die URL explizit analysiert und die Parameterwerte erfasst.
- Falls das Timeout durch einen langsamen Backend verursacht wird, überprüfen Sie den Vorgang und seine Transformationslogik auf Performance-Engpässe, insbesondere große Datenmengen oder langsame externe Aufrufe, und reduzieren Sie den langsamen Schritt.
- Falls der Vorgang tatsächlich mehr Zeit benötigt als die aktuelle Einstellung zulässt, erhöhen Sie das Timeout auf der API-Einstellungsregisterkarte. Das API-Timeout (Standard 30 Sekunden, Maximum 180 Sekunden) ist unabhängig vom Studio-Vorgangstimeout. Das Vorgangstimeout wird nur auf privaten Agents verwendet, wenn die EnableAPITimeout-Einstellung in der Agent-Konfiguration aktiviert ist.
- Falls der Vorgang nicht innerhalb des maximalen Timeouts abgeschlossen werden kann oder eine Echtzeit-Antwort nicht erforderlich ist, gestalten Sie den API-Vorgang so um, dass die langfristige Arbeit asynchron gestartet wird (beispielsweise durch Aufrufen mit RunOperation im asynchronen Modus), damit die API eine Antwort zurückgeben kann, ohne auf den Abschluss zu warten. Siehe Asynchrone Vorgänge verwalten.
- Bei zeitweiligen Timeouts fügen Sie Wiederholungen hinzu, damit ein vorübergehender Fehler erneut versucht wird: 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 der Agent-Last korrelieren, überprüfen Sie die Agent-Kapazität: Führen Sie API-bedienende Vorgänge auf Agents aus, die von schweren ETL-Workloads getrennt sind, und fügen Sie Agents zur Gruppe hinzu, falls diese überlastet ist. Siehe Optimieren und verbessern Sie die Performance 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 im API Portal angezeigt werden.

Microsoft Entra ID OAuth: Der Name des Sicherheitsprofils darf keine Leerzeichen enthalten

Symptom: API-Aufrufe mit einem Microsoft Entra ID (Azure AD) OAuth 2.0-Sicherheitsprofil mit drei Beinen schlagen mit einem Fehler von Microsoft fehl, der auf einen Umleitungs-URL-Konflikt hinweist:
```
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-Umleitungs-URI falsch konstruiert wird und mit keiner der in der Azure-App-Registrierung registrierten Antwort-URLs übereinstimmt.
Lösung:
1. Öffnen Sie das Sicherheitsprofil im API Manager und benennen Sie es um, um Leerzeichen zu entfernen (ändern Sie beispielsweise My Profile in MyProfile oder my-profile).
2. Überprüfen Sie in der Azure-App-Registrierung, dass die dort registrierten Antwort-URLs mit dem Umleitungs-URI übereinstimmen, den API Manager für das umbenannte Profil generiert.

Microsoft Entra ID 2-legged 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 wird, stimmt nicht mit der im API Manager-Sicherheitsprofil konfigurierten Audience überein. Dies deutet normalerweise darauf hin, dass die Application ID URI in der Azure-App-Registrierung falsch konfiguriert ist oder 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 zugewiesen ist, und gehen Sie zu API verfügbar machen.
2. Bestätigen Sie, dass die Application ID URI auf eine gültige URI im Format api://<Application (client) ID> eingestellt ist.
3. Bestätigen Sie im Sicherheitsprofil, dass der OAuth-Bereich auf api://<Application (client) ID>/.default eingestellt ist.
4. Aktualisieren Sie die Clientanwendung, um ein Token mit diesem genauen Bereich anzufordern.
5. Wenn die Validierung weiterhin fehlschlägt, nachdem die Audience und der Bereich korrekt sind, öffnen Sie das Manifest der App-Registrierung und bestätigen Sie, dass requestedAccessTokenVersion auf 2 eingestellt ist. Ein fehlender oder anderer Wert kann auch dazu führen, dass die Token-Validierung fehlschlägt.

Azure AD Graph API wurde eingestellt

Symptom: API-Aufrufe, die zuvor mit einem Microsoft Entra ID (Azure AD)-Sicherheitsprofil funktionierten, schlagen mit Authentifizierungsfehlern fehl.
Mögliche Ursache: Die App-Registrierung des Sicherheitsprofils ist weiterhin 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 Microsoft Entra ID 2-legged OAuth-Sicherheitsprofilkonfiguration befolgen.

Google oder Salesforce Identity Provider: 2-legged 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-legged OAuth konfiguriert ist.
Mögliche Ursache: Google und Salesforce OAuth 2.0-API-Sicherheitsprofile unterstützen 2-legged OAuth nicht.
Lösung: Verwenden Sie ein 3-legged 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 keine Standardauthentifizierung. 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 zugewiesen ist.
2. Ändern Sie den Authentifizierungstyp zu API-Schlüssel oder OAuth 2.0, oder entfernen Sie das Sicherheitsprofil von der API, wenn der Endpunkt keine Authentifizierung erfordert.
3. Veröffentlichen Sie die API erneut und verbinden Sie sie dann in Microsoft Copilot Studio erneut. Siehe Verbinden Sie einen Jitterbit AI-Agent mit Microsoft Copilot Studio.

Schaltfläche „Neue API" ist nicht sichtbar, obwohl die richtige Organisationsrolle vorhanden ist

Symptom: Die Schaltfläche New API wird im API Manager für einen Benutzer mit einer Organisationsrolle, der aber kein Organisationsadministrator ist, nicht angezeigt. Wenn man dem Benutzer die Berechtigung Admin auf Organisationsebene erteilt, wird die Schaltfläche angezeigt, aber es werden auch alle Umgebungen für den Benutzer freigegeben.
Mögliche Ursache: Eine Organisationsrolle allein reicht nicht aus, um APIs zu erstellen. Die Rolle muss auch Write-Zugriff auf Umgebungsebene für die spezifische Umgebung haben, in der der Benutzer APIs erstellen muss.
Lösung:
1. Gehen Sie in der Management Console zu Environments und öffnen Sie die Umgebung, in der der Benutzer APIs erstellen muss.
2. Bestätigen Sie für die Rolle des Benutzers in dieser Umgebung, dass Write-Zugriff aktiviert ist. Falls nicht, aktivieren Sie ihn und speichern Sie.
3. Die Schaltfläche New API sollte jetzt für diese Umgebung sichtbar sein.

Symptom: Eine API mit zwei oder mehr zugewiesenen Basic-Auth-Sicherheitsprofilen zeigt unerwartete Benutzernamen in den API-Protokollen, einschließlich Benutzernamen, die zu keinem der Profile gehören. Einige Anfragen schlagen mit einem 401-Fehler (Unauthorized) fehl.
Mögliche Ursache: Der Browser oder API-Client (z. B. Postman) hat Basic-Auth-Anmeldedaten aus einer vorherigen Sitzung als Cookie zwischengespeichert. Wenn die API erneut aufgerufen wird, sendet der Client zuerst den zwischengespeicherten Cookie. Wenn die zwischengespeicherten Anmeldedaten nicht mit einem der konfigurierten Sicherheitsprofile übereinstimmen, wird die Anfrage abgelehnt und der unerwartete Benutzername wird in den Protokollen angezeigt, bevor die Authentifizierung mit den korrekten Anmeldedaten erfolgreich ist.
Lösung:
1. Löschen Sie die Cookies und den Cache des Browsers, oder wechseln Sie zu einem Inkognito- oder privaten Browserfenster, bevor Sie die API erneut testen.
2. Bestätigen Sie, dass das Verhalten nicht vorhanden ist, wenn eine neue Anfrage ohne vorherige Sitzungs-Cookies gestellt wird. Wenn der Fehler verschwindet, ist das Problem clientseitiges Caching von Anmeldedaten und kein Konfigurationsproblem.
Beachten Sie, dass jeder HTTP-Client, der Cookies speichert (einschließlich browserbasierten Tools und API-Test-Dienstprogrammen), das gleiche Verhalten aufweisen kann.

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

Symptom: API-Aufrufe geben 401 Unauthorized zurück, obwohl die Client-IP korrekt in den vertrauenswürdigen IP-Gruppen des Sicherheitsprofils aufgelistet ist.
Mögliche Ursache: Ein veralteter Cache von Legacy-IP-Bereichseinträgen im Sicherheitsprofil überschreibt die aktiven vertrauenswürdigen IP-Gruppen.
Lösung: Migrieren Sie das Sicherheitsprofil von Legacy-IP-Bereichen zum Modell Trusted IP Groups, dem aktuellen Allowlist-Mechanismus: Definieren Sie die IPs als vertrauenswürdige IP-Gruppe und weisen Sie sie dem Profil zu. Das Deaktivieren der Einstellung Trust requests only from the following IP ranges in einem Profil, das noch Legacy-IP-Bereiche verwendet, entfernt diese Bereiche dauerhaft (eine Bestätigungsaufforderung warnt davor), daher migrieren Sie die IPs zu einer vertrauenswürdigen IP-Gruppe, anstatt die Einstellung zu deaktivieren, um den Cache zu löschen.

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:
- Reduzieren Sie die Länge der Service-URL, indem Sie den Service-Pfad verkürzen oder die API in mehrere Endpunkte aufteilen.
- Bestätigen Sie bei Proxy-APIs, dass die Kombination aus Basis-URL und allen definierten Service-Pfaden das 8.000-Zeichen-Limit nicht überschreitet.

Proxy-API: Servicepfad-Parameter erfordern ein OpenAPI-Dokument

Symptom: Das Konfigurieren eines Proxy-API-Service-Pfads mit Pfadparametern (beispielsweise /resource/{id}) schlägt fehl, wenn dieser manuell eingegeben wird, da das Feld keine geschweiften Klammern akzeptiert.
Mögliche Ursache: Manuell definierte Service-Pfade in Proxy-APIs unterstützen die Zeichen { und } nicht, die zur Definition von Pfadparametern verwendet werden.
Lösung: Um Pfadparameter in einem Proxy-API-Service-Pfad zu verwenden, stellen Sie 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 kann in API Manager nicht gelöscht werden

Symptom: Das Löschen einer API in API Manager schlägt fehl: Die Benutzeroberfläche zeigt einen generischen Fehler an und die API wird nicht entfernt. Der Fehler tritt im Browser auf, bevor eine Löschanfrage den Server erreicht, und wird als JavaScript TypeError in der Browser-Entwicklerkonsole angezeigt.
Mögliche Ursache: Die Rolle des Benutzers hat nicht die Berechtigung Admin. Das Löschen einer API prüft zunächst, welchen API-Gruppen die API zugeordnet ist, und der Zugriff auf die Seite API-Gruppen erfordert die Berechtigung Admin: Eine Rolle mit nur Write-Zugriff auf die Umgebung kann die Seite öffnen, aber nicht deren Inhalte lesen. Wenn die Rolle die API-Gruppen nicht lesen kann, erhält diese Prüfung einen Wert, den die Benutzeroberfläche nicht verarbeiten kann, und das Löschen wird nicht abgeschlossen.
Lösung: Lassen Sie einen Benutzer, dessen Rolle die Berechtigung Admin Rollenberechtigung hat, das Löschen durchführen. Das Gewähren der Berechtigung Admin für die betroffene Rolle funktioniert ebenfalls, ist aber eine umfassende Erhöhung auf Organisationsebene, daher ist es vorzuziehen, 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 Umgebungsfeld ist nicht bearbeitbar.
Mögliche Ursache: Die Umgebung wird zum Zeitpunkt der API-Erstellung festgelegt und kann danach nicht mehr geändert werden.
Lösung:
- Um eine benutzerdefinierte oder Proxy-API in eine andere Umgebung zu verschieben, klonen Sie die API von der APIs-Seite und wählen Sie während des Klonens die richtige Umgebung aus.
- Alternativ können Sie die API aus ihrer aktuellen Umgebung exportieren und in die Zielumgebung importieren.

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

Symptom: Nach dem Aktivieren von CORS auf einer benutzerdefinierten oder Proxy-API verarbeitet die OPTIONS-HTTP-Methode Anfragen ohne Authentifizierung.
Mögliche Ursache: Das Aktivieren von CORS führt dazu, dass Operationen mit der OPTIONS-Methode ohne Authentifizierung ausgeführt werden. Dies ist erforderlich, um Browser-Preflight-Anfragen zu unterstützen, bedeutet aber, dass jede OPTIONS-Anfrage die Operation erreicht, ohne das Sicherheitsprofil zu durchlaufen.
Lösung:
- Wenn die API OPTIONS nicht für sensible Operationen verwendet, ist keine Aktion erforderlich. Dies ist das erwartete Verhalten, wenn CORS aktiviert ist.
- Wenn eine authentifizierte Verarbeitung von OPTIONS erforderlich ist, deaktivieren Sie CORS auf der API oder strukturieren Sie die Operation so um, dass sie unauthentifizierte Preflight-Anfragen explizit erkennt und verarbeitet.

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

Symptom: Eine Proxy-API, die das von Jitterbit gehostete Cloud-API-Gateway verwendet, gibt Fehler zurück oder kann die Ziel-API nicht erreichen.
Mögliche Ursache: Bei Verwendung des Cloud-API-Gateways muss die zu proxierende 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.
- Wenn 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 Whitelist zu setzen, damit das Gateway auf die zu proxierende API zugreifen kann, siehe Whitelist-Informationen.

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

Symptom: Der Umschalter Request & Response Payloads in Logs anzeigen wird in den Einstellungen einer Proxy-API angezeigt, aber das Aktivieren hat keine Auswirkung auf die Protokollausgabe.
Mögliche Ursache: Die Protokollierung von Request- und Response-Payloads wird für Proxy-APIs nicht unterstützt. Der Umschalter 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 Endpunkt aufruft, wobei die Einstellung Request & Response Payloads in Logs anzeigen unterstützt wird.

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

Symptom: Anfragen über ein privates API-Gateway schlagen zeitweilig mit einer HTTP-400-Antwort fehl. Statt einer normalen API-Antwort erhält der Aufrufer 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-Logs für die fehlgeschlagene Anfrage, da die Anfrage nie einen Vorgang 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. Falls 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. Falls die Agents auch nach dem Skalieren konsistent die Apache-Worker-Threads erschöpfen, kontaktieren Sie 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, es sei denn, Sie werden vom Jitterbit-Support angewiesen. Siehe Apache-Konfigurationsdateien.

Änderungen des Sicherheitsprofils benötigen mehrere Minuten, um wirksam zu werden

Symptom: Eine API verhält sich weiterhin so, als ob eine alte Sicherheitsprofil-Konfiguration aktiv ist, obwohl 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 weiterhin besteht, 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 deren OpenAPI-Dokumentation im 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:
- Nach dem Löschen einer API öffnen Sie den Portal Manager und entfernen oder aktualisieren Sie dort manuell den Dokumentationseintrag der API.
- 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, während es noch einer veröffentlichten API zugewiesen 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 einer API entfernt wurde.
Mögliche Ursache: Nach dem Entfernen eines Sicherheitsprofils aus der API-Konfiguration muss die API gespeichert und erneut veröffentlicht werden, bevor das Profil als vollständig nicht zugewiesen gilt. Bis die API erneut veröffentlicht wird, behandelt der API Manager das Profil weiterhin als in Verwendung.
Lösung:
1. Nach dem Entfernen des Sicherheitsprofils von der API klicken Sie auf Save und dann auf Publish für die API.
2. Sobald die API mit der aktualisierten Konfiguration erneut veröffentlicht wurde, wird das Sicherheitsprofil nicht mehr als in Verwendung angezeigt und kann gelöscht werden.

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

Symptom: Ein Sicherheitsprofil, das für 2-legged OAuth konfiguriert ist, verwendet stattdessen 3-legged OAuth, wenn es über ein privates API-Gateway bereitgestellt wird.
Mögliche Ursache: Private API-Gateways vor Version 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 die 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 sich auf demselben Host befinden

Symptom: In einer containerisierten Multi-Gateway-Umgebung hinter einem Application Load Balancer (ALB) schlagen API-Aufrufe intermittierend fehl oder Payloads können nicht abgerufen werden, obwohl einzelne Gateways fehlerfrei erscheinen.
Mögliche Ursache: Bei Verwendung eines containerisierten privaten API-Gateways mit einem ALB müssen alle Gateway-Container auf demselben Host-Rechner ausgeführt werden. Container, die auf verschiedenen Hosts bereitgestellt werden, können die Payload-Abrufung nicht koordinieren, was zu intermittierenden Fehlern führt.
Lösung:
1. Bestätigen Sie, dass alle privaten API-Gateway-Container in der Gruppe auf demselben 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-Installationshandbuch auf zusätzliche 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. Sichern Sie die On-Premise-Konfigurationsdatei, bevor Sie das private API-Gateway aktualisieren.
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
```
obwohl auf den Gateway-Hosts ausreichend Speicherplatz vorhanden 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 Speicher mehr hat. In einem Multi-Node-Private-API-Gateway hinter einem Load Balancer kann dies vorkommen, wenn der Node, der eine Anfrage verarbeitet, nicht auf eine gehostete Datei zugreifen kann, die ein anderer Node erstellt hat, da diese Dateien lokal auf jedem Node vorhanden sind.
Lösung:
1. Bestätigen Sie, dass die Gateway-Hosts nicht wirklich keinen Speicher mehr haben, indem Sie die Festplatte und Inode-Nutzung überprüfen (df -h und df -i). Geben Sie Speicherplatz frei und testen Sie erneut, nur wenn diese tatsächlich voll sind.
2. Wenn das Gateway als mehrere Nodes hinter einem Load Balancer ausgeführt wird, bestätigen Sie, dass der Load Balancer jede Anfrage und ihre Antwort konsistent an denselben Node leitet, da gehostete Payload- und Antwortdateien lokal auf dem Node vorhanden sind, der sie erstellt hat. Für containerisierte Gateways siehe Multi-Gateway ALB: Alle Container müssen sich auf demselben Host befinden.
3. Wenn der Fehler weiterhin besteht, 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 und der ls -lR-Ausgabe für die hosted-files-Verzeichnisse auf jedem Node. Der Support kann serverseitige Bedingungen überprüfen, die nicht vom Kunden konfigurierbar sind, wie z. B. 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 zur Installation oder zum Upgrade eines privaten API-Gateways für Linux (RPM) auf Version 10.62 oder später schlägt mit Fehlern zu fehlenden Abhängigkeiten 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: Das private API-Gateway ab Version 10.62 erfordert die Pakete geoip-devel und libGeoIP, die vom 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 Internetzugang hat und EPEL nicht erreichen kann, um die Pakete herunterzuladen.
Lösung:
- Aktivieren Sie auf einem Gateway-Host mit Internetzugang das EPEL-Repository vor der Installation des Gateways, wie unter Installation eines privaten API-Gateways beschrieben: 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 aus.
- Auf einem isolierten Host ohne Internetzugang wird durch die Installation des Pakets epel-release allein nur die Repository-Definition hinzugefügt; die Pakete geoip-devel und libGeoIP werden nicht heruntergeladen. Laden Sie diese Pakete und ihre transitiven Abhängigkeiten auf einem Computer mit Internetzugang 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 ausführen.

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

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

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

Symptom: Eine OData-Serviceabfrage mit den Systemabfrageoptionen $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: Setzen Sie auf privaten Agenten mit Version 11.32 oder später den OData-Parameter $noErrorOnZeroCount in der OData-Service-Konfiguration auf true. Dies führt dazu, dass $count-Abfragen 0 statt eines Fehlers zurückgeben, wenn keine Datensätze übereinstimmen.

Proxy-API: Anforderungsheader-Bindestriche werden durch Unterstriche ersetzt

Symptom: Ein Proxy-API-Vorgang empfängt Anforderungsheader, bei denen Bindestriche durch Unterstriche ersetzt werden (z. B. kommt X-Custom-Header als X_Custom_Header an), was dazu führt, dass Header-Lookups fehlschlagen.
Mögliche Ursache: Proxy-APIs haben eine Einstellung disable-hyphen-replacement, die steuert, ob Bindestriche in Anforderungsheader-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:
- Überprüfen Sie in der Proxy-API-Konfiguration die Header-Einstellung disable-hyphen-replacement. Um Bindestriche in Header-Namen beizubehalten, stellen Sie sicher, dass die Einstellung true ist.
- Falls die Proxy-API vor Einführung dieses Standards erstellt wurde und die Ersetzung unerwartet auftritt, aktualisieren Sie die Einstellung auf true und veröffentlichen Sie die API erneut.

Vorgangsprotokolle sind für API-ausgelöste Vorgänge 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 wird kein Operationsprotokoll für die von der API ausgelöste Operation angezeigt. 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, werden erfolgreiche Ausführungen standardmäßig nicht in den Operationsprotokollen angezeigt. Fehlgeschlagene Operationen werden immer protokolliert; nur erfolgreiche Operationsprotokolle und alle WriteToOperationLog-Ausgaben aus erfolgreichen Ausführungen werden ausgeblendet. Erfolgreiche Ausführungen werden nur angezeigt, wenn Debug-Modus aktivieren bis (eine API-Manager-Einstellung) oder Operationen-Debug-Protokollierung (eine Agent-Einstellung) aktiv ist.
Lösung:
1. Um erfolgreiche Operationsprotokolle und WriteToOperationLog-Ausgaben anzuzeigen, aktivieren Sie Debug-Modus aktivieren bis für die API auf der Registerkarte API-Einstellungen, oder aktivieren Sie Operationen-Debug-Protokollierung auf dem Agent.
2. Um auch die Rohanfrage- und Antwortdaten sowie Payloads zu erfassen, aktivieren Sie entweder Debug-Modus aktivieren bis (wie in Schritt 1), oder kombinieren Sie Operationen-Debug-Protokollierung mit Anfrage- und Antwort-Payloads in Protokollen anzeigen und Ausführliches Protokollieren. Welche Daten jede Einstellung erfasst, hängt von der aktivierten Kombination ab; eine vollständige Aufschlüsselung finden Sie unter API-Anfrage- und Antwortdaten.
3. Deaktivieren Sie den Debug-Modus nach dem Erfassen der benötigten Protokolle, da das Aktivieren das Protokollvolumen erhöht.

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

Symptom: Ein Workflow, der eine API-Anfrage-Payload vom Agent mehr als 2 Tage nach dem API-Aufruf abruft, kann die Payload nicht finden.
Mögliche Ursache: API-Anfrage-Payloads für benutzerdefinierte APIs und OData-Services werden maximal 2 Tage lang auf dem Agent gespeichert. Nach diesem Zeitraum ist die Payload nur verfügbar, wenn die Operation sie bereits in einen persistenten Speicher-Connector geschrieben hat (z. B. Temporary Storage, File Share oder eine Datenbank).
Lösung:
- Entwerfen Sie Operationen, die API-Anfrage-Payloads verarbeiten, um die Daten sofort zu verarbeiten, wenn die API aufgerufen wird, anstatt den Payload-Abruf zu verschieben.
- Wenn die Payload für längere Verarbeitung beibehalten werden muss, schreiben Sie sie in der ursprünglichen API-ausgelösten Operation an einen persistenten Speicherort.

API-Protokollseite behält vorherige Filterauswahlen bei

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

Unveröffentlichte APIs werden nicht in der Dropdown-Liste „Analytics-APIs" 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 derzeit veröffentlichte APIs werden in der Dropdown-Liste APIs angezeigt. APIs, die unveröffentlicht wurden, werden aus 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-Protokolle. Protokolldaten bleiben dort verfügbar, können aber nicht nach API-Name gefiltert werden.

Fehler 429: Monatliches API-Hit-Kontingent ü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, das durch ihre Lizenz definiert ist, aufgebraucht. 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 zu vermeiden, dass Sie das Limit erreichen, konfigurieren Sie Ratenbegrenzungen auf Umgebungs- oder Sicherheitsprofil-Ebene mit der Einstellung Hits pro Minute, um die Last zu verteilen und Verbrauchslimits pro Consumer durchzusetzen.
- Um das monatliche Kontingent Ihrer Organisation zu erhöhen, kontaktieren Sie Ihren Customer Success Manager.

Fehler 429: Consumer-IP nicht im vertrauenswürdigen IP-Bereich

Symptom: Ein bestimmter Consumer oder eine bestimmte 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 seine Konfiguration der vertrauenswürdigen IP-Gruppe.
2. Fügen Sie die IP-Adresse oder den Adressbereich des Consumers zu einer vorhandenen vertrauenswürdigen IP-Gruppe hinzu, oder erstellen Sie eine neue vertrauenswürdige IP-Gruppe, die die erforderlichen Adressen enthält.

Plattformweite Ratenbegrenzung: 200 Anfragen pro Minute

Symptom: APIs, die auf dem von Jitterbit verwalteten Cloud-API-Gateway gehostet werden, werden gedrosselt oder mit einer 429 Too Many Requests-Antwort unter hohem Datenverkehr abgelehnt, auch wenn die Ratenbegrenzungen des Sicherheitsprofils nicht erreicht wurden.
Mögliche Ursache: Das von Jitterbit verwaltete Cloud-API-Gateway erzwingt ein Plattform-Limit von 200 API-Anfragen pro Minute pro Organisation, das über alle API-Typen (benutzerdefiniert, Proxy und OData) verteilt ist. Dieses Limit gilt nicht für private API-Gateways.
Lösung:
- Überprüfen Sie Ihre API-Verkehrsmuster und verteilen Sie Aufrufe nach Möglichkeit über die Zeit, um innerhalb des Limits von 200 Anfragen pro Minute zu bleiben.
- Wenn Ihr Anwendungsfall einen anhaltenden Durchsatz über diesem Limit erfordert, stellen Sie ein privates API-Gateway bereit, bei dem der Durchsatz durch die Kapazität des Host-Servers und nicht durch eine Plattform-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 über ein Zscaler-verwaltetes oder ähnliches SSL-inspizierendes Netzwerk weitergeleitet werden.
Mögliche Ursachen:
- Zscaler und ähnliche Sicherheitsproxys führen SSL/TLS-Inspektionen durch, indem sie HTTPS-Datenverkehr abfangen und mit ihrem eigenen CA-Zertifikat erneut signieren. Client-Systeme, die der Zscaler-Root-CA nicht vertrauen, lehnen die Verbindung ab.
- Das manuelle Importieren des Jitterbit-Zertifikats in den Trust Store ist keine zuverlässige Lösung: Wenn Jitterbit sein Zertifikat erneuert, wird die manuell importierte Kopie veraltet und unterbricht die Verbindung erneut.
Lösung:
- Installieren Sie das Zscaler-Root-CA-Zertifikat im Betriebssystem oder Browser-Trust Store auf den Systemen, die die API-Aufrufe durchführen, damit Zscaler-erneut signierte Zertifikate vertraut werden.
- Konfigurieren Sie für Tools wie curl, wget oder openssl, dass sie den in der Zscaler-Umgebung definierten HTTP-Proxy verwenden.
- Fordern Sie eine Zscaler-Richtlinienausnahme für die Jitterbit-API-Gateway-Hostnamen an, um die SSL-Inspektionen für diese spezifischen Ziele zu umgehen.
- Überprüfen Sie die Regeln der PAC-Datei (Proxy Auto-Configuration) der Organisation, um zu bestätigen, dass Jitterbit-Endpunkte korrekt behandelt werden.
- Importieren Sie das Jitterbit-Leaf-Zertifikat nicht manuell in einen Trust Store als Lösung: Verwenden Sie stattdessen die Zscaler-Root-CA, um Unterbrechungen bei der Zertifikatreneuerung durch Jitterbit zu vermeiden.

EDI

Dieser Abschnitt behandelt Probleme mit der EDI-Funktionalität von Harmony: Kommunikation mit Handelspartnern und 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; du kannst 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:
- Stelle sicher, dass die richtige VAN-Verbindung dem betroffenen Handelspartner zugewiesen ist.
- Da die VAN-Verbindung nicht direkt von Jitterbit EDI aus konfiguriert werden kann, kontaktiere den Jitterbit-Support oder deinen Customer Success Manager, um die VAN-Verbindung und das Dokument-Routing zu überprüfen.
- Koordiniere 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, daher lehnt der Handelspartner das Dokument ab.
- Das Dokument entspricht nicht dem Implementierungsleitfaden des Handelspartners.
Lösung: Überprüfen Sie die abgelehnte Transaktion auf der Seite Transaktionen auf das spezifische Segment oder Element, das im Fehler angegeben ist, 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.
- Datentypabweichungen, 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 genau 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-Identifikatoren

Symptom: Dokumente werden falsch weitergeleitet, auf Umschlagebene abgelehnt oder vom Handelspartner nicht erkannt.
Mögliche Ursachen:
- Die EDI-ID des Absenders oder Empfängers, der Qualifizierercode 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 Qualifizierercodes 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 Konfiguration Workflows verwalten, 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: 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 Zulassungsliste 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 Zulassungsliste 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 an Handelspartner weitergeben 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: Falls eine Duplikatfilterung für EDIXml- oder XCBL-Workflows erforderlich ist, implementiere eine Deduplizierungslogik in der Studio-Operation, die die eingehenden Dokumente verarbeitet (z. B. durch Überprüfung einer Transaktions-ID gegen einen Datenbank- oder Cloud-Datastore-Datensatz vor der Verarbeitung).

EDI for Cloud v2-Aktivität schlägt auf einem privaten Agent hinter einer Firewall oder einem Proxy fehl

Symptom: Auf einem privaten Agent schlägt eine EDI for Cloud v2-Aktivität wie Get Document beim Abrufen von Daten fehl (z. B. mit einem Fehler „Unable to fetch data"), 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üge eicloudservice.com und seine Subdomänen für den ausgehenden Zugriff in die Whitelist des Netzwerks, der Firewall und des Proxys des privaten Agents ein. Weitere Jitterbit-Domänen und IP-Adressen, die ein privater Agent für den ausgehenden Zugriff benötigt, findest du unter Whitelist-Informationen.
2. Falls ein Proxy verwendet wird, stelle sicher, dass er auf dem privaten Agent korrekt konfiguriert ist und die Verbindung nicht beeinträchtigt.

Deaktiviertes EDI-Zugriffstoken verursacht `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 Zugriffstoken, das von der EDI for Cloud v2-Verbindung verwendet wird, wurde auf der Seite Access Tokens der Management Console auf Inactive gesetzt.
Lösung: Suche auf der Seite Access Tokens das Token und setze seinen Status auf Active.

Transformationsfehler: Unbekanntes 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, daher kann der Connector die Antwort nicht analysieren.
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 über die Seite Agents in der Management Console.

Wiederholtes EDI-Segment oder Loop-Zuordnung 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 einer 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 Raw-XML erstelltes Schema bildet diese korrekt ab, was das Antwortsschema 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 benutzerdefinierte XSD erneut.

Hinzufügen verschachtelter hierarchischer Loop-Ebenen (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-Absender- 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: Absender-ID-Qualifizierer
- ISA06_Sender_ID: Absender-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 in den FTP-Kommunikationseinstellungen eines Handelspartners 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ügung 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 bereits verwendet wird. Bitte bestätigen Sie und geben Sie eine eindeutige ID an.

Preferred ID [ID] kann nicht hinzugefügt werden, da es bereits 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 lokale Validierung, schlagen aber beim Testen des Handelspartners fehl

Symptom: Ausgehende EDI-Dokumente bestehen die lokale Validierungsprüfung in Jitterbit EDI, werden aber während der Handelspartner-Tests oder -Zertifizierung abgelehnt, häufig 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 der Implementierungsleitfaden des Handelspartners erfordert.
- Die EDI-Einstellungen decken die wesentlichen Elemente des Standards ab, aber der Implementierungsleitfaden 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 den Implementierungsleitfaden des Handelspartners auf obligatorische Elemente über die Standard-EDI-Einstellungen hinaus und fügen Sie diese der 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 vor Ablauf der erwarteten Aufbewahrungsfrist archiviert, oder sie bleibt länger als erwartet verfügbar.
Mögliche Ursache: Transaktionen werden basierend auf dem späteren der beiden Daten archiviert: dem Transaktionsdatum und dem 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 Berechtigungen verhindert den Zugriff.
- Die Rollen EDI User und EDI Viewer unterscheiden sich in ihren Möglichkeiten. 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

Dieser Abschnitt behandelt Probleme mit der App-Entwicklungsfunktionalität von Harmony: Erstellen, Bereitstellen und Ausführen von Anwendungen im App Builder.

App Builder startet nicht mit Fehler 500

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 HTTP-Fehler 500.30

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 HTTP-Fehler 503 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.

Ein Fehler tritt beim Laden der Datenbankverbindungsinformationen auf

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 wird mit fehlenden oder beschädigten Stilen geladen

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 schlägt fehl

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 wird nach einem Serverneustart nicht automatisch gestartet

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 schlägt fehl oder leitet zu einer falschen URL um

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 schlägt fehl 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 der 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-Log-Baseline 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 erforderlich ab April 2026

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 werden 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 dem 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: Fehler 403 Forbidden

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 Nutzlast

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 dieselbe 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 mehrmals 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 kann nicht auf erwartete Seiten oder Funktionen 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 Upgrade der App 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: Hintergrundplä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

Bei Problemen mit der App Builder Mobile-App siehe Fehlerbehebung für Mobile-Apps.

Bei Problemen mit der Widget-Konfiguration und ZIP-Dateien siehe Widget-Fehlerbehebung.

Fehlerbehebung in Jitterbit Harmony

Diagnoseschritte

Betriebsprotokolle prüfen

API-Protokolle prüfen

Agent-Protokolle prüfen

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 der Umgebungsförderung nicht übernommen

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

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

SSO-Konfigurationstest sperrt das Konto des Identitätsanbieters

IP-Zulassungsliste sperrt einen Administrator

Ändern der API-Subdomain unterbricht vorhandene API-Integrationen

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

Umgebungsänderungen werden in Harmony-Anwendungen nicht 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 wird in einer Schleife umgeleitet ohne Fehlermeldung

Cloud Datastore-Speicherlöschung schlägt mit Fehler „cannot be excluded" fehl

Zugriffstoken kann nach dem Löschen seiner Umgebung nicht bearbeitet werden

OAuth-Aktualisierungstoken-Ablauf führt zum Fehler verbundener Operationen

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

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

Organisationsregion kann nicht direkt geändert werden

Integration und Automatisierung

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

Geplante Operationen werden nicht ausgeführt

Wörterbuch oder globale Variable ist leer, nachdem eine Operation asynchron ausgeführt wird

504 Gateway Timeout (API-ausgelöste Operationen)

507 Unzureichender Speicher

502 Bad Gateway

Fehler beim Erstellen des temporären Verzeichnisses

Operationsprotokollmeldungen werden bei etwa 100 KB gekürzt

Das Debug-Logging der Operation zeigt PII und Anmeldedaten im Klartext

Fehler bei der Datenbankverbindung des Private Agent

Clientzertifikat kann auf Linux Private Agents nicht geladen werden

Validierungsfehler bei Operationen

Komponentennamen müssen nach dem Projektimport eindeutig sein

Nur Private Agent-Connector blockiert den Import in eine Cloud-Agent-Umgebung

Zielschleifenknoten ist mehreren Quellschleifenknoten zugeordnet

Erweiterte Konfigurationseigenschaften: Variablen mit rohem 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 von Connectoren bereitgestellten JSON-Schemas

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

Gespiegelte Schemas mit Substitutionsgruppen

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

Warnung zu zusätzlichen Unterelementen in Operationsprotokollen

Iterationslimit für Skriptschleife überschritten

Der Vergleich einer Zeichenkette mit einer Zahl liefert unerwartete Ergebnisse

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

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

Leere zugeordnete Felder mit flachen Quellschemas

Dateifunktionen: Operation wird nach Fehler bei ArchiveFile oder ReadFile fortgesetzt

ReadFile: Teilweise Lesevorgänge mit Binärdateiinhalt

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

FlushFile / FlushAllFiles: Fehler, wenn Zieldatei bereits vorhanden ist

DeleteFiles: Fehler, wenn Quellpfad nicht gefunden werden kann

GetJSONString: Ausführung unterbrochen bei ungültigem Pfad

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 immer null mit ODBC-Treibern

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

DBLoad: Erfordert einen JDBC-Datenbanktreiber

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

Variablenupdates gehen in segmentierten Multi-Thread-Operationen verloren

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

Lange numerische IDs werden in der Transformationsausgabe beschädigt

JSON-Transformationsausgabe lässt null- und leere Stringfelder aus

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

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

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

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

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

Dezimalarithmetik erzeugt unerwartete Gleitkommawerte

Datumsfunktionen geben Mitternacht statt eines reinen Datumswerts zurück

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

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

Dateifunktionen: Operation wird nach Fehler bei `ArchiveFile` oder `ReadFile` fortgesetzt

`ReadFile`: Teilweise Lesevorgänge mit Binärdateiinhalt

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

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

`DeleteFiles`: Fehler, wenn Quellpfad nicht gefunden werden kann

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

`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` immer null mit ODBC-Treibern

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

`DBLoad`: Erfordert einen JDBC-Datenbanktreiber

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

JSON-Transformationsausgabe lässt `null`- und leere Stringfelder aus

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

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

Der Vergleich einer Stringvariablen 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 er mit einem `SelectNodes`-Array-Element verwendet wird

`HexToBinary`-Ausgabe erscheint unverändert, wenn protokolliert

`SortArray` sortiert Dateinamen lexikografisch, nicht chronologisch

`URLEncode` codiert bestimmte „sichere" oder Multibyte-Zeichen nicht

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

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

Datenbank: `DBLookup` oder `DBExecute` schlägt beim Testen eines Skripts mit „Kein geeigneter Treiber gefunden" 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 String `"null"`