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:
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.
- App_Data (folder)
- App_Readme (folder)
- bin (folder)
- Properties (folder)
- Swagger-Resources (folder)
- Global.asax (file)
- packages.config (file)
- Web.config (file)
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).
- Right-click on Application Pools and select “Add Application Pool…”.
- Enter a name for the Application Pool, select a version 4 variant of the .NET Framework, and select “Integrated” for the Managed pipeline mode.
- Check the checkbox for “Start application pool immediately” if it is not already checked.
- Click the [OK] button to save the new Application Pool.
- In the Connections section on the left-hand side, navigate to and expand the Issuetrak site where the API is installed.
- Right-click on the “api” folder and select “Convert to Application”.
- Click the [Select] button and select the Application Pool you created for the Issuetrak API.
- Click the [OK] button to create the Application.
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 the API Key Generation step.
Within the script, there is a path variable value that must be set before the script is executed:
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 folder to replace the <SET_PATH_TO_SCRIPTS_HERE> placeholder with is the folder containing the following files:
Execute this database upgrade script using a tool such as Microsoft SQL Server Management Studio. 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).
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.
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.
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.
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.
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.
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.