Content
Updated by Marc Alcobé 16 days ago
**Acceptance criteria:**
* A calculated value is added as a new project attribute
* A calculated value has these details:
* Name
* Section
* Formula
* For all projects
* Admin-only
* there is no special **permission** for reading or writing calculated values, but be aware of the existing permissions for project attributes
* Usage of calculated values is hidden behind a **feature flag**
* The formulas can include the following attributes from that project:
* Integer
* Float
* List factors (Project attribute of type list with values) <mention class="mention" data-id="50111" data-type="work_package" data-text="###50111">###50111</mention>
* Other calculated values
* Mathematical operators: `+`, `-`, `*`, `/`, `%` (modulo and percent), `(` and `)`
* Constants (numbers that can be typed into the formula)
* **Order of operations:** Automatic application of the mathematical rule where multiplication and division are performed before addition and subtraction, unless parentheses dictate otherwise
* In order to trigger the selection of the attributes in the field, the user can use the command "/" as implemented in the Automatically generated subjects.
* The command triggers a dropdown to open with sections for:
* Mathematical operators
* Custom fields of type integer or float
* List factors
* Calculated values
* The project attribute can be displayed in
* the project overview
* the project list
* Enterprise token is needed in order to
* add new calculated values in the administration
* display calculated values on the project overview page and in the project list
* list calculated values in the API
* an enterprise indication is shown as a trailing icon on the add attribute dropdown entry
* once the user clicks on the entry, a full screen page with a [Large Enterprise Banner](https://qa.openproject-edge.com/lookbook/inspect/OpenProject/EnterpriseEdition/banner/large) as [designed here](https://www.figma.com/design/omPTDfbYbO6nYPcOZMl79v/Project-prioritization?node-id=1855-15631&t=YODpKZg1Y9jo1rha-4) _\[video asset in progress\]_
* Error handling
* In calculations, there is error handling for **circular references**.
* In case the user includes text that is **not an integer or a float,** the field will display an inline error: "Only numeric values, project factors, calculated values and mathematical operators are allowed"
* In case the mathematical operation fails (e.g. because of a **division by zero error**), the field will display an inline error.
* In case a custom field is not set, deactivated, or otherwise inaccessible for calculations, the field will display an inline error.
* **\[Technical question\]** consider if and how to persist error information, e.g.
* define error codes for different kinds of errors? (mathematical error vs issue with a custom field used within the formula)
* write an error code into custom\_field\_values
* or: add an extra column to custom\_field\_values called error(\_code)
* or: introduce a dedicated table. That way, we could even reference error-causing custom\_fields via foreign key
* After saving it, the formula is calculated and the result of the calculated value is stored in the database
* Lots of read access from multiple places.
* Difficulty to calculate a calculated value if it in turn includes a calculated value again.
* Updating a modal showing a calculated value while its factors are being inserted by the user. E.g. a factored list being calculated of 2 custom fields. All are displayed in the same section of the overview page. -> the user opens the modal. inputs first one value, then the second. Then the calculated value is ideally displayed right away (even before the users clicks on `save`).
* **\[Technical question\]** Is the whole side menu of the overview page displaying the custom fields updated as one or in sections? Relevant for when the calculated value is not in the same section as the values factored in.
* Calculated values are **displayed in the activity**
* The activity messages from float custom field can be reused
* Only show the change from a value not being calculated to the value being calculated (and vice versa). Or if the calculated value changes.
* e.g. "the value changed from 5 to <error>"
* Open questions
* In which cases is the recalculation triggered? Cases affecting the value:
* A list value of a factor is inserted
* A list value of a factor is deleted
* A list value of a factor is changed
* A calculated value being a factor is recalculated (changed)
* The calculation formula is changed
* **\[open question\]** Is a specific cause mentioned in the project activity?
* maybe a general info text: "the formula has been changed"
* we could also display the new formula as a string
* A custom field being used as a factor is disabled in the project
* A calculated value is activated in a project/in multiple projects at the same time.
* Some of these are bulk actions -> think about using a background job. Cancel a running job if the calculation changes again before the running job completed?
* To make the formula discoverable for non-admins: display a hovercard on the calculated value that displays the formula? If there are errors, color code it to indicate the values already present (blue) and the ones missing (red).
* On the project overview page (attributes section)
* Also within the modal when editing attributes (when you hover over the read-only input field for the calculated value)
* Within the project list
<br>
* A calculated value is added as a new project attribute
* A calculated value has these details:
* Name
* Section
* Formula
* For all projects
* Admin-only
* there is no special **permission** for reading or writing calculated values, but be aware of the existing permissions for project attributes
* Usage of calculated values is hidden behind a **feature flag**
* The formulas can include the following attributes from that project:
* Integer
* Float
* List factors (Project attribute of type list with values) <mention class="mention" data-id="50111" data-type="work_package" data-text="###50111">###50111</mention>
* Other calculated values
* Mathematical operators: `+`, `-`, `*`, `/`, `%` (modulo and percent), `(` and `)`
* Constants (numbers that can be typed into the formula)
* **Order of operations:** Automatic application of the mathematical rule where multiplication and division are performed before addition and subtraction, unless parentheses dictate otherwise
* In order to trigger the selection of the attributes in the field, the user can use the command "/" as implemented in the Automatically generated subjects.
* The command triggers a dropdown to open with sections for:
* Mathematical operators
* Custom fields of type integer or float
* List factors
* Calculated values
* The project attribute can be displayed in
* the project overview
* the project list
* Enterprise token is needed in order to
* add new calculated values in the administration
* display calculated values on the project overview page and in the project list
* list calculated values in the API
* an enterprise indication is shown as a trailing icon on the add attribute dropdown entry
* once the user clicks on the entry, a full screen page with a [Large Enterprise Banner](https://qa.openproject-edge.com/lookbook/inspect/OpenProject/EnterpriseEdition/banner/large) as [designed here](https://www.figma.com/design/omPTDfbYbO6nYPcOZMl79v/Project-prioritization?node-id=1855-15631&t=YODpKZg1Y9jo1rha-4) _\[video asset in progress\]_
* In calculations, there is error handling for **circular references**.
* In case the user includes text that is **not an integer or a float,** the field will display an inline error: "Only numeric values, project factors, calculated values and mathematical operators are allowed"
* In case the mathematical operation fails (e.g. because of a **division by zero error**), the field will display an inline error.
* In case a custom field is not set, deactivated, or otherwise inaccessible for calculations, the field will display an inline error.
* **\[Technical question\]** consider if and how to persist error information, e.g.
* define error codes for different kinds of errors? (mathematical error vs issue with a custom field used within the formula)
* write an error code into custom\_field\_values
* or: add an extra column to custom\_field\_values called error(\_code)
* or: introduce a dedicated table. That way, we could even reference error-causing custom\_fields via foreign key
* After saving it, the formula is calculated and the result of the calculated value is stored in the database
* Lots of read access from multiple places.
* Difficulty to calculate a calculated value if it in turn includes a calculated value again.
* Updating a modal showing a calculated value while its factors are being inserted by the user. E.g. a factored list being calculated of 2 custom fields. All are displayed in the same section of the overview page. -> the user opens the modal. inputs first one value, then the second. Then the calculated value is ideally displayed right away (even before the users clicks on `save`).
* **\[Technical question\]** Is the whole side menu of the overview page displaying the custom fields updated as one or in sections? Relevant for when the calculated value is not in the same section as the values factored in.
* Calculated values are **displayed in the activity**
* The activity messages from float custom field can be reused
* Only show the change from a value not being calculated to the value being calculated (and vice versa). Or if the calculated value changes.
* e.g. "the value changed from 5 to <error>"
* Open questions
* In which cases is the recalculation triggered? Cases affecting the value:
* A list value of a factor is inserted
* A list value of a factor is deleted
* A list value of a factor is changed
* A calculated value being a factor is recalculated (changed)
* The calculation formula is changed
* **\[open question\]** Is a specific cause mentioned in the project activity?
* maybe a general info text: "the formula has been changed"
* we could also display the new formula as a string
* A custom field being used as a factor is disabled in the project
* A calculated value is activated in a project/in multiple projects at the same time.
* Some of these are bulk actions -> think about using a background job. Cancel a running job if the calculation changes again before the running job completed?
* To make the formula discoverable for non-admins: display a hovercard on the calculated value that displays the formula? If there are errors, color code it to indicate the values already present (blue) and the ones missing (red).
* On the project overview page (attributes section)
* Also within the modal when editing attributes (when you hover over the read-only input field for the calculated value)
* Within the project list
<br>