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.
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
[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
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).
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:
-cdtokenparameter (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/myprojectThe custom token will be prefixed by your system username, to prevent collisions with other developer wanting to use the same tag.
If a quality gate is configured for the project,
you can specify the option
-qg so that TICS will also output the failing conditions of the gate (if any):
TICS -project MYPROJECT -viewer -qg /dev/myproject
which 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
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 ().
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
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
Some client viewer parameters can also be configured in TICSConfig.
SERVER.yaml => WEBSERVER => PORTALURL). The TICS Viewer should be reachable from the machine that runs TICS client.
PROJECTS.yaml). You cannot upload results for source code that does not have a base project. Also, this base project must have at least one run.