How to Perform an Upgrade Using the Issuetrak Deployment Manager (IDM)

Introduction

This article is intended to assist the Issuetrak administrator with using the Issuetrak Deployment Manager (IDM) to upgrade an existing installation of Issuetrak. The IDM provides a graphical wizard interface for upgrading Issuetrak while providing a fair degree of control over how the site is installed.

If you would prefer to have more control over the deployment of Issuetrak, and you're comfortable with using PowerShell and hand-editing configuration files, then you might consider using the Issuetrak Deployment Utility (IDU) instead.

You can find more about Issuetrak Deployment Fundamentals here.

Additionally, please see this video created by our Support team about performing upgrades.

---

Confirm Current Functionality

Confirm that your current site is working:

1. Ensure that you can navigate to your Issuetrak site.
2. Confirm that you can sign in to your site.
3. Navigate to Administration > System > System Settings > Email Settings, then click on Test Mail Server and confirm that you receive the test message that is sent. 
4. (If applicable) Navigate to Administration > Incoming Email > click edit for each active mailbox >  click on the Test Connection button to confirm that it is working properly.  

5. (If applicable) Ensure that you are able to authenticate to the site with your identity provider's credentials. 

Identifying Requirements

Please ensure that your environment meets Issuetrak's system requirements. It may be necessary to add roles and features that aren't currently installed on the Web or SQL servers. Additional configuration beyond roles and features may also be required.

Getting the Issuetrak Distribution

Download the latest Issuetrak distribution.

You will be prompted to enter your credentials to access our Support site in order to download the distribution.

Once you've downloaded the distribution, place it on the Web server and then extract it. If it is necessary to transfer the distribution to another server after downloading it, be sure to unblock the zip file prior to extracting it.

If you have added logos to your site, be sure to run the logo migration script either right before or after performing this upgrade.  Find out more about the script here. 

Upgrading Issuetrak Without Integrated Security

Issuetrak 14.6 and above provides support for Integrated Security. This set of upgrade steps is for customers that are upgrading and do not currently wish to use Integrated Security. If you are interested in switching your Issuetrak site to Integrated Security, then please skip to the next section of this article, which provides steps for upgrading while switching over to Integrated Security. 

Navigate to the Issuetrak distribution, then perform the following steps:

1. Right-click the file Issuetrak.Deployment.Manager.exe and choose Run as Administrator.
2. You will be prompted to accept Issuetrak's Terms of Service at this location. Choose Continue to accept the Terms of Service and proceed with your usage of the IDM.
3. Choose Upgrade an existing Issuetrak site.
4. The IDM will scan for existing sites,
   1. If you are upgrading from a version prior to 15.2, then you will be prompted to enter your Site ID. You can get this information by contacting Issuetrak Support.
   2. You will receive a prompt for administrative SQL credentials.
      You may choose to use Windows authentication if your account has SQL admin rights, or simply enter the credentials for a SQL admin account. Afterward, click Authenticate.
5. The IDM will populate a list of valid Issuetrak sites that are available to be upgraded. Select any number of sites that you wish to upgrade. Note that sites with the same version and build number as the current release are eligible to have the upgrade run against them.
6. Under Deployment Options, decide what contexts to deploy, and whether to perform a backup of each site's respective database and web folder.
   • You can also choose to install the API or API v2 at this stage.  If you or your organization are interested in developing a web application that interacts with your Issuetrak instance, this would facilitate that goal.
7. Under View Options, choose Show IDU Output.
8. Click Upgrade.

The IDM will begin to carry out the upgrade, and its output at the bottom of the window will tell you what it's doing and whether it succeeded at each step.

Upgrading Issuetrak to Use Integrated Security

Issuetrak 14.6 and above provides support for Integrated Security. This set of upgrade steps is for customers that are upgrading and wish to change their existing Issuetrak site so that it uses Integrated Security.

Navigate to the Issuetrak distribution, then perform the following steps:

1. Right-click the file Issuetrak.Deployment.Manager.exe and choose Run as Administrator.
2. You will be prompted to accept Issuetrak's Terms of Service at this location. Choose Continue to accept the Terms of Service and proceed with your usage of the IDM.
3. Choose Go to the Sites Explorer.
4. In the upper left corner, click "Add Sites for Deployment" and then By Scanning for Existing Issuetrak Sites.
5. The IDM will scan for existing sites, and will prompt for administrative SQL credentials. You may choose to use Windows authentication if your account has SQL admin rights, or simply enter the credentials for a SQL admin account. Afterward, click Authenticate.
6. The IDM will populate a list of valid Issuetrak sites that are available to be upgraded.
7. Select any number of sites that you wish to upgrade. Note that sites with the same version and build number as the current release are eligible to have the upgrade run against them.
8. Click Export Selected. 
9. Choose a location and a filename to save the JSON to. 
10. Open the JSON you just saved and scroll to the "Database" section. 
11. Change the value for "SiteAuthenticationType" from Sql to Windows.
12. Set the value for "IntegratedSecurityUser" to the domain service account that you want your site to run under the authority of.  This must be specified in "Domain\\UserID" format in order to be valid. 
13. Set the value for "IntegratedSecurityPassword" to the password for the domain service account you specified above. 
14. Blank out the values for the following keys:
    1. ClassicUserName
    2. ClassicUserPassword
    3. MvcUserName
    4. MvcUserPassword
    5. ApiUserName
    6. ApiUserPassword
        
15. Scroll up to the "Application" section.
16. The values for "ClassicAppPoolName" and "MvcAppPoolName" should match, and the application pool they are in should be distinct from other running Issuetrak sites that do not use Integrated Security.
    
    As a best practice, "ApiAppPoolName" (if present) should not be in the same app pool as any Classic and Mvc applications. If you have other Issuetrak sites running on this server that you aren't upgrading yet, then you should set these values to an application pool that is unique and won't be used by other sites. 
    
    In this example, we will enter the value of "INTEGRATED" for the Classic and Mvc app pool names, and "INTEGRATED-API" for the API app pool.
     
17. Save the modified JSON. 
18. Right-click the file Issuetrak.Deployment.Manager.exe and choose Run as Administrator.
19. You will be prompted to accept Issuetrak's Terms of Service at this location. Choose Continue to accept the Terms of Service and proceed with your usage of the IDM.
20. Choose Go to the Sites Explorer.
21. In the upper left corner, click "Add Sites for Deployment" and then From a Configuration File.
22. Navigate to the modified JSON and open it.
23. Under Deployment Options, decide what contexts to deploy, and whether to perform a backup of each site's respective database and web folder.
    • You can also choose to install the API or API v2 at this stage if it hasn't previously been installed.  If you or your organization are interested in developing a web application that interacts with your Issuetrak instance, this would facilitate that goal.
24. Under View Options, choose Show IDU Output.
25. Select your site and then click Deploy.

The IDM will begin to carry out the upgrade, and its output at the bottom of the window will tell you what it's doing and whether it succeeded at each step.

Failed Upgrade?

The default behavior of the IDM is to roll back the state of the website if the upgrade fails. However, this should not be relied upon for disaster recovery. The web files associated with the pre-upgrade iteration of Issuetrak are backed up unless otherwise specified in the JSON or in the IDM. The default backup location is a folder called backups located within the Issuetrak distribution. Backed up web files are located within a subfolder that has been named according to the site's title in IIS.

Get as much context from the IDM window as you can. Something as simple as a misspelled server name can cause the deployment to fail. If the root cause is unclear, proceed with the steps below:

1. Open Explorer and navigate to your Issuetrak distribution folder.
2. Open the Logs folder.
3. Open the latest timestamped log file.
4. Read the log and try to determine where the upgrade failed.
5. Take note of your findings and save the log file.

Issuetrak Support will be happy to troubleshoot or assist you with your upgrade. You can contact Support at 888-789-8725 (US & Canada), +1 757-213-1351 (International), support@issuetrak.com or https://support.issuetrak.com/.

Successful Upgrade

Congratulations on your successful upgrade of Issuetrak!  Even though this isn't a new deployment of Issuetrak for you, please consider reviewing our Post-Deployment Configuration article.  You can add a degree of security to your site by applying DPAPI encryption to your Issuetrak site's connection strings, which is discussed in that article. 

Additionally, consider contacting Support for assistance with cleaning up services after upgrading to 11.6 and above, as the Incoming Email Service is no longer used.  You can contact Support at 888-789-8725 (US & Canada), +1 757-213-1351 (International), support@issuetrak.com or https://support.issuetrak.com/.