NetSuite-Fehlerbehebung

Verbindungsfehler

Rechenzentrumsfehler

• 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.

Unzureichende Berechtigungen

• 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.

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.

Schema- und Feldprobleme

Benutzerdefinierte Felder werden nicht im Aktivitätsschema angezeigt

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

Benutzerdefinierte Segmente werden nicht angezeigt 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.

Benutzerdefinierte Textkörperfelder aufgrund fehlender Rollenberechtigung nicht sichtbar

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

Fehler bei der Aktivitätskonfiguration

Gespeicherte Suchen werden nicht im Dropdown-Menü angezeigt

• 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.

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.

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.

Abfrage testen gibt einen Parse-Fehler zurück, wenn der Filter eine Projektvariable verwendet

• Symptom: Wenn ein Filter der NetSuite-Suchaktivität eine Projektvariable für einen Datums- oder Datetime-Wert verwendet (wie lastModifiedDate), gibt das Klicken auf Abfrage testen in der Aktivitätskonfiguration einen 500-Fehler zurück, der auf ein ungültiges Datumsformat verweist. Derselbe Vorgang wird zur Laufzeit erfolgreich ausgeführt.

  Connector Error: FaultString: java.text.ParseException: Invalid dateTime format: [lastModifiedDate]
  

• Ursache: Abfrage testen löst Projektvariablen nicht auf. Es sendet den wörtlichen Variablenverweis (zum Beispiel [lastModifiedDate]) als Filterwert, den NetSuite als ungültiges Datum ablehnt. Zur Laufzeit ersetzt der Agent den tatsächlichen Wert der Variable, sodass der Vorgang selbst erfolgreich ist.

• Lösung: Um die Aktivität zu testen oder Änderungen daran zu speichern, ohne die Variable zu entfernen, fügen Sie dem Variablenverweis in der Filterbedingung einen temporären Standardwert hinzu:
  1. Ändern Sie im Filter den Variablenverweis von [my_date_variable] zu [my_date_variable{2023-01-01T00:00:00.000Z}] (unter Verwendung der passenden ISO-8601-Datumszeit als Standardwert).
  2. Klicken Sie auf Abfrage testen. Der Test ist jetzt erfolgreich, da anstelle der nicht aufgelösten Variable ein gültiges Datum eingesetzt wird.
  3. Speichern Sie alle weiteren Änderungen an der Aktivität. Der Standardwert kann bestehen bleiben; zur Laufzeit verwendet der Agent immer den aktuellen Wert der Projektvariable.

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.

Update-Aktivität gibt INVALID_KEY_OR_REF zurück, wenn das 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.

Leistung und Datensatzlimits

Vorgänge schlagen aufgrund von Datensatzlimits der NetSuite-API 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.

Vorgänge schlagen aufgrund des Limits für gleichzeitige Anfragen fehl

• 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).

Versions- und Schemaänderungen

Vorgänge schlagen nach der Aktualisierung der NetSuite-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.