Integrazione Ocmis - SAP¶

Panoramica¶

L'integrazione tra gli applicativi Irriverso (IPD, ASSIST/Service) e l'ecosistema Ocmis (SAP ERP, Windchill PLM, Component Engine) definisce un'architettura di scambio dati basata su web-service esposti da Irriverso e driver di collegamento installati in rete Ocmis.

Contesto degli applicativi coinvolti:

Sistema	Ruolo
IPD	Configuratore d'offerta Irriverso
ASSIST (Service)	Gestore del service Irriverso
SAP	ERP aziendale Ocmis
Windchill	PLM aziendale Ocmis
Component Engine	Weborder ricambi

Parte del web-service ASSIST era gia' stata realizzata durante la precedente integrazione ASSIST-BMS e viene estesa. Il web-service IRRIVERSO e' completamente da realizzare come infrastruttura base riutilizzabile anche per future integrazioni con prodotti terzi.

Analisi iniziale condivisa con il cliente¶

Documento di analisi iniziale condiviso con Ocmis disponibile al link interno di progetto.

Aspetti preliminari¶

Architettura¶

Infrastrutturalmente sono previste due nuove istanze Linux:

Istanza	Collocazione	Funzione
WEBSERVICE Irriverso	Cloud Irriverso	Espone le API ai sistemi Ocmis
DRIVER	Rete Ocmis	Si collega ai web-service di SAP e PLM (pubblici o intranet)

Tutte le fasi di sviluppo, testing alpha e testing beta possono essere realizzate sull'ambiente di TEST, senza intaccare la produzione.

Le implementazioni si raggruppano in quattro macro-argomenti:

Web-service: nuovi web-service Irriverso e modifiche a web-service esistenti per consentire la connessione di software esterni.
Driver di collegamento: driver tra i web-service Irriverso e quelli esposti da SAP e Windchill.
Modifiche a IPD: modifiche all'applicativo IPD per attivare i collegamenti agli altri gestionali.
Interfacciamento con Component Engine: modifiche in IPD per abilitare il flusso verso Component Engine.

Specifiche DERGA¶

Documenti di riferimento forniti da DERGA:

OCMIS_AT_GAPO2C10_IF SAP IRRIVERSO_v1.docx
OCMIS_AT_GAPO2C02_IF SAP ASSIST_v1.docx

Endpoint di sviluppo SAP: https://dev.sap.farmfront.com (utente EUROSYSTEM).

Web-service esposti da Irriverso¶

Clienti (IPD)¶

Lato Service il web-service esiste gia'; da verificare la presenza di tutti i dati necessari.

Metodo pubblico	Direzione	Descrizione
POST /v1/cliente	SAP -> IPD	Inserimento/aggiornamento cliente

Creazione articoli configurati (IPD)¶

Metodo pubblico	Direzione	Descrizione
GET /v1/articolo/up	IPD -> PLM	Espone tutti gli articoli aggiornati
POST /v1/articolo/ack	PLM -> IPD	Conferma esportazione articolo, lo smarca dagli aggiornati

Distinte articoli configurati (IPD)¶

Metodo pubblico	Direzione	Descrizione
GET /v1/distinta/up	IPD -> PLM	Espone tutte le distinte aggiornate; solo quelle con tutti gli articoli gia' sincronizzati e (se il componente e' a sua volta distinta) gia' sincronizzata
POST /v1/distinta/ack	PLM -> IPD	Conferma esportazione distinta, la smarca dalle aggiornate

Pagamenti (Service)¶

Metodo pubblico	Direzione	Descrizione
GET /v1/pagamento/up	SERVICE -> SAP	Espone i pagamenti effettuati con collegamenti agli interventi eseguiti
POST /v1/pagamento/ack	SAP -> SERVICE	Conferma esportazione pagamento, lo smarca dagli aggiornati

Driver di collegamento¶

Tabella riepilogativa degli undici driver previsti:

