netsuite-sdf-safe-guide

name	netsuite-sdf-safe-guide
description	Comprehensive NetSuite SDF best practices based on the SAFE Guide (12 principles + appendices). Generates Object XML for all 14 script types, enforces governance limits, security patterns, and defensive coding. Includes N/cache, N/query, concurrency limits, OAuth 2.0 guidance, legacy TBA guardrails, CustomTool runtime patterns, REST Web Services (2026.1 features), and 140+ documented pitfalls. Essential for SuiteApp and Account Customization development.
license	The Universal Permissive License (UPL), Version 1.0
metadata	{"author":"Oracle NetSuite","version":"1.0"}

NetSuite SDF Safe Guide

Description

Comprehensive guide for NetSuite SuiteCloud Development Framework (SDF) projects, incorporating the SAFE Guide (SuiteApp Architecture Framework for Excellence) principles. This skill provides:

• SAFE Guide Integration: 12 principles covering features, governance, performance, multi-SuiteApp environments, security, testing, distribution, maintenance, licensing, open-source compliance, secure coding, and UIF SPA best practices
• Object XML Generation: Automatically creates deployment XML files for all 14 SuiteScript types
• Best Practices Enforcement: Ensures correct deployment configurations, permissions, and status values
• Common Pitfalls Documentation: 140+ documented pitfalls with solutions learned from real deployments
• Performance Guidance: N/cache patterns, N/query with SuiteQL, avoiding N+1 queries, batch operations, Map/Reduce optimization
• Architecture Patterns: Suitelet-as-API pattern, popup communication with postMessage, module-level initialization
• Defensive Coding: Patterns for scripts to coexist with other scripts, workflows, and SuiteApps
• Governance & Limits: Usage unit limits by script type, concurrency limits, API costs, time limits
• Security: OWASP principles, input validation, secure coding practices
• Appendices: Concurrency limits, N/query joins, N/cache samples, and other static reference material

How to Use This Skill

Manual Invocation (Slash Command)

Invoke this skill at any time by typing:

/netsuite-sdf-safe-guide

Or use natural language triggers:

• "Generate objects" – Scan SuiteScripts folder and create missing Object XML files.
• "Create object for this script" – Generate Object XML for the current/specified file.
• "Check my deployment XML" – Review and validate existing Object XML files.
• "Review my SuiteScript" – Review code for best practices, pitfalls, and governance issues.

Optional Coding Assistant Activation Example

For NetSuite SuiteCloud Development Framework (SDF) projects, supported coding assistants may preload this skill from project settings.

Here is an example for Claude, which is one of the supported coding assistants: Step 1: Create or edit .claude/settings.local.json in your SDF project root:

{
  "permissions": {
    "allow": [
      "Skill(netsuite-sdf-safe-guide)"
    ]
  }
}

Step 2 (Optional): Add additional related skills and permissions:

{
  "permissions": {
    "allow": [
      "Skill(netsuite-sdf-safe-guide)",
      "Skill(netsuite-suitescript-learning)",
      "Bash(suitecloud project:deploy:*)"
    ]
  }
}

With skill preloading configured, an assistant will automatically apply SDF best practices when you:

• Work on any NetSuite SDF project (SuiteApps or Account Customization projects).
• Create or modify SuiteScript files (all 14 script types including Suitelets, RESTlets, User Event Scripts, etc.).
• Work with Object XML files, custom records, custom fields, or other SDF objects.
• Configure deployment settings, manifest.xml, or deploy.xml.
• Ask questions about NetSuite SDF development.
• Encounter deployment errors or script issues.

---

Intended Audience

This skill is designed for Technical Architects, Developers, and System Administrators working with NetSuite SuiteScript and the SuiteCloud Development Framework (SDF). It is a practical companion to expert guidance and hands-on experience, not a replacement for the official NetSuite documentation. The focus is SuiteScript 2.1 with callouts to 2.0/1.0 only where meaningful differences exist.

---

When to Use This Skill

Proactive Invocation (Recommended)

This skill should be invoked automatically when:

• The user is working on a NetSuite SDF project.
• The user creates or modifies SuiteScript files.
• The user asks questions about SDF deployment, script types, or NetSuite development.
• The user encounters deployment errors or script issues.

Manual Invocation

• Commands: "generate objects", "create object for this script", "check my deployment XML".
• Questions: "What's wrong with my RESTlet?", "Why won't my script deploy?", "How do I add a button?".
• Best practices: "Review my SuiteScript", "Is this the right approach?", "What's the pattern for...".

Object Generation Mode

When the user says "generate objects" without specifying a file:

1. Scan the entire /SuiteScripts/ folder (including subfolders) for all .js files.
2. For each .js file found:
   • Check if it has a valid @NScriptType annotation.
   • Check if an object XML file already exists for it.
   • If no object exists and it has a valid script type, generate the object.
3. Skip files that:
   • Already have corresponding object XML files.
   • Don't have a valid @NScriptType annotation.
   • Are schema files (*_schema.json).
4. Provide a summary of all files processed.

Single File Processing

Only process a single file when:

• The user explicitly specifies a file path.
• The user says "for this script" or "for this file" (use the currently open file in the IDE).
• The user references a specific script by name.

Best Practices Review Mode

When reviewing code or answering questions:

• Reference the Common Pitfalls section for known issues.
• Apply logging configuration guidelines.
• Recommend architecture patterns (Suitelet-as-API, postMessage, etc.).
• Check for N+1 query problems and suggest batch operations.

Supported Script Types

#	Script Type	@NScriptType Value	Description
1	BundleInstallationScript	BundleInstallationScript	Scripts that run during bundle installation/update/uninstall
2	ClientScript	ClientScript	Client-side scripts for forms
3	CustomTool	CustomTool	Custom tools with RPC schemas for AI agents
4	MapReduceScript	MapReduceScript	Server-side scripts for processing large datasets
5	MassUpdateScript	MassUpdateScript	Scripts for bulk record updates
6	Portlet	Portlet	Dashboard portlets for displaying custom content
7	Restlet	Restlet	RESTful web services
8	ScheduledScript	ScheduledScript	Scripts that run on a schedule
9	SDFInstallationScript	SDFInstallationScript	Scripts that run during SDF project deployment
10	SpaServerScript	SpaServerScript	Server-side initialization for Single Page Applications
11	SpaClientScript	SpaClientScript	Client-side rendering for Single Page Applications
12	Suitelet	Suitelet	Custom pages and forms
13	UserEventScript	UserEventScript	Server-side scripts triggered by record events
14	WorkflowActionScript	WorkflowActionScript	Custom actions for workflows

Process Flow

CRITICAL: Filename Normalization Rules

All filenames MUST be normalized before generating script IDs:

1. Convert to Lowercase: GetCampaign.js → getcampaign.js
2. Replace Hyphens: ue-customer-validation.js → ue_customer_validation.js
3. Maximum Length: 40 characters total (including .xml extension for object files)
4. Validation: Script ID must exactly match normalized filename

Normalization Examples:

Original Filename	Normalized Filename	Script Type	Script ID (max 40)
GetCampaignPreflight.js	getcampaignpreflight.js	CustomTool	custtoolset_getcampaignpreflight (33 chars)
UE-Customer-Validation.js	ue_customer_validation.js	UserEventScript	customscript_ue_customer_validation (36 chars)
Client-Script-Extended.js	client_script_extended.js	ClientScript	customscript_client_script_extended (36 chars)
VeryLongScriptName.js	verylongscriptname.js	Suitelet	customscript_verylongscriptname (31 chars)

Truncation Logic: When a script ID would exceed 40 characters:

1. Calculate prefix length (for example, customscript_ = 13 chars)
2. Remaining space = 40 - prefix length (for example, 40 - 13 = 27 chars)
3. Truncate filename to fit: very_long_filename_example_here → very_long_filename_example_he
4. Final script ID: customscript_very_long_filename_example_he (exactly 40 chars)

If filename needs normalization:

• Display a message to the user: "Renaming file from '[original]' to '[normalized]'"
• Automatically rename the source .js file to the normalized filename
• Use normalized name for all script IDs and file paths

---

Step 1: Identify the SuiteScript File

• Locate the .js file in /SuiteScripts/ (and subfolders).
• Extract the file path and filename.
• Preserve subfolder structure for scriptfile path.

Step 2: Parse JSDoc Comments

Read the JSDoc block at the top of the file to extract:

• @NScriptType - Determines which XML structure to create
• @NApiVersion - For validation (should be 2.x)
• @NModuleScope - Optional

Example JSDoc:

/**
 * filename.js
 * @NApiVersion 2.1
 * @NModuleScope Public
 * @NScriptType CustomTool
 */

Step 3: Extract and Normalize File Information

From path: /SuiteScripts/tools/getCampaignPreflight.js Extract and normalize:

