Module 3: Using SuiteScript Objects

🎯 Learning Objectives

By the end of this module, you will be able to:

• Understand what the context object is and how to use it
• Extract the record object from context
• Get and set field values correctly using the right methods
• Choose the appropriate log level for different situations
• Debug server-side scripts using the SuiteScript Debugger
• Avoid common mistakes like using DOM directly

1. The Context Object

What Is It?

Every entry point function in SuiteScript 2.x receives a context object. Think of it as a "package of information" that NetSuite hands to your function, containing everything you need to know about the current operation.

Basic Structure

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/log'], function(log) {
    
    function afterSubmit(context) {
        // context is passed automatically by NetSuite
        // It contains info about this specific execution
        
        log.debug('Context Type', context.type);  // 'create', 'edit', etc.
    }
    
    return { afterSubmit: afterSubmit };
});

Common Context Properties

2. Getting the Record Object

newRecord vs oldRecord

The context object gives you access to the record through two properties:

function afterSubmit(context) {
    // Get the current state of the record
    var currentRecord = context.newRecord;
    
    // Get the previous state (only on edit/delete)
    var previousRecord = context.oldRecord;
    
    // Example: Compare old vs new values
    if (context.type === 'edit') {
        var oldStatus = previousRecord.getValue('status');
        var newStatus = currentRecord.getValue('status');
        
        if (oldStatus !== newStatus) {
            log.audit('Status Changed', 'From ' + oldStatus + ' to ' + newStatus);
        }
    }
}

Standard Fields vs Custom Fields

Standard fields are created by NetSuite and exist in all accounts (e.g., companyname, email, entity). Custom fields are created by administrators for specific business needs.

3. getValue() vs getText()

This is one of the most important concepts in SuiteScript. Choosing the wrong method is a common source of bugs.

The Rule

For Regular Fields (No Dropdown)

// Text, number, date, email, etc. — always use getValue()
var customerName = record.getValue('companyname');  // "Acme Corp"
var email = record.getValue('email');               // "john@acme.com"
var phone = record.getValue('phone');               // "555-1234"
var amount = record.getValue('amount');             // 1500.00

For Dropdown/List Fields

// List fields (dropdowns) — you have a choice
var salesRepId = record.getValue('salesrep');    // Returns: 42 (internal ID)
var salesRepName = record.getText('salesrep');   // Returns: "John Smith" (display text)

var statusId = record.getValue('status');        // Returns: "A" (internal value)
var statusText = record.getText('status');       // Returns: "Approved" (display text)

// WRONG - email is not a dropdown
var email = record.getText('email');  // Returns: null

// CORRECT
var email = record.getValue('email'); // Returns: "john@acme.com"

4. setValue() vs setText()

Setting values follows similar rules, but with an important difference in syntax.

// Setting a regular field value
record.setValue({
    fieldId: 'custbody_notes',
    value: 'Approved by manager'
});

// Setting a dropdown by ID (most common)
record.setValue({
    fieldId: 'salesrep',
    value: 42  // Internal ID of the sales rep
});

// Setting a dropdown by text (when you don't know the ID)
record.setText({
    fieldId: 'salesrep',
    text: 'John Smith'  // Display name - NetSuite looks up the ID
});

5. Log Levels Explained

NetSuite provides four log levels, each with a specific purpose:

log.debug('Title', 'Detail message');     // Development
log.audit('Status Changed', 'A to B');    // Business tracking
log.error('API Failed', error.message);   // Error handling
log.emergency('Critical', 'Data loss!');  // Rarely needed

How Log Levels Work on Deployments

Each script deployment has a "Log Level" setting that acts as a filter:

6. Why Never Use DOM

If you have JavaScript experience, you might be tempted to access form elements directly using document.getElementById() or similar DOM methods. Don't do this.

// DOM manipulation - WRONG!
var field = document.getElementById('salesrep');
field.value = 42;

// SuiteScript API - CORRECT
record.setValue({
    fieldId: 'salesrep',
    value: 42
});

Why DOM Access is Dangerous

1. Not Future-Proof: NetSuite can change the underlying HTML element names in any release. Your script will break.
2. Bypasses Validation: SuiteScript's setValue() triggers sourcing, field validation, and other built-in logic. DOM doesn't.
3. Cross-Browser Issues: SuiteScript handles browser differences. DOM code might work in Chrome but fail in Safari.
4. Server Sync Issues: DOM changes may not sync to the server correctly, causing data corruption.

7. Debugging SuiteScript

Server-Side Debugging

For User Event scripts and other server-side code, use NetSuite's built-in Script Debugger:

1. Navigate to Customization → Scripting → Script Debugger
2. Click "Debug Existing" and select your script
3. Set breakpoints by clicking line numbers
4. Trigger your script (e.g., save a record)
5. Use the debugger to step through code

Debugger Features

Using REQUIRE for Quick Tests

When testing small code snippets in the debugger, use require instead of define:

// Quick test script (no return statement needed)
require(['N/search', 'N/log'], function(search, log) {
    var results = search.create({
        type: 'customer',
        filters: [['email', 'contains', '@acme.com']],
        columns: ['companyname', 'email']
    }).run().getRange({ start: 0, end: 10 });
    
    log.debug('Results', JSON.stringify(results));
});

🏋️ Practice Exercises