Driver	Direzione	Sorgente dati SAP/PLM	Destinazione
Clienti	SAP -> Irriverso	Business partner SAP	WS Clienti Irriverso
Creazione articoli configurati	IPD -> PLM	WS articolo/up	WS PLM
Distinte articoli configurati	IPD -> PLM	WS distinta/up	WS PLM
Matricole	SAP -> Irriverso	API_EQUIPMENT	WS Matricole Irriverso
Articoli Service	SAP -> Irriverso	WS Articoli SAP (canale 20 Post sales)	WS Articoli Irriverso
Prestazioni	SAP -> Irriverso	WS Prestazioni SAP	WS Prestazioni Irriverso
Listini e sconti	SAP -> Irriverso	WS Pricing SAP	WS Listini e Sconti Irriverso
Giacenze di magazzino	SAP -> Irriverso	WS Giacenze SAP	WS Giacenze Irriverso
Richieste di intervento	SAP -> Irriverso	Ordini di servizio SAP	WS chiamate/interventi Irriverso
Aggiornamento ordini di servizio	Irriverso -> SAP	WS interventi Irriverso	API "Aggiornamento ordini di servizio" SAP
Interventi eseguiti	Irriverso -> SAP	WS Interventi Irriverso	WS SAP
Richieste di addebito (pagamenti)	Irriverso -> SAP	WS Pagamenti Irriverso	WS SAP (con blocco Maintenance_Order)
Creazione avvisi di servizio	Irriverso -> SAP	WS Chiamate Irriverso	WS SAP

Clienti¶

Non essendoci piu' la possibilita' di ricevere notifiche da SAP sull'aggiornamento di un cliente, il driver interroga ciclicamente il web-service "Clienti". La lettura e' differenziale per data/ora aggiornamento.

Destinatari e Contatti sono identificati da SAP come Business partner, presenti come singole righe nelle query e associati al cliente nell'apposita query.

Campi minimi indispensabili (eventualmente ripetuti per canale vendita):

