Understanding the Application Dictionary

Overview

• What you’ll learn: What the Application Dictionary is, how it drives iDempiere’s model-driven architecture, and how metadata tables like AD_Table, AD_Column, AD_Window, AD_Tab, AD_Field, and AD_Reference define the entire application.
• Prerequisites: Lesson 4 – Navigating the User Interface
• Estimated reading time: 20 minutes

Introduction

If you have used other ERP systems, you may have noticed that adding a new field or changing a form layout often requires custom code, recompilation, and redeployment. iDempiere takes a fundamentally different approach. At the heart of the system lies the Application Dictionary (commonly abbreviated as AD), a set of metadata tables that describe every window, tab, field, table, column, and reference in the entire application. When the system renders a window, it does not read a hard-coded form definition; instead, it queries the Application Dictionary at runtime and builds the user interface dynamically.

This design philosophy is called model-driven development, and it is one of the most powerful features inherited from the original Compiere project. Understanding the Application Dictionary is the single most important step toward becoming proficient in iDempiere customization and administration.

What Makes the Application Dictionary Revolutionary

Traditional enterprise applications store their form layouts, field definitions, and business rules in compiled source code. To change a label, add a field, or rearrange a form, a developer must modify code, compile, test, and deploy. The Application Dictionary eliminates this bottleneck by storing all of these definitions as data inside the database itself.

Consider what this means in practice:

• A new column added to a database table can appear on a window within minutes, without writing a single line of Java code.
• Display logic (showing or hiding fields based on conditions) is configured through metadata expressions, not programmed in source files.
• Validation rules, default values, and mandatory constraints are all defined as dictionary entries.
• Changes take effect immediately upon saving the dictionary record and refreshing the window. There is no compilation or deployment step.

The Application Dictionary is not just a convenience feature. It is the architectural foundation upon which the entire iDempiere ecosystem is built. Plugins, localizations, and customizations all interact with the dictionary to extend the system without modifying core code.

The EntityType Concept

Before diving into the individual dictionary tables, it is important to understand the EntityType concept. Every dictionary record carries an EntityType field that identifies who owns that definition. The core system uses the entity type D (for Dictionary). When you create customizations, you should define your own entity type (for example, MYCOMPANY) and assign it to all your custom dictionary records.

This separation serves two critical purposes:

• Upgrade safety: During a system migration, the upgrade process can distinguish between core records (entity type D) and your custom records, preventing your changes from being overwritten.
• Packaging: The 2Pack export tool uses entity types to determine which records belong to a plugin or customization package.

Core Dictionary Tables

The Application Dictionary is composed of several interconnected metadata tables. Each table serves a specific role in describing the application structure. Let us walk through them in logical order, from database structure to user interface.

AD_Table: Table Definitions

The AD_Table table registers every database table that iDempiere knows about. Each row in AD_Table describes one database table and includes:

• TableName: The physical name of the table in the database (e.g., C_Order, M_Product).
• Name: A human-readable label (e.g., “Order”, “Product”).
• AccessLevel: Determines who can access the data. Values include System Only (4), Client Only (2), Organization (1), Client+Organization (3), System+Client (6), and All (7).
• IsView: Indicates whether this entry represents a database view rather than a table.
• IsDeleteable: Controls whether records can be deleted from the UI.
• ReplicationType: Used in multi-site replication scenarios.

When you create a new physical table in the database, you must also create a corresponding record in AD_Table. Without this registration, iDempiere has no knowledge of the table’s existence.

AD_Column: Column Definitions

For each table registered in AD_Table, the AD_Column table stores definitions for every column. This is where iDempiere learns about data types, constraints, and relationships. Key attributes include:

The AD_Reference_ID field deserves special attention because it controls both how data is stored and how it is displayed. For instance, a column with reference type Table Direct automatically creates a dropdown that looks up values from the referenced table.

AD_Window: Window Definitions

The AD_Window table defines the top-level windows that users interact with. Each window record includes:

• Name: The window title displayed in the UI.
• WindowType: Can be Maintain (for editing data), Transaction (for documents like orders and invoices), or Query Only (read-only).
• AD_Image_ID: An optional icon for the window.
• IsSOTrx: For transaction windows, indicates whether this is a sales or purchasing window.

