Semantics

As trackers can be fully customized, you may need a way to define what is the title of your artifacts, when you consider an artifact to be open or close, or the field used to define the contributor (or assignee) of an artifact. This feature is provided by the admin section “Semantics”.

Most of the trackers you will use already defined a semantic. This is the case for instance for all tracker templates.

To define or update a semantic field, select the pencil icon next to the semantic property. Semantic admin section lets you define the following semantic properties:

Title

The title of an artifact is a field that sum up the best the artifact. For instance, it can be the field summary for a bug tracker, the field name for a contact tracker, or the field I want to for a Scrum user story tracker.

You can choose any text field as the title of your artifacts.

This semantic information is used in the edition page of an existing artifact, next to the ID. It is also displayed in My artifacts widget.

Status

The status of an artifact is a field that describes the stage of the artifact. If you set a semantic for status, please define the values that mean open for this field.

The most commom case is a field Status with the value open for open values. All other values will be considered as closed values. But you may want to define any other semantic. You can choose any selectbox field (single or multi) as the status of your artifacts.

This semantic information is used in My artifacts widget (this widget displays only open artifacts that belongs to you).

Done

The done semantic is used for burnup and velocity chart computation. It can also be used by the GitLab integration and the Git integration.

Velocity (Backlog)

Attention

This module is part of Tuleap Entreprise. It might not be available on your installation of Tuleap.

How to add velocity chart in a release:: 1 - You should have a tracker hierarchy between Release and Sprint

Example of release hierarchy

2 - You should have a velocity semantic at release and child level

An error is displayed when children tracker does not have the velocity semantic

3 - You should have at least one backlog tracker with done and initial effort semantic.
I some tracker don’t have both semantic, its value won’t be taken in account during computation.

A warning is displayed if tracker does not have all needed semantic

Once computation is done, you can manually override the computed value by entering a new one.

Contributor / Assignee

The contributor of an artifact (or assignee) is a field that is bound to users. The contributor(s) of an artifact are the person(s) who are responsible for the work needed to complete the artifact. For instance, it can be the field assigned_to for a bug tracker, the field owner for a task tracker.

You can choose any user list field as the contributor of your trackers.

This semantic information is used to define specific permissions on a tracker (for instance restrict tracker access to a group of assignee people).

Cards semantic

The cards semantic allows you to add the fields which will be visible in cardwall, Backlog Planning and Kanban.

The background color semantic allows you to choose the field which will be used to determine the background color of a card. Only selectbox and radio buttons bound to static values can be used to determine background color. It also can only be used when each value has a “named” color. In addition to the background color, a special pattern is associated to the selected color. It will be shown for users who have enabled the Accessibility mode user preference (see Preferences). Patterns have been defined only for “named” colors but not for all possible colors. Therefore there is a limitation for the fields that can be used as background color. All their values must have either “transparent” color or a “named” color. (see Edit the field of a tracker)

The card preview will show you examples of how your cards will be displayed in cardwall.

Attention

While you can select the same field as Status semantic for the background color, you should know that this case has a limitation in Kanban. When drag and dropping cards between columns in Kanban (which affects the Status field’s value), the Background color will not be updated on-the-fly. To see the updated background color for the card, you should either change status via the artifact modal or refresh the page.

Initial Effort (Backlog)

The Initial Effort semantic is special in that it only exists if the project has the Backlog enabled. In the agile context, it is supposed to represent the estimated effort for a given task, story, sprint, release…

In order to use this semantic you need to have a numeric field in your tracker that corresponds to this initial effort notion.

The initial effort is used in the Backlog content and planning views.

Timeframe

The semantic Timeframe represents the period on which the artifact is considered “active”.

It is used by various services across Tuleap (Taskboard, Planning, Roadmap, Burndown and Burnup graphs, Project milestones, etc.).

Timeframes based on fields

It can be configured in two ways:

Start date + end date
Start date + a number of days

When set to “Start date + a number of days”, the end date is automatically computed, excluding Saturdays and Sundays.

For instance, if an artifact has a start date starting on Monday and has a 6 days period of activity, then it will be supposed to end next Monday.

Timeframes inherited from another tracker

When set to “Inherited from another tracker”, the timeframe of artifacts will be the same as artifacts linking them from the target tracker.

For instance, let’s consider that the User Story tracker is configured to inherit its timeframes from the Sprints tracker:

A “Sprints” artifact has a timeframe starting on Monday and ending on Tuesday
It links a “User Story” artifact
The timeframe of the “User Story” artifact will start on Monday and end on Tuesday

Note

To be able to define an inherited semantic timeframe, the following requirements have to be matched:

The current tracker and the target tracker must both have artifact links fields
The target tracker must have a semantic timeframe based on tracker fields

Progress

The semantic Progress is used to compute the progression of the ongoing work on artifacts.

It is used in the Roadmap widget at the moment. In the longer term, we plan to use it in the Backlog as well.

Two computation methods are available: based on effort and based on artifact links count.

Effort based computation

To configure it, you will be asked to provide:

a Total effort field (type: integer, float, computed) representing the total effort needed to complete the work.
a Remaining effort field (type: integer, float, computed) representing the remaining effort to complete the work.

The progress of artifacts will be computed by dividing their remaining efforts by their total efforts.

Artifact links count based computation

The progress of artifacts will be computed by dividing the number of artifacts linked using the type Child by the number of closed children artifacts.

Only direct children are taken into account. It means that children of the children will be ignored during the computation.