netsuite-suitescript-upgrade
SuiteScript 1.0, 2.0, and 2.x to 2.1 migration assistant. Analyzes, converts, explains, and validates script upgrades. Covers 125+ API mappings, 34 object conversions, 13 unmapped API workarounds, all script type entry point changes, SuiteScript 2.0/2.x to 2.1 upgrade guidance, and 16 categories of
By oracle · 603 installs
npx skills add oracle/netsuite-suitecloud-sdk --skill netsuite-suitescript-upgrade
Source repository · Upstream listing
NetSuite SuiteScript Upgrade Skill
Created by: Oracle NetSuite
Description
Complete SuiteScript 1.0, 2.0, and 2.x to 2.1 migration assistant with 4 operating modes : analyze, convert, explain, and validate. SuiteScript 2.1 is always the target version. This skill provides:
Analyze Mode : Scan SS1.0, SS2.0, and SS2.x scripts and produce migration complexity reports
Convert Mode : Transform SS1.0, SS2.0, and SS2.x scripts to SS2.1 with full API mapping and JavaScript modernization
Explain Mode : Deep dive into specific API mappings, objects, or migration concepts for a full SS2.1 conversion
Validate Mode : Check converted scripts for leftover 1.0 patterns, non 2.1 version tags, and common conversion bugs
Backed by comprehensive reference data:
125+ API function mappings (nlapi\ → N/\ modules) across 26 modules
34 object conversions (nlobj\ → SS2.1 classes) with 331 method mappings
13 unmapped APIs with native JavaScript or alternative workarounds
All script type entry point changes (User Event, Client, Suitelet, RESTlet, Scheduled, Map/Reduce, etc.)
16 categories of breaking behavioral changes with before/after examples
How to Use This Skill
Manual Invocation (Slash Command)
Invoke this skill at any time by typing:
Or use specific mode commands:
Automatic Activation (Recommended for Migration Projects)
For projects undergoing SuiteScript migration, add this skill to your project's .claude/settings.local.json :
With all three skills enabled, Claude will:
Detect SS1.0, SS2.0, and SS2.x scripts automatically and offer migration assistance
Convert APIs using the complete mapping reference
Generate proper deployment XML via the leading practices skill
Look up correct field IDs via the suitescript reference skill
When to Use This Skill
Proactive Invocation (Recommended)
This skill should be invoked automatically when:
User opens or references a SuiteScript 1.0 file (detected by nlapi calls, no define() )
User opens or references a SuiteScript 2.0 or ambiguous 2.x file that needs normalization to SuiteScript 2.1
User asks about migrating, upgrading, or converting SuiteScript
User encounters nlapi or nlobj functions and asks what the SS2.1 equivalent is
User is working on a project with mixed SS1.0, SS2.0, SS2.x, and SS2.1 scripts
Manual Invocation
Commands: "analyze this script", "convert to 2.1", "what's the 2.1 version of nlapiSearchRecord?"
Questions: "How do I migrate this User Event?", "What module replaces nlapi functions?"
Validation: "Check my converted script", "Did I miss any 1.0 patterns?"
SS1.0 Detection Logic
How to Identify a SuiteScript 1.0 Script
A file is a SuiteScript 1.0 script if it matches any of these patterns:
Indicator Pattern Confidence
Explicit version tag @NApiVersion 1.0 or @NApiVersion "1.0" in JSDoc Definitive
No AMD wrapper No define() or require() call Strong
Global nlapi\ calls nlapiLoadRecord , nlapiSearchRecord , nlapiSubmitField , etc. Strong
Global nlobj\ constructors new nlobjSearchFilter , new nlobjSearchColumn Strong
No @NScriptType Entry points use function naming conventions, not annotation Moderate
Entry point as bare function function beforeLoad(type, form, request) at global scope Moderate
1 based sublist indexing Loop for (var i = 1; i <= count; i++) with line item ops Moderate
var keyword only No const / let usage (ES3 style) Weak (could be SS2.0)
Version Classification
Version Characteristics
SS1.0 Global nlapi / nlobj , no define() , no @NScriptType
SS2.0 define() wrapper, @NApiVersion 2.0 , uses var (no arrow functions, no template literals)
SS2.1 define() wrapper, @NApiVersion 2.1 , modern JS (const/let, arrow functions, template literals, async/await)
Detection Algorithm
Usage Syntax
Examples:
Core Functionality
1. Analyze Mode ( analyze )
Scan a SuiteScript 1.0 file and produce a migration complexity report.
Process
1. Read the file and confirm it is SS1.0 (using detection logic above)
2. Detect script type from entry point function names or JSDoc annotations
3. Scan for all nlapi function calls ; categorize by module
4. Scan for all nlobj object usage ; categorize by class
5. Check for unmapped APIs — cross reference with references/unmapped apis.md
6. Check for breaking change patterns ; 1 based indexing, positional params, recovery points, etc.
7. Calculate complexity score using the scoring matrix
8. Produce the migration report
Complexity Scoring Matrix
Factor Low (1 pt) Medium (2 pts) High (3 pts)
Line count < 100 lines 100–500 lines 500+ lines
Unique nlapi\ calls < 10 10–30 30+
Subrecord usage None Read only Create/edit
Date/time with timezone None Body fields Sublist date fields
Recovery points None nlapiSetRecoveryPoint Recovery + Yield
Custom module includes None 1–2 includes 3+ includes
Sublist operations None Read only Dynamic line manipulation
Score interpretation:
7–10 points : Low complexity; straightforward conversion
11–15 points : Medium complexity; careful testing needed, some architectural decisions
16–21 points : High complexity; plan a staged full conversion to SS2.1
21+ with unmapped APIs : Critical ; significant rework required, but final output must still be SS2.1
Output Format for Analyze Mode
2. Convert Mode ( convert )
Read a SuiteScript 1.0, 2.0, or 2.x file and produce a complete SS2.1 conversion.
Conversion Target Rules
SuiteScript 2.1 is the only valid output version. Upgrade @NApiVersion 2.0 and ambiguous 2.x references to @NApiVersion 2.1 .
Do not create compatibility shims, adapter layers, helper wrappers, facades, or polyfills that preserve nlapi or nlobj calling semantics.
Every SuiteScript 1.0 API usage must be replaced directly with SuiteScript 2.1 APIs, native JavaScript, or a documented SuiteScript 2.1 architecture change.
Do not propose coexistence, RESTlet bridge, Suitelet bridge, or side by side patterns as a migration outcome. The goal is complete conversion to SS2.1.
Process
1. Run analysis (the same as analyze mode) to understand the script
2. Detect script type and determine entry point pattern from references/script type changes.md
3. Build the define() module list from detected nlapi usage using the module mapping table
4. Convert all nlapi function calls using references/api mapping.json (125+ mappings)
5. Convert all nlobj objects using references/object mapping.json (34 objects, 331 methods)
6. Apply breaking changes from references/breaking changes.md :
1 based → 0 based sublist indexing
Positional parameters → options objects
String comparisons → enum values
Getter/setter methods → properties
Inverted boolean logic (setVisible → isHidden)
Recovery point → Map/Reduce pattern
7. Handle unmapped APIs using workarounds from references/unmapped apis.md
8. Add JSDoc annotations ( @NApiVersion 2.1 , @NScriptType )
9. Restructure entry points to the return object pattern
10. Modernize JavaScript (var→const/let, string concat→template literals, indexOf→includes)
11. Generate deployment XML update notes (reference netsuite sdf leading practices for full XML)
12. Produce migration notes listing every change made
Module Identification Table
When scanning the SS1.0 script, map each nlapi function to its required module:
SS1.0 Function Pattern Required Module Import Name
nlapiCreateRecord , nlapiLoadRecord , nlapiSubmitRecord , nlapiDeleteRecord , nlapiCopyRecord , nlapiTransformRecord , nlapiSubmitField , nlapiAttachRecord , nlapiDetachRecord N/record record
nlapiSearchRecord , nlapiCreateSearch , nlapiLoadSearch , nlapiLookupField , nlapiSearchDuplicate , nlapiSearchGlobal N/search search
nlapiLogExecution N/log log
nlapiSendEmail , nlapiSendCampaignEmail N/email email
nlapiRequestURL , nlapiRequestURLWithCredentials N/http or N/https http / https
nlapiResolveURL N/url url
nlapiSetRedirectURL N/redirect redirect
nlapiCreateFile , nlapiLoadFile , nlapiDeleteFile , nlapiSubmitFile N/file file
nlapiCreateForm , nlapiCreateList , nlapiCreateAssistant N/ui/serverWidget serverWidget
nlapiCreateError N/error error
nlapiGetContext N/runtime runtime
nlapiDateToString , nlapiStringToDate , nlapiFormatCurrency N/format format
nlapiCreateTemplateRenderer , nlapiXMLToPDF , nlapiPrintRecord , nlapiCreateEmailMerger N/render render
nlapiScheduleScript , nlapiCreateCSVImport N/task task
nlapiEscapeXML , nlapiStringToXML , nlapiXMLToString , nlapiSelectNode , nlapiSelectNodes , nlapiValidateXML N/xml xml
nlapiExchangeRate N/currency currency
nlapiEncrypt N/crypto + N/encode crypto , encode
nlapiLoadConfiguration N/config config
nlapiGetLogin N/auth auth
nlapiInitiateWorkflow , nlapiTriggerWorkflow N/workflow workflow
nlapiVoidTransaction N/transaction transaction
Note: N/log is globally available in SS2.1 without importing, but explicitly including it in define() makes dependencies clearer and is recommended.
Client Script Special Handling
For Client Scripts, some nlapi functions map to N/currentRecord instead of N/record :
SS1.0 Function (Client Context) SS2.1 Module SS2.1 Method
nlapiGetFieldValue N/currentRecord currentRecord.getValue
nlapiSetFieldValue N/currentRecord currentRecord.setValue
nlapiGetFieldText N/currentRecord currentRecord.getText
nlapiSetFieldText N/currentRecord currentRecord.setText
nlapiGetLineItemValue N/currentRecord currentRecord.getSublistValue
nlapiSetCurrentLineItemValue N/currentRecord currentRecord.setCurrentSublistValue
nlapiCommitLineItem N/currentRecord currentRecord.commitLine
nlapiSelectNewLineItem N/currentRecord currentRecord.selectNewLine
In Server side scripts (User Event, Suitelet, etc.), these same operations use N/record on the record object provided by the context.
Output Format for Convert Mode
javascript
/
@NApiVersion 2.1
@NScriptType [ScriptType]
/
define(['N/record', 'N/search', 'N/log'], (record, search, log) = {
// ... converted code ...
return { / entry points / };
});
xml
<! Remove these lines:
<beforeloadfunction beforeLoad</beforeloadfunction
<beforesubmitfunction beforeSubmit</beforesubmitfunction
<aftersubmitfunction afterSubmit</aftersubmitfunction
Conversion with Annotations ( annotated )
When annotated is used, include numbered annotations as comments:
3. Explain Mode ( explain )
Provide deep explanations for specific API mappings, object conversions, or migration concepts.
Supported Query Types
nlapi\ Function Queries:
When the user asks about a specific nlapi function (for example, "explain nlapiSearchRecord"):
1. Look up the function in references/api mapping.json
2. Show the SS1.0 signature and SS2.1 equivalent
3. Detail all parameter changes
4. List breaking changes
5. Provide a before/after code example
6. Note governance cost differences if applicable
nlobj\ Object Queries:
When the user asks about an nlobj object (for example, "explain nlobjRecord"):
1. Look up the object in references/object mapping.json
2. Show the SS2.1 class and module
3. List all method conversions with notes
4. Highlight methods that became propert