How to Perform an Upgrade Using the Issuetrak Deployment Utility (IDU)

Introduction

This guide is intended to assist the Issuetrak administrator with using the Issuetrak Deployment Utility (IDU) to upgrade an existing installation of Issuetrak. The IDU provides granular control over the deployment of our product. If you want maximum involvement in the deployment of Issuetrak, and you're comfortable with using PowerShell and hand-editing configuration files, then the IDU is for you. If you just want to install or upgrade Issuetrak without any special requirements, then we recommend that you use the Issuetrak Deployment Manager (IDM), which provides a graphical interface and a wizard to help you deploy our product, while retaining a fair degree of control over how the site is installed. You can get to the IDM upgrade guide here.

You can find more about Issuetrak Deployment Fundamentals here.

This guide is only intended to be used after reading the information provided in the following articles:

Release Notes
Introduction to the IDU
IDU Verb Documentation
Working with the JSON

The reader would be well-advised to read the supporting documentation listed above before proceeding with the steps outlined here.

Important! Make sure your environment meets the system requirements prior to proceeding.

Upgrading Issuetrak requires that your current instance is on version 10.3.7 or higher before proceeding. This is a hard-stop condition and cannot be circumvented.

Upgrading from a version prior to 11.6 and above will clear the existing in-application IEM log due to changes in the way logging is implemented. 

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 the gear icon in the top right > Outgoing Email > click on Test Mail Server and confirm that you receive the test message that is sent. 
  4. Navigate to the gear icon in the top right > Incoming Email > click edit for each active mailbox >  click on the Test Connection button to confirm that it is working properly.  

If you have a mailbox that is active but cannot connect or authenticate, then whoever is listed in the Notify on Error field will be sent an email every minute until this state is corrected.

  1. (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.

The upgrade utility will update Issuetrak‘s Classic and Core application pools to use .NET Framework v4.0 if they aren’t already set to that version. This can affect other sites that share the same application pools!

back to top

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 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. 

back to top

Upgrading Issuetrak

Open the verb documentation to the Deploy section if you haven't already. Read through the possible parameters and make a decision on which of them you will need to use in the upgrade for your site(s).

  1. Open PowerShell with administrative privileges, then change directories to the location of the extracted distribution.
  1. We will now use the IDU to scan the web server for existing Issuetrak instances and generate a JSON named filename.json based on its findings. Note that no particular name or extension needs to be given to the file.

At this time you should also append any parameters needed to constrain the JSON to just a particular Issuetrak site. If you have multiple instances of Issuetrak, and you do not add constraints to this command, the resulting JSON will contain information for ALL of your Issuetrak sites!

.\issuetrak.deployment.utility generatedeploymentconfiguration -i Your.Issuetrak.Site --outfile "path\yoursite.json"
  1. Open the file yoursite.json in a text editor.
  1. Make any additional changes to the JSON that are necessary for your environment, including the "SiteId" and its value for your site. You can get your Site ID by reaching out to Issuetrak Support.
    1. Additionally, if migrating the database is an intermediate step that's being taken during this upgrade, make sure that the JSON points to the correct database server, with correspondingly correct credentials.
    2. Do you want to add the API or API v2 to the site?  If so, be sure to include the API or API v2 object with all values filled. 

Triple-check the information you entered, and validate that the information in the JSON is entered correctly. When you move to deploy this JSON, the IDU will do its best to carry out the deployment. Incorrect information here can lead to corruption of existing sites, hard-to-correct misspellings, overwritten databases, and/or overwritten data.

  1. Decide which contexts you want to deploy. In this example, we'll perform an upgrade without specifying the context. This will therefore make the IDU default to deploying all contexts of Issuetrak. Within the PowerShell window, enter the following:
.\issuetrak.deployment.utility deploy -c filename.json

The IDU will ask you whether you accept the terms of service at https://helpcenter.issuetrak.com/home/2360-issuetrak-premise-software-license-agreement. If you accept the terms, the IDU will begin to carry out the upgrade. IDU output in the PowerShell window will indicate what it's doing and whether it succeeded at each step.

If you need to access the backup copy of the web files, they can be found in the distribution folder, in a subfolder called Backups.

back to top

Failed Deployment?

The default behavior of the IDU 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. 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.

If the deployment of Issuetrak fails, do not repeatedly attempt to re-deploy without determining the root cause. This can cause damage to your instance of Issuetrak that can be difficult to repair.

Get as much context from the PowerShell 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 distribution folder.
  2. Open the Logs folder.
  3. Open the latest timestamped log file.
  4. Read the log and try to determine where the deployment failed.
  5. Change the JSON or your IDU command accordingly, then re-run the upgrade.
  6. If the deployment fails again, determine if it's the same problem or a new one, and re-apply the steps above as needed.

If the steps above failed, 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 Deployment

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/.

If your server environment uses DPAPI encryption AND you performed this deployment as the last stage of server migration, please make sure you update your connection strings file with a connection string that has been encrypted on your new web server. You can learn how to do that here.

back to top
Was this article helpful?
Thank you for your feedback!
User Icon

Thank you! Your comment has been submitted for approval.

Related Articles

 Copyright © Issuetrak, Inc. All rights reserved.