NetSuite SDF（SuiteCloudデベロッパーフレームワーク、スクリプト開発の統合環境）のベストプラクティス集です。SAFE Guide（セーフガイド、公式の安全な開発指針）の12の原則と付録に基づいており、14種類すべてのスクリプトに対応したObjectXML（スクリプトの設定ファイル）を生成します。 ガバナンス上の制限（開発作業の管理ルール）、セキュリティパターン（安全な実装方法）、防御的なコーディング（エラーに強い書き方）を強制します。 N/cache（データ一時保存機能）、N/query（データベース照会機能）、同時実行数制限、OAuth 2.0（安全な認証方式）の解説、従来のTBA（トークン認証）のサポート終了対応、CustomTool実行時パターン（カスタムツール運用時の実装例）、REST Web Services（2026.1版の新機能）、140以上の既知の問題点と対策を網羅しています。 **次のような場合に使用:** SuiteAppとアカウントカスタマイズ（NetSuiteの拡張・改造）の開発に不可欠です。
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.
Comprehensive guide for NetSuite SuiteCloud Development Framework (SDF) projects, incorporating the SAFE Guide (SuiteApp Architecture Framework for Excellence) principles. This skill provides:
Invoke this skill at any time by typing:
/netsuite-sdf-safe-guide
Or use natural language triggers:
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:
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.
This skill should be invoked automatically when:
When the user says "generate objects" without specifying a file:
/SuiteScripts/ folder (including subfolders) for all .js files..js file found:
@NScriptType annotation.@NScriptType annotation.*_schema.json).Only process a single file when:
When reviewing code or answering questions:
| # | 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 |
All filenames MUST be normalized before generating script IDs:
GetCampaign.js → getcampaign.jsue-customer-validation.js → ue_customer_validation.js.xml extension for object files)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:
customscript_ = 13 chars)very_long_filename_example_here → very_long_filename_example_hecustomscript_very_long_filename_example_he (exactly 40 chars)If filename needs normalization:
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 - OptionalExample JSDoc:
/**
* filename.js
* @NApiVersion 2.1
* @NModuleScope Public
* @NScriptType CustomTool
*/
From path: /SuiteScripts/tools/getCampaignPreflight.js
Extract and normalize:
tools (or empty if none)getcampaignpreflight (original: getCampaignPreflight)/SuiteScripts/tools/getcampaignpreflight.jsFilename Normalization Rules:
- (hyphens) with _ (underscores)Examples:
GetCampaignPreflight.js → getcampaignpreflight.jsue-customer-validation.js → ue_customer_validation.jsClient-Script-Form-Validator-Extended-v2.js → client_script_form_validator_extende.js (truncated to 40 chars)IMPORTANT: Script IDs must exactly match the normalized filename
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 charscustomscript_ = 13 characters → filename portion ≤ 27 charsTruncation Example:
Original filename: verylongclientscriptname.js
Prefix: customscript_ (13 chars)
Remaining: 40 - 13 = 27 chars
Final script ID: customscript_verylongclientscriptna
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.
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)
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:
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]
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.
Create the appropriate XML structure based on script type:
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:
<dependencies> tag.SERVERSIDESCRIPTING feature exists, add if missing.<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.
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.
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:
< not <> not >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:
.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>
Version-aware: Check target_netsuite_version in ~/.claude/netsuite-connector-config.json (default "2026.1") and use the matching template below.
<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_versionis"2025.2".
<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:
<rpcschema> line.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.<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 thenetsuite-sdf-roles-and-permissionsskill and validate all<permkey>values againstreferences/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 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:
<runasrole> or <allroles> in deployment.<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:
<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 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:
<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.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.
<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.<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:
suitecloud object:import --type savedsearch --scriptid customsearch_sdftest_open_so --destinationfolder /Objects --excludefiles.<savedsearch> XML with the binary blob is now managed by SDF.<isinactive>T</isinactive> on the Suitelet to deactivate it (or remove it from the project entirely).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 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:
<runasrole> or <allroles> in deployment.<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:
HTML. Always use HTML unless the user explicitly requests a different type.FORM.LIST.LINKS.| 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:
<runasrole> intentionally - per NetSuite documentation, omitting this tag causes the script to run as the current user's role (the user viewing the dashboard).<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 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:
<beforeinstallfunction>, <afterinstallfunction>, etc.) are NOT supported and will be ignored - entry points are auto-detected from the JavaScript file.<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:
<status>NOTSCHEDULED</status> (NOT "RELEASED").<runasrole> or <allroles> in deployment.<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:
<defaultfunction> element is NOT supported and will be ignored - entry point is auto-detected.<title>, <runasrole>, or <allroles> in deployment.<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:
<status>NOTSCHEDULED</status> (NOT "RELEASED").<defaultfunction> element is NOT supported and will be ignored - entry point is auto-detected.<runasrole> or <allroles> in deployment.<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:
run and is defined in the JavaScript file, NOT in the XML.deploy.xml with <script> and <run> elements.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 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:
When NOT to use:
<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:
<returntype> and <returnrecordtype> for returning values to workflow.<returntype>SELECT</returntype>
<returnrecordtype>[customrecordtype_name or customlist_name]</returnrecordtype>
<recordtype> in deployment; prompt user for record type.<defaultfunction> element is NOT supported and will be ignored; entry point is auto-detected.<title>, <runasrole>, or <allroles> in deployment.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><CRITERIA></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:
customworkflow_ prefix (15 chars) → 25 chars remaining for name. 40 char max total.workflowstate_ prefix, scoped within the workflow.workflowaction_ prefix, scoped within the state.workflowtransition_ prefix, scoped within the state.[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.AFTERSUBMIT, BEFORELOAD actions in the entry state won't execute on the triggering transaction.ONENTRY does NOT execute independently, it runs with the first server trigger (BEFORELOAD, BEFORESUBMIT, or AFTERSUBMIT) after state entry.NOTINITIATING: Replaced NOTRUNNING as the non-running status, both values accepted for backward compatibility.SERVERSIDESCRIPTING feature required.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:
custspa_ prefix (8 chars) instead of customscript_.initializeSpa — NOT onAction, onRequest, or other entry points.run — NOT start or other entry points. No @NScriptType annotation needed.url field must be globally unique across ALL SPAs in the account — collisions cause cryptic deployment errors.SPA Deployment Pitfalls:
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.<clientscript>, <serverscript>, <assetfolder> (without brackets), but the local SuiteCloud CLI validator requires <clientscriptfile>, <serverscriptfile>, <assetsfolder> with bracket notation. Always validate locally first.SPA Documentation:
File Location:
/Objects/[script_id].xml
Examples:
/Objects/custtoolset_getcampaignpreflight.xml/Objects/customscript_form_validator.xml/Objects/customscript_update_customer.xmlSecret Object XML (imported reference, not secret value):
/Objects/custsecret_vendor_api_token.xml
(src/Objects/custsecret_vendor_api_token.xml in a standard SuiteCloud project layout).<secret scriptid="custsecret_vendor_api_token"/>
CRITICAL: Object Filename 40-Character Limit
.xml.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
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)| @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.
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
}
}
]
}
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:
context object — receives only params (flat key-value object from schema).context.response.write(), just return a serializable object.{ success: false, error: { type, message } }.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 };
});
| 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. |
CustomTools become MCP tools automatically through this lifecycle:
suitecloud project:deploy.schema.tools[0].name.The <exposetoaiconnector> flag controls visibility (renamed from <exposeto3rdpartyagents> in NetSuite 2026.1 — value semantics unchanged):
T — available to external MCP clients AND NetSuite AIF — only visible to NetSuite's built-in AI assistantThe 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.
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.
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
*/
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
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.
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`.
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.
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.
When implementing this skill, ensure:
/Objects/ as custsecret_*.xml reference objects.<secret scriptid="custsecret_*"/> and never stores secret values in the project.<scriptparametervalue> are used only for non-confidential configuration, never for credentials or other secrets.<scriptfile> and <rpcschema> paths wrapped in square brackets [].< and > for XML tags, NEVER use < or >.<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<permkey> values validated against netsuite-sdf-roles-and-permissions (exact ID match required).runtime.executionContext to control when script runs.try/catch when existence is uncertain).afterSubmit operations in try/catch.getRemainingUsage() before loops with expensive operations.search.lookupFields() (1 unit) instead of record.load() (5-10 units) for field reads.console.log() in Client Scripts (not log.* which is ignored on forms).Script ID Length: Maximum 40 characters total (prefix + filename).
Filename Normalization: All filenames must be lowercase with underscores.
Hyphen Conversion: Replace all - with _ in filenames and script IDs.
Script ID Matching: Script ID must exactly match pattern: customscript_[filename] or custtoolset_[filename] (NO script type in ID).
Truncation Awareness: Long filenames will be truncated to fit 40-char limit.
Bracket Notation for Record Types: Custom records must be wrapped: [customrecord_name].
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.
Path Consistency: Always use forward slashes, always start with /SuiteScripts/.
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).
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.
Deployment Status Values:
Prefix Usage: custtoolset_ for CustomTool (2026.1+; legacy customtool_), customscript_ for all other script types (no script type suffix).
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).
All Roles Access - Not Supported: <allroles> is NOT valid for: ClientScript, Restlet, ScheduledScript, MapReduceScript, MassUpdateScript, WorkflowActionScript.
Title - Not Supported: <title> is NOT valid for: ClientScript, MassUpdateScript, WorkflowActionScript, UserEventScript.
XML Character Encoding: NEVER use HTML entities (<, >) for XML tag brackets - always use literal < and > characters.
Scripts Without Deployments: BundleInstallationScript, SDFInstallationScript, and CustomTool do NOT have scriptdeployments structure.
Entry Point Functions - Not Supported in XML:
<defaultfunction> is NOT valid for: MassUpdateScript, ScheduledScript, WorkflowActionScript (entry points are auto-detected).<beforeinstallfunction>, etc.) are NOT supported (auto-detected from JS).run function defined in JS, triggered via deploy.xml.Record Type Required: ClientScript, UserEventScript, MassUpdateScript, AND WorkflowActionScript all require <recordtype> in their deployment.
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.
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.
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.
SPA Uses Different Prefix: SPA scripts use custspa_ prefix (8 chars), NOT customscript_. Maximum scriptid is 28 characters total.
SPA Object Structure: Both SpaServerScript and SpaClientScript are defined in a SINGLE <singlepageapp> object - do NOT create separate objects for each.
SPA Invalid Fields: <notifyadmins>, <notifyowner>, <notifyuser>, and <executeas> with value "CURRENT_ROLE" are NOT valid for singlepageapp - validation will fail.
SPA Entry Points: SpaServerScript uses initializeSpa(context), SpaClientScript uses run(context) - these are different from other script types.
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.
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.
RESTlet Concurrency Limits - Critical: RESTlets count against the Web Services Concurrent User Limit, which varies by service tier: Standard = 5, Premium = 15, Enterprise = 20, Ultimate = 20. Each SuiteCloud Plus (SC+) license adds 10 additional lanes. NEVER use RESTlets for user-facing AJAX calls (popups, modals, interactive features) — even Premium tier (15 concurrent) can be exhausted by a handful of active users. Instead, use the Suitelet-as-API pattern: a single Suitelet that returns HTML for page loads and JSON for AJAX calls based on an action parameter. RESTlets should ONLY be used for external system integrations.
Suitelet-as-API Pattern: For user-facing features requiring AJAX calls, use one Suitelet for both UI and data: action param empty → return HTML; action=search → return JSON. This avoids Web Services limits and scales with user sessions. Set Content-Type: application/json header when returning JSON.
window.opener Not Finding Function: NetSuite uses frames, so window.opener points to the top window, not the frame with your Client Script. Use the postMessage API instead: the popup calls window.opener.postMessage({action, data}, '*') and also posts to all window.opener.frames[i]. The Client Script listens with window.addEventListener('message', handler).
Search Field Selection: Be selective about which fields to include in search filters. Including salesdescription in item searches often causes false positives because descriptions may contain unexpected text (for example, "Compatible with Brand X equipment"). For type-ahead search, use only itemid and displayname.
N+1 Query Problem - Critical Performance: NEVER run queries inside loops. Doing a pricing lookup for each item individually results in 51 queries (1 search + 50 lookups) instead of 2 (1 search + 1 batch lookup). Use ['item', 'anyof', itemIds] filter for batch operations. This can be 25x faster (200 ms vs. 5 seconds).
pageInit Not Firing with clientScriptModulePath: When attaching a Client Script via form.clientScriptModulePath in a User Event Script, pageInit may NOT fire reliably. Put critical setup code (event listeners, initialization) at the MODULE LEVEL (outside any function), not inside pageInit. Module-level code always runs when the script loads.
Logging in Production: Always use <loglevel>DEBUG</loglevel> during development. For production, consider changing to AUDIT or ERROR to reduce log volume. If the user requests that logging be disabled entirely, omit the <loglevel> element from the deployment XML.
Assuming You're the Only Script: NEVER assume your script is the only one deployed to a record type. Multiple User Event Scripts, Workflows, SuiteFlow processes, and SuiteApps may all trigger on the same event. Always check field values before overwriting them.
Not Checking Execution Context: Use runtime.executionContext to determine how the script was triggered. You may want to skip processing for CSV imports, web services, or scheduled script contexts to avoid conflicts.
Creating Duplicate Records: If your script creates related records (audit logs, child records), always check if one already exists before creating. Use a search with appropriate filters to verify.
Ignoring Other Scripts' Work: Check if fields already have values set by other scripts before overwriting. Use flag fields (for example, custbody_processed_by_script_x) to coordinate between scripts.
Not Validating Before Acting: Always verify that records exist before loading, fields have expected values, and required data is present. Use a targeted search or try/catch when existence is uncertain before calling record.load().
Breaking Script Chain on Error: In afterSubmit, wrap non-critical operations in try/catch. Throwing an error stops other scripts from executing. Log errors and queue for retry instead of failing the entire transaction.
Non-Idempotent Operations: Design scripts to be safely re-runnable. If a script runs twice on the same record, it should produce the same result without duplicates or errors.
SSS_USAGE_LIMIT_EXCEEDED: Script exceeded its usage unit limit. User Event/Suitelet/Client have only 1,000 units. Use getRemainingUsage() to check before expensive operations. Consider Map/Reduce for heavy processing.
SSS_TIME_LIMIT_EXCEEDED: Script exceeded time limit (300s for most scripts, 3,600s for Scheduled/Map-Reduce). Break long operations into smaller chunks or use Map/Reduce with built-in yielding.
Client Script log. Ignored*: When a Client Script is attached to a form via deployment, log.debug(), log.audit(), etc. are silently ignored. Use console.log() instead for browser debugging.
Search Results Truncated: Standard searches return max 1,000 records; saved searches max 4,000. If you need more, use pagination with runPaged() or SuiteQL with OFFSET.
Using record.load() for Single Fields: record.load() costs 5-10 units. For reading a few fields, use search.lookupFields() which costs only 1 unit - 5-10x cheaper.
Heavy Processing in User Event: User Event Scripts have only 1,000 units and 300 second limit. Offload heavy work to Scheduled Script or Map/Reduce using task.create().
Not Checking Governance in Loops: Always check getRemainingUsage() before each iteration in loops that perform record operations. Failing to do so causes abrupt script termination.
Excessive Logging: Company-wide limit of 100,000 log calls per 60 minutes. NetSuite auto-raises log level if one script logs excessively. Use appropriate log levels and consider omitting <loglevel> in production.
N/cache Scope Confusion: cache.Scope.PRIVATE isolates cache per script, NOT per user. If a portlet and a separate Suitelet need to share cache data (for example, for cache-clearing), use cache.Scope.PUBLIC. Otherwise each script accesses its own isolated cache instance.
Browser APIs in Server-Side Scripts: URLSearchParams, fetch, localStorage, sessionStorage, and other browser Web APIs are NOT available in server-side SuiteScript (Suitelets, RESTlets, User Event Scripts, etc.). Use manual string concatenation with encodeURIComponent() for URL params, and N/https module for HTTP requests.
SuiteQL Transaction Line Filtering: The MainLine field works correctly in SuiteQL. Use MainLine = 'T' to get one row per transaction (header data), or MainLine = 'F' for detail lines. Note: (1) Mainline rows may have null item fields for non-itemized transactions like sales orders; (2) Journal entries require TransactionAccountingLine instead of TransactionLine; (3) Use item IS NOT NULL only when you specifically need to exclude non-item lines (expenses, etc.).
CSS Styling in NetSuite Portlets/Suitelets: NetSuite injects its own CSS that may override your styles. Use !important and explicit color values (for example, #FFFFFF instead of CSS variables) to ensure your styles take precedence. Test in the actual NetSuite environment, not just standalone HTML.
SPA Server Must Export initializeSpa: SpaServerScript entry point is initializeSpa(scriptContext) — NOT onAction, onRequest, or any other name. Using wrong export causes SPA creation to fail with cryptic errors.
SPA Client Must Export run: SpaClientScript entry point is run(scriptContext) — NOT start. The client script should NOT have @NScriptType annotation.
SPA audienceallroles=T Deployment Failures: On NetSuite 2025.1+ accounts, setting <audienceallroles>T</audienceallroles> may cause SPA creation to fail with "Items you have requested in the record have been deleted" because it references deleted/restructured roles. Prefer <audienceallroles>F</audienceallroles> with explicit <audienceroles>.
SPA Failed Deploy Leaves Ghost Install: When SPA object creation fails, the SuiteApp remains in FAILED status on the Installed SuiteApps page. You MUST uninstall before retrying. Best practice: Deploy all non-SPA objects first (without the SPA in deploy.xml), verify success, then add the SPA and redeploy.
SPA URL Must Be Globally Unique: The <url> field must be unique across ALL SPAs in the entire account (not just your SuiteApp). Collisions with existing SPAs cause cryptic deployment errors, not clear validation messages.
SPA XML Element Name Discrepancy: Oracle GitHub samples use <clientscript>, <serverscript>, <assetfolder> (newer schema), but the SuiteCloud CLI local validator requires <clientscriptfile>, <serverscriptfile>, <assetsfolder> with bracket notation paths. Always run suitecloud project:validate before deploying.
SPA on STDDEMO Accounts: SPA object creation may fail on STDDEMO (demo/sandbox) accounts with certain publisher IDs. If SPA consistently fails with "Items deleted" error despite correct XML and scripts, the account type may not support SPA creation for your publisher. Test on a non-STDDEMO account.
CustomTool Does Not Require SERVERSIDESCRIPTING: Unlike other server-side script types (Suitelet, RESTlet, UserEventScript, MapReduceScript, ScheduledScript, etc.), CustomTool scripts deploy and execute without the SERVERSIDESCRIPTING feature in manifest.xml. Do not add it to the manifest when the project only contains CustomTools.
SDFInstallationScript Missing Version Check: The run(context) entry point receives context.fromVersion (null on fresh install) and context.toVersion. Failing to check context.fromVersion before running migration logic causes data corruption on fresh installs — migration code runs against empty/default state instead of existing data.
SDFInstallationScript deploy.xml <path> Mismatch: The <path> inside <script> must point to the Object XML file (~/Objects/customscript_*.xml), NOT the JavaScript file. Pointing to the JS file causes a silent deployment failure — the script is never triggered.
SDFInstallationScript Placement in deploy.xml: The <script> block's position in deploy.xml controls execution timing. Placing it before <objects> runs the script before custom records/fields exist. Always place <script> AFTER <objects> unless you specifically need pre-deployment logic (for example, data backup before schema changes).
CustomTool Schema name / JS Export Mismatch: The "name" field in tools[0] must exactly match (case-sensitive) the function name exported from the JS module. If they differ, the tool silently fails to route — no error message, the AI agent simply cannot call the tool.
Using "type": "object" for Complex CustomTool Params: NetSuite's runtime may not pass nested JSON objects cleanly. Declare complex parameters as "type": "string" with a description like "JSON string containing…" and use JSON.parse() in the JS entry point.
Throwing Exceptions in CustomTool Instead of Structured Errors: Unhandled exceptions give the calling AI agent a generic, unhelpful error. Always try/catch and return { success: false, requestId, error: { type, message } } — never let exceptions propagate. Return only a safe, generic message to the caller and include a non-sensitive requestId for log correlation. Do not log stack traces, raw params, response payloads, formulas, query text, credentials, tokens, or internal field values.
Not Checking getRemainingUsage() in CustomTool: CustomTools have only 1,000 governance units (same as Suitelet). Check runtime.getCurrentScript().getRemainingUsage() before expensive operations like query.runSuiteQL(), record.load(), or search.create() and return partial results if insufficient.
Adding <scriptdeployments> to ToolSet XML: CustomTool (ToolSet in 2026.1+) does not support the <scriptdeployments> block. Including it causes SDF validation errors. Other unsupported elements: <description>, <isinactive>, <notifyadmins>, <notifyowner>, <defaultfunction>, <title>, <runasrole>, <allroles>.
Short/Vague CustomTool Schema Description: AI agents rely entirely on the schema description to understand what a tool does and how to call it. Write multi-sentence descriptions with parameter format examples. Vague descriptions like "Runs a query" lead to incorrect invocations.
Not Logging Redacted Audit Trail in CustomTool: Always log.audit() on entry and completion, but log only redacted metadata: tool name, non-sensitive requestId, row/formula counts, and elapsed time. Never log raw params or response bodies. Without a redacted audit trail, debugging production issues is difficult; with raw logs, the tool can leak sensitive AI/user input. Note: NetSuite 2026.1+ provides execution logs at Customization > Scripting > Script Execution Logs — but log.audit() in code is still required to populate them.
Returning Non-Serializable Objects from CustomTool: The runtime serializes the return value to JSON. Functions, circular references, undefined values, and class instances with non-enumerable properties silently fail or produce empty results. Always return plain objects with primitive values, arrays, and nested plain objects.
Missing ERP Feature Dependencies in manifest.xml: Custom fields applied to transaction bodies (custbody_*) or items (custitem_*) require the corresponding ERP features (RECEIVABLES, PAYABLES, INVENTORY, ASSEMBLIES, etc.) declared in manifest.xml. Without these declarations, suitecloud project:validate warns for every affected field — and the warnings multiply (N fields × M missing features). Fix once in manifest.xml to silence all warnings.
<allroles>T</allroles> Selects Internal Roles Only: Setting <allroles>T</allroles> on a scriptdeployment only makes the script available to internal NetSuite roles. To include external roles (Customer Center, Partner Center, Vendor Center), you must also add <audslctrole> elements listing each external role. This applies to all script types that support <allroles> — not just SPAs (see also Pitfall #57 for SPA-specific behavior).
Treating System Contention as a Code Defect: SDF deployment errors containing "system contention caused by operations on other objects" are transient infrastructure failures — NOT code bugs. Do not attempt to fix code or rerun suitecloud project:validate. Instead, wait and retry the deployment during off-peak hours. The Issue Fixer loop should not count contention failures against its retry limit.
Undeclared Features Pass Validation but Fail in Target Accounts: Feature dependencies not declared in manifest.xml are silently ignored in development accounts where features are enabled by default, but generate blocking warnings or failures in target/production accounts where features like RECEIVABLES or INVENTORY may be disabled. Always declare all feature dependencies explicitly, even if your dev account doesn't require them.
UIF Modal Missing owner Prop — Critical: The owner property is the only required property in Window.Options (parent of Modal). Without it, UIF throws "Property 'owner' must be any of: instance of Da, instance of Hr or Element" and "Cannot detach Component that is currently being updated". Fix: Create a useRef, attach it to the root component via ref={myRef}, and pass owner={myRef} to every Modal. Each component file needs its own ref (for example, settingsRef, calendarRef, dashboardRef). The opened prop is NOT a constructor option — use conditional rendering to show/hide modals. Modal.DeprecatedNoOwner exists but is deprecated and must NOT be used.
Non-Async CustomTool Entry Point Functions: NetSuite 2026.1 documentation requires CustomTool entry points declared as async function(options). Using synchronous functions may cause unexpected behavior when the runtime expects to await the result. Declare all entry point functions as async: const myTool = async (params) => { ... }.
Using Pre-2026.1 <tool> Root Element and customtool_ Prefix: In NetSuite 2026.1+, the root XML element is <toolset scriptid="custtoolset_...">, not <tool scriptid="customtool_...">. Using the old structure causes SDF validation errors. Rename root to <toolset>, change prefix from customtool_ to custtoolset_. Version-conditional: This pitfall applies only when targeting 2026.1+. When target_netsuite_version is "2025.2", the <tool> and customtool_ format is correct.
Using <exposeto3rdpartyagents> Instead of <exposetoaiconnector>: The visibility element was renamed in 2026.1. Old <exposeto3rdpartyagents> causes SDF validation errors. Use <exposetoaiconnector>T</exposetoaiconnector>. Value semantics unchanged. Version-conditional: This pitfall applies only when targeting 2026.1+. When target_netsuite_version is "2025.2", <exposeto3rdpartyagents> is the correct element.
destructiveHint Defaults to true — Read-Only Tools Must Set false: The destructiveHint annotation defaults to true, meaning AI agents may treat ALL tools as potentially destructive unless told otherwise. Query/validation tools must explicitly set "destructiveHint": false in the schema annotations. Without this, agents may unnecessarily seek confirmation before calling read-only tools.
Using N/http, N/https, or N/sftp in CustomTool Scripts: These 3 modules are NOT supported in CustomTool scripts. Including them causes runtime error: "Couldn't load modules in the custom tool script because it uses unsupported modules." Use N/query, N/record, or N/search for data access. For external HTTP calls, create a Suitelet intermediary and call it via N/url or N/action.
Ignoring Official CustomTool Error Messages: Oracle documents 7 specific error messages for CustomTool runtime failures. When debugging, check Script Execution Logs and match against: "Access denied", "Couldn't load modules... unsupported modules", "Invalid call, required properties missing", "Script execution context creation failed", "This tool is not allowed", "Unexpected error while executing the tool", "Tool execution failed". Each has a specific root cause — do not treat them all as generic failures.
Assuming CustomTool-Triggered Scripts Run as the Invoking User: When a CustomTool script loads or saves a record, any triggered User Event Scripts and Workflow Actions run under the AI Connector Service configured role — NOT as the user or integration that called the tool. UE/Workflow scripts checking runtime.getCurrentUser() will see the AI Connector Service role. Errors in triggered scripts appear in THOSE scripts' execution logs, not in the CustomTool log.
CustomTool Rename in 2026.1 — Breaking Change: In NetSuite 2026.1, the CustomTool SDF object type was renamed. XML root element: <tool> → <toolset>, script ID prefix: customtool_ → custtoolset_, visibility attribute: <exposeto3rdpartyagents> → <exposetoaiconnector>. Required to enable 2026.1 execution logs (SuiteAnswers ref: 1024036). Old Object XML fails SDF validation in 2026.1+ accounts. Version-conditional: These renames apply only to 2026.1+ accounts. Read target_netsuite_version from ~/.claude/netsuite-connector-config.json to determine the correct format.
Confusing application.xml beforeUndeploy with BundleInstallationScript: BundleInstallationScript handles install/update/uninstall lifecycle through JavaScript entry points and runs AFTER those events. application.xml's <beforeundeploy> runs an SDFInstallationScript BEFORE uninstall begins — earlier in the lifecycle with a different mechanism.
Missing application.xml for Pre-Uninstall Cleanup: If your SuiteApp creates external dependencies (API tokens, webhooks, custom record data) that must be cleaned up before removal, create application.xml with a <beforeundeploy> reference. Without it, the SuiteApp is removed without cleanup, potentially leaving orphaned data.
Not Setting Permissions on .ss/.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.
Creating New SOAP Integrations for SuiteApps: SOAP Web Services are not permitted for new SuiteApps (since 2024.2). All new integrations should use REST Web Services with OAuth 2.0. The last new SOAP endpoint was added in 2025.2; all SOAP endpoints will be permanently disabled in 2028.2. Plan migration for any existing SOAP integrations well before this deadline.
Using Serial REST Calls Instead of Batch API for Bulk Operations: NetSuite 2026.1 introduced REST Batch Operations for processing multiple records of the same type in a single asynchronous request. Serial REST calls for bulk operations consume more concurrency slots and increase total latency. Use batch operations for high-volume create/update/delete scenarios. Note: batch responses are asynchronous (HTTP 202) — poll the job status endpoint for completion. Consult Oracle REST Web Services documentation for exact request format and limits.
Not Polling REST Async Job Completion: When using REST Batch Operations or any async REST operation (HTTP 202 response), the operation is NOT complete when the request returns. You must poll the async job status endpoint until all tasks report COMPLETE or FAILED. Treating the 202 response as immediate completion leads to race conditions and missing results.
Using RSA PKCS#1 v1.5 Keys for OAuth 2.0: RSA PKCS#1 v1.5 signing is deprecated for NetSuite OAuth 2.0. Use RSA-PSS (minimum 2048-bit) or EC keys (256, 384, or 521 bits). Integrations using deprecated key types will fail token requests.
REST Attach/Detach API Limited to Contact and File Records (2026.1): The Attach/Detach endpoint (POST .../record/v1/{type1}/{id1}/!attach/{type2}/{id2}) introduced in 2026.1 only supports Contact and File record types. Attempting other record types returns an error. For unsupported types, use SuiteScript N/record attach() via a RESTlet or Suitelet.
Querying Records Without Filtering Inactive Records: Searches and queries that omit an isinactive filter return deactivated records (items, customers, vendors, employees, custom records, etc.) alongside active ones. This causes stale data in reports, phantom inventory in lookups, and incorrect totals. BAD: search.create({ type: search.Type.CUSTOMER, filters: [['salesrep', 'is', repId]] }) returns inactive customers. GOOD: search.create({ type: search.Type.CUSTOMER, filters: [['salesrep', 'is', repId], 'AND', ['isinactive', 'is', 'F']] }). For SuiteQL: WHERE NVL(isinactive, 'F') = 'F'. Always filter unless the user explicitly requests inactive records. Applies to N/search, N/query, and SuiteQL. Note: transaction records (Sales Order, Invoice, etc.) do not have isinactive — use transaction status fields instead.
<objects> Element Not Supported in SuiteApp Manifests: Adding <objects> inside <dependencies> in a SuiteApp manifest.xml causes validation error: The object field "objects" is invalid or not supported. SuiteApp projects auto-deploy all files from the Objects/ folder; only <features> is valid inside <dependencies>. This element IS valid in Account Customization projects but NOT in SuiteApps.
Hardcoding Production Behavior in Sandbox Environments: Scripts that make external API calls, send emails, or trigger integrations can cause real-world side effects when tested in a NetSuite sandbox account. Use runtime.accountId to detect sandbox — sandbox accounts have a _SB suffix (for example, 1234567_SB1, 1234567_SB2). Use this to skip external calls, route to test endpoints, or use alternate email recipients. BAD: Calling a production payment gateway from a sandbox during testing. GOOD: const isSandbox = runtime.accountId.includes('_SB'); if (!isSandbox) { sendToPaymentGateway(data); }. Apply sandbox guards to: external HTTP calls (N/https), email sends (N/email), integration triggers, and any operation with real-world consequences. See references/01-understand-netsuite-features.md for code patterns.
Directly Manipulating the DOM in SuiteScript: SuiteScript code must NOT directly access or manipulate the browser DOM using document.getElementById, jQuery, innerHTML, querySelector, or any other browser DOM API. NetSuite's internal DOM structure changes without notice between release, direct DOM manipulation breaks unpredictably after upgrades. Use the SuiteScript API instead: N/ui/serverWidget for forms/fields/buttons (server-side), N/ui/dialog and N/ui/message for client-side dialogs, and currentRecord.setValue() / currentRecord.getValue() for field data in Client Scripts. For advanced UI, use UIF SPA (see references/12-uif-spa-best-practices.md) rather than raw DOM manipulation. This prohibition applies to ALL script types — DOM APIs are unavailable in server-side scripts entirely, and must not be used in Client Scripts even though they technically have browser access.
Ignoring Timezone When Handling Dates: NetSuite stores dates internally in Pacific Time (PT). Constructing date strings manually (for example, new Date('2024-01-15')) or comparing raw Date objects created in different timezones produces off-by-one-day errors. Always use the N/format module for timezone-safe date handling: format.parse({ value: dateString, type: format.Type.DATE }) for parsing, and format.format({ value: dateObj, type: format.Type.DATE }) for display. To get the current user's configured timezone: runtime.getCurrentUser().getPreference({ name: 'TIMEZONE' }). Never manually construct date strings for storage or comparison. When passing dates to record.setValue, always pass a JS Date object parsed via N/format, not a raw string. See references/01-understand-netsuite-features.md for code patterns.
Multiple Conflicting User Event Scripts on the Same Record: NetSuite does NOT guarantee execution order when multiple User Event Scripts are deployed to the same record type and event. Multiple UE scripts from different sources (your SuiteApp + account customizations + other SuiteApps) can conflict; scripts may overwrite each other's field values, each script adds latency to every record load/save, and debugging becomes exponentially harder. Best practice: consolidate to one User Event Script per record type per event within your SuiteApp, using a dispatcher pattern that calls modular functions. When coexisting with external UEs is unavoidable, design your UE to be defensive: check field values before overwriting, use runtime.executionContext to guard against unexpected contexts, and use flag fields to coordinate. Use Setup > Customization > Scripted Record to view all UE scripts on a record and drag-reorder them if needed. See references/04-multi-suiteapp-environment.md for coexistence patterns.
Suitelet List Views Exceeding 100 Rows: Rendering more than 100 rows in a Suitelet list view causes browser rendering slowdowns and poor user experience. Keep sublists under 100 rows and on-demand select fields under 100 options. For larger datasets, implement pagination: pass a page or offset parameter in the request URL, load one page at a time, and render Next/Previous navigation links. BAD: Loading all 2,000 records into a single list render. GOOD: Load 50–100 rows per page and add navigation controls.
Hardcoding Suitelet Domain or URL: Hardcoding a NetSuite domain (for example, https://1234567.app.netsuite.com/...) breaks when the script is deployed to a different account, sandbox, or environment. Use url.resolveScript() from the N/url module to build Suitelet URLs dynamically — it resolves the correct domain for the current environment automatically.
// BAD — breaks in sandbox or other accounts
const myUrl = 'https://1234567.app.netsuite.com/app/site/hosting/scriptlet.nl?script=123&deploy=1';
// GOOD — resolves correct domain for the current environment
define(['N/url'], function(url) {
const myUrl = url.resolveScript({
scriptId: 'customscript_my_suitelet',
deploymentId: 'customdeploy_my_suitelet',
params: { action: 'search' }
});
});
ifrmcntnr=T: When a Suitelet is rendered inside an iframe (popup, dashboard widget, inline frame), omitting ifrmcntnr=T from the URL causes rendering issues in Firefox and can trigger X-Frame-Options or Content Security Policy (CSP) conflicts. Always append ifrmcntnr=T when the Suitelet URL will be loaded in an iframe. Prefer popups or full-page navigation over iframes when possible.// GOOD — Append ifrmcntnr=T for iframe contexts.
define(['N/url'], (url) => {
const iframeUrl = url.resolveScript({
scriptId: 'customscript_my_suitelet',
deploymentId: 'customdeploy_my_suitelet'
}) + '&ifrmcntnr=T';
// Use iframeUrl to set the iframe src.
});
https.get()) to a Suitelet URL from another server-side script is inefficient — it requires authentication setup and adds a full network round-trip. Use https.requestSuitelet() instead for direct server-to-server Suitelet invocation within the NetSuite execution context. Use https.requestRestlet() for RESTlets. Both avoid the network overhead and do not require separate authentication.// BAD — Outbound HTTP call, requires auth, adds network latency.
const response = https.get({ url: 'https://1234567.app.netsuite.com/...?script=123&deploy=1' });
// GOOD — Direct server-side invocation, no network overhead.
define(['N/https'], function(https) {
const response = https.requestSuitelet({
scriptId: 'customscript_my_suitelet',
deploymentId: 'customdeploy_my_suitelet',
params: { action: 'getData' }
});
const data = JSON.parse(response.body);
});
Joining System Notes Tables in SuiteQL: SystemNote is an extremely high-volume table — every field change on every record creates a row. Joining it in SuiteQL queries causes severe performance degradation and frequent query timeouts. BAD: SELECT t.id, sn.date FROM Transaction t INNER JOIN SystemNote sn ON sn.recordid = t.id WHERE t.type = 'SalesOrd' performs a full-table scan on SystemNote. GOOD: Query Transaction data without the join. If audit history is needed, run a dedicated standalone query on SystemNote with tight filters on recordid, field, and a narrow date rang, never as a JOIN against a large result set.
Using Dynamic SuiteQL Queries Instead of Parameterized Queries (Fingerprint Optimization): String-interpolated SuiteQL queries (for example, `WHERE id = ${custId}`) generate a unique query fingerprint on every call, preventing NetSuite from caching and reusing execution plans. This degrades performance at scale. BAD: query.runSuiteQL({ query: `SELECT id FROM Customer WHERE id = ${custId}` }) GOOD: query.runSuiteQL({ query: 'SELECT id FROM Customer WHERE id = ?', params: [custId], customScriptId: 'my_customer_lookup_v1' }). Assign a customScriptId to each query and treat it as a version identifier, update it whenever the query structure changes. Reusing the same ID for a modified query confuses the internal optimizer and negates the caching benefit.
Attempting to Use the Interactive Debugger for Client Scripts: The NetSuite Script Debugger (Customization > Scripting > Script Debugger) supports server-side script types only: User Event, Suitelet, RESTlet, Scheduled, Map/Reduce (getInputData stage via manual call), Portlet, Workflow Action, and Bundle Installation. Client Scripts run in the browser; the interactive debugger never attaches to them. Attempting to debug a Client Script via the NetSuite debugger produces no breakpoints and no output. Use browser DevTools (F12) instead: set breakpoints directly in the browser, inspect variables, and use console.log() / console.table() for output. console.table() is particularly useful for visualizing sublist data as a structured grid. Remember: log.debug() and other N/log calls are silently ignored on forms, always use console.* for Client Script debugging.
Assuming Jest Test Pass Means NetSuite Runtime Pass: SuiteScript 2.1 runs on GraalJS (ES2022); Jest runs on Node.js (V8). These are different engines and can produce subtly different behavior for the same code. Common failure modes: (1) Native Iterators: function* generators and Symbol.iterator usage passes Jest/Node.js but fails in GraalJS; use standard array methods instead. (2) AMD require() vs. CommonJS require(): NetSuite's require() loads AMD modules; Node.js loads CommonJS. Use the SuiteCloud Unit Testing Framework (SCUTF) transform to handle AMD transpilation automatically. (3) Constructor return values: AMD modules can return a constructor or function directly; for Jest ES6 import compatibility, add myFn.default = myFn. (4) Global log/util: If scripts use these as globals rather than importing N/log/N/util, declare global.log = { debug: jest.fn(), ... } in Jest setup. (5) Governance:: Jest has no concept of usage units; always complement unit tests with sandbox integration testing to validate governance behavior.
Browser Cache Serving Stale Client Script During Development: NetSuite aggressively caches Client Script files in the browser. After uploading a new version of a Client Script, a normal page refresh (F5) serves the cached version — changes appear to have no effect and the developer wastes time re-uploading or debugging a non-problem. Fix: Use a hard refresh to bypass the cache: Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac). In Chrome, you can also open DevTools (F12), right-click the browser Refresh button, and select "Empty Cache and Hard Reload". This is a development workflow tip, do not modify production Client Script file paths to add cache-busters, as SDF manages those.
Expecting Immediate Server-Side Effects from setValue() in Client Scripts: currentRecord.setValue() and currentRecord.setCurrentSublistValue() are deferred IO operations. They update the client-side record object in memory but do NOT write to the server immediately. The changes are batched and submitted to NetSuite only when the form is saved. BAD: Calling setValue() on a field and then immediately making a Suitelet/RESTlet request expecting that field's new value to be on the server record. GOOD: Pass the field value explicitly as a parameter in any server call, or read it back from the local record object via currentRecord.getValue() within the same client-side event.
Exceeding the 10 Client Script Deployment Limit Per Record: NetSuite enforces a default limit of 10 Client Script deployments per record type. When more than 10 are deployed to the same record, additional scripts beyond the limit are silently ignored: no error, no warning, the extra scripts simply never execute. Diagnosis: go to Setup > Customization > Scripted Record, select the record type, and count active Client Script deployments. Fix option 1: Consolidate multiple scripts into a single dispatcher Client Script that calls modular functions. Fix option 2: Enable the "Remove Client Script Deployment Limit" feature at Setup > Company > Enable Features > SuiteCloud tab. This removes the cap entirely.
Using fieldChanged When postSourcing Is Needed for Sourced Field Values: fieldChanged fires immediately when a field value changes, but at that instant dependent sourced fields may not yet be populated. For example, selecting a Customer auto-sources the billing address, payment terms, and sales rep, but fieldChanged on the entity field fires before those sourced fields have values. BAD: Reading terms inside fieldChanged when the user changes the entity (Customer) field — terms will still be empty. GOOD: Use postSourcing instead. It fires AFTER all dependent field sourcing completes. Use fieldChanged for validating/reacting to what the user directly entered; use postSourcing when your logic needs auto-populated downstream values to be present.
// BAD — fieldChanged on entity fires before terms/address are sourced.
const fieldChanged = (context) => {
if (context.fieldId === 'entity') {
const terms = context.currentRecord.getValue({ fieldId: 'terms' }); // may be empty
applyTermsLogic(terms);
}
};
// GOOD — postSourcing fires after all dependent fields are populated.
const postSourcing = (context) => {
if (context.fieldId === 'entity') {
const terms = context.currentRecord.getValue({ fieldId: 'terms' }); // guaranteed populated
applyTermsLogic(terms);
}
};
return { fieldChanged, postSourcing };
currentRecord.getValue({ fieldId: 'custbody_myfield' }) on a field that doesn't exist on the current form throws a runtime error that aborts the script. Use currentRecord.getFields() to defensively verify a field exists before accessing it.// BAD — Throws if custbody_approval_code doesn't exist on this form.
const code = context.currentRecord.getValue({ fieldId: 'custbody_approval_code' });
// GOOD — Check existence first.
const rec = context.currentRecord;
const fields = rec.getFields();
if (fields.includes('custbody_approval_code')) {
const code = rec.getValue({ fieldId: 'custbody_approval_code' });
processApproval(code);
}
// Also useful for OneWorld: only access subsidiary if the field exists.
if (fields.includes('subsidiary')) {
const sub = rec.getValue({ fieldId: 'subsidiary' });
applySubsidiaryRules(sub);
}
validateLine returning false from ANY deployed Client Script cancels the line commit for ALL scripts. (2) sublistChanged fires for ALL deployed scripts on every sublist change, regardless of which script caused it. Without sublistId filtering, scripts act on sublists they don't own. Always filter sublist events by context.sublistId and avoid conflicting validateLine logic across independently deployed scripts.// BAD — Validates all sublists; returning false blocks every other script.
const validateLine = (context) => {
const qty = context.currentRecord.getCurrentSublistValue({
sublistId: context.sublistId, fieldId: 'quantity'
});
return qty > 0;
};
const sublistChanged = (context) => {
// No sublistId filter — fires logic for ALL sublists.
recalculateTotals(context.currentRecord);
};
return { validateLine, sublistChanged };
// GOOD — Scope to the relevant sublist only.
const validateLine = (context) => {
if (context.sublistId !== 'item') {
return true; // Pass through for sublists this script doesn't own.
}
const qty = context.currentRecord.getCurrentSublistValue({
sublistId: 'item', fieldId: 'quantity'
});
return qty > 0;
};
// GOOD — Filter sublistChanged to owned sublist.
const sublistChanged = (context) => {
if (context.sublistId !== 'item') { return; }
recalculateTotals(context.currentRecord);
};
return { validateLine, sublistChanged };
Migrating SOAP Without a Complete Integration Inventory: Starting migration without a full discovery of all SOAP integrations, their auth methods, record types, and volumes leads to missed integrations hitting the 2028.2 deadline. Complete Phase 0 discovery (see Appendix: SOAP to REST Migration) before any Wave 1 work begins. Document every integration in a Migration Registry with direction, SOAP operations used, auth method, volume, and business criticality.
Cutting Over From SOAP to REST Without Parallel Run: Switching directly from SOAP to REST without running both simultaneously risks undetected data discrepancies. Run SOAP and REST in parallel for at least 1 full business cycle, comparing outputs field-by-field. High-risk integrations (transactions, payments) require 2+ billing/fulfillment cycles of parallel run with zero discrepancies before cutover.
Not Testing SOAP Rollback Before Cutover: Assuming SOAP rollback will work without actually testing it. After cutting over to REST, keep the SOAP credential active (unused) for a 30-day rollback window. Test the rollback procedure in sandbox before production cutover, especially for high-risk integrations with real-time SLAs.
Using NLAuth for New REST Integrations: NLAuth is legacy authentication that should not be used with new REST Web Services integrations. Use OAuth 2.0 Client Credentials for machine-to-machine (M2M) integrations and Authorization Code grant for user-delegated access. See Pitfall #93 for RSA-PSS key requirements.
Ignoring REST Record API Field Coverage Gaps: Not all SOAP-exposed fields are available in the REST Record API. Some record types may have incomplete field coverage or not be available via REST at all. Identify field gaps during Phase 0 discovery by comparing SOAP response fields against REST GET responses for the same records. For unsupported record types or missing fields, build RESTlet adapters as part of Phase 1 foundation work.
Wildcard deploy.xml Paths Include OS Artifacts (.DS_Store): Using wildcard paths like ~/FileCabinet/SuiteScripts/* or ~/FileCabinet/Web Site Hosting Files/* in deploy.xml picks up macOS .DS_Store files, causing deployment failure with A file upload error occurred. It's not possible to add files to this folder. Use specific subfolder paths (for example, ~/FileCabinet/SuiteScripts/tools/*) instead of broad wildcards, and delete any .DS_Store files from the src/ tree before deploying.
Logging PERF_TIMING in Production Without Toggle: The self-instrumented PERF_TIMING pattern (see appendix-perf-timing.md) writes log.audit() entries for every entry point execution. Each call costs 1 governance unit. In a User Event Script with 3 entry points processing 1,000 records/day, that's 3,000 extra log entries and governance units daily. Always gate PERF_TIMING behind a script parameter toggle (custscript_perf_timing checkbox, default OFF). Enable only when actively investigating performance. The company-wide limit of 100,000 log calls per 60 minutes applies, leaving timing on can trigger NetSuite's automatic log level escalation.
Using Date.now() for Client Script Timing: Client Scripts run in the browser where log.audit() is silently ignored. Use performance.now() for sub-millisecond precision and console.time() / console.timeEnd() for named timers in browser DevTools. Date.now() works but only provides millisecond precision. Do NOT use log.audit('PERF_TIMING', ...) in Client Scripts; the log calls are silently dropped and consume no governance, but also produce no output.
Not Estimating Governance Before Deploying Bulk Scripts: Scripts that process variable-size inputs (Scheduled, Map/Reduce, Mass Update) should have their worst-case governance estimated before deployment. A script that costs 50 units per record in a loop processing 200 records = 10,000 units, exactly the Scheduled Script limit. Static estimation catches this before production timeouts. Calculate: (per-iteration cost) x (expected max iterations) + (fixed overhead) and compare against the script type limit. The code-quality-agent performs this automatically in Step 6.5.
Comparing Post-Deploy Metrics Too Soon After Deployment: Querying scheduledscriptinstance immediately after deployment returns stale data or no data for the new version. Scheduled Scripts may not execute for hours; Map/Reduce scripts depend on queue availability. Wait for a representative sample of executions (at least 3 runs) before drawing performance conclusions. The deploy flow's Step 5.3 notes insufficient data when fewer than 3 post-deploy runs are available. For reliable before/after comparison, re-check after 24 hours.
Using <transactionsearch> XML to Create Saved Searches via SDF: Hand-crafted <transactionsearch> XML with human-readable <definition> blocks (containing <filter>, <column>, <sortcolumn> elements) is unreliable for creating saved searches via SDF deployment. The local validator warns "transactionsearch will be categorized as a data file". this is a signal that it will not be treated as a proper SDF object. Behavior is inconsistent: it may work on initial project deployment but fail on subsequent new projects. The correct SDF format is <savedsearch> with a compressed/encoded binary <definition> blob that only NetSuite can generate. You cannot hand-author saved search XML. The <definition> element uses a <SHA256_HASH>@GZC@<VERSION>@<BASE64_GZIP_DATA> format where the title, filters, columns, audience, and public flag are all encoded inside the blob. Changing the scriptid attribute is safe (checksums still validate), but the title is embedded in the blob — deploying a renamed copy with the same blob fails with "A search has already been saved with that name" if the original still exists. Recommended workflow: (1) Create the saved search in NetSuite using the Saved Search Creator Suitelet pattern (see below). Deploy it with login required, either Current Role execution for self-service creation or a least-privilege custom execution role for a controlled bootstrap. If Administrator execution is unavoidable, restrict the Suitelet audience to explicit admin/developer roles and never use <allroles>T</allroles>, (2) Import it into your SDF project using suitecloud object:import --scriptid customsearch_xxx --type savedsearch --destinationfolder /Objects, (3) Deactivate or remove the creator Suitelet after the search exists, (4) Deploy via SDF. The <savedsearch> format with the encoded blob reliably manages the search going forward. Do not make generated searches public by default; set public visibility only after explicit business approval. Additional limitations: SDF does NOT update saved search definitions on redeploy, only metadata gets updated. To modify criteria after initial deploy, delete the search in NetSuite and redeploy, or edit in the UI. The <transactionsearch> format should never be used for SDF deployments.
bodytransactiontypes Element Unsupported in SDF Object XML: Adding <bodytransactiontypes> to a transactionbodycustomfield XML causes validation warning: The object field "bodytransactiontypes" is invalid or not supported. Transaction type filtering for body fields cannot be set via SDF. Configure it manually in the UI after deployment.
MANUFACTURING is not a valid manifest feature ID: Using <feature required="true">MANUFACTURING</feature> causes validation error: The "MANUFACTURING" feature defined in the manifest does not exist. Use ASSEMBLIES for work orders and assembly items. Cross-reference the feature dependency table in appendix-manifest-features.md.
Mandatory Script Parameters Fail SDF Deployment: Setting <ismandatory>T</ismandatory> on a <scriptcustomfield> (script parameter) in Object XML causes SDF validation to fail because SDF cannot supply a value for mandatory parameters at deploy time. Fix: set <ismandatory>F</ismandatory> in the Object XML and validate the parameter at runtime in the script's entry point function (for example, check for null/empty and log.error + return early if missing).
Calling N/ APIs at define() Scope Causes SUITESCRIPT_API_UNAVAILABLE_IN_DEFINE: All N/ API modules are unavailable during the define() callback execution. Calling runtime.getCurrentScript(), record.load(), or any N/ API at module scope causes deployment failure. Use lazy initialization. Declare as null at module scope, initialize on first access from an entry point function.
Item subsidiary sublist is static. Cannot use dynamic mode: Creating items (Service, Inventory, etc.) with isDynamic: true and calling selectNewLine/commitLine on the subsidiary sublist throws "invalid sublist or line item operation" because the subsidiary sublist is static. Fix: use isDynamic: false and setSublistValue on line 0.
entitystatus Table Has No isinactive Column: SuiteQL query WHERE isinactive = 'F' on entitystatus throws Unknown identifier 'isinactive'. Not all SuiteQL tables support isinactive. For entity statuses, omit the filter or use available columns like probability IS NOT NULL.
Account-Specific Mandatory Fields on Record Creation: Fields like taxschedule (items) and projectexpensetype (projects) may be mandatory depending on account configuration, features enabled, or custom forms — even though they're not mandatory in a default NetSuite install. Saving with ignoreMandatoryFields: false fails with "Please enter value(s) for: [field]". Fix: use ignoreMandatoryFields: true as a safety net, and proactively look up required values from existing records of the same type in the account (for example, record.load an existing service item to read its taxschedule value).
appliestojob Ignored in SDF Entity Custom Field XML: Adding <appliestojob>T</appliestojob> to an entitycustomfield Object XML generates a warning during deployment: "The appliestojob object field is invalid or not supported and will be ignored." The field deploys but does NOT appear on Project/Job records. The "Applies To" entity type settings for entity custom fields cannot be set via SDF. They must be configured manually in the UI after deployment (Customization > Entity Fields > edit > Applies To subtab > check Project/Job).
Restrict Saved Search Creator Suitelet Execution and Audience: When using the Saved Search Creator Suitelet pattern to programmatically create saved searches (because SDF cannot create them from hand-written XML), do not combine elevated execution with broad audience. For self-service creation, omit <runasrole> so the Suitelet runs as Current Role and only creates searches the current user is permitted to create; use <allroles>T</allroles> only when every internal role is intentionally allowed to use that self-service flow. For controlled one-time bootstrap, prefer a least-privilege custom execution role and explicit <audslctrole> entries for admins/developers. Use <runasrole>ADMINISTRATOR</runasrole> only when no lower-privilege role can perform the task, and then never pair it with <allroles>T</allroles>. After the saved search is created and imported into SDF, set <isinactive>T</isinactive> on the Suitelet to deactivate it or remove it entirely. Do not set isPublic = true by default; public saved searches require explicit business approval.
Suitelet <isonline> Must Be Explicitly Set to F — Security Critical: The <isonline> element in a Suitelet script deployment controls whether the Suitelet is accessible without authentication. When set to T, anyone with the URL can execute the Suitelet without logging in. This is a severe security risk for any Suitelet that creates, modifies, queries, or deletes data. Always include <isonline>F</isonline> explicitly in every Suitelet deployment. While NetSuite defaults to F when the element is omitted, relying on implicit defaults is dangerous; a developer unfamiliar with the default may add <isonline>T</isonline> during a quick edit without understanding the consequences. The only legitimate use of <isonline>T</isonline> is for Suitelets specifically designed as public-facing pages (for example, anonymous feedback forms or public catalog pages); and even then, the Suitelet must validate all input, implement rate limiting, and never expose internal data. The Saved Search Creator Suitelet pattern MUST NEVER be available without login. If it runs with elevated permissions and creates saved searches, unauthenticated access would allow an attacker to create searches in your account. BAD: <isonline>T</isonline> or omitting <isonline> entirely on data-modifying Suitelets. GOOD: <isonline>F</isonline> with a security comment explaining the requirement.
Account Customization deploy.xml Missing <objects> Section: The deploy.xml file for Account Customization projects requires an <objects> section listing the Object XML paths. Omitting it causes validation error: The object field "objects" is missing. Even if <configuration> or <files> sections are present, <objects> is mandatory when deploying script or custom record Object XML files. Fix: add <objects><path>~/Objects/*</path></objects> to deploy.xml.
Scriptfile Reference Resolution Fails with Incomplete deploy.xml: During deployment, SDF resolves <scriptfile>[/SuiteScripts/filename.js]</scriptfile> references by matching them against the <files> section of deploy.xml. If deploy.xml is missing standard sections (<configuration>, <translationimports>), the reference resolution engine may fail with: The file '[/SuiteScripts/filename.js]' referenced by object field 'scriptfile' could not be resolved — even though <files> includes the correct path. Fix: use the complete deploy.xml structure generated by suitecloud project:create, including all four sections: <configuration><path>~/AccountConfiguration/*</path></configuration>, <files>, <objects>, and <translationimports><path>~/Translations/*</path></translationimports>.
Using SuiteQL Type Abbreviations in search.create(): search.create({ type: ... }) requires lowercase type IDs (for example, 'purchaseorder', 'vendorbill', 'itemreceipt'). SuiteQL's transaction.type column uses different abbreviations (for example, 'PurchOrd', 'VendBill', 'ItemRcpt'). These are not interchangeable. Passing a SuiteQL abbreviation to search.create() throws a runtime error: The record type [PURCHORD] is invalid. Always use search.Type.* enum values (or their lowercase string equivalents) in N/search, and SuiteQL abbreviations only inside SuiteQL query strings. See the type mapping table in 03-performance-optimization.md § 3.3.7.
Using createdfrom on the SuiteQL transaction Table: In N/search, createdfrom is a direct field on the transaction record and works in filter expressions like ['createdfrom.type', 'anyof', ['PurchOrd']]. In SuiteQL, createdfrom does not exist on the transaction table, it is a column on transactionline. Querying WHERE t.createdfrom = ... on the transaction table throws Unknown identifier 'createdfrom'. Fix: join through transactionline — FROM transactionline tl INNER JOIN transaction t ON t.id = tl.transaction WHERE tl.createdfrom = :id. Note also that Vendor Bills link directly back to the originating PO (not to the Item Receipt), the chain is PO → IR and PO → VB via transactionline.createdfrom, not PO → IR → VB.
Accepting Raw SuiteQL in MCP-Exposed CustomTools: A CustomTool exposed through MCP must not accept raw SuiteQL or caller-selected table/field/query fragments. Unlike a normal Suitelet or RESTlet UI flow, tool parameters may be influenced by prompt injection, hallucination, or schema misunderstanding before they reach NetSuite. BAD: schema property query or sql passed to query.runSuiteQL({ query: params.query }). GOOD: schema exposes datasetId with an enum, plus bounded filter fields. Server-side code maps each dataset ID to a fixed SuiteQL template, validates every filter against an allowlist, binds values with params, enforces row limits, and excludes sensitive records/fields such as credentials, tokens, auth/session data, payment/bank/card data, employee compensation, and broad audit/system-note datasets. See references/appendices/appendix-customtool-runtime.md.
The <loglevel> element in script deployments controls what gets captured in the Execution Log. This element is optional; omit it entirely to disable logging.
| Level | Captures | Use Case |
|---|---|---|
DEBUG |
All logs (debug, audit, error, emergency) | Development, troubleshooting |
AUDIT |
Audit, error, emergency only | Production with monitoring |
ERROR |
Error and emergency only | Production, minimal logging |
EMERGENCY |
Emergency only | Production, critical errors only |
| (omit element) | No logs captured | Production, no logging needed |
With logging enabled:
<scriptdeployment scriptid="customdeploy_my_script">
<isdeployed>T</isdeployed>
<loglevel>DEBUG</loglevel> <!-- Change to ERROR for production -->
<status>RELEASED</status>
</scriptdeployment>
With logging disabled (omit the element):
<scriptdeployment scriptid="customdeploy_my_script">
<isdeployed>T</isdeployed>
<!-- No <loglevel> element = no logging -->
<status>RELEASED</status>
</scriptdeployment>
DEBUG to capture all log.debug(), log.audit(), log.error() calls.AUDIT or ERROR to reduce log storage and improve performance.DEBUG, then revert after fixing issues.<loglevel> element entirely.ERROR or EMERGENCY.// These are captured based on loglevel setting:
log.debug('Title', 'Details'); // Only with DEBUG
log.audit('Title', 'Details'); // With DEBUG or AUDIT
log.error('Title', 'Details'); // With DEBUG, AUDIT, or ERROR
log.emergency('Title', 'Details'); // With any loglevel (but NOT if element omitted)
Note: When <loglevel> is omitted, even log.emergency() calls are not recorded in the Execution Log.
When developing SuiteScripts, always assume:
Multiple scripts can deploy to the same record type and event. Your script must coexist gracefully.
/**
* BAD: Assumes this script is the only one setting the field.
*/
const beforeSubmit_Bad = (context) => {
context.newRecord.setValue({
fieldId: 'custbody_approval_status',
value: 'PENDING'
});
};
/**
* GOOD: Checks current state before acting.
*/
const beforeSubmit_Good = (context) => {
const currentStatus = context.newRecord.getValue({
fieldId: 'custbody_approval_status'
});
// Only set if not already set by another script/workflow.
if (!currentStatus) {
context.newRecord.setValue({
fieldId: 'custbody_approval_status',
value: 'PENDING'
});
}
};
Decide explicitly whether your script should override values set by other processes or defer to them.
// Let other scripts/workflows take precedence.
const beforeSubmit = (context) => {
const record = context.newRecord;
const existingValue = record.getValue({ fieldId: 'custbody_processed_by' });
if (!existingValue) {
// Only act if no other process has claimed this
record.setValue({
fieldId: 'custbody_processed_by',
value: runtime.getCurrentScript().id
});
}
};
// Take control but log what was overridden for troubleshooting.
const beforeSubmit = (context) => {
const record = context.newRecord;
const existingValue = record.getValue({ fieldId: 'custbody_tax_code' });
const calculatedValue = calculateTaxCode(record);
if (existingValue && existingValue !== calculatedValue) {
log.audit('Tax Code Override', {
previous: existingValue,
new: calculatedValue,
reason: 'Calculated based on shipping address'
});
}
record.setValue({
fieldId: 'custbody_tax_code',
value: calculatedValue
});
};
// Only run if record wasn't created by specific integration.
const beforeSubmit = (context) => {
const source = context.newRecord.getValue({ fieldId: 'custbody_source_system' });
// Skip processing if record came from ERP integration.
if (source === 'ERP_INTEGRATION') {
log.debug('Skipping', 'Record from ERP integration - deferring to integration logic');
return;
}
// Proceed with normal processing.
processRecord(context.newRecord);
};
Always validate before acting. Never trust that data is in the expected state.
// BAD: Assumes record exists.
const relatedRecord = record.load({
type: 'customrecord_config',
id: configId
});
// GOOD: Verify first with a targeted search.
const existingRecord = search.create({
type: 'customrecord_config',
filters: [['internalid', 'anyof', configId]],
columns: ['internalid']
}).run().getRange({ start: 0, end: 1 });
if (existingRecord.length > 0) {
const relatedRecord = record.load({
type: 'customrecord_config',
id: configId
});
// Process record.
} else {
log.error('Config Missing', `Configuration record ${configId} not found`);
}
// GOOD: Comprehensive validation before action.
const processOrder = (salesOrder) => {
// Sanity checks
const entity = salesOrder.getValue({ fieldId: 'entity' });
const subsidiary = salesOrder.getValue({ fieldId: 'subsidiary' });
const lineCount = salesOrder.getLineCount({ sublistId: 'item' });
if (!entity) {
throw error.create({
name: 'MISSING_CUSTOMER',
message: 'Sales Order must have a customer'
});
}
if (!subsidiary) {
throw error.create({
name: 'MISSING_SUBSIDIARY',
message: 'Sales Order must have a subsidiary'
});
}
if (lineCount === 0) {
log.audit('Empty Order', 'No line items to process');
return;
}
// Safe to proceed.
processLineItems(salesOrder);
};
// Only run in specific contexts.
const beforeSubmit = (context) => {
const execContext = runtime.executionContext;
// Skip if running from CSV import or web services.
if (execContext === runtime.ContextType.CSV_IMPORT ||
execContext === runtime.ContextType.WEBSERVICES) {
log.debug('Skipping', `Execution context: ${execContext}`);
return;
}
// Only process user-initiated actions.
if (execContext === runtime.ContextType.USER_INTERFACE) {
processUserAction(context);
}
};
Design scripts to be safely re-runnable without side effects.
/**
* BAD: Creates duplicate records if run multiple times.
*/
const afterSubmit_Bad = (context) => {
record.create({
type: 'customrecord_audit_log',
values: {
custrecord_source_record: context.newRecord.id
}
}).save();
};
/**
* GOOD: Checks for existing record before creating.
*/
const afterSubmit_Good = (context) => {
const sourceId = context.newRecord.id;
// Check if audit log already exists.
const existingLogs = search.create({
type: 'customrecord_audit_log',
filters: [
['custrecord_source_record', 'is', sourceId],
'AND',
['created', 'within', 'today']
]
}).run().getRange({ start: 0, end: 1 });
if (existingLogs.length === 0) {
record.create({
type: 'customrecord_audit_log',
values: {
custrecord_source_record: sourceId
}
}).save();
} else {
log.debug('Audit Log Exists', `Log already created for record ${sourceId}`);
}
};
Handle failures without breaking other scripts in the execution chain.
const afterSubmit = (context) => {
try {
// Your logic here.
sendNotification(context.newRecord);
} catch (e) {
// Log but don't throw, let other scripts continue.
log.error('Notification Failed', {
error: e.message,
recordId: context.newRecord.id
});
// Optionally: Queue for retry instead of failing.
queueForRetry(context.newRecord.id, 'sendNotification');
}
};
// Script A sets a flag.
const afterSubmit_ScriptA = (context) => {
record.submitFields({
type: context.newRecord.type,
id: context.newRecord.id,
values: {
custbody_script_a_complete: true
}
});
};
// Script B waits for Script A.
const afterSubmit_ScriptB = (context) => {
const scriptAComplete = context.newRecord.getValue({
fieldId: 'custbody_script_a_complete'
});
if (!scriptAComplete) {
log.debug('Waiting', 'Script A has not completed yet');
return;
}
// Safe to proceed.
processAfterScriptA(context.newRecord);
};
// Check script parameter to enable/disable features.
const beforeSubmit = (context) => {
const script = runtime.getCurrentScript();
const enableValidation = script.getParameter({
name: 'custscript_enable_validation'
});
if (enableValidation === false) {
log.debug('Validation Disabled', 'Skipping validation per script parameter');
return;
}
validateRecord(context.newRecord);
};
| Check | Purpose | Example |
|---|---|---|
| Field has value? | Avoid null errors | if (value) { ... } |
| Record exists? | Prevent load failures | Targeted search or try/catch |
| Correct context? | Skip unwanted triggers | runtime.executionContext |
| Already processed? | Prevent duplicates | Check flag field or search |
| Expected type? | Type safety | typeof value === 'number' |
| Within limits? | Governance awareness | runtime.getCurrentScript().getRemainingUsage() |
| Other scripts done? | Coordination | Check completion flag fields |
NetSuite uses a governance model based on usage units to ensure fair resource allocation. Scripts that exceed limits are terminated with errors like SSS_USAGE_LIMIT_EXCEEDED or SSS_TIME_LIMIT_EXCEEDED.
Each script type has a maximum number of usage units it can consume per execution.
| Script Type | Usage Units | Notes |
|---|---|---|
| User Event Script | 1,000 | Design for user responsiveness |
| Client Script | 1,000 | Not shared among scripts on same form |
| Suitelet | 1,000 | Design for user responsiveness |
| Portlet | 1,000 | |
| Mass Update Script | 1,000 | Per record processed |
| Workflow Action Script | 1,000 | Per workflow state |
| Custom Tool Script | 1,000 | |
| RESTlet | 5,000 | |
| Scheduled Script | 10,000 | Consider Map/Reduce for long tasks |
| Bundle Installation Script | 10,000 | |
| SDF Installation Script | 10,000 | |
| Map/Reduce Script | No overall limit | Individual stages are regulated |
Key Insight: User-facing scripts (Suitelet, User Event, Client) have low limits (1,000) to ensure responsiveness. Use Scheduled or Map/Reduce scripts for heavy processing.
Each SuiteScript API operation consumes usage units. Costs vary by record type:
| Operation | Custom | Non-Transaction | Transaction |
|---|---|---|---|
record.load() |
2 | 5 | 10 |
record.create() |
2 | 5 | 10 |
record.copy() |
2 | 5 | 10 |
record.transform() |
2 | 5 | 10 |
record.submitFields() |
2 | 5 | 10 |
record.save() |
4 | 10 | 20 |
record.delete() |
4 | 10 | 20 |
record.attach() |
— | 10 | 10 |
record.detach() |
— | 10 | 10 |
| Operation | Units | Notes |
|---|---|---|
search.create() |
0 | Free to create |
Search.run() |
0 | Free to run |
search.lookupFields() |
1 | Most efficient for single records |
search.load() |
5 | |
search.save() |
5 | |
Search.runPaged() |
5 | |
PagedData.fetch() |
5 | Per page |
ResultSet.each() |
10 | |
ResultSet.getRange() |
10 | |
search.global() |
10 | |
search.duplicates() |
10 |
| Operation | Units |
|---|---|
query.create() |
0 |
query.load() |
5 |
Query.run() |
10 |
Query.runPaged() |
10 |
| SuiteQL execution | 10 |
| Operation | Units |
|---|---|
http.get() / https.get() |
10 |
http.post() / https.post() |
10 |
http.put() / https.put() |
10 |
http.delete() / https.delete() |
10 |
https.requestRestlet() |
10 |
| Operation | Units |
|---|---|
email.send() |
20 |
email.sendBulk() |
10 |
email.sendCampaignEvent() |
10 |
| Operation | Units |
|---|---|
file.create() |
0 |
file.load() |
10 |
File.save() |
20 |
file.delete() |
20 |
| Operation | Units | Notes |
|---|---|---|
task.ScheduledScriptTask.submit() |
20 | |
task.MapReduceScriptTask.submit() |
20 | |
action.executeBulk() |
50 | |
sftp.Connection.download() |
100 | |
sftp.Connection.upload() |
100 | |
task.CsvImportTask.submit() |
100 | |
llm.generateText() |
100 | AI operations |
Each script type has a maximum execution time. Exceeding it throws SSS_TIME_LIMIT_EXCEEDED.
| Script Type | Time Limit |
|---|---|
| Client Script | 300 seconds (5 min) |
| User Event Script | 300 seconds |
| Suitelet | 300 seconds |
| RESTlet | 300 seconds |
| Portlet | 300 seconds |
| Mass Update Script | 300 seconds |
| Workflow Action Script | 300 seconds |
| Custom Tool Script | 300 seconds |
| Map/Reduce (map stage) | 300 seconds |
| Map/Reduce (reduce stage) | 900 seconds (15 min) |
| Map/Reduce (getInputData) | 3,600 seconds (1 hour) |
| Map/Reduce (summarize) | 3,600 seconds |
| Scheduled Script | 3,600 seconds |
| Bundle Installation Script | 3,600 seconds |
| SDF Installation Script | 3,600 seconds |
SuiteScript Debugger: 300 second limit regardless of script type.
| Limit Type | Maximum | Notes |
|---|---|---|
| Standard search | 1,000 records | Via ResultSet.getRange() |
| Saved search iteration | 4,000 records | Via ResultSet.each() |
| Text column values | 4,000 bytes | ~4,000 chars in English |
| SuiteQL results | 5,000 records | Use pagination for more |
| Limit | Maximum | Error Code |
|---|---|---|
| Key length | 3,000 characters | KEY_LENGTH_IS_OVER_3000_BYTES |
| Value size | 10 MB | VALUE_LENGTH_IS_OVER_10_MB |
Best Practice: Pass data in values, not keys. Keep keys short for identification only.
| Limit | Value |
|---|---|
| Company-wide log calls | 100,000 per 60 minutes |
| User log retention | 30 days |
| System error log retention | 60 days |
| Database log storage | 5 million entries |
Critical: If a script logs excessively, NetSuite automatically raises its log level (DEBUG → AUDIT → ERROR).
Client Script Logging: When a Client Script is attached to a form via deployment, log.* calls are ignored. Use console.log() instead.
// In Client Script attached to form
log.debug('Test', 'This is IGNORED'); // Does nothing.
console.log('Test', 'This works'); // Appears in browser console.
Always check remaining units before expensive operations:
const checkGovernance = (requiredUnits) => {
const script = runtime.getCurrentScript();
const remaining = script.getRemainingUsage();
if (remaining < requiredUnits) {
log.audit('Governance Warning', {
remaining: remaining,
required: requiredUnits,
action: 'Stopping to prevent limit exceeded'
});
return false;
}
return true;
};
// Usage in loop.
items.forEach((item, index) => {
// Check before each expensive operation.
if (!checkGovernance(50)) {
log.audit('Incomplete', `Processed ${index} of ${items.length} items`);
return; // Exit loop
}
// Expensive operation (for example, record.save = 20 units for transaction).
processItem(item);
});
For Scheduled Scripts approaching limits, reschedule to continue:
const processRecords = (records) => {
const script = runtime.getCurrentScript();
for (let i = 0; i < records.length; i++) {
// Check governance before each iteration.
if (script.getRemainingUsage() < 200) {
// Reschedule with remaining records.
const taskId = task.create({
taskType: task.TaskType.SCHEDULED_SCRIPT,
scriptId: script.id,
deploymentId: script.deploymentId,
params: {
custscript_start_index: i
}
}).submit();
log.audit('Rescheduled', `Continuing from index ${i}, Task: ${taskId}`);
return;
}
processRecord(records[i]);
}
};
| Practice | Why |
|---|---|
Use search.lookupFields() (1 unit) over record.load() (5-10 units) |
5-10x cheaper for single field reads |
Batch operations with anyof filter |
One search vs. N searches |
| Use Map/Reduce for heavy processing | Built-in yielding, higher limits |
Check getRemainingUsage() before loops |
Prevent unexpected termination |
| Use custom records when possible | 2-5x cheaper than standard records |
Prefer submitFields() over load()+save() |
Half the governance cost |
Use console.log() in Client Scripts |
log.* ignored on form-attached scripts |
For detailed architectural guidance based on Oracle's SAFE Guide (SuiteApp Architectural Fundamentals & Examples, Version 2025.2), see the reference files in the references/ folder:
Full Index - Complete table of contents with quick reference tables
| # | Principle | Key Topics |
|---|---|---|
| 1 | Understand NetSuite Features | REST vs SOAP, SuiteScript 2.1, SuiteTax, OneWorld |
| 2 | Manage Governance | Usage units, script types, optimization patterns |
| 3 | Performance Optimization | N/cache, Map/Reduce, N/query, SuiteQL |
| 4 | Multi-SuiteApp Environment | Script coexistence, execution order, conflicts |
| 5 | Security and Privacy | Roles, permissions, OAuth 2.0, data protection |
| 6 | Testing SuiteApps | Jest testing, SDN environments, phased releases |
| 7 | Managed Distribution | Managed SuiteApps, SuiteApp Control Center |
| 8 | Maintenance | Publisher environment, versioning, deployment |
| 9 | Agreements and Licensing | IP protection, click-through agreements |
| 10 | Open Source | License compliance, prohibited licenses |
| 11 | Security Best Practices | OWASP principles, secure coding |
| 12 | UIF SPA Best Practices | StackPanel layout, conditional rendering, DataGrid constraints |
| Appendix | Description |
|---|---|
| Concurrency Cheat Sheet | Concurrency governance limits and error handling |
| N/query Joins | Multi-level joins using N/query module |
| N/Cache Sample | Complete caching example for concurrent processing |
| N/dataset Formulas | Formula auto-transformations for N/dataset and N/workbook |
| N/dataset Record Types | Record types, field locations, and join patterns for N/dataset |
| CustomTool Runtime | JS entry points, schema design, MCP integration, and complete examples |
| Manifest Features | ERP feature string catalog, required vs optional, manifest.xml examples |
| UIF Component Patterns | AccordionPanel, Breadcrumbs, ToolBar, Pagination, Stepper, Popover, MultiselectDropdown, SplitButton, SystemIcon catalog, ImmutableArray/Object, FormatService, LazyDataSource, EventBus patterns |
| Performance Monitoring Queries | SuiteQL queries for scheduledscriptinstance, scriptnote, script deployment inventory, PERF_TIMING extraction, baseline capture schema |
| Self-Instrumented Timing | PERF_TIMING patterns for all script types, toggle pattern, governance cost, mode-aware integration |
General SDF:
Script Type Documentation:
Governance & Limits:
After completing all file operations, display a Change Report summarizing every file touched.
Internally track each file as: {path, action: created|modified|unchanged, before_content, after_content}
Display a table listing every file that was evaluated:
## Change Report
| Action | File | Description |
|-----------|-----------------------------------|------------------------------|
| Created | src/Objects/customscript_example.xml | New UserEvent script object |
| Modified | src/Objects/custrecord_foo.xml | Added field custrecord_bar |
| Unchanged | manifest.xml | No changes needed |
For each file marked Created or Modified, display a unified diff using a fenced code block with diff syntax highlighting.
Created files: Show the full content as all + lines.
### customscript_example.xml (Created)
```diff
+ <?xml version="1.0" encoding="UTF-8"?>
+ <usereventscript scriptid="customscript_example">
+ <name>Example UE Script</name>
+ ...
+ </usereventscript>
```
Modified files: Show a unified diff comparing the original content against the new content. Include a few lines of unchanged context around each change:
### custrecord_foo.xml (Modified)
```diff
<customrecordtype scriptid="custrecord_foo">
<recordname>Foo Record</recordname>
+ <customrecordcustomfields>
+ <customrecordcustomfield scriptid="custrecord_bar">
+ <fieldtype>TEXT</fieldtype>
+ </customrecordcustomfield>
+ </customrecordcustomfields>
</customrecordtype>
```
Unchanged files: Listed in the summary table only; no diff block needed.
netsuite-sdf-roles-and-permissions — Authoritative lookup of 670+ NetSuite permission IDs for validating <permkey> values in Object XML, customrole definitions, and script deployment configurations. See netsuite-sdf-roles-and-permissions.netsuite-owasp-secure-coding — OWASP Top 10 2021, injection prevention, XSS, output encoding, API security. See netsuite-owasp-secure-coding.netsuite-suitescript-upgrade — SuiteScript 1.0 to 2.1 migration (125+ API mappings, 34 object conversions). See netsuite-suitescript-upgrade.diff syntax highlighting for proper rendering.原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。