Mon – Sat: 9:00 AM – 7:00 PM IST
iDempiere

What is an OSGi plugin?

How iDempiere keeps your customisations separate from its core — and why that separation is the whole point.

In short

OSGi is a Java module system that lets components be installed, started and stopped independently. In iDempiere, customisations are packaged as OSGi plugins that register themselves with the core at runtime rather than altering it. The practical consequence is that you can upgrade the core without reapplying your changes, because your changes were never inside it.

Why It Matters

Why this matters in practice

The single most expensive mistake in any ERP is customisation that cannot survive an upgrade. Estates that modify core code end up either frozen on an old version or paying to reapply changes at every release. The plugin model removes that choice: the core is replaced, the plugins are re-deployed, and the boundary between them is explicit.

Core upgrades do not overwrite your customisations
Plugins can be deployed, started and stopped independently
The extension boundary is explicit and documented
Several plugins can coexist without interfering with each other
How It Works

How it works in practice

1

Event handlers

Register against document events — before save, after complete — to add validation or trigger behaviour without touching the base class.

2

Model factories

Override or extend the behaviour of a business object by supplying your own implementation through the factory.

3

Processes and callouts

Custom processes appear in the menu like standard ones; callouts react to field changes in a window.

4

Dictionary packaging

Application dictionary changes travel with the plugin as 2Pack, so configuration and code deploy together.

5

Deployment

The plugin is dropped into the runtime and started. No core rebuild, and it can be stopped if it misbehaves.

Worked example

A worked example: the upgrade that was not an event

Two businesses run the same open-source ERP with similar customisation: additional validation on sales orders, a custom tax calculation, and an integration to a carrier.

The first implemented all three by editing core classes. It works. At the next release, every edited class has to be compared against the new version and the changes merged by hand — by someone who did not write them, from a diff rather than from intent. The upgrade becomes a project with testing, a window and a risk register, and the business starts deferring it. Three releases later it is effectively on a private fork.

The second implemented the same three as OSGi plugins registering services at defined extension points. The core is untouched, so it is replaced wholesale at upgrade. The plugins are tested against the new version and redeployed. The upgrade is a maintenance task rather than a project, which means it actually happens — and the compounding benefit is that the business stays current rather than accumulating a decade of deferred releases.

Key terms

The vocabulary, briefly

Term What it means
Bundle The deployable unit — a JAR with metadata declaring what it provides and requires.
Service A component one bundle publishes for others to use, resolved at runtime rather than compile time.
Lifecycle Bundles can be installed, started, stopped and updated while the application keeps running.
Dependency resolution The framework matching what a bundle needs against what others provide.
Classloader isolation Each bundle has its own classloader, so versions can coexist without conflict.
What Goes Wrong

Common mistakes worth avoiding

Patching core classes 'just this once'

It is never once, and it is never documented. Every subsequent upgrade pays for it.

Configuration drift from the plugin

Dictionary changes made by hand in one environment and by 2Pack in another diverge quietly. Package them.

One enormous plugin

A single plugin containing everything cannot be stopped selectively. Split by functional area.

No version discipline

Plugins need version numbers that track which core release they were built against, or upgrades become guesswork.

What to measure

Numbers worth tracking

Metric What it tells you What distorts it
Core modifications The number that decides whether upgrades are routine or expensive. Target zero.
Plugins with automated tests Whether upgrade verification is a script or a fortnight of manual checking.
Plugin build reproducibility Can every plugin be rebuilt from source today, by someone else? A surprising number cannot.
Time to apply a release The outcome measure. Falling time means the architecture is working.
FAQ

Questions we are asked about this

Yes — through the application dictionary packaged with the plugin. Fields, tabs and validation can be added or altered without editing the base definition by hand.
That is their purpose. They may need recompiling against a new core version if APIs changed, but they are not overwritten the way core modifications are.
For plugin development, yes — and for a surprising amount of real customisation, no. The Application Dictionary covers fields, windows, validation, defaults, references, print formats and reports without code. Java becomes necessary for genuine behaviour: complex business rules, integrations, custom document processing. A sensible implementation uses the dictionary as far as it reaches and Java only beyond it.
The OSGi framework supports installing, updating and stopping bundles in a running system, which is a genuine architectural advantage. In practice most teams still schedule a short window for anything touching document processing, because the technical capability does not remove the need to verify. The benefit is that the window is minutes rather than a maintenance evening.
They need testing against the new version and redeploying, and that is the whole job — which is the point. Where a plugin uses an interface that changed between releases it needs adjusting, and release notes flag those. This is a far smaller and more predictable task than reconciling modified core source, because you are testing your own code against a published interface rather than merging somebody else's changes into yours.
Look for four things, none of which require reading the logic: a build file that produces the bundle reproducibly, a README explaining what it does and why, declared dependencies with versions rather than assumptions, and tests. A plugin delivered as a JAR with no source, no build and no documentation is not an extension — it is a dependency on whoever built it, and that dependency outlasts the contract.
Related

Where to read next

What is iDempiere?

Read more

Our iDempiere consulting

Read more

iDempiere implementation

Read more

Need this applied to your own systems?

We build and support the systems this page describes. Start with a free working proof of concept — no cost, no commitment.