• Subfolder: tools (or empty if none)
• Filename: getcampaignpreflight (original: getCampaignPreflight)
• Full scriptfile path: /SuiteScripts/tools/getcampaignpreflight.js

Filename Normalization Rules:

1. Convert to lowercase
2. Replace all - (hyphens) with _ (underscores)
3. Ensure total length ≤ 40 characters
4. Remove any invalid characters

Examples:

• GetCampaignPreflight.js → getcampaignpreflight.js
• ue-customer-validation.js → ue_customer_validation.js
• Client-Script-Form-Validator-Extended-v2.js → client_script_form_validator_extende.js (truncated to 40 chars)

Step 4: Generate Script Identifiers

IMPORTANT: Script IDs must exactly match the normalized filename

Script ID Pattern

For CustomTool:    custtoolset_[normalized_filename]
For Other Scripts: customscript_[normalized_filename]

NOTE: Do NOT include the script type in the ID. Use only customscript_ prefix for all non-tool scripts.

CRITICAL: 40 Character Maximum The entire script ID must be ≤ 40 characters. If it exceeds this limit, truncate the filename portion.

Examples:

• custtoolset_getcampaignpreflight (33 chars) ✓
• customscript_form_validator (27 chars) ✓
• customscript_update_customer (28 chars) ✓

Character Count Breakdown:

• custtoolset_ = 12 characters → filename portion ≤ 28 chars
• customscript_ = 13 characters → filename portion ≤ 27 chars

Truncation Example:

Original filename: verylongclientscriptname.js
Prefix: customscript_ (13 chars)
Remaining: 40 - 13 = 27 chars
Final script ID: customscript_verylongclientscriptna

Deployment ID Pattern

For Other Scripts: customdeploy_[normalized_filename]
(CustomTool has NO deployment — skip this step)

Same 40-character limit applies. customdeploy_ = 13 characters → filename portion ≤ 27 chars.

Validation Check

Before generating XML, verify:

1. Normalize filename (lowercase, underscores, no hyphens)
2. Calculate script ID with prefix (customscript_ or custtoolset_)
3. If script ID > 40 chars:
     Truncate filename to fit within 40 char limit
     Warn the user: "Script ID truncated to 40 characters"
4. Validate: script ID exactly matches expected pattern (no script type in ID)

Human-Readable Name Generation

Convert filename from camelCase/snake_case to Title Case:

• getcampaignpreflight → "Get Campaign Preflight"
• ue_update_customer → "UE Update Customer"
• RESTlet_API_Handler → "RESTlet API Handler"

Algorithm:

1. Split on underscores and capital letters.
2. Capitalize first letter of each word.
3. Keep acronyms as-is.
4. Join with spaces.

Step 5: Gather Required Information

For ClientScript, UserEventScript, and MassUpdateScript:

Prompt the user for the record type:

What record type should this [ClientScript/UserEventScript/MassUpdateScript] be deployed to?
Examples:
- Standard records: customer, salesorder, invoice, contact, etc.
- Custom records: [customrecord_yourrecordname]

For CustomTool:

Automatically Create Schema File:

Looking for: /SuiteScripts/[subfolder]/[normalized_filename]_schema.json

If NOT found:
  Automatically create a basic schema template at the expected location.
  Notify the user: "Created schema template at [path]".

Schema file will be referenced in the object XML

NOTE (NetSuite 2026.1+): CustomTool was renamed to ToolSet in 2026.1. Use custtoolset_ prefix (not customtool_) and <toolset> root element (not <tool>). The visibility element is now <exposetoaiconnector> (was <exposeto3rdpartyagents>). See SuiteAnswers 1024036.

Step 6: Generate XML Object File

Create the appropriate XML structure based on script type:

---

Step 7: Update manifest.xml (All Server-Side Scripts)

For ALL server-side scripts (BundleInstallationScript, MapReduceScript, MassUpdateScript, Portlet, Restlet, ScheduledScript, SDFInstallationScript, Suitelet, WorkflowActionScript), update the project's manifest.xml file:

Location: /src/manifest.xml

Required Addition: Insert the following XML block immediately after the <frameworkversion> tag:

<dependencies>
  <features>
    <feature required="true">SERVERSIDESCRIPTING</feature>
  </features>
</dependencies>

Complete Structure Example:

<?xml version="1.0" encoding="UTF-8"?>
<manifest projecttype="SUITEAPP">
  <projectname>[Your Project Name]</projectname>
  <frameworkversion>1.0</frameworkversion>
  <dependencies>
    <features>
      <feature required="true">SERVERSIDESCRIPTING</feature>
    </features>
  </dependencies>
  <!-- rest of manifest -->
</manifest>

Logic:

1. Check if manifest.xml already contains <dependencies> tag.
2. If YES: Verify SERVERSIDESCRIPTING feature exists, add if missing.
3. If NO: Insert entire <dependencies> block after <frameworkversion>.

Note: This is required for all server-side script deployment to NetSuite. The only exceptions are ClientScript (client-side) and CustomTool (has different requirements). UserEventScript also requires this feature. Without this, deployment will fail.

Additional Feature Dependencies

When your project includes custom fields applied to transaction bodies (custbody_*), the following features must be declared in manifest.xml if the field applies to the corresponding transaction type:

Feature String	Required When Field Applies To
RECEIVABLES	Customer Payment transactions
PAYABLES	Vendor Payment transactions
EXPREPORTS	Expense Report transactions
ADVRECEIVING	Item Receipt transactions
OPPORTUNITIES	Opportunity transactions
WEBSTORE	Web Store transactions
MULTILOCINVT	Transfer Order transactions

When your project includes custom fields applied to items (custitem_*) with inventory or assembly applicability:

Feature String	Required When Field Applies To
INVENTORY	Inventory Items
ASSEMBLIES	Assembly Items

Example: A project with custbody_* fields on transaction bodies AND custitem_* fields on inventory/assembly items needs:

<dependencies>
  <features>
    <feature required="true">SERVERSIDESCRIPTING</feature>
    <feature required="true">RECEIVABLES</feature>
    <feature required="true">PAYABLES</feature>
    <feature required="true">EXPREPORTS</feature>
    <feature required="true">ADVRECEIVING</feature>
    <feature required="true">OPPORTUNITIES</feature>
    <feature required="true">WEBSTORE</feature>
    <feature required="true">MULTILOCINVT</feature>
    <feature required="true">INVENTORY</feature>
    <feature required="true">ASSEMBLIES</feature>
  </features>
</dependencies>

Tip: Run suitecloud project:validate. It will list all missing feature dependencies. Add each one to manifest.xml before deploying.

---

Step 8: Create Object File

CRITICAL: XML Character Encoding

NEVER use HTML entities for XML tags. Always use literal angle brackets.

Correct:

<scriptfile>[/SuiteScripts/my_script.js]</scriptfile>
<name>My Script Name</name>

INCORRECT (WILL CAUSE ERRORS):

<scriptfile>[/SuiteScripts/my_script.js]</scriptfile>
<name>My Script Name</name>

When writing XML files:

• Use < not <
• Use > not >
• HTML entities should ONLY be used for content values that contain special characters, not for XML tag syntax

---

CRITICAL: Scriptfile Path Bracket Notation

All <scriptfile> and <rpcschema> paths MUST be wrapped in square brackets [].

This is a NetSuite SDF requirement. Paths without brackets will cause deployment failures.

Correct Format:

<scriptfile>[/SuiteScripts/my_script.js]</scriptfile>
<rpcschema>[/SuiteScripts/my_script_schema.json]</rpcschema>

Incorrect Format (WILL FAIL):

<scriptfile>/SuiteScripts/my_script.js</scriptfile>
<rpcschema>/SuiteScripts/my_script_schema.json</rpcschema>

Why Brackets Are Required:

• NetSuite SDF uses bracket notation to indicate file references within the File Cabinet.
• The brackets signal to the deployment system that this is a relative path within the SuiteApp/Account Customization bundle.
• Without brackets, NetSuite cannot resolve the file path during deployment.

---

---

FileCabinet File Permissions for .ss and .ssp Files

.ss (SuiteScript Classic) and .ssp (SuiteScript Server Pages) files require explicit <permission> configuration in their SDF FileCabinet <file> definition. Without this, file permissions revert to account defaults after deployment.

Valid permission levels: FULL | VIEW | EDIT | CREATE | REMOVE

<file path="/SuiteScripts/my_classic_page.ssp">
  <permissions>
    <permission>
      <permkey>LIST_CUSTJOB</permkey>
      <permlevel>VIEW</permlevel>
    </permission>
  </permissions>
</file>

---

CustomTool Template

Version-aware: Check target_netsuite_version in ~/.claude/netsuite-connector-config.json (default "2026.1") and use the matching template below.

NetSuite 2025.2 Format (Legacy)

