Guida all’integrazione di NetSuite con SkyPlanner APS per la schedulazione della produzione

Oracle ha indicato la direzione. Dalla versione 2026.1, le nuove integrazioni dovrebbero essere sviluppate con i servizi web SuiteTalk REST e OAuth 2.0. Dalla versione 2027.1, non sono più ammesse nuove integrazioni basate su SOAP o Token-Based Authentication (TBA). Gli endpoint SOAP vengono disabilitati nella versione 2028.2. Qualsiasi integrazione per la schedulazione avviata oggi va realizzata su REST.

Autenticazione

Per uno schedulatore server-to-server, usa OAuth 2.0 Client Credentials (machine-to-machine). Il percorso di amministrazione è Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup. Carica un certificato pubblico e associalo a un’entità, a un ruolo e al record di integrazione. Ogni record di integrazione può contenere al massimo cinque certificati attivi.

Crea un ruolo dedicato all’integrazione: accesso in lettura ad articoli, revisioni delle distinte base, cicli di lavorazione e centri di lavoro; accesso in modifica a ordini di produzione, completamenti e prelievi. L’API REST di SkyPlanner (riferimento API) usa JWT, quindi il middleware conserva entrambe le credenziali.

Eventi: non esiste un webhook standard

La documentazione Oracle non descrive alcun webhook nativo in uscita. La soluzione consiste in uno script SuiteScript User Event su Work Order (afterSubmit) che accoda una chiamata in uscita tramite N/task o uno script Map/Reduce, usando N/https per inviarla. Non effettuare mai chiamate sincrone in afterSubmit: la chiamata viene eseguita durante il salvataggio dell’utente, quindi un endpoint lento rallenta il salvataggio o lo fa fallire.

Gli User Event non coprono tutte le modalità di modifica. Gli aggiornamenti massivi e le importazioni CSV possono non attivarli. Affianca allo script di evento un polling SuiteQL periodico di riconciliazione su lastmodifieddate, per non perdere nessuna modifica. Nella direzione opposta, i webhook di SkyPlanner attivano la scrittura dei dati in NetSuite, che riceve così le nuove date non appena il piano cambia.

1. Caricamento iniziale delle anagrafiche. Leggi prima i centri di lavoro, poi articoli, revisioni delle distinte base e cicli di lavorazione tramite SuiteQL. I cicli fanno riferimento ai centri di lavoro, quindi l’ordine conta. Durante la prova, esporta gli stessi dati in CSV e importali in SkyPlanner. La schedulazione viene convalidata prima ancora di scrivere codice.

2. Sincronizzazione degli ordini. Importa gli ordini di produzione negli stati Released e In Process. Decidi fin dall’inizio se includere anche quelli in stato Planned. Se li includi, trattali come domanda provvisoria. Sincronizza nello stesso ciclo gli ordini di acquisto aperti, in modo che la schedulazione verifichi ogni operazione rispetto alle scorte e ai materiali in arrivo, non soltanto alle scorte.

3. Scrittura del programma di produzione in NetSuite. Quando il programma cambia, un webhook di SkyPlanner invia al middleware le nuove date delle operazioni. Il middleware invia PATCH /services/rest/record/v1/manufacturingOperationTask/{id} (riferimento Oracle per il record) con startDate e endDate per ogni operazione modificata. Un’ulteriore PATCH sulla testata workOrder imposta i campi Production Start e End Date. Scrivi solo le date e, se lo usi, un campo personalizzato per la sequenza. Non riscrivere mai quantità o dati della BOM. Per aggiornare molte operazioni in un’unica transazione, un piccolo RESTlet salva l’intero elenco di operazioni con una sola chiamata. L’API per i record resta la scelta predefinita.

4. Conferme dal reparto produttivo. Gli operatori registrano il lavoro in SkyPlanner Mobile Confirmations. Il middleware invia ogni conferma tramite le trasformazioni di Work Order con POST /services/rest/record/v1/workOrder/{id}/!transform/workOrderCompletion, includendo startOperation, endOperation, la quantità completata e il tempo registrato sulle righe delle operazioni. Gli ordini di produzione senza WIP vengono invece chiusi con !transform/assemblyBuild. Work Order Completion tramite REST richiede la funzionalità Manufacturing Work In Process. Le registrazioni di magazzino e dei costi restano in NetSuite.

