TICS Viewer Configuration

This chapter explains the various configuration items for setting up and working with the TICS Viewer.

The TICS Viewer requires some bootstrap configuration to set up and get started. After you have a working TICS Viewer, it can be used to set other configuration options that further control the workings of TICSQServer and the viewer itself. We distinguish between TICSQServer and viewer configuration on one hand, and general and project-specific configuration on the other hand. The locations where the various configuration items can be found are:

Administration Pages

This section describes some of the settings that you find in the Administration pages, in alphabetical order. To access the Administration pages, you need to be logged in and you need to have the proper permissions. If that is the case, you will find the Administration pages in the application dropdown menu in the upper-left corner.

Artifact Repositories

The TiCS command-line tools that are running on a build server or developer machine need other artifacts, such as code checkers, to function. TiCS downloads these artifacts from the viewer-embedded repository on demand. It caches and extracts the downloaded artifacts in a local work directory, and reuses these artifacts for follow-up runs if the version was not changed in the meantime. By default, this embedded repository is automatically populated by the viewer by downloading files from the TIOBE Artifact Registry. Which version to download for which particular artifact is controlled by the config.yaml file: updating a particular checker or tool is a matter of increasing its version in the config.yaml file. The embedded repository can also be populated manually by uploading files to the ticsfs directory on the webserver, located in the section root. This is needed for instance for third-party artifacts that can only be acquired through the vendor's website, such as Coverity.

As outlined above, the default behavior is to serve artifacts from the viewer's embedded repository. However, you can configure the viewer to serve artifacts from an external artifact repository instead. In order to do so, add a new entry to Administration Pages → Artifact Repositories (you need the manageArtifactRepositories permission in order to do so). Then, reference the repository's identifier in each config.yaml file where it should be used using the syntax repository: repo-identifier. External repositories can be automatically populated by the viewer if the repository allows it. If not, you have to populate it yourself. See the section below for more information.

When configuring an external repository, you need to specify the following properties:

Repository type
The type of this repository. Currently supported are the vendor-specific repository managers Sonatype Nexus (using recipe 'raw (hosted)') and JFrog Artifactory (using package type 'Generic'). We also support a vendor-less generic HTTP type that can be used to serve artifacts using standard HTTP methods (HEAD, GET, and PUT).
Identifier
A unique identifier for the repository. This identifier is used for referencing the repository in the config.yaml file. The identifier allows a limited set of characters.
Name
A human-readable name for your repository. Used in informational and error messages about the repository.
URL
Base URL for the repository. Artifacts are expected to be found relative to this base URL. To retrieve an artifact, the base URL is extended with an artifact-specific relative path that is inferred from the config.yaml file.
Authentication
Credentials that are needed when downloading (GET) artifacts from the repository. The following authentication types are supported: no authentication, basic username/password, and bearer token. All authentication types are simple fixed credentials that do not vary per user.
Extra HTTP headers
This is an advanced optional parameter that allows you to specify additional HTTP headers that should be sent with the request when downloading a file.
Allow Upload
Boolean setting that determines whether the viewer can upload artifacts to the repository. This allows the viewer to populate the repository by using the TIOBE Artifact Registry as source repository. By enabling this, you will probably want to configure an authentication method for uploading the artifacts. This authentication method can use different credentials than for downloading artifacts. Uploads to the repository are done by doing an HTTP PUT request containing the file contents as payload.
Reachable from Viewer
This is an advanced setting (with a default and preferred value of 'Yes') that allows you to indicate that the repository is not reachable from the viewer. Setting this to 'No' disables validation on the artifact repository both in the dialog itself and when editing the config.yaml file. If you disable this setting, you need to make sure that a source repository for the artifacts is configured in the config.yaml file. The reason is that the viewer needs access to an artifact to determine its file size and CRC.

Populating an external repository

The easiest way to populate an external repository is to allow the viewer to upload artifacts to it. If this is not possible, you have to populate it yourself. Artifacts can be downloaded from our download site. Alternatively, you can first configure the viewer to use the embedded repository. On saving the config.yaml, the files will be downloaded to the embedded repository (in a directory named .cache found in each artifact directory), where you can pick them up to upload to the external repository.

The locations where you have to place artifacts depends on how you reference the artifacts in the config.yaml file: by path or by version. The preferred way is to reference them by version. If you configure an artifact using the version and platform properties in the config.yaml file, the artifact is expected to be found in path (base URL)/(artifact type directory name)/(tool name)?/(artifact filename.zip). The artifact type directory name is sometimes the same and sometimes slightly different from the respective property in the config.yaml. Please refer to the table below:

Artifact type description Key in config.yaml Directory name in repository Has tool sub-directory
TiCS command-line tool binaries ticsbin bin no
Code Checkers checkers chk yes
Rule implementation rules rules yes
Java Runtime Environment jre jre no
TiCS command-line wrappers wrapper wrapper no
To find out where an artifact is expected to be found, you can also check the validation error message when editing the config.yaml file.

