View source for Upgrading from ofbiz 3.x to opentaps 0.8

opentaps 0.8 features many enhancements to the core framework and significant advances in all of the applications.  As a result, opentaps 0.8 is more secure, stable, and feature-rich than OFBiz 3.0/3.1.  This document will show you how to upgrade from OFBiz 3.0/3.1 to opentaps 0.8

'''Key Changes from OFBiz 3.0/3.1 to opentaps 0.8'''

# Splitting up the application components into framework and applications directories
# Some script/ and src/ files have been moved around as a result of the change
# The XML files now use XSD instead of DTD
# Some entity and service definitions have been moved around to break up large monolithic entitymodel and services xml files into smaller pieces
# Seed and demo data is now split up so you can install seed data without the demo data
# Many screens have been re-factored from JPublish and JSPs to screen-widget
# Screen widget allow reuse of same templates across applications now, such in order manager and ecommerce, reducing the number of duplicate templates.
# Significant amount of changes to the entity model and service definitions
# Whole new applications such as manufacturing and point of sales have gone from early to production versions
# Lots of new framework tools
# Lots of bug fixes and improvements 

This is a non-trivial upgrade. Nevertheless, you will gain the benefit of significant new application features and enhancements to the underlying framework.

'''How to Upgrade'''

Most of the upgrade involves moving files around to the new directory structure of opentaps 0.8 and upgrading your database by altering the tables and inserting primary key data to be compatible with opentaps 0.8.  If you have customized your application, the notes below should help you verify your code.  You can also download a SQL script and a data model and API comparison report which should help you with your upgrade process.
Moving files around

The first step of the upgrade should be to move files around, specifically:

# Rename your old components/ directories to applications/ and framework/
# Move src/ directories' .java files which have moved about
# Move script/ directories' .xml files
# Move config/ directories' files
# Move entity definitions which have moved from one XML file to another
# Move service definitions from one XML file to another 

'''Converting DTD to XSD'''

All of your custom XML files, including services, entity, controller, minilang definition files must be changed to use XSD instead of DTD. This involves changing the XMl file header.

'''Reinstall the Seed Data'''

There is a lot of new seed data. Fortunately, now that seed data is separated out, you can do an:
 $ ant run-install 

to install the new seed data. Be careful, though, that this resets your admin password to the default of "ofbiz" and re-enables all the default userlogins as well (they are part of the seed data.) So it is really important to change your admin passwords as soon as you do this.

'''Entity Relationships'''

Because the entity engine now automatically creates backward pointing relationships, you can safely remove hardcoded back relationships. Use the warning messages from the entity engine on startup to help you with this.

In particular, in parent-child relations, you can remove the child-to-parent "many" relations, as they are automatically created.

Also get rid of entity relationships that no longer exist (see the "opentaps0.8_ofbiz3.1.zip" file.)

'''Database Changes'''

The entity model definitions have also changed, so you may have to alter your database columns. Again, follow the entity engine warnings on startup and drop or modify your columns as needed.

There is now a new primary key for SupplierProduct of minimumOrderQuantity. If you did not have this before, set them to 0.0 in your database.

Also sales tax has a new primary key minItemPrice which needs to be set to 0 if you did no thave any values before.

'''Encrypting Fields'''

Some fields such as credit card, EFT account, passport, social security, and gift card numbers are now encrypted. Existing data in the database need to be encrypted as well. You can use the entity engine to encrypt the existing fields in the database by turning off encryption first, using the entity engine to encrypt the fields, storing the fields, then turning encryption back on again.

'''View layer changes'''

Screen widgets were introduced, and many existing templates were changed from JPublish to screen widgets. If you still need to use JPublish, you can add the JPublish handlers back into controllers.

Also, some classes of the view layer were changed as we moved from components to framework and applications structures. For example, org.ofbiz.content.webapp.* became org.ofbiz.webapp.* and org.ofbiz.content.widget became org.ofbiz.widget.* sed is your friend here.

