API V5

Introduzione

Il V5 Traceability Gateway consente lo scambio di dati bidirezionale tra la gamma di prodotti V5 Traceability e altre soluzioni. Il gateway è altamente flessibile e fornisce una rapida implementazione con molti sistemi ERP ed esterni diversi, consentendo ai clienti di integrare in modo efficiente l'intera fabbrica. La gamma di prodotti V5 dispone di un'API estesa da utilizzare nell'integrazione.

Questa guida fornirà una panoramica dettagliata su come utilizzare i vari metodi per importare ed esportare dati. Verranno inoltre descritte dettagliatamente ciascuna entità che può essere importata e i possibili campi per tali entità.

Il gateway può essere utilizzato in 2 modi principali:

• Tramite un'API REST dell'interfaccia Web che utilizza file JSON o XML.
• Tramite condivisione diretta di file con documenti CSV o XML.

Entrambi questi metodi verranno esaminati in questa guida, oltre a fornire esempi per le principali aree di integrazione dei dati.

1. Cosa fa il gateway V5?
2. Esempio di diagramma del flusso di dati
3. Guide all'integrazione
4. Documenti di riferimento sull'integrazione V5
5. Metodologia: API V5
   1. Richieste di esportazione/OTTIENI
   2. Richieste di importazione/POST
   3. Inserisci o aggiorna?
   4. Indicatori di esportazione
   5. Parametri URI
   6. Registri, transazioni e descrittori di sistema
6. Metodologia – Condivisione di file CSV
   1. Ordinamento dei file di dati e di intestazione
   2. Importazioni
   3. Esportazioni
7. Frequenza e sequenza
8. Contattaci

Il servizio di integrazione V5 Traceability può essere implementato per coprire una gamma di punti dati, che possono essere completamente personalizzati da ogni singolo cliente in base alle proprie esigenze. Questi requisiti verranno discussi durante le fasi iniziali dell'implementazione della Tracciabilità V5.

A seconda delle esigenze del cliente, V5 Traceability può essere configurato per integrare un numero qualsiasi di aree, come formulazione/distinte base, pianificazione dei lavori, ordini di acquisto e vendita, livelli e ubicazioni di inventario.

In questa sezione puoi trovare guide specifiche per l'integrazione di moduli specifici di Tracciabilità V5:

Per i moduli principali che comunemente presentano un'integrazione bidirezionale:

• Materie prime
• Formule
• Ubicazione dell'inventario/magazzino
• Lavori/Ordini di produzione
• Ordini d'acquisto
• Ordini di vendita
• Transfer
• Unità di misura

Per i moduli secondari che dispongono solo di opzioni di importazione:

• Indirizzo
• AllergeneLink
  
• Cliente (Fornitori e Clienti)
• Collegamento campo personalizzato
• HazardLink
• Assegnazione delle azioni

Per assistenza nell'installazione e nell'aggiornamento dell'API V5, consultare la seguente documentazione:

• Guida all'installazione e all'aggiornamento dell'API V5

Per esempi di implementazione dell'integrazione, consultare le nostre guide per soluzioni ERP specifiche di seguito:

• Oracle NetSuite
• Saggio X3
• Microsoft Business Central

In questa guida ai metodi di integrazione di V5 Traceability, faremo uso regolare di due documenti per assisterci. Entrambi sono utili indipendentemente dal metodo di integrazione che stiamo utilizzando. Questi sono:

• Migliori Foglio di lavoro per l'integrazione V5 che contiene informazioni utili e modelli per i moduli più comunemente integrati.
• Migliori Manuale API V5, che può essere utilizzato per individuare URI di importazione/esportazione specifici oltre a fornire una guida completa per ogni classe di dati utilizzata dall'API V5.
• Nelle guide API di questa sezione verranno fatti riferimenti a endpoint transazionali e di registro. Un elenco completo di questi può essere trovato seguendo il collegamento.

Se si utilizza questo metodo, l'API V5 verrebbe installata come servizio Web per facilitare il trasferimento dei dati. Da qui le transazioni vengono gestite dalle diverse classi di moduli disponibili.

