Working with the JSON

Introduction

It is necessary to have an understanding of JSON before deploying Issuetrak with the IDU. This article is intended to provide you with the necessary knowledge to read, edit, understand, and fill out a JSON for Issuetrak. This knowledge is not necessary if you intend to deploy Issuetrak using the IDM.

If you're just here to reference something specific, you can jump ahead using one of the links below. You can also jump to the 11.0 Table of Contents here.

Concepts and Syntax of JSON
Working with our JSON
Generating an Initial JSON
Glossary of IDU JSON Values

What is JSON?

JSON stands for Java Script Object Notation. JSON is an international standardized format for storing and exchanging information. The standard for JSON is laid out by the international standards organization ECMA. The document ECMA-404 defines that standard, and makes an excellent reference for JSON syntax:

https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf

While JSON is not exclusive to Issuetrak, it is utilized for the new deployment tools that we‘ve introduced with Issuetrak 11.0. The JSON should therefore be considered a critical component of the IDU, as it is necessary to contain most of the configuration and deployment settings for any given environment. For the purposes of this documentation, we will often refer to the IDU’s JSON configuration file as simply the JSON.

One of the IDU‘s functions is to generate the JSON for a web server that is already hosting Issuetrak. The JSON will be populated with all of the relevant IIS settings, database information, folder locations, and site information that are necessary for a deployment. While this may seem sufficient to continue with deploying Issuetrak, it’s important that the settings and information within the JSON are verified to be both desired and complete. Always validate the contents of the JSON yourself before running a deployment of Issuetrak!

Concepts and Syntax of JSON

In order to make sense of JSON, we will provide a brief tutorial on how JSON is structured.

JSON is built around the concept of Objects. An object is a data container consisting of one or more key/value pairs. A key is a descriptor for a property given to an object, and it must be a string. A value is a property that is associated with the key, which may consist of a string, integer, array, boolean, or null. Objects may be nested within other objects.

Here's a quick primer on some of the terms above:

  • A string is a sequence of characters enclosed within a set of quotes. This is often just a word or a set of words.
  • An integer is a whole number without any decimals or fractions, eg. “-12” or “794”.
  • An array is a group of values, usually representative of a dataset.
  • A boolean is simply true (1) or false (0).
  • A null is an absence of information, represented as a value that is simply two double quotes: ""

Here's a brief set of rules on proper syntax when working within a JSON:

  • Objects are demarcated with curly brackets: { }
  • All strings are enclosed by double quotes: " "
  • Arrays containing multiple objects or values are demarcated by brackets: [ ]
  • Keys and values are separated by colons: "Key":"Value"
  • Key:value pairs are separated from each other by commas.
  • Objects are separated from other objects by commas placed immediately after their right curly bracket demarcation: {"Key1":"Value1"},{"Key2":"Value2"}

Special characters need to be escaped. That is, an additional character will need to be placed immediately afterwards in order for the rest of the JSON to parse successfully. Of particular concern is the usage of backslashes within the JSON. Any instance of a backslash must have an additional backslash placed immediately after it. Backslashes always appear in file paths, and sometimes appear in license keys. A JSON that is generated by the IDU will automatically have escaped backslashes wherever they are populated. See page 10 of ECMA's document ECMA-404 for additional information on the usage of escape characters.

Let's build an example of object usage within JSON. We can describe mundane objects using JSON. In this example, we will describe a door.

{ "MainEntrance":"Door1" }

In the example above, we have an object consisting of only one key/value pair. We named the key “MainEntrance” and provided it with the value of “Door1”. Let’s expand this object and give it another key/value pair:

{ "MainEntrance":"Door1", "Color":"Red" }

In this expanded example, both key/value pairs are provided on the same line. JSON syntax allows for multiple key/value pairs to be specified on the same line, or have the objects specified in a top-to-bottom list. As long as the syntax is correct, the software parsing the JSON will be able to read it. However, from a human-readability standpoint it is best to have the JSON laid out in a top-to-bottom list, and this is the format provided by the IDU when it generates a deployment configuration. With that in mind, let’s change our presentation of the object to a list format and add another key/value pair:

{  
      "MainEntrance":"Door1",
      "Color":"Red"
      "Status":"Open"
}

Now that we have our first object in list format, let's add another object to the mix to see how it will look:

[
    {  
        "MainEntrance":"Door1",
        "Color":"Red",
        "Status":"Open"
          },
    {
	"SideEntrance":"Door2",
	"Color":"Blue",
	"Status":"Closed"
          }
]

We have now created an array of objects. Note the overarching usage of brackets to enclose the objects and denote their status as an array. You can see that in this way, an entire JSON could be comprised of an array of objects with their key/value associations. In fact, the IDU generates a JSON that does just that.

Working with our JSON

Let‘s take a look at a valid JSON with all possible values present. The JSON below is provided with the Issuetrak distribution as the file named deployment-example-complete.json. After you read through it, we’ll make a few observations on its structure.

{
    "ConfigurationSchemaVersion": "1",
    "WebsiteFilesBackupPath": "C:\\BackupFolder",
    "ShouldSkipWebsiteFilesBackups": false,
    "ShouldSkipDatabaseBackups": false,
    "Sites": [
        {
            "Name": "my-issuetrak-site",
            "ApplicationUrl": "http://www.myissuetrak.com",
            "LicenseKey": "KEY_VALUE",
            "SecureStorageKey": "KEY_VALUE",
            "Api": {
                "AttachmentsRootFilePath": "C:\\WebData\\my-issuetrak-site\\Attachments\\",
                "UserPhotoImagesRootFilePath": "C:\\WebData\\my-issuetrak-site\\Attachments\\",
                "ApiAuthorizationBypassReferrers": "http://www.myissuetrak.com/api/swagger/ui/index",
                "ApiAuthorizationBypassIpAddresses": "127.0.0.1,::1",
                "ApiKey": "KEY_VALUE"
            },
            "Website": {
                "Name": "Deployment Test Site",
                "Bindings": [
                    {
                        "Protocol": "http",
                        "HostName": "www.myissuetrak.com",
                        "IpAddress": "*",
                        "Port": 80
                    }
                ],
                "Application": {
                    "RootApplicationPath": "/",
                    "PhysicalPath": "C:\\WebData\\my-issuetrak-site\\",
                    "ClassicAppPoolName": "my-issuetrak-site Classic",
                    "MvcAppPoolName": "my-issuetrak-site Core",
                    "ApiAppPoolName": "my-issuetrak-site API",
                    "IsAnonymousAuthenticationEnabled": true,
                    "IsWindowsAuthenticationEnabled": false
                }
            },
            "Database": {
                "Server": "localhost",
                "AdminAuthenticationType": "Sql",
                "AdminName": "sa",
                "AdminPassword": "PASSWORD_VALUE",
                "Name": "my-issuetrak-site",
                "ClassicUserName": "WebUser",
                "ClassicUserPassword": "PASSWORD_VALUE",
                "MvcUserName": "IssuetrakUser",
                "MvcUserPassword": "PASSWORD_VALUE",
                "ApiUserName": "IssuetrakApiUser",
                "ApiUserPassword": "PASSWORD_VALUE"
            },
            "ShouldRemoveSqlAgentJobs": true,
            "ShouldEnableIncomingEmail": true,
            "ShouldEnableOutgoingEmail": true,
            "ShouldEnableAdImportTask": true,
            "ShouldEnableScheduledReportsTask": true,
            "ShouldEnableRecurringIssuesTask": true,
            "ShouldEnableAssetAuditTask": true,
            "ShouldEnableIssueEscalationTask": true,
            "ShouldEnableSlaNotificationTask": true,
            "ShouldEnableRedirectHttpToHttpsRule": false
        }
    ]
}

After looking through the JSON above, it becomes evident that all instances of backslashes have been escaped, and it makes file paths look ‘wrong'. This is normal in a JSON, and isn’t anything to be worried about.

The initial section of the JSON contains global configuration options which the IDU will apply to all sites during deployment.

Scroll down further within the JSON, and you will notice that the Sites area contains an array of objects with all of the relevant site configuration populated.