<tool scriptid="customtool_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <rpcschema>[/SuiteScripts/[subfolder]/[filename]_schema.json]</rpcschema>
  <exposeto3rdpartyagents>T</exposeto3rdpartyagents>
  <permissions>
    <permission>
      <permkey>LIST_CONTACT</permkey>
      <permlevel>VIEW</permlevel>
    </permission>
  </permissions>
</tool>

2025.2 compatibility: This format deploys to both 2025.2 AND 2026.1 accounts but does not support execution logs. Use this only when target_netsuite_version is "2025.2".

NetSuite 2026.1+ Format (Current — Recommended)

<toolset scriptid="custtoolset_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <rpcschema>[/SuiteScripts/[subfolder]/[filename]_schema.json]</rpcschema>
  <exposetoaiconnector>T</exposetoaiconnector>
  <permissions>
    <permission>
      <permkey>LIST_CONTACT</permkey>
      <permlevel>VIEW</permlevel>
    </permission>
  </permissions>
</toolset>

Notes:

• If no schema file exists and the user declined to create one, omit the <rpcschema> line.
• CustomTool does NOT use scriptdeployments structure.
• NetSuite 2026.1+: Uses custtoolset_ prefix and <toolset> root element. NetSuite 2025.2: Uses customtool_ prefix and <tool> root element. The correct format is determined by target_netsuite_version in ~/.claude/netsuite-connector-config.json.
• Automatically create schema file if not present.
• DEPLOYMENT FIX: CustomTool does NOT support <description>, <isinactive>, <notifyadmins>, <notifyowner>, <defaultfunction>, <title>, <runasrole>, or <allroles> elements; these cause SDF validation errors.
• <exposetoaiconnector>T</exposetoaiconnector> (2026.1+) or <exposeto3rdpartyagents>T</exposeto3rdpartyagents> (2025.2): enables tool for external MCP clients.

Permkey Validation: When generating <permissions> blocks, load the netsuite-sdf-roles-and-permissions skill and validate all <permkey> values against references/permissions.json. Custom record permkeys (customrecord_*) should be validated against the project's own custom record Object XML files. See netsuite-sdf-roles-and-permissions.

---

ClientScript Template

<clientscript scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <loglevel>DEBUG</loglevel>
      <recordtype>[USER_PROVIDED]</recordtype>
      <status>RELEASED</status>
    </scriptdeployment>
  </scriptdeployments>
</clientscript>

Notes:

• ClientScript requires a record type; prompt the user for it.
• Requires SERVERSIDESCRIPTING feature in manifest.xml.
• DEPLOYMENT FIX: ClientScript does not support <runasrole> or <allroles> in deployment.

---

UserEventScript Template

<usereventscript scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <loglevel>DEBUG</loglevel>
      <recordtype>[USER_PROVIDED]</recordtype>
      <!-- SECURITY: Use least-privilege custom role. See 05-security-privacy.md. -->
      <runasrole>[CUSTOM_ROLE_OR_REMOVE]</runasrole>
      <status>RELEASED</status>
      <!-- NOTE: allroles=T selects internal roles only. Add <audslctrole> for external/portal roles. -->
      <allroles>T</allroles>
    </scriptdeployment>
  </scriptdeployments>
</usereventscript>

SECURITY WARNING: Never use <runasrole>ADMINISTRATOR</runasrole> in production. This grants the script full admin privileges, enabling privilege escalation. Always create a custom role with minimum required permissions. See 05-security-privacy.md and netsuite-owasp-secure-coding.

Notes:

• UserEventScript requires a record type; prompt the user for it.
• Entry points are defined in the JS file: beforeLoad, beforeSubmit, afterSubmit.
• Requires SERVERSIDESCRIPTING feature in manifest.xml.
• <allroles>T</allroles> selects internal roles only. If the script needs to be accessible to external/portal roles (for example, Customer Center or Partner Center), add <audslctrole> elements for each external role.

---

Suitelet Template

<suitelet scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <!-- SECURITY: isonline=F requires login. NEVER set to T unless the Suitelet is explicitly designed for anonymous/public access. See Pitfall #135. -->
      <isonline>F</isonline>
      <loglevel>DEBUG</loglevel>
      <!-- SECURITY: Use least-privilege custom role. See 05-security-privacy.md. -->
      <runasrole>[CUSTOM_ROLE_OR_REMOVE]</runasrole>
      <status>RELEASED</status>
      <title>[Human Readable Name]</title>
      <!-- NOTE: allroles=T selects internal roles only. Add <audslctrole> for external/portal roles. -->
      <allroles>T</allroles>
    </scriptdeployment>
  </scriptdeployments>
</suitelet>

Notes:

• Entry point is defined in the JS file: onRequest.
• Requires SERVERSIDESCRIPTING feature in manifest.xml.
• <isonline>F</isonline> is required — this ensures the Suitelet requires authentication. NEVER set <isonline>T</isonline> unless the Suitelet is explicitly designed for anonymous/public access (for example, a customer-facing portal page). Suitelets that create, modify, or query data must ALWAYS require login. While NetSuite defaults to F when omitted, always include it explicitly to prevent accidental exposure. See Pitfall #135.
• <allroles>T</allroles> selects internal roles only — if the script needs to be accessible to external/portal roles (for example, Customer Center or Partner Center), add <audslctrole> elements for each external role.

---

Saved Search Creator Suitelet Pattern

IMPORTANT: SDF cannot create saved searches from scratch — the <savedsearch> XML requires a system-generated binary definition blob. The recommended approach is to include a Saved Search Creator Suitelet in your SDF project that programmatically creates the search via N/search on first run. After the search exists, import it into your project with suitecloud object:import for ongoing SDF lifecycle management. See Pitfall #125 for full details.

Security posture: choose the execution model before generating this Suitelet.

• Default/self-service model: omit <runasrole> so the Suitelet runs as Current Role, keep <allroles>T</allroles> only when every internal role should be allowed to create searches under its own permissions, and do not make the created search public by default.
• Controlled bootstrap model: if elevated permissions are required to create a canonical SDF-managed search, use a least-privilege custom execution role whenever possible. Use <runasrole>ADMINISTRATOR</runasrole> only for a one-time bootstrap with an explicit admin/developer audience, never with <allroles>T</allroles>.

Object XML — requires login, restricted audience, default Current Role execution:

<suitelet scriptid="customscript_create_saved_search">
  <name>Saved Search Creator</name>
  <scriptfile>[/SuiteScripts/[subfolder]/create_saved_search.js]</scriptfile>
  <description>One-time Suitelet to create saved searches that cannot be hand-authored in SDF XML. Run once, then deactivate.</description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_create_saved_search">
      <isdeployed>T</isdeployed>
      <!-- SECURITY: NEVER set isonline=T for Suitelets that create/modify data. This Suitelet creates saved searches — it MUST require login. -->
      <isonline>F</isonline>
      <loglevel>DEBUG</loglevel>
      <!-- SECURITY: Omit runasrole to run as Current Role. If elevated execution is required, use a least-privilege custom role; use ADMINISTRATOR only with explicit admin/developer audience for a one-time bootstrap. -->
      <!-- <runasrole>[CUSTOMROLE_SAVED_SEARCH_CREATOR]</runasrole> -->
      <status>RELEASED</status>
      <title>Saved Search Creator</title>
      <!-- SECURITY: Do not combine elevated execution with allroles=T. Use explicit roles for privileged creator Suitelets. -->
      <allroles>F</allroles>
      <audslctrole>[CUSTOMROLE_SDF_DEVELOPER]</audslctrole>
    </scriptdeployment>
  </scriptdeployments>
</suitelet>

SuiteScript 2.1 — create_saved_search.js:

/**
 * @NApiVersion 2.1
 * @NScriptType Suitelet
 * @NModuleScope SameAccount
 */
define(['N/search', 'N/ui/serverWidget'], (search, serverWidget) => {

    const onRequest = (context) => {
        if (context.request.method === 'GET') {
            // Show form with a button to create the search.
            const form = serverWidget.createForm({ title: 'Saved Search Creator' });
            form.addSubmitButton({ label: 'Create Saved Search' });
            context.response.writePage(form);
            return;
        }

        // POST. Create the saved search.
        const savedSearch = search.create({
            type: search.Type.TRANSACTION,
            title: 'SG Open Sales Orders - SDF Deployed',
            id: 'customsearch_sdftest_open_so',
            filters: [
                search.createFilter({ name: 'type', operator: search.Operator.ANYOF, values: ['SalesOrd'] }),
                search.createFilter({ name: 'status', operator: search.Operator.ANYOF, values: ['SalesOrd:B'] })
            ],
            columns: [
                search.createColumn({ name: 'internalid', label: 'Internal ID' }),
                search.createColumn({ name: 'trandate', label: 'Date' }),
                search.createColumn({ name: 'type', label: 'Type' }),
                search.createColumn({ name: 'tranid', label: 'Document Number' }),
                search.createColumn({ name: 'entity', label: 'Customer' }),
                search.createColumn({ name: 'memo', label: 'Memo' }),
                search.createColumn({ name: 'amount', label: 'Amount' }),
                search.createColumn({ name: 'statusref', label: 'Status' })
            ]
        });

        const searchId = savedSearch.save();

        // SECURITY: Do not make generated searches public by default.
        // If broader visibility is required, import the search into SDF first, then set
        // the approved audience/public flag through the normal review process.

        context.response.write(`Saved search created successfully. Internal ID: ${searchId}`);
    };

    return { onRequest };
});