Per saperne di più su queste classi, sui diversi endpoint/URI, nonché informazioni sulle varie classi di database con cui avremo a che fare quando utilizziamo l'API V5, possiamo utilizzare sia il 'Foglio di lavoro per la mappatura dell'integrazione V5' e il Sito web dell'API V5 per aiutarci. Da qui possiamo utilizzare il package explorer in alto a sinistra di questa finestra per navigare nelle diverse sezioni del manuale dell'API.

Utilizzeremo queste sezioni per creare esempi mentre discuteremo i vari aspetti dell'integrazione dei dati di seguito.

Una volta installati, è possibile accedere agli endpoint API tramite un browser o un client REST all'indirizzo:

http://{hostname:port}/V5-API/api

Il modulo IntegrationImport ha un percorso di /integrate/import/

Il modulo IntegrationExport ha un percorso di /integrate/export/

Il percorso del modulo "Transazioni" è /integrate/export/transactions/

Ciascun metodo ha il proprio percorso elencato nella directory API V5 come a ‘Target URI’. Questo può essere aggiunto alla fine dei percorsi precedenti per eseguire il metodo.

Ciascuna descrizione del metodo contiene anche a ‘request type’, che indica se si tratta di una richiesta GET o POST più l'URI per quel determinato metodo.

Eventuali richieste GET o POST verranno elaborate in formato JSON. Tutti i campi e gli oggetti sono definiti nel pacchetto database che puoi trovare tramite il file pacchetto di servizi.

Come accennato in precedenza, il modulo di esportazione API V5 ha un percorso di:

http://{hostname:port}/V5-API/api/integrate/export/

Quindi in realtà sarebbe qualcosa del genere (se si interagisce tramite un'istanza installata localmente dell'API V5):

http://127.0.0.1:8080/V5-API/api/integrate/export/

Ciò che verrà dopo dipende da quali dati vogliamo estrarre dalla V5. Faremo quindi riferimento al pacchetto di servizi, utilizzando le finestre a sinistra della finestra principale dell'API per selezionare il pacchetto di servizi, seguito da "IntegrationExport" di seguito.

Possiamo anche utilizzare il collegamento ai servizi nella pagina dell'indice, che caricherà quindi il riepilogo della classe per quel pacchetto, dove potremo quindi scegliere la classe "IntegrationExport".

Ci verrà quindi mostrato l'URI di destinazione dell'esportazione (1) insieme a un elenco di endpoint disponibili per la classe del modulo di esportazione. Possiamo visualizzarli tutti in dettaglio facendo clic sul costruttore 'IntegrationExport' (2), oppure possiamo utilizzare il comando ‘Method Summary’ tabella seguente (3) per trovare rapidamente l'endpoint desiderato. Possiamo anche vedere l'URI di destinazione per questo modulo nella parte superiore della pagina, quindi tutto ciò che dovremmo fare ora è identificare gli oggetti, i campi e i valori richiesti.

Quindi prendiamo la prima voce nella tabella di riepilogo del metodo qui, ‘Batch’. Facendo clic sul collegamento nella colonna di destra (4) verremo portati direttamente all'endpoint di cui vogliamo conoscere.

Questo ci fornisce le informazioni di cui abbiamo bisogno, inclusi quali dati verranno richiamati, il tipo di richiesta e, soprattutto, l'URI di destinazione per la richiesta.

Quindi ora sappiamo che se vogliamo estrarre un batch dall'API V5, l'endpoint che dovremmo raggiungere sarebbe:

http://127.0.0.1:8080/V5-API/api/integrate/export/batch/{batchNumber}

Diamo rapidamente un'occhiata a come funzionerebbe nella pratica. Possiamo iniziare trovando un batch che vogliamo estrarre tramite l'API, andiamo al batch '50009622' che possiamo vedere qui in Control center.

Utilizzando ciò che abbiamo imparato sopra, possiamo quindi completare l'URI nel client REST come tale:

L'esecuzione di questo processo ora genererà quindi un file JSON dettagliato per quel batch, che potrà quindi essere utilizzato e analizzato dall'applicazione client. Un tipico ritorno per questa richiesta potrebbe assomigliare a questo.

In molti casi in cui il pluralismo è applicabile agli endpoint a cui ci rivolgiamo, ad esempio qui i batch possono diventare batch, possiamo usarlo per chiamare un elenco di batch con l'espressione ‘export/batches’ URI.