A window by itself does not display any data. It is a container that holds one or more tabs.

AD_Tab: Tab Definitions

Each tab within a window is defined in the AD_Tab table. Tabs are where the real data display begins, because each tab is linked to a specific database table. Critical attributes include:

• AD_Window_ID: The parent window this tab belongs to.
• AD_Table_ID: The database table whose data this tab displays.
• TabLevel: The hierarchy level. Level 0 is the header (main) tab, level 1 is a detail tab, level 2 is a sub-detail, and so on.
• SeqNo: The display sequence within the window.
• AD_Column_ID (Parent Link): For child tabs, this specifies which column links back to the parent tab’s record.
• IsSingleRow: Whether the tab displays one record at a time or in a grid.
• WhereClause: An optional SQL WHERE clause that filters the records displayed.
• OrderByClause: Controls the default sort order of records.
• ReadOnlyLogic: A conditional expression that makes the entire tab read-only.
• DisplayLogic: A conditional expression that controls tab visibility.

The tab level system is fundamental to iDempiere’s parent-child data navigation. When a user selects a record on a level-0 tab, the level-1 tabs automatically filter to show only related child records.

AD_Field: Field Display Definitions

While AD_Column defines what data exists, AD_Field controls how each column appears on a specific tab. This separation is deliberate: the same column can appear on multiple tabs with different display settings. AD_Field attributes include:

• AD_Tab_ID: Which tab this field belongs to.
• AD_Column_ID: Which column this field displays.
• SeqNo: The display order on the form.
• IsDisplayed: Whether the field is visible.
• DisplayLogic: A conditional expression for dynamic visibility (e.g., @IsSOTrx@='Y' to show only for sales transactions).
• IsSameLine: Whether this field appears on the same row as the previous field.
• IsReadOnly: Whether the field is editable.
• AD_FieldGroup_ID: An optional grouping for collapsible field sections.
• SortNo: Used for default grid sorting.

Display logic expressions use a simple syntax referencing context variables. For example, @DocStatus@='DR' means the field is only visible when the document status is Draft.

AD_Reference: Reference Types

The AD_Reference table defines how lookup fields (dropdowns, search fields) retrieve their values. There are several reference types, each suited to a different scenario:

When a column’s AD_Reference_ID is set to Table or Search, the AD_Reference_Value_ID points to a specific reference record that defines which table to query, which column is the key, which column provides the display value, and an optional WHERE clause for filtering.

How Changes Propagate Immediately

One of the most striking aspects of the Application Dictionary is its runtime nature. When you modify a dictionary record, the change takes effect the next time the affected window is loaded. The propagation works as follows:

1. A user or administrator modifies a record in an AD table (for example, changes a field’s DisplayLogic).
2. The record is saved to the database.
3. The Application Dictionary cache is cleared (either automatically or via the Cache Reset process).
4. When any user next opens the affected window, iDempiere reads the updated metadata and renders the window with the new configuration.

There is no need to restart the server, recompile code, or redeploy the application. This immediate feedback loop makes the Application Dictionary an extraordinarily productive tool for both development and administration.

Tip: If your changes do not appear immediately, use the Cache Reset option from the Administration menu. The system caches dictionary data aggressively for performance, and sometimes a manual reset is needed.

Step-by-Step Example: Creating a Simple Window

To solidify your understanding, let us walk through the process of creating a simple window to manage a custom table. Suppose your organization needs to track training courses.

Step 1: Create the Database Table

First, create the physical table in the database:

CREATE TABLE XX_TrainingCourse (
  XX_TrainingCourse_ID NUMERIC(10) NOT NULL,
  AD_Client_ID NUMERIC(10) NOT NULL,
  AD_Org_ID NUMERIC(10) NOT NULL,
  IsActive CHAR(1) DEFAULT 'Y' NOT NULL,
  Created TIMESTAMP NOT NULL,
  CreatedBy NUMERIC(10) NOT NULL,
  Updated TIMESTAMP NOT NULL,
  UpdatedBy NUMERIC(10) NOT NULL,
  Value VARCHAR(40) NOT NULL,
  Name VARCHAR(255) NOT NULL,
  Description VARCHAR(255),
  XX_TrainingCourse_UU VARCHAR(36) DEFAULT NULL,
  CONSTRAINT XX_TrainingCourse_Key PRIMARY KEY (XX_TrainingCourse_ID)
);

