Introduction

This article is intended to guide through the six stages required to upgrade an existing installation of Mitrefinch TMS for Windows and WebTMS v8. It is intended for an IT professional who is familiar with the Mitrefinch software system. 

If you are upgrading from any version prior to v8 do not proceed and instead contact our Sales Team on 0330 726 0099.

Note: Before starting, Mitrefinch strongly recommend that you read through this entire document to familiarise yourself with the upgrade procedure. In this document, we refer to our network location as 'C:\'. However, this path may be different for your installation.

The six stages for upgrading are: 

1. Backing up your system 
   
2. Downloading and unpacking the setup files for your upgrade. 
   
3. Upgrading TMS for Windows (WinTMS) v8. 
   
4. Upgrading the TMS web instance (WebTMS) 
   
5. Upgrading your data via SYSGEN.exe 
   
6. Request and upload the amended v8 licence* 
   

*Regarding stage 6, if you were not provided the amended v8 licence file with the upgrade then you will need to perform the upgrade during Mitrefinch office hours (Mon to Fri 8:30 till 17:30) to request a licence as you will NOT be able to load WinTMS or WebTMS as your current licence will no longer be valid. Further information can be found in the "Requesting a new v8 licence" section at the end of this document.

Prerequisite check for upgrading

Before you start the upgrade, please make sure that:

• You have the TMS MASTER account password 
  

• You are currently running WinTMS v8. To verify this, log in to WinTMS as the MASTER user and select Help > About. The About window will display your installed version number 
  

• You have an existing installation of WebTMS v8. To verify this, log in to WebTMS as the MASTER user then navigate to the Licensing page and confirm the ‘Allowed version pattern’ is version 8. 
  

• You have access to the server which runs the TMS applications/services (e.g. Poller/Processor) and the Web Server which hosts WebTMS.
  

• You know the location of and have full access to the directories which contain the existing v8 files for WinTMS and WebTMS. These will usually be in C:\WinTms and C:\inetpub\wwwroot\TMS respectively (Note: the names of the TMS directories may differ) 
  

• You have a network log in account with privileges to stop/restart your web server (IIS) 
  

• Ensure that ALL users are logged out of both WinTMS and WebTMS. 
  

• Ensure that ALL Mitrefinch TMS applications and services (e.g. the Poller and Processor) are stopped. Instructions on stopping the services are shown below. 
  

1. On your server which runs the TMS applications/services, load the Poller Controller via the taskbar or shortcut
   
2. When prompted, enter the MASTER login details
   
3. Select File, then click Stop poller
   

4. Once it has been stopped, select File and click Exit
   
5. Repeat from step 2, but instead use the Processor Controller program
   
6. Should you have more than one poller/processor running, repeat these steps for each of them
   

• Ensure that IIS is stopped by opening the command prompt on the Web server and type the command “IISRESET/STOP”. This process should only take a second or two.
  

Note: you will need to have Administrator rights on the web server to do this.

System backup

Before upgrading your system, it is very important that you have a recent backup. This will allow you to roll back any changes you make during the upgrade procedure should anything go wrong. You should backup your TMS database, WinTMS programs and your existing WebTMS directory using the following guidance.

Whilst you may already have a TMS database backup from a nightly backup routine, we still recommend that a manual backup is taken via your SQL Server Management Studio on your TMS Server or via WinTMS to ensure it is fully up to date prior to upgrading. 

• SQL Tools - Mitrefinch Helpdesk do not directly support for SQL tools, but suitable instructions can be found online by search for ‘Backing up using Microsoft SQL server’. Examples shown below: 
  

• SQL Server 2012 or later - https://msdn.microsoft.com/en-gb/library/ms187510.aspx
  
• SQL Express - http://www.serverintellect.com/support/sqlserver/database-backup-ssmse 
  

Note: If you are unsure of the database name used by TMS, then load WinTMS as the MASTER user and select the menu Help > About. 

• WinTMS Database Backup - Alternatively a manual database backup can be performed by loading WinTMS, but you will require a daily pin to perform this which needs to be requested Mitrefinch Support. 
  