Come accennato in precedenza, il modulo di importazione API V5 ha un percorso di:

http://{hostname:port}/V5-API/api/integrate/import/

Ciò che seguirebbe dipenderebbe da quali dati stiamo cercando di importare tramite l'API. Ritorneremo alla sezione relativa ai pacchetti di servizi del file Manuale API e questa volta fare clic su "IntegrationImport" (1).

Questo è strutturato allo stesso modo della pagina delle esportazioni, con l'URI di importazione (2), il collegamento alla parte superiore delle pagine di riepilogo di seguito (3) e la tabella di riepilogo del metodo (4) dove possiamo vedere tutti gli endpoint disponibili .

Come prima, dovremmo solo trovare l'endpoint pertinente ai dati che desideriamo pubblicare nel sistema tramite l'API.

Tieni presente che la maggior parte degli endpoint POST di importazione prevede un array in modo che più record possano essere inviati in un'unica richiesta. Ciò può essere verificato esaminando i tipi di parametri per gli endpoint di importazione in ‘Method Summary’.

Prendiamo come esempio le materie prime:

Ciò che ci dice qui è che possiamo utilizzare questo endpoint per importare elenchi di prodotti/ingredienti che possono poi essere utilizzati per la formulazione. L'URI che utilizzeremmo per questo sarebbe:

http://127.0.0.1:8080/V5-API/api/integrate/import/commodity

Di seguito possiamo vedere questo endpoint in uso, insieme a un file di importazione di esempio molto semplice in formato JSON:

Per aiutarci nella strutturazione di un file di importazione JSON, possiamo avvalerci del collegamento alla relativa sezione dei pacchetti database del manuale API presente nel riepilogo del servizio:

Oppure possiamo navigare manualmente alla sezione pertinente selezionando la sezione di riepilogo delle classi del database dal file Homepage dell'API.

Se passiamo alla pagina della classe del database di seguito per ‘Commodity’, possiamo come dovremmo strutturare il file JSON. Ad esempio, se vogliamo definire un codice merceologico quando utilizziamo questo URI, questo sarebbe ‘code’, e lo stesso vale per la descrizione della merce ‘description’.

Nota quindi come questi campi si trovano all'estrema sinistra del file JSON di esempio sopra, insieme ad altri campi che possiamo vedere nello screenshot come ‘defExpiryDays’. Potremmo anche aggiungere il costo predefinito della merce al nostro file e controllando di seguito possiamo vedere che sarebbe semplicemente ‘cost’ (1). Tieni inoltre presente che tutto ciò che è elencato qui come a ‘primary key’ (2) è un campo obbligatorio per quell'endpoint, ovvero il file non verrà importato se questo non è presente.

Possiamo anche attraversare diversi livelli dell'API da questa classe di database, quindi vediamo come possiamo farlo per includere più informazioni sui nostri prodotti ‘units’.

Verso la fine di questa pagina ci imbatteremo ‘WeightUnit’, che possiamo usare come classe nidificata all'interno dell'URI della merce.

Questo ci dà la nostra classe di database per ‘units’, che può collocarsi allo stesso livello delle altre classi che abbiamo già definito. Per scoprire quali dati possiamo annidare qui possiamo cliccare su ‘WeightUnit’ qui per sfogliare le definizioni di quella classe.

Come possiamo vedere ci sono solo 3 punti dati all'interno di questa classe e nel nostro esempio JSON li utilizziamo tutti, ‘code’, ‘description’, e ‘conversionRate’. Questi 3 punti dati verrebbero nidificati all'interno del file ‘units’ campo, come mostrato.

Se eseguiamo questo file JSON come sopra, vedremo (a seconda del client che stiamo utilizzando) una risposta dall'API e saremo anche in grado di vedere questa merce importata nel nostro 'Materie prime' nel Centro di controllo.

Quando si utilizza la funzione POST per raggiungere gli endpoint per l'API V5, è possibile aggiornare o inserire un record. Ciò che accade qui è definito dalla chiave primaria che stiamo tentando di pubblicare.

