netsuite-suitescript-upgrade

# 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: ``` /netsuite-suitescript-upgrade ``` Or use specific mode commands: ``` /netsuite-suitescript-upgrade analyze [file-path] # Assess migration complexity for SS1.0/2.0/2.x /netsuite-suitescript-upgrade convert [file-path] # Convert SS1.0/2.0/2.x → SS2.1 /netsuite-suitescript-upgrade explain [api-or-concept] # Deep dive into a mapping /netsuite-suitescript-upgrade validate [file-path] # Check converted script ``` ### Automatic Activation (Recommended for Migration Projects) For projects undergoing SuiteScript migration, add this skill to your project's `.claude/settings.local.json`: ```json { "permissions": { "allow": [ "Skill(netsuite-suitescript-upgrade)", "Skill(netsuite-sdf-leading-practices)", "Skill(netsuite-suitescript-reference)" ] } } ``` 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 ``` 1. Scan for @NApiVersion annotation → If "1.0": CONFIRMED SS1.0 → If "2.0" or "2.x": SS2.0/SS2.x input; upgrade to SS2.1 is required → If "2.1": Already SS2.1 2. If no @NApiVersion found: → Scan for define() or require() wrapper → If absent: Likely SS1.0 → Scan for nlapi*/nlobj* function calls → If present: CONFIRMED SS1.0 → Scan for @NScriptType annotation → If absent: Likely SS1.0 3. Count indicators to determine confidence level ``` --- ## Usage Syntax ``` /netsuite-suitescript-upgrade [mode] [target] [options] Modes: analyze - Assess a SS1.0, SS2.0, or SS2.x script's migration complexity convert - Convert a SS1.0, SS2.0, or SS2.x script to SS2.1 explain - Explain a specific API mapping or migration concept validate - Check a converted SS2.1 script for leftover issues Target: - File path for analyze/convert/validate mode - API name, object name, or concept for explain mode Options: --dry-run Show what would change without writing files (convert mode) --annotated Include numbered change annotations in output (convert mode) --verbose Include detailed migration notes in reports (all modes) ``` **Examples:** ``` /netsuite-suitescript-upgrade analyze /SuiteScripts/my_ue.js /netsuite-suitescript-upgrade convert /SuiteScripts/my_ue.js /netsuite-suitescript-upgrade convert /SuiteScripts/my_ue.js --annotated /netsuite-suitescript-upgrade explain nlapiSearchRecord /netsuite-suitescript-upgrade explain nlobjRecord /netsuite-suitescript-upgrade explain indexing /netsuite-suitescript-upgrade explain error-handling /netsuite-suitescript-upgrade validate /SuiteScripts/my_ue_v2.js ``` --- ## 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 ```markdown ## Migration Analysis: [filename] ### Script Overview - **Detected Version**: SuiteScript 1.0 - **Script Type**: [UserEventScript / ClientScript / Suitelet / etc.] - **Line Count**: [N] - **Entry Points**: [list of detected entry point functions] ### SS1.0 API Usage Summary #### nlapi* Function Calls ([total] calls, [unique] unique) | Function | Count | SS2.1 Module | Status | |----------|-------|-------------|--------| | nlapiLoadRecord | 3 | N/record | Mapped | | nlapiSearchRecord | 2 | N/search | Mapped | | nlapiAddDays | 1 | — | Unmapped (use native JS) | #### nlobj* Object Usage ([total] objects) | Object | Count | SS2.1 Class | |--------|-------|-------------| | nlobjSearchFilter | 4 | search.createFilter / filter array | | nlobjSearchColumn | 3 | search.createColumn | ### Required N/* Modules for SS2.1 | Module | Import Name | Reason | |--------|-------------|--------| | N/record | record | nlapiLoadRecord, nlapiSubmitRecord | | N/search | search | nlapiSearchRecord, nlapiLookupField | | N/log | log | nlapiLogExecution | ### Breaking Changes Affecting This Script | # | Change | Impact | Severity | |---|--------|--------|----------| | 1 | 1-based → 0-based sublist indexing | 3 loop constructs need updating | High | | 2 | Positional params → options objects | 12 function calls | Medium | | 3 | String type checks → enum values | 2 event type comparisons | Low | ### Unmapped APIs Found | Function | Workaround | |----------|------------| | nlapiAddDays | Use native JavaScript Date methods | ### Migration Complexity | Factor | Score | |--------|-------| | Line count | 2 (Medium) | | nlapi calls | 2 (Medium) | | Subrecord usage | 1 (None) | | Date/time ops | 2 (Body fields) | | Recovery points | 1 (None) | | Custom modules | 1 (None) | | Sublist ops | 3 (Dynamic) | | **Total** | **12 / 21** | **Complexity Rating: Medium** ### Migration Checklist - [ ] Set up SS2.1 file with @NApiVersion 2.1 and @NScriptType - [ ] Create define() wrapper with required modules: N/record, N/search, N/log - [ ] Convert 12 nlapi* calls to N/* module methods - [ ] Convert 7 nlobj* objects to SS2.1 classes - [ ] Fix 3 sublist loops from 1-based to 0-based indexing - [ ] Replace nlapiAddDays with native JS Date methods - [ ] Convert entry points to context-based pattern - [ ] Update error handling from nlobjError to try/catch - [ ] Test in the Sandbox environment - [ ] Update deployment XML (remove entry point function names) ``` --- ### 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