Upgrading to Timesheet 5.6 - Journyx, Inc.

Support
Upgrading to Timesheet 5.6

 

This document outlines the process for upgrading to Journyx Timesheet v5.6 from an existing installation of Timesheet 5.5x, 5.0x, 4.6x or 4.5x. If your organization is running any version of Timesheet prior to 4.5x, you must upgrade to 4.5x before you can upgrade to version 5.6. Please contact Journyx Customer 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 at least followed all 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 5.6.

Please Note: If you are an existing customer with a current maintenance agreement you are eligible to receive this increased functionality for FREE if you have purchased Timesheet 5.0x or for just 50% of the full price of v5.6 if you purchased an earlier version!

If you encounter any problems while performing the upgrade to Timesheet 5.6, please contact Journyx Customer Support.

Migration Notes for Upgrades from 4.6x/4.5x
Journyx Timesheet 5.0 included a redefined database structure and format. These changes greatly enhance the stability and flexibility of Timesheet; however, they also present several issues that our customers who are migrating from versions of Timesheet prior to 5.0x should be aware of.

Foreign Key Constraints
The newly designed Timesheet database makes use of foreign key constraints to ensure data integrity. On the most basic level, what this translates to for migrating customers is that if you have historical data to migrate and some portion of that data has been previously deleted (i.e., a user who no longer works for your organization), all records associated with that deleted item (i.e., time records, password information) will be deleted during the migration because that data violates the referential integrity enforced by foreign key constraints.

Records deleted in this fashion are logged to the Migration Error Log file and are not deleted from the backup file. These records are deleted only from the actual installation. Therefore, this data is not permanently lost.

If, during your test migration, you discover that important information is lost due to foreign key constraints please contact Journyx Customer Support so that we may work with you to retain that data during your production migration.

Obviously, the implementation of foreign key constraints further increases the need to perform a Test Migration before proceeding with a Production Migration. Please perform a Test Migration first!

Migration Procedure Outline

This is a 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.

  • 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!
  • Download the new version of Journyx Timesheet. Install it to a new machine (Windows or Unix) or a different account on the same machine (Unix 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 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.
  • 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.

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.

  1. 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 test 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.
  2. 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 as your current production timesheet server!!
  3. 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.
  4. Make sure you have downloaded the latest version of Timesheet, 5.6m2. If you are using an older version of 5.6 then you may encounter a bug in the database migration code that causes temporary database disconnects to stop the entire process (which forces you to start over from the beginning.)
  5. Create a new database account for the new version. Follow the other instructions in the External Database setup guide.
  6. Make sure your database is set up with the character set that you wish to use. The character set controls which accented letters and other special characters are allowed in the database. Generally this should be the same character set that your previous version used.
  7. 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.
  8. 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.
  9. 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.
  10. 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

  1. Double-check database settings and other Prerequisites that are described above.
  2. Download and install the new version of Timesheet to the Test app server and Test database.
  3. Do a test migration run:
    1. Make a backup from production. Leave the production server online.
    2. Restore the backup to your Test server.
    3. Log in and verify that the new version works with your configuration.
  4. 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.
  5. 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.
  6. 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.
  7. Save both backups (.jx database backup and the install directory) to a safe location. Consider burning several copies to CD-ROM and storing them in off-site locations.
  8. 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.
  9. Make sure any special patches or hotfixes have been applied as recommended by Journyx Support or Professional Services. Timesheet version 5.6m2 should at least have the wtmigration.pyc hotfix applied to prevent temporary database disconnects from stopping the entire process (which forces you to start over from the beginning.)
  10. 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.
  11. 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. Do not run a large migration from the "Setup Web Server and Database" program, even though it may prompt you to restore a backup. On Unix, open a terminal window and source the setup file as you would before running any Timesheet Unix command.
  12. Once again, double check all the Prerequisites mentioned above! In particular, you should make sure that:
    • you have the wtmigration.pyc hotfix applied
    • 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
  13. 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.
  14. 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.
  15. 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.
  16. 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.
  17. 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.
  18. 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.
  19. 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.
  20. 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.