📁 Appendix C: Project Case Studies

Case Study 1: Custom Button Controller

Solution Overview

Complete Annotated Code

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 * @NModuleScope SameAccount
 * @version 1.2
 * 
 * ═══════════════════════════════════════════════════════════════════
 * 📚 MODULES DEMONSTRATED
 * ═══════════════════════════════════════════════════════════════════
 * MODULE 4: User Event entry points (beforeLoad)
 * MODULE 3: Reading record fields with getValue()
 * MODULE 12: url.resolveScript() to generate Suitelet URLs
 * MODULE 4: form.addButton() to add custom buttons
 * MODULE 14: try/catch error handling
 * ═══════════════════════════════════════════════════════════════════
 * 
 * Adds buttons to Case record:
 * 1. Print PDF - Always visible
 * 2. Get Customer Completion Email - Only if service NOT complete
 */
define(['N/url', 'N/runtime', 'N/log'],
    function(url, runtime, log) {

        /**
         * 📚 MODULE 4: beforeLoad Entry Point
         * ────────────────────────────────────
         * Triggered BEFORE the page renders when user views the record.
         * Perfect for: Adding buttons, hiding/showing fields, modifying form
         * 
         * context.type values:
         *   - VIEW: User is viewing record
         *   - EDIT: User is editing record  
         *   - CREATE: User is creating new record
         *   - COPY: User is copying record
         *   - PRINT: User is printing record
         */
        function beforeLoad(context) {
            try {
                log.debug('beforeLoad Started', 'Type: ' + context.type);

                // ─────────────────────────────────────────────────────────
                // 📚 MODULE 4: Check execution context
                // Only add buttons when VIEWING the record
                // ─────────────────────────────────────────────────────────
                if (context.type !== context.UserEventType.VIEW) {
                    log.debug('beforeLoad', 'Not VIEW mode, skipping buttons');
                    return;
                }

                // Get form and record objects from context
                var form = context.form;
                var newRecord = context.newRecord;
                var caseId = newRecord.id;

                // ─────────────────────────────────────────────────────────
                // 📚 MODULE 3: getValue() to read custom checkbox field
                // This determines if we show the email button
                // ─────────────────────────────────────────────────────────
                var serviceComplete = newRecord.getValue({
                    fieldId: 'custevent_service_complete'
                });
                
                log.debug('Service Complete Check', 
                    'Case ID: ' + caseId + ', Complete: ' + serviceComplete);

                // ─────────────────────────────────────────────────────────
                // 📚 MODULE 12: url.resolveScript() generates Suitelet URL
                // This creates a URL that calls another script
                // ─────────────────────────────────────────────────────────
                var printPdfURL = url.resolveScript({
                    scriptId: 'customscript_case_pdf_suitelet',
                    deploymentId: 'customdeploy_case_pdf_suitelet',
                    params: {
                        'caseid': caseId  // Pass case ID as URL parameter
                    }
                });

                // ─────────────────────────────────────────────────────────
                // 📚 MODULE 4: form.addButton() adds custom button
                // functionName: Client-side JavaScript to execute
                // ─────────────────────────────────────────────────────────
                form.addButton({
                    id: 'custpage_print_pdf',
                    label: 'Print PDF',
                    functionName: 'window.open(\'' + printPdfURL + '\', \'_blank\')'
                });

                log.debug('Print PDF Button Added', 'URL: ' + printPdfURL);

                // ─────────────────────────────────────────────────────────
                // 📚 BUSINESS LOGIC: Conditional button visibility
                // Only show email button if service is NOT complete
                // ─────────────────────────────────────────────────────────
                if (!serviceComplete || serviceComplete === false) {
                    
                    var sendEmailURL = url.resolveScript({
                        scriptId: 'customscript_case_send_email',
                        deploymentId: 'customdeploy_case_send_email',
                        params: {
                            'caseid': caseId
                        }
                    });

                    form.addButton({
                        id: 'custpage_send_email',
                        label: 'Get Customer Completion Email',
                        functionName: 'window.open(\'' + sendEmailURL + '\', \'_blank\')'
                    });

                    log.debug('Email Button Added', 'URL: ' + sendEmailURL);
                } else {
                    // 📚 MODULE 14: Use log.audit for important business events
                    log.audit('Button Skipped', 
                        'Case ' + caseId + ' - Service complete, email button hidden');
                }

            } catch (e) {
                // 📚 MODULE 14: Error handling with stack trace for debugging
                log.error('Error in beforeLoad', e.toString() + ' | Stack: ' + e.stack);
            }
        }

        // 📚 MODULE 4: Return object maps function to entry point
        return {
            beforeLoad: beforeLoad
        };
    });

