Come sviluppare un add-on per SAP Business One: UI API, DI API o Service Layer, e come distribuirlo

SAP Business One copre bene i processi standard, ma ogni azienda ha alcuni passaggi che le maschere standard non gestiscono: la scansione degli articoli in una consegna, un’approvazione particolare, il calcolo delle provvigioni, un collegamento alla fatturazione elettronica o un registro delle chiamate accanto alla scheda cliente. Un add-on è il modo per aggiungere questi passaggi senza uscire da SAP Business One.

Questa guida spiega come si sviluppano oggi gli add-on, quale API usare per che cosa e come consegnarne uno di cui gli utenti si fidino.

Che cos’è un add-on

Un add-on è un programma separato che SAP Business One avvia quando un utente effettua l’accesso. Si collega al client in esecuzione e può:

• aggiungere menu e maschere native che hanno l’aspetto e il comportamento delle maschere SAP standard,
• reagire agli eventi delle maschere standard, per esempio quando un utente aggiunge un ordine cliente,
• leggere e scrivere dati aziendali tramite gli oggetti di business di SAP, con gli stessi controlli del client.

Gli utenti non devono installare nulla. L’add-on viene registrato una sola volta e SAP Business One lo distribuisce a ogni postazione.

Le tre API e quando usare ciascuna

Un tipico add-on client usa la UI API per l’interfaccia e la DI API per i dati, e ottiene la connessione DI dalla UI API, così condivide la sessione e la licenza dell’utente. La logica che deve girare senza un utente collegato (una sincronizzazione notturna, un portale, una coda di fatturazione elettronica) va invece sul server e comunica con il Service Layer.

Leggere i dati con query SQL va bene ed è spesso il modo più rapido per popolare una maschera. La scrittura invece deve passare dalla DI API o dal Service Layer, così giacenze, registrazioni contabili, approvazioni e log delle modifiche restano corretti.

Maschere native, non finestre separate

Gli utenti si aspettano che la maschera di un add-on sembri SAP: gli stessi campi, la stessa Choose From List, lo stesso comportamento della tastiera. La UI API costruisce maschere con griglie, campi di testo, caselle combinate e pulsanti disegnati dal client stesso. Una finestra Windows separata aperta dall’add-on risulta estranea, non segue le impostazioni SAP dell’utente e spesso viene rifiutata dagli utenti.

Due dettagli rendono naturali le maschere native:

• Choose From List su campi come cliente, articolo od ordine, filtrata su ciò che ha senso (solo ordini aperti, solo i documenti di quel cliente).
• Congelare la maschera mentre viene costruita o aggiornata, così compare in un unico passaggio invece di disegnarsi elemento per elemento.

Salvi i suoi dati in UDF e UDT

La maggior parte degli add-on ha bisogno di qualche campo o tabella in più. SAP Business One lo consente senza modificare le proprie tabelle:

• I campi definiti dall’utente (UDF) aggiungono colonne a oggetti esistenti, per esempio lo stato della fattura elettronica sulla fattura cliente o una percentuale di provvigione sull’addetto alle vendite.
• Le tabelle definite dall’utente (UDT) contengono i dati propri dell’add-on, come una tabella di blocchi, un log o una tabella di impostazioni.

Li crei dall’add-on all’avvio (saltando quelli già presenti), così una nuova società li riceve automaticamente. Usi nomi brevi: SAP limita a 30 caratteri la descrizione di una UDT, e una descrizione più lunga può impedire la creazione della tabella.

Eventi: dove si nasconde la maggior parte dei bug

Un add-on reagisce agli eventi: un clic su un menu, la pressione di un pulsante, la modifica di un valore, l’aggiunta di un documento. Tre regole evitano la maggior parte dei problemi:

