How to build an SAP Business One add-on: UI API, DI API or Service Layer, and how to ship it

SAP Business One covers the standard processes well, but every company has a few steps that the standard screens do not handle: scanning items into a delivery, a custom approval, a commission calculation, an e-invoicing connection or a call log next to the customer card. An add-on is how you add those steps without leaving SAP Business One.

This guide explains how add-ons are built today, which API to use for what, and how to deliver one that users trust.

What an add-on is

An add-on is a separate program that SAP Business One starts when a user logs in. It connects to the running client and can:

• add menus and native screens that look and behave like standard SAP forms,
• react to events on standard screens, for example when a user adds a sales order,
• read and write business data through SAP’s own business objects, with the same checks as the client.

Users do not install anything themselves. The add-on is registered once and SAP Business One distributes it to each workstation.

The three APIs and when to use each

A typical client add-on uses the UI API for the screen and the DI API for the data, and gets the DI connection from the UI API so it shares the user’s session and licence. Logic that must run without a user logged in (a nightly sync, a portal, an e-invoicing queue) belongs on the server and talks to the Service Layer instead.

Reading data with SQL queries is fine and often the fastest way to fill a screen. Writing must go through the DI API or the Service Layer so that stock, journal entries, approvals and the change log stay correct.

Native screens, not separate windows

Users expect an add-on screen to look like SAP: the same fields, the same Choose From List, the same keyboard behaviour. The UI API builds forms with grids, edit fields, combo boxes and buttons that the client draws itself. A separate Windows window opened by the add-on feels foreign, does not follow the user’s SAP settings and is often rejected by users.

Two details make native screens feel right:

• Choose From List on fields such as customer, item or order, filtered to what makes sense (only open orders, only this customer’s documents).
• Freezing the form while it is built or refreshed, so it appears in one step instead of drawing item by item.

Store your own data in UDFs and UDTs

Most add-ons need a few extra fields or tables. SAP Business One supports this without changing its own tables:

• User-defined fields (UDFs) add columns to existing objects, for example an e-invoice status on the A/R invoice or a commission rate on the sales employee.
• User-defined tables (UDTs) hold the add-on’s own data, such as a lock table, a log or a settings table.

Create them from the add-on at start-up (and skip those that already exist), so a new company gets them automatically. Keep names short: SAP limits UDT descriptions to 30 characters, and a longer one can stop the table from being created.

Events: where most add-on bugs live

An add-on reacts to events: a menu click, a button press, a value change, a document being added. Three rules prevent most problems:

1. Handle every event you register for, and only filter carefully. An event filter that leaves out menu clicks makes every menu of the add-on silently stop working.
2. Cancel in the “before” event, act in the “after” event. To block or validate an action, cancel it before SAP processes it; to add follow-up work, wait until SAP has finished.
3. Remember that data added through the DI API does not raise screen events. If another add-on reacts when a user adds an invoice on screen, it will not see invoices your add-on posts in code.

Posting documents safely

When an add-on creates documents, for example an invoice from a scanned delivery, do it like SAP would:

• Base the new document on the source (order → delivery → invoice) so prices, taxes and open quantities flow automatically.
• Use a transaction when one action creates several documents, so either all are posted or none.
• Read everything you need before the transaction starts. A failed lookup inside a DI API transaction can make the final commit fail.
• Check every return code and show SAP’s own error message to the user, not a generic “something went wrong”.

Packaging and deployment with the Extension Manager

Add-ons are delivered as extensions:

1. Build the add-on for the same bitness as the client (64-bit for current SAP Business One 10.0 clients).
2. Package it with ExtensionPackage.exe from the SDK. The package is a zip with the program, its files and a registration file (.ard). The zip name becomes the extension name.
3. In the Extension Manager (System Landscape Directory), import the zip, assign it to the company and choose whether it starts automatically for users.
4. For a new version, import a zip with the same name and a higher version. The Extension Manager treats it as an upgrade and keeps the old version for rollback.

Use a version number that always increases, such as 2026.1021.1530 (year, month and day, time). Never change the extension name after the first import, or users get a second copy of every menu.

Testing before users see it

• Test on a copy of the company, never only on production.
• Test with a normal user, not only with the manager account; authorizations change what users can do.
• If you support both databases, test on SQL Server and SAP HANA: HANA compares text case-sensitively and uses a different SQL dialect, which breaks queries that work on SQL Server.
• Write a log file on each workstation. When a user says “the button does nothing”, the log answers in minutes.
• After every SAP Business One upgrade, re-test the add-on on the copy before upgrading production.

Common mistakes

How we build add-ons at Kodenova

We build SAP Business One add-ons on SQL Server and SAP HANA: native screens through the UI API, posting through the DI API, Extension Manager packages, and a log on every workstation. Examples include a telephony add-on for a German manufacturer, a ZATCA e-invoicing bridge and a sales commission portal. Every project has a fixed price per phase and three months of free support after go-live.

If the work belongs outside the client, for example a customer portal or a mobile app, see SAP Business One development and the Service Layer guide.

Sources

• 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

Related services

• SAP Business One development