ADR-001: iDempiere Version Compatibility Strategy

Status: Accepted Date: 2024-11-29 Context: CLI generator must produce version-compatible plugins across iDempiere 10, 11, 12, 13, and Custom Fork

Context

The iDempiere CLI generator creates OSGi plugin scaffolds that must be compatible with multiple iDempiere versions. Each version introduces technical changes that affect plugin structure, dependencies, and registration patterns.

This ADR documents version-specific technical changes discovered from the iDempiere Wiki New Features and Release Notes that influence CLI generator behavior.

Decision

The CLI generator will maintain version-aware templates that adapt to the following technical differences:

iDempiere Branch-to-Dependency Mapping

IMPORTANT BUILD RULE: Each iDempiere version is managed as a separate branch in the iDempiere repository. When building the CLI with a specific Maven profile, you must use the corresponding iDempiere branch to get the correct core class mapping.

Branch Naming Convention

Profile iDempiere Branch Artifact Version Java CLI Build Status
-Pv10 release-10 10.0.0-SNAPSHOT 11 ⚠️ Incompatible (Tycho)
-Pv11 release-11 11.0.0-SNAPSHOT 17 ✅ Supported
-Pv12 (default) release-12 12.0.0-SNAPSHOT 17 ✅ Supported
-Pv13 development 13.0.0-SNAPSHOT 21 ✅ Supported

Build Workflow

  1. Clone iDempiere with correct branch:

    # For v12 (default)
git clone -b release-12 https://github.com/idempiere/idempiere.git

# For v13 (latest)
git clone -b development https://github.com/idempiere/idempiere.git

  2. Install iDempiere core to local Maven repository:

    cd idempiere
mvn install -DskipTests

  3. Build CLI with matching profile:

    cd ../cloudempiere-cli
mvn package -Pv12 -DskipTests   # Uses 12.0.0-SNAPSHOT
mvn package -Pv13 -DskipTests   # Uses 13.0.0-SNAPSHOT

Why This Matters

The CLI depends on iDempiere core classes (MTable, MColumn, DisplayType) from org.adempiere.base. These classes have version-specific APIs:

Using mismatched versions will cause compilation errors or runtime failures.

Custom Fork

Custom Fork maintains its own branch structure. When building for Custom Fork:

git clone -b custom-fork-12 https://your-repo/idempiere.git
cd idempiere && mvn install -DskipTests
cd ../cloudempiere-cli && mvn package -Pv12 -DskipTests

Version-Specific Technical Changes

iDempiere 10

Runtime Requirements:

Breaking Changes:

Build System Changes:

CLI Compatibility:

CLI Impact:

Wiki References:

iDempiere 11

Runtime Requirements:

Technical Changes:

Deprecated APIs:

OSGi Factory Patterns (from v9.1, fully adopted in v11):

CLI Impact:

Wiki References:

iDempiere 12

Runtime Requirements:

Dependency Updates:

Technical Changes:

CLI Impact:

Wiki References:

iDempiere 13

Runtime Requirements:

Breaking Changes - Jakarta EE Migration:

Database Changes:

Deprecated APIs:

CLI Impact:

Wiki References:

Custom Fork

Runtime Requirements:

Specific Configuration:

CLI Impact:

OSGi Registration Pattern Evolution

Legacy Pattern (v10 and earlier)

// Plugin Activator registration
public class Activator implements BundleActivator {
    public void start(BundleContext context) {
        Core.getMappedModelFactory().addMapping(
            "XX_MyTable",
            () -> new MXXMyTable(),
            (ctx, rs, trxName) -> new MXXMyTable(ctx, rs, trxName)
        );
    }
}

Modern Pattern (v11+)

@Component
public class MyModelFactory extends AnnotationBasedModelFactory {
    @Activate
    public void activate(BundleContext context) {
        scan(context, "org.mycompany.myplugin.model");
    }
}

@Model(table = "XX_MyTable")
public class MXXMyTable extends PO {
    // ...
}

Available Annotations (v11+)

Extension Type Annotation Package
Process @Process org.adempiere.base.annotation
Model @Model org.adempiere.base.annotation
Callout @Callout org.adempiere.base.annotation
Form @Form org.idempiere.ui.zk.annotation
Event Handler @EventTopicDelegate org.adempiere.base.event.annotations

Event Handler Annotations (v11+)

Class-level by category:

Method-level shortcuts:

2Pack Packaging for Plugins

Activator Options

Activator Location Behavior
AdempiereActivator META-INF/2Pack.zip Single file, applies once
Version2PackActivator 2Pack_X.Y.Z.zip Version-matched application
Incremental2PackActivator 2Pack_*.zip All versions applied sequentially

File Naming Convention

[Timestamp]_[ClientValue]_[Description].zip

Wiki Reference: NF5.1 Automatic External Packin

Version-Specific Field Types (AD_Reference)

The CLI validates field types against the target iDempiere version. Using a type not available in the target version will result in an error.

Field Types by Minimum Version

