Migration Notes

From iDempiere en


Version iDempiere 11

Technical Notes from 11

Java 17 required

For the release-11 we decided to move to the next Long Term Supported version of java. As java 11 is too close to its end of life, the release-11 requires java-17 for running and compiling.

Upgrade to Hazelcast

The hazelcast library was upgraded with ticket IDEMPIERE-5816, the hazelcast.xml configuration file is not compatible with previous version, so it is needed to run setup again to use the new template. In case your hazelcast.xml is customized, you need to take the template for version 5.3 and apply your changes.

Storage size increase because of new Record_UU columns

As explained in UUID Key Tables documentation page: a number of Record_UU columns have been added to core tables, which can represent an increase in storage size and backup size in implementations that have many records on these tables, for example many attachments, or heavy usage of chat, post-it or labels. Also the Change Log can be affected by size depending on the System Configurator key AD_CHANGELOG_SAVE_UUID

New MPInstance constructors to manage the new column AD_PInstance.AD_Table_ID

The table AD_PInstance table had a Record_ID column without the corresponding AD_Table_ID. This is an anomaly and it created a problem as it was not possible to figure out which table triggered a process, and use the Record_ID field to navigate to the originating record.

With ticket IDEMPIERE-5567 the column was added, and the migration script 202309111844_IDEMPIERE-5567_ADPInstance.sql tries the best to fill the new column AD_Table_ID discovering the related table from column, toolbar button, print formats, etc.