Case Study 2: Case Completion System

System Architecture

Workflow Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│  TRIGGER: Button click from Case record (via ue_case_buttons.js)        │
└───────────────────────────────┬─────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────┐     ┌─────────────────────────────────┐
│  sl_case_send_email             │────▶│  Email sent to FSE with link    │
│  (Suitelet)                     │     │  to customer form               │
└─────────────────────────────────┘     └───────────────┬─────────────────┘
                                                        │
                        ┌───────────────────────────────┘
                        ▼
┌─────────────────────────────────┐     ┌─────────────────────────────────┐
│  sl_case_customer_form          │────▶│  FSE signs → Customer signs     │
│  (Public Suitelet)              │     │  → PDF generated → Team notified│
└─────────────────────────────────┘     └─────────────────────────────────┘
                        ▲
                        │ (Reminder links)
┌─────────────────────────────────┐
│  ss_case_deadline_reminder      │  ◀──── Runs hourly
│  (Scheduled Script)             │        • 42-hour: Send reminder
└─────────────────────────────────┘        • 72-hour: Auto-close case

Suitelet: Email Sender

/**
 * @NApiVersion 2.1
 * @NScriptType Suitelet
 * @NModuleScope SameAccount
 * 
 * 📚 MODULE 5: N/email for sending emails
 * 📚 MODULE 5: N/record for loading cases and creating messages
 * 📚 MODULE 12: Suitelet as a processing endpoint
 */
