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. 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.

Authentication & Authorization

Authorization allows you to control which users have access to which projects and functionalities of the viewer. Users authenticate themselves using a username and password that they enter in the authentication dialog that is accessible through the padlock icon in the upper-right corner. The viewer supports two authentication services: built-in and LDAP. The built-in authentication service requires you to add each username and password manually. The LDAP authentication service is preferred because it is more scalable. If you already have an LDAP directory service running in your network, users can use the same credentials as they are used to. Users are automatically added when they first log in and can be authenticated using one of the configured LDAP queries. Even when using LDAP, you still might want to create some additional user accounts manually. One example is to create a functional account for a script that accesses the Web API. 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 the LDAP query that caused you to no longer have the proper permissions.

To use the built-in authentication service, create a user with a password on the Users page. In the user creation dialog, you can immediately choose the role that the user should receive. 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 on the Roles page.

To assign roles to users, you need to create Authorization Rules. By default, a rule is created 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 one or more users and a "project scope". The users can be an explicit set of users that you select from a list, or an implicit set of users that are accepted by an LDAP query. 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.

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 Miscellaneous page.

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

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 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.

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 Administration Pages → Source Code Retrieval. 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 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 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. 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 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/TICS",
    "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 Settings 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 is automatically updated each time you add or remove a project or perform an analysis in a 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.