If you configure the artifact path explicitly using the property artifact you can control where the artifact is located. The absolute URL is obtained by concatenating the repository's base URL with the value of artifact.

Authentication & Authorization

Authorization allows you to control which users have access to which projects and functionalities of the viewer. Users authenticate themselves using the authentication dialog that is accessible through the padlock icon () in the upper-right corner. The viewer supports the following authentication providers:

The simple built-in authentication provider requires an administrator to manually add each username and password to the viewer settings database. The LDAP authentication provider connects to an existing LDAP directory service running in your network, so that users can use the same credentials as they are used to. Azure Active Directory (Azure AD) is a cloud-based identity provider built and operated by Microsoft. Our authentication provider for Azure AD is currently the only one that supports multi-factor authentication and single sign-on (SSO). See the section below for more information on configuring Azure AD.

Users that log in using one of the authentication providers are automatically added to the user database when they first log in. Even when using an external authentication provider, you still might want to add built-in user accounts manually. Another good practice is to create a (backup) administrator account that can be used when you are locked out, for instance when the LDAP service is (temporarily) unavailable, or when you made a change to an LDAP query that caused you to no longer have the proper permissions.

To use the built-in authentication provider, create a user with a password in the Administration Pages → Users settings. In the user creation dialog, you can immediately choose the role that the user should receive. The user will assume this role for all projects. If this is not desired, you can choose to not assign a default role, but instead configure this using Authorization Rules, as explained below. To use LDAP authentication, create one or more LDAP Queries. A user is authenticated when it is accepted by at least one of the LDAP queries. You should create multiple LDAP queries if you want to assign different roles to different sets of users.

A role is simply a convenient name for a set of permissions. Example (built-in) roles are "Administrator", "Build Manager", and "User". Examples of permissions are the "administration" permission, which allows a user to access the Administration page and the "view project" permission, which allows a user to view metric data of a project. You can inspect or create new roles in the Administration Pages → Roles settings.

Authorization Rules

To assign roles to users, you can create authorization rules. Alternatively you can set the 'default role' for a user that is controlled by the built-in authentication provider. By default a rule exists that assigns the User role to users that are not logged in (guests). To disable guest access, you should first delete this rule and then create one or more new rules. When creating a new rule, you need to select the user scope and the project scope. The project scope determines for which projects the user receives the permissions that are associated with the role. This is only relevant for project-specific permissions, such as the "view project" and "edit project" permissions. You can leave this field empty to select all projects. For the user scope, we distinguish the following types:

By default, a user that does not have access to a project gets to see a padlock icon instead of the metric value. If you want to hide the project altogether, disable the "List unauthorized projects" setting on the Security → General page.

Please refer to the Administration Pages for more in-depth information.

Authentication Tokens

An authentication token is used to authorize a client process, such as TICSQServer or a script accessing the WebAPI, when it connects to the TICS Viewer. There are two types of tokens:

For both types of tokens you can optionally set an expiration date. When a user is removed from the system, the associated user-bound tokens will automatically be revoked. Role-bound tokens are not revoked when the user that created them is removed.

By default, the communication between the TICS executables (comprised of the TICS, TICSQServer and TICSMaintenance command-line tools) and the TICS Viewer requires authentication. However, previous versions automatically added guest authorization rules to disable the need for authentication for the roles mentioned above.

Warning! If your TICS Viewer is accessible to the public (untrusted) internet, you should take action in the case of an update, and make sure authentication tokens are configured as described below.

To make sure that communication to the viewer is protected by authentication, take the following steps:

Configuring a token for TICS Analyzer

To allow TICS Analyzer to communicate with the TICS Viewer, you need to configure an authentication token, as follows:

Configuring a token for TICS Client

TICS Client (the TICS executable) is used by developers on their local machine to check the quality of their code. Each developer that wants to use TICS Client should generate a token first, by following the following steps:

Users that want to use TICS Client need to have the following permissions: queryDatabase, queryConfiguration, queryArtifacts, and clientDataUploadApi. By default, in an out-of-the-box installation, the Developer role has these permissions, but the default User role has not. In case you are having an authorization problem when using TICS Client even after configuring a token, ask your administrator to change your role to Developer for instance, or change the permissions of your role. Note that you can inspect your permissions in the authentication dialog ().

Configuring a token for TICS Build Service

