Simple Migration for Unmodified-opentaps Users

CAUTION: THIS IS A ROUGH DRAFT PAGE NOT READY TO USE -- Has Not Passed Testing Yet.

Migration of your current opentaps Version 1.0.X installation to a new one running Version 1.4 will be discussed, step-by-step in this section.

Back-up Your Current Version 1.0.X Installation

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

Back-up Your Database

If you are in production with opentaps then you have a database backup method that you are using already. This must be a backup method that you have practiced, so that you know it works, including the practice of restoring the backup copy and putting that restored copy back into production again.

You will want to backup your current production database before you start migrating to opentaps Version 1.4. Then, you can follow the migration guidelines which will modify your currently existing database to accomodate changes required for Version 1.4. After the modifications for Version 1.4, the database will no longer work with earlier releases of opentaps, but you will have your backup copy saved in case you run into any problems requiring you to go back to the earlier version.

Preserve Your Current Installation Directories and Configurations

There are two very important reasons why you will want to preserve your current older version of opentaps installation directories and the files they contain.

Copying XML configuration files and properties

First, your current, older version, installation directories contain all of the configuration files, and files containing set-up "Properties" used to fully configure the opentaps system. Thus, these files are the comprehensive record of how the system is currently set-up.

You can copy much of the critical information from these files and documents from the old version to the new version, or you can refer back to the older version if you have questions later about how it was set up before you migrated.

Your Fall-Back Strategy in Case of Problems

Your current, older version, opentaps installation is the best fall back strategy you have for continuing production in the unlikely event that you have problems in getting the new Version 1.4 up and running without problems, and on time.

Thus, you should plan to install the new Version 1.4 in a new installation directory, while preserving the old one without modifications. Then it will be available to bring up along with the restored data from the old system.

Alternate Strategy for Server Migration

Many Users who have opentaps in production will have a separate server that they use for testing purposes, sometimes for their own company modifictions to the configuration, that are developed as the company grows, and also for other testing like upgrades to system code or upgrades to opentaps.

You can use such a test server installation to practice your upgrade to opentaps Version 1.4 so that any problems may be found and resolved before you attempt to put the production site through your upgrade changes.

When an upgrade involves changing out multiple major items of the server software or hardware at the same time, a separate test environment can be used to avoid unexpected problems on the production site.

Install opentaps Version 1.4 and Upgrade Your Current Database

We do not repeat opentaps Installation guides in this section, but rather we refer to the opentaps Installation Manual, which contains a wealth of information useful to those planning migration to the latest version.

Select Or Upgrade Your Opentaps Host Server

New options are available for hosting the opentaps system, including the use of Amazon EC2, which provides virtual servers running in the Amazon server cloud environment. This setup allows an opentaps User to instantiate their own opentaps system by using the pre-installed image that resides on EC2. (One word of precaution, however. Using Amazon EC2 will be very similar to using standard Ubuntu Linux, so be prepared for that experience if that will impact your migration strategy.)

Install opentaps Version1.4

For the next step, refer to the detailed installation guide, Opentaps Installation Manual, which provides sections for installing on Linux, Mac OS-X, and on Windows.

*  Follow the directions to install on your type of system. 
*  Then you will be directed to follow the directions for starting opentaps for a brief test. 
***  Don't connect to your own database yet.

As a test, to verify that the installation was successful, you can start opentaps Version 1.4 as described in the installation guide. You will be running with the demo data (not your own data), and this test is just to verify that the system comes up running and that you can log-in to it.

* Start opentaps Version 1.4.
* On the Main Navigation Screen, proceed to Log-in,
* In the "opentaps Login" box, on the left side, 
* Enter Username: admin
* Enter Password:  ofbiz
* Click: [Login], the Main Navigation Screen opens again with more large Icons. 
* Click: the first large Icon, "iii", which is the CRM/SFA Icon.
* The MyHome screen opens in the CRM/SFA application of opentaps.
* Your installation was successful. 

*** Now Stop opentaps before proceeding to the next step.

If you do not get the results described, return to the Opentaps Installation Manual and review your work, and the last section of the installation guide you used, that deals with problem shooting.

Pointing to Your Existing Database

Next, you will point your new installation to work with your existing opentaps database, so that the database upgrades can be performed, making it compatible with Version 1.4 (and no longer compatible with the older version of opentaps).

Since your database is already set up, with a login ID and password specified in the opentaps 1.0.X files, when you point Version 1.4 to this database you can use the same ID and password that you defined in the earlier opentaps.

Detailed instruction for pointing Version 1.4 to your database are contained in the guide, Using_opentaps_ERP_+_CRM_with_MySQL, or in guide, Using_opentaps_ERP_+_CRM_with_MySQL.

* Stop opentaps before proceeding with the next steps.

* Follow the appropriate directions for pointing opentaps Version 1.4 to your database.
* Copy your existing User Name and Password into the new Version 1.4 files when directed to do so
  in the guide you are following.

This completes the Set-up that points opentaps to use your current database for making the upgrade modifications.

Modify the Current Database to Function with opentaps Version 1.4

Modification of the database is accomplished in three steps, as follows:

1. In the first step, we will finish re-installing the system by running the ant program.
2. Then, in the second step, we will start the opentaps running with the existing database, to further modify it.
3. Finally, in the third step, we will run the upgrade SQL script file which also makes changes for V1.4.

These steps must be run in the specified order to prevent migration problems.