1. Gestisca ogni evento a cui si registra e filtri con attenzione. Un filtro eventi che esclude i clic sui menu fa smettere di funzionare in silenzio tutti i menu dell’add-on.
2. Annulli nell’evento “before”, agisca nell’evento “after”. Per bloccare o validare un’azione la annulli prima che SAP la elabori; per aggiungere un’operazione successiva attenda che SAP abbia finito.
3. Ricordi che i dati aggiunti tramite la DI API non generano eventi di interfaccia. Se un altro add-on reagisce quando un utente aggiunge una fattura a video, non vedrà le fatture che il suo add-on registra da codice.

Registrare documenti in modo sicuro

Quando un add-on crea documenti, per esempio una fattura da una consegna scansionata, lo faccia come lo farebbe SAP:

• Basi il nuovo documento su quello di origine (ordine → consegna → fattura), così prezzi, imposte e quantità aperte vengono riportati automaticamente.
• Usi una transazione quando un’unica azione crea più documenti, così vengono registrati tutti oppure nessuno.
• Legga tutto ciò che le serve prima di avviare la transazione. Una ricerca fallita all’interno di una transazione DI API può far fallire il commit finale.
• Controlli ogni codice di ritorno e mostri all’utente il messaggio di errore di SAP, non un generico “qualcosa è andato storto”. Il significato dei codici più comuni (-5002, -1029, -2035, -5006) è spiegato in Codici di errore della DI API di SAP B1.

Pacchetto e distribuzione con l’Extension Manager

Gli add-on si consegnano come estensioni:

1. Compili l’add-on con la stessa architettura del client (64 bit per gli attuali client di SAP Business One 10.0).
2. Crei il pacchetto con ExtensionPackage.exe dell’SDK. Il pacchetto è uno zip con il programma, i suoi file e un file di registrazione (.ard). Il nome dello zip diventa il nome dell’estensione.
3. Nell’Extension Manager (System Landscape Directory) importi lo zip, lo assegni alla società e scelga se avviarlo automaticamente per gli utenti.
4. Per una nuova versione importi uno zip con lo stesso nome e una versione più alta. L’Extension Manager lo tratta come un aggiornamento e conserva la versione precedente per un eventuale ripristino.

Usi un numero di versione sempre crescente, come 2026.1021.1530 (anno, mese e giorno, ora). Non cambi mai il nome dell’estensione dopo la prima importazione, altrimenti gli utenti si ritrovano una seconda copia di ogni menu.

Test prima che lo vedano gli utenti

• Testi su una copia della società, mai solo in produzione.
• Testi con un utente normale, non solo con l’account manager; le autorizzazioni cambiano ciò che gli utenti possono fare.
• Se supporta entrambi i database, testi su SQL Server e SAP HANA: HANA confronta i testi distinguendo maiuscole e minuscole e usa un dialetto SQL diverso, che rompe query funzionanti su SQL Server.
• Scriva un file di log su ogni postazione. Quando un utente dice “il pulsante non fa nulla”, il log risponde in pochi minuti.
• Dopo ogni aggiornamento di SAP Business One, ritesti l’add-on sulla copia prima di aggiornare la produzione.

Errori comuni

Come sviluppiamo gli add-on in Kodenova

Sviluppiamo add-on per SAP Business One su SQL Server e SAP HANA: maschere native tramite la UI API, registrazioni tramite la DI API, pacchetti per l’Extension Manager e un log su ogni postazione. Tra gli esempi ci sono un add-on di telefonia per un’azienda manifatturiera tedesca, un bridge per la fatturazione elettronica ZATCA e un portale per le provvigioni di vendita. Ogni progetto ha un prezzo fisso per fase e tre mesi di assistenza gratuita dopo la messa in produzione.

Se il lavoro va svolto fuori dal client, per esempio un portale clienti o un’app mobile, veda Sviluppo SAP Business One e la guida al Service Layer.

Sources

• SAP Help Portal: documentazione di SAP Business One (SDK, DI API, UI API)
• SAP Help Portal: Working with SAP Business One Service Layer (PDF)
• SAP Learning: Leveraging the SAP Business One Service Layer

Related services

• Sviluppo SAP Business One