When you want to want to make use of the (optional) TICS Build Service, you need to create two tokens: one for the 'TICS Analyzer' role as described above, and one for the 'TICS Build Service' role. Both tokens should be placed in %APPDATA%/TICS (on Linux ~/.tics) for the account under which TICS Build Service is running. By default, on Windows, TICS Build Service is running under the LocalSystem account, so the token should be placed in C:\Windows\System32\config\systemprofile\AppData\Roaming\TICS. You probably need to create the TICS directory. Alternatively, you can change the account under which the service is running and put the tokens in the %APPDATA%/TICS directory of that account. In order to change the account, take the following steps:

  1. Open the Administrative Tools → Services window on your Windows server
  2. Open the Properties → Log On dialog for the service named 'TICS Build Service'
  3. Change the account to the target user account
  4. Restart the service

As an alternative to creating a TICS Build Service authentication token, you can also create a guest authorization rule for the TICS Build Service role.

Automation Scripts

Authentication tokens can also be useful when you want to write an automation script that accesses the Web API. Instead of putting your own username and password in the script, you can generate a token and use that instead.

When you obtained a token, you should make sure that the HTTP client library or command-line tool provides the HTTP basic access authentication header. Below is an example for providing a token when using the curl command-line tool to retrieve data from the Measure API: 

curl -H "Authorization: Basic ZjYxNzMyZmItZGQyOC00M2VhLWI2ZjYtZGE4ODQwZjMzYmMxOntlSFxHO3o0d3QiUUJ9Ig" "http://localhost/tiobeweb/TICS/api/public/v1/Measure?metrics=tqi&filters=Project(MYPROJECT)"

Configuring Azure Active Directory

Azure Active Directory is an identity provider from Microsoft that can be used for authentication in the TICS viewer when your organization has a Microsoft Azure account (tenant). The TICS viewer does not have to run in the Azure cloud for this to work. To start using Azure AD for authentication, you need to take the following steps (see also here).

First configure the Azure side:

  1. Sign-in to the Azure portal
  2. Search for Azure Active Directory
  3. Select App Registrations
  4. Select New Registration and enter the following:
    1. Enter a name for the application, for instance 'TICS Viewer'
    2. Select an account type, typically Accounts in this organizational directory only
    3. Select the Redirect URI type Web
    4. Enter Redirect URI: https://HOSTNAME/tiobeweb/TICS/api/public/v1/AzureAuth (URL path is case sensitive), where HOSTNAME is the hostname of the server through which your users will access the viewer. Azure AD requires this to be an https address for security reasons. Note that TICS is the name of the viewer section for which you want to configure Azure AD. The default section name is 'TICS'. If you have multiple sections configured, you need to configure multiple Redirect URI's.
    5. Click Register
  5. You will be redirected to the Overview page for the newly registered 'TICS Viewer' app showing details that we need when configuring the viewer side.
  6. Navigate to Certificates & Secrets
  7. Select New client secret and add a client secret using an appropriate description and expiration time

Enabling Azure Group Membership claims is optional, but it allows the TICS Viewer to receive information about the Azure groups that a logged in user is a member of. In order to enable Group Membership claims, do the following:

  1. In the App Overview page, go to Manifest
  2. In the JSON editor, change: "groupMembershipClaims": null to "groupMembershipClaims": "SecurityGroup"
  3. Click Save

After configuring the Azure portal, you need configure the Azure identity provider in the TICS Viewer:

  1. Sign-in to the TICS Viewer as Administrator user
  2. Navigate to Administration Pages → Identity Providers
  3. Select Add Identity Provider
  4. Enter as Authority URL: https://login.microsoftonline.com/tenant_id where you replace tenant_id by the identifier (UUID) found next to field 'Directory (tenant) ID' on the Overview page in the Azure portal.
  5. Enter as Application ID the identifier (UUID) found next to the field 'Application (client) ID' on the Overview page
  6. Enter as Client Secret the client secret value (not the ID) configured in the Azure portal.
    Limitation Certificates are not yet supported.
  7. Click Ok
  8. The Authentication dialog will now contain a new button that allows you to log in using Azure Active Directory. Note that if you are already logged in, you first need to log out for the button to become visible.

Finally, you need to configure an authorization rule of type GROUP to make sure that users that authenticate using Azure will be assigned a role. Group memberships claims are reported by Azure as a group object id (as opposed to a human-readable name). You can create groups and find their object ids in the Azure Portal in the Azure AD → Manage → Groups panel. If you did not configure the groupMembershipClaims option in Azure (see above), and you want to assign a role to anyone that logs in using Azure, you need to configure an authorization rule with type GROUP for group id 69f04963-31e8-467c-9e69-43cfdf3f3651.

Custom Notifications

A notification is a message that the viewer shows in the upper-right corner to provide the user with information, or to notify the user of any problems. Different colors are used for different levels of severity:

An example of an informational notification is when you open the Annotated Source for the Coding Standard metric and there are no issues for that metric. You will then see the following notification in the upper-right corner:

This file has no Coding Standard Violations