After the search is created:

1. Run suitecloud object:import --type savedsearch --scriptid customsearch_sdftest_open_so --destinationfolder /Objects --excludefiles.
2. The imported <savedsearch> XML with the binary blob is now managed by SDF.
3. Set <isinactive>T</isinactive> on the Suitelet to deactivate it (or remove it from the project entirely).
4. Review the imported saved search audience. Do not mark it public unless the business owner explicitly approves public visibility.

Key field mappings for common transaction searches:

Filter Value	Meaning
SalesOrd	Sales Order transaction type
SalesOrd:B	Pending Fulfillment status
SalesOrd:A	Pending Approval status
SalesOrd:F	Billed status
statusref	Human-readable status text (vs status which shows codes)
entity	Customer field on transactions
tranid	Document Number

---

Restlet Template

<restlet scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <loglevel>DEBUG</loglevel>
      <status>RELEASED</status>
      <title>[Human Readable Name]</title>
    </scriptdeployment>
  </scriptdeployments>
</restlet>

Notes:

• Entry points are defined in the JS file: get, post, put, delete.
• Requires SERVERSIDESCRIPTING feature in manifest.xml.
• DEPLOYMENT FIX: Restlet does NOT support <runasrole> or <allroles> in deployment.

---

Portlet Template

<portlet scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <portlettype>HTML</portlettype>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyemails></notifyemails>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <loglevel>DEBUG</loglevel>
      <status>RELEASED</status>
      <title>[Human Readable Name]</title>
      <!-- NOTE: allroles=T selects internal roles only. Add <audslctrole> for external/portal roles. -->
      <allroles>T</allroles>
    </scriptdeployment>
  </scriptdeployments>
</portlet>

Portlet Type Selection Logic:

1. Default to HTML. Always use HTML unless the user explicitly requests a different type.
2. Change portlettype when user specifies:
   • The user mentions "form portlet" or "data entry" → use FORM.
   • The user mentions "list portlet" or "table/grid" → use LIST.
   • The user mentions "links portlet" or "navigation" → use LINKS.
3. If unclear, ask the user which type they need.

Portlet Type	User Keywords	SuiteScript Methods
HTML (default)	"html", "content", "display", "custom"	portlet.html = "..."
FORM	"form", "input", "submit", "data entry"	portlet.addField(), portlet.setSubmitButton()
LIST	"list", "table", "grid", "columns", "rows"	portlet.addColumn(), portlet.addRow()
LINKS	"links", "navigation", "menu"	portlet.addLine(), portlet.addRow()

Notes:

• Portlet requires SERVERSIDESCRIPTING feature in manifest.xml (like Suitelet and Restlet).
• Portlet omits <runasrole> intentionally - per NetSuite documentation, omitting this tag causes the script to run as the current user's role (the user viewing the dashboard).
• The <portlettype> element is at the portlet level, NOT inside scriptdeployment.
• <allroles>T</allroles> selects internal roles only — if the portlet needs to be accessible to external/portal roles (for example, Customer Center or Partner Center), add <audslctrole> elements for each external role.

---

BundleInstallationScript Template

<bundleinstallationscript scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
</bundleinstallationscript>

Notes:

• BundleInstallationScript does NOT use scriptdeployments structure.
• DEPLOYMENT FIX: Entry point function XML elements (<beforeinstallfunction>, <afterinstallfunction>, etc.) are NOT supported and will be ignored - entry points are auto-detected from the JavaScript file.
• Requires SERVERSIDESCRIPTING feature in manifest.xml.

---

MapReduceScript Template

<mapreducescript scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <loglevel>DEBUG</loglevel>
      <status>NOTSCHEDULED</status>
      <title>[Human Readable Name]</title>
    </scriptdeployment>
  </scriptdeployments>
</mapreducescript>

Notes:

• Map/Reduce scripts have 4 entry points defined in the JS file: getInputData, map, reduce, summarize.
• The XML does NOT specify entry point functions - they are detected from the script.
• Requires SERVERSIDESCRIPTING feature in manifest.xml.
• DEPLOYMENT FIX: MapReduceScript uses <status>NOTSCHEDULED</status> (NOT "RELEASED").
• DEPLOYMENT FIX: MapReduceScript does NOT support <runasrole> or <allroles> in deployment.

---

MassUpdateScript Template

<massupdatescript scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <loglevel>DEBUG</loglevel>
      <recordtype>[USER_PROVIDED]</recordtype>
      <status>RELEASED</status>
    </scriptdeployment>
  </scriptdeployments>
</massupdatescript>

Notes:

• Like ClientScript and UserEventScript, MassUpdateScript requires a record type.
• Prompt the user: "What record type should this MassUpdateScript be deployed to?".
• Requires SERVERSIDESCRIPTING feature in manifest.xml.
• DEPLOYMENT FIX: <defaultfunction> element is NOT supported and will be ignored - entry point is auto-detected.
• DEPLOYMENT FIX: MassUpdateScript does NOT support <title>, <runasrole>, or <allroles> in deployment.

---

ScheduledScript Template

<scheduledscript scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <loglevel>DEBUG</loglevel>
      <status>NOTSCHEDULED</status>
      <title>[Human Readable Name]</title>
    </scriptdeployment>
  </scriptdeployments>
</scheduledscript>

Notes:

• Schedule/recurrence is configured in NetSuite UI after deployment, not in XML.
• Requires SERVERSIDESCRIPTING feature in manifest.xml.
• DEPLOYMENT FIX: ScheduledScript uses <status>NOTSCHEDULED</status> (NOT "RELEASED").
• DEPLOYMENT FIX: <defaultfunction> element is NOT supported and will be ignored - entry point is auto-detected.
• DEPLOYMENT FIX: ScheduledScript does NOT support <runasrole> or <allroles> in deployment.

---

SDFInstallationScript Template

<sdfinstallationscript scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
</sdfinstallationscript>

Notes:

• IMPORTANT: SDFInstallationScript does NOT have entry point function XML elements like BundleInstallationScript.
• The entry point is run and is defined in the JavaScript file, NOT in the XML.
• Does NOT use scriptdeployments structure.
• To trigger the script, reference it in deploy.xml with <script> and <run> elements.
• Execution timing is controlled by placement in deploy.xml (beginning = before install, end = after install).
• Requires SERVERSIDESCRIPTING feature in manifest.xml.

run(context) Entry Point — Context Object:

Property	Type	Description
context.fromVersion	string | null	Version being upgraded from. null on fresh install. Always check this to distinguish install vs upgrade.
context.toVersion	string	Version being installed/upgraded to.

/**
 * @NApiVersion 2.1
 * @NScriptType SDFInstallationScript
 */
define(['N/record', 'N/log'], (record, log) => {

    const run = (context) => {
        if (!context.fromVersion) {
            // Fresh install. Create initial data, set defaults
            log.audit({ title: 'Fresh Install', details: `Version ${context.toVersion}` });
        } else {
            // Upgrade. Run migration logic
            log.audit({
                title: 'Upgrade',
                details: `${context.fromVersion} -> ${context.toVersion}`
            });
            // Example: migrate data, update custom records, etc.
        }
    };

    return { run };
});

Example deploy.xml reference:

<deploy>
  <configuration>
    <path>~/Objects/customscript_[filename].xml</path>
  </configuration>
  <files>
    <!-- other files -->
  </files>
  <objects>
    <!-- other objects -->
  </objects>
  <!-- Place at end for after-install behavior -->
  <script>
    <path>~/Objects/customscript_[filename].xml</path>
    <run>customdeploy_[filename]</run>
  </script>
</deploy>

---

application.xml — Pre-Uninstall Lifecycle Hook

application.xml is an optional SDF file that registers SDFInstallationScripts to run at specific points in the SuiteApp lifecycle. The most common use is <beforeundeploy>, running cleanup logic before uninstall begins.

Comparison: BundleInstallationScript vs application.xml

Aspect	BundleInstallationScript	application.xml
Mechanism	JavaScript entry points (beforeInstall, afterInstall, etc.)	SDFInstallationScript referenced in XML
Timing	Runs AFTER the lifecycle event	<beforeundeploy> runs BEFORE uninstall begins
Use case	Install/update/uninstall logic in JS	Pre-uninstall cleanup (API tokens, webhooks, data)
Deployment	Part of script object XML	Separate application.xml file