Look within the Database object and find the AdminName and AdminPassword. If you intend to use SQL credentials to authenticate to the database server and deploy or upgrade Issuetrak, then these values should be filled out. If the database server's authentication (AdminAuthenticationType) is set to “Windows” then these values should remain blank.


Generating an Initial JSON

The IDM can be used to generate a JSON with several values pre-filled for you. This JSON will contain all of the proper syntax needed to be successfully parsed by the IDU or the IDM.

Create JSON from Existing Site(s)

  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.

Create JSON for a New Site

  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 Install a New Issuetrak Site.
  4. Fill out all required information and click Next as prompted. Click Add Site to Site Explorer when the button becomes available.
  5. Click Export Selected.
  6. Set the filename and location to save the exported JSON.

You now have a JSON that is ready for modification prior to deployment.

Glossary of IDU JSON Values

This section contains a list of all possible values a JSON can be populated with, and is organized by object. Each of the objects within our JSON have their own set of values.

Global
Sites
Website
Application
Database
API

 

Global

The initial section of the JSON contains information that applies to the IDU's environment, and affects all sites listed in the JSON. We will therefore call this section “Global”.

ConfigurationSchemaVersion Determines the version of the schema we're working with. As of Issuetrak 11.0, this version should remain at 1.
DistributionPath Path to the Issuetrak 11.0 distribution files. If not present, the IDU will default to using the folder that the IDU is executed from.
WebsiteFilesBackupPath Path the website files will be backed up to. This location must already exist.
ShouldSkipWebsiteFilesBackups Boolean value. Specifies whether backups of website(s) should be skipped.
ShouldSkipDatabaseBackups Boolean value. Specifies whether backups of database(s) should be skipped.

Sites

This section deals with internal properties of the Issuetrak site.

Name Name of the site that will be deployed, as it will be displayed at the top of the site.
ApplicationUrl Intended URL for the site that will be deployed.
LicenseKey Specifies the license key that should be applied to the site.
InitialOrganizationName Name for the default organization that will be in Issuetrak. Mandatory if this JSON is being used to perform an initial deployment of Issuetrak. Ignored if the site is being upgraded.
InitialAdminPassword Sets the default password for the Admin account within this instance of Issuetrak.
SecureStorageKey This is a cryptographic key for securing communication to external servers. External-facing services (IEM/OEM/AD) rely upon this value to encrypt passwords. This value is read from existing Issuetrak sites and populated into the JSON when the GenerateDeploymentConfiguration verb is passed to the IDU. If a new site is being deployed, then this value will be auto-generated for the site upon deployment.
ShouldRemoveSqlAgentJobs Specifies whether pre-Issuetrak 11.0 SQL agent jobs should be removed. If there are pre-11.0 sites still active on this server that are not being upgraded, then you should set this to False.
ShouldEnableIncomingEmail Boolean value. Sets the status of the Incoming Email feature upon site deployment.
ShouldEnableOutgoingEmail Boolean value. Sets the status of the Outgoing Email feature upon site deployment.
ShouldEnableADImportTask Determines whether the scheduled AD imports task should include this site in its processing.
ShouldEnableScheduledReportsTask Determines whether the scheduled reports scheduled task should include this site in its processing.
ShouldEnableRecurringIssuesTask Determines whether the recurring issues scheduled task should include this site in its processing.
ShouldEnableAssetAuditTask Determines whether the Asset Audits scheduled task should include this site in its processing.
ShouldEnableIssueEscalationTask Determines whether the Issue Escalation scheduled task should include this site in its processing.
ShouldEnableSlaNotificationTask Determines whether the SLA Notification scheduled task should include this site in its processing.
ReportsDirectoryOverride If present, specifies a path other than the website's “Reports” subfolder for scheduled reports output. This location must exist; it will not be created during deployment.
AttachmentOverridePath If present, specifies a path other than the website's “Attachments” subfolder for storing issue attachments. This location must exist; it will not be created during deployment.
ShouldEnableRedirectHttpToHttpsRule Boolean value. Determines whether the HTTP to HTTPS URL rewrite should be enabled. 

