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

The Label Rule API can be used to create Label Rules.

URL: /api/public/v1/LabelRule
Since version: 2019.3

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:

Labels have meaningful key names and distinct icons, whereas items in the ORG view always have the key 'Subsystem' and use a directory icon.
Labels can span multiple projects, whereas an ORG view is specific for a project and requires you to first drill down in a project. As such, you cannot (easily) compare ORG view items from different projects.
Labels allow you to group directly on lower levels in the label hierarchy to compare all labels for a certain key. For instance, when you define Components and Subcomponents, you can directly group by Subcomponent without first having to select a Component. In an ORG view, you can only compare sibling nodes directly.
You can define multiple label hierarchies. For instance, you might want to define one label hierarchy to impose a structure that models the software architecture in terms of components, modules, etc, whereas another label hierarchy might impose an organizational structure in terms of teams, managers, etc.

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 the Administration Pages.

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

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=true): boolean value indicate whether the breadcrumb is allowed to automatically select keys in this group when drilling down. If set to false, 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 → 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. 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.

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=true): boolean value indicate whether the breadcrumb is allowed to automatically select keys in this group when drilling down. If set to false, 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 → 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. 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",
    autoSelect: false
  },
  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 parent relations in labelDetails. 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. Because it is placed at the top, this would result in the viewer automatically selecting Department to group by when you enter the TQI Dashboard frontpage. You might want this behavior, but for the purpose of this example we override this behavior by configuring autoSelect: false.

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