Migrate - Marking Customizations
Contents
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:
- CUSTOMPREFIXED
An entity is named with a special prefix which identifies it as a customization. Prefixes are stored in the Application Dictionary.
- CUSTOMMARKED
An entity is marked as customization in the Application Dictionary.
- CUSTOMIMPLIED
An entity itself is not customized, but it contains customized components.
- CUSTOMNONE
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 → .
Create a new record, enter four letters as your new entity type, and give it a short name and a description.
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:
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 → . Navigate to the Organization field, and deselect Same Line so that the field gets displayed in the next row.
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 → → →
Find the change you want to keep permanently and mark it is customization:
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.
