View source | Discuss this page | Page history | Printable version   

How to Migrate 2.50 Modules to 3.0

Contents

Overview

This document explains how module developers can migrate their modules to make them compatible with Openbravo 3.0

When to Migrate

Any module version should declare a dependency -direct or indirect- to the core module. It defines the Openbravo Release (2.50, 3.0) that the module version is compatible with. A module version can be compatible with different Openbravo Releases if the dependencies it declares allow to install it on top of different major version of the core module. Before September 2010 all versions of all Openbravo modules were compatible only with Openbravo 2.50 since it was the only core major version that supported modularity. Then the first Release Candidate of Openbravo 3.0 was published. This document explains what are the steps a developer needs to do to migrate the modules he has published to make them compatible with Openbravo 3.0. The main concept behind this migration is the "extension of dependencies": the dependency of module version A v1 on other module version B v2 can be extended by declaring the Last Version of module B (v3) that satisfies as well the dependency. This way the dependency is on the range of module versions between v2 and v3.

As stated above, the compatibility with Openbravo 2.50 or 3.0 depends on the dependencies declared by the module version. There are several different cases to take into account:

For any of the cases that require of extending dependencies it is needed to release a new version of the module, this can be done following any of the approaches detailed below.

Simplified Approach

As 3.0 API is mainly the same as 2.50 one, most 2.50 modules are compatible with 3.0. This simplified approach consists in extending dependencies of the module assuming it will be compatible with 3.0, publishing it in test mode and test it (install and use) in a 3.0 instance. Finally, after succesful testing, make it available to everyone.

In summary the steps are:

Each of these steps is detailed below.

Extend Dependencies

In a 2.50 development environment with your modules installed on, extend dependencies of them by setting the Last Version field to 3.0.0 in the case of dependencies to core, or to the 3.0 compatible version of the module in the case of other dependencies.

Note that for Major dependency enforcement it is not needed to add the Last Version in case the 3.0 compatible version is within the same major version as the First Version. So for example, if your module A depends on B from version 1.0.5 (which is only compatible with 2.50) and a new 1.0.6 minor version of B is released, it is not necessary to change A's dependency as it will be automatically be compatible with B 1.0.6. Also for direct dependencies to core minor version is not taken into account, so the Last Version field could be any 3.0.x (for example 3.0.0).


Migration30-extend-deps.png

Publish New Version

In the same 2.50 development environment, prepare, release and publish a new version of your module with these changes in the dependencies.

It is preferable to publish a new minor version, so other modules depending on yours will still be compatible with this new version. For example, if your original module B 1.0.5 was only compatible with core 2.50, the suggested new version for the new B compatible with 3.0 would be 1.0.6 (or any other 1.0.x higher than 1.0.5). In this way, if it exists any other module A which depends on B 1.0.x it won't be required for A to extend B dependency because it is already compatible with the new one.

Migration30-new-ver.png

The steps to follow are:

Test

Now you will be able to install your module in a 3.0 instance. For example, you can use a 3.0 virtual appliance to look in Central Repository for the new version and install it. Do not forget to configure your instance to accept module versions in Test maturity status.

Once it is installed you can do all testings you need to ensure it works correctly.

When everything is fine you can promote the new module version to Control Release or General Available maturity status to make it available to every one.

Standard Approach

This is the standard way of extending dependencies of modules, it is valid not only for core but for any new major version of a dependent module, though, as example, it is explained for dependencies to core.

It consists on upgrading core with the modules installed, test them, extend dependencies and publish.

In short, the steps to migrate a 2.50 module to 3.0 are the following ones:

The following sections explain more in detail each of the steps.

Upgrade to 3.0

In a Openbravo ERP 2.50 instance install the module(s) you want to make 3.0 compatible.

