netsuite-suitescript-learning

# NetSuite SuiteScript Learning Skill **Created by:** Oracle NetSuite ## Description Interactive learning system for NetSuite SuiteScript and SDF projects with **SAFE Guide integration**. This skill provides: - **Learn Mode**: Topic-based learning from SAFE Guide principles (14 topics including governance, performance, security, N/cache, concurrency) - **Review Mode**: Analyze code files and identify key learning concepts - **Explain Mode**: Deep-dive explanations with automatic SAFE Guide references - **Annotate Mode**: Embed educational comments directly into code - **Quiz Mode**: Generate quizzes from user code (`--source=code`), SAFE Guide principles (`--source=safe`), or both - **Final Mode**: Comprehensive learning documentation with SAFE Guide compliance checklist Covers all 14 script types, deployment configurations, performance patterns, defensive coding practices, and governance limits. ## How to Use This Skill ### Manual Invocation (Slash Command) Invoke this skill at any time by typing: ``` /netsuite-suitescript-learning ``` Note: `/netsuite-suitescript-learning` is the full skill command, while `/suitescript-learning` may be available as a coding assistant alias where supported. Or use specific mode commands: ``` /netsuite-suitescript-learning learn [topic] # Learn a SAFE Guide topic /netsuite-suitescript-learning review [filename] # Review a file and identify learning concepts /netsuite-suitescript-learning explain [concept] # Deep dive into a specific concept /netsuite-suitescript-learning annotate [filename] # Add inline learning comments to code /netsuite-suitescript-learning quiz [section] # Generate quiz questions /netsuite-suitescript-learning final # Generate a comprehensive learning document ``` ### Optional Coding Assistant Activation Example For Claude Code, add this to your project's `.claude/settings.local.json`: ```json { "permissions": { "allow": [ "Skill(netsuite-sdf-safe-guide)", "Skill(netsuite-suitescript-learning)" ] } } ``` With both skills enabled, an assistant will: - Follow SDF best practices for all SDF components (scripts, custom records, workflows, etc.) - Automatically embed educational annotations in code as it's written - Generate quizzes and learning materials on request - Provide guidance on Suitelets, RESTlets, User Event Scripts, and all 14 script types --- ## When to Use This Skill ### Proactive Invocation (Recommended) - Invoke this skill **during development** as code is being written, not just at the end. - Call after each major component is created (script file, object XML, etc.). - Use for real-time learning reinforcement. - **IMPORTANT**: When creating NetSuite SuiteScript code, automatically embed learning annotations (CONCEPT comments, LEARNING NOTES) directly into the code as it's written. ### Automatic Annotation During Code Creation When this skill is active and code is being created (not just reviewed), the following annotations should be automatically included: 1. **JSDoc Headers**: Include LEARNING NOTES explaining the script type and purpose. 2. **Entry Points**: Add LEARNING NOTES blocks explaining when/how the function runs. 3. **API Calls**: Add CONCEPT comments before each N/* module usage. 4. **Complex Logic**: Add step-by-step comments for multi-step operations. 5. **Return Statements**: Explain what's being exposed and why. This ensures educational content is embedded as code is written, not added as an afterthought. ### Manual Invocation - User explicitly requests educational content: "explain this code", "create a quiz", "review for learning" - Commands like: "/suitescript-learning", "/quiz", "/explain-suitescript" - After completing a NetSuite SDF project to generate final learning materials ### Invocation Modes | Mode | Trigger | Purpose | |------|---------|---------| | `learn` | When learning a SAFE Guide topic | Topic-based learning from SAFE Guide principles | | `review` | After creating a script file | Generate concepts and questions for that specific file | | `explain` | When user asks for explanation | Deep-dive into specific code patterns | | `annotate` | When the user asks to annotate code with inline comments | Add inline learning comments to existing code | | `quiz` | After completing a section | Generate quiz questions with answers | | `final` | At project completion | Consolidate all learning into comprehensive documentation | --- ## Usage Syntax ``` /netsuite-suitescript-learning [mode] [target] [options] Modes: learn – Topic-based learning from SAFE Guide principles review – Review a specific file and identify learning concepts explain – Explain a specific concept or code pattern annotate – Add inline learning comments to existing code quiz – Generate quiz questions for recent code final – Generate final comprehensive learning document Target: - File path for review/annotate mode - Concept name for explain mode - "all" or section name for quiz mode - Topic keyword for learn mode (see SAFE Guide Learning Topics) Options: --source=code Quiz questions from user's code only (quiz mode) --source=safe Quiz questions from SAFE Guide principles only (quiz mode) --source=owasp Quiz questions from OWASP secure coding practices only (quiz mode) --source=both Quiz questions from both sources (default for quiz mode) ``` **Examples:** ``` /suitescript-learning learn ncache /suitescript-learning learn governance /suitescript-learning review quick_add_ue.js /suitescript-learning explain beforeLoad /suitescript-learning annotate quick_add_cs.js /suitescript-learning quiz user-event-scripts /suitescript-learning quiz --source=safe /suitescript-learning final ``` --- ## Core Functionality ### 1. Code Review Mode (`review`) When reviewing a SuiteScript file, identify and document: #### Script Type Analysis Detect the script type from JSDoc annotations and provide: - Purpose of this script type - When it executes (server-side vs client-side) - Common use cases - Entry points specific to this type #### Key Concepts Extraction For each code pattern found, document: - **Concept Name**: Brief identifier - **What It Does**: Plain English explanation - **Why It's Used**: Business/technical rationale - **Code Location**: Line number reference - **Common Pitfalls**: What could go wrong - **Best Practice**: Recommended approach #### Output Format for Review Mode ```markdown ## Code Review: [filename] ### Script Overview - **Type**: [UserEventScript/ClientScript/Suitelet/RESTlet/etc.] - **Execution Context**: [Server/Client] - **Entry Points**: [list of entry points used] ### Key Concepts Identified #### 1. [Concept Name] **Lines**: [X–Y] **What**: [explanation] **Why**: [rationale] **Pitfall**: [common mistake] **Best Practice**: [recommendation] #### 2. [Next Concept] ... ### Quiz Questions for This File 1. [Question about concept 1] 2. [Question about concept 2] ... ``` --- ### 2. Explain Mode (`explain`) Provide deep-dive explanations for specific concepts: #### Supported Concepts (Auto-Detect from User Query) **User Event Script Concepts:** - `beforeLoad` – Form modification before render - `beforeSubmit` – Validation before save - `afterSubmit` – Post-save processing - `context.type` – Record access modes - `form.addButton()` – Custom buttons - `form.clientScriptModulePath` – Linking client scripts **Client Script Concepts:** - `pageInit` – Page load initialization - `saveRecord` – Save validation - `validateField` – Field-level validation - `fieldChanged` – Reactive field handling - `currentRecord.get()` – Accessing record data - `selectNewLine/commitLine` – Sublist manipulation - `window.opener` – Parent window communication **Suitelet Concepts:** - `onRequest` – HTTP request handling - `GET vs POST` – HTTP method routing - `response.write()` – Sending responses - `serverWidget.Form` – NetSuite forms - Custom HTML rendering **RESTlet Concepts:** - `get/post/put/delete` handlers - JSON responses - URL parameters vs body - CORS and authentication **Search & Query Concepts:** - `N/search` – Saved searches - `N/query` – SuiteQL - Search filters and columns - `search.run().each()` – Result iteration - Performance optimization **Deployment Concepts:** - Script IDs and naming - Deployment XML structure - `<runasrole>` and `<allroles>` support by type - `<recordtype>` requirements - Status values (RELEASED vs NOTSCHEDULED) - manifest.xml dependencies **Defensive Coding Concepts:** - `runtime.executionContext` – Check how script was triggered - Override vs. Wait patterns – When to defer to other scripts - Idempotent operations – Safe to re-run without side effects - Script coordination – Using flag fields for ordering - Graceful error handling – try/catch in afterSubmit - Sanity checks – Verify before acting - `search.lookupFields()` – Check record exists before loading **Governance Concepts:** - `Script.getRemainingUsage()` – Monitor remaining usage units - Usage unit limits by script type – 1,000 for UE/Suitelet, 10,000 for Scheduled - API governance costs – Different costs for custom vs transaction records - `SSS_USAGE_LIMIT_EXCEEDED` – Script exceeded usage units - `SSS_TIME_LIMIT_EXCEEDED` – Script exceeded time limit - Search result limits – 1,000 standard, 4,000 saved search - Yielding in Scheduled Scripts – Reschedule before hitting limits - Client Script logging – `log.*` ignored, use `console.log()` #### Output Format for Explain Mode ````markdown ## Concept: [Name] ### What It Is [Clear explanation] ### When to Use It [Use cases and scenarios] ### How It Works [Technical details with code examples] ### Example Code ```javascript [Relevant code snippet] ``` ### Common Mistakes 1. [Mistake 1] 2. [Mistake 2] ### Best Practices 1. [Practice 1] 2. [Practice 2] ### Related Concepts - [Link to related concept 1] - [Link to related concept 2] ### SAFE Guide Reference This concept relates to **Principle [X]: [Name]** Key points from the SAFE Guide: - [Point 1 from SAFE Guide] - [Point 2 from SAFE Guide] See: `../netsuite-sdf-safe-guide/references/[XX-filename.md]` ```` #### Concept-to-Principle Mapping When explaining concepts, automatically reference relevant SAFE Guide principles: | Concept Category | SAFE Guide Principle | Reference File | |------------------|---------------------|----------------| | Governance, Usage Units | Principle 2 | `02-governance-usage-units.md` | | N/cache, Performance | Principle 3 | `03-performance-optimization.md` | | N/query, SuiteQL | Principle 3 | `03-performance-optimization.md` | | Script Coexistence | Principle 4 | `04-multi-suiteapp-environment.md` | | Security, Permissions | Principle 5 & 11 | `05-security-privacy.md`, `11-security-best-practices.md` | | Testing, SDN | Principle 6 | `06-testing-suiteapps.md` | | Map/Reduce, Scheduled | Principle 2 & 3 | `02-governance-usage-units.md` | | RESTlet vs Suitelet | Appendix | `appendices/appendix-concurrency-cheatsheet.md` | | Legacy TBA Exceptions | Principle 5 | `05-security-privacy.md` | | OWASP, XSS, Injection | OWASP Skill | `netsuite-owasp-secure-coding/SKILL.md` | --- ### 3. Annotate Mode (`annotate`) Add inline learning comments directly into code files. This embeds educational content where developers will see it as they work with the code. #### Comment Styles **CONCEPT Comments** – Brief inline explanations ```javascript // CONCEPT: context.type tells us how the record is being accessed if (context.type !== context.UserEventType.VIEW) ``` **LEARNING NOTES Comments** – Block explanations in JSDoc ```javascript /** * beforeLoad Entry Point * * LEARNING NOTES: * - This function executes BEFORE the form is sent to the browser * - Perfect place to modify the form (add fields, buttons, sublists) * - context.form gives access to the N/ui/serverWidget.Form object * * @param {Object} context – Contains form, record, type (view/edit/create) */ const beforeLoad = (context) => { const form = context.form; }; ``` **Parameters Comments** – Explain function parameters ```javascript // Parameters: // id: Unique identifier (prefix with custpage_ for custom buttons) // label: What the user sees // functionName: Client Script function to call when clicked form.addButton({ id: 'custpage_quick_add_items', label: 'Quick Add Items', functionName: 'openQuickAddDialog' }); ``` #### Annotation Rules 1. **JSDoc Header Annotations** - Add LEARNING NOTES block to every entry point function. - Include what the function does, when it runs, and key parameters. - Reference related concepts and common pitfalls. 2. **Inline CONCEPT Comments** - Add before any non-obvious code pattern. - Keep to single line when possible. - Focus on the "why" not just the "what". 3. **Code Block Explanations** - Add before complex logic blocks. - Use numbered steps for multi-step operations. - Include expected outcomes. 4. **Return Statement Comments** - Explain what the return object exposes. - Note which functions are entry points vs custom. #### Where to Add Annotations | Location | Comment Type | Purpose | |----------|--------------|---------| | File header | LEARNING NOTES in JSDoc | Overall script purpose and type | | Entry point functions | LEARNING NOTES block | Function behavior and parameters | | Module imports | CONCEPT comment | Why each module is needed | | Conditionals | CONCEPT comment | Why this check is performed | | API calls | Parameters comment | What each parameter does | | Complex logic | Numbered steps | Break down multi-step operations | | Return statements | CONCEPT comment | What's being exposed and why | #### Example: Fully Annotated User Event Script ```javascript /** * @NApiVersion 2.1 * @NScriptType UserEventScript * @NModuleScope SameAccount * * @description User Event Script to add "Quick Add Items" button to Sales Orders * * LEARNING NOTES: * - @NApiVersion 2.1 tells NetSuite to use SuiteScript 2.1 (modern JS support) * - @NScriptType UserEventScript identifies this as a UE script * - @NModuleScope SameAccount restricts execution to same NetSuite account * - User Event Scripts run on the SERVER, not in the browser */ // CONCEPT: define() is the AMD module pattern; loads dependencies define(['N/ui/serverWidget', 'N/runtime'], (serverWidget, runtime) => { /** * beforeLoad Entry Point * * LEARNING NOTES: * - Executes BEFORE the form is sent to the browser * - Perfect place to modify the form (add fields, buttons, sublists) * - context.form gives access to the N/ui/serverWidget.Form object * - Changes made here appear when the page loads * * @param {Object} context – Contains form, record, type (view/edit/create)