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 canalso  find more about Issuetrak Deployment Fundamentals 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-and-standards/standards/ecma-404/

While JSON is not exclusive to Issuetrak, it has a central role in our deployment tools. 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"}

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",
  "DistributionPath": ".\\",
  "WebsiteFilesBackupPath": ".\\backups",
  "ShouldSkipWebsiteFilesBackups": false,
  "ShouldSkipDatabaseBackups": false,
  "RepairAllObjects": false,
  "Sites": [
    {
      "Name": "my-issuetrak-site",
      "ApplicationUrl": "http://www.myissuetrak.com",
      "SiteId": "12345",
      "InitialOrganizationName": "My Issuetrak Organization",
      "InitialAdminPassword": "PASSWORD_VALUE",
      "SecureStorageKey": "KEY_VALUE",
      "SessionSigningKey": "KEY_VALUE",
      "ApiSessionSigningKey": "KEY_VALUE",
      "ShouldRemoveSqlAgentJobs": true,
      "ShouldEnableIncomingEmail": true,
      "ShouldEnableOutgoingEmail": true,
      "ShouldInstallApiV2": true,
      "AdImportActive": true,
      "ScheduledReportsActive": true,
      "RecurringIssuesActive": true,
      "AssetAuditActive": true,
      "IssueEscalationActive": true,
      "SLANotificationsActive": true,
      "ShouldEnableRedirectHttpToHttpsRule": true,
      "ShouldEnableXFrameOptionsSameoriginRewriteRule": true,
      "ShouldEnableCacheControlRewriteRule": false,
      "ShouldEnforceExpectCt": false,
      "ExpectCtReportUri": "",
      "ExpectCtMaxAge": 0,
      "Website": {
        "Name": "Deployment Test Site",
        "Bindings": [
          {
            "Protocol": "http",
            "HostName": "www.myissuetrak.com",
            "Port": 80,
            "IpAddress": "*"
          },
          {
            "Protocol": "https",
            "HostName": "www.myissuetrak.com",
            "Port": 443,
            "IpAddress": "*",
            "CertificateThumbprint": "THUMBPRINT_VALUE",
            "ShouldUseCentralCertificateStore": false
          }
        ],
        "Application": {
          "RootApplicationPath": "/",
          "PhysicalPath": "C:\\WebData\\my-issuetrak-site\\",
          "ClassicAppPoolName": "my-issuetrak-site Main",
          "MvcAppPoolName": "my-issuetrak-site Main",
          "ApiAppPoolName": "my-issuetrak-site API",
          "ApiV2AppPoolName": "my-issuetrak-site API v2",
          "IsAnonymousAuthenticationEnabled": true,
          "IsWindowsAuthenticationEnabled": false,
          "ShouldEncryptConnectionStrings": true
        }
      },
      "Database": {
        "Server": "localhost",
        "Name": "my-issuetrak-site",
        "AdminAuthenticationType": "Sql",
        "AdminName": "sa",
        "AdminPassword": "PASSWORD_VALUE",
        "SiteAuthenticationType": "Windows",
        "IntegratedSecurityUser": "DOMAIN\\UserID",
        "IntegratedSecurityPassword": "PASSWORD_VALUE",
        "ClassicUserName": "WebUser",
        "ClassicUserPassword": "PASSWORD_VALUE",
        "MvcUserName": "IssuetrakUser",
        "MvcUserPassword": "PASSWORD_VALUE",
        "ApiUserName": "ApiUser",
        "ApiUserPassword": "PASSWORD_VALUE",
        "ShouldReapplyIntegratedSecurityUser": false,
        "PreloadedDataType": "Standard"
      },
      "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"
      },
      "SiteAttributes": [
        {
          "Name": "MyAttribute",
          "Value": "MyAttributeValue"
        }
      ]
    }
  ]
}

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.
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 export.
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 production 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 12.8, this version should remain at 1.
DistributionPath	Path to the Issuetrak 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.
RepairAllObjects	Boolean value. Specifies whether the deployment tools should set the directory permissions on the web folder (and subfolders) and reinstall all database objects. Deployment will take somewhat longer.

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.
SiteId	Unique identifier for this site (provided by Issuetrak Support) used to validate your license.
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 legacy Issuetrak SQL agent jobs should be removed. If there are legacy Issuetrak 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.
ShouldEnableRedirectHttpToHttpsRule	Boolean value. Determines whether the HTTP to HTTPS URL rewrite should be enabled.
ShouldEnableXFrameOptionsSameoriginRewriteRule	Specifies whether to deploy a URL rewrite rule for this site to help prevent clickjacking. See here for more details.
ApiSessionSigningKey	Session signing key used by API v2 during authentication. This is a Base64 encoded 32-byte string in the same format used by SessionSigningKey (but should not be the same value).
ShouldInstallApiV2	Boolean value. Specifies whether API v2 should be installed.
ShouldEnforceExpectCt	Boolean value. Determines whether "enforce" is specified in the Expect-CT response header. Default value is false.
ShouldEnableCacheControlRewriteRule	Boolean value. Determines whether the URL rewrite rule to disable cache for this site should be enabled. If this value is omitted, the default behavior is for the URL rewrite rule to be disabled.
ExpectCtReportUri	Determines what value is set for "report-uri" in the Expect-CT response header. Default value is NULL.
ExpectCtMaxAge	Sets the value for "max-age" in the Expect-CT response header. Default value is 0.

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.
ShouldUseCentralCertificateStore	Boolean value. Only valid for SSL bindings. Specifies whether this site binding should use a Central Certificate Store.

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.
ApiV2AppPoolName	Name of the app pool containing the API v2 site for Issuetrak.
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.
ShouldEncryptConnectionStrings	Determines whether connection strings should be encrypted.  For sites that use SQL accounts to run, the IDM sets this to "True". For sites that use Integrated Security to run, the IDM sets this to "False".

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.
SiteAuthenticationType	Determines whether the site uses Integrated Security.  Two values are accepted:  "Windows", which effectively enables Integrated Security, and "Sql", which uses SQL credentials to authenticate to the SQL server.  If "Windows" is entered, then the "IntegratedSecurityUser" and "IntegratedSecurityPassword" entries below must also be present.  If "Sql" is entered, then the "ClassicUserName", "ClassicUserPassword", "MvcUserName", and "MvcUserPassword" entries must also be present.
IntegratedSecurityUser	If the site is deployed with Integrated Security, this will provide the user ID of the account the site is deployed with.  This value must be entered in "Domain\\Username" format to properly validate.
IntegratedSecurityPassword	The password for the Integrated Security user account that the site is deployed with.
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.
PreloadedDataType	Can either be Clean or Standard.  Clean is a blank slate for all settings and areas in Issuetrak.  Standard contains pre-filled helpful hints and pointers to assist new users with navigating Issuetrak.
ShouldReapplyIntegratedSecurityUser	If the site being deployed is already using Integrated Security, AND this setting is either omitted from the JSON or set to false, then the Integrated Security identity will NOT be applied to the scheduled tasks, services, and app pools.  If the site being deployed is already using Integrated Security, AND this setting is specified as true, then the Integrated Security identity WILL be applied to the scheduled tasks, services, and app pools.

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.