Skip to main content
Units are simple, reusable measurement labels you attach to form elements and indicators. They make numbers meaningful to users (for example, showing “kWh” next to an energy field) and keep terminology consistent across an organization.

​
At a Glance

  • What it is: A label with a name (e.g., “kWh”, “tCO2e”). No symbols, categories, or conversions are modeled in the database.
  • Scope: Public (available to all organizations) or Organization (private to one org).
  • Used in: Form elements and Indicators; displayed in forms, indicator lists, and dashboards via indicators.
  • Management: Add/Delete/Merge in Customization → Units. Admins can create public units.

​
What Units Are (and Aren’t)

  • A Unit stores only a name and its scope (public vs. organization). There is no built‑in concept of type/category, precision, conversion factors, or validation between compatible/incompatible units.
  • There is currently no automatic unit conversion in calculations or dashboards. Units are for display and consistency, not computation.

​
Scopes

  • Public units: Available to all organizations. Only system administrators can create or merge public units.
  • Organization units: Available only within the current organization. Owners can create, delete, and merge these units.

​
Where Units Appear

  • Form elements: A numeric (and some other) fields can reference a unit. The form renderer shows the unit label (e.g., “kWh”) next to the input. Stored as FormElement.unitId.
  • Indicators: Indicators can reference a unit for display. Stored as Indicator.unitId. Dashboards render indicator values with the indicator’s unit name.

​
Managing Units

  • List: Customization → Units displays both public and organization units.
  • Create: Add a new unit name. Admins may mark it as Public (visible to all orgs).
  • Delete: Deletes the unit; existing references are set to null (they won’t retain the old label). Prefer merge when cleaning up duplicates.
  • Merge: Select 2+ units and provide a new name; references in the current org are updated to the new unit and old units are deleted. Merging public units is admin‑only. Note that references to deleted public units in other organizations will be set to null.

​
Cross‑Org Form Duplication

When duplicating a form to another organization, a “Unit Mapping” step lets admins map each source unit to an existing target unit or create a new one in the target org.

​
API Quick Reference

  • units.list (viewer): List public + current organization units.
  • units.listForOrganization (admin + membership): List public + a specific organization’s units.
  • units.create (owner): Create an org unit; isCommon=true requires system admin.
  • units.delete (owner): Delete org units; admins can delete public units.
  • units.merge (owner): Merge 2+ units into a new one; respects scope; admins required for public.
REST equivalents are exposed via OpenAPI metadata:
  • GET /units, POST /units, DELETE /units/{id}, POST /units/merge.

​
Limitations & Notes

  • No built‑in conversions, categories, or precision metadata.
  • Deleting a unit sets any unitId references to null (no automatic reassign or safety check).
  • Name uniqueness is not enforced at the database level; avoid duplicate names within a scope for clarity.

​
Best Practices

  • Use standard names consistently (e.g., “kWh”, “tCO2e”, “m³”).
  • Prefer merging duplicates over deleting in‑use units.
  • Use public units for common standards; use organization units for custom/internal labels.
  • Review unit mapping when duplicating forms across organizations.

​
Examples

Form element with a unit
  • Field: “Monthly Electricity Consumption”
  • Unit: “kWh” (organization or public)
  • Display: Number input with “kWh” label on the right.
Indicator with a unit
  • Indicator: “Total Scope 2 Emissions”
  • Unit: “tCO2e”
  • Dashboard: Cards/charts will show values with the indicator’s unit label.