Leitfaden zur NetSuite-Integration für die Feinplanung mit SkyPlanner APS

Oracle hat die Richtung vorgegeben. Ab 2026.1 sollen neue Integrationen auf SuiteTalk REST-Webservices mit OAuth 2.0 basieren. Ab 2027.1 sind keine neuen Integrationen über SOAP oder Token-Based Authentication (TBA) mehr möglich. Mit 2028.2 werden SOAP-Endpunkte deaktiviert. Jede heute begonnene Integration für die Feinplanung gehört auf REST.

Authentifizierung

Für eine Server-zu-Server-Anbindung der Feinplanung verwenden Sie OAuth 2.0 Client Credentials (Machine-to-Machine). Der Pfad in der Administration lautet Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup. Sie laden ein öffentliches Zertifikat hoch und ordnen es einer Entität, einer Rolle und dem Integrationsdatensatz zu. Jeder Integrationsdatensatz kann höchstens fünf aktive Zertifikate enthalten.

Legen Sie eine eigene Integrationsrolle an: mit Leserechten für Artikel, BOM-Revisionen, Arbeitspläne und Arbeitsstationen sowie Bearbeitungsrechten für Fertigungsaufträge, Fertigmeldungen und Materialentnahmen. Die SkyPlanner REST API (API-Referenz) verwendet JWT. Die Middleware hält daher beide Zugangsdaten vor.

Ereignisse: Es gibt keinen Standard-Webhook

Die Dokumentation von Oracle beschreibt keinen nativen Webhook für ausgehende Benachrichtigungen. Bewährt hat sich ein SuiteScript User Event-Skript auf Work Order (afterSubmit), das einen ausgehenden Aufruf über N/task oder ein Map/Reduce-Skript in die Warteschlange stellt. Der Aufruf selbst erfolgt mit N/https. Führen Sie in afterSubmit niemals synchrone Aufrufe an externe Systeme aus: Der Aufruf läuft während des Speichervorgangs des Benutzers. Ein langsamer Endpunkt verzögert daher das Speichern oder lässt es fehlschlagen.

User Events erfassen nicht alle Wege, auf denen Daten geändert werden. Massenaktualisierungen und CSV-Importe können sie umgehen. Ergänzen Sie das Event-Skript deshalb um einen regelmäßigen Abgleich per SuiteQL-Abfrage auf lastmodifieddate, damit keine Änderung übersehen wird. In der Gegenrichtung lösen die eigenen Webhooks von SkyPlanner das Zurückschreiben aus. So erhält NetSuite neue Termine, sobald sich der Plan ändert.

1. Erstübernahme der Stammdaten. Lesen Sie mit SuiteQL zuerst die Arbeitsstationen ein, danach Artikel, BOM-Revisionen und Arbeitspläne. Arbeitspläne verweisen auf Arbeitsstationen, deshalb ist die Reihenfolge wichtig. Exportieren Sie in der Testphase dieselben Daten als CSV und importieren Sie sie in SkyPlanner. So wird der Plan validiert, bevor Code geschrieben wird.

2. Auftragssynchronisierung. Rufen Sie Fertigungsaufträge mit dem Status Released und In Process ab. Entscheiden Sie frühzeitig, ob auch Fertigungsaufträge mit dem Status Planned übernommen werden sollen. Falls ja, behandeln Sie diese als vorläufigen Bedarf. Synchronisieren Sie im selben Zyklus offene Bestellungen, damit die Planung für jeden Arbeitsgang sowohl Lagerbestand als auch Materialzugänge prüft – nicht nur den Lagerbestand.

3. Planungstermine zurückschreiben. Bei Planänderungen übermittelt ein SkyPlanner-Webhook die neuen Arbeitsgangtermine an die Middleware. Diese sendet für jeden geänderten Arbeitsgang PATCH /services/rest/record/v1/manufacturingOperationTask/{id} (Oracle-Referenz zum Datensatz) mit startDate und endDate. Ein weiterer PATCH auf die Kopfdaten von workOrder setzt Production Start Date und Production End Date. Schreiben Sie nur Termine und, falls verwendet, ein benutzerdefiniertes Feld für die Reihenfolge zurück. Schreiben Sie niemals Mengen oder Stücklistendaten zurück. Sollen viele Arbeitsgänge in einer Transaktion aktualisiert werden, speichert ein kleines RESTlet die gesamte Arbeitsgangliste mit einem einzigen Aufruf. Die record API bleibt der Standardweg.

4. Rückmeldungen vom Shopfloor. Die Mitarbeiter erfassen ihre Arbeit in SkyPlanner Mobile Confirmations. Die Middleware bucht jede Rückmeldung über die Transformationen für Work Order mit POST /services/rest/record/v1/workOrder/{id}/!transform/workOrderCompletion. Übertragen werden startOperation, endOperation, die fertiggestellte Menge und die erfasste Zeit in den Arbeitsgangzeilen. Fertigungsaufträge ohne WIP werden stattdessen mit !transform/assemblyBuild abgeschlossen. Work Order Completion über REST setzt die Funktion Manufacturing Work In Process voraus. Bestands- und Kostenbuchungen bleiben in NetSuite.