A custom notification is a message that is created by a user, rather than originating from the system itself. Only users having the manageCustomNotifications permission can create custom notifications; these are typically users having the 'Administrator' role, but this can be configured. Custom notifications are useful to broadcast messages to all users of the viewer. An example of this is to inform users of scheduled maintenance, or a tool that is temporarily failing, causing a drop in the TQI scores. Custom notifications are visually distinct through the use of a hand icon ().

Custom notifications can be created in the Administration Pages → Custom Notifications panel.

Filter Sets

Filter sets can be used to restrict quality gate conditions to specific files in the archive. You assign a logical name to a filter set, so that you can easily refer to it. Currently you can select a Language, Code Type and Time Window when defining a filter set. The Time Window allows you to define a quality gate condition that holds only for files that are created or changed after a certain date.

Firewall

Using the firewall settings you can block access to users based on their IP address. This provides an extra layer of protection on top of the authorization mechanism described above. The firewall supports IPv4 and IPv6 addresses, black- and whitelisting, and fine control over which functionality of the viewer should be blocked.

Please refer to the Administration Pages → Firewall settings for more in-depth information.

Metric Presets

Metric presets are shortcuts to pre-configured sets of metrics. They are accessible from the Presets dropdown menu in the Explorer view. When selecting a preset in the Explorer, all existing metrics are replaced. In addition to metrics, a preset optionally sets one or more filters.

The TICS Viewer comes with a number of pre-configured metrics. You can change those or add new ones in Administration Pages → Metric Presets settings.

Quality Gates

A quality gate is a set of conditions that should hold before your software can pass to the next phase in the software development process. Each condition checks whether the current value of a metric is above or below a target threshold. An example of a condition is 'the number of Coding Standard Violations for level 1, 2, and 3 should be 0'.

You can define quality gates in the Administration Pages → Quality Gates settings.

The quality gate statuses can be seen on the TQI Dashboard when you group by project or branch. A green or red flag behind the project determines whether the project passes or fails the gate. When no gate is associated with a project, no flag is shown. When an evaluation error occurred, an orange flag is shown, urging you to check the gate configuration. By clicking on the flag a dialog opens showing the evaluation result of each condition. Clicking on a condition shows you why the condition failed (or passed).

Quality gates statuses are evaluated dynamically by the viewer and are not stored in the database. This has advantage that when you create or change a quality gate, you can immediately see it's effect; projects that previously did not have a quality gate associated it now do, and passed projects might now fail and vice versa. This allows you to adjust the quality gate definitions and see the effect immediately. This also allows you to go back in time using the time machine functionality and inspect the status when the gate was not even defined yet.

You can specify a Filter Set when defining a condition, which allows you to restrict the quality gate check to certain parts of the code. For instance, you might want to exclude certain programming languages code from being able to fail the quality gate.

Conditions can be evaluated (checked) per project (the default) or per file. When checking per file, every individual file should pass the condition. For 'file-based' conditions, the quality gate flags are also shown for items inside a project, such as directories and files. In the status dialog, conditions that are project-based are shown as skipped (), to indicate that they are not applicable on this level. The same holds when the condition is evaluated against an empty file set, which can happen for instance when the condition is defined on Java code (using a Filter Set), while there directory only contains JavaScript code.

Conditions can be absolute (the default) or relative. An absolute condition checks whether the metric value at the current date is above or below the target threshold. A relative condition checks whether the metric has changed a certain amount with respect to a chosen reference date, or in other words, whether the delta metric value is above or below the target threshold. An example of a relative condition is 'Δ Average Code Coverage ≥ 0', which specifies that the code coverage should increase with respect to the given reference date, which is configured in the binding as explained below.

When you create a quality gate, a default binding is created that binds the gate to global project scope. This means that the gate will be checked for every project configured in the viewer. If you only want some projects to be checked by the gate, you can specify a narrower scope in the binding.

In addition to the scope, you can also specify the delta reference date in the binding. This determines for relative conditions which date should be taken to compare the metric value with. These options include picking a specific date, a specific baseline name, the last baseline, the first analysis, or the previous analysis. Note that all options reference a static point in time, except for the 'previous analysis' which is dynamic: the reference date changes with each run. This could result in an unstable quality gate status: when the gate status goes to 'failed' because a developer introduced 5 issues, it will go to 'passed' when the next commit solves 1 issue. You can still see this in the history of the status, but you must take care not to ignore this information. Therefore, we recommend using one of the static reference dates where possible, or combine the dynamic reference date with a static one by creating two bindings.

Quality Indicators

A quality indicator is a standardized metric of software quality. It expresses the quality of (an aspect of) source code on a scale between 0 and 100%. The TIOBE Quality Indicator (TQI) is the built-in quality indicator that is defined by TIOBE, and is defined as the weighted average of 8 sub-metrics, such as code coverage, duplication, coding standard compliance, complexity, etc. The TQI has an associated label that is shown on the Dashboard. The TQI metric and its sub-metrics can be selected from the metric picker, but you can also click on one of the sub-metrics in the TQI Label to select it.