Load WinTMS as the MASTER user and select the menu Help > About. Select on the ‘System Information’ link, then select ‘Backup’ button and enter the daily pin provided by Mitrefinch Support.

Backing up the WinTMS programs

To do this you will need to make a copy of your existing WinTMS directory. The default location for your TMS directories is: 

C:\WinTMS 

Browse to this directory which contains all the files necessary for WinTMS. Right-select the directory and select copy. Then paste the directory in a safe location e.g. C:\WinTMS_BACKUP. This will allow you to roll back any changes you make during the upgrade procedure.

Backing up WebTMS

To do this you will need to make a copy of your existing WebTMS directory. The default location for your web directories is: 

C:\inetpub\wwwroot

Browse to this directory and locate the folder which contains all the files necessary for WebTMS. Right-select the directory and click copy. Then paste the directory in a safe location. This will allow you to roll back any changes you make during the upgrade procedure.

Download setup files

On the TMS Server, download the TMS 8 zipped files for WinTMS and WebTMS using the URL links labelled CD provided with these instructions.

Next, unzip each downloaded file and extract the contents to a temporary location (e.g. your desktop) you can work from.

Note: If you were provided download links labelled with EXEs, then follow the overwrite instructions provided in the email and proceed to the Upgrading data section.

Upgrading WinTMS v8

Once you have made a backup of your existing WinTMS system, downloaded and extracted the WinTMS v8 zip file, you are ready to start the upgrade of your system.

TMS Setup

Locate the setup.exe file from the temporary location, and double-click it to launch the Install Shield Wizard for TMS:

Select Next to continue

Select packages to upgrade

Select the packages that you use, and click Next to continue.

Note: If you are unsure of the packages you use, select all the boxes. You will need to have the appropriate licenses to run the packages.

Choose the WinTMS directory

The upgrade routine will automatically detect the directory where WinTMS is currently installed on your machine. This is C:\WinTMSv8 in the example below:

Select the folder for icons

Select a folder from the programs menu on your PC where the new TMS icons will be stored:

Select Next to continue.

A progress window will be displayed as the installation proceeds:

The installation should run through the completion and automatically install the necessary programs and related files. If you are prompted to overwrite any files, agree for existing files to be overwritten. Select Finish when prompted.

If you are installing on a more recent PC Operating System, you may also see the following prompt:

Assume that the program has installed correctly and select ‘This program installed correctly’.

Note: Subject to your operating system, you may be then prompted to reboot the server. You do not need to do this immediately if it is not convenient.

Upgrading WebTMS v8

Mitrefinch Upgrade tool

Once you have made a backup of your existing WebTMS directory, downloaded and extracted the WebTMS v8 zipper file, you are ready to use the Mitrefinch Upgrade tool. 

Choose either 32-bit or 64-bit installer

The Mitrefinch Upgrade tool is designed to upgrade an existing installation of WebTMS and contains both a 32-bit and 64-bit installer. Therefore, before commencing with the WebTMS installer, you need to confirm which installer you require.

To do this, simply load Internet Information Service (IIS) Manager and expand the Application Pool. Then, right click on the application pool used by TMS and select Properties, then click Advanced settings.

If ‘Enable 32-Bit applications’ is set to ‘True’, then you have 32-bit installed.

If ‘Enable 32-bit Applications’ is set to ‘False’, then you have 64-bit installed:

Once confirmed, cancel the ‘Advanced settings’ and click File, and then Exit to close IIS Manager.

Then, navigate to the location of your extracted files and right click on UpgradeWizard.exe and select Run as administrator. As of Version 8.31.1.0, the UpgradeWizard will run as an administrator automatically.

The Upgrade Wizard will prompt you to choose the MSI installer to launch the Mitrefinch Upgrade Tool. To do this, select the Browse button, which will default to the location of your extracted files.

Then, double-click on the required MSI file:

• 32-bit: Mitrefinch.TMS.Server.x86.msi
  