If you reference files explicitly, such as a survey template, using "components/...", you now have to change them to "applications/..." or "framework/..."

In jpublish.xml, components/common need to be changed to framework/common

The old ${pages.get(...)} no longer works, as there is no longer a JPublish pages repository to get from. You would have to re-write your page composition using the new screen-widget. There are two ways to do it:

# Define your .ftl page as a screen and use the new ${screens.get(...)}
# Take page composition out of .FTL altogether and do it in screen widget instead. An example of this is the product page in ecommerce. In OFBiz 3.0, for example:

controller.xml:
 <view-map name="product" type="jpublish" page="/catalog/product.ftl"/>

product.ftl:
 ${pages.get(requestAttributes.detailTemplate)}
 productdetail.ftl:
 ${pages.get("/catalog/productshortsum.ftl")}
 ${pages.get("/catalog/productsummary.ftl")}

In opentaps 0.8:
controller.xml:
 <view-map name="product" type="screen" page="component://ecommerce/widget/CatalogScreens.xml#product"/>

CatalogScreens.xml#product:
 <include-screen name="${detailScreen}"/>

In either case it would require defining a screen whose purpose would be solely to include a .FTL. An example is applications/ecommerce/widget/CatalogScreens.xml#breadcrumbs:
 <screen name="breadcrumbs">
  <section>
  <actions>
    <property-map resource="CommonUiLabels" map-name="uiLabelMap" global="true"/>
  </actions>
  <widgets>
    <platform-specific><html><html-template location="component://order/webapp/ordermgr/entry/catalog/breadcrumbs.ftl"/></html></platform-specific>
  </widgets>
  </section>
 </screen>

'''Request Attributes'''

JPublish used the equivalent of request.setAttribute/.getAttribute (actually, a setRequestAttributes operation and a requestAttributes variable) to pass data from one FTL page to another.

The OFBiz screen widget is more abstracted and does not rely on a "request". Rather, it sets data into the context in a screen. Thus, code which required request attributes have been changed to use context. This would affect how your pages should be re-written.

'''UI Label Maps'''

In OFBIZ 3.1./3.0 uiLabelMaps were set in the request as an attribute by a beanshell script called envsetup.bsh, usually in WEB-INF/actions/includes/.

opentaps 0.8 now uses the screen-widget, which sets uiLabelMaps in the context directly. Thus, there is no longer a need to have lines of code like: <#assign uiLabelMaps = requestAttributes.uiLabelMaps> in your .FTL scripts. In fact, they would cause crashes because they are no longer in requestAttributes. You should remove those pages or put them into <#if> blocks.

'''API Changes'''

This is a really odd one: getProductCategoryAndLimitedMembers now returns a starting view index value of 1 instead of 0. It may cause some "Index out of bounds errors" in your online store after you upgrade.

You can no longer create GenericValues using a GenericValue constructor, so you'll need to change all those to use delegator.makeValue(....)

UtilCache class has moved from org.ofbiz.base.util.UtilCache to org.ofbiz.base.util.cache.UtilCache

'''Shipment Groups'''

This is a big changes: orders are now divided up into shipment groups. Method calls during checkout may now require a shipment group idea, and previous data about order shipments would have to be migrated to shipments.

'''Preprocessor for ShoppingCart in Controller'''

If you have a custom ecommerce store, you may need to add the following:

 <event type="java" path="org.ofbiz.order.shoppingcart.ShoppingCartEvents" invoke="keepCartUpdated"/>

to your controller as a preprocessor, or you may have problems with order partyId's being lost.

'''Configuration Changes'''

carol.properties is no longer used--it has been split into iiop.properties and jrmp.properties, so you should copy the values and remove the old one.

'''EntityListIterator Changes'''

The EntityListIterator is more controlled than before. For example, you can no longer do a findEntityListIteratorByCondition without wrapping it in a transaction. In some other cases you'll get warning messages. So unless you really need it, it's better to change your code from using the ELI to regular finds.