In addition to the built-in quality indicator, you can define your own custom quality indicator metric and associated quality label in Administration Pages → Quality Indicators. You need to have the manageQualityIndicators permission to do this. By default, the Administrator, Build Manager, and Project Leader roles have this permission. A custom quality indicator metric can be used in the same way as the TQI: you can define quality gates on it, create metric presets, compute deltas on it, etc.

Name
Quality Attribute
Abbreviation
Sub-metrics
Document URL and Title

When creating a quality indicator, you need to specify the following properties:

Name
The name of the quality indicator and associated metric. This name will be shown in the metric picker and in the QI Label's title for instance. Example value: Custom Quality Indicator
Abbreviation
The abbreviation is used in places in the user interface where the full name would not fit, such as in the tab list on top of the QI label that will be shown when multiple QI labels are configured. It will also be used in front of the names for the QI sub-metrics. Your are advised to use upper-case letters. Example value: CQI
Enabled
Determines whether the quality indicator is enabled. When disabled, the QI label and metrics are not shown anywhere in the viewer. This is useful to temporarily disable the QI as long as you are not happy with it, without having to delete it completely.
Add Label To Dashboard
Whether the quality indicator should be shown as a label on the dashboard. When this setting is disabled, you can still select the quality indicator in the metric picker. When you want to make sure that your quality indicator is selected by default when opening the Dashboard, make sure that your custom quality indicator is first in the list by using drag & drop.
Identifier
This mandatory field is the identifier that is used in the metric expressions for the QI metric and sub-metrics. The identifier is not used in the user interface, but it is used to persistently and uniquely refer to the quality indicator's metric and sub-metrics in URLs and other settings, such as quality gate and metric preset settings. It is best to pick the identifier once and not change it later, because changing it will invalidate all URLs and settings that refer to it. If not set, the identifier will automatically be set to the lower-case value of the abbreviation, but please check whether you are happy with the automatic choice. Example value: cqi
Document URL and Title
These optional properties will be used to generate a hyperlink in the bottom of the quality indicator label that brings the user to the PDF document or website detailing on the quality indicator's definition. The URL is used as the target of the link. The optional title is used as the text for the link; if omitted, the name of the quality indicator is used as the title.
Quality Attribute
An optional setting that specifies which quality attribute this indicator measures. This is currently only used as a text in the QI Label above and below the rainbow indicator. Leave empty to use the text 'quality'. Example value: maintainability

Sub-metrics

After creating the quality indicator, you have to specify one or more sub-metrics (also called components) that define the value of the quality indicator metric as a weighted average. As long as the custom quality indicator has no sub-metrics defined, it will be considered disabled and will not be shown. Each sub-metrics is based on another metric with an optional formula applied to it. The outcome of this formula should be a score in the 0-100% range that indicates the score on a particular quality attribute, where 100% is a perfect score. In any case, the metric value will be clamped to 0-100% range so that metric values cannot go outside of it.

Name

The name of the sub-metric as shown in the UI. Note that it will be prefixed by the abbreviation of the associated quality indicator. For instance, if you define a sub-metric 'Coupling' in the quality indicator with abbreviation 'CQI', the full metric name will become 'CQI Coupling'. Example value: Coupling.

Base Metric

The metric on which this sub-metric is based. If you pick a metric that is not in the 0-100% range, you should set a formula to make sure it is mapped to that range. Not all metrics are available for you to pick. You cannot pick another quality indicator metric for instance. The reason for this is that the quality indicator metric already considers the metric coverage, and since the custom quality indicator that you define also takes this into account, the metric coverage would be considered twice.

For each QI sub-metric, the metric picker shows a folder that contains the QI sub-metric, the associated metric coverage metric, and the base metric. Additionally, it contains metrics that are related to the base metric. For instance, when you select Coding Standard Compliance as a base metric, the QI folder will also contains the related Violations, Violations/KLOC, Suppressions, and Suppressions/KLOC metrics. However, the metric picker has the limitation that it will not show duplicate metrics. This means that if you pick a base metric that is already used by another QI metric (including any built-in QI metric, such as the TQI), only the first QI folder will show those base metric and related metrics.

Relative Weight
The weight that this sub-metric has in the weighted average over all the sub-metrics for this QI, as a natural number. For example, if you use 1 for all sub-metrics, they all have equal weight. If you have three sub-metrics and give them weight 1, 2, and 3 respectively, they will have weights of 1/6, 2/6, and 3/6 respectively.
Formula
An optional formula that is applied to the base metric value. The outcome of this formula should be a score between 0 and 100%. The formula should use v to refer to the base metric value.
  • You can use the following mathematical operators: +, -, *, /, %, ^, &&, ||, <, >, =, !=
  • You can use the following mathematical functions: abs(v), log(v), log10(v), round(v), floor(v), ceiling(v), sqrt(v), min(v,u), max(v,u), not(b), if(b, v, u), where v and u are numerical expressions, and b is a boolean expression.
  • You can use the following constants: e, PI