Se prendiamo l'esempio della merce di cui sopra, abbiamo visto nelle definizioni delle classi del database che il codice della merce è la sua chiave primaria. Al momento della pubblicazione, se questo codice esiste già, aggiorneremo il record di quella merce con i nuovi valori inclusi a quel livello di classe.

Al contrario, se il codice attualmente non esiste nel database V5, verrà creato un nuovo record.

Tuttavia, se guardiamo il ns ‘units’ classe nidificata, tieni presente che mentre possiamo inserire nuovi dati di unità se la chiave primaria di questa classe non è già presente, non possiamo aggiornare le unità esistenti utilizzando il comando ‘commodity’ punto finale. Dovremmo invece affrontare il ‘import/unit’ URI invece.

L'API V5 utilizza indicatori di esportazione per distinguere tra i dati che sono stati o non sono già stati esportati nel sistema ERP di un cliente. Per impostazione predefinita, questo è abilitato per facilitare l'esportazione dei dati che l'ERP esterno non ha ancora visto e, una volta contrassegnati come esportati nel database V5, questi dati non verranno inclusi nelle esportazioni future.

Questo può tuttavia essere disabilitato a seconda delle preferenze del cliente. Questo può anche essere disabilitato se il sistema ERP in uso può restituire marcatori di esportazione all'API V5 per confermare di aver già ricevuto i dati in questione.

In questa situazione viene utilizzata una conferma di ricezione per informare l'API V5 che i dati sono stati ricevuti, l'endpoint che può essere utilizzato per controllarlo è documentato Qui..

Se né l'API V5 né l'ERP sono impostati per fornire indicatori di esportazione, a seconda dell'endpoint utilizzato ciò potrebbe potenzialmente restituire una grande quantità di dati. In questi casi, possiamo utilizzare i parametri URI per filtrare la quantità di dati esportati.

L'API V5 utilizza anche vari parametri URI che possono essere utilizzati per restringere ulteriormente le nostre richieste dal sistema.

Possiamo vedere se questi parametri sono disponibili per i nostri endpoint controllando i riepiloghi dei metodi nel servizio desiderato. Se possiamo vedere ‘int’ seguito da un parametro, quindi possiamo utilizzare questo parametro per filtrare i risultati che riceveremo dall'API.

Ad esempio, abbiamo visto sopra che funziona per ‘batch’ permettendoci di filtrare in base al numero di lotto.

Altri esempi potrebbero includere l'estrazione dei registri batch per data, dove possiamo usarli ‘batch_system_logs/filterFrom/{filterDate}’ (utilizzando le convenzioni di datazione epocale).

Per molti dei moduli che possono essere integrati tramite l'API V5, spesso è più conveniente recuperare informazioni dalle transazioni e dagli endpoint di registro. Alcuni di questi possono essere utilizzati per diversi scopi (come i “registri di sistema”), mentre altri sono più personalizzati per moduli specifici (come le “transazioni di vendita”).

Questi endpoint utilizzano descrittori di sistema per denotare determinati eventi che accadono (ricezione di una merce, consumo di un ingrediente per la produzione, ecc.) e sono particolarmente utili per mantenere l'accuratezza dell'inventario nel sistema V5.

Per esaminare questi endpoint e quali informazioni restituiscono/per quali moduli sono utili, fare clic su Qui..

Il metodo di condivisione file V5 utilizza file csv e csvh di "intestazione" per eseguire scambi di dati con Tracciabilità V5. Per questi scambi, utilizzeremmo file di "intestazione" per determinare l'ordine dei dati sia per le importazioni che per le esportazioni, quindi importeremmo o riceveremmo un CSV esportato che segue questo ordine. Di seguito possiamo dare un'occhiata a come funzionerebbe nella pratica.

Sia che importiamo o esportiamo dati utilizzando il metodo di condivisione file CSV, utilizzeremo file di intestazione per determinare l'ordine dei dati. In termini di come possiamo strutturarli, qui possiamo utilizzare sia il 'Foglio di lavoro per la mappatura dell'integrazione V5' e in linea Manuale API per aiutarci in questo. Diamo un'occhiata a un esempio qui per a ‘Commodities’ importare dal foglio di lavoro.

