Updating Scripts Using the SuiteScript Agent Skill

The NetSuite SuiteScript Upgrade skill helps you assess, convert, explain, and validate SuiteScript 1.0, 2.0, and 2.x scripts for SuiteScript 2.1. It preserves the script's behavior when identifying the API, runtime, and syntax changes needed for a safe migration.

For more information, see netsuite-suitescript-upgrade GitHub instructions or AI Agent Plug-ins and SuiteCloud Agent Skills help topic.

What This Skill Does

The skill supports four ways of working:

Mode	Use it when	Result
Analyze	You need to understand the migration effort before changing a script.	A complexity assessment, detected APIs and objects, required N/*modules, compatibility risks, and recommended testing focus.
Convert	You are ready to update a legacy script	A SuiteScript 2.1 version of the script, including annotation, API, object, and entry-point updates where needed.
Explain	You need help with a particular API or migration issue.	An explanation of the 2.1 approach, including mappings and behavioral differences.
Validate	A script has been converted or manually updated.	Checks for legacy annotations, nlapi* and nlobj* patterns, and common 2.1 migration issues.

Mode

Use it when

Result

Analyze

You need to understand the migration effort before changing a script.

A complexity assessment, detected APIs and objects, required N/*modules, compatibility risks, and recommended testing focus.

Convert

You are ready to update a legacy script

A SuiteScript 2.1 version of the script, including annotation, API, object, and entry-point updates where needed.

Explain

You need help with a particular API or migration issue.

An explanation of the 2.1 approach, including mappings and behavioral differences.

Validate

A script has been converted or manually updated.

Checks for legacy annotations, nlapi* and nlobj* patterns, and common 2.1 migration issues.

When To Use This Skill

Use the NetSuite SuiteScript upgrade skill when:

A script uses @NApiVersion 1.0, 2.0, or 2.x.
A script contains SuiteScript 1.0 APIs such as nlapiLoadRecord, nlapiSearchRecord, or nlapiLogExecution.
You need to determine whether a script can run successfully in the SuiteScript 2.1 runtime.
You are converting a project or specific script to SuiteScript 2.1.
You need to review a migration before testing or deployment.

How To Use This Skill

Invoke the skill and choose the mode that best matches the task to complete:

            /netsuite-suitescript-upgrade analyze FileCabinet/SuiteScripts/customer_ue.js
/netsuite-suitescript-upgrade convert FileCabinet/SuiteScripts/customer_ue.js --annotated
/netsuite-suitescript-upgrade explain nlapiSearchRecord
/netsuite-suitescript-upgrade validate FileCabinet/SuiteScripts/customer_ue.js

You can also use the following options when using the skill:

            --dry-run       Show proposed conversion changes without editing the script.
--annotated     Include numbered annotations that explain conversion changes.
--verbose       Include detailed migration notes.

Recommended Workflow

Inventory the script - Identify its version annotation, script type, dependencies, entry points, and the business process it supports.

Analyze before converting - Use analyze to identify legacy APIs, object usage, module requirements, and risks such as sublist indexing or date handling.

Test runtime compatibility when appropriate - For SuiteScript 2.0 and 2.x server scripts, use the account-level 2.1 execution preferences in a sandbox to test behavior before changing the file annotation.

Convert the script - Use convert, or make the required changes using the analysis as a checklist. Preserve script IDs, deployment behavior, custom module dependencies, and logic.

Validate the result - Use validate to confirm the script is annotated with @NApiVersion 2.1 and does not retain legacy 1.0 APIs or incompatible patterns.

Complete functional testing - Test the affected workflow, integrations, permissions, execution logs, and error handling in a sandbox before deployment.

Example Workflow

The following example shows how to convert a legacy SuiteScript User Event script, customer_ue.js. The following SuiteScript 1.0 script will be converted to SuiteScript 2.1:

            /**
 * @NApiVersion 1.0
 * @NScriptType UserEventScript
 */
