IDU Verb Documentation

Introduction to IDU Verbs

In order for the IDU to perform useful work, we need to tell it what to do. This is accomplished through the use of verbs. Only one verb may be specified at runtime. Each verb has its own set of parameters that are either required or optional. If a verb is invoked, it must be placed before any verb parameters. You may choose from the list below to jump to a specific verb's documentation, or you can jump to the Issuetrak 11.0+ Table of Contents here.

Deploy
GenerateDeploymentConfiguration
GenerateAPIKey
ApplyLicenseKey
VerifyConfiguration
DecodeLicenseKey
GetSiteDetails
VerifySQLCredentials
GetIISConfiguration


Deploy

The verb Deploy will deploy Issuetrak with the options specified.

.\issuetrak.deployment.utility deploy -c yoursite.json -x database

Verb parameters:

-i, --site

Deploys the sites specified by a space-separated list of site names. If this parameter is omitted, then all sites listed in the JSON will be deployed. Sitename consists of the name of the root website and the full IIS application path separated with a period, as well as the spaces and slashes replaced with periods.

-x, --context

Specifies which machine the deployment is running on. Valid options are “web”, “database”, “services” and “all”. If this option is omitted, it will default to “all”. Note that the JSON must provide administrative SQL authentication regardless of which context is specified. This is because the IDU performs a mandatory check of the site version prior to attempting deployment. Additionally, please note that the ‘web' and 'services’ contexts can only be deployed on the web server at this time.

-c, --config

Specifies the path and filename of the JSON configuration file. If no name or path is specified, the IDU will look in the root of the distribution for deployment.json.

-d, --distro

Specifies the path to the folder containing the distribution. If this is omitted, the path specified in the JSON is used. If the JSON doesn't provide a location, then the folder the IDU is run from is assumed to be the distribution.

--agree-to-terms-of-service

Pre-emptively acknowledges the Issuetrak Terms of Service before beginning deployment. If this parameter is not specified during deployment, the IDU will prompt the administrator to agree to the Terms of Service before proceeding.

Usage Example 1

.\issuetrak.deployment.utility deploy -c yoursite.json -x database

Deploy Issuetrak using the JSON file yoursite.json, but only using the database context.

Usage Example 2

.\issuetrak.deployment.utility deploy -d “C:\temp\Issuetrak_11.xxxx” -c yoursite.json -i site1 site2

Deploy Issuetrak from a particular distribution folder, using the JSON yoursite.json, but only the sites named site1 and site2 designated within the JSON. Since no deployment context is provided, all contexts of Issuetrak will be deployed.

GenerateDeploymentConfiguration

The verb GenerateDeploymentConfiguration will output configuration information for the Issuetrak sites found on the web server. The output will never contain valid SQL credentials, as the IDU does not have the ability to determine these on its own.

.\issuetrak.deployment.utility generatedeploymentconfiguration -i Your.Issuetrak.Site > yoursite.json

Verb parameters:

-i, --site

Generates a configuration for only the site specified as sitename. If omitted, all sites will be included in the generated configuration. Sitename consists of the name of the root website and the full IIS application path separated with a period, as well as the spaces and slashes replaced with periods.

> yoursite.json

Tells the IDU to write the output to the specified file instead of the console window. Useful for obtaining a starting configuration file for an environment with pre-existing Issuetrak sites.

The specified file does not need to exist prior to running this command.

Usage Example 1:

.\issuetrak.deployment.utility generatedeploymentconfiguration -i Your.Issuetrak.Site > yoursite.json

Generate a deployment configuration for the application “Your Issuetrak Site” , which has an application path of /. Note that the sitename converts to “Your.Issuetrak.Site”. Writes the configuration information to the file yoursite.json.

Usage Example 2:

.\issuetrak.deployment.utility generatedeploymentconfiguration > yoursite.json

Generates a deployment configuration for all sites detected on the web server. Writes the configuration information to yoursite.json.

GenerateAPIKey

The verb GenerateAPIKey generates an API key within the console window. The output contains the correct syntax to be copied and pasted into the appropriate location within a JSON. If a site is deployed with the API key specified, then that API key will be required to authenticate to the API after deployment.

.\issuetrak.deployment.utility generateapikey

Example Output:

{
"ApiKey": "3HpE9Ho4XAZFdFnRh1pFRhgVuKkPzWYQIZGYgbnEII8="
}

You may also choose to save the output of this to make it easier to find the key you generated:

.\issuetrak.deployment.utility generateapikey > apikey.txt

ApplyLicenseKey

The verb ApplyLicenseKey will parse each site entry in a given JSON. The IDU will apply the license key value specified for each site. Note that this is not related to the API key. License keys are validated as they are parsed. If the license key for a given site fails validation, it will not be applied to the site, and the IDU will skip to the next site entry in the JSON.

.\issuetrak.deployment.utility applylicensekey -c twosites.json -i Your.Web.Site

Parameters for this verb:

