--- title: "Advanced Custom Fields for Orangescrum Self-Hosted" description: "Conditional, calculated, and project scoped custom fields for Orangescrum self-hosted. Formulas, subtask rollups, and fields required before a status change." canonical: https://www.orangescrum.com/self-hosted/plugins/advanced-custom-fields --- # Advanced Custom Fields for Orangescrum Self-Hosted > For the complete documentation index, see [llms.txt](https://www.orangescrum.com/llms.txt). 1. [Home](/) 2. › 3. [Self-Hosted](/self-hosted) 4. › 5. [Plugins](/self-hosted/plugins) 6. › 7. Advanced Custom Fields # Advanced Custom Fields by [Orangescrum](/) · Productivity Self-HostedVerifiedField Logic Adds conditional, calculated, and project scoped behaviour to Orangescrum custom fields. A field can be shown only when another field holds a certain value, compute itself from a formula over other fields, roll up a total from its subtasks, or become mandatory before a task moves to a chosen status. Advanced fields stay ordinary custom fields underneath, so the forms, reports, and exports you already use keep working. Installs Available Active deployments Support Vendor Supported Priority response Trust Self-Hosted Your infra, your data $499/year Per company • Add-on to any Self-Hosted plan [Buy & See All Plans](/self-hosted/pricing#addons)[Talk to Sales](/contact-sales) - Show a field only when another field matches a rule - Calculated fields from a sandboxed formula - Subtask rollups: sum, minimum, maximum, average, count - Require a field before a chosen status change - Scope a field to selected projects or the whole company - Minimum role to view and minimum role to edit, per field - Set one field across many tasks in a single action - Export and import the whole field library as JSON Pairs with [Self-Hosted Core ($1,500/yr) or Business ($2,250/yr)](/self-hosted/pricing) [Overview](#overview)[Features](#features)[About](#about)[Install](#install)[FAQ](#faq) ## Screenshots Field editor with a conditional display rule Formula builder with live preview and referenced fields Task form showing only the fields that apply ## Key Features ### Conditional Display A field appears only when another field matches the rule you set. The form stays short and people only see the questions that apply to the work in front of them. ### Conditionally Required Require a field before a task moves to a chosen status, and only when a condition holds. The check runs on the server, so it cannot be skipped by a different screen. ### Nine Comparison Operators Rules compare with equals, not equals, greater than, less than, greater or equal, less or equal, contains, is empty, and is set. ### Calculated Fields A field can work out its own value from a formula over other fields, so nobody types a number the system could derive. ### Sandboxed Formula Engine Formulas are tokenised and parsed into a small syntax tree, never evaluated as PHP. Only a fixed function set is allowed: IF, ROUND, MIN, MAX, SUM, ABS, CONCAT, DATEDIFF, and TODAY. ### Circular Reference Guard A formula that would depend on itself, directly or through another field, is refused when you save it rather than failing later on a task. ### Live Formula Preview Try an expression against sample values before you commit to it, and see exactly which fields it references. ### Subtask Rollups Aggregate a child field across subtasks with sum, minimum, maximum, average, or count, so a parent item shows the real total instead of a guess. ### Project Scoping A field is either global or attached to chosen projects. Teams stop scrolling past fields that belong to somebody else's work. ### Per Field Role Limits Set a minimum role to view a field and a minimum role to edit it, so commercial or sensitive values stay with the people who need them. ### Field Groups Give fields a group name and the task form reads as sections rather than one long list. ### Bulk Set Values Pick a field, pick many tasks, set the value once. Calculated and rollup fields are refused, because their value is derived rather than entered. ### Value History Every change to a field's value on a task is recorded with the old value, the new value, the person, and the time, and the recent history is shown on the field. ### Reorder, Duplicate, Deactivate Drag fields into the order you want, duplicate one as the starting point for the next, and deactivate a field without losing the values already captured. ### Export and Import Export the field library as JSON and import it into another install. Formulas, conditions, rollup sources, and project scoping are remapped on the way in. ### Built on Core Fields Advanced fields are ordinary rows in the core custom field table with a plugin owned overlay, so the existing render, save, and reporting path is reused rather than replaced. ## About this plugin ### Why Advanced Custom Fields for Orangescrum? Custom fields solve one problem and create another. Every team adds the fields it needs, the form grows, and after a while people scroll past most of it. This add-on gives fields behaviour: a field can hide until it matters, work out its own value, pull a total from the work underneath it, or refuse to let a task move on until it is filled. ### Fields that appear when they matter A rule ties one field to another. Show the escalation reason only when severity is critical. Show the vendor name only when the cost type is external. Nine operators cover equals, not equals, the four comparisons, contains, is empty, and is set. The show rules also run in the browser, so the form reacts as somebody types rather than after a save. ### Values the system can work out A calculated field carries a formula over other fields. Expressions are parsed into a small syntax tree and walked, never handed to PHP, and only a fixed function list is available: IF, ROUND, MIN, MAX, SUM, ABS, CONCAT, DATEDIFF, and TODAY. A formula that would depend on itself is refused at save time, and you can test an expression against sample values before committing to it. ### Rollups from the work underneath A rollup field aggregates a chosen child field across subtasks with sum, minimum, maximum, average, or count. A parent item can therefore show real effort, real cost, or a real count without anybody maintaining it by hand. Calculated and rollup fields are read only, including in the bulk editor, because their value is derived. ### Scope, order, and who can see what Each field is global or attached to chosen projects. Each field can carry a minimum role to view and a minimum role to edit. Fields can be grouped into sections, reordered by dragging, duplicated, and deactivated without losing the values already captured. Every change to a value is recorded with the before, the after, the person, and the time. ### Custom fields in Cloud, advanced behaviour in Self-Hosted Custom fields themselves are part of Orangescrum, and there is a feature overview at /custom-fields. The conditional, calculated, rollup, and project scoping behaviour described on this page is a self-hosted add-on. The advanced attributes live in plugin owned tables, so the core custom field schema is untouched and removing the add-on leaves your fields and their values in place. ### What's included - Conditional display rules bound to another field's value - Conditionally required rules enforced on a status change - Nine comparison operators: equals, not equals, greater than, less than, greater or equal, less or equal, contains, is empty, is set - Client side show and hide so the form reacts while it is being filled - Calculated fields with a sandboxed expression evaluator - Fixed function set: IF, ROUND, MIN, MAX, SUM, ABS, CONCAT, DATEDIFF, TODAY - Expression validation, referenced field resolution, and a live sample preview - Circular dependency detection at save time - Automatic recalculation when a referenced field changes - Subtask rollups with sum, minimum, maximum, average, and count - Global fields or fields scoped to selected projects - Minimum role to view and minimum role to edit, per field - Field groups so the task form reads as sections - Drag to reorder, duplicate, and deactivate without data loss - Bulk set a field value across many selected tasks - Calculated and rollup fields blocked from manual and bulk editing - Field usage count as a guard before a type change - Value change history per field per task with old value, new value, user, and time - JSON export and import of the whole field library with cross reference remapping - Works for task fields and project fields - Role permission seeding through the core roles screen - Multi-tenant company-scoped data isolation ### Compatibility Requires the Orangescrum Self-Hosted edition running PHP 8.2+, CakePHP 4.6+, and PostgreSQL 16. The plugin folder is AdvancedCustomFields and it is gated by the ADVANCED\_CUSTOM\_FIELDS\_ENABLED flag in config/constants.php. Advanced attributes are stored in plugin owned acf\_ tables and the fields themselves remain rows in the core custom field table, so the core schema is unchanged. Multi-tenant aware, so every field rule, scope, computed dependency, and value history row is company-scoped. ## Installation A self-hosted install takes a few minutes. Buy the add-on, drop the plugin into your `plugins/` directory, run the migrations, and you're live. 1. 1 ### Buy the add-on Purchase the Advanced Custom Fields add-on from /self-hosted/pricing at $499/year per company, payable annually. 2. 2 ### Drop the plugin into your install Copy the AdvancedCustomFields/ folder into plugins/ on your self-hosted Orangescrum server. 3. 3 ### Enable the feature flag and register the plugin Add \`define('ADVANCED\_CUSTOM\_FIELDS\_ENABLED', true);\` to config/constants.php and register \`AdvancedCustomFields\` in src/Application.php with \`routes => true, bootstrap => true\`. 4. 4 ### Run the database migrations Run \`bin/cake migrations migrate --plugin AdvancedCustomFields\` to create the field meta, project scope, condition, computed dependency, permission, and value audit tables. 5. 5 ### Seed the role permissions Run \`bin/cake migrations seed --plugin AdvancedCustomFields\` so the module and its role defaults appear on the core roles screen. 6. 6 ### Add your first conditional field Open Settings, then Custom Fields. Create a field, pick the field it depends on, choose an operator and a value, and decide whether the rule shows the field or requires it. 7. 7 ### Add a calculated field and a rollup Write an expression, validate it, and preview the result against sample values. Then add a rollup field and choose the child field and the function to aggregate it with. ## Frequently Asked Questions ### What can a formula actually do? ▾ It can reference other custom fields on the same item, do arithmetic and string joining, compare values, and call a fixed set of functions: IF, ROUND, MIN, MAX, SUM, ABS, CONCAT, DATEDIFF, and TODAY. The expression is tokenised and parsed into a syntax tree, then walked. It is never passed to PHP, and nothing from the request or the environment enters the evaluation. ### Can I add my own function to the formula language? ▾ No. The function list is fixed and closed on purpose, and anything not on it is a parse error rather than a runtime surprise. There are also hard limits on expression length, token count, and nesting depth. If you need logic beyond that, calculate it outside and write the result in through the API. ### Can somebody type over a calculated value? ▾ No. Calculated and rollup fields are derived, so they are refused in the normal editor and in the bulk value setter. If you want a value people can override, use an ordinary field. ### How does a required field get enforced? ▾ A require rule can be tied to a specific target status or to any status change, and it can be further gated by a condition on another field. The check runs in the save path on the server, so a task cannot reach that status with the field empty, whichever screen the move was made from. ### Can a field be limited to certain projects? ▾ Yes. A field is either global or attached to the projects you choose. Fields scoped away from a project are dropped from that project's task forms, so people are not asked questions that belong to another team. ### Does installing this change the custom fields we already have? ▾ No. Advanced fields are ordinary rows in the core custom field table with an overlay stored in plugin owned tables. Existing fields carry on exactly as before until you give one a rule, a formula, or a scope. Removing the add-on removes the advanced behaviour, not the fields or their values. ### Can I move a field library between installs? ▾ Yes. Export the library as JSON and import it elsewhere. The import runs in two passes so that formulas, condition dependencies, rollup sources, and project scoping are remapped to the identifiers on the target install. Fields whose name already exists are skipped but still mapped, so references resolve.