define(['N/email', 'N/record', 'N/log', 'N/url', 'N/runtime'],
    function(email, record, log, url, runtime) {

        function onRequest(context) {
            try {
                // 📚 MODULE 12: Get URL parameters from request
                var caseId = context.request.parameters.caseid;

                if (!caseId) {
                    context.response.write('Error: No Case ID provided');
                    return;
                }

                log.debug('Sending email', 'Case ID: ' + caseId);

                // 📚 MODULE 5: record.load() to get case data (10 governance units)
                var caseRecord = record.load({
                    type: record.Type.SUPPORT_CASE,
                    id: caseId
                });

                // 📚 MODULE 3: getValue() vs getText()
                // getValue = internal ID, getText = display name
                var caseNumber = caseRecord.getValue({fieldId: 'casenumber'});
                var caseTitle = caseRecord.getValue({fieldId: 'title'});
                var customerName = caseRecord.getText({fieldId: 'company'});

                // 📚 MODULE 12: Generate external URL for customer form
                // returnExternalUrl: true = full URL for non-NetSuite users
                var customerFormURL = url.resolveScript({
                    scriptId: 'customscript_case_customer_form',
                    deploymentId: 'customdeploy_case_customer_form',
                    params: { 'caseid': caseId },
                    returnExternalUrl: true
                });

                // 📚 BUSINESS LOGIC: Dynamic recipient from case assignment
                var emailAuthor = [SERVICE_EMPLOYEE_ID];
                var emailRecipient = caseRecord.getValue({fieldId: 'assigned'});

                if (!emailRecipient) {
                    var errorMsg = 'Error: Case ' + caseNumber + ' has no assigned user.';
                    log.error('sl_case_send_email Error', errorMsg);
                    context.response.write(errorMsg);
                    return;
                }

                // Build HTML email body
                var subject = 'ACTION REQUIRED: Get Customer Completion for Case #' + caseNumber;
                var body = '<html><body style="font-family: Arial, sans-serif;">';
                body += '<p>Please use this link to collect customer completion:</p>';
                body += '<p><strong>Case: ' + caseNumber + ' - ' + escapeHTML(caseTitle) + '</strong></p>';
                body += '<p><a href="' + customerFormURL + '">START CUSTOMER FORM</a></p>';
                body += '</body></html>';

                // 📚 MODULE 5: email.send() - sends email (20 governance units)
                email.send({
                    author: emailAuthor,
                    recipients: emailRecipient,
                    subject: subject,
                    body: body
                });

                log.audit('Email Sent', 'To: ' + emailRecipient + ', Case: ' + caseNumber);

                // ─────────────────────────────────────────────────────────
                // 📚 MODULE 5: Create Message record for audit trail
                // This logs the email in the Case's Communication subtab
                // ─────────────────────────────────────────────────────────
                try {
                    var messageRecord = record.create({
                        type: record.Type.MESSAGE
                    });

                    messageRecord.setValue({fieldId: 'author', value: emailAuthor});
                    messageRecord.setValue({fieldId: 'recipient', value: emailRecipient});
                    messageRecord.setValue({fieldId: 'subject', value: subject});
                    messageRecord.setValue({fieldId: 'message', value: body});
                    messageRecord.setValue({fieldId: 'entity', value: caseRecord.getValue({fieldId: 'company'})});
                    messageRecord.setValue({fieldId: 'activity', value: caseId});
                    messageRecord.setValue({fieldId: 'emailed', value: true});
                    messageRecord.setValue({fieldId: 'messagetype', value: 'emailout'});

                    var messageId = messageRecord.save();
                    log.audit('Message activity created', 'ID: ' + messageId);

                } catch (msgError) {
                    // 📚 MODULE 14: Non-critical error - log but don't fail
                    log.error('Could not create message', msgError.toString());
                }

                // 📚 MODULE 12: Write HTML response to browser
                var successHTML = '<html><body><h1>Email Sent Successfully!</h1>';
                successHTML += '<p>Case: ' + escapeHTML(caseNumber) + '</p>';
                successHTML += '<script>setTimeout(function(){ window.close(); }, 3000);</script>';
                successHTML += '</body></html>';

                context.response.write(successHTML);

            } catch (e) {
                log.error('Error in sl_case_send_email', e.toString());
                context.response.write('Error: ' + e.toString());
            }
        }

        // 📚 MODULE 15: Helper function for security
        function escapeHTML(text) {
            if (!text) return '';
            return text.replace(/&/g, '&amp;')
                       .replace(/'&lt;')
                       .replace(/>/g, '&gt;');
        }

        return { onRequest: onRequest };
    });

Suitelet: Customer Form (Key Excerpts)

GET/POST Request Handling

/**
 * 📚 MODULE 12: Suitelet with GET/POST handling
 * 
 * GET  = Display the form
 * POST = Process form submission
 */
function onRequest(context) {
    if (context.request.method === 'GET') {
        showForm(context);
    } else {
        processForm(context);
    }
}

Deadline Checking Logic

/**
 * 📚 MODULE 5: Using N/format for date parsing
 * Checks if the 72-hour deadline has passed
 */
var deadline = caseRecord.getValue({fieldId: 'custevent_signature_deadline'});
var deadlinePassed = false;

if (deadline) {
    // 📚 MODULE 5: format.parse() converts string to Date object
    var deadlineDate = format.parse({
        value: deadline,
        type: format.Type.DATETIME
    });
    var now = new Date();
    deadlinePassed = (now > deadlineDate);
}

