References names, or “ref names”, are unique internal identifiers used throughout Uncountable to represent elements within the platform such as fields, definitions, templates, conditions, and triggers.
When creating a new element within the platform, users are typically prompted to enter:
- Name: The global/display name shown in the UI to end users (e.g.
"Batch Size") - Reference: A stable identifier used in internal logic (e.g.
batchSize)
Once a ref name has been assigned, it becomes available for use in value spec throughout the platform. Using the batchSize field as an example, once created, the ref name can be used to pull the Batch Size value of a Lab Request.
To learn more about value spec, refer to:
Assigning Ref Names
Ref names must be a single, continuous string with no spaces. If a space is included, the platform will display a validation error and prevent the entity from being saved. To improve readability, users can use underscores (_) or camelCase formatting. For example, the “Batch Size” could have a ref name of batchSize or batch_size.
Generally, ref names are assigned within the creation modal when creating a new field, definition, template, etc. One exception to this is triggers. When creating a trigger, ref names are assigned retroactively within the Advanced tab of that trigger.
Editing Ref Names
Once a reference name has been assigned, it cannot be edited directly on the original entity’s configuration page. Additionally, not all entities in the Uncountable platform support reference name editing after creation. This restriction exists to protect the integrity of workflows, formulas, and logic throughout the platform.
For example, fields and definitions cannot have their reference names edited once created. This is because changing a ref name does not automatically propagate the change across all the places it is used. If not updated manually in every location, an outdated reference will cause errors, and value spec logic will fail to operate or pull the correct data.
However, some entity types do support ref name editing, including projects, ingredients, ingredient attributes, condition parameters, naming schemes, etc.
How to Edit a Reference Name
To edit a reference name for a supported entity:
Access the Control Panel. Scroll to find the Edit Reference Names button, located just beneath the Example File Manager table. Alternatively, use Command + K and search for "Edit reference names" to navigate there quickly.
On the Edit Reference Names page:
- Select the entity type from the dropdown menu.
- Locate the specific entity from the table.
- Click the pencil icon next to the reference name.
- Type your new ref name and press Enter.
- Click the blue “Commit” button at the top of the page to save your changes.
Note: After editing a reference name, be sure to manually update any references to that name across the platform to ensure continued functionality.
Common Ref Name Use Cases
Ref names are used across many platform features. Some common scenarios include:
- Referencing fields or entities when configuring trigger actions or action buttons
- Creating custom naming schemes
- Creating label templates
- Creating notification templates
Best Practices
To work effectively with ref names, follow these guidelines:
- Choose concise, descriptive names that reflect the purpose of the field or component.
- Be mindful of case sensitivity to avoid confusion or logic errors.
- Avoid unnecessary changes. If you do need to update a ref name, verify and update all affected logic (e.g., formulas, templates, triggers).