Migrate - Marking Customizations

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.

Marking Customizations

Customizations are preserved through migrations. Entities which are not recognized as customizations will be dropped or overwritten from the reference database.

Migrate recognizes four different levels of customization:


An entity is named with a special prefix which identifies it as a customization. Prefixes are stored in the Application Dictionary.


An entity is marked as customization in the Application Dictionary.


An entity itself is not customized, but it contains customized components.


An entity is not customized.

The only way to determine the customization level is by consulting the Application Dictionary, which means you must have informed the Application Dictionary about your customizations before you start Migrate.

Registering Custom Entity Types

You can register four-letter entity types to identify your customizations. These four letters can also be used as prefix to name database objects which are not maintained by the application dictionary.

For example, if you decide to identify your customizations by entity type QRST, then you can create a custom index and name it QRST_MyIndexName. Because QRST is registered as custom entity type in the Application Dictionary, Migrate understands that QRST_MyIndexName is a custom index and will preserve it.7

It is good practice to also name those objects which are maintained by the Application Dictionary using your custom prefix, like QRST_MyTableName and QRST_MyColumnName. This makes the customizations also easily recognizable by human database administrators.

Of course you can also use different entity types for different topics, like QRS1 for security related customizations, QRS2 for accounting related customizations, etc.

To register your custom entity type, log in as System and open the window Application DictionaryEntity Type.

Select Entity Type from the Application Dictionary menu

Create a new record, enter four letters as your new entity type, and give it a short name and a description.

Register your custom entity type in the Application Dictionary

Mark Customizations in the Application Dictionary

You can now use your new entity type to mark your customizations in the Application Dictionary.

For example, if you add a new column to a table, you can define it as being of your new entity type:

Select your custom entity type for newly created objects

Apart from your own entity types, you can of course also mark your customizations with one of the predefined types User maintained, Applications, Other Customizations, Extensions, or Other Extensions.

Do not use Adempiere or Dictionary, which mark your changes as system-maintained and they will be dropped during the next version migration.

Mark Customizations in the Change Log

In some cases it is not possible to identify your changes with a custom entity type.

For example, if you wanted to change the Business Partner window so that the organization field is not displayed next to the client field but below it in the next row. Logged in as System, you would make the changes in the window Application DictionaryWindow, Tab & Field. Navigate to the Organization field, and deselect Same Line so that the field gets displayed in the next row.

Tweaking window appearance

But as you can see, the entity type for this field is already Dictionary, and you can not apply your custom entity type.

To still protect your change from being undone during the next version migration, you can mark it as customization in the change log. For security reasons, Adempiere keeps a log of changes done to the system. The log can be accessed from the window System AdminGeneral RulesSecurityChange Audit.

Select Change Audit from the Security menu

Find the change you want to keep permanently and mark it is customization:

Marking changes as customization in the Change Log

Migrate will preserve changes marked as customization in such way.

[7] Exception: If the same four letters are also registered as entity type in the reference database, they will not be considered as customization markers. The reasoning behind this is that if you use a customized reference database, those customizations contained in the reference database should also be maintained and controlled by the reference database and not protected by Migrate.