Semantic options
To make sense of the information stored in artifacts, setting up semantics is essential.
For example, it is necessary to indicate when a task should be considered open or, on the contrary, completed. Status fields are often used to represent the status of an item (task, bug, release, feature, etc.).
These fields record a value, but Tuleap cannot automatically deduce their meaning. Therefore, the role and scope of each value must be explicitly defined so that the platform can interpret them correctly.
In a task manager with "To Do," "In Progress," and "Done" statuses, a task can be considered open if its status is "To Do" or "In Progress." This distinction is important because many tools rely on the notion of an "open" element.
The "My Artifacts" widget displays only the open artifacts assigned to the user. The Agile Dashboard, Kanban or Test Management also use this information to feed their backlog and organize the elements in progress.
The configuration of the semantics is done in the "Semantics" section of the Tracker administration.
The semantic options concern:
The "Title"
Title semantics allows you to define which field in the tracker will contain the title of the artifact, this is the field that should summarize the artifact. Depending on the nature of the tracker, the field (string or text) that is most relevant will be used.
Careful!
A wrong choice makes it harder to navigate and search.
The title will be displayed on the artifact's edit page, next to its ID, and in the My Artifacts widget.
The "Description"
Description semantics relies on a text-like field to describe the artifact.
It makes it possible to clearly identify where the main descriptive information is located and it guarantees a consistent reading of the artifact, regardless of the tracker.
The "Status"
This semantics allows you to configure the notion of an open artifact. From a selected list field (usually the status), you have to choose the values of this field which implies that the artifact is "open".
Why it matters:
Tuleap uses this information to filter the artifacts displayed.
Widgets and tools only work on open artifacts.
Without this semantics, the notions of advancement and follow-up lose their meaning.
The "Done" state
This semantics is used to configure the definition of Fini for an artifact type. It uses the same field as state semantics, but with different values.
Why it matters:
It is used to calculate burnup and velocity graphs.
It allows you to hide completed artifacts in certain tools.
It serves as a reference for integrations, including Git and GitLab.
Practical information
Without this semantics, progress metrics cannot be calculated correctly.
The "Contributor"
Contributor semantics are used to indicate who is responsible for an artifact.
It is based on a user list field.
It allows you to clearly assign the work.
It powers the My Artifacts widget.
It is used by notifications and some permission rules.
The "Timeframe"
Timeframe semantics defines the period of time that an artifact is active. It is used by the Taskboard, Planning, Roadmap, and charts.
It allows artifacts to be positioned over time and makes consistent milestone planning possible.
Practical information
The time range can be set from fields or inherited from another tracker, ensuring consistency between parents and children.
The "Progress"
Progression semantics is used to calculate the actual progress of an artifact. It transforms raw data into visual indicators and allows progress to be tracked in the Roadmap.
This calculation can be done in two ways: either based on total effort and remaining effort, or based on the status of child artifacts, by comparing the number of completed items to the total number of linked items.
The "Tooltip"
Tooltip semantics are used to define the information displayed when hovering over an artifact with the cursor. This avoids opening each artifact to obtain key information and improves readability and navigation.
Practical information
All the fields of the tracker can be displayed on the tooltip but in practice we will select 3 or 4 important ones that allow you to display the useful information at a glance.
The "Cards"
Card semantics define the fields visible on Backlog, Kanban, and Cardwall. You can also define a field that is used for the background color of the cards.
Only list or radio button fields with static values can be used.
Each value must be associated with a named color or be transparent.
A reason is automatically added for users who have enabled accessibility mode.
A preview of the maps is displayed to visualize the final rendering.
Warning
If you use the same field for status and background color, the color doesn't update automatically when dragging and dropping in Kanban.
To see the correct color, open the artifact or reload the page.
The "Initial Effort"
Initial effort semantics represents the work estimate for an artifact.
It allows you to compare estimated effort and capacity and is used in release and sprint planning.