Notice the standard columns (AD_Client_ID, AD_Org_ID, IsActive, Created, CreatedBy, Updated, UpdatedBy) that every iDempiere table requires.

Step 2: Register in the Application Dictionary

Open the Table and Column window in iDempiere and create a new record:

• Set the DB Table Name to XX_TrainingCourse.
• Set the Name to “Training Course”.
• Set the EntityType to your custom entity type.
• Use the Create Columns from DB process to automatically generate AD_Column records for each database column.

Step 3: Create the Window

Open the Window, Tab & Field window:

• Create a new window record with the name “Training Course” and type “Maintain”.
• Create a tab at level 0 linked to the XX_TrainingCourse table.
• Use the Create Fields process to automatically generate AD_Field records for each column.
• Adjust field sequence, display settings, and labels as needed.

Step 4: Add to the Menu

Open the Menu window and create a new menu entry pointing to your window. Assign it to the appropriate menu tree location.

Step 5: Test

Log out and log back in (or reset the cache), navigate to your new menu entry, and your Training Course window is fully functional with create, read, update, and delete capabilities. No Java code was written.

Key Takeaways

• The Application Dictionary is a set of metadata tables that define the entire iDempiere application structure, from database tables to user interface elements.
• Model-driven development means changes to the dictionary take effect immediately without code compilation or redeployment.
• The core dictionary tables form a hierarchy: AD_Table and AD_Column describe the data model; AD_Window, AD_Tab, and AD_Field describe the UI; AD_Reference defines lookup behavior.
• EntityType separates core dictionary records from customizations, ensuring upgrade safety.
• New windows and forms can be created entirely through the dictionary without writing Java code.
• The AD_Reference system provides flexible lookup mechanisms (Table Direct, Table, List, Search) for foreign key relationships.

What’s Next

Now that you understand the Application Dictionary, the next lesson will focus on Working with Windows and Tabs, where you will learn the header/line pattern, parent-child tab relationships, display logic, and how to navigate complex multi-tab windows like the Business Partner window.

CREATE TABLE XX_TrainingCourse (
  XX_TrainingCourse_ID NUMERIC(10) NOT NULL,
  AD_Client_ID NUMERIC(10) NOT NULL,
  AD_Org_ID NUMERIC(10) NOT NULL,
  IsActive CHAR(1) DEFAULT 'Y' NOT NULL,
  Created TIMESTAMP NOT NULL,
  CreatedBy NUMERIC(10) NOT NULL,
  Updated TIMESTAMP NOT NULL,
  UpdatedBy NUMERIC(10) NOT NULL,
  Value VARCHAR(40) NOT NULL,
  Name VARCHAR(255) NOT NULL,
  Description VARCHAR(255),
  XX_TrainingCourse_UU VARCHAR(36) DEFAULT NULL,
  CONSTRAINT XX_TrainingCourse_Key PRIMARY KEY (XX_TrainingCourse_ID)
);

CREATE TABLE XX_TrainingCourse (
  XX_TrainingCourse_ID NUMERIC(10) NOT NULL,
  AD_Client_ID NUMERIC(10) NOT NULL,
  AD_Org_ID NUMERIC(10) NOT NULL,
  IsActive CHAR(1) DEFAULT 'Y' NOT NULL,
  Created TIMESTAMP NOT NULL,
  CreatedBy NUMERIC(10) NOT NULL,
  Updated TIMESTAMP NOT NULL,
  UpdatedBy NUMERIC(10) NOT NULL,
  Value VARCHAR(40) NOT NULL,
  Name VARCHAR(255) NOT NULL,
  Description VARCHAR(255),
  XX_TrainingCourse_UU VARCHAR(36) DEFAULT NULL,
  CONSTRAINT XX_TrainingCourse_Key PRIMARY KEY (XX_TrainingCourse_ID)
);