Codice cliente SAP
Dati anagrafici principali (indirizzo, CAP, localita', provincia, stato estero)
Partita IVA
Codice fiscale
Codice di pagamento
E-mail
Indirizzi / Destinazioni: codice, dati anagrafici, e-mail
Contatti: codice, nome/cognome, e-mail, telefono/interno, cellulare, posizione/ruolo (codificato)

Creazione articoli configurati¶

IPD invia a PLM i codici di livello 0 (configurati finiti) e livello 1 (primi componenti di distinta). I componenti di livello 2 vengono generati direttamente da PLM e non arrivano a IPD.

Suggerimento PLM: PLM espone un web-service interrogato da IPD per verificare l'esistenza di un articolo. Se almeno un articolo non esiste, la struttura dati non puo' passare e viene contattato l'UT per la creazione in PLM; il passaggio della distinta deve essere ritentato.

Struttura articolo:

Codice articolo
Descrizione
UM
Altri campi da definire in coordinamento PLM-SAP (eventuali campi provenienti dal configuratore gia' disponibili in IPD)

Flusso del driver: interroga gli aggiornamenti (solo inserimenti) tramite v1/articolo/up e per ciascun articolo chiama il web-service PLM per l'inserimento; in caso di esito positivo chiama /v1/articolo/ack, altrimenti attiva il sistema di segnalazioni lasciando l'articolo invariato.

Distinte articoli configurati¶

Per un prodotto finito nuovo viene inviata anche la distinta relativa (livello 0 e figli livello 1).

Struttura distinta:

Codice padre
Codice figlio
Quantita'

Flusso: interroga v1/distinte/up, chiama il web-service PLM, in caso positivo invoca /v1/distinta/ack.

Matricole¶

Il driver interroga il web-service SAP "equipment/numeri di serie" (API_EQUIPMENT) per recuperare gli aggiornamenti alle matricole d'assistenza (le macchine). Viene aggiunto un "Codice host" sulla tabella Irriverso come collegamento.

Chiamata: /sap/opu/odata/sap/API_EQUIPMENT

Campi minimi:

API_EQUIPMENT
Serial number
Codice modello
Marca (Brand)
Codice cliente
Codice ubicazione/destinazione
Anno di costruzione
Inizio/fine garanzia
Descrizione

Alcune informazioni aggiornate (es. periodo di garanzia) possono essere restituite a SAP.

Articoli Service¶

Il driver interroga il web-service SAP "Articoli" filtrando il settore Service, con filtro per "Tipo materiale":

Tipo materiale	Descrizione
ROH	Materie prime
HALB	Semilavorati
DIEN	Servizi vendita
FERT	Prodotti finiti (matricole)

Interrogabile per data/ora aggiornamento. Gli articoli necessari sono del canale "20 Post sales".

Campi minimi: codice SAP, tipo materiale, descrizione, unita' di misura, eventuale descrizione estesa.

Prestazioni¶

Il driver interroga il web-service SAP "Prestazioni" e aggiorna il DB Irriverso tramite l'apposito web-service. Potrebbe coincidere con il web-service utilizzato per i materiali.

Listini e sconti¶

Il driver interroga il web-service SAP "Pricing" considerando solo articoli di competenza del service e relativi sconti, aggiornandoli sui web-service "Listini" e "Sconti" Irriverso.

Attenzione: non e' possibile interrogare per data/ora aggiornamento, quindi il driver deve recuperare ad ogni chiamata (o in sotto-chiamate) tutti i dati e valutare se aggiornare. Da valutare attentamente il formato dei dati restituiti per ottimizzare l'importazione.

Condizione base: PPR0 (prezzo base).

Giacenze di magazzino¶

Il driver interroga il web-service SAP "Giacenze" per recuperare gli aggiornamenti. I furgoni sono identificati come "ubicazioni" all'interno del magazzino ricambi.

Richieste di intervento¶

Il driver interroga il web-service SAP "Ordini di servizio" per aggiornare la struttura chiamate/interventi Irriverso.

Filtri:

Tipologie di ordine: ZASP, ZASG, ZRST, ZCLP, ZCLG
"Tipo attivita' PM" (tipo intervento), escludendo ad esempio gli interventi da remoto
Solo ordini in stato "Rilasciato"

Estrazione possibile per data/ora ultima modifica; considera anche gli interventi inviati da Irriverso.

Campi necessari: Id ordine SAP, cliente, destinazione/ubicazione, data richiesta, data richiesto intervento, eventuale tecnico pre-assegnato, descrizione chiamata, data assegnazione, priorita'/data limite, EQUIPMENT, dettaglio prestazioni (codice + quantita'), dettaglio materiali previsti (codice + quantita').

Aggiornamento ordini di servizio¶

Driver invocato dopo l'assegnazione da parte del Service, o dopo una modifica che interessi:

Tecnico
Data/ora assegnazione
Furgone (centro di lavoro)

Utilizza l'API SAP specifica "Aggiornamento ordini di servizio".

Interventi eseguiti¶

Il driver preleva dal web-service "Interventi" di Irriverso gli interventi eseguiti e li esporta su SAP. SAP riceve prestazioni diverse tra costi e ricavi; tutte le prestazioni eseguite devono essere previste e la stessa prestazione puo' essere diversificata per tecnico e data intervento.

Criteri:

Prestazione eseguita: relazione con la prestazione "costo" gestita su SAP, con conferma finale.
Modifiche post-chiusura: gestite solo lato SAP.
Materiali: API separata (ManufacturingOrder) invocata alla chiusura dell'intervento. I materiali utilizzati possono essere previsti oppure scelti nella dotazione del furgone.

Richieste di addebito (pagamenti)¶

Quando il tecnico riceve un pagamento diretto dal cliente assistito viene generato un pagamento. Il driver preleva i pagamenti dal web-service "Pagamenti" Irriverso e li esporta su SAP. L'ordine deve essere "bloccato" tramite chiamata all'API Maintenance_Order in modo che per quell'intervento la fatturazione arrivi dalla richiesta di addebito.

Vincolo: non e' possibile ricevere pagamenti se non sull'intervento in corso.

Campi necessari: Id ordine SAP, eventuale sconto a valore assoluto, dettaglio prestazioni/materiali (codice, quantita', prezzo, UM).

Caso prezzo concordato non riconducibile alla somma dei prezzi delle singole voci:

L'addebito va dettagliato con le stesse righe dell'ordine di servizio ma il codice prestazione deve essere il CM VENDITA, associato manualmente al codice di servizio interno tramite tabella gestita manualmente.
Necessaria la modifica su APP per gestire il dettaglio dell'incasso.
Eventuale sconto esplicitato come sconto assoluto (a valore), passato nel body della chiamata API.
Condizione da usare: ZHMO (vedi documentazione DERGA).

Creazione avvisi di servizio¶

Il driver preleva dal web-service "Chiamate" di Irriverso le nuove chiamate da parte di un dealer e le esporta su SAP.

Campi necessari: Id chiamata Assist, cliente, destinazione/ubicazione, data richiesta, data richiesto intervento, eventuale tecnico pre-assegnato, descrizione chiamata, data assegnazione, priorita'/data limite, EQUIPMENT, dettaglio prestazioni (codice + quantita'), dettaglio materiali previsti (codice + quantita').

Step operativi di realizzazione¶

Component Engine (SAP -> Irriverso -> CE -> SAP)¶

Abilita l'autenticazione di un utente per effettuare un ordine di ricambi su Component Engine.

Flusso:

L'utente entra su Irriverso
L'utente chiede di effettuare un ordine di ricambi
Parte la richiesta del token Irriverso -> CE, gia' comprensiva dei dati cliente
CE richiede l'autenticazione a Auth0
Auth0 restituisce a CE le informazioni di autenticazione
Se tutto e' ok, l'utente puo' effettuare l'ordine
L'ordine viene spedito a SAP

Il flusso presuppone che Irriverso abbia gia' aggiornato i dati cliente tramite il driver dedicato.

Moduli necessari:

WS Clienti
Driver "Clienti" (acquisizione dati cliente da SAP a Irriverso)

Vincoli operativi:

Macchina driver in rete Ocmis con accesso alle API SAP (completato).
Accesso al WS di SAP da coordinare con Derga: valutare i dati di contatti e indirizzi e se SAP ha tabelle/importazioni separate (PCASE-4228).
Call con CE: definizione di domini e gestione su Irriverso (coordinamento con Scaglioni su stato attuale BMS), e definizione tecnica dello scambio dati.

IPD (SAP -> Irriverso; PLM -> Irriverso)¶

Abilita la ricezione dei dati da SAP e PLM per la realizzazione dei progetti in IPD.

Flusso:

Un utente IPD crea il progetto di una nuova macchina
Il progetto viene confermato e diventa un'Offerta
Invio dati a PLM: nuovi codici (prodotto finito e semilavorati) e distinte base collegate
Invio mail con l'Offerta
PLM invia i codici creati a SAP

Service (SAP -> Irriverso -> SAP)¶

Abilita la connessione bidirezionale del modulo Service con SAP.

Modifiche IPD¶

Progettazione¶

Al termine della progettazione e della creazione dell'offerta, segue l'invio dell'offerta come PDF con i codici articoli precedentemente passati a PLM. Si deve implementare la logica di scrittura dell'offerta, delle distinte base e dei nuovi articoli semilavorati in apposite tabelle sincronizzate con SAP tramite i meccanismi descritti.

Agente ricambi¶

IPD puo' essere utilizzato come configuratore di ricambi da un'utenza "agente ricambi" (personale interno Ocmis). A differenza delle altre utenze, il canale del cliente destinatario dell'offerta e' il canale Post-Sales. Non sono necessarie modifiche sulla quantita' ordinabile: l'offerta viene inserita come ordine manualmente in SAP.

Utilizzo da parte di agenti interni¶

IPD puo' essere utilizzato da personale interno Ocmis per creare offerte al cliente "rivenditore", che va selezionato e indicato nell'offerta (nella gestione standard l'utilizzatore coincide con il cliente).

Make to Stock¶

L'agente interno puo' configurare articoli da produrre senza finalita' di vendita. Si effettua un'offerta a "cliente interno" (Ocmis); pur salvando l'ambiente come Offerta in IPD, viene esportata solo la struttura "Articolo + distinte base".

Implementazioni aggiuntive¶

Consultazione macchine: aggiunto il codice articolo attribuito a ciascuna macchina.
Cicli standard: la gestione dei cicli di produzione non e' piu' necessaria poiche' e' effettuata direttamente dal PLM.
Metadati articoli configurazione: IPD puo' definire metadati collegati agli articoli di configurazione, utilizzati per caratterizzare i prodotti configurati e trasmessi al PLM.

Interfaccia con Component Engine¶

In Irriverso e' prevista una procedura di autenticazione verso il Web Order articolata in due parti:

Irriverso contatta il Web Order inviando un token di autenticazione per l'utente X.
Il Web Order utilizza il token ricevuto ricontattando Irriverso e ottenendo in risposta le informazioni dell'utente.

Contenuto del JSON¶

Irriverso, durante l'autenticazione del cliente al Web Order, passa a Component Engine:

Dati dell'anagrafica cliente canale "POST-SALES" (ricevuta da SAP):
- Dati anagrafici di base
- Destinazioni
- Tipo pagamento
- Vettori autorizzati
- Modalita' di spedizione
Domini dell'utente sul Web Order (autorizzazioni operative su Component Engine).

Modifiche da realizzare¶

Irriverso: gestione dei domini "Component Engine" da attribuire all'utente.
SSO: implementazione del JSON da passare a Component Engine dopo l'autenticazione.

Processi manuali¶

Alcuni archivi di base non sono stati automatizzati nella sincronizzazione e restano manuali:

Codici pagamento
Stati esteri
Modelli matricole
Tipi attivita' di assistenza
Tecnici
Automezzi
Anagrafiche magazzini
Codici IVA
Stati chiamata

Tutti i flussi operativi manuali non esplicitati in sincronizzazione nel presente documento restano invariati.