Pika 400 Upgrade Guide
By Matthew Friedlander
Pika Software (http://www.pikasoftware.com/)
|Table of contents|
Pika 4.0 Upgrade Guide
This guide is a short walk-through of the process of upgrading your 3.x Pika CMS to the new 4.0 version released at the end of 2008. As many of you have customizations to your system this guide is not intended to address specific custom code, merely to outline the process as a starting point in planning your specific upgrade.
If you have not already done so please download the newest version of Pika and unzip it into a temporary directory that can be viewed via a web browser for testing. The newest version can be downloaded from here (http://pikasoftware.com/files) at no cost to those of you with a current Pika subscription.
Upgrading your current Database
Included in the Pika CMS files are a group of sql scripts that will upgrade a 3.x version of Pika to the most current version. These are located under the pika_dir/app/sql/upgrades folder in the release. In order to ensure that the upgrades work please make a backup copy of your database. Usually we recommend creating another copy in order to test the upgrade and locate any problems that may occur before working on the production copy. For example if your database is named pika you would create a copy named pika_400 in order to go through the upgrade process.
In this case I'm going to use an example to walk through the process. In this example you have a Pika CMS version 3.03 database.
- Create a copy of the database named pika_400
- Since your current Pika CMS is version 3.03 start by running each successive version upgrade file in sequence
- That would mean running pika304.sql, pika306.sql, and pika400.sql in sequence on the pika_400 copy database.
- If any of the files report errors (usually due to custom fields) correct the issues or contact Pika support for assistance if you are unsure.
Pika CMS 4.0 Setup
Once the database has been successfully upgraded to version 4.0 you can then enable the test site to read it. Under the pika_400 directory that you set up earlier open the pika_400-custom/config directory and edit the settings.php file to point to the upgraded database (ex. $db_name => pika_400 - $db_user => pika - $db_password => password need to be populated with the correct credentials). Update the base_dir and base_url variables to the correct locations for your setup (ex $base_url => /~pika/pika_400 and $base_dir => /home/pika/pika_400). Once you have completed this process use your web browser to navigate to the new site and attempt to log in to your new Pika CMS 4.0 install.
<?php $plSettings = array ( 'db_type' => 'mysql', 'db_host' => 'localhost', 'db_name' => 'pika_400', 'db_user' => 'pika', 'db_password' => 'password', 'cookie_prefix' => 'Pika 4.0', 'enable_system' => '1', 'enable_compression' => '1', 'enable_benchmark' => '0', 'enable_html_tidy' => '0', 'autonumber_on_new_case' => '1', 'owner_name' => 'Pika 4.0', 'admin_email' => 'email@example.com', 'act_interval' => '15', 'base_url' => '/matt/dev/pika_400', 'base_directory' => '/home/matt/www/pika_400', 'xchg_directory' => '', 'xchg_url' => '', 'time_zone' => 'America/New_York', 'time_zone_offset' => '0', 'docs_directory' => '', ); ?>
Database Doc Storage
As of Pika CMS version 4.0 we have moved document storage and management into the database. In previous versions we have used the folder doc_storage under the Pika main directory to house all case related files and a forms directory to house all of the form letters for Document Assembly. In order to upgrade to this new system we have included the fs2db.php file script to migrate all Pika Case files and Form letters into the database.
We will break down the conversion process into several steps.
- Copy your current doc_storage directory from your current production site to the new pika_400 directory.
- Edit the fs2db.php script file, populate the database name, user, and password to the pika_400 database created in the previous step
- Save and close the fs2db.php script.
- Navigate your web browser to the script (ex. http://yoursitename/pika_400/app/scripts/fs2db.php) and run it.
The fs2db conversion script runs through the documents table in your database and uploads each file into the new doc_storage database table. During this process it will look to see what the largest file in your document storage is and will report it to you. This is important due to the fact that MySQL has a size limit on the length of queries submitted (max_allowed_packet). If you MySQL server has a size limit below the largest file the script will warn you that its size is insufficient and stop. To adjust the size of your MySQL server you will need to alter the my.cnf configuration file max_allowed_packet variable to a size large enough to accommodate your files (ex 16MB).
[client] socket = /var/mysql/mysql.sock [mysqld] socket = /var/mysql/mysql.sock max_allowed_packet = 16M
One other item you may encounter will be directory permissions for the doc_storage directory. You should, following the directory copy, change the file permissions to 777 (or global full access) for all of the directories and files in doc_storage.
chmod -R 777 /home/pika/pika_400/doc_storage
The fs2db script, once run, will take time to complete the uploads depending on how many documents you have stored in Pika. During my testing I noticed that it was roughly equivalent to 30 minutes per gigabyte to upload (your experience may vary with different hardware). Once the script is complete it will output all warnings and errors and give you some statistics on how many files were uploaded and how many errors and warnings it encountered. Many of the errors will pertain to orphaned records which may or may not be an issue unless it is a significant number in relation to the total number of documents.
Once the script has completed log into the pika_400 site via your web browser and examine several cases with documents to make sure that they have transferred successfully. Once you are satisfied that everything is working properly delete the copied doc_storage directory from the file system.
Finally, I'd like to review the process of moving over your Pika CMS 3.x customizations. As customizations come in a myriad of forms and levels of complexity and integration I will merely go over some guidelines on how we approach this proceedure.
As of Pika CMS 3.06 we have added an additional directory structure to host customization code. This is the -custom directory that sits next to the pika main application directory. Here is a listing of how this appears in Pika 4.0.
/pika_cms-400-custom /case_tabs /config /js /modules /subtemplates /template_plugins /templates
In an effort to make upgrades less painful for those of you with custom code we have added the case_tabs, js, modules, subtemplates, template_plugins, and templates directories. When a script in Pika looks for files listed under any of these directories it will check the -custom directory first. This allows you to keep your custom code separate from the standard Pika codebase. It is hoped that in the future all that will be required for upgrades is to copy over your pika-custom directory to the new version and all of your changes will be carried over with no further intervention or coding. Currently this structure allows you to incorporate customizations of the following types:
- Subtemplates/Templates - any html template file can be used with the custom directory and will override the existing html template if present.
- Case Tabs - any case tab that is implemented in the current Pika can have a customized version in the -custom/case_tabs or -custom/modules directories
- Template Library Plug-ins - any plug-in function for the templating library (New template library only (pikaTempLib))
For example, you want to add an additional field to the Case Info tab in Pika. To do this you only need to copy the case-info.html under pika/subtemplates/case-info.html to pika-custom/subtemplates/case-info.html and make your changes to that file. Pika will check to see if there is a newer custom version of that file under the -custom directory as it is assembling the Case Info tab. It will detect the case-info.html file in the custom directory and load that in lieu of the standard pika/subtemplates/case-info.html.
When a new version of Pika is released at a later time and you go to upgrade all that is required to move your custom case-info.html into the new version is to copy the file over to the new custom directory. This helps to ensure that customizations are moved seamlessly from one version to the next without significant searching or re-programing.
The purpose of this guide is to outline the steps required to upgrade your Pika CMS install to the new 4.0 versions. Depending on the complexity of your Pika CMS install and the amount of customization that has been done you may require further technical assistance. If you have any questions concerning this process or have any suggestions or corrections for this guide please feel free to send them to Pika Support (mailto:firstname.lastname@example.org).