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:

{
  "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:

Version Classification

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

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