Migration Notes

Migration Scripts

From ADempiere 360 to ADempiere 361

Apply migration scripts from the following folders:

• 360lts-360lts.010
• 360lts.010-361.Final
• 361.Final-BUG_FIXES

From ADempiere 360 to iDempiere 1.0

Apply migration scripts from the following folders:

• 360lts-i1.0a
• i1.0a-i1.0b
• i1.0b-i1.0c
• i1.0c

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.

From iDempiere 1.0 to iDempiere 2.0

Apply migration scripts from the following three folders:

• i1.0c # just the scripts still not applied
• i1.0z
• i2.0

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:

• i2.0 # just the scripts still not applied
• i2.0z
• i2.1

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.1 to iDempiere 3.0

Apply migration scripts from the following three folders:

• i2.1 # just the scripts still not applied
• i2.1z
• i3.0

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.

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.

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).

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

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 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 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

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.

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