Use JavaScript columns in filters

Filter calculations

Create a calculated value from the data already available in a filter—including data joined from multiple tables or systems.

A JavaScript filter column adds a calculated column to one filter's result. Use it to format, combine, or derive data needed only by that filter.

Create a filter-specific calculationDirect link to Create a filter-specific calculation

Decide where the calculation belongsDirect link to Decide where the calculation belongs

Put the column on a…	When it is the right choice
System table	The calculation is reused across NIM and needs values from one table only.
Filter	The calculation is used by one filter or needs columns that the filter combines from multiple tables or systems.

A system-table column can be reused throughout NIM, but it can reference columns only from its own table. A filter column can reference every column present in that filter's result, but it is not available to other filters.

Add the calculationDirect link to Add the calculation

Edit the filter and open Columns Specification.
Select Add Script Column and give the column a descriptive name.
Write the calculation in Code. Use the green-arrow control to insert a column reference at the cursor. References use tableName['columnName'] notation.
Select Test Script and inspect Script Result Value with representative filter data. Correct errors before selecting Save and Exit.

Use NIM's column notation when referencing filter data:

return `${employees['first_name']} ${employees['last_name']}`;

Step 1 of 3

Write resilient calculationsDirect link to Write resilient calculations

Source values may be blank, and an optional relation may not supply a joined record. Handle both conditions so one incomplete record does not break the calculation.

Use a fallback for blank valuesDirect link to Use a fallback for blank values

The nullish-coalescing operator (??) uses a fallback only when the source value is null or undefined.

return (Users['description'] ?? 'No description').toLowerCase();

Check optional joined dataDirect link to Check optional joined data

For an any-none relation, first verify that the joined table object exists, then provide a fallback for its field value.

const location = typeof ConfigEmployeeLocation !== 'undefined'
  ? (ConfigEmployeeLocation['LocationName'] ?? 'Unassigned')
  : 'Unassigned';

return location;

Prefer template literals for textDirect link to Prefer template literals for text

Template literals make text transformations easier to read than string concatenation.

return `Student @ ${Students['BldName']} | ${Students['Grade']}.`;

tip

Use try/catch only for genuinely exceptional conditions. Explicit fallbacks for missing tables and values make scripts easier to test and maintain.

Use NIM query helpersDirect link to Use NIM query helpers

JavaScript columns can use Vault queries to check records in the Vault and variable queries to read NIM variables.

When the calculation is broadly reusable and needs only one source table, create a JavaScript system column instead.

Edit or remove a JavaScript filter columnDirect link to Edit or remove a JavaScript filter column

Open Columns Specification while editing the filter. Select Edit Column to update and test a script, or Remove Column to delete it. Preview the resulting data and select Save.

Use JavaScript columns in NIM filters