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

Diagnose-Schritte

Betriebsprotokolle überprüfen

Öffnen Sie in der Management Console die Seite Runtime und überprüfen Sie den Protokolleintrag für den betroffenen Betrieb. Der Status und alle Protokollmeldungen sind der primäre Indikator für die Ursache. Die Seite Runtime listet alle Betriebe 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 überprü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 Betriebe erscheinen hier auch neben der Runtime-Seite.

Agent-Protokolle überprü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 überprüfen

Falls ein Problem alle Operationen oder alle APIs statt nur einen einzelnen Workflow zu beeinträchtigen scheint, überprü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:
- Überprü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 richtigen 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 jedoch auf Variablenwerte zum Migrieren auswählen, was alle Variablen ausschließt, deren Wert sich geändert hat. Eine Variable, die nicht einbezogen wird 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 in der Projekthistorie erfasst werden.

Umschalten einer Agent-Gruppe 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 daher während eines Release-Rollouts 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 verbindet sich standardmäßig mit einer einzelnen Harmony-Region-URL im Anmeldedialogfeld. Wenn SSO aktiviert ist, wird die SSO-Umleitung nur für die Harmony-Region aufgelöst, die die Organisation hostet. Benutzer müssen Design Studio daher auf die URL dieser Region verweisen, bevor sie sich anmelden.
Lösung:
- Drücken Sie im Design Studio-Anmeldedialogfeld Strg + Umschalt + U, um das URL-Feld zu öffnen. Geben Sie die URL für die Harmony-Region der Organisation ein (z. B. https://na-east.jitterbit.com für NA oder https://emea-west.jitterbit.com für EMEA), und schließen Sie dann die SSO-Anmeldung ab.
- Um die Änderung dauerhaft zu speichern, legen Sie die URL in der Konfigurationsdatei client.properties fest:
  - Öffnen Sie <Jitterbit Studio Home>\configuration\client.properties in einem Text-Editor (unter macOS ist der Pfad /Applications/Jitterbit Studio [version].app/Contents/Java/configuration/client.properties).
  - Heben Sie die Auskommentierung des Parameters cloud.url auf und setzen Sie ihn auf die regionale URL.
  - Speichern Sie die Datei und starten Sie Design Studio neu.

SSO-Konfigurationstest sperrt das Identitätsanbieter-Konto

Symptom: Ein Administrator wird aus seinem Identitätsanbieter-Konto gesperrt, während er eine SSO-Konfiguration in der Management Console testet.
Mögliche Ursache: Jeder Klick auf 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 Identitätsanbieter 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 sofort nach dem Ändern der Bereiche durch einen anderen Administrator in IP-Bereich der Whitelist aktivieren den Zugriff auf das Harmony-Portal.
Mögliche Ursache: Die Richtlinie IP-Bereich der Whitelist 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 bestehende 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 bestehenden 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 berücksichtigt

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 zur Liste SSO umgehen hinzugefügt werden, bevor er zur Organisation hinzugefügt wird. 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-Authentifizierungsfluss.
Lösung:
- Löschen Sie den Browser-Cache und alle Jitterbit-bezogenen Cookies, und versuchen Sie es erneut.
- Versuchen Sie sich in einem Inkognito- oder privaten Browserfenster anzumelden, um zwischengespeicherte Daten zu umgehen.
- Versuchen Sie einen anderen Browser, um Browser-spezifische Kompatibilitätsprobleme auszuschließen.

Cloud Datastore-Speicherlöschung schlägt mit dem Fehler „kann nicht ausgeschlossen werden" 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 Löschung seiner Umgebung nicht bearbeitet werden

Symptom: Ein Zugriffstoken kann nicht bearbeitet oder kopiert werden, obwohl es 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 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 zu Fehlern bei verbundenen Operationen

Symptom: Operationen, die einen Connector mit 3-legged OAuth 2.0 (3LO) authentifizieren, funktionieren nach einiger Zeit nicht mehr, mit Authentifizierungsfehlern wie Connector could not retrieve the access token to be used in the HTTP call oder einer Meldung vom Identitätsanbieter, 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 vor Ort 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 Änderungen der Region vor Ort.
Lösung:
1. Erstellen Sie eine neue Harmony-Organisation in der Zielregion.
2. Exportieren Sie jedes Integrationsprojekt aus der Quellorganisation und importieren Sie es in die neue Organisation.
3. Konfigurieren Sie in der neuen Organisation umgebungsspezifische Einstellungen, Verbindungen, Zeitpläne, Projektvariablen und Sicherheitsprofile neu.
4. Aktualisieren Sie alle externen Clients, Integrationen oder Webhook-Konfigurationen so, dass sie auf die API-URLs der neuen Region verweisen.
5. Kontaktieren Sie für eine koordinierte Migration den Jitterbit-Support oder Professional Services, um den Zeitpunkt 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 „Eingereicht" oder „Wird ausgeführt" stecken

Symptom: Eine Operation wird nicht wie erwartet abgeschlossen. Sie bleibt im Status Submitted oder Running 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 bricht sie möglicherweise ab, als ob sie hängen geblieben wäre, auch wenn die Operation auf dem Agent abgeschlossen wurde. Dies kann Operationen betreffen, die normalerweise in Sekunden abgeschlossen werden.
- Die Operation wurde abgeschlossen, aber ihr endgültiger Status wurde nicht an Harmony zurückgemeldet, daher wird sie weiterhin als Running angezeigt, bis sie abläuft.
- Die Agent-Gruppe ist stark belastet und ist langsam beim Abholen oder Aktualisieren von warteschlangigen 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 Agenten 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 Warteschlangen-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.
- Es besteht eine Zeitzonenkonfiguration in den Zeitplaneinstellungen.
- 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 Zeitzoneneinstellung. Weitere Informationen finden Sie unter Operationszeitzone.
- Überprüfen Sie bei privaten Agents, dass 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, dass 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 gleichzeitigen 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 zu doppelt so viele gleichzeitige Operationen wie CPU-Kerne ausführen).
- Wenn eine geplante Operation versendet wird, dann aber steckenbleibt, anstatt nie zu starten, siehe Operationen, die in Submitted- oder Running-Status 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 Run type des Invoke Operation-Tools auf Asynchronously gesetzt oder RunOperation mit runSynchronously auf false gesetzt), läuft die untergeordnete Operation in einem separaten Thread 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. Für das entsprechende Verhalten in segmentierten Multi-Thread-Operationen siehe Variable updates lost in chunked multi-threaded operations.
Lösung:
- Wenn die übergeordnete Operation von Werten abhängt, die die untergeordnete Operation erzeugt, rufen Sie die untergeordnete Operation synchron auf (das Run type des Invoke Operation-Tools auf Synchronously gesetzt oder RunOperation wird 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 freizugeben, 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 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 Sleep-Funktion) erhöht die Latenz und garantiert nicht, dass die untergeordnete Operation abgeschlossen ist. Führen Sie die Operation stattdessen synchron aus.

