Module 6: Scripting Sublists

🎯 Learning Objectives

• Understand what sublists are and their structure
• Read values from sublist lines
• Add, modify, and remove sublist lines
• Work with sublists in both standard and dynamic mode
• Find sublist and field IDs using the Records Browser

1. What Are Sublists?

A sublist is a list of related records displayed as a table within a parent record. For example, a Sales Order has an "Items" sublist containing all the line items being sold.

Common Sublists

Record Type	Sublist ID	Contains
Sales Order	item	Line items
Invoice	item	Billable items
Purchase Order	item, expense	Items and expenses
Customer	addressbook	Addresses
Employee	roles	Assigned roles

2. Sublist Elements

Every sublist has three key elements you need to know:

1. Sublist ID - The internal name of the sublist (e.g., item)
2. Field ID - The column name (e.g., quantity, rate)
3. Line Number - Zero-based index (first line = 0)

// To access a value, you need all three:
record.getSublistValue({
    sublistId: 'item',      // Which sublist
    fieldId: 'quantity',    // Which column
    line: 0                 // Which row (0-based)
});

3. Reading Sublist Values

Get Line Count

var lineCount = record.getLineCount({ sublistId: 'item' });
log.debug('Number of lines', lineCount);

Get Value from Specific Line

// Get quantity from first line
var qty = record.getSublistValue({
    sublistId: 'item',
    fieldId: 'quantity',
    line: 0
});

// Get text display (for list fields)
var itemName = record.getSublistText({
    sublistId: 'item',
    fieldId: 'item',
    line: 0
});

Loop Through All Lines

var lineCount = record.getLineCount({ sublistId: 'item' });

for (var i = 0; i < lineCount; i++) {
    var itemId = record.getSublistValue({
        sublistId: 'item',
        fieldId: 'item',
        line: i
    });
    var qty = record.getSublistValue({
        sublistId: 'item',
        fieldId: 'quantity',
        line: i
    });
    var rate = record.getSublistValue({
        sublistId: 'item',
        fieldId: 'rate',
        line: i
    });
    
    log.debug('Line ' + i, 'Item: ' + itemId + ', Qty: ' + qty + ', Rate: ' + rate);
}

4. Writing to Sublists (Standard Mode)

Set Value on Existing Line

record.setSublistValue({
    sublistId: 'item',
    fieldId: 'quantity',
    line: 0,
    value: 10
});

Insert a New Line

// Insert at specific position
record.insertLine({
    sublistId: 'item',
    line: 0  // Insert at beginning
});

// Set values on the new line
record.setSublistValue({
    sublistId: 'item',
    fieldId: 'item',
    line: 0,
    value: 123  // Item internal ID
});
record.setSublistValue({
    sublistId: 'item',
    fieldId: 'quantity',
    line: 0,
    value: 5
});

Remove a Line

record.removeLine({
    sublistId: 'item',
    line: 2  // Remove third line
});

5. Dynamic Mode Operations

In dynamic mode, you work with sublists like a user would in the UI:

// Load record in dynamic mode
var salesOrder = record.load({
    type: record.Type.SALES_ORDER,
    id: 123,
    isDynamic: true
});

// Select a new line
salesOrder.selectNewLine({ sublistId: 'item' });

// Set values on current line
salesOrder.setCurrentSublistValue({
    sublistId: 'item',
    fieldId: 'item',
    value: 456
});
salesOrder.setCurrentSublistValue({
    sublistId: 'item',
    fieldId: 'quantity',
    value: 10
});

// Commit the line (like clicking Add)
salesOrder.commitLine({ sublistId: 'item' });

salesOrder.save();

Dynamic Mode Methods

Method	Purpose
selectLine	Select existing line for editing
selectNewLine	Start adding a new line
setCurrentSublistValue	Set value on selected line
getCurrentSublistValue	Get value from selected line
commitLine	Save the current line
cancelLine	Discard changes to current line

🏋️ Practice Exercises