As the dependencies of these modules should be to 2.50, it will not be possible to directly upgrade the instance. To do so it is required to locally relax dependencies on core and on all modules that depend on core 2.50 (unless they are Enforcement None dependencies). This can be done by setting the User Editable Enforcement field in the Dependencies tab and using the Enforcement None in the Settings tab. In this way the module will not prevent upgrade to 3.0. More detailed information about this, can be found in the Modules Management document. These settings are available from 2.50MP21. Note that after this process the User Editable Enforcement can be restored again if wanted.

Bulbgraph.png   Important note: User Editable Enforcement should be only modified for the modules you are owner of. In case there are modules of third parties that are dependencies for your modules, you will have to wait till new versions of them depending on 3.0 are published before you can make your one ones compatible with 3.0.

After this, you will be able to upgrade your instance to 3.0. Direct upgrade from Module Manager Console is supported from 2.50MP23, instances in earlier release can upgrade through obx file.

Verify 3.0 Compatibility

3.0 is based on 2.50 so most modules should work without any additional modification. Anyway, when extending dependencies, it should always be checked everything still works as expected paying special attention to the API changes that could have occur since last verification and might affect your module.

Extend Dependencies

Once every thing works nice, you can extend the core dependency of you module to 3.0.

Note that in case you module has dependencies to other modules that depend on 2.50 you should also change the dependencies to them to be to the version that supports 3.0.

Dependency extension can be done in two ways:

Repackage and Publish

Finally you will have to create a new version of your module, package the obx file and publish it as usual.

If the new version is compatible with 2.50 and 3.0, it is advisable to create a new minor version of the module. In this way modules that depend on it (Major Enforcement) will not need to release a new version to be compatible with yours.

Known issues

API changes

As stated above the technical API of Openbravo remains mostly stable from 2.50 to 3.0, although there have been some low risk API changes in the 2.50 and 3.0 life cycle. Check the list if you find some issue when testing your module on Openbravo 3.0

Financial flows

In 3.0 the financial flows have been refactored using the Advanced Payables and Receivables module. It means that the following entities have been replaced:

If your module makes use of some of these entities you should check the Advanced Payables and Receivables documentation for a proper semantic mapping to the new entities.

Alert Management

As of Openbravo 3 RC6 the alert management window has been redesigned. As part of this project the alert Status management has been improved. If your module is managing the alerts it should adapted. The column isFixed has been deprecated and replaced by the new Status column. The background process doesn't set the fixed alerts as deactivated neither. New statuses supported by default are:

Other modules can add new statuses if needed.

Cleanup Project

During the 3.0 development cycle the Cleanup Project did remove several deprecated elements from the Openbravo codebase. If your module is affected by this it might need some updates. Check Cleanup Project wiki page contains a description of the changes done.


Library Update

During the 3.0 development cycle the most third party libraries used by Openbravo have been updated to newer version. The project page for this Library Update projects explains a few known issues for which every modules must be checked, so verify if it is affected or not.

Required changes

Here are listed the most common cases requiring modifications. Note that there are some other and stranger cases covered within in this Appendix.

AD windows

Application Dictionary windows will automatically be shown in the new Openbravo 3 mode, unless they use an unsupported feature or they require some changes to be able to work in the new way.

Bulbgraph.png   Starting Openbravo 3 rc5, there is a way to find out why a window is not being shown in the new mode. If you want to know why one of the windows of your module is not shown using the Openbravo 3 look and feel, use this ant task:

ant check.window.compatibility

This task will show the windows which will be opened in classic mode, and the reason for this.

Tab whereclauses, orderbyclauses and filterclauses

In Openbravo, tabs can define whereclauses and filterclauses, which allow tabs to show only some of the records contained in a table, and orderbyclauses, which allow the developer to define a specific order in which the records should be shown.

In Openbravo 3, windows use the Data Access Layer in the backend component to retrieve data. As you might know, the Data Access Layer uses the Hibernate HQL language instead of SQL, and because of that, the old whereclauses, filterclauses, and orderbyclauses, which were written in SQL, cannot be used.

Therefore, if any tab in your module has a defined whereclause, filterclause, or orderbyclause, you need to define a corresponding hqlwhereclause, hqlfilterclause, or hqlorderbyclause, so that Openbravo can show it as an Openbravo 3 window.