// If locked, use submitFields to mark complete (more efficient than load/save)
if (deadlinePassed && !serviceCompleteFlag) {
    // 📚 MODULE 5: record.submitFields() - only 2 governance units!
    record.submitFields({
        type: record.Type.SUPPORT_CASE,
        id: caseId,
        values: {
            'custevent_service_complete': true
        },
        options: {
            enableSourcing: false,
            ignoreMandatoryFields: true
        }
    });
}

72-Hour Deadline Calculation

/**
 * When FSE signs, calculate the 72-hour deadline
 * 📚 MODULE 3: Working with Date objects
 */
var fseSignatureTimestamp = new Date();

// Calculate 72 hours from now (72 * 60 * 60 * 1000 milliseconds)
var deadlineTimestamp = new Date(fseSignatureTimestamp.getTime() + (72 * 60 * 60 * 1000));

// 📚 MODULE 3: Save both timestamps to case record
caseRecord.setValue({fieldId: 'custevent_fse_signature_dt_tm', value: fseSignatureTimestamp});
caseRecord.setValue({fieldId: 'custevent_signature_deadline', value: deadlineTimestamp});
caseRecord.save();

PDF Generation with N/render

/**
 * 📚 MODULE 12: PDF Generation with N/render
 * Uses FreeMarker template syntax in XML
 */
function generatePDF(caseId, signatureData) {
    // Load case for PDF data
    var caseRecord = record.load({
        type: record.Type.SUPPORT_CASE,
        id: caseId
    });
    
    // 📚 MODULE 12: XML template with BFO PDF syntax
    var xmlTemplate = '<?xml version="1.0"?>' +
        '<!DOCTYPE pdf PUBLIC "-//big.faceless.org//report" "report-1.1.dtd">' +
        '<pdf><head><style>...</style></head>' +
        '<body>' +
        '<h1>Case Completion Report</h1>' +
        '<p>Case: ${record.casenumber}</p>' +
        '...more template content...' +
        '</body></pdf>';
    
    // 📚 MODULE 12: render.create() for PDF generation
    var pdfRenderer = render.create();
    pdfRenderer.templateContent = xmlTemplate;
    
    // Add case record for template variables
    pdfRenderer.addRecord({
        templateName: 'record',
        record: caseRecord
    });
    
    // 📚 MODULE 12: renderAsPdf() creates file object
    var pdfFile = pdfRenderer.renderAsPdf();
    pdfFile.name = 'Case_Completion_' + caseNumber + '.pdf';
    pdfFile.folder = [PDF_FOLDER_ID];
    
    // 📚 MODULE 5: file.save() returns file ID
    var fileId = pdfFile.save();
    
    // Attach to case record
    record.attach({
        record: { type: 'file', id: fileId },
        to: { type: record.Type.SUPPORT_CASE, id: caseId }
    });
    
    return pdfFile;
}

Scheduled Script: Deadline Reminders

/**
 * @NApiVersion 2.1
 * @NScriptType ScheduledScript
 * 
 * 📚 MODULE 7: N/search for finding cases by criteria
 * 📚 MODULE 8: Scheduled Script processing pattern
 */
