Add a global constant

Updated 17 Oct 2026

A threshold, a scale, a mode the tenant can change without a developer is a global constant, not a C# literal. Files live in Constants/. In code you read GlobalConstants.<Group>.<Name> (or Get<T> / SetAsync).

Note

IConstantResolver is a different subsystem: per-dictionary compile-time constants. Runtime named values go through the generated GlobalConstants class, which forwards to IGlobalConstantManager. See Runtime.

How to#

1. The group — Constants/_groups.json, kind: "ConstantGroups". One item per group (name, caption, its own metaId). Common already ships Measurement for AmountScale / QuantityScale / WeightScale. Reuse a group before you add another.

2. The constant — Constants/<Name>.json, kind: "GlobalConstant". Point groupMetaId at the group. Set constantType and the matching storage (numberValue / stringValue / …). Names are unique system-wide.

Types the catalog accepts: Integer, Decimal, String, Text, Html, DateTime, Date, Flag, DictionaryRecordId, RecordsIdList. Unset reads as null (int?, decimal?, bool?, …).

3. Read it from a script. Prefer the typed property. Get<T> is for a name you only have as a string. SetAsync writes and invalidates the cache — the next read anywhere sees the new value.

var scale = GlobalConstants.Measurement.AmountScale ?? 2;
var depth = GlobalConstants.Get<int?>("PriceTypeChainMaxDepth") ?? 20;
await GlobalConstants.SetAsync("AmountScale", 3);

An unknown name throws ApplicationException ("Constant not found") — the legacy contract, not a silent null.

A Task script (a job) does not get the generated class. Use GetService<IGlobalConstantManager>().Get<T>("Name") there — Create a job.

4. Bump modelVersion in the same change.

Warning

A rate or a scale hardcoded in a service will not match the tenant that changed the constant, and it cannot be fixed without a developer. If the same number is about to appear in a second script, it is already a constant.

Changing constantType flushes the other storage columns. Writes of the definition (create / update / delete) must go through IGlobalConstantManager or the process serves a stale cache until restart.

What's not there yet#

Object constants (values owned by one dictionary or document) are a separate catalog. This page is the system-wide store. A Task script will not see GlobalConstants.X until the generator covers that host.

Where next#

Was this page helpful?