Example formulas are 100 / max(v,1), 100 - 50 * log10(101 - v), if(v > 50, 100, 0).

An effort is made to validate the formula to check whether it produces a real result for values of v in the range [0..100]: the formula should not cause a division by zero or produce an infinite value. You should avoid division by zero by using the provided functions. For instance, when you want to use the formula 100 / v for a base metric that produces natural numbers, you could use 100 / max(v,1) instead to avoid division by zero for v=0. Alternatively, you could use if(v=0, 100, 100 / v).

Identifier
An identifier that is used to uniquely and persistently refer to the sub-metric. Please see the description of the Identifier field of for considerations. Example value: coupling.

Remarks and limitations

Source Code Retrieval

After each analysis, TICSQServer uploads the source files that it analyzed to the viewer and removes any previously uploaded source files. This means that old revisions of source files are not readily available to the viewer. If you want to use the 'Diff' functionality in the Annotated Source, you need to enable Source Code Retrieval to be able to see old source file revisions.

The Source Code Retrieval is opt-in; it is disabled by default. You can enable it in the Administration Pages → Source Code Retrieval settings. By default, the viewer will invoke TICSMaintenance on the Build Server (using TICS Build Service). The requirements for this default scenario are:

If these requirements are not met, you can configure the viewer to invoke a custom command on the viewer machine to retrieve source files. For instance, to configure the viewer to use Subversion over SSH, use the following settings:

Retrieve Old Sources
Yes
Execute on Viewer
Yes
Use Custom Command
Yes
Command
svn cat svn+ssh://user@192.168.1.1/path/to/svnrepository/$file@$revision
Environment Variables
SVN_SSH="C:/Program Files (x86)/Putty/plink.exe" -i "C:/Program Files (x86)/Putty/privatekey.ppk"

Please refer to the Administration Pages→Source Code Retrieval settings for more in-depth information.

Configuring Sections

A default TICS installation only has one section, named TICS. When you access the viewer, you can see the section name in your browser's address bar. Sometimes you want to configure multiple sections, for instance, one for each business unit. Each section is isolated from the rest in the sense that it has its own set of projects and configuration. It is also possible for each section to run a distinct version of the viewer. This is useful for instance when you want to upgrade to a new version, but want to assess the impact of this upgrade on your TQI score, or first want to make sure that the new viewer is running correctly before you move it into production.

To configure a new section, you need to change the TIOBEPortal.cfg file. This JSON file is located in the webapps directory of your Tomcat installation, and look something likes this: 

{
  "TICS": {
    "root": "C:/Program Files/TIOBE/TICS/WebServer/TICS",
    "tiobewebServlet": "tiobeweb-9.0.1.34491"
  }
}

The root key points to a directory where the viewer stores various files such as data and settings (section root). The tiobewebServlet points to the name of WAR file that contains the viewer "servlet". To create a new section, you are advised to first stop the Tomcat service. Then, duplicate the JSON object, change both the section name and the root directory. For instance, to create a new section "BU2" for a new business unit, the TIOBEPortal.cfg file will look like this: 

{
  "TICS": {
    "root": "C:/Program Files/TIOBE/TICS/WebServer/TICS",
    "tiobewebServlet": "tiobeweb-9.0.1.34491"
  },
  "BU2": {
    "root": "C:/Program Files/TIOBE/TICS/WebServer/BU2",
    "tiobewebServlet": "tiobeweb-9.0.1.34491"
  }  
}

After saving your changes, restart Tomcat, and access the BU2 section. You can do this by accessing your viewer's URL without a section, i.e. by accessing http://yourhostname:42506/tiobeweb. You will get a page with a list of configured sections.

It is possible to hide certain sections from this list. To achieve this, specify "hidden": true for the sections you want to hide from this list. If all sections are hidden but one, you are automatically forwarded to that section.

Configuring SSL/TLS

The TICS Viewer acts as both a server and a client in several communication channels, as depicted in the diagram below.

Most of these channels can be configured to use secure SSL/TLS communication. The TICS Viewer acts as a server (incoming arrows) in the following events:

In order to make the the above connections secure, you need to configure server-side SSL/TLS.

The TICS Viewer acts as a client (outgoing arrows) in the following events:

Server-side SSL/TLS

By configuring SSL/TLS you enable encrypted HTTPS communication between the TICS Viewer and its clients, such as browsers, which helps to prevent intruders from stealing sensitive data such as passwords. Because the TICS Viewer runs on Apache Tomcat, SSL/TLS can be configured through the Tomcat configuration files.

