Difference between revisions of "Upgrading from opentaps 1.0 to opentaps 1.4"

From Opentaps Wiki
Jump to navigationJump to search
(→‎Coding Changes)
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
  
−
== Data Changes ==
 
  
−
* Run the service <tt>opentaps.setSupplementalDataForAllParties</tt> to populate primary contact data for all parties.
+
These instructions for upgrading existing '''opentaps''' installations are provided in two parts, the first part is for the users of unmodified 1.0.X versions of '''opentaps''' who would like to migrate their installation and existing database to the new Version 1.4.  The second part of the instructions is for users of customized 1.0.X versions who want to upgrade to '''opentaps''' Version 1.4 and to migrate their customizations also.  
−
* Configuration of GL accounts for invoice writeoffs have been changed. Instead of using <tt>GlAccountTypeDefault</tt>, they are now configured with <tt>InvoiceAdjustmentGlAccount</tt> with the adjustment type "WRITEOFF"
 
−
* If you have custom UI labels, they may be loaded by adding them to <tt>LabelConfiguration.properties</tt> in <tt>opentaps-common/config/</tt>
 
−
** If previously you were using <tt>UtilMessage.registerLabelMap()</tt> to load custom labels, you may now remove all calls to this function as it is no longer needed.
 
−
* Run the upgrade SQL script in hot-deploy/opentaps-common/scripts/sql for the following:
 
−
** <tt>ProductAverageCost</tt> has been re-factored to use a single productAverageCostId as its primary key.  The script will alter the table and automatically fill in its values and update <tt>SequenceValueItem</tt> so that opentaps will generate correct future keys.
 
−
* Add the following to your custom component's build.xml:
 
−
  <fileset dir="${ofbiz.dir}/hot-deploy/opentaps-common/lib" includes="*.jar"/>
 
−
  <fileset dir="${ofbiz.dir}/hot-deploy/opentaps-common/lib/hibernate" includes="*.jar"/>
 
−
* Set <tt>SupplierProduct.supplierPrefOrderId</tt> to '''10_MAIN_SUPPL''' where it is null.
 
  
−
== Coding Changes ==
+
In either case, '''opentaps''' Users should take note of a few changes in the installation requirements, and in the requirements for hardware, which are summarized here for convenience in preparing a migration strategy for your systems.
  
−
Changes in the ofbiz framework would require the following changes to your code:
+
# The change in JAVA SDK Requirements -- Some users of '''opentaps''' 1.0.X will find that the required version of the JAVA SDK has changed since their earlier version was installed.  These are the details:  opentaps 1.4 pre-compiled download from Sourceforge.com works with Java 6, and you must use the Sun Java SDK (software developer kit) version of JAVA for your opentaps installation.
 +
# The change in Hardware CPU and RAM Requirements -- With many software improvements, and functional additions that are included, the new '''opentaps''' Version 1.4 needs more hardware resources to provide snappy perfromance.  For  the details on recommended hardware, please see [[Hardware Server Guidelines]].
 +
# Additional Installation options are discussed in [[Opentaps Installation Manual]].
  