5. Idempotenza e nuovi tentativi. Ogni completamento usa l’ID della registrazione ore di SkyPlanner come ID esterno in NetSuite. Gli ID esterni sono univoci per tipo di record: un webhook ripetuto viene quindi rifiutato come duplicato, invece di registrare due volte quantità e costi. Le scritture passano attraverso una coda. Una chiamata non riuscita (limite di concorrenza, record bloccato, certificato scaduto) viene ritentata e registrata nel log. Gli errori che persistono sono visibili al team SkyPlanner che fornisce assistenza sull’integrazione.

6. Responsabilità sui dati. NetSuite stabilisce cosa viene prodotto: articolo, quantità, distinta base, ciclo di lavorazione e ubicazione. SkyPlanner stabilisce quando e dove: sequenza delle operazioni, centro di lavoro, inizio e fine. Le date modificate in NetSuite vengono sovrascritte al successivo invio dei dati, quindi blocca Production Start/End Date con una personalizzazione del modulo o un workflow.

• Ordini di produzione senza cicli di lavorazione. Un ordine di produzione privo di Manufacturing Routing non ha operazioni da schedulare. Oracle afferma lo stesso a proposito del proprio strumento di schedulazione della produzione che tiene conto della capacità disponibile: “Work orders not associated with a NetSuite routing should not be scheduled.” (Gli ordini di produzione non associati a un ciclo di lavorazione NetSuite non devono essere schedulati.) Individuali con SuiteQL prima della messa in produzione.
• I centri di lavoro hanno pochi dettagli. Un centro di lavoro NetSuite è un Group con due conteggi, Machine Resources e Labor Resources (entrambi impostati a 0 per default), e un Work Calendar, di solito “Default Work Calendar”. Carica i centri di lavoro una volta sola, poi gestisci in SkyPlanner i singoli centri di lavoro, i turni per persona, gli utensili, la matrice dei tempi di attrezzaggio e i centri di lavoro alternativi.
• Qualità dei dati in Setup Time e Run Rate. La schedulazione a capacità infinita di NetSuite usa questi campi, ma, non tenendo conto della capacità, lascia passare inosservati i valori errati. Una schedulazione della produzione che rispetta la capacità reale di macchine e personale li mette in evidenza fin dal primo giorno.
• WIP o non-WIP. Con Manufacturing WIP, la produzione viene registrata tramite Work Order Issue, Work Order Completion e Work Order Close. Senza WIP, si usa un Assembly Build. L’integrazione registra i completamenti per gli articoli WIP e gli Assembly Builds per gli altri, quindi il modello di ciascun articolo rientra nella mappatura.
• Advanced Manufacturing nello stesso account. Se l’account usa anche Advanced Manufacturing SuiteApp, i relativi record Manufacturing Work Bench devono corrispondere esattamente al ciclo di lavorazione: sequenza delle operazioni, nome dell’operazione e centro di lavoro. Decidi quale sistema stabilisce le date delle operazioni. Due schedulatori sugli stessi ordini di produzione significano due piani in conflitto.
• Limiti di concorrenza. Le chiamate ai servizi web e ai RESTlet condividono un unico limite di concorrenza dell’account, determinato dal livello di servizio, con un incremento di 10 per ogni licenza SuiteCloud Plus. Il polling parallelo dei singoli record lo raggiunge rapidamente. Usa SuiteQL con paginazione per le letture e metti in coda le scritture.
• L’aggiornamento della sandbox cancella la configurazione M2M. Le associazioni OAuth 2.0 Client Credentials vengono cancellate quando si aggiorna la sandbox e non vengono copiate tra account. Un certificato scaduto o revocato interrompe la sincronizzazione finché non viene creata una nuova associazione. Configura avvisi per gli errori di autenticazione.