Installing the API (Issuetrak 11.0+)

Introduction

Issuetrak 11.0 and above provides the means to deploy the API via either the Issuetrak Deployment Utility (IDU) or the Issuetrak Deployment Manager (IDM). If you wish to install the API while installing a new instance of Issuetrak with the IDM, you should select the API when prompted by the IDM, and continue with the deployment as normal. In order to install the API during an upgrade or re-deployment of an extant 11.x site, a bit more work is required.

Deploying the API will require a few minutes of downtime for all involved Issuetrak sites. During deployment, the following events will happen for each targeted Issuetrak instance.

  • An API user will be created on the SQL server if it doesn't exist, and it will be associated with your Issuetrak instance.
  • An account called “APIUser” will be added within your Issuetrak site. It will only be visible when querying the SQL server for this account. This account must remain active, and should not be modified.
  • A new application called api will be created in the root of your Issuetrak site in IIS.
  • The Issuetrak instance itself will be re-deployed with the information specified in the JSON.

If you want to learn more about Issuetrak 11.x before performing an API deployment, you can jump to the 11.0 Table of Contents here.

Selecting a Site for the API

It is necessary to generate a JSON for the site in question. We will use the IDM to accomplish this goal.

  1. Open the IDM on the Issuetrak web server with administrative credentials.
  2. You must agree to the Issuetrak Terms of Service to proceed past this point.
  3. Choose Go to the Sites Explorer.
  4. In the upper left corner of the IDM, click Add Sites for Deployment, then click By Scanning for Existing Issuetrak Sites.
  5. Choose whether to use SQL credentials or the current Windows credentials to authenticate to the SQL server, and then click Authenticate. Note that you may be prompted more than once, if there are multiple SQL servers used by different instances of Issuetrak running on this server.
  6. Read the list of sites that appears, and check off the sites that you wish to install the API for.
  7. Click Export Selected.
  8. Set the filename and location to save the exported JSON.

Generating the API Key

From the web server you expect to run Issuetrak on, open PowerShell and change directories to the Issuetrak 11.0 distribution folder. Next, run the following command:

.\issuetrak.deployment.utility GenerateAPIKey

The IDU will randomly generate a key used to authenticate to the API. Take note of the API key that is displayed within quotes. You will need to specify it in the JSON, and provide it to whoever needs to use the API.

Modifying the JSON

The IDU can be used to deploy the API. This requires customizing a JSON containing your site configuration to configure several parameters for the API. Please familiarize yourself with JSON before attempting this. Each of the JSON entries provided below are pre-filled, but should be changed to suit your site and environment.

Add the API object for each site entry. Take care to ensure that the API object is separate from the Application and Database objects, and ensure that you fill the values appropriately according to your environment:

"Api": {
      "AttachmentsRootFilePath": "C:\\inetpub\\wwwroot\\Attachments",
      "UserPhotoImagesRootFilePath": "C:\\inetpub\\wwwroot\\Attachments",
      "ApiAuthorizationBypassReferrers": "https://localhost/api/swagger/ui/index",
      "ApiAuthorizationBypassIpAddresses": "127.0.0.1,::1",
      "ApiKey": ""
    },

Paste the API key into the value ("") portion of the empty ApiKey object.

Within the Application object for each site, add (and customize if you need to) the following key/value pair:

"ApiAppPoolName": "Issuetrak API Pool",

Within the Database object for each site, add (and customize if you need to) the following key/value pairs:

"ApiUserName": "APIUser",
"ApiUserPassword": "password"

Deploying the API

Once the desired changes have been made to the JSON, open the IDM with administrative credentials on the web server, then perform the following:

  1. Accept the Issuetrak Terms of Service.
  2. Select Go to the Site Explorer.
  3. In the upper left corner of the IDM, click Add Sites for Deployment, then choose From a Configuration File.
  4. Browse to the JSON file you exported in the earlier steps, and open it.
  5. Find View Options along the top of the IDM, and then select Show IDU Output.
  6. Along the top of the IDM, click on Deploy.

The IDM will re-deploy any sites listed in the JSON with the API, and display the output in the bottom portion of the window.