docs/system-admin-guide/projects/project-attributes/README.md
Project attributes are custom fields shown on the Project home page. They allow you to communicate key information relevant to a project.
[!NOTE] Prior to version 14.0, these were called "project custom fields" and described under the Custom fields page. Starting with 14.0, they are referred to as project attributes.
This page describes how instance administrators can create, order, and group project attributes, and assign them to projects. For instructions on editing project attribute values within a project, see the Project home page.
To view all existing project attributes, navigate to Administration settings → Projects → Project attributes.
Project attributes are organized into sections. Each attribute row contains:
An empty section will display a button to add a project attribute.
At least one section must exist before project attributes can be created.
To add a section:
Name the section and save it.
Each section includes a location selector defining where it appears on the Project home page:
Use the More menu on the right side of the section header to rename, delete, or reorder a section.
[!TIP] A section can only be deleted if it contains no attributes.
Attributes can be dragged between sections. Entire sections can be reordered via drag and drop. Use the drag and drop handle to the left of the section name.
[!TIP] Attributes always appear in the section they are assigned to across all projects.
To create a new project attribute, click on the + Add button in the top right corner, select Project attribute and select the project attribute format from the list of available options.
[!IMPORTANT] You cannot change the project attribute format once the project attribute is created.
You can pick from multiple project attribute formats. Depending on the chosen format, you can define additional parameters, such as minimum and maximum width, default value or regular expressions for validation.
This is an example of new project attribute with a format List.
Name: This is the name that will be visible in the Project home page, if the custom field is activated on that project.
Section: If there are sections, you can pick where this new project attribute should appear. Learn about sections for more information.
Allow multi-select: Allows the user to assign multiple values to this custom field.
Add a comment text field: Allows the user to add a comment related to the project attribute when selecting the value in the project overview.
Possible values: Add, define, arrange or remove possible values for this project attribute.
Required: Checking this enables this project attribute and makes it required for all projects. It cannot be deactivated at a project level. Existing projects will not require a value when being updated.
[!IMPORTANT]
Project attributes of type Boolean and Calculated value can NOT be set to be required.
For all projects: Mark the attribute as available in all existing and new projects.
Admin-only: If you enable this, the project attribute will only be visible to administrators. All other users will not see it, even if it is activated in a project.
Searchable: Checking this makes this project attribute (and its value) available as a filter in project lists.
Once you create a project attribute, you can enable it for specific projects and define help text.
There are multiple format options for project attributes in OpenProject. You can select one of the following formats:
[feature: custom_field_hierarchies ]
Project attributes of the Hierarchy type function in the same way as work package custom fields of the Hierarchy type. For detailed information, please refer to Work package custom fields documentation.
[feature: weighted_item_lists ]
Weighted item list project attributes function similarly to the Hierarchy type. They let you define a structured list of items arranged in a hierarchy for users to choose from.
To set up a project attribute of the Weighted item list type, follow the same procedure as when adding a standard project attribute and select the Weighted item list option.
Adding and modifying items within a weighted item list works in the same way as for a hierarchy project attribute.
In contrast to Hierarchy, items in a weighted item list do not include a Short value but instead require a Weight.
This numeric value is required and can be used in calculations — for example, within a project attribute of type Calculated value
[feature: calculated_values ]
Calculated values enable automatic computations based on formulas using numeric and boolean project attributes, including scores from Weighted item lists or even other calculated values. The computed result is displayed directly on the project overview and in the project list. It automatically updates whenever one of its source attributes (e.g., Benefit or Effort in the example below) is changed. This allows teams to calculate project scores and prioritize consistently across the portfolio.
To set up a project attribute of the Calculated value type, follow the same procedure as when adding a standard project attribute and select the Calculated value option. Define the name, section it will appear in and the calculation formula.
In the example below, a project attribute called Initiative score (calculated) is determined by this formula: (Strategic fit * 0.4) + (User benefit * 0.4) - (Effort * 0.2).
Formulas support the literals, operators, functions and keywords listed below, and can reference other project attributes — integer, float, boolean, weighted item list scores and other calculated values.
Number and boolean literals are supported. Numbers can be either integer (42) or decimal (3.14, .1). Boolean literals are uppercase (TRUE and FALSE).
Operators with higher precedence evaluate before those with lower. Operators with same precedence are evaluated left to right. Precedence can be changed using parentheses:
5 + 3 * 2 => 11(5 + 3) * 2 => 16| Operator | Description | Precedence | Examples |
|---|---|---|---|
+ | Addition | 10 | 1 + 2 => 3 |
- | Subtraction | 10 | 5 - 2 => 3 |
- | Unary negation | 40 | -x negates x |
* | Multiplication | 20 | 4 * 3 => 12 |
/ | Division | 20 | 9 / 3 => 3.0 |
10 / 4 => 2.5 | |||
% | Modulo | 20 | 7 % 3 => 1 |
% | Percentage | 30 | 7 + 1% => 7.01 |
^ | Exponentiation | 30 | 9 ^ 0.5 => 3.0 |
2 ^ 3 ^ 2 => 64 |
| Name | Description | Examples |
|---|---|---|
ABS | Absolute value | ABS(-5) => 5 |
ABS(5) => 5 | ||
AVG | Arithmetic mean of arguments | AVG(1, 2) => 1.5 |
MAX | Largest argument | MAX(3, 1, 2) => 3 |
MIN | Smallest argument | MIN(3, 1, 2) => 1 |
ROUND | Round to 0 or specified number of decimals | ROUND(1.5) => 2 |
ROUND(-1.5) => -2 | ||
ROUND(3.14159, 3) => 3.142 | ||
ROUNDDOWN | Round down to 0 or specified number of decimals | ROUNDDOWN(1.5) => 1 |
ROUNDDOWN(-1.5) => -2 | ||
ROUNDDOWN(0.9999, 3) => 0.999 | ||
ROUNDUP | Round up to 0 or specified number of decimals | ROUNDUP(1.5) => 2 |
ROUNDUP(-1.5) => -1 | ||
ROUNDUP(1.0001, 3) => 1.001 | ||
SUM | Sum of arguments | SUM(1, 2, 3) => 6 |
| Operator | Description | Precedence | Examples |
|---|---|---|---|
< | Less than | 5 | 1 < 2 => TRUE |
2 < 2 => FALSE | |||
> | Greater than | 5 | 2 > 1 => TRUE |
2 > 2 => FALSE | |||
<= | Less than or equal | 5 | 2 <= 2 => TRUE |
3 <= 2 => FALSE | |||
>= | Greater than or equal | 5 | 2 >= 2 => TRUE |
2 >= 3 => FALSE | |||
<> or != | Not equal | 5 | 1 != 2 => TRUE |
1 != 1 => FALSE | |||
= or == | Equal | 5 | 2 = 2 => TRUE |
2 = 1 => FALSE |
AND and OR are available both as operators and functions. XOR and NOT are functions only. All arguments must be logical.
When used as operators, AND and OR have the same lowest precedence 0, lower than any other operator.
| Name | Description | Examples |
|---|---|---|
AND or && | True when all operands/arguments are TRUE | TRUE AND TRUE AND FALSE => FALSE |
AND(TRUE, TRUE, TRUE) => TRUE | ||
NOT | Logical negation | NOT(TRUE) => FALSE |
NOT(FALSE) => TRUE | ||
OR or || | True when any operand/argument is TRUE | FALSE OR FALSE OR TRUE => TRUE |
OR(FALSE, FALSE, FALSE) => FALSE | ||
XOR | True when an odd number of arguments are TRUE | XOR(TRUE, FALSE, FALSE) => TRUE |
XOR(TRUE, FALSE, TRUE) => FALSE | ||
XOR(TRUE, TRUE, TRUE) => TRUE |
IF(condition, when_true, when_false) returns one of two branches based on a boolean condition:
IF(1 > 2, 123, 456) => 456
SWITCH(value, candidate1, result1, candidate2, result2, ..., default) compares value against each candidate and returns the matching result, or the trailing default unless it is omitted:
SWITCH(200, 100, 1, 200, 2, 3) => 2
SWITCH(4, 1, TRUE, 2, FALSE, TRUE) => TRUE
SWITCH(300, 100, 1, 200, 2) => invalid
CASE provides similar behaviour using keyword form. Invalid if no branch matches and there is no ELSE:
CASE 200 WHEN 100 THEN 1 WHEN 200 THEN 2 ELSE 3 END => 2
CASE 4 WHEN 1 THEN TRUE WHEN 2 THEN FALSE ELSE TRUE END => TRUE
CASE 300 WHEN 100 THEN 1 WHEN 200 THEN 2 END => invalid
You can edit existing attributes under Administration settings → Projects → Project attributes.
Click on the More icon to the right of each project attribute to edit, re-order or delete a project attribute.
[!CAUTION] Deleting a project attribute will delete it and the corresponding values for it from all projects.
You can also use the drag handles to the left of each project attribute to drag and drop it to a new position.
[!NOTE] Project admins can chose to enable or disable a project attribute from their project, but they cannot change the order. The order set in this page is the order in which they will appear in all projects.
Under Administration settings → Projects → Project attributes select the More menu and select Edit or simply clicking on the name of the project attribute. This will open a detailed view of the project attribute you selected.
The Details tab will allow you to edit the name, section and visibility, and enable a comment text field.
The Projects tab will show a list of all the projects this project attributes was activated in.
You can remove a project attribute from a specific project by selecting the More menu at the end of the line and clicking the Remove from project option.
To add this project attribute to a specific project click the +Add projects button. A modal will appear allowing you to search for projects to add this project attribute into. Please note that the projects in which the project attribute is already activated will be shown disabled in that selection. You can include subprojects.
[!NOTE] It is not possible to add or remove a project attribute, if a project attribute is set to be required.
To define field caption and help text click on a project attribute and navigate to Help text tab. Here you can define the following:
[!IMPORTANT] Any text and images you add here will be publicly visible to all logged in users.