Client Viewer

The client viewer functionality provides you, as a developer, a way to inspect your TICS Client run results in the centrally hosted TICS Viewer, without you having to install the webserver or database components. By instructing your TICS client to upload it's results you unlock the full interactive and visual experience offered by the TICS Viewer, as opposed to the limited text-based reporting offered by TICS Client. Additionally, by uploading the results you can check whether your code changes pass the company-defined quality gate.

Usage

In order to be able to inspect your client results in the viewer, you have to specify the -viewer flag when invoking TICS client. For instance, to check your local code changes in directory /dev/myproject for project MYPROJECT you could run: 

TICS -project MYPROJECT -viewer /dev/myproject
Note that this document is not about the different command-line parameters that you can invoke TICS with. Please see the TICS client documentation for that.
Note that the TICS Client requires a project to upload results to the viewer. If the viewer is unable to link your source files to a project in the case of using -project auto, or you are running with the -noproject option, then the TICS Client will fail.
At the end of the run, TICS will output one or more URLs as an [INFO 3016] message that you can use to inspect the results: 
[INFO 3014] The data for the client run changes of project 'MYPROJECT' can be viewed at the following URLs:

Explorer
========
https://localhost/tiobeweb/TICS/Explorer.html#axes=ClientData(nPFYkTr57NanLcVRIhjiVw),Project(MYPROJECT),Branch(main),Window(-1),File()&x=Delta(tqiCodingStd,Run(-2)),Delta(loc,Run(-2))

Quality gate result
===================
https://localhost/tiobeweb/TICS/Explorer.html#axes=ClientData(nPFYkTr57NanLcVRIhjiVw),Project(MYPROJECT),Branch(main),Window(-1),File()&x=Delta(tqiCodingStd,Run(-2)),Delta(loc,Run(-2))&zqgs=1&

You can (control-)click an URL to open it in your browser if your terminal supports this, otherwise you have to copy and paste the URL.

Note that the URLs returned by TICS contain a so-called client-data token (in this case nPFYkTr57NanLcVRIhjiVw), which is a unique identifier generated specifically for your client run. This ensures that the results are only visible to you and do not interfere with the normal TICSQServer analysis results of MYPROJECT that are visible to everyone. Furthermore, because a token is generated for every TICS run and results are not overwritten, you can also inspect results of earlier runs.

The viewer represents the client-data token in the breadcrumb with the icon. As long as this breadcrumb item is there, you will see client-specific results; if you remove the breadcrumb item, you will see the data that is based on the regular TICSQServer runs again. The client data is combined with the base project data: a run is inserted for the time on which TICS client ran. Any runs in the base project that come after this date will not be visible in the client view. This means that the view referred to by the client-data token is immutable; the metric data will in principle not change when new TICSQServer runs will be done later for the project. Most functionality of the viewer, including most metrics, the chart, treemap, annotated source, and search also works in client views. However, for an overview of the limitations, see below.

To get more information about the client run that you are looking at in the viewer, you can select ' Run Info' option in the client data filter's context menu (only works in the Dashboard and Explorer).

Providing a custom token

As stated, by default a new random client-data token is generated every time you do a TICS run. However, it is also possible to specify a custom token that you then reuse for different TICS runs. Any previous results for that a specific token & project/branch combination will be overwritten. Specifying a custom token can be useful for several reasons:

You can specify a custom token at the command-line with the -cdtoken parameter (only alphanumerical characters and underscores are permitted). For instance, to upload result for project MYPROJECT for a token named 'my_tag' you would execute: 
TICS -project MYPROJECT -viewer -cdtoken my_tag /dev/myproject
The custom token will be prefixed by your system username, to prevent collisions with other developer wanting to use the same tag.

Running TICS with GATE

It is also possible to do a quality gate check via the -calc GATE option. -calc GATE is a metric alias matching all metrics that are part of your quality gates, as follows:

The following command line invocation runs TICS for all metrics covered by your quality gate on your code in /dev/myproject. The metrics run are equal to the metrics in your quality gate. TICS then uses the viewer to determine whether your code passes the quality gate. 

TICS -project MYPROJECT -calc GATE /dev/myproject

When the TICS client determines the metrics to run, it now queries the viewer for which quality gates are applicable for this project, and runs these metrics. Then, at the end, it provides a quality gate to check your files against.

For instance, let's give as an example that your quality gate checks whether any new level 1 Coding Standard and Compiler Warning violations are introduced. In that case, using the option -calc GATE will be equivalent to using the option -calc CODINGSTANDARD,COMPILERWARNING.

Requirements for using GATE are that a viewer needs to be available, a project needs to be used, and a quality gate is set. If not met, TICS will fail with an error message.

Note that running with -calc ALL will skip over fetching the metrics from the enabled quality gates. This is because any metric which would be enabled by running GATE will already be enabled by ALL. For instance, let's assume the following is configured in your SERVER.yaml: 

CODINGSTANDARD:
  ENABLED: 1
COMPILERWARNING:
  ENABLED: 1
FANOUT:
  ENABLED: 1
AVGCYCLOMATICCOMPLEXITY:
  ENABLED: 1
MAXCYCLOMATICCOMPLEXITY:
  ENABLED: 1

In the case you run TICS -calc ALL, it will always run all of these metrics. So it is not necessary to check the metrics of quality gates on top of this. It would not change any of the actions being done by TICS. It also saves performance since then it's superfluous to check the QG.

Client Quality Gate Output

If a quality gate is configured for the project, and you have specified the option -calc GATE, this will output something along the lines of: 

2021-04-07 10:37:18: [INFO 3017] The viewer quality gate(s) for project MYPROJECT have failed.
Failed quality gate details:
  * Gate: Gate 1     Condition: TQI should be at least 60.00%, but actual value is 32.70%
  * Gate: Gate 2     Condition: Coding Standard Violations for levels 1, 2, 3 should be equal to 0 for each file, but was not for 20 files

In order to have the exit status indicate the status of the gate, you can use the -exitsqa parameter: the exit status is 0 if and only if all gates pass. Quality gate conditions that are based on delta metrics (relative conditions) can also be checked, since the client data is combined with the base project data.

Quality gate conditions that are defined on metrics that are not included in the client run will not take part in the the quality gate evaluation. They will not be shown as part of the TICS [INFO 3017] log entry. In the quality gate status dialog in the viewer, they will be shown as skipped, as indicated by a gray flag ().

Configuration

To enable the client viewer functionality, no configuration changes are needed in the TICS Viewer Administration or TICS configuration. As a developer, you just have to specify the parameter -viewer. As a manager, you can automatically have all TICS clients upload their data without the need to specify -viewer by configuring SERVER.yaml => WEBSERVER => CLIENTVIEWER. If for some reason you want TICS client to ignore this setting, you can specify the parameter -noviewer.

Some client viewer parameters can also be configured in TICSConfig.

Remarks and limitations

Remarks

Limitations