-i, --site

Specifies the sites to update the license key for. Multiple sites can be specified in a space-separated list. If this parameter is omitted, the IDU will parse the JSON and apply the license key value specified for each site.

-c, --config

Mandatory. Specifies the path and filename of the JSON.

Usage Example

.\issuetrak.deployment.utility applylicensekey -c twosites.json -i Your.Web.Site

Parses the file twosites.json and applies the license key specified for the Your Issuetrak Site site.

Example Output - Successful

2017-08-30 18:04:07.4873 | Issuetrak Deployment Utility - Version 11.0.xxxx
2017-08-30 18:04:07.7143 | verifying the configuration file integrity
2017-08-30 18:04:07.8153 | verifying the configuration file integrity was successful
2017-08-30 18:04:07.8153 | verifying the database server system requirements for all sites
2017-08-30 18:04:07.8483 | verifying the database server system requirements for site Your.Web.Site was successful
2017-08-30 18:04:07.8613 | verifying the database compatibility level for all sites
2017-08-30 18:04:07.9293 | verifying the database compatibility level for site Your.Web.Site was successful
2017-08-30 18:04:07.9293 | verifying the existing site version for all sites
2017-08-30 18:04:07.9523 | verifying the existing site version for site Your.Web.Site was successful
2017-08-30 18:04:07.9603 | verifying the license keys for all sites
2017-08-30 18:04:08.0583 | verifying the license keys for site Your.Web.Site was successful
2017-08-30 18:04:08.0653 | setting the license key for all sites
2017-08-30 18:04:09.7213 | setting the license key for site Your.Web.Site was successful

Example Output - Failure Scenario 1: Invalid License Key

2017-08-30 18:08:32.4594 | Issuetrak Deployment Utility - Version 11.0.xxxx
2017-08-30 18:08:32.6933 | verifying the configuration file integrity
2017-08-30 18:08:32.8473 | verifying the configuration file integrity was successful
2017-08-30 18:08:32.8593 | verifying the database server system requirements for all sites
2017-08-30 18:08:32.8813 | verifying the database server system requirements for site Your.Web.Site was successful
2017-08-30 18:08:32.9023 | verifying the database compatibility level for all sites
2017-08-30 18:08:33.2863 | verifying the database compatibility level for site Your.Web.Site was successful
2017-08-30 18:08:33.3073 | verifying the existing site version for all sites
2017-08-30 18:08:33.4523 | verifying the existing site version for site Your.Web.Site was successful
2017-08-30 18:08:33.4583 | verifying the license keys for all sites
2017-08-30 18:08:33.4823 | The License Key is invalid for site Your.Web.Site
2017-08-30 18:08:33.4893 | there was a problem verifying the license keys for site Your.Web.Site
2017-08-30 18:08:33.5203 | skipped setting the license key for all sites

Failed Output - Failure Scenario 2: Missing/Blank License Key

2017-08-30 18:09:34.3603 | Issuetrak Deployment Utility - Version 11.0.xxxx
2017-08-30 18:09:34.5842 | verifying the configuration file integrity
2017-08-30 18:09:34.6932 | verifying the configuration file integrity was successful
2017-08-30 18:09:34.7032 | Configuration file entry ‘Sites.Site.LicenseKey' must be present and not blank for site 'Your.Web.Site’
2017-08-30 18:09:34.7032 | skipped verifying the database server system requirements for all sites
2017-08-30 18:09:34.7032 | skipped verifying the database compatibility level for all sites
2017-08-30 18:09:34.7282 | skipped verifying the existing site version for all sites
2017-08-30 18:09:34.7282 | skipped verifying the license keys for all sites

VerifyConfiguration

The verb VerifyConfiguration parses the specified JSON to determine whether required values are filled. This does not validate the values, it merely checks to see if they are present.

.\issuetrak.deployment.utility verifyconfiguration -c .\twosites.json

Parameters:

-c, --config

Specifies the full path and filename of the JSON to verify. If omitted, the IDU will look for the file deployment.json in the console's current folder.

-d, --distro

Specifies the path to the folder containing the distribution. If this parameter is omitted at runtime, the IDU will use the DistributionPath value in the JSON if specified. If the DistributionPath value isn‘t specified in the JSON, and this parameter isn't passed to the IDU, then the IDU will assume the console’s current folder contains the distribution.

Usage Example

.\issuetrak.deployment.utility verifyconfiguration -c .\twosites.json

Verifies that the required values are filled in the file twosites.json.

Example Output - Successful

2017-08-30 18:25:20.4071 | verifying the configuration file integrity
2017-08-30 18:25:20.6441 | verifying the configuration file integrity was successful

Example Output - Failure

2017-09-06 14:59:09.4726 | verifying the configuration file integrity
2017-09-06 14:59:09.6196 | verifying the configuration file integrity was successful
2017-09-06 14:59:09.6286 | Configuration file entry ‘Sites’ is blank or missing.
2017-09-06 14:59:09.6286 | At least one Site entry must exist in the configuration.

