Upgrading to Timesheet 8.0

Support
Upgrading to Timesheet 8.0

This document applies to upgrading to Timesheet 8.0 or later. Please click here for the older version of this document for installation to Timesheet 7.9.

This document outlines the process for upgrading to Journyx Timesheet 8.0 or higher from an existing installation of Timesheet 7.x. (i.e, 7.0, 7.6, 7.9, etc.) If your organization is running any version of Timesheet prior to version 7.0, you must upgrade your site to Timesheet 7.9 before you can upgrade to version 8.0 or higher. Please contact Journyx Support for assistance with upgrading an older version of Timesheet.

It is important to read this entire page before beginning your migration process. Please make sure you have followed all of the steps in the "Prerequisites" section below.

Please Note: When upgrading, you will need to contact the Journyx Sales department to request a new license key to use with your installation of Journyx Timesheet. Old license keys will not work with Timesheet 8.0 or higher.

If you encounter any problems while performing the upgrade to the new version of Journyx Timesheet, please contact Journyx Support.

Migration Procedure Outline

This is an overview of the steps that go into a successful migration procedure. Please review the detailed instructions in the "Complete Migration Procedure" section below before you actually begin changing anything.

Please read the updated hardware and software requirements (including supported operating systems and databases) for Timesheet, because these have changed for Timesheet 8.
Please read the updated External Database setup instructions, because the requirements and procedures for setting up a database connection have changed. The list of supported database versions has also changed; for instance, Oracle 9i and Microsoft SQL Server 2000 are no longer supported for Timesheet 8 and higher.
Talk to your database administrator. Create a new database user and schema for the new version. Check the other database settings described in Prerequisites below. For a problem-free migration it is critical to make sure the database is set up correctly and has enough free disk space and other resources!
Consider making backups at three different levels: The Timesheet .jx format (the backupdb command), a "native" database system backup such as through the "Enterprise Manager" program, and a Windows or Linux system-level backup. Having an appropriate backup and disaster recovery strategy in place before beginning this process is essential.
Download the new version of Journyx Timesheet. Install it to a new machine (Windows or Linux) or a different account on the same machine (Linux only.) Let it set up a blank/default Timesheet site in the new database account. Leave your production server online until you complete the test.
Do a test migration first on the new machine/account and verify the results. Run backupdb on the production machine during an off-peak time and then run restoredb on the new machine/account to copy the data over. Run some reports and poke around.
Warn your users that a migration is about to begin. Give them a last chance to log in and update their timesheets before a service outage happens.
Make a new backup of your production data with backupdb to get the latest data. Stop the production timesheet site to prevent people from adding new data, but do not uninstall it. Consider using the "Archive" features to only copy the most recent year's data over to the new site.
Restore the new backup to the new version test site with restoredb. When it is finished, make a Timesheet backup of the newly migrated site, as well as a native Oracle or SQL Server backup if possible.
If the new server is to become your permanent server, then you are finished. Tell your users the address of the new server and let them begin using it. Update any bookmarks or links on your Intranet pages if neccesary. Otherwise, move the data from the test server to the production database server, or just point the new versions' application server to the new database account.
Make sure you have an effective backup and disaster recovery strategy in place after you get the new system up and running. Consider scheduling automated backups of the Timesheet site, the database server, and the host operating system(s).

More detailed instructions follow.

Prerequisites

Before you begin the migration process, please follow this checklist and make sure that you have all the pieces in place to perform a successful migration. Most of these items concern the database. If you are unsure of how to check any of these settings, please discuss this document with your Database Administrator (DBA.) You and your DBA should both be familiar with this document and the requirements before you actually begin migrating.

The most important decision to make now is whether to keep your production server intact while you perform a test run with the new version. Journyx strongly recommends that you use a separate server for the migration. In case of any problem or delay in migrating, your original site will still be available. However, if you are running on the Windows Server platform, you will need a separate server machine for the new version, since two versions of Timesheet cannot coexist on the same Windows server. Different versions and sites can coexist on Unix systems as long as each site runs under a different Unix user ID. Virtualization solutions such as VMWare may also be a viable option.
If you are using an external database such as Oracle, and you do not want any chance of impacting your other database applications, set up a test Oracle server in addition to the test Timesheet application server. Otherwise create a new account on the existing Oracle server. Do not under any circumstances use the same account/schema as your current production timesheet server!!
Be sure to read the External Database setup notes as the instructions and requirements have changed. For instance, Oracle 9i and SQL Server 2000 are no longer supported - you might need to upgrade your database server to a newer version, or else switch to the provided high-performance PostgreSQL database.
Create a new database account for the new version and verify that you can connect to this account using the instructions in the External Database setup guide. If using an external PostgreSQL database, make sure your database have been created with the UTF8 (Unicode) encoding and the desired "locale" for sort ordering (collation.)
The rest of this document assumes you will follow those recommendations and have a separate server for the new version. If you choose to not follow this advice, you run the risk of having an extended outage of Timesheet services.
Make sure you have downloaded the latest version of Timesheet and have secured a license key for the new version.
Some databases such as Oracle may require that some special settings are made on the Timesheet application server.
- Be sure to check the registry key HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\NLS_LANG. It should be set to the name of the Oracle locale and character set such as AMERICAN_AMERICA.WE8ISO8859P1 (for the Latin-1 character set with sorting rules appropriate for the USA.)
- Shared Pool -- should be at least 50 megabytes in Oracle. Consider running the command ALTER SYSTEM FLUSH SHARED POOL (as sysdba) just before beginning the restore.
Check that your database schema/tablespace has enough free disk space. The amount of space that you need depends on many factors. For a large site with 1,000 users or more, plan to have at least 3 GB free space or as much as 5+ gigabytes free space if possible. This is very important as running out of space will force you to start over from the beginning. If your site has fewer than 500 users, you may need only 1 GB of database disk space or less.
If you are using an external database such as Oracle, check that your 'TEMP' tablespace has at least 1 GB of usable space, or at least 2 GB for a larger site (1,000 users or more.) Running out of TEMP space shouldn't stop the restore in most cases but may force you to manually rebuild database indexes later.
Check the filesystem permissions for the Timesheet directory. Make sure the "install user" has WRITE access to ALL files in the install directory and below. The "install user" is the system user ID of the user who installed Timesheet. Contact Journyx Support if you are unsure on this point.

