Home Contact Buy
Sitemap Contact
Home Download Video Free Buy Sitemap Contact

How to Upgrade Time Tracker

This document describes how to upgrade Anuko Time Tracker from an older version to the latest. The upgrade procedure is relatively straightforward:
  • Start with a working old version.
  • Deploy a new code on the server and execute relevant update steps in dbinstall.php.
The rest of this page provides further details and describes some issues that may arise and how to solve them.

Before You Start

You'll need to have any one of the following to start upgrading.
  • Access to an older Time Tracker running.
  • team_data.xml file. A team manager can create this file on the Export page in Time Tracker.
  • Database dump.
We start with any one item from the above list, and, upon completion of the steps described below, have the latest Time Tracker running with migrated data.

Backup Database and Code

Backup your database and the code first in case something goes wrong and you need to rollback.
  • Backup the database using mysqldump.
  • Backup your existing code by making a copy of the directory from where Time Tracker runs.

Have Old Time Tracker Running

If you have the old version already running (your current production environment) make a copy of the code to another directory. Also, make a copy of the database and configure it to use it. This makes sure we don't interfere with production data during upgrade.

Alternatively, you can download and install the old version of Time Tracker on another server. Issues may arise because your environment is now different. For example, a newer version of MySQL server may complain about timestamp syntax in mysql.sql:
`al_timestamp` timestamp(14) NOT NULL,
To make installation possible modify all such lines by removing the brackets with what is inside, so that it becomes:
`al_timestamp` timestamp NOT NULL,
Another common problem is PEAR configuration. Time Tracker starting from version uses PEAR that is built-into its own directory structure. Older versions need an externally installed PEAR with DB module. Integrated PEAR does not have DB module. Instead, it uses MDB2. Therefore, you may need to install PEAR separately.

If all goes well, by this point we have the older Time Tracker running, meaning that you can create a team on it and log time. Test it.

Start with Old Data

If you already have a working database copy, go to the next step. Otherwise, login to Time Tracker as admin (default password is "secret" without quotes) and import team from team_data.xml file. A couple of issues may arise here if your file is large.

File Upload Error

If you see this, it means that the file cannot be uploaded, most likely because of its large size. One thing to try is to export a compressed file from your original server to see if it works.

Another thing to try is to tweak the following values in php.ini to accommodate your file size:
Restart your web server for changes to take effect. Finally, in Time Tracker code, find and change the maxsize value in this line in import.php file:
$form->addInput(array('type'=>'upload','name'=>'xmlfile','value'=>'browse','maxsize'=>16777216)); // 16 MB file upload limit.
// Note: for the above limit to work make sure to set upload_max_filesize and post_max_size in php.ini to at least 16M. 
This should take care of the File upload error.

Blank Page during Import after Timeout

If your data set is large, Time Tracker will timeout and display a blank page during the import operation. To fix this, adjust the following value in php.ini:
max_execution_time = 3600     ; Maximum execution time of each script, in seconds
Restart your web server to notice the change.

If all goes well, you should see the Import completed successfully message on screen when import is finished. Now we have old team data on the old version in Time Tracker.

Install New Time Tracker Code

  • Remove old Time Tracker code.
  • Download new Time Tracker code and deploy it.
  • For UNIX systems set up full access rights for catalog ./WEB-INF/templates_c/ (chmod 777 templates_c).
  • Prepare ./WEB-INF/config.php by first making it a copy of ./WEB-INF/config.php.dist and then adjusting the DSN string in it:
define('DSN', 'mysql://root:no@localhost/dbname?charset=utf8mb4');

Upgrade Database Structure

Point your browser to dbinstall.php file in the root of Time Tracker installation. You should see something like this:

DB Install page in Time Tracker
DB Install page in Time Tracker

Carefully execute update steps in sequence from top to bottom that are relevant to the version you are upgrading from. For example, if you started from 0.9.7, then all of the following steps must be done:
  • Update database structure (v0.7 to v1.3.3)
    • Update
    • Update projects
  • Update database structure (v1.3.3 to v1.3.40)
    • Update
    • Update companies
  • Update database structure (v1.4.85 to v1.5.79)
    • Update
  • Update database structure (v1.5.79 to v1.5.97)
    • Update
    • Update clients
    • Update custom fields
    • Update tracking mode
Examine output at each step. It is normal to see some errors at the beginning of the first step as you may be upgrading from the middle of it and already have partially changed db structure. However, all of the following steps must produce no errors with the exception of step v1.4.85 - v1.5.79 (it may generate two errors when dropping non-existing indexes client_name_idx and ub_id_u, but no other errors).

If you clicked a wrong button and see a lot of errors, start over by having an original database, and then executing all steps in proper sequence. It may help if you prepare a check-list of the steps required and execute them one after another.

Dealing with Corrupted Characters after Upgrade

In some situations, an updated Time Tracker may show corrupted characters. There are at least 2 possible reasons for this.

Double Encoding

If you use mysqldump, some characters may become double-encoded. The result of this is that characters like ß in "Straße" are displayed with two symbols like "Straße" on your Time Tracker web pages. A solution to this issue is described here.

Wrong Connection Charset

This character corruption manifests itself differently. Instead of double encoding you may see incorrect encoding for some characters. For example, accented French letters are displays as black diamonds with a question mark inside.

Corrupted French characters
Corrupted French characters

It happens because database data are stored in one encoding (such as latin1) but your connection string in DSN value in ./WEB-INF/config.php file uses a different charset or not uses one at all.

Note: prior to version the charset parameter was not provided in ./WEB-INF/config.php.dist file. When charset is not specified, the default charset is used, whatever it is. Use the following mysql command to get some ideas of what the default charset might be on your system.
mysql> show variables where variable_name like 'character_set_%';
| Variable_name            | Value                      |
| character_set_client     | latin1                     |
| character_set_connection | latin1                     |
| character_set_database   | latin1                     |
| character_set_filesystem | binary                     |
| character_set_results    | latin1                     |
| character_set_server     | latin1                     |
| character_set_system     | utf8                       |

There are two ways to fix the charset issue.

For a quick fix specify the same charset in the DSN constant. For example, if your connection charset used to be latin1, use it after migration as well:
define('DSN', 'mysql://root:no@localhost/dbname?charset=latin1');
Or do not use one at all:
define('DSN', 'mysql://root:no@localhost/dbname');
If it works - great! However, not using a connection charset, or using a wrong one (not utf8mb4) is a bad idea. It may get you into trouble during future upgrades. To fix this, try the following: convert the data to utf8mb4 with mysqldump, import the data into a new database, and then use utf8mb4 charset in the DSN constant in config.php. In other words:
  • Dump the database using mysqldump.
  • Restore it in to a new database.
  • Use utf8mb4 charset in DSN string for database connections.
define('DSN', 'mysql://root:no@localhost/dbname?charset=utf8mb4');

If all goes well, Time Tracker should be updated by now. If you need help with any of the above you can order a support incident.

Time Tracker Install Guide