Or

• 64-bit: Mitrefinch.TMS.Serverx64.msi
  

The example shown below would be for a 32-bit install:

The following window will then open displaying the progress while the files are extracted.

Prerequisite check

The next screen performs a prerequisite check on the server.

In the example above, the X++ Redistributables are already installed. If they are, select next and skip over the Installing the C++ Redistributables section.

Installing the C++ Redistributables (if required)

If the C++ Redistributables are not installed on your server, please follow the steps below:

1. Select the Install button which is displayed on the Prerequisites screen.
   
2. On the Microsoft C++ Setup screen, select the check-box to accept the licence terms and then select Install to start the process. Progress bars will be displayed as the installation proceeds.
   
3. Select Finish to close the setup. Next, select Refresh on the Mitrefinch Upgrade tool to update the Prerequisites screen, and select Next to continue.
   

Choose the Web directory

Select the Browse button and locate the directory where your existing WebTMS files have been installed. The following is the defaults directory:

C:\inetpub\wwwroot\

Review

A window opens that asks you to review the following information:

• The installed version
  
• The upgrade version
  
• The location of the install file
  
• The location of the web directory
  
• The location of the Application Host Backup — the Upgrader tool backs up the applicationHost.config and machine_backup.config files. These are the root files of the configuration system when you are using IIS 7 and above. They include definitions of all sites, applications, virtual directories and application pools, as well as global defaults for the web server settings. 
  

This window will also inform you that you need to run SYSGEN after performing the upgrade – this is covered late on in this guide. If you need to change any of the previous steps, select Back.

If you are ready to begin the upgrade process, click Stats and a progress window will be displayed.

Summary 

The final step in the WebTMS upgrade is to review the upgrade summary. This will tell you if the upgrade has been successful and will inform you of the version of WebTMS you are now running. There are three possible outcomes on this page:

1. Upgrade Successful – this indicates that the upgrade of WebTMS has been completed successfully. Select Close to close the Mitrefinch Upgrade tool.
   

2. Upgrade Successful with warnings – this indicated that the upgrade was completed successfully but some warnings were generated during the process. The summary will inform you of the warnings and direct you towards a solution.
   

For instance, the example below informs you that the WebConfig file has been changed:

Selecting More info offers you the chance to view the changes using WinMerge:

This program allows you to correct the changes to your WebConfig file manually. The Upgrader tool always makes a backup of the WebConfig file in case any errors are introduced.

If you click Yes, you will be shown a side-by-side view of all of the changes to the WebConfig file:

A WebConfig report is also produced by the Upgrade tool, and is saved on the desktop of the PC where the upgrade was performed. If you are having any difficulties, please email this file to support@mitrefinch.co.uk

3. Upgrade Failed – the upgrade process was stopped and your WebTMS files have not been changed. The error examples below relate to ‘There was an error moving the Geocode DLL’s’
   

Example 1 – The process cannot access the file because it is being used by another process

If you see the following window, then the Application Pool is still running within the IIS Manager, therefore the WebTMS upgrade could not be applied.

• Select Close to close the Mitrefinch Upgrade Tool.
  
• Open a command prompt on the host server and type the command IISRESET /STOP. This process should only take a second or two.
  

Note: This step required administrator rights on the Web server.

• Repeat the WebTMS upgrade procedure.
  

Example 2 – Access to the path is denied

If you see the following window, then the upgrade was attempted using an account with insufficient privileges (i.e. not the Administrator).

Solution: Re-run UpgradeWizard.exe and ensure you right click and select Run as Administrator. 

Upgrading data

The final stage in upgrading your existing installation of WinTMS v8 is to update your data and databases to the new version. To do this, you need to run the SYSGEN program.

Note: If you do not upgrade your data with SYSGEN, both WinTMS and WebTMS may fail.

Running SYSGEN

SYSGEN is the Mitrefinch System Generation application which is used to upgrade, backup and repair your TMS database. Navigate to the folder where WinTMS has been installed, and double-click SYSGEN.exe and follow the prompts. Before the login window opens, the following warning may be displayed:

If you have followed this guide, then you will have already made a back-up of your data and so it is safe to proceed. Click Yes to continue. If not, please select No and backup your data using this guide.

The warning window will close and the SYSGEN login window will open:

You will need to enter the Master account login details. The SYSGEN application will open, displaying your current server settings and Version information. In this example, the WinTMS package has been upgraded to v8.11 but the database is currently at v8.09.

Select Upgrade or select Upgrade from the File menu to start the program.

SYSGEN will then upgrade the database tables. A progress log will be displayed.

At the end of the process, an information window will appear:

Click OK to close the window. Then select Close on the SYSGEN LOG window.

The Version information in SYSGEN window should now indicate that the database has been upgraded. A new window will open telling you that the application will shut down:

Selecting OK closes all windows and exits SYSGEN.

Restarting the web server

Before attempting to use your upgraded version of WebTMS, you will need to restart your web server for the changes to take effect.

Note: You will need to have Administrator rights for the web server to be able to do this.

Requesting and uploading the updated v8 Licence

After upgrading v8 you will not be able to fully load WinTMS or WebTMS. For example, the following ‘Invalid licence’ error message will appear when attempting to login via WebTMS:

If you received an updated licence file with your upgrade, then skip to the section about uploading a licence.

Requesting a new v8 licence

If you did not receive an updated v8 licence with your upgrade, then you will need to request a licence by loading WebTMS and the MASTER user, then navigate to the Licencing page and select Email licence request within the left-hand navigation pane.

Select ‘Generate licence request’ email to open the draft message in your default email client. The generated email is addressed to Mitrefinch and contains your unique installation information in the message. Once you have sent the message, contact Mitrefinch by telephoning 0330 726 0090 and quote your reference number displayed in the email.

If you do not have a default email client set up, you can use the ‘Copy’ action found in the top-right corner of your unique installation information to copy the details to a Notepad or Word document. Then, save the document to a suitable location and email it to licensing@mitrefinch.co.uk to request an updated licence.

Uploading a new v8 licence

To upload a new licence in WebTMS, login as the MASTER user using the Supervisor login option.

Then, navigate to the Licensing page and select Upload licence in the left-hand navigation pane.

The Upload licence page opens as shown in the example below:

The Upload licence page has a Document location field. Select Brose to open a file browser window on your PC and navigate to the licence file you wish to upload.

Note: the only accepted licence format to upload is the .lic format.

The path of the file is displayed in the Document location field. 

Select Submit to be directed to the Upload confirmation page. Alternatively, select Cancel to abandon and return to the Licensing page.

The Upload confirmation page contains a comparison to review the information before activating, between your existing licence and the new licence. For example:

Anything that has changed from the existing licence compared to the new licence is highlighted in yellow.

Select Activate at the bottom of the page to activate your licence or select Cancel to return to the Upload licence page. 

When activated, you’ll be directed back to the Licensing page. A success message will be displayed at the top of the page along with all the updated details of the new licence. For example: 

Reinitialising the system

Restarting TMS Services

After completing the upgrade of your systems, you will need to restart all Mitrefinch TMS applications and services such as the Poller and Processor on your polling PC or server. Instructions on starting the TMS services are show below.

1. On your server which runs the TMS applications/services, load the Poller controller via the taskbar or shortcut.
   
2. When prompted, enter the MASTER login details.
   
3. Select File, then click Start poller. Once started, select File, then click Minimise.
   

4. Then repeat from step 2 using the Processor Controller via the taskbar or shortcut.
   
5. Should you have more than one poller/processor running, repeat the steps again for each of them.
   

Confirm upgrade version

For the last stage of the upgrade procedure, it is recommended that you confirm the version has successfully updated.

• Log in to WinTMS as the MASTER user and select Help and then click About. The About window will display your installed version number.
  
• Log in to WebTMS as the MASTER user then navigate to the Licensing page and confirm the ‘Allowed version pattern’.