Skip to main content

Custom JavaScript columns

Calculated system data guide

Use a custom JavaScript column to derive a reliable value from collected data without changing the source system.

A custom JavaScript column is a calculated field. It returns a value from JavaScript that NIM can use like another collected column. Typical uses include normalizing source values, combining attributes, or deriving a value needed by several workflows.

Choose where the calculated value belongsDirect link to Choose where the calculated value belongs

You can add a custom JavaScript column to a system data table or to a filter. The right place depends on its scope.

Create it on a system table when…Create it in a filter when…
The calculation uses fields from that table and should be reused across filters, mappings, name generators, or other workflows.The calculation is only needed by one filter or needs data that the filter has already brought together.
You want one consistent definition of a normalized source value, such as a trimmed first name.You are shaping data for a specific outcome, such as constructing an account path from multiple related records.
A change should take effect everywhere that uses the table.You want the calculation to remain local and avoid changing shared system data.
Use the smallest scope that worksA system-table column is shared data-model logic. Put broadly useful, same-table calculations there; keep one-off workflow logic in the filter that needs it.

Create a system JavaScript columnDirect link to Create a system JavaScript column

  1. Open the system table and go to its Columns tab.
  2. Select Add, enter a clear column name, and add the JavaScript code.
  3. Use the green-arrow control to insert a column variable rather than typing it manually.
  4. Select Test Script and verify the result with representative records, including records with blank values.
  5. Select Save and Exit, then collect the system and confirm the calculated result in the table data.

For the complete create, edit, and remove procedure, see Manage JavaScript system columns.

Write defensive calculationsDirect link to Write defensive calculations

Source data is often incomplete. Handle a missing value explicitly so one blank attribute does not make the calculated column fail.

// Return a default when description is null or missing.
return (Users['description'] ?? 'Not provided').toLowerCase();

When the record object itself might be absent—for example, after an optional join in a filter—check it before reading a property.

return typeof Users_01 !== 'undefined'
  ? (Users_01['description'] ?? 'Not provided')
  : 'Not provided';

Use template literals to build readable strings instead of long concatenation chains.

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

Return a predictable value for every record. A short default such as an empty string, Unknown, or a configured fallback is usually easier to filter and troubleshoot than an unhandled error.

Available helpersDirect link to Available helpers

  • Vault queries let a calculation check for records in the Vault. Use lookup-oriented helpers where possible; broad record searches can be expensive.
  • Variable queries let a calculation read a configured NIM variable.
  • Built-in insertion tools in the editor can add supported hash and query functions without requiring you to memorize their syntax.

Important boundary: this is not an App scriptDirect link to Important boundary: this is not an App script

This JavaScript runs as part of NIM’s data-model or filter calculation features. It is separate from TypeScript scripts in Apps, which are available only inside NIM Apps and cannot be triggered or executed elsewhere in NIM.

Before you saveDirect link to Before you save

  • Use a name that describes the output, not the implementation—for example, normalized_department rather than trim_value.
  • Keep the original source fields available for validation and troubleshooting.
  • Test both complete and incomplete records.
  • Document any business rule embedded in the calculation, especially defaults or value transformations.
  • Recollect and inspect the result before relying on the new column in a mapping or scheduled job.
Last updated on