define(['N/search', 'N/record', 'N/log', 'N/email', 'N/url', 'N/runtime', 'N/format'],
    function(search, record, log, email, url, runtime, format) {

        /**
         * 📚 MODULE 8: execute() is the entry point for Scheduled Scripts
         */
        function execute(context) {
            log.audit('START', 'Scheduled Reminder Script Started');

            try {
                process42HourReminders();
                process72HourReminders();
                log.audit('END', 'Script Finished');
            } catch (err) {
                log.error('CRITICAL ERROR', err.toString());
            }
        }

        /**
         * 📚 MODULE 7: Search for cases eligible for 42-hour reminder
         */
        function process42HourReminders() {
            log.audit('42-HOUR', 'Starting 42-Hour Processing');

            // 📚 MODULE 7: search.create() with multiple filters
            var search42Hr = search.create({
                type: search.Type.SUPPORT_CASE,
                filters: [
                    // FSE has signed (signature timestamp exists)
                    ['custevent_fse_signature_dt_tm', 'isnotempty', ''],
                    'AND',
                    // Customer has NOT signed
                    ['custevent_signature_base64', 'isempty', ''],
                    'AND',
                    // 42-hour reminder not yet sent
                    ['custevent_42hr_reminder_sent', 'isempty', ''],
                    'AND',
                    // Customer email exists
                    ['custevent_customer_reminder_email', 'isnotempty', '']
                ],
                columns: [
                    'internalid',
                    'casenumber',
                    'company',
                    'custevent_customer_reminder_email',
                    'custevent_fse_signature_dt_tm',
                    'custevent_signature_deadline'
                ]
            });

            var count = 0;

            // 📚 MODULE 7: run().each() processes results one at a time
            search42Hr.run().each(function(result) {
                var caseId = result.getValue('internalid');

                try {
                    // Get FSE signature timestamp
                    var fseSignatureDateString = result.getValue('custevent_fse_signature_dt_tm');
                    
                    if (!fseSignatureDateString) {
                        return true;  // Continue to next result
                    }

                    // 📚 MODULE 5: format.parse() to convert string → Date
                    var fseSignatureDate = format.parse({
                        value: fseSignatureDateString,
                        type: format.Type.DATETIME
                    });

                    // Calculate 42 hours after FSE signature
                    var fortyTwoHoursAfter = new Date(
                        fseSignatureDate.getTime() + (42 * 60 * 60 * 1000)
                    );
                    var now = new Date();

                    // Only process if 42 hours have passed
                    if (now < fortyTwoHoursAfter) {
                        return true;  // Not time yet, continue
                    }

                    // Get case details for email
                    var caseNumber = result.getValue('casenumber');
                    var companyName = result.getText('company') || 'Customer';
                    var customerEmail = result.getValue('custevent_customer_reminder_email');

                    // 📚 MODULE 12: Generate form URL for reminder email
                    var formURL = url.resolveScript({
                        scriptId: 'customscript_case_customer_form',
                        deploymentId: 'customdeploy_case_customer_form',
                        params: { 'caseid': caseId },
                        returnExternalUrl: true
                    });

                    // Build and send reminder email
                    var emailSubject = 'Reminder: Signature Deadline Approaching - Case #' + caseNumber;
                    var emailBody = '<p>Dear ' + companyName + ',</p>';
                    emailBody += '<p>Your Case Completion Form deadline is approaching. You have 30 hours remaining.</p>';
                    emailBody += '<p><a href="' + formURL + '">CLICK HERE TO SIGN</a></p>';

                    // 📚 MODULE 5: email.send() with relatedRecords for case linking
                    email.send({
                        author: [SERVICE_EMPLOYEE_ID],
                        recipients: customerEmail,
                        subject: emailSubject,
                        body: emailBody,
                        relatedRecords: {
                            activityId: caseId  // Links email to case
                        }
                    });

                    // 📚 MODULE 5: Mark reminder as sent (efficient update)
                    record.submitFields({
                        type: record.Type.SUPPORT_CASE,
                        id: caseId,
                        values: {
                            'custevent_42hr_reminder_sent': new Date()
                        }
                    });

                    log.audit('42-HOUR SENT', 'Case #' + caseNumber);
                    count++;

                } catch (e) {
                    log.error('42-HOUR Case ' + caseId + ' FAILED', e.toString());
                }

                return true;  // Continue to next result
            });

            log.audit('42-HOUR COMPLETE', 'Processed ' + count + ' reminder(s)');
        }

        // Similar pattern for process72HourReminders()...
        // At 72 hours: send timeout notice, set service complete, notify billing team

        return { execute: execute };
    });

Custom Fields Reference