Come possiamo vedere qui, SG ha già strutturato un layout di intestazione di base qui, e se guardiamo nel manuale dell'API questa particolare classe di database, possiamo vedere che la maggior parte dei campi qui esistono in questa classe, permettendoci semplicemente di usare ‘code’, ‘cost’, ‘bulkUnit’ ecc. come sono definiti qui.

Tieni presente che, analogamente a quando stavamo esaminando la struttura dei nostri file JSON sopra, la chiave primaria (code) deve essere incluso.

Possiamo anche attraversare le classi del database in un modo simile a quello che abbiamo visto durante la strutturazione dell'importazione JSON sopra. Possiamo vederlo nel nostro esempio sopra con ‘units.code’. All'interno del ‘Commodity’ classe abbiamo il ‘WeightUnits’ classe (definita come ‘units’).

Seguendo questo collegamento al ‘WeightUnit’ class ci mostrerà che per definire il codice per l'unità di peso, questo è ‘code’ in questa classe, quindi per passare a questo dal nostro ‘Commodity’ il punto di partenza sarebbe ‘units.code’.

Qui possiamo attraversare tutti i livelli che vogliamo, basta collegarli nel manuale dell'API.

Faremo lo stesso per strutturare le intestazioni che utilizzeremo per le esportazioni, utilizzando le definizioni di classe del database appropriate per individuare quali dati vogliamo ricevere dal sistema e in quale ordine.