Alternatively, you can install a reverse proxy such a Nginx on a different machine or port number to encrypt traffic between the proxy and the browsers. Communication between the viewer and proxy can then remain unencrypted, so that you do not have to change the Tomcat configuration.

Server-side SSL using Tomcat configuration

To configure SSL in Tomcat, you first need to have a certificate. You can acquire one from a certificate authority (CA), or you can generate a self-signed certificate. In general, the downside of a self-signed certificate is that they are not trusted by default, and explicit configuration on the client side is typically needed. To generate a self-signed certificate for IP address 192.168.1.91, execute the following command and use changeit when prompted for the password: 

"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -keystore c:/path/to/keystore.jks -ext SAN=IP:192.168.1.91

Now add an HTTPS connector to conf/server.xml located in the Tomcat directory: 

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" 
   maxHttpHeaderSize="8192" SSLEnabled="true" 
   maxThreads="150" minSpareThreads="25" 
   enableLookups="false" disableUploadTimeout="true" 
   acceptCount="100" scheme="https" secure="true" 
   clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true" 
   keystorePass="changeit" 
   keystoreFile="c:/path/to/keystore.jks" 
   />

You need to restart the Tomcat service for the changes to take effect. Afterwards, you should be able to access the viewer on HTTPS on port 8443. Note that when using a self-signed certificate, your browser will indicate that the connection is not secure, because the browser does not trust self-signed certificates. This means that the connection is encrypted, but the server cannot be authenticated.

If you want to disable HTTP access, you can remove the default HTTP connector for port 42506 that was created by the setup. In case you migrate from a situation where the viewer was already running for some time and was accepting HTTP connections, and you now only want to support HTTPS connections, you can forward all requests so that existing links will not be broken. To do so, specify the redirectPort in the HTTP connector in server.xml as follows: 

<Connector connectionTimeout="20000" 
    port="42506" 
    protocol="HTTP/1.1" 
    redirectPort="8443"
    />

In conf/web.xml you have to include the following snippet inside <web-app>: 

<security-constraint>
    <web-resource-collection>
        <web-resource-name>HTTPSOnly</web-resource-name>
        <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>
Heads up! For some updates of the viewer, the TICS setup wants to update the Tomcat installation e.g. to fix a security vulnerability. Please make sure you have a backup of the conf/server.xml (and perhaps conf/web.xml), so that you can restore your configuration changes when they are overwritten by the defaults.

Client-side SSL/TLS for the TICS Viewer

In cases where the TICS Viewer acts as a client in communicating with other machines through SSL/TLS, and in case the certificate that the server uses is not signed by a root certificate that is trusted by Java by default, you need to add that certificate to the JRE's trust store (located in %JAVA_HOME%\lib\security\cacerts), using the keytool command that ships with Java and is located in %JAVA_HOME%\jre\bin.

If you have a certificate file (.cer, .crt) for instance, you would run: 

%JAVA_HOME%\bin\keytool -import -trustcacerts -alias "MyRootCA" -file my-certificate.crt -keystore %JAVA_HOME%\lib\security\cacerts -storepass changeit -noprompt

If you have a keystore file (.jks), you would invoke the following command: 

%JAVA_HOME%\bin\keytool -importkeystore -srckeystore my-keystore.jks -destkeystore %JAVA_HOME%\lib\security\cacerts -srcstorepass changeit -deststorepass changeit -noprompt

Please refer to the documentation of keytool for more details. The TICS viewer will pick up changes to the cacerts automatically: you do not need to restart Tomcat.

Heads up! The TICS setup sometimes updates the JRE that ships with TICS, but it will take care to merge the existing cacerts file with the new one, so that changes you made are not lost.

Client-side SSL/TLS for other TICS applications

Various TICS applications (such as the TICS Client and TICS Build Server) can connect to the TICS Viewer. When the viewer is configured to use SSL, build servers and clients might need SSL configuration as well, depending on the type of the certificate authority (CA) that your certificate requires:

Heads up! This section assumes that you are using the latest version of the TICS wrappers. Older versions of the TICS wrapper may result in usage of insecure connections by default.

When it comes to SSL/TLS, there are two relevant configuration properties:

In cases where self-signed certificates are used, these security constraints may be too strict. In this case, both of these features can be enabled or disabled through properties in a configuration file or environment variables. This configuration file should be named wrapper.properties and should be placed either next to the wrapper for the application (typically in the BuildServer or Client directory) or in the client configuration directory located in %APPDATA%\TICS (on Windows) or ~/.tics (on Unix-like platforms).

FeatureEnvironment variablePropertyPermitted values
Certificate validationTICSTRUSTSTRATEGYtrust_strategyall, self-signed, strict
Hostname verificationTICSHOSTNAMEVERIFICATIONhostname_verification1/true or 0/false

