Checklist for reviewing NetSuite custom code before SuiteScript 2.1 migration
NetSuite•10 min read

Is Your NetSuite Custom Code Ready for SuiteScript 2.1? A Migration Checklist

Aug 14, 2026

Readiness Means the Business Result Is Protected

A script is not ready for SuiteScript 2.1 just because it uploads. It is ready when the team knows what it does, who owns it, how to test it, and how to recover if the result is wrong.

Oracle recommends that users of SuiteScript 1.0, 2.0, or the 2.x tag consider updating to SuiteScript 2.1.[1] This checklist turns that direction into a set of gates your company can prove.

We conducted this review around evidence, not opinion. Mark an item complete only when you can point to a record, owner, test, decision, or release control.

SuiteScript 2.1 Readiness Scorecard

Readiness areaPass conditionStop signal
InventoryFile, deployment, version, and owner are knownA running script has no trusted source
CompatibilityRuntime and API differences were reviewedThe plan is only to change the version tag
Business proofExpected outputs are written and approvedTesting checks only for script errors
ReleaseWindow, approver, monitoring, and rollback are setNo one can restore the prior deployment
SupportLogs, alerts, runbook, and owner are readyThe original developer is the only support plan

A single stop signal does not mean the migration must fail. It means the script should stay out of the current release wave until the gap has an owner and a clear fix.

1. Can You Find Every Script and Deployment?

Start with script records and active deployments. Link each one to its file, source repository, bundle, calling script, integration, and business process. Oracle's own test guidance tells customers to list all script deployments and use the list as a testing checklist.[2]

  • Record the current @NApiVersion and script type.
  • Name the business and technical owners.
  • List records, forms, roles, schedules, and integrations touched.
  • Confirm the deployed file matches trusted source control.
  • Flag hidden, bundled, locked, copied, and unused scripts.
  • Write the expected business result in plain language.

2. Is the Script Type Supported?

Check the product area and script type before changing code. Most common server and client script work can use 2.1, but support is not identical in every NetSuite area. Document any approved exception instead of forcing one company-wide answer.

Also review module scope, roles, execution context, and deployment status. A technically correct script can fail when it cannot load a module or run under the real user's permissions.

IdentifyFind the code, deployment, process, and owner.
InspectReview runtime issues, APIs, tags, and access.
ProveCompare expected and actual business results.
ReleaseApprove the window, monitoring, and rollback.
SupportConfirm alerts, runbook, owner, and follow-up.

3. Did You Scan for 2.0 Runtime Differences?

SuiteScript 2.1 uses a different runtime from 2.0. Oracle lists behavior changes involving strict mode, reserved words, error properties, invalid JSON, const variables, iteration, dates, RESTlet results, parseInt, and promises.[3]

Search for each pattern, then test the output. Syntax review alone is not enough. Dates, totals, strings, and response bodies can change without producing an obvious script failure.

4. Does Every 1.0 API Have a Clear Replacement?

SuiteScript 1.0 is a conversion path, not a tag update. Oracle's API map says some 1.0 APIs do not have a 2.1 equivalent, and other mappings are not one to one.[4]

Record the chosen module, method, property, or standard JavaScript replacement. If the match is unclear, create a design decision. Do not hide the gap inside a developer's personal notes.

5. Are the JSDoc Tags and Entry Points Valid?

NetSuite uses JSDoc tags such as @NApiVersion and @NScriptType to validate entry-point scripts. Oracle specifies the required block format and explains that NetSuite parses the version tag when a 2.1 script record is requested.[5]

Check the tags, entry-point names, returned object, module dependencies, file paths, and scope. Keep custom modules separate from entry-point rules.

6. Can the Tests Prove the Real Process?

Our analysis treats a test as evidence only when it names the input, expected result, actual result, account, role, reviewer, and date. Add screenshots or record IDs when they help another person repeat the check.

  • Normal records and every important logic branch
  • Empty, invalid, duplicate, and unusually large data
  • Employee roles, integration users, and permission failures
  • Governance limits, schedules, queues, retries, and restarts
  • Dates, time zones, currency, tax, totals, and rounding
  • RESTlet requests, responses, authentication, and errors
  • Dependent systems, timeouts, and credential changes
  • Rollback and support-team handoff