However, it is very possible that not all relationships can be figured out, after migration you can review which records were left on AD_PInstance table with null AD_Table_ID and Record_ID>0, and decide if you want to fill it for your specific cases (sometimes is not possible to discover it at the end (for example the process org.compiere.process.BankStatementMatcher could have been called from three different tables and there is no trace about that).

Additionally, it is possible that your plugins call processes filling AD_PInstance without the table, the old constructors for MPInstance are marked as deprecated to ease the task to find them in your plugins and migrate to use the new methods.

Constructor MPaymentBatch(Properties, String, String) changed

There was a constructor MPaymentBatch(Properties, String, String) that was not used in the official core.

The second parameter of this constructor was the Name and it was intended to create a new record and set the Name of the Payment Batch record.

This constructor conflicts with the new UUID based constructor, so it was replaced by the UUID constructor and its behavior is now completely different.

Most probably nobody is using this old constructor, but in case you use MPaymentBatch constructor in your plugins, please review that you are not using this constructor, if used, please change it to a normal constructor with zero as ID parameter and then set the Name.

Product Info toolbar button deactivated in Core.

The community discussion was that most people is not using that toolbar button. However, if you miss it after upgrading. You can go to the Toolbar Button window and activate it again.

Version iDempiere 10

Technical Notes from 10

System user with ID zero deprecated

The user System with ID=0 was inactivated and replaced with a similar user with ID=10

Implementors that use System in any way must check if there is impact with this change, the migration script 202202072157_IDEMPIERE-5174.sql copies the information from AD_User, but it doesn't copy custom columns. Also, it replaces AD_User_ID in some core tables, but implementors must take care if is needed in other custom tables.

Change on Schedule behaviour

Ticket IDEMPIERE-5093 changed the way the schedule works:

  • Before this ticket when you had a schedule configured to run at 9AM, the job was executed at 9AM of the server timezone.
  • This ticket changed this behaviour and now the job is executed at 9AM of the tenant timezone where the job is defined.

Terminology changed from Client to Tenant

Ticket IDEMPIERE-4586 changed the terminology for Client to be known as Tenant in the whole application.

This have little impact from user perspective, but it can have a big impact on documentation.

Backward compatibility issue with TimeUtil.getBusinessDaysBetween

Before v10, the method was counting the last day of the period in the total of non business days.

Now, the last day is excluded. In order to fix that, a new method with a new parameter has been added includeEndDate, so you must use that new method with your plugin if you want to preserve behaviour prior to v10.

Version iDempiere 9 Horizon

Technical Notes from 9 Horizon

Deprecated direct http usage

iDempiere 9 Horizon doesn't support anymore direct http usage of the webui interface. Workaround is simply to use port https.

If you use http the system doesn't allow login in webui.

Note that http can still be used for proxy forwarding, but the configuration requires to forward the header X-Forwarded-Proto to https.

In nginx you must add the following line to the definition of the locations /webui and /webui/zkau/comet:

proxy_set_header  X-Forwarded-Proto $scheme;

As described in Proxy iDempiere Through Nginx

All core views imported to dictionary

With ticket IDEMPIERE-5059 the definition of the 149 core views was imported to the dictionary.

In the migration scripts there is code to recreate all these views, so it is very possible that all the custom columns that were added to views by the implementor will present problems when applying the scripts.

Two possible cases that you need to take care about:

  • the script doesn't show errors, but your customization for the view is lost. You must check all the core views that you customized to see if they are having problems and apply the corresponding fixes in release 9
  • the script show errors when applying (usually postgres complains because it cannot change the columns)

In both cases it is required that you fix the views, do not create the view by hand in SQL, the best way is to add your customized columns to the dictionary and then use the iDempiere process to validate/create the view in the database.


Take care of AD_Window.PredefinedContextVariables

Ticket IDEMPIERE-4837 will erase changes done on AD_Window.PredefinedContextVariables for Order, Invoices. Make a backup of the content of those fields if you have customized them and reapply them.

PostgreSQL Default to Native Dialect

Release-9 comes by default with Native PostgreSQL dialect. The SQLs in core were changed to make them compatible for Oracle and PostgreSQL. Because of that is possible that some plugins can be broken, for example if using NATIVE_PostgreSQL_KEYWORK.

To solve that, the best option is to change your plugin to use SQL standard (compatible with both databases).

See NF9 PostgreSQL Default To Native Dialect for information about how to disable it (not recommended).

Version iDempiere 8.2

When migrating from old versions to 8.2 you must take into account the following migration notes:

For migration script issues see Note Upgrade 8.2 from Hiep

Technical Notes from 8.2

Themes

With the ticket IDEMPIERE-4421 it was implemented a mechanism for versioning the themes.

We tried to preserve backward compatibility with pre-8.2 themes, but still you'll find problems when the following conditions are in your plugin

  • if the old plugin has references to /theme/default, because the URL of /theme/default was changed to the versioning approach
    • Recommended solution: migrate your theme to 8.2 approach
    • Or change the pointers to /theme/default to point to your own theme
    • Or change the pointers to ~./theme/default/ (this is not recommended, is preferable to maintain your own theme assets)
  • if your plugin referenced the public variable ITheme.THEME_PATH_PREFIX, that variable was dropped
    • Solution is to change the variable to ThemeManager.THEME_PATH_PREFIX

PO is immutable

Plugin developers must take care about not writing objects retrieved from cache.

iDempiere now has a mechanism that forbids writing to these objects to prevent multi-threading issues with these objects. The workaround that must be implemented in code is simply to read the object directly from database (f.e. with ctx+ID+trx constructor), also there are some classes that implemented a getCopy method that can be used to get an updateable copy from the cache.

See IDEMPIERE-4287

Cross-tenant reading/writing forbidden by default

Plugin developers must take care about avoiding reading or writing records from a different tenant than the tenant that was used in login.

iDempiere now has a mechanism that forbids reading/writing records from a different tenant.

Reading can be done from the current tenant or System tenant. Writing can be done just on the current tenant.

The workaround that must be implemented in code is simply to read the object directly from database (f.e. with ctx+ID+trx constructor), also there are some classes that implemented a getCopy method that can be used to get an updateable copy from the cache.

How to avoid this condition?

  • Always read/write records within the tenant
  • for example filter AD_Client_ID=?
  • or filter AD_Client_ID IN (0,?)
  • with Query consider using the method setClient_ID

If, for any reason, it is absolutely necessary to read or write a record in a different tenant, the following code can be used:

try {
    PO.setCrossTenantSafe();
    // write here the Query.list or PO.saveEx that is cross tenant safe
} finally {
    PO.clearCrossTenantSafe();
}

See IDEMPIERE-4268

Version iDempiere 7.1

Multi-server schedulers

Because of ticket IDEMPIERE-4056, the schedulers running in all servers are not supported anymore.

This is, in previous versions when a scheduler didn't have a RunOnlyOnIP defined it was executed in all servers, after the implementation of IDEMPIERE-4056 the schedulers without an IP defined are executed on just one server (randomly).

How to configure now:

  • The RunOnlyOnIP keeps working as usual, so the easiest workaround is to configure one scheduler per each server

Version iDempiere 3.0

When migrating from old versions to 3.0 you must take into account the following migration notes:

Technical Notes from 3.0

Keystore moved

As the web server was changed from tomcat to jetty the keystore file was moved from idempiere-server/keystore/myKeystore to idempiere-server/jettyhome/etc/keystore

Themes

With the upgrade of zk to version 7 the file org.adempiere.ui.zk/theme/default/css/theme.css.dsp was split in fragments located at folder org.adempiere.ui.zk/theme/default/css/fragment:

  • about.css.dsp
  • adwindow.css.dsp
  • application-menu.css.dsp
  • borderlayout.css.dsp
  • button.css.dsp
  • desktop.css.dsp
  • field-editor.css.dsp
  • find-window.css.dsp
  • form.css.dsp
  • gadget.css.dsp
  • grid.css.dsp
  • group.css.dsp
  • help-window.css.dsp
  • info-window.css.dsp
  • input-element.css.dsp
  • login.css.dsp
  • menu-tree.css.dsp
  • setup-wizard.css.dsp
  • tab.css.dsp
  • tab-editor.css.dsp
  • toolbar.css.dsp
  • toolbar-popup.css.dsp
  • tree.css.dsp
  • window.css.dsp

Theme developers must take care of migrating the themes to be compliant with this new schema.

Migration Notes from Hieplq

Please take a look to the migration notes provided by hiep at Known issues when updating your development environment zk7 branch

From iDempiere 2.1 to iDempiere 3.0

Apply migration scripts from the following three folders:

NOTE: The folder specified above can vary on every release - the idea is to apply all migration scripts until you arrive to the release you're migrating to.

From iDempiere 2.0 to iDempiere 2.1

Apply migration scripts from the following three folders:

NOTE: The folder specified above can vary on every release - the idea is to apply all migration scripts until you arrive to the release you're migrating to.

From iDempiere 1.0 to iDempiere 2.0

Apply migration scripts from the following three folders:

NOTE: The folder specified above can vary on every release - the idea is to apply all migration scripts until you arrive to the release you're migrating to.

Version iDempiere 1.0

When migrating from old systems to iDempiere 1.0 you must take into account the following migration notes:

Technical Notes for iDempiere 1.0

org.compiere.acct.Doc

Constructor account schema parameter have been changed from MAcctSchema[] to MAcctSchema. This can break extensions that modify accounting, solution is simple, just change it to use new method and accomodate code.

2Pack

The new 2pack format is not backward compatible

AD_WF_Node

The xposition and yposition column now stored the node's position in a grid instead of absolute pixel value.

Change Log Configuration

The change log is now enabled by default in most of the tables.

Enabling the change log is done with the script 201306261840_EnableChangeLog.sql

If you have already tuned your change log configuration, you can skip that script - or run it and then recover your specific fine tuning changes.

Note also that enabling the change log it will increase the disk consumption - if that's a concern on your installation you must fine tune this configuration after running the script.

Jasper ID parameters passed as BigDecimal now as Integer

In some cases the ID parameters (table, table direct, search) were passed to jasper reports as BigDecimal, while in other cases same parameters were passed as Integer (like RECORD_ID or ranges), with IDEMPIERE-1422 that behavior is now consistent, always using Integer for _ID parameters.

This change can break old jasper reports that defined the ID parameter as BigDecimal, the fix is simple, just change the jasper parameter to Integer and compile again.

When this error is reached running the jasper report throws this exception:

16:47:32.058===========> ProcessUtil.startJavaProcess: org.compiere.report.ReportStarter [17]
java.lang.ClassCastException: java.lang.Integer cannot be cast to java.math.BigDecimal
	at net.sf.jasperreports.engine.query.JRJdbcQueryExecuter.setStatementParameter(JRJdbcQueryExecuter.java:553)
	at net.sf.jasperreports.engine.query.JRJdbcQueryExecuter.setStatementParameter(JRJdbcQueryExecuter.java:399)
	at net.sf.jasperreports.engine.query.JRJdbcQueryExecuter$1.visit(JRJdbcQueryExecuter.java:332)
	at net.sf.jasperreports.engine.query.JRAbstractQueryExecuter$QueryParameter.accept(JRAbstractQueryExecuter.java:157)
	at net.sf.jasperreports.engine.query.JRAbstractQueryExecuter.visitQueryParameters(JRAbstractQueryExecuter.java:646)
	at net.sf.jasperreports.engine.query.JRJdbcQueryExecuter.createStatement(JRJdbcQueryExecuter.java:317)
	at net.sf.jasperreports.engine.query.JRJdbcQueryExecuter.createDatasource(JRJdbcQueryExecuter.java:196)
	at net.sf.jasperreports.engine.fill.JRFillDataset.createQueryDatasource(JRFillDataset.java:1087)
	at net.sf.jasperreports.engine.fill.JRFillDataset.initDatasource(JRFillDataset.java:668)
	at net.sf.jasperreports.engine.fill.JRBaseFiller.setParameters(JRBaseFiller.java:1281)
	at net.sf.jasperreports.engine.fill.JRBaseFiller.fill(JRBaseFiller.java:900)
	at net.sf.jasperreports.engine.fill.JRBaseFiller.fill(JRBaseFiller.java:845)

Functional Notes for iDempiere 1.0

Inventory Document Types

Because of IDEMPIERE-675 you need to set manually the inventory document subtype for your inventory documents (internal use and physical inventory).

In case you used the same document type for both cases - then recommendation is to inactivate the old mixed document and create new document types for each specific case.

Deprecated Functionalities

With IDEMPIERE-362, IDEMPIERE-170, IDEMPIERE-247 some functionalities that were not working properly where deprecated, please check the tickets and commits for details, most prominent are:

  • Cash Journals (all cash functionalities can be modeled using payments)
  • MRP Heavy Manufacturing (Light Manufacturing was integrated)
  • Payroll (being developed as extension)

Production

If you used the old Production window (original from Compiere with three tabs) - please note some changes are required as noted in IDEMPIERE-521

Advanced Roles

With IDEMPIERE-1160 a new security feature was implemented, when creating a new client the ClientAdmin role is configured as advanced role and the ClientUser role is not, after that you can use the ClientAdmin role to configure the rest of roles (advanced or not) and users.

Please note that advanced role is not intended for end-users, is mostly intended for Information technology (IT) roles that administer the system - advanced roles have access to many fields that are documented and exposed security holes in the system.

This new feature creates a problem when migrating databases with existing tenants - as we can't know in advance how the security was configured in an already existing client - we cannot set advanced role to one of the client roles in the database via migration script. The consequence is that when migrating databases, all the roles on Clients (not GardenAdmin and System) are marked as non-advanced - and there is not a way to mark advanced role within the system, it's needed to mark your required advanced role directly via SQL with a command like:

UPDATE AD_Role SET IsAccessAdvanced='Y' WHERE AD_Role_ID=?

where you replace the ? with the ID of the role you design as advanced (with access to security holes).

Migration Scripts

From ADempiere 360 to ADempiere 361

Apply migration scripts from the following folders:

From ADempiere 360 to iDempiere 1.0

Apply migration scripts from the following folders:

NOTE: The folder specified above can vary on every release - the idea is to apply all migration scripts until you arrive to the release you're migrating to.

From ADempiere 361 to iDempiere 1.0

You need to apply the migration scripts like migrating from 360, EXCLUDING those already applied when you migrated from 360 to 361.

Increasing speed of some scripts

  • Script postgresql/789_GenerateUUIDColumns.sql can apply ALTER TABLE too slowly for big tables - this can be improved dropping the " DEFAULT NULL" at the end of each ALTER TABLE
  • It is highly recommended to run "UUID Generator" process after migration to fill the empty UUID columns, but this can be a very slow process for big tables, a faster way can be achieved executing an update directly on the database, also you can consider deleting the related uuid index before the update and recreating it at the end, for example:
    • DROP INDEX ad_changelog_uu_idx;
    • UPDATE AD_ChangeLog SET AD_ChangeLog_UU=generate_uuid() WHERE AD_ChangeLog_UU IS NULL;
    • CREATE UNIQUE INDEX ad_changelog_uu_idx ON ad_changelog (ad_changelog_uu);
  • The script processes_post_migration/postgresql/02_SynchronizeTerminology.sql tend to be slow on postgresql versions higher than 9.1 with the default memory. In order to solve this is recommended to tune the memory for the database.

Note about migrating from ADempiere 370

Pb_integratio is sharing and documenting experience about this at Migration from ADempiere 370 to iDempiere

Note about migrating from ADempiere pre-360

Problem

Migrating some Adempiere installations before 360 to iDempiere generates a problem when using postgresql 9.2 - applying the script 201309192024_IDEMPIERE-1370.sql:222 throws:

ERROR:  cannot change name of input parameter "p_product_id"

Cause

An issue has been detected migrating a database pre-360 to iDempiere using postgresql 9.2

The function bomqtyonhand from the database seed doesn't match with the function bomqtyonhand present on the migration scripts (pre-360), the script 201309192024_IDEMPIERE-1370.sql fixes that situation, but postgresql 9.2 doesn't allow changing a parameter name for a function.

Solutions

  • You can do the migration using postgres 8.4 and at the end migrate to 9.2 (postgres 8.4 allows changing name of function parameters)

alternatively

  • You can drop the old function bomqtyonhand (and all the associated views) and recreate them properly
Cookies help us deliver our services. By using our services, you agree to our use of cookies.