JavaScript scripting now supports string-based enum handling (v.26.2, breaking change)

When working with domain objects in JavaScript scripts, enum values have historically been exposed as JavaScript numbers.

As a result, comparisons and assignments involving enum properties had to use their underlying numeric values.

For example:

if (subject.TransactionObj.MovementType !== 1) {
  ...
}

Using enum names as strings did not work as expected:

if (subject.TransactionObj.MovementType !== 'Receipt') {
   // always false
}

This behavior was consistent, but unintuitive and error-prone, especially for more complex scripts.

What has changed?

Starting with v.26.2, ERP.net introduces string-based enum handling in JavaScript scripting.

By default, enum values are now exposed to JavaScript as their name strings, instead of their numeric values.

This means the following expressions now work as expected:

if (subject.TransactionObj.MovementType !== 'Receipt') {
 ...
}

The string 'Receipt' is interpreted as the enum value MovementType.Receipt.

This change makes scripts easier to read, write, and maintain, and removes the need to remember or hardcode numeric enum values.

Why is this considered a breaking change?

There are scenarios where existing scripts rely on numeric enum comparisons, such as:

if (subject.TransactionObj.MovementType === 1) {
  ...
}

or

// document released status
if (subject.State === 30) {
  ...
}

After this change, such expressions may no longer behave as expected if the script assumes numeric enum values.

How can I revert to the old behavior?

To preserve backward compatibility, a configuration option is introduced:

/Scripting/UseNumericEnumConversionMode

When the value of this key is:

• "0" (False) or the key is not defined
  Enum values are exposed as strings (default behavior).
• "1" (True)
  Enum values are exposed as their underlying numeric values, restoring the previous behavior.

This allows you to opt out of the new behavior and continue using numeric enum comparisons if needed.

Do I need to take any action?

No manual action is required if your scripts already use string-based enum comparisons, or if you want to adopt the new behavior.

If you have existing scripts that rely on numeric enum values, it is strongly recommended to migrate those scripts to use string-based enum comparisons.

The configuration option can be enabled temporarily to revert to the previous behavior during the migration period.

---

More information is available in our official documentation:

https://docs.erp.net/tech/advanced/scripting/index.html
https://docs.erp.net/tech/reference/config-options-reference.html#75-scriptingusenumericenumconversionmode