Installing the API (Pre-11.0)

Preparation

The Issuetrak API installation files are included in the Issuetrak distribution from version 10.0 to 10.3.12.  If you're interested in installing the API for versions newer than Issuetrak 10.3.12, please see Installing the API (Issuetrak 11.0+).

Once this is done, create a folder on the web server named “API Installation Files” and copy the contents of the compressed file containing the API installation files to the newly created folder. This will result in a folder (referred to in the following instructions as the “API Installation Files folder”) containing the following folders structure:

  • Issuetrak-API-10.x-Deployment
    • Issuetrak-API-10.x-.NET-Client
    • Issuetrak-API-10.x-.NET-Client-Example
    • Issuetrak-API-10.x-API
    • Issuetrak-API-10.x-Database-Deployment-Scripts
    • Issuetrak-API-10.x-Documentation
    • Issuetrak-API-10.x-KeyTool

    Web Server Installation

    Refer to the Web Server Requirements article for details about preparing the IIS server for hosting the Issuetrak API. Before installing the API, the Issuetrak application must be installed on the hosting web server.

    The steps to integrate the Issuetrak API with the existing Issuetrak web application assume that a subfolder named “api” will be created within the Issuetrak deployment folder structure.

    1

    Create a directory in the Issuetrak application file structure with the name “api”.

    2

    In the API Installation Files folder there is a folder named “Issuetrak-API-10.x-API”. Copy the contents of this folder to the “api” folder created above. This will result in the “api” folder containing the following content:

    • App_Data (folder)
    • App_Readme (folder)
    • bin (folder)
    • Properties (folder)
    • Swagger-Resources (folder)
    • Global.asax (file)
    • packages.config (file)
    • Web.config (file)
    3

    Ensure that the “Logs” subfolder has been created under the “App_Data” folder. If the “Logs” subfolder does not exist, create is beneath the “App_Data” folder.

    4

    Within the “api” folder locate the “Web.config” file and open it in a text editor such as Notepad.

    5

    Search the “Web.config” file for the following text: “connectionStrings”.

    6

    Locate the database connection definition named “Issuetrak-Database”. Within the connection string entry, locate the following placeholder values and replace the placeholder values with the connection information relevant to the installation. Please note that the placeholder values are changed within the existing quotation marks so that the actual values entered will also be contained within quotation marks.

    1. Change this value to the name of the server that hosts the Issuetrak database.

      Change this value to the name of the Issuetrak database.

      Change this value to the ID of the database user used to connect to the Issuetrak database.

      Change this value to the password of the database user used to connect to the Issuetrak database (see c. above).

      1. ENTER_ISSUETRAK_DATABASE_SERVER_NAME_HERE
      2. ENTER_ISSUETRAK_DATABASE_NAME_HERE
      3. ENTER_ISSUETRAK_DATABASE_USER_ID_HERE
      4. ENTER_ISSUETRAK_DATABASE_USER_PASSWORD_HERE
    7

    Search the “Web.config” file for the following text: “AttachmentsRootFilePath”.

    8

    Change the file path for the “AttachmentsRootFilePath” to match the path to the Issuetrak attachments file storage. Ensure that the path has a trailing backslash (“\”) character.

    9

    Search the “Web.config” file for the following text: “UserPhotoImagesRootFilePath”.

    10

    Change the file path for the “UserPhotoImagesRootFilePath” to match the path to the Issuetrak user photo image file storage. In most cases, this file path will be the same file path as specified for the “AttachmentsRootFilePath” setting. Ensure that the path has a trailing backslash (“\”) character.

    11

    Search the “Web.config” file for the following text: “Bypass”.

    12

    Change the default value of the “APIAuthorizationBypassReferrers” setting to match the URL of the api website. The URL must end with /api/swagger/ui/index (e.g. <value>http://www.mysite.com/api/swagger/ui/index</value>).

    13

    Change the default value of the “APIAuthorizationBypassIPAddresses” setting to include the IP addresses of any computers that should be allowed to connect to the Swagger UI for the Issuetrak API. If more than one IP address is included in the list they should be separated with a comma only (no spaces) (e.g. <value>1.2.3.4,5.6.7.8</value>).

    14

    Save the Web.config file, but keep it open as it is used in a later step.

    15

    Open Internet Information Services (IIS).

    16

    In the Connections section on the left-hand side, expand the server where the Issuetrak site is installed.

    17

    Create a new Application Pool for the Issuetrak API if you have not already done so.

      1. Right-click on Application Pools and select “Add Application Pool…”.
      2. Enter a name for the Application Pool, select a version 4 variant of the .NET Framework, and select “Integrated” for the Managed pipeline mode.
      3. Check the checkbox for “Start application pool immediately” if it is not already checked.
      4. Click the [OK] button to save the new Application Pool.
    18

    Convert the “api” folder created above to an Application

      1. In the Connections section on the left-hand side, navigate to and expand the Issuetrak site where the API is installed.
      2. Right-click on the “api” folder and select “Convert to Application”.
      3. Click the [Select] button and select the Application Pool you created for the Issuetrak API.
      4. Click the [OK] button to create the Application.
    19

    Ensure that the “App_Data/Logs” subfolder for the application has read/write permissions for the user associated with the API’s application pool. For IIS 7+ or IIS 8+, the default identity for a new application pool will be “ApplicationPoolIdentity”. This identity will translate into a user name of “IIS APPPOOL\App_Pool_Name”, e.g., “IIS APPPOOL\Issuetrak.API”. Use Windows Explorer to set the permissions for the this AppPool user (local account) to read/write for the “App_Data/Logs” folder.

    20

    Ensure that the only “Authentication” type with a status “Enabled” for the Issuetrak API application is “Anonymous Authentication”. The “Authentication” settings are accessed in IIS Manager by left-clicking on the Issuetrak API application in the “Connections” treeview in the left pane of IIS Manager and then double left-clicking the “Authentication” icon.

    API2.png
     
    API3.png

    Database Upgrade

    Before executing the database upgrade script to install the database components for the Issuetrak API, ensure that a full and complete database backup has been made using backup methods appropriate for the particular recovery model for the Issuetrak database to be upgraded.

    The API Installation Files folder includes a database installation script named “Master-Issuetrak-API-1.0-Database-Upgrade-Script.sql” located in the SQL Scripts folder. This upgrade script must be executed in the context of a database account that has the DBO user role for the Issuetrak 10.x database that is to be upgraded. This upgrade script must be executed before the API Key Generation step.

    Within the script, there is a path variable value that must be set before the script is executed:

    :SETVAR PathToUpgradeDatabaseScriptsRoot<SET_PATH_TO_SCRIPTS_HERE>

    Replace the <SET_PATH_TO_SCRIPTS_HERE> placeholder with the full path to the directory containing the API database upgrade scripts (the SQL Scripts folder in the API Installation Files folder). The path should be in double-quotes ("), not single-quotes ('). The path should not end with a trailing backslash (\). (e.g. :SETVAR PathToUpgradeDatabaseScriptsRoot “C:\API Installation Files\Issuetrak REST API 10.x\SQL Scripts\”)

    The path specified for the “PathToUpgradeDatabaseScriptsRoot” variable is interpreted relative to the computer on which the SQL Server Management Studio session is executing.

    The folder to replace the <SET_PATH_TO_SCRIPTS_HERE> placeholder with is the folder containing the following files:

    • Master-Issuetrak-API-10.x-Create-APIUser-User-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Create-Full-Text-Catalogs-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Create-Full-Text-Indexes-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Create-Stored-Procedures-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Create-Tables-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Create-TableTypes-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Create-User-Defined-Functions-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Database-Compatibility-Change-Script.sql
    • Master-Issuetrak-API-10.x-Database-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Drop-Stored-Procedures-Upgrade-Script.sql
    • Master-Issuetrak-API-10.x-Drop-User-Defined-Functions-Upgrade-Script.sql

    Execute this database upgrade script using a tool such as Microsoft SQL Server Management Studio. The script must be executed in “SQLCMD” mode. To use SQLCMD mode in Microsoft SQL Server Management Studio, first open the upgrade script and then open the Query menu and select the “SQLCMD Mode” option (see the following screenshot from SQL Server Management Studio for an illustration of how to select SQLCMD mode from the “Query” menu).

    API4.png

    API Key Generation

    The API key generation step produces a random cryptographically strong API key that is used to generate the request authorization hashes. To generate this API key, the Key Generation Tool is provided. The Key Generation Tool should be executed after all other API installation and configuration steps are completed as the tool will insert the generated key within the Issuetrak database.

    1

    Launch the Key Generation Tool

    The Key Generation Tool is located in the “Key Generation Tool” folder in the API Installation Files folder and is named Issuetrak.API.KeyTool.exe (depending on your settings, you may not see the “.exe” ending on the filename). Double-click the Issuetrak.API.KeyTool.exe executable to start the Key Generation Tool. You will be asked to press a key to begin the process.

    API5.png
    2

    Select the Path to the API web.config File

    Provide the location of the Web.config file from the “api” folder in your Issuetrak 10.x site (not the Web.config file in the API Installation Files folder or in the root of your Issuetrak 10.x site). A file selection dialog will be displayed for this purpose. Use the dialog to locate the API Web.config file, select the file, and click the [Open] button.

    API6.png
    3

    Generate a New API Key

    If there is no API key detected in the Issuetrak database, this step will complete without the need for user interaction. If an existing API key is detected, a dialog box will be shown requesting confirmation of the key change.

    Updating to a new API key will block applications using the existing key. If in doubt, click “No”, and ensure that preparations for updating the key have been made before proceeding.

    API7.png
    4

    Retrieve the Generated API Key Value

    Once the new API key has been generated it will be displayed and you will be prompted to press [Enter]. Once you press [Enter] the new API key will be copied to your clipboard so you can paste the new API key into a document and save it in a secure location.

    Anyone who has the key can use the API, so maintaining the security of the key is extremely important. It is highly recommended that you do not transmit the key via e-mail or save it in a publicly-accessible network location.

    API8.png
    5

    Edit the web.config File to Add the API Key Value

    Search the “Web.config” file for the following text: “ENTER_API_KEY_HERE”. Change the default value of the “ENTER_API_KEY_HERE” setting value to the API key value generated in Step 4.