Type AD_Reference_ID Min Version Description
JSON 200222 v11+ JSON/JSONB data (IDEMPIERE-2981)
Chart 53370 v11+ Dashboard chart
Single Selection Grid 200209 v11+ Single selection grid
Multiple Selection Grid 200210 v11+ Multiple selection grid
Radiogroup List 200212 v11+ Radio button list
Chosen Multiple Selection List 200214 v11+ Multi-select dropdown
Chosen Multiple Selection Table 200215 v11+ Multi-select table
Chosen Multiple Selection Search 200216 v11+ Multi-select search
Timestamp with Timezone 200228 v11+ Timestamp with timezone
Timezone ID 200229 v11+ Timezone identifier
Record UU 200230 v11+ Record UUID reference
Dashboard Content 200162 v12+ Dashboard panel
UUID 200231 v13+ Native UUID type
Table UU 200233 v13+ Table UUID reference
Table Direct UU 200234 v13+ Direct UUID foreign key
Search UU 200235 v13+ Search UUID dialog

CLI Validation Example

# This will fail - JSON requires v11+
idempiere-cli add column XX_Data --table C_BPartner --type json -i 10
# Error: Reference type 'JSON' is not available in iDempiere 10. Requires iDempiere 11+.

# This works - JSON available in v11+
idempiere-cli add column XX_Data --table C_BPartner --type json -i 11

# This will fail - UUID requires v13+
idempiere-cli add column XX_UUID --table C_BPartner --type uuid -i 12
# Error: Reference type 'UUID' is not available in iDempiere 12. Requires iDempiere 13+.

Custom Fork Compatibility

Custom Fork is based on iDempiere 12 but actively backports community features. This means:

Guaranteed support:

May be backported:

CLI Handling: The CLI maintains a isCustom ForkSupported() method in ADReference.java that explicitly lists which v13+ features have been backported to Custom Fork.

Backport Registration Workflow:

When a v13+ feature is backported to Custom Fork:

  1. Code: Update src/main/java/org/idempiere/cli/api/model/ADReference.java

    // In isCustom ForkSupported() method:
switch (this) {
    case UUID:      // Backported from v13
        return true;
    case TABLE_UU:  // Add more as needed
        return true;
    default:
        return false;
}

  2. Docs: Update FEATURES.md → "Backported Features Log" table

  3. Changelog: Add entry to CHANGELOG.md under [Unreleased]

  4. Test: Verify with idempiere-cli add column XX_Test --table C_BPartner --type uuid -i custom

Reference: NF11 JSON Field Type

Model Generator Type Mapping (gen model)

The gen model command uses iDempiere core's ModelInterfaceGenerator for Java type mapping. This provides compile-time version sensitivity through Maven profiles.

How It Works

  1. CLI is built with Maven profile (-Pv11, -Pv12, -Pv13)
  2. Profile determines which iDempiere core version is included
  3. ModelInterfaceGenerator.getClass() handles all DisplayType mappings
  4. Type mapping automatically matches the compiled iDempiere version

DisplayType Evolution by Version

Based on analysis of SystemIDs.java:

DisplayType ID v11 v12 v13 Java Type
UUID 200231 ✗ ✓ ✓ String/UUID
TableUU 200233 ✗ ✓ ✓ String
TableDirUU 200234 ✗ ✓ ✓ String
SearchUU 200235 ✗ ✓ ✓ String
RecordID 200202 ✗ ✓ ✓ int
RecordUU 200240 ✗ ✓ ✓ String
JSON 200267 ✗ ✓ ✓ String
TimestampWithTimeZone 200133 ✗ ✓ ✓ Timestamp
TimeZoneId 200135 ✗ ✓ ✓ String
ImageURL 200271 ✗ ✓ ✓ String
RadiogroupList 200152 ✗ ✓ ✓ String
ChosenMultipleSelectionList 200161 ✗ ✓ ✓ String
ChosenMultipleSelectionTable 200162 ✗ ✓ ✓ String
ChosenMultipleSelectionSearch 200163 ✗ ✓ ✓ String
SchedulerState 200173 ✗ ✓ ✓ String

Build Profile Requirements

Always build the CLI with the profile matching your target iDempiere version:

# For iDempiere 11.x databases
mvn package -Pv11 -DskipTests

# For iDempiere 12.x databases
mvn package -Pv12 -DskipTests

# For iDempiere 13.x / development
mvn package -Pv13 -DskipTests

Version Mismatch Risks

If CLI version doesn't match database version:

Implementation Reference

See GenerateCommand.GenerateModelCommand:

Template Variables Summary

Variable Source Description
config.javaVersion IdempiereVersion.getJavaVersion() 17 or 21
config.zkVersion IdempiereVersion.getZkVersion() 9.6.0, 9.6.4, or 10.0.0
config.idempiereVersion IdempiereVersion.getFullVersion() Full version string
config.usesDeclarativeServices IdempiereVersion.usesDeclarativeServices() true for v11+
config.usesJakartaNamespace IdempiereVersion.usesJakartaNamespace() true for v13+
config.isCustom Fork IdempiereVersion.isCustom Fork() Custom Fork fork flag

Consequences

Positive

Negative

Risks

References

OSGi Factory Documentation

Application Dictionary

Path: /docs/developers/architecture/idempiere-hub/001-idempiere-version-compatibility