Oracle's public SuiteCloud SDK includes unit-testing tools. Its sample repository provides SuiteScript 2.1 projects and advises using a test account with test data.[6] Use unit tests for code logic, then use a sandbox for NetSuite behavior and full business workflows.

7. Does the Project Validate Against the Target Account?

SuiteCloud project validation checks project structure, dependencies, object definitions, required fields, and target-account conditions. Oracle says server-side validation also runs during deployment and produces a validation log.[7]

Keep the validation log with the release evidence. A clean result does not replace business testing, but it can catch deployment problems before the change reaches production.

8. Are Release, Rollback, and Support Ready?

Name the release owner, approver, support owner, and business checker. Set the deployment order, monitoring period, stop conditions, rollback steps, and communication plan. Keep the prior code and deployment settings recoverable.

NIST's Secure Software Development Framework supports preparing the organization, protecting code, producing secure releases, and responding to weaknesses.[8] Those practices support source control, review, testing, release records, defect handling, and clear ownership for NetSuite custom code.

How to Read the Result

Ready: Every gate has evidence, the business owner approves the result, and rollback has been tested.

Ready with conditions: Low-risk gaps have named owners and due dates, and approvers accept them in writing.

Not ready: The source, owner, expected result, API choice, test evidence, or rollback path is missing. Keep that script out of the wave.

Final Takeaway

SuiteScript 2.1 readiness is not a code-only question. It joins code, business rules, test data, permissions, releases, and support.

Begin with the inventory. Choose a small pilot with clear expected results. Close every stop signal before production, then use the same checklist for the next wave.

References

  1. Oracle NetSuite: SuiteScript Versioning Guidelines.
  2. Oracle NetSuite: Test Your SuiteScript Deployments.
  3. Oracle NetSuite: Differences Between SuiteScript 2.0 and SuiteScript 2.1.
  4. Oracle NetSuite: SuiteScript 1.0 to SuiteScript 2.1 API Map.
  5. Oracle NetSuite: SuiteScript 2.1 JSDoc Validation.
  6. Oracle on GitHub: NetSuite SuiteCloud SDK and Oracle Samples: NetSuite SuiteCloud Projects.
  7. Oracle NetSuite: SuiteCloud Project Validation.
  8. NIST SP 800-218: Secure Software Development Framework.

Need an Evidence-Based SuiteScript Readiness Review?

We can audit your code, deployments, risks, tests, owners, and rollback plan before the first migration wave.

Review Your Custom Code

Know Which Scripts Are Ready Before You Change Them

Turn your custom-code inventory into clear pass, condition, and stop decisions for SuiteScript 2.1.

Book a SuiteScript Readiness Audit

Frequently Asked Questions

Common questions about checking NetSuite custom code for SuiteScript 2.1.

How do I know whether custom code is ready for SuiteScript 2.1?

The code is ready when it has a known owner, trusted source, supported script type, reviewed APIs, clear expected results, passing tests, a controlled deployment plan, monitoring, and rollback steps.

Does every SuiteScript 2.0 file need to be rewritten?

No. SuiteScript 2.1 is backward compatible with 2.0, but runtime differences can affect behavior. Review the code and test each important deployment before changing its version.

Can SuiteScript 1.0 pass the same readiness check?

Yes, but 1.0 normally needs a full conversion to the 2.x structure and module APIs. Some old APIs have no direct one-to-one match, so the checklist must allow redesign work.

What SuiteScript 2.1 issues should a code scan find?

Look for reserved words, strict-mode issues, const reassignment, old iteration patterns, invalid JSON handling, date changes, RESTlet response differences, unsupported APIs, and missing JSDoc tags.

What test evidence is needed before release?

Keep expected and actual results for normal records, edge cases, permissions, governance, integrations, schedules, errors, volume, and rollback. Record who reviewed and approved the evidence.

Should we test SuiteScript 2.1 in production?

Use a sandbox or other safe test account for migration tests whenever possible. Oracle warns that debugger actions can affect production data when the debugger is opened from a production account.

Who should approve SuiteScript 2.1 readiness?

A technical reviewer should approve the code and tests, while the business owner should confirm the process result. The release owner should confirm timing, monitoring, and rollback.

What happens when a script is not ready?

Keep it out of the release wave. Record the missing owner, API decision, test, permission, dependency, or rollback step, then assign an action and review date.