Do not run the SQL script file until it is specified in the third step.  
Proceed as follows:

First Step -- Run the Ant Installer Program

In this step the Version 1.4 system will be installed to run with the modified database. Follow these steps:

1. To avoid having your administrator Username and Password reset by the installer program, make this change before you run Ant: (If you forget to do this, just manually configure the Username and Passwords for all the admin user ids back to the condition you require.)

* Locate the following file within the opentaps installation directory:
      applications/securityext/opbiz-component.xml
* Open the file with your text editor and find this line near the bottom of the file:
<entity-resource type="data" reader-name="demo" loader="main" location="data/PasswordSecurityData.xml/>
* Comment the line out by adding the /!-- in front of the line and --> at the end like this:
/!-- <entity-resource type="data" reader-name="demo" loader="main" location="data/PasswordSecurityData.xml/> -->

2. Next you will run the Ant installer program as follows:

 Caution: After running the ant installer your database will not work with Version 1.0.X any longer.

Open your operating system command prompt.
Make your current directory the opentaps installation directory.
Run the ant program according to the installation guide instructions for
   your operating system, for example in Linux you would do this:
     On the command line, Enter: ./ant run-install-seed, and Press: Enter Key
The command window will display a series of status messages as ant is
   running, making modifications, and installing seed data values.
When it finishes it will provide a "Successful Build" message with the
amount of time taken to run it.

This completes the ant installation step and modifications. Next, we will start opentaps to further prepare the database for operating Version 1.4.

Second Step -- Start opentaps to Make More database Adjustments

To start opentaps:

Start opentaps as described in the installation manual for your operating
system, for example if you are using Linux navigate to the installation directory, and
Run: ./startofbiz.sh

Third Step -- Run the Upgrade Script for Your Database (MYSQL or POSTGRES)

Notice: When executing the upgrade script, first stop opentaps server before you run the script.

This step will run a script that modifies the database entities for use with opentaps Version 1.4. Follow this procedure to run it:

• The upgrade SQL script is in the Version 1.4 installation directory, and sub-directory hot-deploy/opentaps-common/scripts/sql
• Run the script version for the database you are using, either upgrade.mysql or upgrade.postgres.
• The script alters tables and automatically fills in some values, and it updates key fields so that opentaps will generate correct future keys.

Example: Running the upgrade SQL file with MYSQL

The following is an example of how to run the SQL upgrade script for an opentaps 1.0 MYSQL database that is being migrated to opentaps Version 1.4 on Linux.

* On the command line, change directories to the opentaps installation and then,
* Change directories to hot-deploy/opentaps-common/scripts/sql
* Note that in this directory you have a copy of the upgrade script, upgrade.mysql and another one for Postgres
* Make sure you are using a login ID with MYSQL in the next step, which has ALL privileges on your 
      database that is going to be modified, so that the SQL statements will execute.
* Run this command: mysql your_db_name < upgrade.mysql
* The upgrade script will run, and this completes those modifications

Start opentaps Version 1.4 and Run Data-Services

In this step, we will start opentaps and then run several "Services" which prepare data required for operating Version 1.4 with the database.

To start opentaps:

Start opentaps as described in the installation manual for your operating
system, for example if you are using Linux navigate to the installation directory, and
Run: ./startofbiz.sh

Run Version 1.4 Services that Set Up Some Data Fields

This step runs several of the "Services" stored in the opentaps server. Use the following guide:

Step-By-Step Running the Services

Next, after opentaps has started, we will navigate to the Services that we need to run.

Login to opentaps as the administrator on your system, using the Username and
Password for the administrator which is found in your own database, which we are now using. 
On the Main Navigation Page, Click: [Webtools] Icon,
Point: Mouse over the [Framework Web Tools] menu, and then 
Click: [Service Engine Tools], the "Service List" page opens.
Click: [Run Service] in the Sub-Tabs, the "Run Service" page opens. 

From this page we can run each of the five needed Services to prepare data fields. Proceed to run these as follows:

* Enter in the Service box: recalcAllEmptyAmountsPayments
* Leave the Pool box unchanged, it already contains the entry: pool
* Click: [Submit]

* Enter in the Service box: recalcAllEmptyAmountsInvoices
* Leave the Pool box unchanged, it already contains the entry: pool
* Click: [Submit]

* Enter in the Service box: updatePostedAmountAcctgTrans
* Leave the Pool box unchanged, it already contains the entry: pool
* Click: [Submit]

* Enter in the Service box: opentaps.setSupplementalDataForAllParties
* Leave the Pool box unchanged, it already contains the entry: pool
* Click: [Submit]

* Enter in the Service box: opentaps.createHibernateSearchIndex
* Leave the Pool box unchanged, it already contains the entry: pool
* Click: [Submit]

This completes the use of Services for data preparation.

Additional Manual Configuration Items

The following items are among those that will need to be manually configured on Version 1.4 following the migration steps already completed. To configure these items in Version 1.4, refer to the User Guide sections included in the chapter, Opentaps_Users_Manual#Step-By-Step_Configuration_for_Business_Process_Administrators

Add the List Here . . . 

Back-Up the New Installation and Database

The opentaps Version 1.4 server is now ready to test for deployment in production. You should use your own usual test method and decision criteria for determining that the opentaps server is ready for deployment in your company.

Meanwhile, you may wish to backup the new installation with its modified database for the first time.