By default, TICS will use secure settings, meaning the strict trust strategy and hostname verification enabled. Changing these settings will make the connection less secure and enable potential attackers to impact the correct operation of TICS.

Note that changing these settings requires the application to be restarted. In particular, the TICSBuildServer application or TICSBuildService service will need to be restarted as well.

Proxy Server Configuration

It is possible that your (company) network uses a proxy to (limit) access (to) certain websites. The TICS executables (TICS, TICSQServer, TICSMaintenance) communicate with the viewer via HTTP(S). In case the viewer is only accessible via a proxy, the proxy settings should be propagated to the TICS executables.

You can use the *_proxy environment variables to specify the proxy settings for TICS, e.g., 

http_proxy=http://127.0.0.1:8989
https_proxy=http://127.0.0.1:8989

If (for example) http_proxy is set in the environment TICS is running in, then these settings will be used by the TICS executables when communicating with the viewer.

Note that it is also possible to specify the username and password authentication in the value of the http_proxy. 

http_proxy=http://username:password@127.0.0.1:8989

Be sure to URL encode both username and password.

Configuring a Global TICS Viewer

A common scenario is to have one TICS Viewer per site within your company. Another scenario is that you have one TICS Viewer with multiple sections. In both cases, if you want to get an overall TQI score over all sections and sites, you need to set up a Global viewer. To configure a global viewer, create a new section in one of your viewers, and specify the option "global": true in the TIOBEPortal.cfg, as follows: 

  "global": {
    "root": "C:/Program Files/TIOBE/TICS/WebServer/Global",
    "tiobewebServlet": "tiobeweb-9.0.1.34491",
    "global": true
  }

Note that the name of the section can be chosen freely and does not need to be global.

Next, you need to point each regular 'local' viewer/section to the newly created global viewer/section. To this end, navigate to the Administration pages of each local viewer, click on the System tab, and enter the global viewer's URL, including the section in the Global Viewer URL input field. After you save the settings, the project data is sent from the local to the global viewer and the projects should appear automatically. The global viewer will be updated after each analysis that is performed in the local viewer. The data for the analyzed project is then sent to the global viewer, together with the set of active projects. This means that projects that are no longer present in the local viewer will be removed from the global viewer only after an analysis is performed for another project in the local viewer.

Compatibility

Configuring a viewer as a global viewer is supported starting from version 9.1. Configuring a viewer as a local viewer is supported starting from version 8.8. It is possible to have local viewers that are of a different version than the global viewer, however, the global viewer's version should (in general) be higher than all of the local viewer's versions.

Enabling the TICS installation script

The User Settings → Install TICS page allows (logged-in) users to access a script that installs the TICS command-line tools on their development machine. A build manager or administrator can also access the script through Administration Pages → Install TICS.

By default, this feature is available in new out-of-the-box installations. However, when you upgrade from an old installation this feature does not automatically become available. To enable this feature, configure the jre and wrapper artifacts in the config.yaml file of the respective TiCS configurations.

In earlier versions you had to enable this feature by creating links.yaml files in the jre and wrapper directories. This is still supported, but it is deprecated in favor of configuring the artifacts in the config.yaml file. You will get a validation warning on any links.yaml file containing these properties.

Alternate installation location

The default location where the TICS binaries will be installed can be overridden by specifying the TICSINSTALLDIR environment variable.

Hostname verification

On Linux based systems, by default, host name verification is applied before artifacts are downloaded. When using self-signed certificates, it might be needed to disable this verification step. This is done by setting TICSHOSTNAMEVERIFICATION to 0 or false.

Customize script

It is possible to provide a modified installation script instead of the built-in one. A service engineer can place files install_tics.ps1 and/or install_tics.sh in the wrapper directory where they will be automatically picked up.

Enabling self-updating wrappers

The TICS wrappers can be retrieved from the TICS Viewer using a self-update process. This makes it easier to roll out certain changes in the TICS wrappers without having to update individual client machines.

Heads up! The self-updating mechanism does not update the wrapper that is initially invoked, but instead invokes a locally downloaded copy. That means that periodically updating the JRE and wrappers on each client machine may still be necessary from time to time even if the wrappers are updated centrally on the TICS Viewer.

In order to enable wrapper updates, configure the wrapper in links.yaml. Refer to Enabling the TICS installation script for details.

Disabling wrapper updates

In some cases, using the locally installed TICS wrapper may be preferable over using the version configured on the TICS Viewer. If this is the case, the updating functionality can be disabled by setting the TICSUPDATEWRAPPER environment variable to 0 or false. The same can be accomplish by setting the update_wrapper property to this value in wrapper.properties and placing this file in %APPDATA%\TICS (on Windows) or ~/.tics (on Unix-like platforms).