File location:

src/
  application.xml        ← at project root level
  Objects/
    customscript_my_cleanup.xml
  FileCabinet/
    SuiteScripts/
      my_cleanup.js

application.xml Structure:

<?xml version="1.0" encoding="UTF-8"?>
<application>
  <hooks>
    <beforeundeploy>
      <!-- Reference an SDFInstallationScript Object XML and its deployment. -->
      <script>
        <path>~/Objects/customscript_[uninstall_cleanup].xml</path>
        <run>customdeploy_[uninstall_cleanup]</run>
      </script>
    </beforeundeploy>
  </hooks>
</application>

When to use application.xml:

• Your SuiteApp creates API tokens or OAuth credentials that must be revoked before removal.
• Your SuiteApp registers webhooks or external subscriptions that must be de-registered.
• Your SuiteApp creates data in external systems that must be cleaned up before the SuiteApp is removed.
• You need to archive or migrate data BEFORE the SuiteApp's custom records are deleted.

When NOT to use:

• General install/update logic → use BundleInstallationScript instead.
• Post-uninstall cleanup → not possible (SuiteApp is already gone).

---

WorkflowActionScript Template

<workflowactionscript scriptid="customscript_[filename]">
  <name>[Human Readable Name]</name>
  <scriptfile>[/SuiteScripts/[subfolder]/[filename].js]</scriptfile>
  <description></description>
  <isinactive>F</isinactive>
  <notifyadmins>F</notifyadmins>
  <notifyowner>T</notifyowner>
  <scriptdeployments>
    <scriptdeployment scriptid="customdeploy_[filename]">
      <isdeployed>T</isdeployed>
      <loglevel>DEBUG</loglevel>
      <recordtype>[USER_PROVIDED]</recordtype>
      <status>RELEASED</status>
    </scriptdeployment>
  </scriptdeployments>
</workflowactionscript>

Notes:

• Can optionally have <returntype> and <returnrecordtype> for returning values to workflow.
• If the script returns a value to a workflow field, add:

  <returntype>SELECT</returntype>
  <returnrecordtype>[customrecordtype_name or customlist_name]</returnrecordtype>
  

• Requires SERVERSIDESCRIPTING feature in manifest.xml
• DEPLOYMENT FIX: WorkflowActionScript REQUIRES <recordtype> in deployment; prompt user for record type.
• DEPLOYMENT FIX: <defaultfunction> element is NOT supported and will be ignored; entry point is auto-detected.
• DEPLOYMENT FIX: WorkflowActionScript does NOT support <title>, <runasrole>, or <allroles> in deployment.

---

Workflow Object XML Template (SuiteFlow)

IMPORTANT: This is NOT a script type, it's a workflow object (customworkflow) that defines SuiteFlow workflows as SDF-deployable XML. Workflows have states, transitions, actions, and conditions; no .js script file needed (unless using <customaction> which references a WorkflowActionScript).

<workflow scriptid="customworkflow_[name]">
  <name>[Human Readable Name]</name>
  <description>[PURPOSE]</description>
  <recordtypes>[RECORD_TYPE]</recordtypes>
  <initoncreate>T</initoncreate>
  <initonvieworupdate>F</initonvieworupdate>
  <inittriggertype>BEFORELOAD</inittriggertype>
  <initcontexts></initcontexts>
  <initeventtypes></initeventtypes>
  <initsavedsearchcondition></initsavedsearchcondition>
  <isinactive>F</isinactive>
  <islogenabled>T</islogenabled>
  <keephistory>ONLYWHENTESTING</keephistory>
  <releasestatus>TESTING</releasestatus>
  <runasadmin>F</runasadmin>
  <workflowstates>
    <workflowstate scriptid="workflowstate_[state_name]">
      <name>[State Display Name]</name>
      <description></description>
      <donotexitworkflow>F</donotexitworkflow>
      <positionx>243</positionx>
      <positiony>133</positiony>
      <workflowactions triggertype="[TRIGGER_TYPE]">
        <!-- Action elements here (see Action Type Reference below) -->
      </workflowactions>
      <workflowtransitions>
        <workflowtransition scriptid="workflowtransition_[name]">
          <tostate>[scriptid=customworkflow_[name].workflowstate_[target]]</tostate>
          <triggertype>AFTERSUBMIT</triggertype>
          <initcondition>
            <formula></formula>
            <type>VISUAL_BUILDER</type>
          </initcondition>
        </workflowtransition>
      </workflowtransitions>
    </workflowstate>
  </workflowstates>
</workflow>

Trigger Types for <workflowactions> and <workflowtransitions>:

• BEFORELOAD — Before record loads (server, UI + API)
• BEFORESUBMIT — Before record saves (server)
• AFTERSUBMIT — After record saves (server)
• ONENTRY — When entering the state (server, runs with first server trigger)
• ONEXIT — When exiting the state (server)
• BEFOREUISUBMIT — Before UI submit (client-side only)
• AFTERUISUBMIT — After UI submit (client-side only)

Workflow Action Type Reference:

Action	XML Element	Key Properties
Set Field Value	<setfieldvalueaction>	<field>, <valuetype>, <valuetext> / <valueselect>
Set Field Mandatory	<setfieldmandatoryaction>	<field>, <ismandatory>
Set Field Display	<setfielddisplayaction>	<field>, <isdisplayed>
Set Field Display Type	<setfielddisplaytypeaction>	<field>, <displaytype> (NORMAL, HIDDEN, READONLY, DISABLED)
Send Email	<sendemailaction>	<recipienttype>, <recipientemail>, <sender>, <template>
Create Record	<createrecordaction>	<recordtype>, field mappings via <initcondition>
Create Line	<createlineaction>	<sublist>, field mappings
Transform Record	<transformrecordaction>	<recordtype>, <resultfield>
Add Button	<addbuttonaction>	<label>, triggers transition on click
Remove Button	<removebuttonaction>	<buttonid>
Lock Record	<lockrecordaction>	(no special props)
Go To Page	<gotopageaction>	<targetpage>
Go To Record	<gotorecordaction>	<recordtype>, <recordid>
Custom Action	<customaction>	<scriptid> references a WorkflowActionScript
Return User Error	<returnusererroraction>	<errorfield>, <errormessage>
Show Message	<showmessageaction>	<messagetext>
Confirm	<confirmaction>	<messagetext>
Subscribe To Record	<subscribetorecordaction>	<recipient>
Initiate Workflow	<initiateworkflowaction>	<workflowid>
Scheduled Action	<scheduledaction>	<schedulemode>, <scheduledelay>

Action XML Pattern (Common Structure):

<workflowactions triggertype="BEFORESUBMIT">
  <setfieldvalueaction scriptid="workflowaction_set_status">
    <field>STDBODYAPPROVALSTATUS</field>
    <valuetype>STATIC</valuetype>
    <valueselect>1</valueselect>
    <isinactive>F</isinactive>
    <initcondition>
      <formula>&lt;CRITERIA&gt;</formula>
      <type>VISUAL_BUILDER</type>
      <parameters>
        <parameter>
          <name>Amount</name>
          <value>[amount]</value>
        </parameter>
      </parameters>
    </initcondition>
  </setfieldvalueaction>
</workflowactions>

Add Button + Transition Pattern (Approval Workflow):

<workflowstate scriptid="workflowstate_pending">
  <name>Pending Approval</name>
  <donotexitworkflow>F</donotexitworkflow>
  <positionx>243</positionx>
  <positiony>133</positiony>
  <workflowactions triggertype="BEFORELOAD">
    <addbuttonaction scriptid="workflowaction_approve_btn">
      <label>Approve</label>
      <isinactive>F</isinactive>
    </addbuttonaction>
    <addbuttonaction scriptid="workflowaction_reject_btn">
      <label>Reject</label>
      <isinactive>F</isinactive>
    </addbuttonaction>
  </workflowactions>
  <workflowtransitions>
    <workflowtransition scriptid="workflowtransition_to_approved">
      <tostate>[scriptid=customworkflow_so_approval.workflowstate_approved]</tostate>
      <triggertype>BEFORESUBMIT</triggertype>
      <buttonaction>[scriptid=customworkflow_so_approval.workflowstate_pending.workflowaction_approve_btn]</buttonaction>
    </workflowtransition>
    <workflowtransition scriptid="workflowtransition_to_rejected">
      <tostate>[scriptid=customworkflow_so_approval.workflowstate_rejected]</tostate>
      <triggertype>BEFORESUBMIT</triggertype>
      <buttonaction>[scriptid=customworkflow_so_approval.workflowstate_pending.workflowaction_reject_btn]</buttonaction>
    </workflowtransition>
  </workflowtransitions>
</workflowstate>

Workflow Notes & Pitfalls:

• Script ID: customworkflow_ prefix (15 chars) → 25 chars remaining for name. 40 char max total.
• State script IDs: workflowstate_ prefix, scoped within the workflow.
• Action script IDs: workflowaction_ prefix, scoped within the state.
• Transition script IDs: workflowtransition_ prefix, scoped within the state.
• Cross-references: Use bracket notation [scriptid=customworkflow_name.workflowstate_target] for <tostate> and <buttonaction>.
• releasestatus: ALWAYS deploy as TESTING first, never RELEASED on first deploy. Promote to RELEASED only after validation.
• keephistory: Use ONLYWHENTESTING for development, ALWAYS for audit-critical workflows.
• runasadmin: Only effective when the deployer has admin role; ignored for non-admin deployers.
• PITFALL — Trigger order: If workflow initiates on AFTERSUBMIT, BEFORELOAD actions in the entry state won't execute on the triggering transaction.
• PITFALL — ONENTRY timing: ONENTRY does NOT execute independently, it runs with the first server trigger (BEFORELOAD, BEFORESUBMIT, or AFTERSUBMIT) after state entry.
• PITFALL — UE script conflicts: Workflow and User Event script execution order is NOT guaranteed on the same record — avoid both modifying the same field.
• PITFALL — Workflow custom fields: Fields created as "Workflow" type cannot be used in client-side actions (BEFOREUISUBMIT, AFTERUISUBMIT).
• PITFALL — NOTINITIATING: Replaced NOTRUNNING as the non-running status, both values accepted for backward compatibility.
• No manifest feature needed: Workflows deploy as objects, not scripts, no SERVERSIDESCRIPTING feature required.

---

SPA (Single Page Application) Template

IMPORTANT: SPA scripts use a DIFFERENT object type than traditional scripts. Both SpaServerScript and SpaClientScript are defined within a SINGLE <singlepageapp> object.

CRITICAL: Always reference the Oracle SPA samples for working examples. The local SuiteCloud CLI validator and the server-side deployment use DIFFERENT XML element names — always validate locally before deploying.

<!-- SuiteApp project: folder inside /SuiteApps/<publisherid>.<projectid>/ -->
<singlepageapp scriptid="custspa_[spa_name]">
  <name>[Human Readable Name]</name>
  <description>[Optional description]</description>
  <url>[custom-url-path]</url>
  <folder>[/SuiteApps/<publisherid>.<projectid>/[spa_folder]/]</folder>
  <clientscriptfile>[/SuiteApps/<publisherid>.<projectid>/[spa_folder]/SpaClient.js]</clientscriptfile>
  <serverscriptfile>[/SuiteApps/<publisherid>.<projectid>/[spa_folder]/SpaServer.js]</serverscriptfile>
  <assetsfolder>[/SuiteApps/<publisherid>.<projectid>/[spa_folder]/assets/]</assetsfolder>
  <loglevel>DEBUG</loglevel>
  <audienceallroles>F</audienceallroles>
  <executeas></executeas>
</singlepageapp>

SPA XML Field Reference:

Field	Required	Max Chars	Constraints
scriptid	Yes	28	Prefix: custspa_, lowercase, alphanumeric + underscore
name	Yes	1000	-
url	Yes	1000	Lowercase, unique across ALL SPAs in account, no reserved URL chars
folder	Yes	99	Bracket notation, inside SuiteApps (for SuiteApp projects)
clientscriptfile	Yes	199	Bracket notation, .js file, inside SPA folder
serverscriptfile	Yes	199	Bracket notation, .js file, inside SPA folder
description	No	1000	-
assetsfolder	No	99	Bracket notation, inside SPA folder
audienceallroles	No	-	T or F, default: F. WARNING: T selects internal roles only and may cause deployment failures on some accounts, prefer F with explicit audienceroles
audienceroles	No	-	Pipe-separated role references (for example, ADMINISTRATOR|DEVELOPER)
loglevel	No	-	DEBUG, AUDIT, ERROR, EMERGENCY
executeas	No	-	Empty string for current role. Cannot be ADMINISTRATOR

SpaServerScript Entry Point (AMD — SuiteCloud CLI compatible):

/**
 * @NApiVersion 2.1
 * @NScriptType SpaServerScript
 */
define(["require", "exports"], function (require, exports) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    exports.initializeSpa = void 0;
    const initializeSpa = (scriptContext) => {
        scriptContext.addStyleSheet({ relativePath: '/styles.css' });
    };
    exports.initializeSpa = initializeSpa;
});

SpaClientScript Entry Point (AMD — SuiteCloud CLI compatible):

/**
 * @NApiVersion 2.1
 */
define(["require", "exports"], function (require, exports) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    exports.run = void 0;
    const run = (scriptContext) => {
        // Initialize the SPA client application
        // Load root component and render
    };
    exports.run = run;
});

Notes:

• SPA uses custspa_ prefix (8 chars) instead of customscript_.
• Maximum scriptid length is 28 characters total.
• Both client and server scripts are referenced in the SAME object XML.
• SPA scripts do NOT have separate deployment records.
• Requires SERVERSIDESCRIPTING feature in manifest.xml.
• SPA primarily supported in SuiteApp projects; Account Customization support added in 2025.1.
• SpaServerScript MUST export initializeSpa — NOT onAction, onRequest, or other entry points.
• SpaClientScript MUST export run — NOT start or other entry points. No @NScriptType annotation needed.
• SPA server scripts should be minimal (add stylesheets, validate roles) — business logic belongs in separate library modules called from the client via server actions.
• The url field must be globally unique across ALL SPAs in the account — collisions cause cryptic deployment errors.

SPA Deployment Pitfalls:

• "Items you have requested in the record have been deleted" — This cryptic error during SPA creation can be caused by: (1) URL collision with existing SPA, (2) audienceallroles=T referencing deleted roles in 2025.1+ accounts, (3) publisher restrictions on STDDEMO/demo accounts, (4) wrong entry point names in server/client scripts. Always deploy non-SPA objects first, then add the SPA in a subsequent deploy.
• Failed SPA deployments leave ghost installs — A failed deploy that includes the SPA will leave the SuiteApp in FAILED status on the Installed SuiteApps page. You MUST uninstall before retrying. Consider deploying without the SPA first to establish a clean base.
• Oracle samples vs local validator discrepancy — Oracle GitHub samples use element names like <clientscript>, <serverscript>, <assetfolder> (without brackets), but the local SuiteCloud CLI validator requires <clientscriptfile>, <serverscriptfile>, <assetsfolder> with bracket notation. Always validate locally first.

SPA Documentation:

• Single Page Applications Overview
• SPA XML Definitions
• SPA Server Script
• SPA Client Script
• singlepageapp XML Reference
• SPA XML Definition Example
• Oracle SPA Samples (GitHub)

---

XML Templates by Script Type

File Location:

/Objects/[script_id].xml

Examples:

• /Objects/custtoolset_getcampaignpreflight.xml
• /Objects/customscript_form_validator.xml
• /Objects/customscript_update_customer.xml

Secret Object XML (imported reference, not secret value):

• First create the secret in NetSuite UI.
• Mark it available to the SuiteApp when the project needs to import it.
• Import the secret object into the project as /Objects/custsecret_vendor_api_token.xml (src/Objects/custsecret_vendor_api_token.xml in a standard SuiteCloud project layout).
• Secret object XML contains only the reference:

<secret scriptid="custsecret_vendor_api_token"/>

CRITICAL: Object Filename 40-Character Limit

• Object filename = script ID + .xml.
• The script ID portion (before .xml) MUST be ≤ 40 characters.
• This is the same 40-character limit used for the scriptid attribute in the XML.
• All filenames must be lowercase.
• Hyphens must be converted to underscores.
• If the script ID would exceed 40 chars, truncate the filename portion to fit.

Object Filename Formula:

Object filename = [script_id].xml
Where script_id ≤ 40 characters.

Example:
  Script ID: customscript_form_validator (27 chars) ✓
  Object file: customscript_form_validator.xml

---

Quick Reference: Character Limits

Script ID Prefixes and Maximum Filename Lengths:

Script Type	Prefix	Prefix Length	Max Filename	Example
BundleInstallationScript	customscript_	13 chars	27 chars	customscript_bundle_install
ClientScript	customscript_	13 chars	27 chars	customscript_form_validator
CustomTool	custtoolset_	12 chars	28 chars	custtoolset_campaigntool
MapReduceScript	customscript_	13 chars	27 chars	customscript_mr_process
MassUpdateScript	customscript_	13 chars	27 chars	customscript_mu_cleanup
Portlet	customscript_	13 chars	27 chars	customscript_sales_dashboard
Restlet	customscript_	13 chars	27 chars	customscript_api_handler
ScheduledScript	customscript_	13 chars	27 chars	customscript_nightly_job
SDFInstallationScript	customscript_	13 chars	27 chars	customscript_sdf_install
SpaServerScript	custspa_	8 chars	20 chars	custspa_home
SpaClientScript	custspa_	8 chars	20 chars	custspa_home
Suitelet	customscript_	13 chars	27 chars	customscript_portal_page
UserEventScript	customscript_	13 chars	27 chars	customscript_update_customer
WorkflowActionScript	customscript_	13 chars	27 chars	customscript_wf_action
Workflow (SuiteFlow)	customworkflow_	15 chars	25 chars	customworkflow_so_approval

