SAP Business One Add-on entwickeln: UI API, DI API oder Service Layer und wie Sie es ausliefern

SAP Business One deckt die Standardprozesse gut ab, doch jedes Unternehmen hat einige Arbeitsschritte, die die Standardmasken nicht abbilden: Artikel in eine Lieferung scannen, eine eigene Genehmigung, eine Provisionsberechnung, eine Anbindung an die E-Rechnung oder ein Anrufprotokoll neben der Kundenstammkarte. Mit einem Add-on ergänzen Sie diese Schritte, ohne SAP Business One zu verlassen.

Dieser Leitfaden erklärt, wie Add-ons heute entwickelt werden, welche API wofür geeignet ist und wie Sie ein Add-on ausliefern, dem die Benutzer vertrauen.

Was ein Add-on ist

Ein Add-on ist ein eigenständiges Programm, das SAP Business One beim Anmelden eines Benutzers startet. Es verbindet sich mit dem laufenden Client und kann:

• Menüs und native Masken hinzufügen, die wie Standardformulare von SAP aussehen und sich auch so verhalten,
• auf Ereignisse in Standardmasken reagieren, zum Beispiel wenn ein Benutzer einen Kundenauftrag hinzufügt,
• Geschäftsdaten über SAPs eigene Geschäftsobjekte lesen und schreiben, mit denselben Prüfungen wie der Client.

Die Benutzer installieren nichts selbst. Das Add-on wird einmal registriert, und SAP Business One verteilt es an jeden Arbeitsplatz.

Die drei APIs und wann Sie welche einsetzen

Ein typisches Client-Add-on nutzt die UI API für die Oberfläche und die DI API für die Daten und bezieht die DI-Verbindung über die UI API, sodass es Session und Lizenz des Benutzers mitverwendet. Logik, die ohne angemeldeten Benutzer laufen muss (ein nächtlicher Abgleich, ein Portal, eine Warteschlange für die E-Rechnung), gehört auf den Server und spricht stattdessen mit dem Service Layer.

Daten per SQL-Abfrage zu lesen ist in Ordnung und oft der schnellste Weg, eine Maske zu füllen. Schreiben muss dagegen über die DI API oder den Service Layer laufen, damit Lagerbestand, Buchungssätze, Genehmigungen und das Änderungsprotokoll korrekt bleiben.

Native Masken statt separater Fenster

Benutzer erwarten, dass eine Add-on-Maske wie SAP aussieht: dieselben Felder, dieselbe Auswahlliste (Choose From List), dasselbe Tastaturverhalten. Die UI API erstellt Formulare mit Grids, Eingabefeldern, Kombinationsfeldern und Schaltflächen, die der Client selbst zeichnet. Ein separates Windows-Fenster, das das Add-on öffnet, wirkt fremd, folgt nicht den SAP-Einstellungen des Benutzers und wird von den Anwendern oft abgelehnt.

Zwei Details sorgen dafür, dass sich native Masken richtig anfühlen:

• Choose From List an Feldern wie Kunde, Artikel oder Auftrag, gefiltert auf das Sinnvolle (nur offene Aufträge, nur Belege dieses Kunden).
• Einfrieren des Formulars, während es aufgebaut oder aktualisiert wird, damit es in einem Schritt erscheint, statt Element für Element gezeichnet zu werden.

Eigene Daten in UDFs und UDTs speichern

Die meisten Add-ons brauchen einige zusätzliche Felder oder Tabellen. SAP Business One unterstützt das, ohne die eigenen Tabellen zu verändern:

• Benutzerdefinierte Felder (UDFs) ergänzen bestehende Objekte um Spalten, zum Beispiel einen E-Rechnungs-Status an der Ausgangsrechnung oder einen Provisionssatz am Vertriebsmitarbeiter.
• Benutzerdefinierte Tabellen (UDTs) speichern die eigenen Daten des Add-ons, etwa eine Sperrtabelle, ein Protokoll oder eine Einstellungstabelle.

Legen Sie sie beim Start des Add-ons an (und überspringen Sie bereits vorhandene), damit ein neuer Mandant sie automatisch erhält. Halten Sie die Namen kurz: SAP begrenzt UDT-Beschreibungen auf 30 Zeichen, und eine längere Beschreibung kann verhindern, dass die Tabelle angelegt wird.

Ereignisse: Hier stecken die meisten Add-on-Fehler

Ein Add-on reagiert auf Ereignisse: einen Menüklick, einen Klick auf eine Schaltfläche, eine Wertänderung, das Hinzufügen eines Belegs. Drei Regeln verhindern die meisten Probleme:

1. Behandeln Sie jedes registrierte Ereignis, und filtern Sie nur mit Bedacht. Ein Ereignisfilter ohne Menüklicks lässt jedes Menü des Add-ons stillschweigend ausfallen.
2. Im „Before“-Ereignis abbrechen, im „After“-Ereignis handeln. Um eine Aktion zu blockieren oder zu prüfen, brechen Sie sie ab, bevor SAP sie verarbeitet; für Folgearbeiten warten Sie, bis SAP fertig ist.
3. Denken Sie daran, dass per DI API hinzugefügte Daten keine Maskenereignisse auslösen. Reagiert ein anderes Add-on darauf, dass ein Benutzer eine Rechnung in der Maske hinzufügt, sieht es die Rechnungen nicht, die Ihr Add-on per Code bucht.

Belege sicher buchen

Wenn ein Add-on Belege anlegt, zum Beispiel eine Rechnung aus einer gescannten Lieferung, sollte es so vorgehen wie SAP selbst:

• Basieren Sie den neuen Beleg auf dem Ursprungsbeleg (Auftrag → Lieferung → Rechnung), damit Preise, Steuern und offene Mengen automatisch übernommen werden.
• Verwenden Sie eine Transaktion, wenn eine Aktion mehrere Belege erzeugt, damit entweder alle oder keiner gebucht werden.
• Lesen Sie alles Benötigte, bevor die Transaktion beginnt. Eine fehlgeschlagene Abfrage innerhalb einer DI-API-Transaktion kann das abschließende Commit scheitern lassen.
• Prüfen Sie jeden Rückgabecode und zeigen Sie dem Benutzer die Fehlermeldung von SAP statt eines allgemeinen „Etwas ist schiefgelaufen“. Was die häufigen Codes (-5002, -1029, -2035, -5006) bedeuten, erklärt der Artikel SAP B1 DI API Fehlercodes.

Paketierung und Verteilung mit dem Extension Manager

Add-ons werden als Extensions ausgeliefert:

1. Kompilieren Sie das Add-on in derselben Bitbreite wie der Client (64 Bit für aktuelle SAP Business One 10.0 Clients).
2. Paketieren Sie es mit ExtensionPackage.exe aus dem SDK. Das Paket ist eine ZIP-Datei mit dem Programm, seinen Dateien und einer Registrierungsdatei (.ard). Der Name der ZIP-Datei wird zum Namen der Extension.
3. Importieren Sie die ZIP-Datei im Extension Manager (System Landscape Directory), weisen Sie sie dem Mandanten zu und legen Sie fest, ob sie für die Benutzer automatisch startet.
4. Für eine neue Version importieren Sie eine ZIP-Datei mit demselben Namen und einer höheren Version. Der Extension Manager behandelt sie als Upgrade und behält die alte Version für ein Rollback.

Verwenden Sie eine stets steigende Versionsnummer wie 2026.1021.1530 (Jahr, Monat und Tag, Uhrzeit). Ändern Sie den Namen der Extension nach dem ersten Import nie, sonst erhalten die Benutzer jedes Menü doppelt.

Testen, bevor die Benutzer es sehen

• Testen Sie auf einer Kopie des Mandanten, nie nur im Produktivsystem.
• Testen Sie mit einem normalen Benutzer, nicht nur mit dem Manager-Konto; Berechtigungen verändern, was Benutzer tun können.
• Wenn Sie beide Datenbanken unterstützen, testen Sie auf SQL Server und SAP HANA: HANA vergleicht Text unter Beachtung der Groß- und Kleinschreibung und verwendet einen anderen SQL-Dialekt, an dem Abfragen scheitern, die auf SQL Server funktionieren.
• Schreiben Sie an jedem Arbeitsplatz eine Protokolldatei. Wenn ein Benutzer sagt „Die Schaltfläche macht nichts“, liefert das Protokoll die Antwort in Minuten.
• Testen Sie das Add-on nach jedem Upgrade von SAP Business One erneut auf der Kopie, bevor Sie das Produktivsystem aktualisieren.

Typische Fehler

Wie wir bei Kodenova Add-ons entwickeln

Wir entwickeln SAP-Business-One-Add-ons auf SQL Server und SAP HANA: native Masken über die UI API, Buchungen über die DI API, Pakete für den Extension Manager und ein Protokoll an jedem Arbeitsplatz. Beispiele sind ein Telefonie-Add-on für einen deutschen Fertigungsbetrieb, eine ZATCA-Brücke für die E-Rechnung und ein Provisionsportal für den Vertrieb. Jedes Projekt hat einen Festpreis pro Phase und drei Monate kostenlosen Support nach dem Produktivstart.

Gehört die Arbeit außerhalb des Clients, zum Beispiel ein Kundenportal oder eine mobile App, lesen Sie Entwicklung für SAP Business One und den Service-Layer-Leitfaden.

Quellen

• SAP Help Portal: SAP Business One documentation (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

Passende Leistungen

• Entwicklung für SAP Business One