App Scripts

NIM Apps developer guide

Use TypeScript scripts to add focused custom logic inside a NIM App.

Custom script support

Custom scripts are used at your own risk. Validate scripts with non-production data and accounts before making them available to production workflows.

Scripts run only in NIM AppsDirect link to Scripts run only in NIM Apps

TypeScript scripts are an App-only extension point. They run from a NIM App and cannot be triggered or executed by connectors, mappings, jobs, filters, or other NIM features outside the App runtime.

Use a REST or PowerShell connector when custom code must integrate an external system. Use an App script when the custom logic belongs to an App experience.

What App scripts are forDirect link to What App scripts are for

NIM App scripts can add custom decision-making and automation around NIM data. Common uses include:

transforming or validating values before an action runs;
looking up records through filters;
coordinating multiple target-system actions; and
encapsulating reusable business rules.

Use an App script for clear, bounded logic. Prefer built-in App configuration when it already expresses the requirement—it is easier to review and maintain.

Develop with TypeScriptDirect link to Develop with TypeScript

App scripts are written in TypeScript. You can develop them in the NIM App interface, or use the NIM-Script example repository in VS Code for autocomplete, type feedback, and local debugging. Its README documents the setup, and the repository includes example script functions.

Try the example project locallyDirect link to Try the example project locally

Open the repository in VS Code and install its dependencies with npm i. Follow the README's Node.js version guidance for this example project.
Start NIM, download the nim.ts references file, and place it in the project's src directory.
Create config.json using config.sample.json as the guide.
Add or adapt functions in script.ts. Put calls to those functions in main.ts.
Run the project's build task, then run the project to exercise the calls in main.ts and debug the functions locally.

Use the repository examples as a starting point and validate the resulting script in a test App before using it in a production workflow.

A practical patternDirect link to A practical pattern

Keep scripts small: receive input, validate it, call NIM services, then return a predictable result or throw a useful error.

const results = await nim.filterExecute('Employee_User_View_P_ID', {ID: id});

if (results?.length === 1) {
  nim.logInfo(`Found employee [${id}]`);
  return results[0];
}

if (results?.length > 1) {
  throw new RangeError(`Found multiple employees for [${id}]`);
}

throw new RangeError(`No employee found for [${id}]`);

This pattern makes the expected outcomes explicit: one match succeeds; zero or multiple matches stop the workflow with useful diagnostic context.

Work safely with NIM dataDirect link to Work safely with NIM data

Scripts can call filters and target-system actions, so treat their inputs and outputs as part of the workflow contract.

Practice	Why it matters
Validate inputs	Avoid executing an action with missing or malformed values.
Handle no-match and many-match cases	Prevent a script from selecting an unintended identity.
Return predictable shapes	Keeps downstream scripts, mappings, and actions reliable.
Log context, not secrets	Make diagnosis possible without exposing credentials or personal data.
Throw actionable errors	Helps an operator correct the data or configuration quickly.

Test before releaseDirect link to Test before release

Test the happy path with a known test record.
Test missing, invalid, and ambiguous input.
Confirm any target-system action uses a disposable account or safe test scope.
Review logs for accidental secrets or sensitive values.
Give the script a clear name, description, and owner before production use.

Choose the right extension pointDirect link to Choose the right extension point

Need	Use
Integrate a full external system	A REST connector or PowerShell connector.
Transform or coordinate data within a NIM App	A NIM App TypeScript script.
Select or narrow records	A NIM filter, optionally called by a script.
Configure standard data movement	A mapping or target-system action.