I file di intestazione dovrebbero essere costruiti come file CSV, con 1 valore in ogni cella della riga superiore finché non avremo definito tutti i dati che vogliamo importare o esportare. Questo file CSV deve quindi essere salvato e quindi la sua estensione deve essere modificata in a ‘csvh’ file (per eseguire questa operazione è necessario abilitare la visualizzazione dell'estensione file in Windows).

Eventuali modifiche al file csvh devono essere apportate dopo averlo riportato in un file csv e averlo modificato in questo formato.

Le intestazioni utilizzate per le importazioni devono essere inserite in:

<installdir>\SG Control Center\gateway\import\column_defs

Le intestazioni utilizzate per le esportazioni devono essere inserite in:

<installdir>\SG Control Center\gateway\export\order

Ora possiamo vedere come procederemo con le nostre importazioni ed esportazioni.

Una volta impostati i file di intestazione pertinenti, dobbiamo completare il file CSV per l'importazione.

Come già accennato, i dati nel nostro file CSV devono aderire alla stessa struttura del file di intestazione corrispondente, ovvero i dati corretti devono trovarsi nella colonna corretta, affinché l'importazione abbia esito positivo. Per restare con il nostro esempio sulle materie prime, possiamo vedere che nell'esempio seguente abbiamo incluso i dati dell'intestazione per aiutarci nell'immissione dei dati. Tuttavia non è necessario includerlo (vedere "Ignora intestazioni" di seguito).

Una volta impostato questo, possiamo continuare a compilare il CSV per includere tutte le merci che vogliamo importare.

Una volta completato il CSV, è possibile eseguire le importazioni trascinando i file CSV opportunamente formattati e denominati in ‘\SG Control Center\gateway\import’. Le convenzioni di denominazione per questi file sono definite nel foglio di lavoro di mappatura dell'integrazione V5, quindi per le materie prime possiamo vedere che questo è:

Quindi, ad esempio, il nostro nome file potrebbe essere denominato "commodity-0530231803.csv per dirci che questo è stato importato il 30^th Maggio 2023, ore 18:03. Non esiste una preferenza per l'ordine di data/ora, quindi SG consiglia di utilizzare il formato che funziona meglio per ciascun cliente qui (questo potrebbe essere determinato dall'ERP esterno in uso).

Dopo aver inserito i nostri file nella cartella corretta, Control Center li elaborerà automaticamente, a condizione che le importazioni siano abilitate nel Gateway. Il sistema fornirà un dialogo per informarci se il processo ha avuto successo o meno. Ulteriori informazioni a riguardo, insieme ai log, sono disponibili nella sezione "Gateway" del Centro di controllo.

I file possono anche essere importati manualmente da altre posizioni facendo clic con il pulsante destro del mouse sull'icona del Centro di controllo nel sistema e scegliendo Gateway > Importa file.

Verrà quindi aperta una finestra di dialogo all'interno del Centro di controllo per selezionare il file CSV appropriato.

All'interno del Gateway stesso possiamo quindi impostare le opzioni rispetto al processo di importazione:

Le impostazioni qui possono essere definite come segue:

• Importazione abilitata – abilita l'importazione, consentendo al Gateway di scansionare la cartella di importazione alla ricerca di CSV non appena vengono inseriti lì.
• Inserisci entità secondarie – consente al Gateway di creare dinamicamente entità interne se sono collegate all'interno del file csv. Un buon esempio di ciò potrebbe essere l'importazione di una formula che elenchi le merci non già presenti nel database. In questo caso il Gateway creerà per noi queste entità "figlie", a condizione che venga fornita la chiave primaria per la merce (codice).
• Ignora intestazioni – forza il Gateway a saltare la prima riga (riga) di un csv importato. Ciò è utile se il file di intestazione è incluso nel file di importazione CSV.
• Livello di convalida – imposta la modalità di convalida dei dati quando vengono importati dal Gateway. Ci sono 2 opzioni qui:
  • Dai un avvertimento – Se esiste un errore in un file e non è possibile importare una riga, il sistema te lo informerà ma continuerà a tentare di elaborare il resto del file.
  • abortire – Se esiste un errore in un file e la riga non può essere importata, il sistema interromperà il processo e informerà dell'errore.

Le modifiche alle impostazioni possono quindi essere applicate nella parte in alto a destra di questo pannello. È necessario riavviare Control Center affinché le modifiche abbiano effetto.

L'esportazione tramite il metodo di condivisione file CSV è in gran parte gestita dal file di intestazione e dalle informazioni richieste dal sistema. Se li strutturiamo correttamente utilizzando il manuale API, dovremmo ricevere tutti i dati che desideriamo nell'ordine corretto.

All'interno del Gateway stesso possiamo anche impostare le opzioni rispetto al processo di esportazione:

Qui possiamo utilizzare le caselle di controllo fornite per selezionare quali dati desideriamo esportare, a seconda dei punti dati che desideriamo vedere.

Tieni presente che le classi di database iniziali qui, come ‘BatchConsumption’ e ‘SystemLogs’ sono diversi da quelli con cui inizieremmo per le importazioni, ma a condizione che siamo in grado di navigare con successo nel manuale API per queste classi, possiamo produrre un file di intestazione adatto.

Una volta selezionato ciò che vogliamo esportare, è sufficiente inserire un intervallo di esportazione (in millisecondi) in alto a sinistra e applicare questo valore (0 non esporterà mai) in alto a destra. È necessario riavviare Control Center affinché le modifiche abbiano effetto.

I file CSV esportati verranno inseriti in ‘<installdir>\SG Control Center\gateway\export’ by default.

Indipendentemente dalla metodologia utilizzata per l'integrazione con V5 Traceability, la frequenza e il livello di automazione delle importazioni ed esportazioni di dati sono un elemento del processo che può essere costruito per soddisfare le esigenze di ciascun cliente.

Questa operazione può essere eseguita manualmente dal cliente o automatizzata per acquisire l'output da un ERP esterno da una posizione specifica sul server del cliente.

In questa fase è anche possibile imporre un ordine specifico di importazione, quindi ad esempio potremmo importare una distinta base prima di un ordine di lavoro relativo a quella distinta base. Potremmo farlo caricando i file in sequenza nella directory di importazione o negli endpoint URI API.

Come mostrato sopra, possiamo anche impostare il Gateway per l'esportazione a intervalli specifici per inviare nuovamente i dati al sistema ERP.

Le importazioni e le esportazioni possono essere gestite quasi in tempo reale o eseguite a intervalli prestabiliti. Utilizzando il percorso API, sia le importazioni che le esportazioni possono essere gestite più facilmente quasi in tempo reale. La frequenza di importazione per il metodo di condivisione di file CSV dipende dalla singola soluzione ERP/middleware implementata, mentre la frequenza di esportazione viene gestita tramite Control Center come descritto sopra.

Sei interessato alla tracciabilità V5 e all'integrazione dei dati che fornisce? Contatta il nostro team di vendita Qui.!