References in Tuleap
References allow you to automatically create links between different elements of Tuleap from a simple text.
In concrete terms, when a user writes a reference in a comment, a text field, a Wiki page or a commit message, Tuleap can recognize this reference and automatically transform it into a clickable link to the element concerned.
A reference is usually based on a keyword, followed by an identifier. This makes it easy to link information together, without having to manually copy links.
References can also be used to point to an item in another project, as long as the user has the necessary permissions to access it. If the user does not have consultation rights on the referenced element, it will not be presented to him.
There are two types of references in Tuleap: system references and project references.
System references are defined at the platform level. They are common to all projects and are often linked to a Tuleap service, such as trackers, documents, files or the Wiki. They cannot be changed directly, but they can be turned on or off.
Project references, on the other hand, are specific to a project. They can be created, edited, or deleted by project administrators to meet the specific needs of their team or organization.
If you want more information about artifact references specifically, check out this article.
Create system references.
To access system references from the platform administration, click on "Predefined project references" in the side menu, this will send you directly to system reference management.
To create or modify a system reference, the platform administrator must provide several pieces of information:
The reference keyword allows Tuleap to recognize the text to be automatically transformed into a link. It should be short and self-explanatory, so that users can easily understand what the reference is.
The description briefly explains the purpose of the reference. It is displayed when the user hovers their mouse over a recognized reference.
The nature corresponds to the type of object that the reference will designate in Tuleap (artifact, Build Jenkins, Commit, Ficher, etc.). It's a kind of category that allows Tuleap to know what type of element is concerned by the reference.
The referral link is the address to which the user will be redirected when clicking on the referral. This link can point to a Tuleap page, but also to an external page. This allows, for example, to create references to another tool used by the organization.
It is also possible to use variables in the link. These variables are automatically replaced by the information contained in the reference, such as the short name of the project, the project ID, or the parameters entered by the user. This allows you to create dynamic links, adapted to the text recognized by Tuleap.