5. Idempotenz und Wiederholungsversuche. Jede Fertigmeldung trägt die SkyPlanner-Zeiterfassungs-ID als externe ID in NetSuite. Externe IDs sind je Datensatztyp eindeutig. Ein erneut zugestellter Webhook wird deshalb als Duplikat abgewiesen, statt Mengen und Kosten doppelt zu buchen. Schreibvorgänge laufen über eine Warteschlange. Fehlgeschlagene Aufrufe – etwa wegen des Limits für gleichzeitige Aufrufe, eines gesperrten Datensatzes oder eines abgelaufenen Zertifikats – werden wiederholt und protokolliert. Was weiterhin fehlschlägt, ist für das SkyPlanner-Team sichtbar, das die Integration betreut.

6. Zuständigkeiten der Systeme. NetSuite gibt vor, was gefertigt wird: Artikel, Menge, BOM, Arbeitsplan und Standort. SkyPlanner bestimmt, wann und wo gefertigt wird: Reihenfolge der Arbeitsgänge, Arbeitsstation, Start und Ende. In NetSuite geänderte Termine werden beim nächsten Rückschreiben überschrieben. Sperren Sie deshalb Production Start/End Date über eine Formularanpassung oder einen Workflow.

• Fertigungsaufträge ohne Arbeitsplan. Ein Fertigungsauftrag ohne Manufacturing Routing hat keine Arbeitsgänge, die eingeplant werden können. Oracle weist ebenfalls darauf hin, bezogen auf die eigene Feinplanung: „Work orders not associated with a NetSuite routing should not be scheduled.“ (Fertigungsaufträge ohne zugeordneten NetSuite-Arbeitsplan sollten nicht eingeplant werden.) Ermitteln Sie diese Aufträge vor dem Go-live mit SuiteQL.
• Arbeitsstationen enthalten nur wenige Planungsdaten. Eine Arbeitsstation in NetSuite ist eine Group mit zwei Mengenangaben, Machine Resources und Labor Resources (beide standardmäßig 0), und einem Work Calendar, in der Regel „Default Work Calendar“. Übernehmen Sie die Arbeitsstationen einmalig. Pflegen Sie danach einzelne Arbeitsstationen, Schichten je Person, Werkzeuge, die Rüstzeitmatrix und alternative Arbeitsstationen in SkyPlanner.
• Datenqualität bei Setup Time und Run Rate. Die Planung mit unbegrenzter Kapazität in NetSuite nutzt diese Felder. Da sie die Kapazität jedoch nicht berücksichtigt, bleiben falsche Werte unbemerkt. Eine Feinplanung macht sie gleich am ersten Tag sichtbar.
• WIP oder Nicht-WIP. Mit Manufacturing WIP wird die Fertigung über Work Order Issue, Work Order Completion und Work Order Close gebucht. Ohne WIP wird ein Assembly Build verwendet. Die Integration bucht für WIP-Artikel Fertigmeldungen und für die übrigen Artikel Assembly Builds. Das Modell je Artikel gehört deshalb zur Datenzuordnung.
• Advanced Manufacturing im selben Konto. Wenn im Konto auch die Advanced Manufacturing SuiteApp läuft, müssen deren Manufacturing Work Bench-Datensätze exakt mit dem Arbeitsplan übereinstimmen: Reihenfolge und Name der Arbeitsgänge sowie Arbeitsstation. Legen Sie fest, welches System die Arbeitsgangtermine vorgibt. Zwei Planungssysteme für dieselben Fertigungsaufträge bedeuten zwei konkurrierende Pläne.
• Limits für gleichzeitige Aufrufe. Webservices und RESTlet-Aufrufe teilen sich ein kontoweites Limit für gleichzeitige Aufrufe. Es richtet sich nach der Servicestufe und erhöht sich um 10 je SuiteCloud Plus-Lizenz. Parallele Einzelabfragen von Datensätzen erreichen dieses Limit schnell. Verwenden Sie zum Lesen SuiteQL mit Paginierung und für Schreibvorgänge eine Warteschlange.
• Eine Sandbox-Aktualisierung löscht die M2M-Einrichtung. Die Zuordnungen für OAuth 2.0 Client Credentials werden bei einer Sandbox-Aktualisierung gelöscht und nicht zwischen Konten kopiert. Ein abgelaufenes oder widerrufenes Zertifikat stoppt die Synchronisierung, bis eine neue Zuordnung angelegt ist. Richten Sie Warnmeldungen für Authentifizierungsfehler ein.