$originalValue

The first value of the current property, in other words, the value which was retrieved on the initial load of the layout.

$oldValue

Previous value, i.e. the value of the current property before the last change. Equals to $value if no direct changes were made.

$value

The current value of the calculated property. If any other property uses this calculated field it will refer exactly to this value.

The rest of the $ vocabulary

Beyond the three value variables above, the same function scope exposes:

Sources and $sourceState

Sources live in the widget's Sources array. If your expression reads from one, check $sourceState before trusting the data — it may not have loaded yet:

return $sourceState.$value === 2; // LOADED = 2

Types and Default Values

The property's declared Type sets its default value. Return the wrong shape and the field just reads empty rather than throwing:

Currency is a shape, not a number. Always return an object with CC (currency code) and Value (numeric amount):

return { CC: $user.currency, Value: number.$value };

Arrays change in place. Arrays are DataModelArray instances — when you return a new array, the engine calls .set() on the existing instance rather than replacing the reference, so mutating $value with push/splice also works and fires notifications:

// Build an array of n blanks:
var arr = [];
for (var c = 0; c < bCount.$value; c++) {
    arr.push({});
}
return arr;

param.$value

The current value of the parameter.

param.$oldValue

Value of the parameter before the current change. Equals to param.$value if no direct changes were made.

param.$hasChanges

Identifies if the parameter value has been changed in the curing iteration, i.e. recalculated due to the changes in the watched property. Is handy in case there is more than one watchable variable and you need to recalculate the value of the calculated property only if a specific property has changed. 

The Most Common Mistake, and param.$setValue()

A parameter is always an object, never a raw value — you cannot reach across the Data Model with a path string inside an expression, only through a declared parameter. One of the most common mistakes is comparing that object directly instead of reading .$value off it:

return messageType.$value === 1;   // ✓ correct — read .$value
return messageType === 1;          // ✗ compares the object itself — always false

A common pattern is simply forwarding a parameter's value, for example return objectIds.$value; or return id.$value;.

A parameter also exposes param.$setValue(v) to write to another property — this is the mechanism behind the PDRConfigurationProjectClassChange example under Helpers below.

Localization Parameters

A parameter with __type: 2 is a localized string, not a Data Model path. Its path is an $LS$[guid] reference, and the engine treats it as a plain string constant:

{ "varName": "corporate", "path": "$LS$[9587ead5-…]",
  "name": "localStr1", "__type": 2, "value": "Local:{Corporate}" }

// then, in the expression:
return $format(corporate);
return $format("{code} ({name})");         // fills from sibling parameters
return $format(message, name.$value);      // positional {0}, {1} …

$forceValueChanged()

Call this function to force all dependent data model properties to be recalculated.

The method is used to run Service Operation when a certain condition is met. Note that the Service Operation should be configured to run on data update.

For example, open Administration application → User Interface → Control Descriptors → click OAuth2 Authentication Control → run Change Layout action to open the Layout Designer. The Data Model has the following redirectUrl property that uses $forceValueChanged() method:

When $inactive is set to false (==active) it triggers the $forceValueChanged() method, which triggers running the entire Service Operation, in this example it’s GetOAuth2AuthorizationUrl.

According to the Source Execution Mode in the Service Configuration, if any of the properties has changed, the Service Operation runs:

In order not to run the Service Operation every time when any of the properties has changed, but only when all necessary properties are available the following logic takes place.

When the Control Descriptor is added to the Dialog, it has all necessary properties as listed in the Widget Attributes. When the properties that are necessary for the $inactive are filled out, its value becomes false:

var a = "Hello";
var b = "World";
return $format("{0} {1}!", a, b); // "Hello World!"

Calculated property exception: { Path, Expression, Error }

Maximum relcalculations exeeded: Context.Foo.
  Last call triggered by: SubmitData.data.Bar

Warning!. Data model property `<path>` may contain child properties
  which could be ignored during data update

[data-model] $oldValue is a read-only snapshot of the previous state
  — .set() does not affect $value.