Deployment ID Prefixes: Same pattern as script IDs, but use customdeploy_ prefix instead:

• customdeploy_[filename] (40 char max, 13 char prefix → 27 chars for filename)

---

Script Type Mapping Reference

@NScriptType Value	XML Element	Script ID Prefix	Max Filename Length	Has Deployment	Needs RecordType	Status Value
BundleInstallationScript	<bundleinstallationscript>	customscript_ (13)	27 chars	No	No	N/A
ClientScript	<clientscript>	customscript_ (13)	27 chars	Yes	Yes	RELEASED
CustomTool	<toolset>	custtoolset_ (12)	28 chars	No	No	N/A
MapReduceScript	<mapreducescript>	customscript_ (13)	27 chars	Yes	No	NOTSCHEDULED
MassUpdateScript	<massupdatescript>	customscript_ (13)	27 chars	Yes	Yes	RELEASED
Portlet	<portlet>	customscript_ (13)	27 chars	Yes	No	RELEASED
Restlet	<restlet>	customscript_ (13)	27 chars	Yes	No	RELEASED
ScheduledScript	<scheduledscript>	customscript_ (13)	27 chars	Yes	No	NOTSCHEDULED
SDFInstallationScript	<sdfinstallationscript>	customscript_ (13)	27 chars	No	No	N/A
SpaServerScript	<singlepageapp>	custspa_ (8)	20 chars	No*	No	N/A
SpaClientScript	<singlepageapp>	custspa_ (8)	20 chars	No*	No	N/A
Suitelet	<suitelet>	customscript_ (13)	27 chars	Yes	No	RELEASED
UserEventScript	<usereventscript>	customscript_ (13)	27 chars	Yes	Yes	RELEASED
WorkflowActionScript	<workflowactionscript>	customscript_ (13)	27 chars	Yes	Yes	RELEASED
N/A (SuiteFlow)	<workflow>	customworkflow_ (15)	25 chars	No (states, not deployments)	Yes	TESTING

*SPA scripts don't have traditional deployments - they're part of the singlepageapp object which defines both client and server scripts together.

---

Basic CustomTool Schema Template

When creating a schema file for CustomTool, use this template:

{
  "tools": [
    {
      "name": "[toolFunctionName]",
      "description": "[Description of what this tool does]",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "required": []
      },
      "annotations": {
        "title": "[Human Readable Title]",
        "readOnlyHint": true,
        "idempotentHint": true,
        "destructiveHint": false,
        "openWorldHint": false
      }
    }
  ]
}

CustomTool JavaScript Entry Points

The schema name and the JS exported function name must match exactly (case-sensitive). If they don't, the tool silently fails to route — no error, the AI agent simply cannot call it.

/**
 * @NApiVersion 2.1
 * @NScriptType CustomTool
 * @NModuleScope SameAccount
 */
define(['N/log'], (log) => {
    const TOOL_NAME = 'myToolFunction';
    const getRequestId = (params) => {
        const candidate = String((params && params.requestId) || '');
        return /^[A-Za-z0-9_-]{1,80}$/.test(candidate) ? candidate : `ct_${Date.now()}`;
    };

    const myToolFunction = async (params) => {
        params = params || {};
        const startTime = Date.now();
        const requestId = getRequestId(params);
        log.audit('Tool Start', `tool=${TOOL_NAME} requestId=${requestId}`);
        try {
            // Params is a flat object; keys match schema inputSchema.properties.
            // Complex params arrive as JSON strings; always JSON.parse() them.
            const result = doWork(params);
            const rowCount = Array.isArray(result) ? result.length : 1;
            log.audit('Tool Complete', `tool=${TOOL_NAME} requestId=${requestId} rows=${rowCount} elapsedMs=${Date.now() - startTime}`);
            return { success: true, requestId, data: result };
        } catch (e) {
            log.error('Tool Error', `tool=${TOOL_NAME} requestId=${requestId} elapsedMs=${Date.now() - startTime}`);
            return {
                success: false,
                requestId,
                error: {
                    type: 'UNEXPECTED_ERROR',
                    message: 'Unexpected tool execution error. Use requestId to correlate with logs.'
                }
            };
        }
    };
    return { myToolFunction };  // ← Export name MUST match schema tools[0].name.
});

Key differences from other script types:

• No context object — receives only params (flat key-value object from schema).
• Return value is the response — no context.response.write(), just return a serializable object.
• Never throw exceptions — always catch and return { success: false, error: { type, message } }.
• Governance: 1,000 units / 300 seconds — same as Suitelet.

Helper modules use relative imports with no @NScriptType annotation:

// lib/my_helpers.js — plain AMD module, no script annotations.
define(['N/search'], (search) => {
    const findRecords = (filters) => { /* ... */ };
    return { findRecords };
});

Schema Design Best Practices

Guideline	Detail
Complex params	Declare as "type": "string" with description "JSON string containing…" — JSON.parse() in JS. NetSuite runtime may not pass nested objects cleanly.
Descriptions	Write comprehensive, multi-sentence descriptions. AI agents rely entirely on the description to understand the tool. Include parameter format examples inline.
required array	Always specify which fields are required — agents use this to validate before calling.
readOnlyHint	true for query/validation tools (safe to retry). false for create/update tools.
idempotentHint	true if calling N times = same result as 1. false for create operations.
destructiveHint	false for read-only or non-destructive tools. Omit (or true) for tools that create/update/delete — default is true. AI agents use this to decide whether to seek confirmation.
openWorldHint	false for tools that only access NetSuite data (closed system).
Query parameters	Never expose raw SuiteQL, table names, field names, joins, WHERE fragments, or ORDER BY text through MCP schemas. Use allowlisted dataset IDs, fixed query templates, parameter binding, filter validation, field/table allowlists, and sensitive-record exclusions.

MCP Integration

CustomTools become MCP tools automatically through this lifecycle:

1. Deploy via SDF — suitecloud project:deploy.
2. Register — NetSuite reads the RPC schema and registers the tool.
3. Discover — MCP servers query available tools; schema maps directly to MCP definition.
4. Invoke — AI agent calls the tool; NetSuite routes to the JS function matching schema.tools[0].name.
5. Return — JS return value is serialized to JSON and sent back to the agent.

The <exposetoaiconnector> flag controls visibility (renamed from <exposeto3rdpartyagents> in NetSuite 2026.1 — value semantics unchanged):

• T — available to external MCP clients AND NetSuite AI
• F — only visible to NetSuite's built-in AI assistant

The RPC schema IS the MCP tool definition — name, description, inputSchema, and annotations map 1:1. What you write in the schema is exactly what the AI agent sees.

CustomTool Error Handling

Always return structured errors — never let exceptions propagate:

// ✅ Correct. Structured error return.
return {
    success: false,
    error: { type: 'VALIDATION_ERROR', message: 'customerId is required' }
};

// ❌ Wrong. Thrown exception gives agent a generic unhelpful error.
throw error.create({ name: 'VALIDATION_ERROR', message: 'customerId is required' });

For governance-aware error handling and complete examples, see the CustomTool Runtime Appendix.

---

Error Handling

Missing JSDoc or @NScriptType

If the .js file doesn't contain a valid @NScriptType:

Error: Cannot determine script type.
Please ensure your SuiteScript file has a JSDoc comment with @NScriptType annotation.

Example:
/**
 * @NApiVersion 2.1
 * @NScriptType ClientScript
 */

File Already Exists

If an object XML file already exists:

An object file already exists for this script:
[path/to/existing/file.xml]

Would you like to:
1. Overwrite the existing file
2. Cancel
3. View the existing file

Invalid Record Type

If the user provides an invalid record type format:

Record type should be either:
- A standard record name (lowercase): customer, salesorder, invoice
- A custom record reference: [customrecord_yourname]

Please try again.

---

Example Usage Scenarios

Scenario 1: Creating Object for New CustomTool

User: "I just created a new CustomTool script at /SuiteScripts/tools/emailvalidator.js. Can you create the object file?"

Assistant:
1. Reads /SuiteScripts/tools/emailvalidator.js.
2. Parses @NScriptType CustomTool.
3. Checks for /SuiteScripts/tools/emailvalidator_schema.json.
4. Asks: "Would you like to create a schema file? (Y/N)".
5. Generates /Objects/custtoolset_emailvalidator.xml with proper structure (2026.1+ naming).
6. If the user said yes, also create `emailvalidator_schema.json`.