function beforeSubmit(type) {
    if (type !== 'create') {
        return;
    }

    var newRecord = nlapiGetNewRecord();
    var customerId = newRecord.getFieldValue('entity');
    var customer = nlapiLoadRecord('customer', customerId);

    if (customer.getFieldValue('isinactive') === 'T') {
        throw nlapiCreateError(
            'INACTIVE_CUSTOMER',
            'You cannot create a transaction for an inactive customer.',
            true
        );
    }

    nlapiLogExecution('AUDIT', 'Customer verified', 'Customer ID: ' + customerId);
}

Convert a 1.0 Script to SuiteScript 2.1:

Analyze the script - Start with an analysis to understand the script type, legacy APIs, required modules, and migration risks. The skill detects a SuiteScript 1.0 User Event script. It identifies the legacy record and logging APIs, recommends N/record and N/log, and calls out record-loading behavior as a testing focus.
```
                  /netsuite-suitescript-upgrade analyze FileCabinet/SuiteScripts/customer_ue.js 

                
```
Convert the script - After reviewing the analysis, request an annotated conversion so each material change is explained. Review the converted code before treating it as ready. Confirm that entry points, custom module dependencies, script IDs, deployment behavior, and logic are still correct.
```
                  /netsuite-suitescript-upgrade convert FileCabinet/SuiteScripts/customer_ue.js --annotated 

                
```

Validate the converted script - Run validation after conversion to catch legacy annotations and API patterns that remain in the file. Validation is a static migration check, not a substitute for functional testing. Test the User Event in a sandbox using the records, roles, and scenarios it supports.

                  /netsuite-suitescript-upgrade validate FileCabinet/SuiteScripts/customer_ue.js

The conversion replaces legacy global APIs with N/error, N/log, and N/record modules, updates the entry point to use the User Event context, and changes the script annotation to 2.1.

                  /**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/error', 'N/log', 'N/record'], (error, log, record) => {
    const beforeSubmit = (context) => {
        if (context.type !== context.UserEventType.CREATE) {
            return;
        }

        const customerId = context.newRecord.getValue({ fieldId: 'entity' });
        const customer = record.load({
            type: record.Type.CUSTOMER,
            id: customerId
        });

        if (customer.getValue({ fieldId: 'isinactive' })) {
            throw error.create({
                name: 'INACTIVE_CUSTOMER',
                message: 'You cannot create a transaction for an inactive customer.',
                notifyOff: true
            });
        }

        log.audit({
            title: 'Customer verified',
            details: `Customer ID: ${customerId}`
        });
    };

    return { beforeSubmit };
});

Validation Checklist

Validation is successful when:

The script has no leftover @NApiVersion 1.0, 2.0, or 2.x annotations.
Legacy nlapi and nlobj patterns have been removed or addressed.
The script passes syntax and project-level checks.
The script runs successfully in a sandbox and completes its expected behavior.
Execution logs show no SuiteScript 2.1 compatibility errors.

Next Steps After Validation

If validation succeeds, retain the test evidence and deploy the SuiteScript 2.1 script through the normal process.

If validation does not succeed, keep the script at its current supported version when you resolve the identified compatibility issues. Re-run analysis and validation after each substantive update. Do not change production behavior solely because a conversion completed without errors.

Take advantage of validation to help identify issues that may need review:

SuiteScript 1.0 nlapi and nlobj objects that need N/ module equivalents.
Script type entry points and their expected context objects.
API parameters that become options objects.
Date, time zone, subrecord, search, and error handling behavior.
Unmapped legacy APIs that require a native JavaScript or alternative NetSuite approach.

Use explain mode when you need help with a specific migration question, for example:

            /netsuite-suitescript-upgrade explain nlapiSearchRecord
/netsuite-suitescript-upgrade explain nlobjRecord
/netsuite-suitescript-upgrade explain indexing
/netsuite-suitescript-upgrade explain error-handling

General Notices