−
=== URL Parameter Security ===
+
The new '''opentaps''' Version 1.4 offers many improvements in usability, functionality, and feature advantages that can make upgrading your system worthwhile.  For a summary of the key enhancements in Version 1.4, please refer to [http://www.opentaps.org/products/opentaps-14 opentaps Version 1.4 Summary]
  
−
You can no longer pass parameters to a service request directly in the URL.  These requests must be part of a POST form.  To make buttons work as before, you need to change them to forms and then activate them with javascript.  For example, in earlier versions, you could have a button to delete a lead like this:
 
−
  <#assign update_options = update_options + "<a class='subMenuButtonDangerous'
 
−
          href='deleteLead?leadPartyId=" + partySummary.partyId + "'>" + uiLabelMap.CommonDelete + "</a>"  />
 
  
−
In opentaps 1.4, you must do it this way:
+
=== Introduction to Simple Upgrade for Users of Unmodified-'''opentaps''' ===
−
  <form name="deleteLeadForm" method="post" action="<@ofbizUrl>deleteLead</@ofbizUrl>"/>
+
For the many users of an unmodified '''opentaps''' installations, we have condensed the migration instructions into a few simple steps that will convert your existing database, populate new database entities with the initial data required (based upon your historical data), and then come up running a newly installed '''opentaps''' Version 1.4.
−
      <@inputHidden name="leadPartyId" value="${partySummary.partyId}"/>
 
−
  </form>
 
−
  <#assign update_options = update_options + "<a class='subMenuButtonDangerous'  
 
−
            href='javascript:document.deleteLeadForm.submit()'>" + uiLabelMap.CommonDelete + "</a>"  />
 
  
−
For your convenience, there is also a new macro to do this (see ''form'' and ''submitFormLink'' in opentapsFormMacro.ftl):
+
We have not repeated the '''opentaps''' Version 1.4 Installation instructions here.  It is a good idea to read the [[Opentaps Installation Manual]] first, before starting a migration. When we refer to them, use the separate instructions provided for the installation steps:
−
  <@form name="deleteLeadForm" url="deleteLead" leadPartyId=partySummary.partyId />
+
                [[Opentaps Installation Manual]]
−
  <#assign update_options>${update_options}<@submitFormLink form="deleteLeadForm" text=uiLabelMap.CommonDelete class="subMenuButtonDangerous" /></#assign>
 
  
−
The ''form'' macro makes hidden inputs for all parameters (except ''name'', ''url'' and ''method'' that are used to define the form element itself), and also accept nested elements for more complex cases.
+
WARNING: BEST PRACTICES ADVISE -- BACK-UP YOUR DATABASE BEFORE MIGRATING
 +
 +
YOUR EXISTING DATABASE WILL BE MODIFIED AND WILL NO LONGER BE USABLE WITH
 +
AN OLDER LEVEL OF '''OPENTAPS'''.  THEREFORE IT IS ESSENTIAL THAT YOU PRESERVE YOUR
 +
CURRENT DATABASE AS-IS WITHOUT MODIFICATIONS, TO SERVE AS A BACKUP IN CASE OF ANY
 +
UPGRADE PROBLEMS. 
 +
 +
THEREFORE, BACK-UP YOUR DATABASE IN THE MANNER YOU ARE ALREADY USING FOR
 +
PRODUCTION (SO THAT YOU KNOW THE BACKUP CAN BE RESTORED TO PRODUCTION IF NEEDED).
  
−
Also the new ''selectActionForm'' and ''actionForm'' can be used with ''form'' to define a drop-down menu where when an item (''actionForm'') is selected it submits the corresponding ''form'':
+
Follow the Step-By-Step guide for this upgrade,
−
  <@form name="deleteLeadForm" url="deleteLead" leadPartyId=partySummary.partyId />
+
                [[Simple_Migration_for_Unmodified-opentaps_Users]]
−
  <@form ... />
 
−
  <@selectActionForm name="leadActions" prompt="${uiLabelMap.CommonSelectOne}">
 
−
    <@actionForm form="deleteLeadForm" text="${uiLabelMap.CommonDelete}"/>
 
−
    <@actionForm .../>
 
−
  <@selectAction/>
 
  
−
=== Service and HTML inputs ===
 
  
−
As a security feature, the services will filter any input with HTML by default. Some services still require HTML (like emails or templates services) and to allow that there is a new ''allow-html'' parameter. For example:
+
=== Introduction to Migrating Customized '''opentaps''' Installations ===
 +
This section of the Upgrade guide is for '''opentaps''' Users who have implemented some customizations that go beyond the modification of "properties" values in XML files, or "configuration" options available in the standard release packages.  
  
−
    <attribute name="content" type="String" mode="IN" optional="false" allow-html="safe"/>
+
A summary of all data changes, and coding changes which will impact custom code modifications that have been implemented by Users of the '''opentaps''' source code are provided in this section.
−
    <override name="mergeFormText" allow-html="safe"/>
 
  
−
=== Form Widget Changes ===
+
This guide for Upgrading with customized code is available at,  
−
 
+
               [[Upgrading_for_opentaps_Users_with_Customized_Code]]
−
Form widget URL parameters should be specified with <tt>parameter</tt> tag now, instead of in the URL:
 
−
<pre>
 
−
-            <hyperlink description="${contactListName} (${contactListId})" target="viewContactList?contactListId=${contactListId}">
 
−
+            <hyperlink description="${contactListName} (${contactListId})" target="viewContactList">
 
−
+               <parameter param-name="contactListId" from-field="contactListId"/>
 
−
            </hyperlink>
 
−
</pre>
 
−
Do not have it both in the URL and as a <tt>parameter</tt>, or the parameter will be on the form twice and be passed incorrectly.
 
−
 
 
−
=== Controller redirects ===
 
−
 
 
−
Redirects have been changed, now ''request-redirect'' will only copy the parameters that were in the URL string by default. To forward posted or service output parameter, use the ''redirect-parameter'' elements (one per parameter).
 
−
  <response name="success" type="request-redirect" value="viewAccount">
 
−
      <redirect-parameter name="partyId"/>
 
−
  </response>
 
−
Also ''request-redirect-filter-param'' is now considered deprecated.
 
−
 
 
−
=== Js dateTime format ===
 
−
 
 
−
Js dataTime format in ftl have been changed, now the format will return html encode string which will cause the parse exception, you should use StringUtil.wrapString to avoid this issue. For example, in earlier versions, you could have define a js dataTime format variable like this:
 
−
 
 
−
  <#assign dateFormat = Static["org.opentaps.common.util.UtilDate"].getJsDateTimeFormat(Static["org.opentaps.common.util.UtilDate"].getDateFormat(locale))/>
 
−
 
 
−
In opentaps 1.4, you must do it this way:
 
−
 
 
−
  <#assign dateFormat = StringUtil.wrapString(Static["org.opentaps.common.util.UtilDate"].getJsDateTimeFormat(Static["org.opentaps.common.util.UtilDate"].getDateFormat(locale)))/>
 
−
 
 
−
=== BSH embedded in Forms ===
 
−
 
 
−
In Forms widgets you could embed bsh code in order to have more flexibility over the formatting. Those embedded scripts need to be changed to groovy to avoid classpath issues. Fortunately this is as simple as changing the ''${bsh:'' to ''${groovy:''
 
−
 
 
−
For example, in earlier versions, you could transform a party Id into the whole party name:
 
−
 
 
−
  <field name="partyId" title="${uiLabelMap.ProductSupplier}">
 
−
    <display description="${bsh:org.ofbiz.party.party.PartyHelper.getPartyName(delegator, partyId, false)} (${partyId})"/>
 
−
  </field>
 
−
 
 
−
In opentaps 1.4, you must change it to:
 
−
 
 
−
  <field name="partyId" title="${uiLabelMap.ProductSupplier}">
 
−
    <display description="${groovy:org.ofbiz.party.party.PartyHelper.getPartyName(delegator, partyId, false)} (${partyId})"/>
 
−
  </field>
 
−
 
 
−
=== UEL in Minilang ===
 
−
 
 
−
The ofbiz framework now supports unified express language (UEL) in the screen widgets and minilang simple methods.  (See [http://docs.ofbiz.org/display/OFBTECH/Unified+Expression+Language+%28JSR-245%29+in+OFBiz ofbiz wiki])
 
−
 
 
−
One side effect is that code in simple methods, for example:
 
−
  someHash.${someVariableAsKey}
 
−
 
 
−
In opentaps 1.4, you must change it to:
 
−
  someHash[someVariableAsKey]
 
−
 
 
−
=== HTML escaping ===
 
−
 
 
−
The ofbiz framework now automatically encodes most of the data displayed on the page. In some cases this is not wanted, and to avoid escaping in form widget use ''encode-output="false"'' in the field element:
 
−
    <field name="transactionDate" encode-output="false"><date-time/></field>
 
−
 
 
−
In the FTL templates use the ''StringUtil'' class:
 
−
    ${StringUtil.wrapString(someData)}
 
−
 
 
−
Some previous helper methods that constructed HTML code will not work anymore. For example ''PartyHelper.createViewPageLink'' has been replaced with the macro:
 
−
    <@displayPartyLink partyId=partyId />
 

Latest revision as of 13:51, 17 May 2010


These instructions for upgrading existing opentaps installations are provided in two parts, the first part is for the users of unmodified 1.0.X versions of opentaps who would like to migrate their installation and existing database to the new Version 1.4. The second part of the instructions is for users of customized 1.0.X versions who want to upgrade to opentaps Version 1.4 and to migrate their customizations also.

In either case, opentaps Users should take note of a few changes in the installation requirements, and in the requirements for hardware, which are summarized here for convenience in preparing a migration strategy for your systems.

  1. The change in JAVA SDK Requirements -- Some users of opentaps 1.0.X will find that the required version of the JAVA SDK has changed since their earlier version was installed. These are the details: opentaps 1.4 pre-compiled download from Sourceforge.com works with Java 6, and you must use the Sun Java SDK (software developer kit) version of JAVA for your opentaps installation.
  2. The change in Hardware CPU and RAM Requirements -- With many software improvements, and functional additions that are included, the new opentaps Version 1.4 needs more hardware resources to provide snappy perfromance. For the details on recommended hardware, please see Hardware Server Guidelines.
  3. Additional Installation options are discussed in Opentaps Installation Manual.

The new opentaps Version 1.4 offers many improvements in usability, functionality, and feature advantages that can make upgrading your system worthwhile. For a summary of the key enhancements in Version 1.4, please refer to opentaps Version 1.4 Summary


Introduction to Simple Upgrade for Users of Unmodified-opentaps

For the many users of an unmodified opentaps installations, we have condensed the migration instructions into a few simple steps that will convert your existing database, populate new database entities with the initial data required (based upon your historical data), and then come up running a newly installed opentaps Version 1.4.

We have not repeated the opentaps Version 1.4 Installation instructions here. It is a good idea to read the Opentaps Installation Manual first, before starting a migration. When we refer to them, use the separate instructions provided for the installation steps: 

                Opentaps Installation Manual

WARNING: BEST PRACTICES ADVISE -- BACK-UP YOUR DATABASE BEFORE MIGRATING

YOUR EXISTING DATABASE WILL BE MODIFIED AND WILL NO LONGER BE USABLE WITH 
AN OLDER LEVEL OF OPENTAPS.  THEREFORE IT IS ESSENTIAL THAT YOU PRESERVE YOUR
CURRENT DATABASE AS-IS WITHOUT MODIFICATIONS, TO SERVE AS A BACKUP IN CASE OF ANY
UPGRADE PROBLEMS.  

THEREFORE, BACK-UP YOUR DATABASE IN THE MANNER YOU ARE ALREADY USING FOR
PRODUCTION (SO THAT YOU KNOW THE BACKUP CAN BE RESTORED TO PRODUCTION IF NEEDED).

Follow the Step-By-Step guide for this upgrade, 

               Simple_Migration_for_Unmodified-opentaps_Users


Introduction to Migrating Customized opentaps Installations

This section of the Upgrade guide is for opentaps Users who have implemented some customizations that go beyond the modification of "properties" values in XML files, or "configuration" options available in the standard release packages.

A summary of all data changes, and coding changes which will impact custom code modifications that have been implemented by Users of the opentaps source code are provided in this section.

This guide for Upgrading with customized code is available at, 

              Upgrading_for_opentaps_Users_with_Customized_Code
Retrieved from "https://docs.opentaps.org/docs/index.php?title=Upgrading_from_opentaps_1.0_to_opentaps_1.4&oldid=6052"