504 Gateway Timeout (API-ausgelöste 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 Folgendes zurück:
```
507 Insufficient Storage
```
Mögliche Ursachen:
- Der Agent oder Gateway-Host hat keinen Speicherplatz mehr.
- Bei einem Private-API-Gateway kann das Gateway seine gehostete Payload- oder Antwortdatei nicht öffnen und gibt einen 507 zurück, auch wenn ausreichend Speicherplatz verfügbar ist. Dies deutet normalerweise auf ein Problem mit der privaten Domänenregistrierung oder der Gateway-Konfiguration hin.
Lösung:
- Bestätigen Sie, dass der Agent oder Gateway-Host ausreichend freien Speicherplatz hat.
- Wenn ausreichend Speicherplatz vorhanden ist und die API über ein Private-API-Gateway bereitgestellt wird, siehe Private Gateway gibt HTTP 507 oder „No such file or directory" zurück für die Ursache und Lösung.

502 Bad Gateway

Symptom: Ein Vorgang, der Jitterbit Message Queue (JBMQ) verwendet, schlägt fehl mit:
```
502 Bad Gateway
```
Der Server hat eine ungültige oder unvollständige Antwort zurückgegeben.
Mögliche Ursache: Der JBMQ-Service hat keine vollständige Antwort auf die Anfrage zurückgegeben, was zu einem 502 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 besteht, kontaktieren Sie den Jitterbit-Support.

Fehler beim Erstellen des temporären Verzeichnisses

Symptom: Ein Vorgang kann kein temporäres Verzeichnis erstellen und gibt einen Fehler wie diesen aus:
```
Failed to create the directory '/tmp/jitterbit/...'. Reason: boost::filesystem::create_directories: Permission denied
```
Bei einer Cloud-Agent-Gruppe kann stattdessen die Meldung No space left on device angezeigt werden.
Mögliche Ursachen:
- Bei einem privaten Agent verfügt das Jitterbit-Agent-Dienstkonto nicht über die erforderlichen Berechtigungen auf Betriebssystemebene für den Pfad der temporären Dateien, oder die Festplatte ist voll.
- Bei einer Cloud-Agent-Gruppe liegt die Ursache auf der Seite des von Jitterbit verwalteten Agenten und nicht in Ihrem Projekt oder Ihrer Konfiguration.
Lösung:
- Bestätigen Sie bei privaten Agenten, dass das Agent-Dienstkonto ausreichende Berechtigungen für den Pfad der temporären Dateien (/tmp oder TemporaryFiles) hat, und überprüfen Sie, ob der Agent-Host über ausreichend freien Speicherplatz verfügt.
- Bei Cloud-Agent-Gruppen deutet dies auf ein Problem auf der Agent-Seite 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 angezeigt werden.
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 mit folgendem Fehler fehl:

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 Fehler bei der TranDb-Verbindung 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 (Clientzertifikat) 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-Agenten ausführt, hat keine Leseberechtigung für die private Schlüsseldatei oder ihre übergeordneten Verzeichnisse.
- Ein Linux-Sicherheitsmodul wie SELinux oder AppArmor blockiert den Zugriff des Agenten 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 werden eine oder mehrere Komponenten als ungültig angezeigt und die Bereitstellung schlägt mit einer ähnlichen Meldung fehl:
```
[Operation / Connection / Activity / Transformation / Script / Tool / Email / Variable] names must be unique.
```
Mögliche Ursache: Das importierte Projekt enthält mehrere Komponenten desselben Typs mit identischen Namen. Studio verhindert 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 bei 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, diese zu ersetzen oder beide beizubehalten.

Nur für Private Agent verfügbare Connector-Blöcke blockieren den Import in eine Cloud-Agent-Umgebung

Symptom: Das Importieren oder Migrieren 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 importieren.

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

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

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. Bei Vorhandensein erscheint der folgende Fehler im Operationsprotokoll:
```
Transformation failed. Error: The operation "Operation" failed.
Error: Failed to convert XML file to JSON.
org.jitterbit.integration.server.engine.EngineSessionException: org.xml.sax.SAXParseException ...
```
Lösung: Verwenden Sie ein Jitterbit-Skript, um die Zeichen &, <, >, ' und " im CDATA-Abschnitt, einschließlich der CDATA-Trennzeichen (<![CDATA[ ... ]]>), durch ihre Escape-Äquivalente (&, <, >, ', ") zu Replace. Falls eine Ausrichtung nur auf den CDATA-Abschnitt nicht möglich ist, 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-Zeichenkettenwert 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, auch wenn die ursprüngliche Datei kleiner ist.
Ursache: Der JSON-Parser des Agents begrenzt einen einzelnen JSON-Zeichenkettenwert 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.

Wenn die Aktivität beispielsweise ein Feld mit dem Namen location_ids[] bereitstellt, wird es in location_ids__ konvertiert. Wenn der Endpunkt immer noch den ursprünglichen Namen erwartet, kann er einen Fehler wie den folgenden zurückgeben:
```
"error_message": "{location_ids:expected String to be a Array}"
```
Lösung:
1. Bestätigen Sie, dass in der betroffenen Aktivität ein JSON-Schema verwendet wird. Solche Schemas haben einen Stammknoten namens json:
2. Aktivieren Sie die Projekteinstellung JSON-Namen beibehalten (erfordert Agent-Version 11.48 oder später).
3. Konfigurieren Sie den Vorgang neu, stellen Sie ihn bereit und führen Sie ihn aus.
Wichtig

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

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

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

Symptom: Ein Multibyte-Zeichen in einer JSON-Connector-Antwort wird beschädigt. Der beschädigte Text zeigt das klassische Muster von UTF-8-Bytes, die als Latin-1 dekodiert werden (z. B. São Luís wird als SÃ£o LuÃs zurückgegeben). In der Regel ist nur ein Multibyte-Zeichen betroffen, das nach ungefähr 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 auf doppelte Knoten verweist, schlägt zur Laufzeit mit einem Fehler wie folgt fehl:

Failed to initialize transformation "<transformation name>". Failed to expand the target tree for the path: <path to node>. The node: <node name> cannot be created.

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

Mögliche Ursache: Beim Importieren einer Zuordnungsdatei, die doppelte Knoten zum Zielschema hinzugefügt hat, wurde die entsprechende Änderung nicht auf die Schemadefinition angewendet, die bei der Ausführung des Vorgangs verwendet wird. Dies führt dazu, dass die beiden nicht synchron sind. Dieses Problem 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. Anschließend importieren Sie die Zuordnungsdatei erneut. Durch den erneuten Import wird die bei der Laufzeit verwendete Schemadefinition mit der Zuordnung synchronisiert. Wenn der Fehler weiterhin besteht, konfigurieren Sie die Aktivität neu, die das Schema bereitstellt, und aktualisieren Sie dann das Schema in der Transformation.

Warnung zu zusätzlichen Unterelementen in Operationsprotokollen

Symptom: Eine extra subelement-Meldung in den Vorgangsprotokollen 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 Antwortdatenschema definiert sind.
Lösung: Wenn Sie die zusätzlichen Daten erfassen müssen, aktualisieren Sie das Schema, um die zusätzlichen Felder einzuschließen.

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.

`RunOperation` stoppt nach 50 synchronen Aufrufen in einer `While`-Schleife

Symptom: Nach dem Upgrade eines privaten Agents auf Version 12.11 oder später verarbeitet ein Skript, das RunOperation, RunOperationFromProject oder ReRunOperation synchron aus einer While-Schleife aufruft, weniger Datensätze als erwartet. Es tritt kein Fehler auf Vorgangsebene auf, es sei denn, das Skript selbst prüft den Rückgabewert der Funktion oder ruft GetLastError auf. Das Vorgangsprotokoll zeigt einen Eintrag, der den Vorgang identifiziert, der aufgerufen wird, wenn das Limit erreicht ist.
Mögliche Ursache: Ab Agent-Version 12.11 begrenzt ein Limit auf Agent-Ebene (MaxSynchronousRunOperationCallsInLoop im Abschnitt [OperationEngine] der jitterbit.conf-Datei, standardmäßig 50) die Anzahl der synchronen RunOperation-, RunOperationFromProject- und ReRunOperation-Aufrufe, die aus einer einzelnen While-Schleife heraus erfolgen. Alle drei teilen sich eine kumulative Zählung pro Schleife. Sobald das Limit erreicht ist, gibt jeder weitere Aufruf false zurück, ohne einen Fehler auszulösen. Eine Schleife, die den Rückgabewert nicht prüft, setzt daher die Iteration fort, ohne zu bemerken, dass spätere Aufrufe nichts bewirkt haben.

Der Vergleich einer Zeichenkette mit einer Zahl liefert unerwartete Ergebnisse

Symptom: Ein Vergleich zwischen einer Zeichenkette und einer Zahl liefert ein unerwartetes Ergebnis. Beispielsweise ergibt der Vergleich einer nicht-numerischen Zeichenkette mit 0 als gleich, 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 (beispielsweise $value == "0" oder $value == "") statt mit einer Zahl. Falls ein Wert als beide Typen ankommen kann, konvertieren Sie beide Operanden vor dem Vergleich in denselben Typ (beispielsweise mit String).

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

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

Der Unterschied liegt in der Behandlung von Namespace-Präfixen:
- Vor 10.25: Gespiegelte XML-Schemas verwendeten das Standard-Namespace-Präfix xsi.
- 10.25 und später: Gespiegelte XML-Schemas verwenden das qualifizierte Namespace-Präfix ns. Nicht zugeordnete Felder werden nicht im Schema angezeigt.
Lösung: Ab Version 10.27 behält der Import eines Projekts, dessen gespiegelte XML-Schemas vor 10.25 erstellt wurden, das ursprüngliche Namespace-Präfix bei, sodass das Schema mit dem Zeitpunkt seiner 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äfixverweise entsprechend.

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

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

Symptom: Ein Zielfeld mit dem Datentyp double im Schema erhält den Wert 0, obwohl das Zuordnungsskript einen nicht leeren Zeichenfolgenwert zurückgibt.
Mögliche Ursache: Wenn die Transformation eine Skriptausgabe verarbeitet, wird das Ergebnis in den Datentyp des Zielfelds konvertiert. 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 Zuordnungsskript eine nicht numerische Zeichenkette zurückgeben kann, fügen Sie eine explizite Validierung hinzu, um sicherzustellen, dass nur numerische Werte numerischen Zielfeldern zugeordnet werden, oder ändern Sie den Datentyp des Felds im Schema.

Leere zugeordnete Felder mit flachen Quellschemas

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

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

Symptom: Ein Vorgang wird mit Erfolgsstatus 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 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 Bytes außerhalb von UTF-8 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 Raw-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 eine Ersetzung, die 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 Raw-Byte ab und ersetzen Sie es mit deaktivierter Unicode-Hex-Unterstützung, damit HexToString auf Raw-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 von StringToHex($readFile) gemeldete Byte an, und passen Sie die Ersetzungszeichenkette (~) nach Bedarf an, dann bilden Sie 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 folglich 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 entspricht, unterbricht die Funktion sofort den Ausführungsfluss und gibt einen Fehler zurück, was dazu führen kann, dass das gesamte Skript abbricht.
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 Zielfelds umfasst sowohl RunScript als auch Unmap, aber das Feld wird nicht zugeordnet. Bei einem JSON- oder XML-Ziel wird das Feld in der Ausgabe mit einem null-Wert angezeigt, statt weggelassen zu werden.
Mögliche Ursachen:
- RunScript steht vor Unmap im selben Zuordnungsausdruck (beispielsweise RunScript("<TAG>script:MyScript</TAG>"); Unmap();). Bei Agent-Versionen vor 12.9 hob diese Kombination die Zuordnung des Felds nicht auf.
- Unmap wird aus dem von RunScript aufgerufenen Skript aufgerufen, statt direkt im eigenen Zuordnungsausdruck des Zielfelds. RunScript gibt das Ergebnis des aufgerufenen Skripts als Zeichenkette zurück, statt ein Unmap-Signal zurück zur Zuordnung zu propagieren, sodass der Aufruf von Unmap aus dem aufgerufenen Skript keine Auswirkung hat, auf jeder Agent-Version, unabhängig von bedingter Logik um den Aufruf. Dies ist das erwartete Verhalten.
Lösung:
- Falls RunScript und Unmap beide direkt im Zuordnungsausdruck des Zielfelds aufgerufen werden, führen Sie ein Upgrade auf Agent-Version 12.9 oder später durch.
- Falls Unmap aus dem von RunScript aufgerufenen Skript aufgerufen wird, verschieben Sie den Unmap-Aufruf aus dem aufgerufenen Skript in den eigenen Zuordnungsausdruck des Zielfelds, beispielsweise:
```
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 verursacht einen Fehler.
Lösung: Entscheiden Sie, ob Sie Auto-Commit-Verhalten oder explizite Transaktionskontrolle benötigen, und legen Sie dann nur die entsprechende Variable fest:
- Für Auto-Commit (jede Anweisung wird sofort committed): setzen Sie $jitterbit.scripting.db.auto_commit = true und lassen Sie jitterbit.scripting.db.transaction ungesetzt oder false.
- Für Transaktionskontrolle (Commit 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, das CallStoredProcedure verwendet, 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 Database-Endpunkt einen ODBC-Treiber verwendet, ist resultSet immer null, unabhängig davon, was die gespeicherte Prozedur zurückgibt.
Lösung:
- Falls das Resultset der gespeicherten Prozedur erforderlich ist, wechseln Sie den Database-Endpunkt zu einem JDBC-Treiber statt ODBC.
- Falls ein Treiberwechsel nicht möglich ist, rufen Sie Ausgabedaten über Ausgabeparameter statt über das Argument resultSet ab.

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

Symptom: Ein Skript, das CallStoredProcedure gegen eine PostgreSQL-Datenbank verwendet, 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. Falls das Datenbankobjekt eine PostgreSQL-Funktion statt einer Prozedur ist, kann der Treiber es nicht finden und gibt den Fehler „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, der DBLoad verwendet, 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. Falls er einen ODBC-Treiber verwendet, wechseln Sie zu JDBC.

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

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

Variablenupdates gehen in aufgeteilten 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 werden beibehalten, wenn der Vorgang abgeschlossen ist; Änderungen aller anderen Threads werden verworfen.
Lösung:
- Falls 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.
- Falls mehrstufiger Durchsatz erforderlich ist, sammeln Sie keinen Status pro Datensatz in einer globalen oder Projektvariable an. Leiten Sie stattdessen die Ausgabe jedes Threads in eine eindeutige Temporary Storage-Datei oder eine Staging-Datenbanktabelle weiter 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.
- Allgemeiner gesagt: Verlassen Sie sich nicht auf Aktualisierungen globaler oder Projektvariablen aus mehrstufigen, mehrstufigen Vorgängen in späteren Skripten oder Vorgängen. Falls 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 einem hierarchischen Ausgabeformat (z. B. JSON) zuordnet, verwirft stillschweigend doppelte Datensätze. Datensätze mit identischen Feldwerten erscheinen in der Ausgabe nur einmal, 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 doppelte Datensätze während der Normalisierung. 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 standardmäßig auch führende und nachfolgende Leerzeichen aus CSV-Feldwerten ab. Datensätze, die sich nur durch führende oder nachfolgende Leerzeichen unterscheiden, werden nach dem Trimmen identisch und unterliegen 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 statt 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 in einem Skriptschritt vor der Transformation auf true. 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 während der Konvertierung zu einem Überlauf 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 ebenfalls numerisch typisiert ist, konvertieren Sie den Wert explizit mit String, bevor Sie ihn zuordnen:
```
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 enthalten sind, erstellen Sie den JSON-Body in einem Skriptschritt mit String-Verkettung und senden Sie ihn über einen HTTP v2-Connector mit einem Request-Body ohne Schema.

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

Symptom: In einer XML- oder SOAP-Transformation wird ein zugeordnetes Feld mit einem leeren Wert als nil-Element ausgegeben, und der Ziel-Endpoint lehnt die Anfrage ab. Beispielsweise erzeugt eine leere Telefonnummernzuordnung:
```
<ns1:Phone_Number xsi:nil="true"/>
```
Einige Endpoints (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 null- oder leeren Werten 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 enthalten sind.

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 Feldwerts, 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. Ordnen Sie das Feld dann mit Replace zu, um diese zu entfernen. Bei Agent-Versionen 12.6 oder älter, bei denen UTF-8 nicht die Standardeinstellung ist, können Sie auch explizit die Zeichenkodierung 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 Script-Schritts oder einer Transformation in Studio gibt eine Projektvariable, auf die im Script 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 (beispielsweise ein Verbindungszeitüberschreitung aufgrund einer leeren Serveradresse).
Mögliche Ursache: Projektvariablenwerte werden zur Laufzeit von der Harmony-Plattform eingefügt. Während eines Design-Zeit-Tests existiert kein Laufzeitkontext, um diesen Wert einzufügen. Daher gibt ein Projektvariablenverweis einen leeren Wert zurück, es sei denn, die Variable hat einen konfigurierten Standardwert, der als Fallback verwendet werden kann. Die eigene Verbindungsauflösung einer Funktion ist ein separater Fall, der den Standardwert überhaupt nicht verwendet. Siehe Eine Funktion schlägt fehl, wenn das Endpunkt-Verbindungsfeld auf eine Variable gesetzt ist.
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 Design-Zeit-Tests). Zur Laufzeit fungiert er also auch als Fallback, wenn die Variable anderweitig nicht gesetzt ist. Siehe Projektvariablen für Konfigurationsdetails.
- Verwenden Sie eine globale Variable: Ersetzen Sie den Projektvariablenverweis durch eine globale Variable und weisen Sie ihren Wert im Script selbst zu, bevor die Zeile verwendet wird, die sie nutzt. Da eine globale Variable ihren Wert aus der Script-Ausführung statt aus der Laufzeiteinspeisung erhält, macht das Zuweisen vor der Verwendung sie während eines Design-Zeit-Tests verfügbar. Verwenden Sie dies, wenn der Wert in einem Script abgeleitet wird oder wenn Sie keinen Laufzeit-Fallback-Wert möchten. Siehe Globale Variablen für Details. Wenn auf die globale Variable in einem Connector-Konfigurationsfeld statt direkt in einem Script verwiesen wird, müssen Sie auch einen feldspezifischen Standardwert für dieses Feld definieren (siehe Standardwert definieren, das sowohl die Variable-Pill-Methode als auch die Inline-Syntax-Methode für Felder abdeckt, die keine Pill anzeigen).

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

Symptom: Das Testen eines Scripts (mit Test ausführen), das eine Funktion wie DBLookup, DBExecute oder SfLookup aufruft, schlägt fehl, beispielsweise mit:
```
No suitable driver found for [...]
```
oder ein Fehler, der einen ungelösten Variablenplatzhalter in der Endpunktadresse anzeigt. Das gleiche Script wird erfolgreich ausgeführt, wenn es in einem Vorgang bereitgestellt und ausgeführt wird.
Mögliche Ursache: Die von der Funktion verwendete Verbindung hat ein Feld (wie Anmeldung, Passwort, Verbindungszeichenfolge oder eine Serveradresse), das auf eine globale oder Projektvariable gesetzt ist. Das Testen eines Scripts führt nur das getestete Script aus, daher hat die Variable ihren Laufzeitwert noch nicht erhalten, 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 Funktion wie diese liest den Standardwert nicht, wenn eine Verbindung aufgelöst wird. Für eine Variable, auf die direkt in einem Script oder einer Zuordnung verwiesen wird, wo ein Standardwert das Problem löst, siehe Projektvariablen geben während Script- und Transformationstests leere Werte zurück.

`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 zurück. Ab Agent 11.37 behält der Agent diese Unterscheidung genau bei. Skripte oder Transformationen, die sich zuvor darauf verlassen haben, dass IsNull für leere Strings true zurückgibt, waren auf früheres Verhalten angewiesen, 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 leere Strings explizit zu testen: Wenn Sie nur überprü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, anstatt "field": "" zu verwenden.

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 überprüfen, ob eine String-Variable den Wert "0" enthält, vergleichen Sie mit dem String-Literal "0" anstelle der Ganzzahl 0:
```
// Compares string to integer: non-numeric strings coerce to 0 and match unexpectedly
If($myVar == 0, ...)

// Compares string to string: behaves as expected
If($myVar == "0", ...)
```
- Wenn die Variable einen numerischen Wert enthalten soll, stellen Sie sicher, dass sie vor dem Vergleich als Zahl und nicht als String zugewiesen wird.

Dezimalarithmetik erzeugt unerwartete Gleitkommawerte

Symptom: Ein arithmetischer Ausdruck mit Dezimalliteralen erzeugt ein Ergebnis, das sehr leicht vom erwarteten Wert abweicht. Beispielsweise gibt Double(12.01) - Double(12.00) 0.00999999999999979 anstelle von 0.01 zurück, und (4.9 * 100) - 490 wird zu 5.6843418860808e-14 anstelle von 0 ausgewertet.
Mögliche Ursache: Jitterbit Script speichert Zahlen als Gleitkommawerte. Die meisten Dezimalbrüche können in binärem Gleitkomma nicht exakt dargestellt werden, daher kann Arithmetik auf ihnen kleine Rundungsfehler ansammeln. Subtraktion, die den größten Teil eines Wertes aufhebt, macht diesen Rest sichtbar. 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
```
- Dezimalliterale mit Float umwandeln: Umhüllen Sie das Dezimalliteral in Float vor der Berechnung:
```
$a = (Float(4.9) * 100) - 490;
WriteToOperationLog($a);
```

Datumsfunktionen geben Mitternacht statt eines reinen Datumswerts zurück

Symptom: Nach dem Upgrade auf Agent-Version 12.8 oder später geben ConvertTimeZone, Date oder GeneralDate für eine Eingabe von genau Mitternacht eine vollständige Datums- und Zeitzeichenfolge zurück (z. B. 2026-01-01 00:00:00) statt einer reinen Datumzeichenfolge (2026-01-01), was die nachgelagerte Logik unterbrechen kann, die das kürzere Format erwartet. CVTDate ist nicht betroffen.
Mögliche Ursache: Mit 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 Datumzeichenfolge 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 in den Cache geschriebener Wert mit langer Ablaufzeit (z. B. 24 Stunden) verschwindet lange bevor diese Zeit verstreicht, 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 die Ablaufzeit bei jedem Lesevorgang auf 24 Stunden zurück
testVal = ReadCache("CacheTest", 86400, "env");
```
- Übergeben Sie -1, um die Schreibablaufzeit zu bewahren: Das Übergeben eines nicht positiven Werts führt dazu, dass ReadCache die durch den letzten WriteCache-Aufruf festgelegte Ablaufzeit beibehält, anstatt eine neue anzuwenden:
```
testVal = ReadCache("CacheTest", -1, "env");
```

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

Symptom: RunXSLT schlägt mit 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:
- XSLT aktualisieren, um XML-Ausgabe zu erzeugen: Ändern Sie die Ausgabeerklärung des Stylesheets in <xsl:output method="xml"/>, oder entfernen Sie die xsl:output-Erklärung vollständig (XML ist die Standardeinstellung). Dies ist der empfohlene Ansatz und funktioniert sowohl auf Cloud- als auch auf privaten Agenten.
- XSL Transform-Plugin verwenden (nur private Agenten): Für private Agent-Gruppen verwendet das veraltete XSL Transform-Plugin den Saxon-XSLT-Prozessor und unterstützt Ausgabeformate ohne XML, einschließlich HTML. Weitere Informationen zur Installation finden Sie unter Verfügbare Plugins.

`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 mit // beginnenden Zeichenkette) 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 überall im Dokument überein, unabhängig davon, welches Item-Element aus dem Array abgerufen wurde.
Lösung:
- Relativen Pfad verwenden: Lassen Sie das führende // weg und geben Sie nur den Elementnamen oder einen Pfad relativ zum aktuellen Knoten an. Dies beschränkt die Suche auf den Knoten, der als erstes Argument übergeben wird:
```
$itemName = SelectSingleNode($item, "ItemName");
```
- Alternative: Knoten in String einwickeln: Das Konvertieren des Array-Elements in eine Zeichenkette vor der Übergabe an SelectSingleNode erzeugt ebenfalls das richtige Ergebnis, aber die Verwendung eines relativen Pfads ist der bevorzugte Ansatz:
```
$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 Rohdaten im Binärformat ausgeben. Bei Übergabe eines Binärwerts wird dieser zur Anzeige in Hexadezimalformat konvertiert. 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 diese 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 in der erwarteten chronologischen Reihenfolge, wenn Dateinamen eingebettete Datums- oder Zeitzeichenketten 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 unverarbeiteten Dateinamens.

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

Symptom: Ein Wert, der durch URLEncode geleitet wird, wird zum 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 werden sie nie codiert: $ - _ . + ! * ' ( ) ,. 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 der Agent Version 12.4 oder später verwendet.

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 sowohl die Jitterbit Apache- als auch die 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 Rekursionstiefe).
```
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 Limit für Schleifeniterationen pro Skript (JavaScriptMaxIterations, siehe Limit für Skript-Schleifeniterationen überschritten) die Rekursionsobergrenze nicht erhöht, die nicht als konfigurierbare Einstellung verfügbar gemacht wird.

JavaScript: Änderungen an globalen Variablen gehen bei Skriptfehlern verloren

Symptom: Ein JavaScript-Skript, das globale Variablen ändert, wird in einigen Fällen ohne erkennbaren Fehler ausgeführt, aber Änderungen an diesen globalen Variablen fehlen in nachfolgenden Skripten oder Operationen.
Mögliche Ursachen:
- In JavaScript werden Änderungen an globalen Variablen nur 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 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 aus und verwenden Sie sie konsistent im gesamten Skript.
- Um zu bestätigen, welche Variablen gesetzt werden, fügen Sie WriteToOperationLog-Aufrufe hinzu, um Variablenwerte an Schlüsselpunkten während der Ausführung zu protokollieren.

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

Symptom: Der Aufruf von Jitterbit.GetVar auf eine benutzerdefinierte Projektvariable in einem JavaScript-Skriptschritt gibt null statt des Variablenwerts zurück, ohne eine Fehlermeldung anzuzeigen.
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 die Punktnotation von JavaScript 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 eignen sie sich nicht für Arrays oder Objekte. Ein mit SetVar festgelegter Wert kann mit GetVar innerhalb desselben Skripts gelesen werden, bleibt aber nicht in späteren Skripten erhalten.
Lösung: Verwenden Sie die Syntax $variableName 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 die Punktnotation von JavaScript nicht direkt zugreifen kann. Verwenden Sie für eine bestimmte Variable entweder $-Präfixierung oder GetVar/SetVar, nicht beides. Siehe auch JavaScript: Änderungen an globalen Variablen 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
```

Das Hochladen einer Schemadatei ersetzt sie projektübergreifend

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

Die Bereitstellung der Marketplace-Prozessvorlage schlägt aufgrund von Schemaabweichungen 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ät fehlen und die Validierung fehlschlägt.
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 vom 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 verbessert sich die Reaktionsfähigkeit mit weniger Operationen pro Workflow. 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 diese 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, einschließlich OpenAI's GPT-5.6-Modelle, unterstützen keinen On-Demand-Durchsatz und erfordern stattdessen die ID eines regionsübergreifenden Inferenzprofils anstelle der Modell-ID, die in der Liste Modell auswählen der Aktivität zurückgegeben wird.
Lösung:
1. Gehen Sie in der AWS Management Console zu Amazon Bedrock > Inferenzprofile und suchen Sie die Inferenzprofil-ID für das Modell. Beispiel: Die Inferenzprofil-ID für anthropic.claude-3-5-haiku-20241022-v1:0 in den USA ist us.anthropic.claude-3-5-haiku-20241022-v1:0. Für OpenAI's GPT-5.6-Modelle variieren gültige Inferenzprofil-ID-Präfixe je nach Modell und Region (z. B. us. oder global.), wie us.openai.gpt-5.6-terra oder global.openai.gpt-5.6-terra. Die genaue Inferenzprofil-ID für Ihr Modell und Ihre Region finden Sie in AWS's Modellkarten für GPT-5.6 Sol, GPT-5.6 Terra und GPT-5.6 Luna.
2. Geben Sie die Inferenzprofil-ID mit der Option Modellkennung eingeben in der Aktivitätskonfiguration ein.

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

Symptom: Eine Cloud Datastore-Aktivität Delete Items meldet Erfolg im Operationsprotokoll, aber der Zieldatensatz existiert noch, wenn man ihn danach abfragt.
Mögliche Ursache: Delete Items identifiziert Datensätze anhand des Schlüssel-Werts (oder Alternativer Schlüssel) des Speichers, der im keys- oder ids-Array 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 Delete Items-Anfrage vorbereitet, den Schlüssel-Wert (oder Alternativer Schlüssel) des Speichers zu, nicht die interne Datensatz-ID.
- Wenn Sie von einer Query Items-Aktivität verketten, ordnen Sie den key-Wert aus der Abfrageantwort der Löschanfrage zu.

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

Symptom: Ein Coupa-Connector-Vorgang schlägt mit einem Forbidden (403)-Fehler fehl, wenn API-Schlüssel-Authentifizierung verwendet wird.
Mögliche Ursache: Seit Coupa Release R35 (Januar 2023) sind Coupa API-Schlüssel veraltet und werden nicht mehr für die Authentifizierung unterstützt. Verbindungen, die für die Verwendung von API-Schlüssel-Authentifizierung konfiguriert sind, erhalten einen 403-Fehler.
Lösung:
1. Wechseln Sie in der 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 und testen Sie erneut.

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

Symptom: Eine DBLookup- oder DBExecute-Funktion für eine PostgreSQL- oder SQL Server-Datenbank über einen JDBC-Treiber schlägt zur Laufzeit fehl mit:
```
Base64 decoding failed. Reason: error:00000000:lib(0)::reason(0)
```
Dies tritt auf, wenn der zurückgegebene Wert Base64-codierten Daten ähnelt, wie 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 können fälschlicherweise versuchen, 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): Multibyte-Zeichen werden nicht korrekt verarbeitet

Symptom: Beim Lesen aus oder Schreiben in eine Datenbank über den Datenbank-Connector mit einem ODBC-Treiber werden Multibyte- oder Nicht-ASCII-Zeichen (z. B. Umlaute oder nicht-lateinische Zeichen) nicht korrekt verarbeitet.
Mögliche Ursache: Die Unterstützung für Multibyte-Zeichen beim Datenbank-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 wird bei Verwendung eines JDBC-Treibers nicht benötigt.
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. Beispielsweise 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 wird durch Sicherheitsrichtlinie blockiert

Symptom: Ein Datenbank-Connector-Verbindungstest schlägt fehl mit:

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

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

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

oder einen bestimmten Verbindungsstring-Parameter:

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

Mögliche Ursache: Agent-Version 12.10 und später schränken bestimmte Datenbankverbindungen und Verbindungsstring-Parameter standardmäßig aus Sicherheitsgründen ein. Dies umfasst Verbindungen zu localhost oder 127.0.0.1 sowie bestimmte Verbindungsstring-Parameter für die MySQL-, PostgreSQL-, Oracle- und SQL Server-Treiber. Eine Verbindung, die zuvor funktioniert hat, kann nach dem Upgrade eines privaten Agents auf Version 12.10 fehlschlagen, da die Einschrä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 Agent 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 Agent neu.

Datenbank: Verbindungszeitüberschreitungen unter Last

Symptom: Datenbank-Quell- oder Zielvorgänge schlagen unter hoher gleichzeitiger Last intermittierend fehl, mit einer Ausnahme ähnlich wie:
```
java.sql.SQLException: Network error IOException: Connection timed out
Caused by: java.net.ConnectException: Connection timed out
```
Mögliche Ursache: Jeder Datenbankvorgang öffnet eine neue physische JDBC-Verbindung und schließt sie danach, anstatt eine vorhandene wiederzuverwenden. Unter gleichzeitiger Last erzeugt dies genug Verbindungswechsel gegen die Zieldatenbank, dass einige Verbindungsversuche ein Timeout verursachen.
Lösung: Agent-Version 12.11 und später können Verbindungen in einem Pool zusammenfassen und wiederverwenden, anstatt für jeden Vorgang eine zu öffnen und zu schließen, was diesen Wechsel reduziert. Setzen Sie auf einem privaten Agent jdbc.hikari.enabled=true im Abschnitt [SourceTargetPooling] der Agent-Konfigurationsdatei (jitterbit.conf), und starten Sie dann den Agent neu.

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 einen der folgenden Einträge:
```
One or more values were truncated when inserting and/or updating the field
```
```
Field value too long
FieldName: m_site  Length: 3  Length Allowed: 1
```
Mögliche Ursache: Standardmäßig lehnt die Aktivität die Zeile ab und meldet den Status Error, wenn ein zugeordneter Quellwert die definierte Länge der Zielpalte überschreitet, anstatt den Wert zu kürzen.
Lösung:
1. Aktivieren Sie in der Konfiguration der Datenbank-Aktivität Insert, Update oder Upsert die Option Allow truncation of character fields to avoid field length errors. Mit dieser Option werden Werte, die die Zielfeld-Länge überschreiten, gekürzt und die Operation meldet den Status Success with Info statt Error.
2. Falls Kürzung nicht akzeptabel ist, kürzen oder transformieren Sie das Quellfeld in der Transformationszuordnung, damit Werte die Zielpalten-Länge nie überschreiten, oder vergrößern Sie die Zielpalte auf der Datenbankseite.
3. Stellen Sie die Operation erneut bereit und führen Sie sie erneut aus.

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

Symptom: Benutzerdefinierte JDBC-Treiber-JAR-Dateien, die für den Datenbank-Connector installiert wurden, werden gelöscht oder überschrieben, wenn der Agent aktualisiert wird.
Mögliche Ursache: Nur das Verzeichnis <JITTERBIT_HOME>/tomcat/drivers/lib/ wird bei Agent-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 sie in das richtige Verzeichnis und starten Sie den Agent neu.

Datenbank: Sonderzeichen in Spaltennamen verursachen Abfragefehler

Symptom: Datenbank-Abfragen 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 Datenbank-Aktivität auf die Ansicht statt auf die ursprüngliche Tabelle.

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

Symptom: Eine Datenbank-Aktivität Query schlägt fehl oder wird gekürzt, wenn die konfigurierte SQL-Anweisung sehr lang ist.
Mögliche Ursache: Das Feld für die SQL-Anweisung in einer Datenbank-Aktivitä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 on iSeries (AS/400 oder IBM i) mit einem JDBC-Treiber kann keine Verbindung herstellen.
Mögliche Ursache: Einige Verbindungen zu DB2 on iSeries mit einem JDBC-Treiber verursachen Probleme, die bei einem ODBC-Treiber nicht auftreten.
Lösung: Wechseln Sie die Verbindung zu einem ODBC-Treiber statt JDBC. ODBC-Verbindungen werden nur auf privaten Agenten unterstützt.

IBM DB2: JCC-JDBC-Treibereinrichtung (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 verursacht Kompatibilitätsfehler mit neueren DB2-Versionen.
Mögliche Ursachen:
- Die Treiberdatei db2jcc.jar implementiert die veraltete JDBC-3-Spezifikation. Die aktuelle db2jcc4.jar implementiert JDBC 4, das neuere DB2-Versionen erfordern.
- Der JCC-Treiber 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 keinen JCC-Treiber oder Lizenzdatei erfordert.

Kerberos: „Could not initialize class KerbAuthentication"

Symptom: Eine Datenbankverbindung mit Kerberos-Authentifizierung schlägt fehl mit:
```
Could not initialize class com.microsoft.sqlserver.jdbc.KerbAuthentication
```
Mögliche Ursache: Die Kerberos-Konfigurationsdateien auf dem Agent-Host haben nicht die 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 des Verbindungstests

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 verursacht dies einen Konflikt mit der Kerberos-Konfiguration.
Lösung:
1. Entfernen Sie den Parameter -Dsun.security.jgss.native=true aus den JVM-Argumenten des Agenten.
2. Fügen Sie in krb5.conf unter dem Abschnitt [libdefaults] den Eintrag udp_preference_limit = 1 hinzu, um TCP statt UDP für Kerberos-Datenverkehr zu erzwingen.
3. Starten Sie den Agent neu.

Microsoft Excel: „Operation must use an updateable query"

Symptom: Eine Datenbankaktivität 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; an, um die Excel-Datei im Lese-/Schreibmodus zu öffnen.

MySQL: Zugriff verweigert trotz korrekter Anmeldedaten

Symptom: Die Verbindung zu einer MySQL-Datenbank mit dem Datenbankconnector 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 aus 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 Syntax für Berechtigungen 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 die Insert- oder Update-Leistung nicht

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

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

Symptom: Beim Konfigurieren einer Datenbankverbindung zu MySQL mit einem ODBC-Treiber auf einem privaten Agenten wird der installierte Treiber nicht in der Dropdown-Liste Treiber in Studio angezeigt.
Mögliche Ursache: Der ODBC-Manager auf dem Host des privaten Agenten 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 Host des privaten Agenten (Windows) Datenquellen (ODBC) (unter Verwaltung) und bestätigen Sie, dass der MySQL ODBC-Treiber aufgeführt ist. Informationen zu MySQL-Treiberoptionen finden Sie unter Mit MySQL verbinden.
- Bestätigen Sie, dass der Agent sich mit dem richtigen Computer verbindet: Der ODBC-Treiber muss auf dem Agent-Host installiert sein, nicht auf dem Computer des Studio-Benutzers.

PostgreSQL: Fehler bei Client-Encoding-Nichtübereinstimmung

Symptom: Ein Verbindungstest des Datenbankconnectors zu PostgreSQL schlägt mit einem Fehler „Client-Encoding-Nichtübereinstimmung" 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 Datenbankverbindungseinstellungen ConnSettings=SET CLIENT_ENCODING to 'LATIN1' (ersetzen Sie das tatsächliche Encoding des Servers) zum Feld Zusätzliche Verbindungszeichenfolgen-Parameter hinzu.
- Wenn der Server unter Windows ein kyrillisches Encoding wie WIN1251 verwendet, legen Sie das Client-Encoding auch in den ODBC-Treibereinstellungen auf WIN1251 fest.

PostgreSQL: Verwenden Sie den von Jitterbit bereitgestellten Treiber unter Linux

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-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 die Windows-integrierte Sicherheit.
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 nach dem Anwenden von Berechtigungsänderungen neu.

SQL Server: „Kann keinen expliziten Wert für die Identitätsspalte einfügen" beim Einfügen in eine Identitätsspalte

Symptom: Ein Database-Connector-Vorgang, der in eine SQL Server-Tabelle mit einer Identitätsspalte schreibt, schlägt fehl mit:
```
Database Error: Cannot insert explicit value for identity column in table '<table>' when IDENTITY_INSERT is set to OFF.
```
Mögliche Ursache: Die Identitätsspalte ist in der INSERT-Anweisung enthalten, die der 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 die 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, legen Sie IDENTITY_INSERT in der Zieltabelle in Pre- und Post-SQL-Skripten innerhalb der Aktivität fest:
```
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 hat den gebündelten Treiber auf eine Version aktualisiert, die standardmäßig Verschlüsselung anfordert, daher kann eine vor diesem Upgrade konfigurierte Verbindung danach fehlschlagen.
Lösung: Geben Sie encrypt=false; im Feld Zusätzliche Verbindungszeichenfolgen-Parameter unter Optionale Einstellungen der Datenbankverbindung ein, oder 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: 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 mithilfe von Variablen oder Skripten zusammengestellt werden, fügen Sie vor der Übergabe von Adressen an die Aktivität eine Deduplizierungsprüfung hinzu.

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

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

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

Symptom: E-Mails, die mit S/MIME-Signierung konfiguriert sind, können nicht versendet werden, werden vom Server des Empfängers abgelehnt oder kommen unsigniert an, wenn ein Cloud-E-Mail-Anbieter wie Microsoft 365 oder Exchange Online verwendet wird.
Mögliche Ursachen:
- Cloud-Anbieter erfordern ein S/MIME-Zertifikat, das von einer vertrauenswürdigen Zertifizierungsstelle (CA) ausgestellt wurde. Selbstsignierte Zertifikate werden von Cloud-Anbietern wie Microsoft 365 (Exchange Online) nicht akzeptiert.
- S/MIME 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.

E-Mail: Microsoft 365 (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 der Benutzername, das Kennwort, die Client-ID, die Mandanten-ID und das Client-Geheimnis alle korrekt sind.
Mögliche Ursache: Die ROPC-Authentifizierung erfordert, dass die 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 die 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 die 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, Dateifreigabe und lokaler Speicher: „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, Dateifreigabe und lokaler Speicher: 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, Dateifreigabe und lokaler Speicher: 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 Speicherorte schreiben.
Mögliche Ursachen:
- Die Felder für den Erfolgsordner und den Fehlerordnerpfad in FTP-, File Share- und Local Storage-Aktivitäten unterstützen keine 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 Speicherort zu verschieben oder umzubenennen.

FTP, Dateifreigabe, lokaler Speicher und temporärer Speicher: „Header schreiben" erzeugt 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 es wird überhaupt keine Datei erstellt (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 (z. B. beim Lesen von Hunderten kleiner Dateien in einer Schleife oder bei vielen Operationen, die nach Plan gegen den gleichen Server laufen), schlägt schließlich mit einer Anmeldungsverweigerung oder einem Verbindungsfehler fehl. Die gleiche Operation funktioniert unter geringerer Last.
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, Operationsläufe oder Projekte hinweg wiederverwendet. Dies ist beabsichtigt. Wenn viele Operationen gegen den gleichen Server laufen, z. B. mehrere geplante Operationen oder mehrere Projekte, die auf den gleichen Host abzielen, authentifiziert sich jeder Lauf 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 hergestellt werden. Ersetzen Sie eine Read-Aktivität in einer Schleife durch eine einzelne Read-Aktivität, die einen Platzhalter im Feld Get Files verwendet (z. B. *.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 „Anmeldung verweigert. Authentifizierungsfehler." 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 von einem interaktiven SFTP-Client aus erfolgreich authentifizieren.
```
Failed to get ftp directory list for url sftp://example.com:22/. Login denied. Authentication failure.
```
Mögliche Ursachen:
- Der private Schlüssel ist durch eine Passphrase geschützt, aber die Einstellung PrivateKeyPassphrase fehlt im Abschnitt [SSH] der Agent-Datei jitterbit.conf.
- Ein Passwort ist im FTP-Endpunkt zusammen mit dem privaten Schlüssel konfiguriert. Das Vorhandensein eines Passworts in den Endpunkt-Einstellungen beeinträchtigt die schlüsselbasierte Authentifizierung.
Lösung:
- Bestätigen Sie für private Agenten, 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-Endpunkt-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: „FTP-Umbenennung verwenden" 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 Agenten 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 archive pattern-Operationen.
Der Dateiname enthält Multibyte-Zeichen und der SFTP-Server unterstützt das Umbenennen von Dateien mit solchen Namen nicht. Ab Agent-Version 12.8 kann der FTP-Connector Dateien mit Multibyte-Namen lesen und schreiben. Bei aktiviertem Use FTP Rename lädt der Agent die Datei jedoch unter einem temporären Namen (Suffix -jbupload) hoch und benennt sie dann um. Wenn der Server die Multibyte-Namen nicht umbenennen kann, wird eine irreführende Fehlermeldung Permission denied zurückgegeben. Dateinamen mit nur ASCII-Zeichen sind nicht betroffen. Dies ist eine Einschränkung des SFTP-Servers, nicht von Jitterbit.
Lösung:
- Stellen Sie sicher, dass der Agent Version 11.56 oder später ist, wo Use FTP Rename mit SFTP wie erwartet funktioniert. Cloud-Agenten werden automatisch aktualisiert; aktualisieren Sie private Agenten bei Bedarf.
- Deaktivieren Sie das Kontrollkästchen Use FTP Rename in der Aktivitätskonfiguration, damit der Agent direkt in den Zielpfad schreibt, anstatt unter einem temporären Namen hochzuladen und umzubenennen. Dies vermeidet den Umbenennungsschritt und behebt beide Ursachen.
- Verwenden Sie für den Multibyte-Fall alternativ einen SFTP-Server, der das Umbenennen von Dateien mit Multibyte-Namen unterstützt.

SFTP: Anhängen an Datei wird 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 abgeschnittenen Dateinamen.
Mögliche Ursache: Der FTP-Connector behandelt den Dateipfad als URL, in der das Hash-Zeichen ein reserviertes Fragment-Trennzeichen ist. Der Connector 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-Agenten 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 privaten 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 für diesen Zweck kein lokales Dateisystem zur Verfügung.
Lösung:
- Verwenden Sie private Agenten für alle Vorgänge, die den Local Storage-Connector erfordern. Local Storage ist auf privaten Agenten standardmäßig deaktiviert, daher aktivieren Sie es auch in der Konfigurationsdatei des privaten Agenten (siehe Lokalen Dateispeicherort aktivieren).
- Ersetzen Sie für Cloud-Agent-Workflows Local Storage durch Temporary Storage oder einen externen Speicher-Connector (File Share, FTP oder Cloud Datastore).

Temporärer Speicher: Dateien fehlen, wenn sie von einer späteren Operation 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 Wichtige Hinweise.
Lösung:
- Verknüpfen Sie Vorgänge, die Temporary Storage-Dateien gemeinsam nutzen müssen, in die gleiche Vorgangskette mit Vorgangsaktionen, wobei das Temporary Storage-Verhalten konsistent und zuverlässig ist.
- Für private Agenten 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), anstelle von Temporary Storage.

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: Limit von 50 GB Dateigröße 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.
- Falls nur Cloud-Agenten verfügbar sind, teilen Sie große Datenmengen 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 %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 Ziel-Variablen 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 Ziel-Variablen 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 Anforderungsschemas 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 Authentifizierung. Fügen Sie keinen manuellen Authorization-Header neben der konfigurierten Authentifizierung hinzu.
- Falls 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-Projektvariablen schlägt beim Parsing fehl

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]
```
Dasselbe JSON funktioniert, wenn es 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"}.
- Falls der JSON-Inhalt statisch ist, fügen Sie ihn direkt in die Spalte Value der Tabelle Request Headers ein, statt eine Variable zu verwenden. Der Connector wendet das notwendige 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 Konstruieren der endgültigen URL ein.

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

Symptom: REST-API-Aufrufe über den HTTP v2-Connector schlagen beim Zielsystem fehl, da URL-Parameter in der ausgehenden Anfrage doppelt codiert erscheinen (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 konstruiert 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: Operation schlägt fehl, wenn die Basis-URL umgeleitet wird

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

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

Symptom: Eine HTTP v2-Aktivität verwendet eine globale, Projekt- oder Jitterbit-Variable 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 innerhalb dieses Teilpfads (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 die Zeichenkette `"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-null-Literal 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 angegeben 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 Zieleingang 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 untergeordnete Elemente 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 Groß-/Kleinschreibung beachtet

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 Groß-/Kleinschreibung (z. B. objectClass).
Lösung:
1. Überprüfen Sie in der LDAP-Aktivitätskonfiguration Search Entry das vorausgefüllte Feld Filter Expression.
2. Passen Sie die Groß-/Kleinschreibung von Attributnamen an, die der LDAP-Zielserver erwartet. Ändern Sie z. B. ObjectClass in 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 für diese Endpunkte 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 Abfragefilterbedingungen auswä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 Auswahlliste 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 mit `Edm.String`-Typkonflikt abgelehnt

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

Ein Wert wurde gefunden, dessen Typname nicht mit den Metadaten 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 Abfragefilterbedingung" 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:
- Registerkarte „Basic": Aktivieren Sie das Kontrollkästchen Include Count. Dies fügt $count=true automatisch zur Abfrage hinzu.
- Registerkarte „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: Datencenter-URL-Fehler

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

Connector Error: Error getting the data center URL.

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

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

Unter bestimmten Umständen kann stattdessen dieser Fehler auftreten:

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

NetSuite: `INSUFFICIENT_PERMISSION` trotz erfolgreichem Verbindungstest

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

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

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

NetSuite: Benutzerdefinierte Felder 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 Body-Felder nicht sichtbar aufgrund fehlender Rollenberechtigung

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: Erweiterte Suche: Schaltfläche „Abfrage testen" 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: Testabfrage-Analysefehler, wenn 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 höher

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

NetSuite: Update-Aktivität gibt `INVALID_KEY_OR_REF` zurück, wenn 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: Operationen schlagen nach der 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 fehl mit „is not a legal value for Country"

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 geladen werden mit „No entity sets found"

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 nur Daten 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 Datenbereichs-ID 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 file is not present"

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

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

Mögliche Ursache: Der Oracle EBS-Konnektor erfordert, dass der Oracle JDBC-Treiber (ojdbc8.jar) manuell auf dem privaten Agent platziert wird. Diese Datei 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 Host des privaten Agents.
3. Starten Sie alle Agents in der Agent-Gruppe neu.
4. Testen Sie die Oracle EBS-Verbindung erneut.

Salesforce: Operationen schlagen aufgrund von API-Datensatzlimits fehl

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

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

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

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

Hinweis

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

Salesforce-Zertifikat: Nichtübereinstimmung des Subject Alternative Name (SAN)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Salesforce Bulk-Aktivitäten schlagen fehl, wenn sie durch eine API- oder SOAP-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
```
Die gleiche Bulk-Aktivität wird ohne Probleme ausgeführt, wenn sie unabhängig oder auf andere Weise ausgelöst wird.
Mögliche Ursache: Operationen, die über eine API- oder SOAP-Anfrage ausgelöst werden (z. B. ein Salesforce-Outbound-Message-Flow), unterstützen keine Salesforce Bulk-Aktivitäten. In diesem Kontext ist die Organisations-ID für das Bulk-Load-Subsystem nicht verfügbar, was zum Datenbankconstraint-Fehler bei der Initialisierung führt.
Lösung: Ersetzen Sie die Bulk-Aktivität durch die entsprechende Standard-Salesforce-Aktivität in Operationen, die Teil einer API- oder SOAP-ausgelösten Kette sind. Ersetzen Sie beispielsweise eine Bulk Query durch eine Standard-Query-Aktivität oder ein Bulk Update durch eine Standard-Update-Aktivität. Standard-Aktivitäten funktionieren in diesem Kontext ordnungsgemäß.

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

Symptom: Nach dem Neustart oder der Neuinstallation eines privaten Agents können Salesforce Events-Konnektor-Events nicht aktiviert werden, auch wenn die Verbindungsanmeldedaten korrekt sind.
Mögliche Ursache: Nach einem Neustart ist die Konnektor-JAR-Datei möglicherweise noch nicht auf dem Agent vorhanden. Um ein Event zu aktivieren, muss der Konnektor zunächst auf den Agent heruntergeladen werden.
Lösung:
1. Öffnen Sie die Salesforce Events-Verbindungskonfiguration in Studio.
2. Klicken Sie auf Test, um die Verbindung zu testen. Dies erzwingt das Herunterladen der Konnektor-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 Konnektor-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 bekanntes Problem in Studio.
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 mit folgendem Fehler fehl:

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 vorgelagerte Anforderungstransformation 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 Anforderungstransformation, die der SAP-Aktivität RFC vorgelagert ist, 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 Autorisierungsobjektzuweisungen 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 hat die falsche Groß-/Kleinschreibung (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.

ServiceNow: 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 Läufe 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 Lauf 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.

ServiceNow v2: Ein Objekt wird nicht unter seinem ServiceNow-Connector-Namen aufgelistet

Symptom: Ein Objekt, das im ServiceNow-Connector unter einem bekannten Namen auswählbar ist, kann im ServiceNow v2-Connector unter demselben Namen nicht gefunden werden.
Ursache: Die Verwendung der ServiceNow REST API durch den ServiceNow v2-Connector macht Objekte unter Verwendung des tatsächlichen Backend-Tabellennamens von ServiceNow verfügbar, der sich vom Namen unterscheiden kann, der für dasselbe Objekt im ServiceNow-Connector verwendet wird. Beispielsweise entspricht das Objekt mit dem Namen System im ServiceNow-Connector Sys im ServiceNow v2-Connector.
Lösung: Suchen Sie in ServiceNow den tatsächlichen Tabellennamen des Objekts unter System Definition > Tables auf und suchen Sie dann nach diesem Namen in der Aktivitätskonfiguration des ServiceNow v2-Connectors.

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

Symptom: Nach dem Ändern der API-Version auf einer 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 zu bestätigen, 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-Space-Fehler 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 wenige Zeilen zurückgeben, oder wenn derselbe Agent auch über andere Connectors mit Heap-Fehlern fehlschlägt, ist die Ursache wahrscheinlicher die Gesamtheap-Zuordnung des Agenten als die Größe des Ergebnissatzes. Siehe Java heap space: 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.

Snowflake: Operationen schlagen auf Agent 12.x fehl

Symptom: Bei 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 bezieht sich auf die Arrow-Speicherschicht des Treibers, zum Beispiel:

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

oder:

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

Mögliche Ursache: Standardmäßig gibt der Snowflake-JDBC-Treiber Abfrageergebnisse im Apache-Arrow-Format zurück, das nicht mit Agent-Version 12.x und später kompatibel ist. Weitere Details finden Sie in Snowflakes Artikel zur Fehlerbehebung bei diesem Java-Modulfehler. Der Verbindungstest gibt kein Resultset zurück, daher wird er 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 Arrow 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, falls 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 die Operation 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 Value data zu den vorhandenen Java-Optionen --add-opens=java.base/java.nio=ALL-UNNAMED 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 Authentifizierungsdeprecation fehl

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

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

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

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

Symptom: Beim Konfigurieren einer Snowflake-Aktivität wird die Liste der verfügbaren Objekte nicht gefüllt oder erscheint leer, obwohl der Verbindungstest erfolgreich ist.
Mögliche Ursache: Snowflake Developer Instances wechseln in den Ruhezustand, wenn auf sie lange nicht zugegriffen wurde. Während der Verbindungstest gegen eine schlafende Instanz erfolgreich sein kann, gibt die Instanz möglicherweise keine Tabellen- und Objektmetadaten zurück.
Lösung:
1. Melden Sie sich bei 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: Nichtübereinstimmung der Groß-/Kleinschreibung des Flat-Schema-Stammknotens 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 der XML-Antwort in Kleinbuchstaben zurück. Wenn Studio ein Flat-Schema aus der Abfrage generiert, wird der Stammknotenname in Großbuchstaben erstellt. Die Abweichung bei der Groß-/Kleinschreibung zwischen dem Schemastammknoten (Großbuchstaben) und dem XML-Antwortstammknoten (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 Abweichung bei der Groß-/Kleinschreibung 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, stellt beide Felder bereit.
Mögliche Ursache: Externe Stages sind schreibgeschützte Verweise auf Dateien, die bereits in externem 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 Dateiinhalte aus dem Vorgang übertragen müssen, konfigurieren Sie die Merge-Aktivität für die Verwendung einer internen Stage. Das Schema stellt dann stageName und fileContent bereit.

Snowflake Insert oder Merge: SQL-Syntaxfehler durch Sonderzeichen

Symptom: Eine Snowflake-Aktivität Insert oder Merge schlägt mit einem SQL-Kompilierungsfehler fehl, z. B.:
```
SQL compilation error:
syntax error line 1 at position <n> unexpected '<token>'.
```
Spaltenwerte können auch falsch zugeordnet werden, wobei Daten aus einem Feld in der falschen Spalte erscheinen.
Mögliche Ursachen:
- Feldwerte mit einfachen Anführungszeichen (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 mit einfachen Anführungszeichen: Aktivieren Sie in den Optionalen Einstellungen der Snowflake-Verbindung die Option Sonderzeichen maskieren. Dies maskiert automatisch einfache Anführungszeichen in Insert- und Invoke Stored Procedure-Aktivitätsnutzlasten. Verwenden Sie für Merge-Aktivitäten oder als Alternative für Insert SQLEscape in der Transformationszuordnung, um einfache Anführungszeichen in betroffenen Feldwerten zu 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: "Keine WSDL mit Locator"

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

SOAP WSDL: schemaLocation muss relative Verweise verwenden

Symptom: Eine SOAP-Verbindung, die auf eine WSDL mit importierten XSD-Schemadateien verweist, kann nicht geladen werden oder 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 nicht von absoluten Remote-URLs abrufen, wenn eine lokal importierte WSDL geladen wird.
Lösung:
1. Bearbeiten Sie die WSDL so, dass alle schemaLocation-Verweise relative Pfade verwenden (z. B. schema.xsd statt http://example.com/schema.xsd).
2. Platzieren Sie alle referenzierten XSD-Dateien im selben Verzeichnis wie die WSDL und importieren Sie die WSDL erneut in die SOAP-Verbindung.

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

Symptom: Die vom SOAP-Activity erzeugte XML-Envelope stimmt nicht mit den literalen Namespace-Präfixen oder der Struktur der Quell-WSDL überein (beispielsweise ersetzt der Connector xmlns:ns1 durch xmlns:glob). Strikte SOAP-Services, die den exakten 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, umgehen Sie den SOAP-Connector und erstellen Sie die Request-Payload als String:
1. Erstellen Sie eine HTTP v2-Verbindung, die auf die SOAP-Service-URL verweist.
2. Erstellen Sie in einer Transformation die SOAP-Envelope als String, indem Sie String-Literale und zugeordnete Werte mit dem +-Operator verketten. Alternativ lesen Sie eine Vorlage aus einer Datei und ersetzen Sie dynamische Werte mit Replace.
3. Verwenden Sie im HTTP v2 POST-Activity das Standard-Request-Schema (laden Sie kein benutzerdefiniertes Request-Schema hoch) und ordnen Sie die konstruierte SOAP-Envelope-String dem body-Feld dieses Schemas zu. Der Connector sendet den body-Wert unverändert und bewahrt das literale XML.
4. Setzen Sie den Content-Type-Header auf text/xml oder application/soap+xml und setzen Sie den SOAPAction-Header, falls der Service dies erfordert.
5. Lesen Sie die Antwort des Service aus dem responseContent-Feld des Standard-Response-Schemas des Activity.

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

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

VTEX: 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: Der VTEX-Benutzer oder der Anwendungsschlüssel, der der Verbindung zugeordnet ist, verfügt über eine oder mehrere Berechtigungen nicht, 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 mit dem Workday-Connector, der mit WSDL-Version 42.0 oder 42.1 konfiguriert ist, 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 später für Operationen, die die Services Human_Resources oder Resource_Management verwenden.
2. Testen Sie die Verbindung und führen Sie die betroffenen Operationen erneut aus, um zu bestätigen, dass das Problem behoben ist.

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

Symptom: Ein Workday-Verbindungstest schlägt mit 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/). Den korrekten Wert können Sie 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 erfordert einen nativen Connector als Quelle

Symptom: Ein Vorgang mit aktiviertem Chunking sendet alle Datensätze in einem einzigen Batch an das Ziel, anstatt die konfigurierte Chunk-Größe zu beachten. 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 nur beachtet, wenn die Quelle ein nativer Connector ist. Vorgänge mit nativen Quellen wie HTTP, Database, Variable und Local Storage beachten Chunking normalerweise.
Lösung:
- Falls Chunking nicht erforderlich ist, deaktivieren Sie es in den Vorgangsoptionen.
- Falls Chunking erforderlich ist, teilen Sie den Vorgang in zwei auf:
  - Im ersten Vorgang lesen Sie aus der ursprünglichen 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 nativ ist, funktioniert Chunking in diesem Vorgang korrekt. Die Schritte zur Chunking-Konfiguration 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 Agents.
Lösung:
- Falls die Jitterbit-Services nicht ausgeführt werden, starten Sie diese:
  - Windows: Siehe Windows-Agent starten.
  - Linux: Siehe Linux-Agent starten.
  Falls der Service nicht startet, überprüfen Sie folgende Speicherorte auf Fehlermeldungen:
  - Windows: C:\Program Files (x86)\Jitterbit Agent\log und das Windows-Protokoll Event Viewer Application.
  - Linux: /opt/jitterbit/log.
  Das Konto, das Jitterbit-Services ausführt, benötigt lokale Administratorrechte unter Windows und vollständigen Zugriff auf das Jitterbit-Installationsverzeichnis.
- Falls die Services ausgeführt werden, aber die Harmony Cloud nicht erreichen können, überprüfen Sie folgende Punkte:
  - Die Internetverbindung vom Agent-Host funktioniert.
  - Das Agent-Protokoll (jitterbit-agent.log) enthält keine Fehlermeldungen zur Cloud-Konnektivität.
  - Der Agent kann das Harmony-Portal auf Port 443 erreichen.
- Falls der Agent sich über einen Unternehmens-Proxy verbindet, überprüfen Sie, dass der Proxy korrekt für den Agent konfiguriert ist, einschließlich der NTLM-Domäne, falls der Proxy NTLM-Authentifizierung verwendet. Siehe Proxy-Server für private Jitterbit-Agenten. Das Ablehnungsprotokoll des Proxy-Servers ist hilfreich zur Diagnose, was der Proxy blockiert.
- Falls die Services des Agents auf dem Host fehlerfrei sind (jitterbit status zeigt alle Services als ausgeführt an), der Agent aber wiederholt zu Unknown wechselt oder zwischen Running, Unknown und Stopped wechselt, wird die Verbindung oder der Prozess des Agents wahrscheinlich zwischen den Heartbeats unterbrochen. Überprüfen Sie folgende mögliche Ursachen:
  - Ein Netzwerkgerät (Firewall, NAT-Gateway oder Cloud-VM-Idle-Timeout) kann die ausgehende Verbindung des Agents zwischen den Heartbeats schließen. Versuchen Sie, das Heartbeat-Intervall des Agents (agent.heart.beat.interval) zu reduzieren. Für Cloud-gehostete Agenten siehe Azure VM: Verlorene Verbindungen und WebSocket-/E-A-Fehler, was auch für andere eingeschränkte Netzwerke wie AWS gilt.
  - Der Agent kann unter Speicherdruck abgestürzt sein. Überprüfen Sie auf OutOfMemoryError- oder hs_err_pid-Crash-Dump-Dateien. Siehe Java-Heap-Speicher: OutOfMemoryError.
  - Falls Agenten kürzlich zu einem neuen Betriebssystem migriert wurden und dabei eine Agent-Gruppe wiederverwendet wurde, die zuvor Agenten auf dem alten Betriebssystem gehostet hat, kann die wiederverwendete Gruppe die Ursache sein. Siehe Agent zeigt Unknown oder Stopped nach Wiederverwendung einer Agent-Gruppe über Betriebssysteme hinweg.

Agent zeigt unterschiedliche Versionen oder IP-Adressen an

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

Agent-Synchronisierungsfehler: Projektänderungen werden nicht angewendet

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

Fehler 1722 bei Windows-Installation

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

PostgreSQL-Dienst nach fehlgeschlagenem Upgrade unter Windows entfernt

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

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

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

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

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

Linux-Installation ohne Root-Berechtigung schlägt fehl

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

JDBC-Treiber: „Kein geeigneter Treiber gefunden"

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

Java-Heap-Speicher: `OutOfMemoryError`

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

Speicherplatz und Protokollakkumulation

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

`TranDb`-Verbindungsfehler

Symptom: Operationen schlagen mit Fehlern fehl, die auf die interne PostgreSQL-Datenbank des privaten Agenten verweisen, oder interne Agent-Services können nicht gestartet werden, da das Verbindungslimit erreicht wurde. Wiederholte Fehler können auch ProcessEngine.log überfluten und es auf mehrere GB anwachsen lassen:
```
Failed to connect to back-end database 'TranDb'
```
```
FATAL: query_wait_timeout
```
```
FATAL: remaining connection slots are reserved for non-replication superuser connections
```
Mögliche Ursachen:
- Das Limit max_connections der internen PostgreSQL oder das Limit max_db_connections von PgBouncer ist für die Workload des Agenten zu niedrig.
- Operationen stauen sich unter hoher Last oder aufgrund einer Netzwerk- oder Endpoint-Verlangsamung auf und halten Datenbankverbindungen, bis der PgBouncer-Pool erschöpft ist (query_wait_timeout).
- Bei einem Windows-Agent beeinträchtigt IP Helper die lokalen Datenbankverbindungen des Agenten.

PostgreSQL: Schnelles administratives Herunterfahren

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

Fehler beim Zertifikat-Handshake (TLS)

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

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

SSLHandshakeException: Received fatal alert: protocol_version

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

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

FTP: Datenverbindung hat das Zeitlimit überschritten

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

IPv6-Problem unter Windows

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

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

attachment

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

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

Apache: Keine installierten `ConfigArgs`

Symptom: Der Agent gibt folgende Meldung zurück:

No Installed ConfigArgs for the Service "Jitterbit Apache Server"

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

Apache/Tomcat: `APPARENT DEADLOCK`

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

Apache stürzt unter gleichzeitiger Last unerwartet ab

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

Cleanup-Dienst kann gesperrte Protokolldateien unter Windows nicht entfernen

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

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

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

Agent kann nach der Abmeldung nicht mit Authentifizierungsfehlern neu gestartet werden

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

Hinweis

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

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

Änderung der Cloud-Protokollierung erfordert Neustart des privaten Agents

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

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

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

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

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

Privater Agent kann nicht gelöscht werden

Symptom: Der Versuch, einen privaten 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. Agenten 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 Agenten.
2. Stoppen Sie den Agent und warten Sie, bis sich sein Status ändert, bevor Sie das Löschen 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 das Löschen erneut.

Automatisches Connector-Update deaktivieren wird durch Agent-Aktionen umgangen

Symptom: Connectors werden auf privaten Agenten aktualisiert, obwohl Disable Auto Connector Update in Organisationsrichtlinien aktiviert ist.
Ursache: Die Organisationsrichtlinie Disable Auto Connector Update verhindert, dass private Agenten bereits installierte Connectors automatisch auf neuere Versionen aktualisieren (beispielsweise lädt die Schaltfläche Test einer Verbindung nicht mehr die neueste Connector-Version herunter). Sie 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 Management Console Agents 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 privater Agents auf ein anderes Betriebssystem (z. B. Windows zu Linux) bei Wiederverwendung derselben Agent-Gruppe zeigen die migrierten Agents auf der Registerkarte Privat der Seite Agents der Management Console zeitweise als Unbekannt oder Beendet an, obwohl jitterbit status zeigt, dass die Services ausgeführt werden und Operationen normal ausgeführt werden.
Mögliche Ursache: Die Wiederverwendung einer Agent-Gruppe aus dem vorherigen Betriebssystem kann Metadaten hinterlassen, die die Statusberichterstellung für die neuen Agents beeinträchtigen. Der Effekt ist typischerweise kosmetisch: Services und Operationen werden weiterhin normal ausgeführt.
Lösung: Erstellen Sie stattdessen eine neue, saubere Agent-Gruppe für die migrierten Agents, anstatt die Gruppe aus dem vorherigen Betriebssystem wiederzuverwenden, und registrieren Sie die Agents dort.

Operationen verzögert oder in der Warteschlange nach Projektbereitstellung

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

Agent zeigt sich als nicht fähig an

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

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

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

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

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

Fehlerhafte Windows-Installation wiederherstellen

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

Connector nicht auf Agent heruntergeladen

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

Hinweis

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

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

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

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

Operationen 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 von API Manager-APIs ausgelöste Vorgänge die Timeout-Einstellungen für Studio-Vorgänge. Die Einstellung EnableAPITimeout in jitterbit.conf muss explizit aktiviert werden, damit API-Vorgänge Timeout-Werte berücksichtigen.
- Es ist keine maximale Laufzeit für Vorgänge festgelegt, daher werden Vorgänge ohne zeitliche Obergrenze ausgeführt.
Lösung:
1. Um Timeout-Einstellungen für API-gesteuerte Vorgänge zu erzwingen, setzen Sie EnableAPITimeout=true im Abschnitt [Settings] von jitterbit.conf.
2. Um die Gesamtlaufzeit eines Vorgangs zu begrenzen, setzen Sie MaxOperationRuntimeSeconds im Abschnitt [ProcessEngine] von jitterbit.conf. Dies erfordert, dass RunOperationsInSeparateProcess auf true (Standard) gesetzt ist.
3. Starten Sie die Agent-Dienste nach Änderungen an jitterbit.conf neu.

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

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

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

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

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

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

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

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

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

Salesforce-Sandbox-Verbindung schlägt mit Zertifikatkonflikt fehl

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

Lösung:

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

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

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

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

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

SSH: SFTP-Verbindung schlägt aufgrund eines falschen 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 nach einem Agent-Upgrade oder -Neustart mit einem Fehler für eine leere private Schlüsseldatei fehl. SSH-Schlüssel-Einstellungen, die zur lokalen jitterbit.conf hinzugefügt wurden, funktionieren möglicherweise auch nach dem Neustart des Agenten nicht mehr.
```
CURL_DEBUG_TEXT: Using SSH private key file ''
CURL_DEBUG_TEXT: SSH public key authentication failed: Unable to extract public key from private key file
```
Mögliche Ursachen:
- Die Remote-Agent-Konfiguration ist aktiviert (standardmäßig der Fall), daher haben Einstellungen, die über die Registerkarte Jitterbit Configuration der Management Console verwaltet werden, Vorrang. SSH-Schlüssel-Einstellungen, die nur zur lokalen jitterbit.conf hinzugefügt wurden, funktionieren möglicherweise nicht oder werden nach dem Neustart des Agenten nicht beibehalten.
- Die SSH-Schlüssel-Einstellungen (PrivateKeyFile, PrivateKeyPassphrase, PublicKeyFile) befinden sich im falschen Abschnitt. Neuere Agent-Versionen analysieren streng und ignorieren SSH-Einstellungen, die außerhalb des Abschnitts [SSH] platziert sind (z. B. unter [SSL]).
Lösung:
1. Wenn die Remote-Konfiguration aktiviert ist, fügen Sie die SSH-Schlüssel-Einstellungen dort hinzu: Öffnen Sie die Schublade Agent group details für die Agent-Gruppe, wählen Sie die Registerkarte Jitterbit Configuration aus, und fügen Sie sie unter dem Abschnitt SSH hinzu. Siehe Jitterbit configuration.
2. Wenn die lokale jitterbit.conf die Konfigurationsquelle ist, bestätigen Sie, dass die SSH-Schlüssel-Einstellungen unter [SSH] platziert sind (nicht [SSL]).
3. Starten Sie die Agent-Services neu.
4. Weitere Informationen zur Fehlerbehebung bei SFTP-Schlüsselauthentifizierung (Passwortfelder, Passphrase, Schlüsselformat) finden Sie unter SFTP "Login denied. Authentication failure." 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 gleichen Agent (mit dem gleichen Schlüssel) sind erfolgreich, und die Verbindung zum fehlgeschlagenen Server über die Befehlszeile des Betriebssystems ist ebenfalls erfolgreich.
```
Failed to get ftp directory list for url sftp://... Login denied. Authentication failure.
```
Ursache: Der SFTP-Server erfordert neuere SSH-Cipher, Key-Exchange- oder Host-Key-Algorithmen, die die cURL-Bibliothek in älteren Agent-Versionen nicht unterstützt. Server, die die älteren Algorithmen noch akzeptieren, funktionieren weiterhin, weshalb der gleiche Schlüssel bei anderen Hosts und über die Befehlszeile des Betriebssystems erfolgreich ist.
Lösung: Aktualisieren Sie den privaten Agent auf Version 11.37 oder später, die eine aktualisierte cURL-Bibliothek mit Unterstützung für aktuelle SSH-Cipher, Key-Exchange- und Host-Key-Algorithmen enthält.

HTTPS-Proxy: 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 die Basis-Authentifizierung während HTTPS-Proxy-Tunneling standardmäßig. Die JVM-Eigenschaft jdk.http.auth.tunneling.disabledSchemes blockiert die Basis-Authentifizierung, sofern sie nicht explizit gelöscht wird.
Lösung: Fügen Sie -Djdk.http.auth.tunneling.disabledSchemes="" zu CATALINA_OPTS hinzu, bevor Sie Tomcat starten. Schritt-für-Schritt-Anweisungen für Windows, Linux und Docker finden Sie unter 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 in der Lage sein, das Gateway zu erreichen (direkt oder über seinen Load Balancer in einer Multi-Gateway-Bereitstellung).
Lösung:
- Öffnen Sie ausgehende HTTPS (Port 443) vom Agent-Host zu den Harmony-Region-URLs. Die Verbindung wird auf WSS (sicheres WebSocket) für die laufende bidirektionale Kommunikation aktualisiert. Auf dem Agent-Host müssen keine eingehenden Ports für Harmony oder das Gateway geöffnet werden.
- Konfigurieren Sie beim Einrichten der Firewall die regionsspezifischen Jitterbit-Services, die unter Ausgehende Kommunikation aufgelistet sind, auf die Allowlist. Dies ist der Abschnitt, der für einen privaten Agent hinter einer Firewall gilt.
- Falls der Agent für die Verwendung von nicht standardmäßigen (benutzerdefinierten) Ports konfiguriert wurde, lassen Sie diese auch durch die Unternehmens-Firewall zu. Siehe Netzwerk-Ports.
- Falls ein privates API-Gateway bereitgestellt wird, lassen Sie auch ausgehende Konnektivität von jedem Agent-Host zum Gateway zu (direkt oder über seinen Load Balancer bei einer Multi-Gateway-Bereitstellung). Der Agent verbindet sich mit dem Gateway, um die API-Antwort-Payload zurückzugeben. Den vollständigen Request-Flow finden Sie unter Systemarchitektur des privaten API-Gateways.

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

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

Native Observability zeigt keine Daten an

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

Agent-Metriken fehlen, wenn 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 Metriken Harmony nicht erreichen, obwohl sich der Agent selbst erfolgreich verbindet.
Lösung:
1. Bestätigen Sie, dass der Proxy HTTPS unterstützt. Agent-Metriken werden über HTTPS übermittelt, daher blockiert ein Proxy, der nur HTTP-Traffic verarbeitet, diese. Das Aktivieren von HTTPS auf dem Proxy behebt das Problem.
2. Wenn Sie HTTPS auf dem Proxy nicht aktivieren können oder Metriken nach dem Aktivieren weiterhin fehlen, benötigt der Metrics-Traffic des Agents eine eigene Proxy-Konfiguration, getrennt von der des Agents. Kontaktieren Sie den Jitterbit-Support, um dies einzurichten.

Datadog-Agent startet nach Docker-Installation nicht

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-Services starten nach einem Neustart nicht („postmaster.pid existiert nicht")

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

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

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

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

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

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

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

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

Listening-Service-Nachrichten nicht zugestellt

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

Custom-API-Operationsprotokolle werden nicht angezeigt

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

Operationsdebug-Protokollierung endet vor dem ausgewählten Enddatum

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

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

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

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.
Lösung: Überprüfe das Verbose Log Shipper-Serviceprotokoll auf dem Agent:
```
<JITTERBIT_HOME>/VerboseLogShipper/verbose-log-shipper.out.log
```
Wenn das Protokoll Fehler anzeigt, starte den Verbose Log Shipper-Service neu. Unter Linux kann dies ohne einen vollständigen Agent-Neustart durchgeführt werden:
```
jitterbit stop verboselogshipper
jitterbit start verboselogshipper
```
Unter Windows und Linux werden beim Neustart aller Jitterbit-Agent-Dienste auch die Verbose Log Shipper-Dienste neu gestartet.

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

Symptom: Nachrichten in einer Quorum-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 ihr konfiguriertes 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-Zulassungsliste für Ihren Netzwerk-Proxy oder Web-Filter enthält nicht die erforderlichen Jitterbit-Adressen. Siehe Zulassungslisten-Informationen.
Lösung: Vollständige Lösungsschritte, einschließlich Anweisungen zum Hinzufügen von Zertifikaten zum Jitterbit Java KeyStore, finden Sie unter SSL-Zertifikat oder Proxy-Filterkonfigurationsfehler.

Design Studio auf macOS Sequoia als Malware gekennzeichnet

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

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

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

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

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

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

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

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

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

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

oder:

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

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

Design Studio: Projektkomponenten 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 Projektexport-Datei .json kann nicht importiert werden. Die Ursache ist normalerweise eine einzelne beschädigte Komponente im Projektexport, die das Parsing der gesamten Datei unterbricht.
Mögliche Ursache: Eine Komponente im Projektexport hat fehlerhaftes JSON, z. B. einen leeren Body oder ungewöhnliche Zeichen, die die Datei ungültig machen.
Lösung:
1. Exportieren Sie das Projekt aus dem Harmony-Portal, um eine .json-Datei zu erstellen.
2. Öffnen Sie die .json-Datei in einem Texteditor und überprüfen Sie das components-Array auf Einträge, die leer, fehlerhaft oder ungewöhnliche Zeichen enthalten.
3. Entfernen Sie das vollständige JSON-Objekt der verdächtigen Komponente aus dem components-Array.
4. Speichern Sie die Datei und importieren Sie sie zurück in Harmony.
5. Wenn die Beschädigung nicht identifizierbar ist, senden Sie den Projektexport an den Jitterbit-Support zur Analyse.

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

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

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

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

Design Studio: SOAP-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 einer Operation, bei der ein SOAP-Fehler direkt eine E-Mail auslöst, kann einen Fehler verursachen.
Lösung:
1. Konfigurieren Sie den SOAP-Fehler so, dass stattdessen eine Operation ausgelöst wird.
2. Verwenden Sie in dieser Operation die Funktion SendEmailMessage in einem Skript, um die Benachrichtigungs-E-Mail zu senden.

Design Studio: Dateiübertragungen wiederholen sich unerwartet

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

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

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

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

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

Design Studio: FTP-Verzeichnisauflistung kann nicht analysiert werden

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

Design Studio: FTP-Ziel „Use FTP Rename" funktioniert nicht mit SFTP-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 erreichbar und gibt Daten zurück, wenn er direkt in einem Browser oder API-Client aufgerufen wird.
Mögliche Ursache: Die Schaltfläche Test Connection in der HTTP-Quellenkonfiguration sendet eine HTTP HEAD-Anfrage. Einige Server unterstützen die HEAD-Methode nicht und geben einen Fehler 405 oder ähnliches zurück, obwohl GET- und POST-Anfragen erfolgreich sind.
Lösung:
1. Wenn der Endpunkt in einem Browser oder über eine direkte GET-/POST-Anfrage erreichbar ist, kann der fehlgeschlagene Verbindungstest ignoriert werden. Fahren Sie mit der Bereitstellung und Ausführung des Vorgangs fort, um die tatsächliche Konnektivität zu überprüfen.
2. Wenn der Vorgang auch zur Laufzeit fehlschlägt, untersuchen Sie das Problem weiter mithilfe der Vorgangsprotokolle.

Design Studio: NetSuite-Rechenzentrum-URL-Fehler, verwenden Sie 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-Benutzer mit TFA 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 unterberechtigten Rolle, aber die Berechtigungsprüfungen zur Laufzeit schlagen fehl.
Lösung:
1. Wechseln Sie in NetSuite zu einer Rolle mit vollständigem Zugriff oder Administrator-Rolle, wenn Sie die Zugriffstokens generieren, oder fügen Sie der aktuellen Rolle die erforderlichen Berechtigungen hinzu.
2. Generieren Sie die Zugriffstokens mit der aktualisierten Rolle neu und konfigurieren Sie den NetSuite-Endpunkt neu.

Design Studio: NetSuite Dropdown für gespeicherte Suchen ist leer, wenn das Objekt mehr als 1.000 gespeicherte Suchen hat

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

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

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

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

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

Design Studio: Salesforce OAuth 2.0 Verbindungsbearbeitungen werden nicht in Salesforce-Anmeldung testen berücksichtigt

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

Design Studio: SAP IDocs werden nicht gefunden, wenn eine geplante Operation auf einem anderen Agent ausgeführt wird

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

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

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

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

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

Design Studio: Temporäre Dateien für SAP IDoc Store-and-Forward werden nach 24 Stunden gelöscht

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

Design Studio: SAP BAPI Operation erfolgreich, aber Transaktion wird nicht committed

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

Design Studio: SAP Event Listener nimmt iDocs unter Windows nicht auf

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

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

API-Verwaltung

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

API kann nicht veröffentlicht werden: Limit für Abonnement-APIs erreicht

Symptom: Das Erstellen oder Veröffentlichen einer API schlägt mit einer Fehlermeldung wie dieser fehl:
```
You have reached Maximum no of API Service configured for your Jitterbit organization
```
Ursache: Die Organisation hat die maximale Anzahl veröffentlichter API-URLs erreicht, die das Abonnement zulässt. Jede veröffentlichte benutzerdefinierte API, jeder OData-Service oder 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-Managers die Anzahl der verwendeten Custom-API-URLs und verwendeten Proxy-API-URLs, die oben auf der Seite angezeigt werden, gegen die von Ihrem Abonnement zulässigen Gesamtzahlen. 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 der Abonnementstufe 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 (z. B. nach einer Abonnementänderung), stellen Sie es auf den beabsichtigten Wert wieder her.
- Überprüfen Sie auf der Seite APIs, 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 nach dem Timeout-Fenster des Gateways auf (30 bis 180 Sekunden, abhängig von der Timeout-Einstellung der API).
Mögliche Ursachen:
- Die API-URL ist fehlerhaft, oder Pfadparameter werden nicht korrekt verarbeitet, was dazu führt, dass das Gateway beim Routing der Anfrage fehlschlägt.
- Der Backend-Betrieb oder der externe Service antwortet zu langsam 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 vollständig ausgelastet ist oder unter hoher Last steht, sodass ein Timeout am Gateway auftritt, bevor der Betrieb ausgeführt wird. Ein Zeichen für diesen Fall ist, dass die fehlgeschlagene Anfrage keinen entsprechenden Eintrag in den Betriebsprotokollen hat.
Lösung:
- Überprüfe, dass die API-URL korrekt formatiert ist. Wenn die API Pfadparameter verwendet, erwäge das Hinzufügen eines Skripts zum Betrieb, das die URL explizit analysiert und die Parameterwerte erfasst.
- Wenn das Timeout durch ein langsames Backend verursacht wird, überprüfe den Betrieb und seine Transformationslogik auf Leistungsengpässe, insbesondere große Datenmengen oder langsame externe Aufrufe, und reduziere den langsamen Schritt.
- Wenn der Betrieb wirklich mehr Zeit benötigt als die aktuelle Einstellung zulässt, erhöhe das Timeout auf der Registerkarte „API-Einstellungen". Das API-Timeout (Standard 30 Sekunden, Maximum 180 Sekunden) ist unabhängig vom Studio-Betriebstimeout; das Betriebstimeout wird nur auf privaten Agents verwendet, wenn die Einstellung EnableAPITimeout in der Agent-Konfiguration aktiviert ist.
- Wenn der Betrieb nicht innerhalb des maximalen Timeouts abgeschlossen werden kann oder eine Echtzeitantwort nicht erforderlich ist, gestalte den Betrieb der API 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 Betriebe verwalten.
- Bei zeitweiligen Timeouts füge Wiederholungen hinzu, damit ein vorübergehender Fehler erneut versucht wird: Verwende die integrierten Wiederholungseinstellungen der HTTP v2-Verbindung für ausgehende Aufrufe oder eine skriptgesteuerte RunOperation-Wiederholungsschleife mit einer Verzögerung zwischen den Versuchen.
- Wenn Timeouts mit der Agent-Last korrelieren, überprüfe die Agent-Kapazität: Führe API-Betriebe auf Agents aus, die von schweren ETL-Workloads getrennt sind, und füge Agents zur Gruppe hinzu, wenn diese überlastet ist. Siehe Optimiere und verbessere die Leistung von Jitterbit-Private-Agents.

API Portal spiegelt Projektänderungen nicht wider

Symptom: Das API Portal zeigt veraltete Projektnamen oder Attribute an, nachdem ein Projekt umbenannt oder aktualisiert wurde.
Mögliche Ursache: Das API Portal wurde nach der Projektänderung nicht automatisch synchronisiert.
Lösung:
1. Um alle benutzerdefinierten und Proxy-APIs in der Umgebung zu aktualisieren, öffnen Sie den Portal Manager und klicken Sie auf Regenerate Docs. Um eine einzelne API zu aktualisieren, öffnen Sie deren Registerkarte Documentation auf der Seite APIs und klicken Sie auf Save & Publish.
2. Überprüfen Sie, dass die aktualisierten Informationen korrekt 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 Antwort-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-Redirect-URI falsch konstruiert wird, was keiner der in der Azure-App-Registrierung registrierten Antwort-URLs entspricht.
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 dem Redirect-URI entsprechen, 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 Zielgruppe überein. Dies deutet normalerweise darauf hin, dass der Application ID URI in der Azure-App-Registrierung falsch konfiguriert ist oder der OAuth-Bereich, den der Client anfordert, nicht mit dem registrierten URI übereinstimmt.
Lösung:
1. Öffnen Sie im Azure-Portal die App-Registrierung, die diesem Sicherheitsprofil zugewiesen ist, und navigieren Sie zu API verfügbar machen.
2. Bestätigen Sie, dass der Application ID URI auf einen gültigen URI im Format api://<Application (client) ID> gesetzt ist.
3. Bestätigen Sie im Sicherheitsprofil, dass der OAuth-Bereich auf api://<Application (client) ID>/.default gesetzt ist.
4. Aktualisieren Sie die Clientanwendung, um ein Token mit diesem genauen Bereich anzufordern.
5. Wenn die Validierung nach Korrektur der Zielgruppe und des Bereichs weiterhin fehlschlägt, öffnen Sie das Manifest der App-Registrierung und bestätigen Sie, dass requestedAccessTokenVersion auf 2 gesetzt ist. Ein fehlender oder anderer Wert kann ebenfalls zu Fehlern bei der Token-Validierung führen.

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 Identitätsanbieter: 2-legged OAuth wird nicht unterstützt

Symptom: Ein API-Sicherheitsprofil, das mit Google oder Salesforce als OAuth 2.0 Identity Provider konfiguriert ist, schlägt fehl, wenn es für 2-legged OAuth konfiguriert wird.
Mögliche Ursache: OAuth 2.0 API-Sicherheitsprofile von Google und Salesforce 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 Identity Provider 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 erneut in Microsoft Copilot Studio. Siehe Verbinden Sie einen Jitterbit AI-Agent mit Microsoft Copilot Studio.

Schaltfläche „New 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.

`INVALID_TRIGGER_USER` oder `TRIGGER_USER_TOO_LONG` Fehler

Symptom: Ein API-Aufruf mit einem Sicherheitsprofil mit Basic Authentication oder einer Custom-Logging-Einstellung schlägt mit einem Fehler INVALID_TRIGGER_USER oder TRIGGER_USER_TOO_LONG fehl, obwohl die gleichen Anmeldedaten oder der Header-Wert zuvor funktioniert haben.
Mögliche Ursache: Der Wert, der zur Identifizierung des Aufrufers der Anfrage verwendet wird, verstößt gegen eine Validierungsregel: Er enthält ein nicht zulässiges Zeichen (INVALID_TRIGGER_USER) oder überschreitet 256 Zeichen (TRIGGER_USER_TOO_LONG).
- Bei Basic Authentication mit der Standard-Logging-Einstellung ist dieser Wert das Feld User name des Sicherheitsprofils.
- Bei einer Custom-Logging-Einstellung ist es der Wert, den die aufrufende Anwendung im konfigurierten Header sendet.
Die Zeichenvalidierung wurde in der 12.10 Harmony-Version hinzugefügt, und das Längenlimit wurde in der 12.11 Harmony-Version hinzugefügt. Ein privates API Gateway, das eine frühere Version ausführt, erzwingt die entsprechende Validierung nicht, daher können beide Fehler zum ersten Mal nach dem Upgrade des Gateways angezeigt werden, obwohl sich die Konfiguration des Sicherheitsprofils nicht geändert hat.

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

Symptom: API-Aufrufe geben 401 Unauthorized zurück, obwohl die Client-IP korrekt in den vertrauenswürdigen IP-Gruppen des Sicherheitsprofils aufgeführt ist.
Mögliche Ursache: Ein veralteter Cache von Legacy-IP-Bereichseinträgen im Sicherheitsprofil setzt die aktiven vertrauenswürdigen IP-Gruppen außer Kraft.
Lösung: Migrieren Sie das Sicherheitsprofil von Legacy-IP-Bereichen zum Modell Vertrauenswürdige IP-Gruppen, dem aktuellen Zulassungsmechanismus: Definieren Sie die IPs als vertrauenswürdige IP-Gruppe und weisen Sie sie dem Profil zu. Das Deaktivieren der Einstellung Anfragen nur von den folgenden IP-Bereichen vertrauen 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 auszuschalten, um den Cache zu löschen.

Salesforce on Hyperforce: Aufrufe an eine API werden abgelehnt, nachdem sich Salesforce-IP-Adressen ändern

Symptom: Aufrufe von Salesforce an eine API (ausgehende Nachrichten, Apex-Aufrufe, Salesforce Connect oder aufrufbare Aktionen) werden abgelehnt, nachdem die Salesforce-Organisation zu Hyperforce, Salesforces öffentlicher Cloud-Infrastruktur, migriert wird. Das Sicherheitsprofil der API hat Anfragen nur von den folgenden IP-Bereichen vertrauen aktiviert mit einer vertrauenswürdigen IP-Gruppe, die Salesforce-IP-Adressen auflistet.
Mögliche Ursache: Vertrauenswürdige IP-Gruppen gleichen die Quell-IP-Adresse einer Anfrage ab, und die Adressen, die eine Salesforce-Organisation auf Hyperforce für ausgehende Aufrufe verwendet, ändern sich im Laufe der Zeit. Eine Gruppe, die einen festen Satz von Salesforce-Adressen auflistet, stimmt nicht mehr überein.
Lösung: Salesforce empfiehlt, ausgehende Aufrufe in Ihr Netzwerk zu authentifizieren, anstatt ihre Quell-IP-Adressen in die Zulassungsliste aufzunehmen:
1. Öffnen Sie das Sicherheitsprofil, das der API zugewiesen ist, und setzen Sie seinen Authentifizierungstyp auf API-Schlüssel. Konfigurieren Sie den Salesforce-Aufruf so, dass der Schlüssel in einem Request-Header gesendet wird, nicht in einem Query-Parameter, damit er nicht in Request-URLs aufgezeichnet wird. OAuth 2.0 ist ebenfalls verfügbar, wobei mit Salesforce als Identitätsanbieter der einzige Flow 3-legged ist, der manuelle Interaktion erfordert.
2. Nachdem sich der Aufruf erfolgreich authentifiziert hat, heben Sie die Zuweisung der vertrauenswürdigen IP-Gruppe auf, die die Salesforce-Adressen auflistet, damit spätere Adressänderungen die API nicht mehr beeinflussen. Heben Sie die Zuweisung der Gruppe auf, anstatt Anfragen nur von den folgenden IP-Bereichen vertrauen auszuschalten, was alle noch im Profil vorhandenen Legacy-IP-Bereiche dauerhaft entfernt.
Wenn Ihre Organisation IP-Zulassungslisten benötigt, veröffentlicht Salesforce seine Hyperforce-Bereiche als dynamische Liste unter ip-ranges.salesforce.com/ip-ranges.json und kündigt Ergänzungen im Voraus an. Diese Liste ändert sich jedes Mal, wenn Salesforce seine Adressen ändert, daher bedeutet das Aktualisieren einer Zulassungsliste, die Datei zu verfolgen und die vertrauenswürdige IP-Gruppe entsprechend zu aktualisieren. Aufrufe von einer Adresse, die seit der letzten Aktualisierung der Gruppe hinzugefügt wurde, werden abgelehnt. Diese Adressen werden auch über Salesforce-Organisationen hinweg gemeinsam genutzt, daher bestätigt das Zulassungslisten dieser Adressen, woher eine Anfrage kam, nicht dass sie von Ihrer Organisation kam. Vollständige Anleitung von Salesforce, einschließlich bidirektionales SSL (mTLS), Auth Providers und verbundene Apps, finden Sie unter Retain uninterrupted access to Salesforce services on Hyperforce.

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

Symptom: Das API-Gateway gibt folgende Meldung zurück:
```
414 URI Too Large
```
Mögliche Ursache: Die konstruierte Service-URL (einschließlich Basis-URL, Service-Pfad und aller Pfad- oder Abfrageparameter) überschreitet 8.000 Zeichen.
Lösung:
- 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 der Basis-URL und aller definierten Service-Pfade innerhalb des 8.000-Zeichen-Limits bleibt.

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

Symptom: Das Konfigurieren eines Proxy-API-Service-Pfads mit Pfadparametern (z. B. /resource/{id}) schlägt fehl, wenn er manuell eingegeben wird, da das Feld keine geschweiften Klammern akzeptiert.
Mögliche Ursache: Manuell definierte Service-Pfade in Proxy-APIs unterstützen nicht die Zeichen { und }, die zur Definition von Pfadparametern verwendet werden.
Lösung: Um Pfadparameter in einem Proxy-API-Service-Pfad zu verwenden, stellen Sie ein OpenAPI-Dokument bereit, das die Pfade und ihre Parameter definiert. Der 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 verfügt nicht über die Admin-Berechtigung. Beim Löschen einer API wird zunächst überprüft, welchen API-Gruppen die API zugeordnet ist. Das Anzeigen der Seite API-Gruppen erfordert die Admin-Berechtigung: Eine Rolle mit nur Write-Umgebungszugriff kann die Seite öffnen, aber nicht deren Inhalte lesen. Wenn die Rolle die API-Gruppen nicht lesen kann, erhält diese Überprüfung einen Wert, den die Benutzeroberfläche nicht verarbeiten kann, und das Löschen wird nicht abgeschlossen.
Lösung: Lassen Sie einen Benutzer, dessen Rolle die Admin-Rollenberechtigung hat, das Löschen durchführen. Das Gewähren der Admin-Berechtigung für die betroffene Rolle funktioniert ebenfalls, stellt aber eine umfassende Erhöhung auf Organisationsebene dar. 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 Seite APIs 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 HTTP-Methode OPTIONS Anfragen ohne Authentifizierung.
Mögliche Ursache: Das Aktivieren von CORS führt dazu, dass Operationen mit der Methode OPTIONS 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 unauthentifizierte Preflight-Anfragen explizit erkannt und verarbeitet werden.

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 API, die als Proxy fungiert, über das öffentliche 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 über das öffentliche 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 Proxy-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, verwende eine benutzerdefinierte API, die denselben Endpunkt aufruft, wobei die Einstellung Request & Response Payloads in Logs anzeigen unterstützt wird.

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

Symptom: Anfragen über ein privates API-Gateway schlagen zeitweise 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 der Agent-Gruppe weitere Agents hinzu, um die Last zu verteilen, und bestätigen Sie, dass die Agent-Hosts über ausreichend CPU und Speicher verfügen.
2. Überwachen Sie die Apache-Worker-Thread-Nutzung der Agents. Wenn native Observability aktiviert ist, überprüfen Sie die Diagramme Apache Thread Capability, Apache idle workers und Apache busy workers (siehe Dashboards), um zu bestätigen, ob Threads während der Ausfälle erschöpft sind.
3. Wenn die Agents auch nach dem Skalieren konsistent keine Apache-Worker-Threads mehr haben, kontaktieren Sie den Jitterbit-Support, um die Apache-Worker-Thread-Kapazität der Agents zu überprüfen (die Einstellung MaxRequestWorkers). Ändern Sie die Jitterbit-Apache-Konfigurationsdateien nicht, es sei denn, der Jitterbit-Support weist Sie dazu an. Siehe Apache-Konfigurationsdateien.

Sicherheitsprofiländerungen dauern mehrere Minuten, bis sie wirksam 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 ihre 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 den Dokumentationseintrag der API dort manuell.
- Alternativ können Sie die Registerkarte Documentation für die API vor dem Löschen verwenden, um den Portal-Eintrag zuerst zu entfernen.

Sicherheitsprofil kann nicht gelöscht werden, 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 zugewiesen gilt. Bis die API erneut veröffentlicht wird, behandelt API Manager das Profil weiterhin als in Verwendung.
Lösung:
1. Nachdem das Sicherheitsprofil von der API entfernt wurde, klicken Sie auf Speichern und dann auf Veröffentlichen der 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 auf 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 auf demselben Host sein

Symptom: In einer containerisierten Multi-Gateway-Umgebung hinter einem Application Load Balancer (ALB) schlagen API-Aufrufe zeitweise fehl oder Payloads können nicht abgerufen werden, obwohl 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-Computer ausgeführt werden. Container, die auf verschiedenen Hosts bereitgestellt werden, können die Payload-Abrufung nicht koordinieren, was zu zeitweisen Ausfällen 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 sie 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 dem 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. Nachdem das Upgrade abgeschlossen ist, 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 die Inode-Nutzung überprüfen (df -h und df -i). Geben Sie Speicherplatz frei und führen Sie den Test erneut durch, nur wenn diese wirklich voll sind.
2. 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 zum selben 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 zum Installieren oder Aktualisieren eines Linux-Private-API-Gateways (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: Private API Gateway Version 10.62 und später erfordern 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 Private API Gateway installieren 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 durch.
- 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 auf einem Computer mit Internetzugang diese Pakete und ihre transitiven Abhängigkeiten herunter, übertragen Sie sie auf den Gateway-Host und installieren Sie sie in Abhängigkeitsreihenfolge mit yum install <package.rpm>, bevor Sie die Gateway-Installation erneut durchführen.

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

Symptom: Das Befehlszeilen-Selbsttest-Dienstprogramm des Private API Gateway gibt Folgendes zurück:
```
Failure, test call to API failed
```
Mögliche Ursache: In Private API Gateway Version 11.30 und früher 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.
- Wenn 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 Systemabfrageopionen $count oder $inlinecount gibt einen Fehler statt 0 zurück, wenn keine Datensätze dem Filter entsprechen.
Mögliche Ursache: Ein OData-Service gibt standardmäßig einen Fehler statt 0 zurück, wenn eine $count- oder $inlinecount-Abfrage keine Datensätze findet.
Lösung: Auf privaten Agenten mit Version 11.32 oder später den OData-Parameter $noErrorOnZeroCount in der OData-Service-Konfiguration auf true setzen. Dies führt dazu, dass $count-Abfragen 0 statt eines Fehlers zurückgeben, wenn keine Datensätze übereinstimmen.

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

Symptom: Eine Proxy-API-Operation empfängt Request-Header, bei denen Bindestriche durch Unterstriche ersetzt wurden (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 disable-hyphen-replacement-Einstellung, die steuert, ob Bindestriche in Request-Header-Namen durch Unterstriche ersetzt werden. Bei neuen Proxy-APIs ist diese Einstellung standardmäßig auf true gesetzt (Ersetzung deaktiviert). Ältere Proxy-APIs können auf false gesetzt sein, was die Ersetzung verursacht.
Lösung:
- In der Proxy-API-Konfiguration die disable-hyphen-replacement-Header-Einstellung überprüfen. Um Bindestriche in Header-Namen beizubehalten, sicherstellen, dass die Einstellung auf true gesetzt ist.
- Falls die Proxy-API vor Einführung dieses Standards erstellt wurde und die Ersetzung unerwartet auftritt, die Einstellung auf true aktualisieren und die API erneut veröffentlichen.

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

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

API-Payload auf Agent für 2 Tage verfügbar

Symptom: Ein Workflow, der eine API-Request-Payload mehr als 2 Tage nach dem API-Aufruf vom Agent abruft, kann die Payload nicht finden.
Mögliche Ursache: API-Request-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 (z. B. Temporary Storage, File Share oder eine Datenbank) geschrieben hat.
Lösung:
- Gestalte Operationen, die API-Request-Payloads verarbeiten, so, dass sie die Daten sofort nach dem API-Aufruf verarbeiten, anstatt den Payload-Abruf zu verschieben.
- Wenn die Payload für eine längere Verarbeitung beibehalten werden muss, schreibe sie in der ursprünglichen API-ausgelösten Operation an einen persistenten Speicherort.

API-Protokolle behalten vorherige Filterauswahl

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

Unveröffentlichte APIs werden nicht in der Analytics-APIs-Dropdown angezeigt

Symptom: Eine API wird nicht in der Dropdown 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 APIs angezeigt. APIs, die unveröffentlicht wurden, werden aus der Dropdown ausgeschlossen, auch wenn API-Protokolle für diese APIs vorhanden sind.
Lösung:
- Bestätige, 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, verwende stattdessen die Seite API Logs. Protokolldaten bleiben dort verfügbar, können aber nicht nach API-Name gefiltert werden.

Fehler 429: Monatliches API-Hit-Limit ü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üfe die aktuelle Hit-Anzahl gegen dein monatliches Kontingent auf der Seite APIs. Das Kontingent wird am ersten Tag des folgenden Monats zurückgesetzt.
- Um zu vermeiden, dass das Limit erreicht wird, konfiguriere 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 deiner Organisation zu erhöhen, kontaktiere deinen Customer Success Manager.

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

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

Plattformweites Ratenlimit: 200 Anfragen pro Minute

Symptom: APIs, die auf dem von Jitterbit verwalteten Cloud-API-Gateway gehostet werden, werden bei hohem Datenverkehr gedrosselt oder mit einer 429 Too Many Requests-Antwort abgelehnt, auch wenn die Rate Limits des Sicherheitsprofils nicht erreicht wurden.
Mögliche Ursache: Das von Jitterbit verwaltete Cloud-API-Gateway erzwingt ein plattformweites Limit von 200 API-Anfragen pro Minute pro Organisation, das über alle API-Typen (Custom, Proxy und OData) hinweg gemeinsam genutzt wird. Dieses Limit gilt nicht für private API-Gateways.
Lösung:
- Überprüfen Sie Ihre API-Verkehrsmuster und verteilen Sie Aufrufe zeitlich, wenn möglich, 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 plattformweite Obergrenze bestimmt wird.

Zscaler oder SSL-abfangende Firewall blockiert API-Zugriff

Symptom: API-Aufrufe schlagen mit Zertifikatfehlern fehl, oder Backend-Endpunkte können nicht auf APIs zugreifen, die mit TLS gesichert sind, wenn sie ü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 neu signieren. Clientsysteme, 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 von Zscaler neu signierte Zertifikate vertraut werden.
- Konfigurieren Sie Tools wie curl, wget oder openssl so, 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 verarbeitet werden.
- Importieren Sie das Jitterbit-Leaf-Zertifikat nicht manuell in einen Trust Store als Lösung: Verwenden Sie stattdessen die Zscaler-Root-CA, um Probleme bei der Zertifikaterneurung 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; Sie können sie nicht selbst erstellen oder konfigurieren. Zustellungsfehler betreffen typischerweise die VAN-Verbindung, das Mailbox-Routing oder die Partnereinrichtung auf der Seite des Anbieters, nicht eine Self-Service-Einstellung in Jitterbit EDI.
Lösung:
- Bestätigen Sie, dass die richtige VAN-Verbindung dem betroffenen Handelspartner zugewiesen ist.
- Da die VAN-Verbindung nicht direkt von Jitterbit EDI aus konfiguriert werden kann, kontaktieren Sie den Jitterbit-Support oder Ihren Customer Success Manager, um die VAN-Verbindung und das Dokument-Routing zu überprüfen.
- Koordinieren Sie mit dem VAN-Anbieter, um zu bestätigen, dass die Mailbox-Identifikatoren und das Routing des Handelspartners auf der VAN-Seite korrekt sind.

Dokument abgelehnt: Ungültige oder fehlende Daten

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

EDI-Zuordnungs- oder Schemafehler

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

Falsche Handelspartner-Identifikatoren

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

Bestätigungen nicht konfiguriert oder nicht empfangen

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

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

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

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

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

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

Deaktiviertes EDI-Zugriffstoken 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 von der EDI for Cloud v2-Verbindung verwendete Zugriffstoken wurde auf der Seite „Zugriffstokens" der Management Console auf Inaktiv gesetzt.
Lösung: Suchen Sie auf der Seite „Zugriffstokens" das Token und setzen Sie seinen Status auf Aktiv.

Transformationsfehler: Nicht erkanntes Feld in EDI-Aktivität

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

Wiederholendes EDI-Segment oder Loop ordnet nur die letzte Iteration zu

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

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

Zugewiesene Kommunikationsverbindung kann nicht gelöscht werden

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

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

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

EDI-ID- oder bevorzugte ID-Hinzufü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 derzeit verwendet wird. Bitte bestätigen Sie und geben Sie eine eindeutige ID an.

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

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

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

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

Transaktion früher oder später als erwartet archiviert

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

Auf EDI-Funktionen kann nicht zugegriffen werden

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

PII-Einstellungen können nicht aktiviert werden

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

App-Entwicklung

Dieser Abschnitt behandelt Probleme mit der App-Entwicklungsfunktion von Harmony: Erstellen, Bereitstellen und Ausführen von Anwendungen in App Builder.

App Builder startet nicht mit einem 500-Fehler

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

App Builder startet nicht mit einem HTTP 500.30-Fehler

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

App Builder gibt einen HTTP 503-Fehler zurück

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

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

App Builder startet, erstellt aber keine Datenbanken

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

Fehler beim Laden der Datenbankverbindungsinformationen

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

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

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

App Builder 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 startet nach einem Serverneustart nicht automatisch

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

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

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

Hochverfügbarkeit: Alle Instanzen müssen die gleiche `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 zur 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 ab April 2026 erforderlich

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

SharePoint-Dateisystem: Dateien 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 Payload

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

Datummigration läuft bei großen Datenmengen ab

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

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

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

SMTP-Konfigurationsfehler

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

Argument passed in is not serializable. Parameter name: value

Value cannot be null. ParameterName: From Address

Unknown URI scheme. Parameter name: uri

Authentication required

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

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

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

Ein Ereignis wird 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: Geplante Hintergrundaufgaben werden nicht ausgeführt, wenn die App geschlossen ist

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

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

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

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

Fehlerbehebung in Jitterbit Harmony

Diagnose-Schritte

Betriebsprotokolle überprüfen

API-Protokolle überprüfen

Agent-Protokolle überprüfen

Harmony-Systemstatus überprü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 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 Identitätsanbieter-Konto

IP-Zulassungsliste sperrt einen Administrator

Ändern der API-Subdomain unterbricht bestehende 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 berücksichtigt

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 dem Fehler „kann nicht ausgeschlossen werden" fehl

Zugriffstoken kann nach Löschung seiner Umgebung nicht bearbeitet werden

OAuth-Aktualisierungstoken-Ablauf führt zu Fehlern bei verbundenen 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 vor Ort geändert werden

Integration und Automatisierung

Operationen bleiben im Status „Eingereicht" oder „Wird ausgeführt" 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 für Private Agent verfügbare Connector-Blöcke blockieren den Import in eine Cloud-Agent-Umgebung

Zielschleifenknoten ist mehreren Quellschleifenknoten zugeordnet

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

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

RunOperation stoppt nach 50 synchronen Aufrufen in einer While-Schleife

Der Vergleich einer Zeichenkette mit einer Zahl liefert unerwartete Ergebnisse

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

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

Leere zugeordnete Felder mit flachen Quellschemas

Dateifunktionen: Operation wird nach Fehler bei ArchiveFile oder ReadFile fortgesetzt

ReadFile: Teilweise Lesevorgänge mit Binärdateiinhalt

ReadFile-Inhalt mit Bytes außerhalb von UTF-8 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 aufgeteilten 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

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

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

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

`RunOperation` stoppt nach 50 synchronen Aufrufen in einer `While`-Schleife

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

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

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

`ReadFile`-Inhalt mit Bytes außerhalb von UTF-8 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

FTP: Dateinamen mit `#` werden nicht korrekt verarbeitet

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

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

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