Website

This section is populated with an array of objects containing the relevant IIS settings specific to each site. Objects included in the array include the website's name as it appears in IIS (Name), site bindings, and app pool information. This section will be populated by the IDU if the GenerateDeploymentConfiguration verb is used during the course of an upgrade.

Name Name of the site within IIS.
Bindings Array containing all of the bindings for this site entry.
Protocol Specifies whether HTTP or HTTPS is used for this binding.
Hostname The hostname that will be set for this binding entry.
Port Port for this binding.
IpAddress IP address for this binding. Wildcards are allowed, in the form of an asterisk, to denote ‘all available IP addresses on this web server’.
CertificateThumbprint This key/value pair is valid only for SSL bindings. This needs to be set to the thumbprint value of the SSL certificate that will be used for the site.

Application

The properties described in this section have to do with the Application Pools within IIS.

RootApplicationPath This value is used for deploying virtual directories beneath existing sites, and it is always relative to the value provided for Name. For example, if the parent site is called Issuetrak in IIS, and you are attempting to deploy a virtual directory within that site called Test, then the value for RootApplicationPath will be /Test.
PhysicalPath Path to the site's web folder.
ClassicAppPoolName Name of the app pool containing the Classic side of Issuetrak.
MvcAppPoolName Name of the app pool containing the MVC/ASP.NET side of Issuetrak.
ApiAppPoolName Name of the app pool containing the API site for Issuetrak. You will notice that this key is present without a value if you export a site that does not have the API to a JSON. This is normal behavior.
IsAnonymousAuthenticationEnabled Boolean value. Specifies whether anonymous authentication is enabled for the site in IIS.
IsWindowsAuthenticationEnabled Boolean value. Specifies whether Windows authentication is enabled for the site in IIS.

Database

This section contains information relevant to how the Issuetrak site will communicate with the SQL server.

Server Hostname and named instance (if applicable) of SQL server.
Name Name of the database on the SQL server.
AdminAuthenticationType Determines the type of authentication the IDU will use for the SQL server. This authentication is only used during the usage of the IDU, and not for day-to-day behind-the-scenes use of Issuetrak. Valid values are SQL or Windows. If Windows is selected, then the Windows account that is used to run the IDU will be used to authenticate to the SQL server, and the Admin credentials provided further down in the Database object should be left blank.
AdminName Administrative SQL account used to authenticate the IDU to the SQL server. Omit or leave blank if the IDU is using Windows authentication against the SQL server.
AdminPassword Administrative SQL account's password, used to authenticate the IDU to the SQL server. Omit or leave blank if the IDU is using Windows authentication against the SQL server.
ClassicUserName Mandatory. SQL account that the Classic side of the Issuetrak site will use to authenticate to the SQL server.
ClassicUserPassword Mandatory. Password for the SQL account used by the Classic portion of the Issuetrak site.
MvcUserName Mandatory. SQL account that the MVC/ASP.NET portion of the site will use to authenticate to the SQL server.
MvcUserPassword Mandatory. Password for the MVC/ASP.NET site's SQL account.
ApiUserName SQL account used for the API site to authenticate to the SQL server. You will notice that this key is present without a value if you export a site that does not have the API to a JSON. This is normal behavior.
ApiUserPassword Password for the SQL account used for the API site. You will notice that this key is present without a value if you export a site that does not have the API to a JSON. This is normal behavior.

API

This area contains API-specific settings. This section can be entirely omitted from the JSON if the deployment of the API is not desired.

AttachmentsRootFilePath Path to the Attachments folder within the applicable Issuetrak site. This location must exist; it will not be created during deployment.
UserPhotoImagesRootFilePath Path to the User Graphics folder within the applicable Issuetrak site. This location must exist; it will not be created during deployment.
ApiAuthorizationBypassReferrers URL that will be used to access the API.
ApiAuthorizationBypassIpAddresses Whitelist of IPv4 and IPv6 addresses that will be used to access the API.
ApiKey API key used to authenticate API users. The GenerateAPIKey verb can be used with the IDU to create this value.