Mutation Web API

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

Label Rule API

Labels are key:value pairs attached to projects that allow you to organize those projects into semantic structures. For instance, you might want to organize projects by the business unit or department they belong to. For example, 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 also be nested to model hierarchical structures. In this way you can, for instance, model that each business unit falls under a department.

Currently, the only way to configure labels is using the Label Rule API described here; there is no UI to configure 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 has two input parameters:

Parameter Type Required Description
tag string yes

All rules and labels created by the API call will be associated with this tag. The next time an API call is done for the same tag, all rules and labels with this tag are deleted first.

POST data JSON yes

The API end point expects a data entity in JSON format. The JSON object at top-level contains the following fields:

  • labelKeys: array of JSON objects, each one specifying details about a key. The ordering of the array determines the order in which the keys are shown in the breadcrumb group-by dropdown menu. Once set, the ordering of the keys is remembered between subsequent calls to the Label Rule API, but you can change it later through the Administration Pages → Label Keys panel.

    Fields of each labelKey object in the array:

    • key: name of the key. The name of the key will be displayed in the user interface.
    • parentKey (optional): the name of the key in which it is nested. The referenced parent key must occur in the array before the current key. This field must be omitted for top-level keys.
    • icon (optional): a CSS class of the icon to use for this key. You can use one of the following predefined classes: tiobe-icon-Organization (the default), tiobe-icon-Organization2 , tiobe-icon-Team .
  • labels: array of JSON objects, each one specifying details about a label.

    Fields of each label object in the array:

    • key: the key of the label. The key must have been defined in the labelKeys array.
    • value: the value of the label, which will be displayed in the user interface. Must be unique among all labels for given key.
    • fullName (optional): the full (non-abbreviated) name that should be shown in e.g. the tooltip in the metric table
    • parentValue: the value of the parent label. This field is mandatory when the label's key has a parent key. The referenced parent label must occur in the array before the current label.
  • rules: array of JSON objects, each one specifying a label rule. The order of the rules is important only when a project is covered by multiple scopes for the same key; the project will be assigned the label of the first rule that applies to it. Note that if a project is not covered by a rule for a certain key, the viewer will show it using label value -.

    Fields of each rule object in the array:

    • key/value: the label to which this rule applies
    • scope (mandatory): a filter expression denoting the projects to which the label should be assigned. Unlike the query API, here you can only use filters that are project-transcending. Typically you want to use one or more of the following filters:
      • Project(Set(...)) to denote a specific project or set of projects. Example: use Project(Set(foo,bar)) to assign a label to projects foo and bar.
      • ProjectGroup(group) to denote to all projects in a project group.
      • Site(location) to denote to all projects in a site.
      • ProjectProperty(sectionUuid,UUID) to denote all projects coming from a particular TICS Viewer (and viewer section) instance. This is useful to use in global viewers when you want to assign the same label to all projects coming from a particular local viewer. Each viewer section is uniquely identified by an UUID that is generated one first start-up of the section. To determine the UUID, choose the metric 'Section UUID' in the Project Properties category in the metric picker of a global viewer.

The following shows example POST data that 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 parent relations in labelDetails. The rules field assigns business units to projects. Through the parent relations this automatically assigns labels for key "Department" to the projects as well.

The example shows some (not necessarily realistic) examples of scopes that you could use. Business Unit BS is responsible for two projects: X and Y. Business Unit CS is responsible for all projects located in site Eindhoven. Department Research is responsible for all projects coming from the viewer section with UUID 511c68d0-00f7-4514-9219-c1433e085a6a. Business Unit AR is responsible for projects in project group Aerospace, whereas business unit TS is responsible for projects in project group Secret.

{
  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: "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)"},
  ]
}

Any HTTP client (library) can be used to access 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?tag=organization_script

It is important to specify JSON as the content type header and to make sure that the payload.json file is in UTF8 encoding, otherwise the API will not be able to parse the POST data.

Authentication

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.