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, 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:

  • group: JSON object specifying details about the label group that you want to provide data for. For instance, you might want to provide labels that describe the organizational structure in terms of business units, teams, etc, or you might to provide labels that describe the functional structure in terms of blocks, components, etc. Each API call provides data for one group; if you want to define multiple groups, you need to perform a distinct API call for each group.

    Fields of the group object:

    • name: name of the group. All existing data that has been earlier posted for this name will be deleted. This name is currently not displayed in the UI.
    • listIndex (optional): integer between [1..1,000] or [10,000..20,000] indicating the position of the grouper in the breadcrumb's dropdown menu. An index of 1 places the group's keys at the top of the menu, higher numbers place the group lower. This is useful when you want to determine the mutual positions of the groups when you have defined multiple label groups. It can also be used to place the group's keys at the bottom of the dropdown menu instead of at the top; the built-in groupers (Project, Subsystem, File, etc) have an index in the range (1,000..10,000). To place your group at the bottom, assign an index in the range [10,000..20,000].
    • autoSelect (optional, default=false): boolean value indicate whether the breadcrumb is allowed to automatically select keys in this group when drilling down. If set to false (the default), the user has to deliberately select the key to group by it.

  • labelKeys: array of JSON objects, each one specifying details about a key. The ordering of the array should reflect the natural hierarchical order of the keys from top to bottom. 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 → Labels settings.

    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. Key names should be unique, even over different label groups.
    • 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 , tiobe-icon-Component , tiobe-icon-Cube .

  • 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. Each rule assigns the specified label to all files in the specified scope. Multiple rules can be specified for the same label to specify multiple scopes. Items that are not covered by a rule will receive the label -. The order of the rules is typically not important when the scopes are disjunct. When a file is covered by multiple scopes for the same label, the label of the first applicable rule will be assigned.

    Fields of each rule object in the array:

    • key/value: the label to which this rule applies
    • scope (mandatory): a filter expression denoting the project or directory to which the label should be assigned. In order to assign labels to one or more projects, use one 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.

      In order to assign a label to a directory inside a project, use a Project filter followed by a Subsystem filter. For instance, use Project(X),Sub(foo/bar) to denote directory foo/bar in project X. See the documentation on filter expressions for more information about the syntax.

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.

Examples

Organizational Structure

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.

Posting the data

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.

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.