Complete Migration Procedure

Double-check database settings and other Prerequisites that are described above.
Download and install the new version of Timesheet to the Test app server and Test database.
Do a test migration run:
1. Make a backup from production using the backupdb tool. Leave the production server online afterwards.
2. Consider using the Archive features of backupdb to copy only the most recent data to your new server, or at least for a test run in order to get a smaller file and a faster test restore completed.
3. Restore the backup to your Test server with the restoredb command.
4. Log in and verify that the new version works with your configuration.
Warn your users that a migration is beginning. Give them a last chance to log in and update their timesheets before a service outage occurs. It is best to give users several days notice if possible. Give them a chance to preview things on the test site that you created in the previous step. Try to get an idea of any difficulties your users may encounter. It is wise to get feedback from your users while the older version's server is still up and available.
Make a new backup of your production data. Stop the production timesheet site, but do not uninstall it. You just want to prevent people from adding new data to it. Complete details on how to run a backup using backupdb can be found in the Journyx online KnowledgeBase.
Consider making a filesystem backup of the Timesheet install directory. You can use commercial backup software or simply zip up the entire c:\Program Files\Journyx directory and save it in a safe place. The install directory will always be in the %WTHOME% environment variable on Windows and $WTHOME on Unix in case you did not install to the default location.
Save both backups (.jx database backup and the install directory) to a safe location. Consider copying them to an external hard drive or other storage medium and storing them in off-site locations.
Log on to the new Test server. Make sure you are logged in as the correct user. You should be logged in as the same user that installed the application. This is known as the "install admin" user. The install user is privileged in Timesheet.
Make sure any special patches or hotfixes have been applied as recommended by Journyx Support or Professional Services.
Make sure the "Auditing" feature is turned off. If auditing is on, it will greatly slow down the migration in most cases. To make sure Auditing is turned off, log into the new Timesheet site as an Administrator. Check that auditing is off under the "Logging Options" screen.
Open a command line window to run the restore. On Windows, click on Start, then Programs, then "Journyx Timesheet", and finally click on "Timesheet Command Line Prompt." You must run the restore in a window which will not close automatically. On Unix, open a terminal window and source the setup file as you would before running any Timesheet Unix command.
Once again, double check all the Prerequisites mentioned above! In particular, you should make sure that:
- your new server is pointing to the correct Test database account (not your current production [old version] account!)
- the database has plenty of free disk space in your tablespace
You are now ready to run the production migration. Run the restoredb yourbackupname.jx command. Replace yourbackupname.jx with the actual name of the backup file that you created above. Run the restoredb command with no other options to get a list of available options. You can put the new license key in the system by specifying it on the restoredb command line with the -k key option.
The restoredb command will ask you for a directory location (path) to use for saved reports and a location to store uploaded image receipts. If your organization is using a specific location for these two items, you should enter the complete path to these locations at this time. If you are not using uploaded receipts, or if the default locations for these options are acceptable for you, simply press Enter to accept the defaults. Or give the -D option on the restoredb command line to skip these prompts and use the default locations.
Wait. Depending on the size of your data, your Timesheet configuration, your hardware resources and other factors, the restore could take an hour or two, or it could take several days in some extreme cases. (After your site is migrated, consider using the "Archive" feature to trim out old data from your site.) For most customers with around 500 users or less, the restore should not take much more than a couple of hours in most cases.
When the restore finishes, make sure that it did not show any error messages. If in doubt, contact support@journyx.com and be sure to include any Timesheet log files or error messages that you can find.
Now is a good time to make a Timesheet backup with the backupdb command. Also talk to your database administrator and have him/her create a native database backup, such as an "Oracle dump". Save these backups to safe locations.
Log into the new install as an Administrator. Add the correct license key for the new version if neccesary. Do any extra testing and verification at this time.
If the new server is to become your permanent server, then you are finished. Tell your users the address of the new server and let them begin using it. Update any bookmarks or links on your Intranet pages if neccesary.
If you need to move the data off the test server back on to your original production database server, first make sure you have a backup of the Timesheet install directory as well as the data in the database. Then uninstall the old version and install the new version. Instead of setting up a new database, export the migrated test database to the old production user/schema, or just point the production server to the new database account.

If you have any questions, please feel free to contact our Technical Support Department.