Javascript Guidelines
Developer guide · JavaScript
Find the right place for a calculation, test it with real data, and follow the detailed guide for that NIM feature.
Javascript is used at your own risk. Validate scripts with non-production data and accounts before making them available to production workflows.
NIM uses JavaScript in several configuration areas. The available data, the result NIM expects, and the effect of a change depend on where the code runs. Start with the use case below; the linked articles provide the complete settings and procedures.
Runtime guidelinesDirect link to Runtime guidelines
NIM supports ECMAScript 2020 (ECMA-262) for this JavaScript. Write code as though it runs in strict mode: declare variables with const or let, use === for comparisons, and do not rely on assigning undeclared variables or on a browser's global this value. Check every method you use against the supported language version; newer features may not run.
The runtime does not load external libraries or Node.js modules such as crypto, and console.log is unavailable. Use NIM's documented functions and the feature's test or preview controls to inspect results. Do not assume browser APIs or a package manager are present.
Choose where the code belongsDirect link to Choose where the code belongs
| What you need | Use | Where to go next |
|---|---|---|
| A calculated value reused wherever a system table is used | System JavaScript column. It uses fields from its own table. | Create and test a system column |
| A calculation needed by one filter, including values joined from other tables | Filter JavaScript column. It uses columns available in that filter. | Add a filter column |
| A calculation over grouped filter results | Group By output column with the script type. | Group and aggregate results |
| A reusable calculated value or shared helper class | JavaScript configuration variable. Return the type expected by its consumer. | Create and manage variables |
| A calculated value, display condition, or validation rule inside an App | App JavaScript variable or item property. | Use the Designer and set item properties |
| A button action on a REST connector's Connection screen | Connection item action in the connector definition. | Design the Connection screen |
An App script is a separate extension point. It runs inside a NIM App to carry out custom logic, such as calling a filter or coordinating actions. It is not a system column, filter column, or configuration variable.
Write a reliable calculated columnDirect link to Write a reliable calculated column
System and filter columns use NIM's tableName['columnName'] notation. In the column editor, use the insertion control to add a reference, then Test Script against representative data before saving. For a system column, collect the system afterward and inspect the result; for a filter column, preview the filter's Data tab.
const firstName = employees['first_name'] ?? '';
const lastName = employees['last_name'] ?? '';
return `${firstName} ${lastName}`.trim();
Return a predictable value when an input is blank. In a filter with an optional joined table, first check whether its table object exists before reading a field. System columns can reference their own table; filter columns can reference the tables included in their filter. See custom system columns and filter calculations for more patterns.
Handle errors deliberatelyDirect link to Handle errors deliberately
Use a fallback for an expected condition, such as a missing optional value or an empty lookup result. For an invalid input or broken configuration, fail with a useful error instead of silently returning a plausible value. Catch an error only when you can recover from it or add context; never include credentials or sensitive record values in error text. Test both the success path and the failure path before using the calculation in a job or App.
Read configured values and collected recordsDirect link to Read configured values and collected records
Use variableGetValue('variable_name') in a custom system or filter column when the calculation needs a centrally managed NIM variable. Test the column again after changing that variable.
Share helper functions through a global variableDirect link to Share helper functions through a global variable
A global JavaScript variable can return a helper class that multiple script columns reuse. Create the variable in Configuration → Variables, place the class definition in its JavaScript code, and give it a stable name such as T4ELib. The NIM Library HelperFunctions example shows a class returned from a global variable and called from a filter script column:
let lib = variableGetValue('T4ELib');
return lib.cleanName("My Test string here");
The example returns the result of cleanName. Test the global variable and every helper you plan to call, then test each script column that uses it. A change to a shared helper can affect every calculation that calls it.
For a lookup against collected Vault data, use the helper that matches the result you need:
| Need | Helper |
|---|---|
| Check a primary key | vaultObjectExists |
| Check a configured reference key | vaultObjectExistsByRef |
| Read values from matching records | vaultObjectFind |
Vault helpers read collected data, so collect the target system first and verify its keys. Prefer an existence check when a true/false result is enough. For a repeatable relationship, consider a relation before adding a Vault lookup to each row. See the Vault helper reference for arguments and examples.
Keep calculations efficientDirect link to Keep calculations efficient
Each JavaScript column adds work when NIM calculates its result, and App variables can add work as the App evaluates them. Many script columns or variables can slow collection, filters, or App rendering. Code quality matters too: repeated Vault lookups, unnecessary loops, and repeated conversions can make even a small number of scripts expensive.
Use the fewest calculations needed for the result, reuse a well-tested helper for shared logic, and prefer a relation or built-in filter operation for repeatable data joins and aggregates. Test with representative data volume, not only one record, and review performance after adding or changing shared code.
Use JavaScript in Apps carefullyDirect link to Use JavaScript in Apps carefully
The Designer supports JavaScript variables. Some general properties and item-specific properties also evaluate JavaScript for display, input, or validation. Check the expected result for each property; for example, a hide or disable condition must evaluate to true to take effect.
Check syntax and the expected return value before saving code in an App. Invalid JavaScript can break the App and may prevent it from appearing in the Designer. Test the affected forms and actions in Run mode with safe data after each change.
Check a change before relying on itDirect link to Check a change before relying on it
Test
Verify
Review
For the exact editing controls and feature-specific limits, use the linked article for the place where your code runs.