The Mutation Web API is the public programming interface for making configuration changes to the TICS Viewer. If you are looking for a way to query data from the TICS Viewer, please refer to the Query Web API documentation.
The mutation APIs require you to make HTTP POST requests, as opposed to the GET requests as done by the Query Web APIs. Currently there is only one mutation API available, the "Label Rule mutation API".
Labels are key:value pairs attached to projects, directories and files that allow you to organize those items into semantic structures.
For instance, you might want to organize projects by the business unit or department they belong to.
When you assign the label Department:X to projects that belong to X and Department:Y to projects that belong to Y,
you can get the TQI or other metric score per department by choosing 'group by Department' in the breadcrumb.
Keys and the associated labels can be nested to model hierarchical structures. In this way you can, for instance, model that each business unit falls under a department.
Another way to use labels is to assign meaningful names to structures inside projects. You might want to identify one or more directories as belonging to the same component and give that component a meaningful name. Those directories do not necessarily have to be in the same project. This feature is a more powerful and flexible alternative to the legacy ORG view feature:
Because of these advantages, the ORG view feature is considered deprecated and will be removed in a future release. Note that assigning labels to groups of projects is also a more powerful alternative than assigning a Project Group, and should be preferred.
Currently, the only way to create labels is using the Label Rule API described here. There is only a limited UI available in Administration Pages → Labels.
In order to assign labels to projects, you have to create label rules. A label rule consists of a label and a scope: all projects that fall in the scope will receive the given label.
Use the following URL:
POST
The API endpoint expects POST data in JSON format and has one optional parameter.
| Parameter | Type | Description |
|---|---|---|
|
POST data
(required) |
JSON |
The API end point expects a data entity in JSON format. The JSON object at top-level contains the following fields:
|
|
tag
(optional) |
string | Allows you to partially update the labels in a group. Normally when you submit configuration for a label group, all existing keys, labels, and rules for that group are removed. When you specify a tag, only labels and associated rules that have previously been submitted for this group and tag are removed. This can be used for instance when you want to generate labels per project in a TICS post analysis step for the respective project. In that case you might want to use the name of the project as a tag. |
The following JSON data shows a small example configuration:
{
group: {
name: "My Organization"
},
labelKeys: [
{key: "Department"},
{key: "Business Unit", icon: "tiobe-icon-Organization2", parentKey: "Department"}
],
labels: [
{key: "Department", value: "Development", fullName: "Development Department"},
{key: "Department", value: "Research", fullName: "Research Department"},
{key: "Business Unit", value: "BS", fullName: "Business Solutions", parentValue: "Development"},
{key: "Business Unit", value: "CS", fullName: "Consultancy Solutions", parentValue: "Development"},
{key: "Business Unit", value: "AR", fullName: "Aerospace Research", parentValue: "Research"},
{key: "Business Unit", value: "TS", fullName: "Top Secret Research", parentValue: "Research"}
],
rules: [
{key: "Business Unit", value: "BS", scope: "Project(Set(X,Y))"},
{key: "Business Unit", value: "CS", scope: "Site(Eindhoven)"},
{key: "Business Unit", value: "CS", scope: "Project(Z),Sub(foo/bar)"},
{key: "Business Unit", value: "AR", scope: "ProjectProperty(sectionUuid,511c68d0-00f7-4514-9219-c1433e085a6a),ProjectGroup(Aerospace)"},
{key: "Business Unit", value: "TS", scope: "ProjectProperty(sectionUuid,511c68d0-00f7-4514-9219-c1433e085a6a),ProjectGroup(Secret)"},
]
}
This data configures two keys: "Department" and "Business Unit".
Department "Development" is configured to have two business units "BS" and "CS",
while department "Research" has business units "AR" and "TS",
as indicated by the parentValue fields in labels.
The rules field specifies which files fall in which business units.
Through the parent relations this automatically assigns labels for key "Department" to the projects as well.
The example configuration shows some (not necessarily realistic) examples of scopes that you could use.
Business Unit BS is responsible for two projects: X and Y.
The Set() syntax is used here to specify that we want to filter on more than two projects
(this is called a compound filter).
Business Unit CS is responsible for all projects located in site Eindhoven.
Another rule for the same label expresses that it is also responsible for the directory foo/bar in project Z.
Department Research is responsible for all projects coming from the viewer section with UUID 511c68d0-00f7-4514-9219-c1433e085a6a.
The filter ProjectProperty(sectionUuid,...) is only useful for
global TICS viewers and is not used for normal viewers.
Business Unit AR is responsible for projects in project group Aerospace,
whereas business unit TS is responsible for projects in project group Secret.
This example places the labels in a group named "My Organization".
Since we did not configure the listIndex field,
the label keys will be placed at the top of the breadcrumb's group-by dropdown menu.
Since we did not specify autoSelect: true inside the group,
the viewer will not automatically select Department to group by when you enter the TQI Dashboard frontpage.
Any HTTP client or HTTP library can be used to do a HTTP POST request to configure the viewer through the API.
We will give an example using the curl command.
Create a user named automationuser with password secret and store the POST data in a file named payload.json.
curl -X POST --data "@payload.json" -H "Content-Type:application/json;charset=UTF-8" --user automationuser:secret http(s)://hostname:port/tiobeweb/section/api/public/v1/LabelRules
It is important to specify JSON as the content type header and to make sure that the file payload.json is in UTF8 encoding,
otherwise the API will not be able to parse the POST data.
If multiple teams in your organization need to define rules independently of each other for the same label group,
and each team is going to do its own API call,
you might want to use the tag query parameter so that the different calls do not interfere.
In this case, each team will do the following call, but use different values for %TEAMNAME%:
curl -X POST --data "@payload.json" -H "Content-Type:application/json;charset=UTF-8" --user automationuser:secret http(s)://hostname:port/tiobeweb/section/api/public/v1/LabelRules?tag=%TEAMNAME%
If for some reason you change the tag that you are using, the rules for the old tag remain. In order to delete the labels and rules associated the old tag, you should use the Administration → Label Tags panel to delete the old tag. This will not remove any Label Groups that you might have created. In order to remove those, you should use the Administration → Label Groups panel.
Accessing a mutation API requires authentication.
You should provide the credentials using HTTP basic access authentication.
The authorized user should have the right permission to access Mutation Web APIs.
By default, only the "Automation Script" role (introduced in 2019.3) has the accessMutationApi permission,
and no user has that role by default, so you need to add authorization rules to give your user that permission.
You can do this in the in the Administration Pages.
If you intend to make an automated script that periodically updates labels,
you are advised to create a "headless" user for this purpose that has the "Automation Script" role.