DecodeLicenseKey

The verb DecodeLicenseKey will decode and output the details of one or more license keys.

.\issuetrak.deployment.utility decodelicensekey -k "908pTHjduTL7^%SKiHUX5!TRM#2ORgGIEM681iQ8ECbKp*BzznIBAo15y" "HyhC2yVaGvpfgJUZ9GbkT97YrK+HXOdezUTyomCxaOY="

There are two parameters:

-k, --key
License keys should be specified after this parameter, enclosed within quotes and separated by spaces. If the license key is invalid, then the IDU will note this in the console window.

The usage example above decodes both of the provided keys.

-b, --base64key
This parameter is a function intended to be used only by the IDM. It decodes base64-encoded license key strings. Although we don't provide a mechanism for encoding license keys in base64 for the IDU, you may encode a license key in base64, and use this parameter to decode them. Here is an example of how this parameter can be used:

.\Issuetrak.Deployment.Utility.exe decodelicensekey —b "SSBsb3ZlIHBvdGF0byBzYWxhZCBzbyBtdWNoIQ=="

Example Output - Successful

[
 {
"Key": "SSBsb3ZlIHBvdGF0byBzYWxhZCBzbyBtdWNoIQ==",
"Status": "Decoded",
"Modules": [
    "ActiveDirectory",
    "AssetManagement",
    "Billing",
    "SupportSurvey"
    ],
 "LicensedUsers": 100,
 "CreatedDate": "2015-12-08",
 "DoesExpire": false,
 "Model": "Support"
 }
]

Example Output - Failure

[
 {
    "Key": "SSBsb3ZlIHBvdGF0byBzYWxhZCBzbyBtdWNoIQ==",
    "Status": "Invalid"
 }
]

GetSiteDetails

The verb GetSiteDetails will provide very brief IIS and database information about a site specified in a JSON. This is useful for determining how long it might take to back up website files and database information, as well a count of total users versus how many are licensed.

.\issuetrak.deployment.utility getsitedetails -i Your.Web.Site -c twosites.json

Verb parameters:

-i, --site

Provides details for a specific site, specified by “sitename”. If omitted, all sites listed in the JSON will be included.

-c, --config

Provides path and filename of the JSON this verb should scan. If omitted, the IDU will look for deployment.json in the console's current folder.

Usage Example

.\issuetrak.deployment.utility getsitedetails -i Your.Web.Site -c twosites.json

Targets the site called Your Web Site, which has an entry in the JSON named twosites.json.

Example Output

{
    "Your.Web.Site": {
      "Name": "Your.Web.Site",
      "Version": "11.0.xxxx",
      "TotalUserCount": 1,
      "LicensedUserCount": 1,
      "DatabaseSizeInBytes": 84934656.0,
      "TotalSiteFileSizeWithExclusions": 71538838
  }
}

VerifySQLCredentials

The verb VerifySQLCredentials will verify SQL that credentials are valid by attempting to authenticate to the designated SQL server. If validation fails, the output on the Message line will give an indication of what went wrong.

.\issuetrak.deployment.utility verifysqlcredentials -s servername -u sa -p yourpassword

Verb parameters:

-s, --server

Mandatory. Specifies the server to verify credentials against. This can be a hostname or IP.

-u, --username

Specifies the username to verify. This must exist as a SQL account on the designated server.

-p, --password

Specifies the password to verify.

Usage Example

.\issuetrak.deployment.utility verifysqlcredentials -s yourserver -u sa -p yourpassword

Attempts to authenticate to the server called yourserver, using username sa and password yourpassword.

Example Output - Successful

{
"Server": "yourserver",
"IsVerifed": true,
"Message": ""
}

Example Output - Failure

{
"Server": "yourserver",
"IsVerifed": false,
"Message": "Login failed for user ‘sa’."
}

GetIISConfiguration

The verb GetIISConfiguration pulls information from IIS about ALL (not just Issuetrak) web sites currently running on the server and dumps them to the screen as JSON.

.\issuetrak.deployment.utility getiisconfiguration

Example Output

{
  "Websites": [
    {
      "Id": 1,
      "Name": "Default Web Site",
      "Bindings": [
        {
          "Protocol": 0,
          "HostName": "",
          "IpAddress": "*",
          "Port": 80
        }
      ],
      "Applications": [
        {
          "WebsiteName": "Default Web Site",
          "WebsiteId": 1,
          "ApplicationPoolName": "Issuetrak Classic Pool",
          "Path": "/",
          "PhysicalPath": "D:\\WebData\\Issuetrak",
          "IsAnonymousAuthenticationEnabled": true,
          "IsWindowsAuthenticationEnabled": false
        },
          ]
    },
     ],
  "Certificates": []
}

The output from this command can be redirected to a file to make it easier to view:

.\issuetrak.deployment.utility getiisconfiguration > yoursite.json