If a window in your module contains a tab with a whereclause, filterclause, or orderbyclause, and without its corresponding hqlwhereclause, hqlfilterclause, or hqlorderbyclause, the window will work, but in classic mode, and you will not be able to benefit from all the new features of the Openbravo 3 windows.

You can take a look at how hql clauses are defined in Openbravo Core windows to see how you should define your own.

Application Dictionary Column default values

There is a small but important change of behaviour in Openbravo 3 windows, regarding default values. In Openbravo 2.50, Application Dictionary columns have a default expression which is executed if there is a field for that column in the tab. If there is no field, however, that expression will just be ignored.

In Openbravo 3, however, this is not the case. If the default expression is a "simple one" (that is, if it's not a complex SQL expression like "@SQL=SELECT COALESCE(MAX(SeqNo),0)+10 AS DefaultValue FROM AD_Column WHERE AD_Table_ID=@AD_Table_ID@"), the expression will be executed when the record is saved, if there is no field for the column. If there is a field for the column, the behaviour will be the same as in 2.50.

In a related note, as was previously mentioned, Openbravo 3 windows use the Data Access Layer to do operations in the database, and therefore, database physical default expressions will be ignored.

Manual code changes

Previous considerations

There are new functions that should be used when needed:

This functions call be invoked from any window/popup of Openbravo independently of the frame deep.

Form related javascript changes (mandatory)

Javascript structures like top.whatever should be changed by the proper one using the new getFrame() function (top.whatever moves to getFrame('main').whatever in most cases)

Popup related javascript changes (mandatory)

Javascript structures like something(optional).opener.top.whatever should be changed by the proper one using the new getFrame() function (something(optional).opener.top.whatever moves to getFrame('main').whatever in most cases)

Multiple-browser support style changes (optional)

A lot of changes have been developed in core in order to proper visualization of Openbravo ERP 2.50 in Chrome, Safari and Opera. The only change required in manual code is related to the proper visualization of the MessageBox (without it the messagebox of the affected html will display ugly in the mentioned browsers): These changes affects to modules with manual windows and a MessageBox inside them.

The change is: This structure

<table cellpadding="0" cellspacing="0" style="width: 100%;">
<tbody>
<tr>
<td class="MessageBox_LeftTrans">

should be changed by this structure

<table cellpadding="0" cellspacing="0" class="MessageBox_Container">
<tbody>
<tr>
<td class="MessageBox_LeftTrans">

Notice that the only change is the table style tag by a class tag

Open popups as 3.00 modal popups (optional)

Since 2.50 MP24 + 3.00 RC3 there is the possibiliy of open classic browser popups inside new 3.00 modal popups. The result will look like:

ModalPopUp.png

The needed changes are:

a) In the page which performs the call (could be from a form -95% of the cases- or from another popup) [opener]:

Typical case: If there is something like

openServletNewWindow('DEFAULT', false, '../ad_process/ApplyModules.html', 'BUTTON', null, true, 700, 900);

is should be changed to

openServletNewWindow('DEFAULT', false, '../ad_process/ApplyModules.html', 'BUTTON', null, true, 700, 900, null, null, null, null, true);

Notice that in this typical case you shouldn't change anything with "openPopUp" since "openServletNewWindow" is already in charge of call it.


b) In the html of the popup that is going to be opened [opened popup]:

Examples:

Opening modal processes

Processes invoked from menu or buttons in tabs are opened by default in browser popups. Starting from 3.0RC4, they can be configured through properties to be opened in modal popups.

This is managed through 2 sets of preferences: ModalModule* and ModalProcess*.

The steps to do set these properties are:

PopupProcess.png

Retrieved from "http://wiki.openbravo.com/wiki/How_to_Migrate_2.50_Modules_to_3.0"

This page has been accessed 5,684 times. This page was last modified on 4 July 2011, at 11:37. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.