Scenario 2: Creating Object for ClientScript

User: "Create an object for my client script at /SuiteScripts/customer_validation.js".

Assistant:
1. Reads the file.
2. Parses @NScriptType ClientScript.
3. Asks: "What record type should this ClientScript be deployed to?".
4. User responds: "customer".
5. Generates /Objects/customscript_customer_validation.xml.
6. Sets <recordtype>customer</recordtype> in deployment.

Scenario 3: Batch Creation

User: "I have 5 new scripts in /SuiteScripts/batch/ that need objects created".

Assistant:
1. Lists all .js files in /SuiteScripts/batch/.
2. For each file:
   - Parse script type.
   - Gather required info.
   - Generate object.
3. Provides summary of created files.

---

Implementation Checklist

When implementing this skill, ensure:

Object XML Generation

• JSDoc parser correctly identifies @NScriptType.
• Filename normalization (lowercase, underscores, ≤40 chars).
• Script IDs match normalized filename exactly.
• Deployment IDs follow naming conventions.
• Human-readable names are properly formatted.
• XML structure matches script type.
• Secrets are created in NetSuite UI first, then imported into /Objects/ as custsecret_*.xml reference objects.
• Secret object XML contains only <secret scriptid="custsecret_*"/> and never stores secret values in the project.
• Script parameters and <scriptparametervalue> are used only for non-confidential configuration, never for credentials or other secrets.
• CRITICAL: All <scriptfile> and <rpcschema> paths wrapped in square brackets [].
• CRITICAL: Use literal < and > for XML tags, NEVER use < or >.

Deployment Configuration

• <runasrole> ONLY for: UserEventScript, Suitelet (Portlet intentionally omits to run as current user)
• <runasrole> NOT supported for: ClientScript, Restlet, ScheduledScript, MapReduceScript, MassUpdateScript, WorkflowActionScript
• <allroles> ONLY for: UserEventScript, Suitelet, Portlet
• <status>NOTSCHEDULED for: ScheduledScript, MapReduceScript
• <status>RELEASED for: All other script types with deployments
• Required fields are prompted for (recordtype for ClientScript, UserEventScript, MassUpdateScript, WorkflowActionScript).

Manifest and Schema

• Schema files are auto-created for CustomTool.
• manifest.xml updated with SERVERSIDESCRIPTING feature for all server-side scripts.
• Files are created in correct /Objects/ location.
• <permkey> values validated against netsuite-sdf-roles-and-permissions (exact ID match required).

Best Practices Enforcement

• Check for N+1 query patterns and recommend batch operations.
• Recommend Suitelet-as-API pattern instead of RESTlet for user-facing AJAX.
• Recommend postMessage for popup-to-parent communication.
• Recommend module-level code for critical Client Script initialization.
• Apply appropriate logging configuration (DEBUG for dev, omit for production).

Defensive Coding

• Check field values before overwriting (don't assume you're the only script).
• Use runtime.executionContext to control when script runs.
• Verify records exist before loading (use a targeted search or try/catch when existence is uncertain).
• Check for existing records before creating (idempotent operations).
• Wrap non-critical afterSubmit operations in try/catch.
• Use flag fields for script coordination when needed.
• Validate required fields before processing.
• Consider using script parameters to enable/disable features.

Governance Awareness

• Know your script type's usage unit limit (1,000 for UE/Suitelet/Client, 10,000 for Scheduled).
• Check getRemainingUsage() before loops with expensive operations.
• Use search.lookupFields() (1 unit) instead of record.load() (5-10 units) for field reads.
• Offload heavy processing to Scheduled/Map-Reduce scripts.
• Use console.log() in Client Scripts (not log.* which is ignored on forms).
• Handle search result limits (1,000 standard, 4,000 saved search).
• Implement yielding for long-running Scheduled Scripts.

---

Common Pitfalls to Avoid

1. Script ID Length: Maximum 40 characters total (prefix + filename).
2. Filename Normalization: All filenames must be lowercase with underscores.
3. Hyphen Conversion: Replace all - with _ in filenames and script IDs.
4. Script ID Matching: Script ID must exactly match pattern: customscript_[filename] or custtoolset_[filename] (NO script type in ID).
5. Truncation Awareness: Long filenames will be truncated to fit 40-char limit.
6. Bracket Notation for Record Types: Custom records must be wrapped: [customrecord_name].
7. CRITICAL - Bracket Notation for File Paths: All <scriptfile> and <rpcschema> values MUST be wrapped in square brackets: [/SuiteScripts/filename.js] - deployment WILL FAIL without brackets.
8. Path Consistency: Always use forward slashes, always start with /SuiteScripts/.
9. CustomTool Special Case: No scriptdeployments, minimal elements only — name, scriptfile, rpcschema, exposetoaiconnector, permissions. Uses <toolset> root element and custtoolset_ prefix in NetSuite 2026.1+ (legacy: <tool> root and customtool_ prefix).
10. SERVERSIDESCRIPTING Manifest: Must update manifest.xml with SERVERSIDESCRIPTING feature for ALL server-side scripts EXCEPT CustomTool (BundleInstallationScript, MapReduceScript, MassUpdateScript, Portlet, Restlet, ScheduledScript, SDFInstallationScript, Suitelet, UserEventScript, WorkflowActionScript). CustomTool deploys and executes without this feature dependency.
11. Deployment Status Values:
    • NOTSCHEDULED: Required for MapReduceScript and ScheduledScript (queued execution scripts).
    • RELEASED: Use for all other script types with deployments.
    • Using wrong status will cause deployment to FAIL.
12. Prefix Usage: custtoolset_ for CustomTool (2026.1+; legacy customtool_), customscript_ for all other script types (no script type suffix).
13. Run As Role - Not Supported: <runasrole> is NOT valid for: ClientScript, Restlet, ScheduledScript, MapReduceScript, MassUpdateScript, WorkflowActionScript. Only Suitelet, UserEventScript, and Portlet support it (Portlet intentionally omits to run as current user).
14. All Roles Access - Not Supported: <allroles> is NOT valid for: ClientScript, Restlet, ScheduledScript, MapReduceScript, MassUpdateScript, WorkflowActionScript.
15. Title - Not Supported: <title> is NOT valid for: ClientScript, MassUpdateScript, WorkflowActionScript, UserEventScript.
16. XML Character Encoding: NEVER use HTML entities (<, >) for XML tag brackets - always use literal < and > characters.
17. Scripts Without Deployments: BundleInstallationScript, SDFInstallationScript, and CustomTool do NOT have scriptdeployments structure.
18. Entry Point Functions - Not Supported in XML:
    • <defaultfunction> is NOT valid for: MassUpdateScript, ScheduledScript, WorkflowActionScript (entry points are auto-detected).
    • BundleInstallationScript entry point XML elements (<beforeinstallfunction>, etc.) are NOT supported (auto-detected from JS).
    • SDFInstallationScript has NO XML entry point elements - uses run function defined in JS, triggered via deploy.xml.
19. Record Type Required: ClientScript, UserEventScript, MassUpdateScript, AND WorkflowActionScript all require <recordtype> in their deployment.
20. CustomRecordType - Invalid Fields: <allowinlineinsert> is NOT a valid field for customrecordtype XML - SDF validation will warn about this. Do NOT include it in custom record definitions.
21. CustomList - Abbreviation Requires MATRIXITEMS: The <abbreviation> field in customlist values requires the MATRIXITEMS feature. Avoid using abbreviation unless MATRIXITEMS is already enabled, or simply omit it.
22. CUSTOMRECORDS Manifest Requirement: When a project contains ANY customrecordtype, the manifest.xml MUST include <feature required="true">CUSTOMRECORDS</feature> in the dependencies section. Deployment will FAIL without this.
23. SPA Uses Different Prefix: SPA scripts use custspa_ prefix (8 chars), NOT customscript_. Maximum scriptid is 28 characters total.
24. SPA Object Structure: Both SpaServerScript and SpaClientScript are defined in a SINGLE <singlepageapp> object - do NOT create separate objects for each.
25. SPA Invalid Fields: <notifyadmins>, <notifyowner>, <notifyuser>, and <executeas> with value "CURRENT_ROLE" are NOT valid for singlepageapp - validation will fail.
26. SPA Entry Points: SpaServerScript uses initializeSpa(context), SpaClientScript uses run(context) - these are different from other script types.
27. N/log Module Required: If using log.debug(), log.error(), or log.audit(), you MUST import the N/log module in the define() statement. The log object is NOT available globally in SuiteScript 2.x - script will fail silently without this import.
28. clientScriptModulePath in SuiteApps: When using form.clientScriptModulePath in a SuiteApp, you MUST use the full File Cabinet path (for example, /SuiteApps/com.publisher.appid/scripts/my_cs.js), NOT a relative path like ./my_cs.js. Relative paths work in Account Customization projects but NOT in SuiteApps.