Custom Lists

Custom Lists provide predefined dropdown options for custom fields, ensuring consistent data entry across records.

When to Use Custom Lists

Use Case	Example
Status values	Pending, Approved, Rejected
Categories	Product categories, regions
Priority levels	Low, Medium, High, Critical
Rating scales	1-5 stars, A-F grades
Configuration	Fixed options for settings

Custom List Structure

┌─────────────────────────────────────────────────────────────────────────────┐
│                    CUSTOM LIST ARCHITECTURE                                  │
└─────────────────────────────────────────────────────────────────────────────┘

     ┌──────────────────────────────────────────────────────────────────┐
     │  CUSTOM LIST DEFINITION                                           │
     │  customlist_approval_status                                       │
     │  ────────────────────────────────────────────────────────────────│
     │  Name: Approval Status                                           │
     │  Description: Status values for approval workflow                │
     │  Is Ordered: Yes                                                 │
     │  Convert to Custom Record: No                                    │
     └──────────────────────────────────────────────────────────────────┘
                                    │
                                    │ Contains
                                    ▼
     ┌──────────────────────────────────────────────────────────────────┐
     │  LIST VALUES                                                      │
     │  ────────────────────────────────────────────────────────────────│
     │  ID: 1  │  Script ID: val_pending   │  Value: Pending            │
     │  ID: 2  │  Script ID: val_approved  │  Value: Approved           │
     │  ID: 3  │  Script ID: val_rejected  │  Value: Rejected           │
     │  ID: 4  │  Script ID: val_cancelled │  Value: Cancelled          │
     └──────────────────────────────────────────────────────────────────┘
                                    │
                                    │ Used by
                                    ▼
     ┌──────────────────────────────────────────────────────────────────┐
     │  CUSTOM FIELDS                                                    │
     │  ────────────────────────────────────────────────────────────────│
     │  custbody_approval_status   (Transaction Body)                   │
     │  custrecord_ia_status       (Custom Record)                      │
     │  custentity_vendor_status   (Entity)                             │
     └──────────────────────────────────────────────────────────────────┘

Basic Custom List XML

<?xml version="1.0" encoding="UTF-8"?>
<customlist scriptid="customlist_approval_status">
    <name>Approval Status</name>
    <description>Status values for approval workflows</description>

    <!-- Ordering -->
    <isordered>T</isordered>

    <!-- Matrix options (for dimension fields) -->
    <ismatrixoption>F</ismatrixoption>

    <!-- Custom values -->
    <customvalues>
        <customvalue scriptid="val_pending">
            <value>Pending</value>
            <abbreviation>P</abbreviation>
            <isinactive>F</isinactive>
        </customvalue>

        <customvalue scriptid="val_in_review">
            <value>In Review</value>
            <abbreviation>R</abbreviation>
            <isinactive>F</isinactive>
        </customvalue>

        <customvalue scriptid="val_approved">
            <value>Approved</value>
            <abbreviation>A</abbreviation>
            <isinactive>F</isinactive>
        </customvalue>

        <customvalue scriptid="val_rejected">
            <value>Rejected</value>
            <abbreviation>X</abbreviation>
            <isinactive>F</isinactive>
        </customvalue>

        <customvalue scriptid="val_cancelled">
            <value>Cancelled</value>
            <abbreviation>C</abbreviation>
            <isinactive>F</isinactive>
        </customvalue>
    </customvalues>

</customlist>

List Value Properties

Property	Description
`scriptid`	Unique identifier for the value
`value`	Display text shown in dropdown
`abbreviation`	Short code (optional)
`isinactive`	T/F - hide from dropdowns

Common Custom Lists

Priority Levels

<?xml version="1.0" encoding="UTF-8"?>
<customlist scriptid="customlist_priority">
    <name>Priority</name>
    <description>Priority levels</description>
    <isordered>T</isordered>

    <customvalues>
        <customvalue scriptid="val_low">
            <value>Low</value>
            <abbreviation>L</abbreviation>
        </customvalue>

        <customvalue scriptid="val_medium">
            <value>Medium</value>
            <abbreviation>M</abbreviation>
        </customvalue>

        <customvalue scriptid="val_high">
            <value>High</value>
            <abbreviation>H</abbreviation>
        </customvalue>

        <customvalue scriptid="val_critical">
            <value>Critical</value>
            <abbreviation>C</abbreviation>
        </customvalue>
    </customvalues>
</customlist>

Region List

<?xml version="1.0" encoding="UTF-8"?>
<customlist scriptid="customlist_regions">
    <name>Sales Regions</name>
    <description>Geographic sales regions</description>
    <isordered>T</isordered>

    <customvalues>
        <customvalue scriptid="val_northeast">
            <value>Northeast</value>
            <abbreviation>NE</abbreviation>
        </customvalue>

        <customvalue scriptid="val_southeast">
            <value>Southeast</value>
            <abbreviation>SE</abbreviation>
        </customvalue>

        <customvalue scriptid="val_midwest">
            <value>Midwest</value>
            <abbreviation>MW</abbreviation>
        </customvalue>

        <customvalue scriptid="val_west">
            <value>West</value>
            <abbreviation>W</abbreviation>
        </customvalue>

        <customvalue scriptid="val_international">
            <value>International</value>
            <abbreviation>INTL</abbreviation>
        </customvalue>
    </customvalues>
</customlist>

Product Categories

<?xml version="1.0" encoding="UTF-8"?>
<customlist scriptid="customlist_product_category">
    <name>Product Category</name>
    <description>Product classification categories</description>
    <isordered>T</isordered>

    <customvalues>
        <customvalue scriptid="val_electronics">
            <value>Electronics</value>
            <abbreviation>ELEC</abbreviation>
        </customvalue>

        <customvalue scriptid="val_clothing">
            <value>Clothing</value>
            <abbreviation>CLOTH</abbreviation>
        </customvalue>

        <customvalue scriptid="val_furniture">
            <value>Furniture</value>
            <abbreviation>FURN</abbreviation>
        </customvalue>

        <customvalue scriptid="val_food">
            <value>Food & Beverage</value>
            <abbreviation>FOOD</abbreviation>
        </customvalue>

        <customvalue scriptid="val_services">
            <value>Services</value>
            <abbreviation>SVC</abbreviation>
        </customvalue>

        <customvalue scriptid="val_other">
            <value>Other</value>
            <abbreviation>OTH</abbreviation>
        </customvalue>
    </customvalues>
</customlist>

Using Custom Lists in Fields

In Custom Record Field

<customrecordcustomfield scriptid="custrecord_priority">
    <label>Priority</label>
    <fieldtype>SELECT</fieldtype>
    <selectrecordtype>[customlist_priority]</selectrecordtype>
    <ismandatory>T</ismandatory>
    <defaultvalue>2</defaultvalue>  <!-- Medium = 2nd value -->
</customrecordcustomfield>

In Transaction Body Field

<transactionbodycustomfield scriptid="custbody_approval_status">
    <label>Approval Status</label>
    <fieldtype>SELECT</fieldtype>
    <selectrecordtype>[customlist_approval_status]</selectrecordtype>
    <displaytype>NORMAL</displaytype>
</transactionbodycustomfield>

In Entity Field

<entitycustomfield scriptid="custentity_region">
    <label>Sales Region</label>
    <fieldtype>SELECT</fieldtype>
    <selectrecordtype>[customlist_regions]</selectrecordtype>
    <appliestocustomer>T</appliestocustomer>
</entitycustomfield>

Working with Lists in Scripts

Getting List Value by ID

const record = require('N/record');

// When you get a SELECT field value, you get the internal ID
const salesOrder = record.load({
    type: record.Type.SALES_ORDER,
    id: 12345
});

// Get internal ID of selected value
const statusId = salesOrder.getValue({
    fieldId: 'custbody_approval_status'
});  // Returns: 1, 2, 3, etc.

// Get display text of selected value
const statusText = salesOrder.getText({
    fieldId: 'custbody_approval_status'
});  // Returns: "Pending", "Approved", etc.

Setting List Value

// Set by internal ID
salesOrder.setValue({
    fieldId: 'custbody_approval_status',
    value: 2  // ID of "Approved"
});

// Set by text
salesOrder.setText({
    fieldId: 'custbody_approval_status',
    text: 'Approved'
});

Searching by List Value

const search = require('N/search');

// Search by internal ID
const approvedOrders = search.create({
    type: search.Type.SALES_ORDER,
    filters: [
        ['custbody_approval_status', 'anyof', 2]  // ID of Approved
    ]
});

// Search by text (using 'is' operator)
const pendingOrders = search.create({
    type: search.Type.SALES_ORDER,
    filters: [
        ['custbody_approval_status', 'is', 'Pending']
    ]
});

Getting All List Values

const search = require('N/search');

const getListValues = (listId) => {
    const values = [];

    const listSearch = search.create({
        type: 'customlist' + listId.replace('customlist_', ''),
        columns: ['name', 'abbreviation', 'isinactive']
    });

    listSearch.run().each((result) => {
        values.push({
            id: result.id,
            name: result.getValue('name'),
            abbreviation: result.getValue('abbreviation'),
            inactive: result.getValue('isinactive')
        });
        return true;
    });

    return values;
};

// Usage
const statusValues = getListValues('customlist_approval_status');

List Value Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                    LIST VALUE FLOW                                           │
└─────────────────────────────────────────────────────────────────────────────┘

     ┌──────────────────────────────────────────────────────────────────┐
     │  CUSTOM LIST: customlist_approval_status                         │
     │  ────────────────────────────────────────────────────────────────│
     │  1: Pending    (val_pending)                                     │
     │  2: Approved   (val_approved)                                    │
     │  3: Rejected   (val_rejected)                                    │
     └──────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
     ┌──────────────────────────────────────────────────────────────────┐
     │  DROPDOWN DISPLAY                                                 │
     │  ┌──────────────────────────────────────────────────────────┐    │
     │  │  Approval Status: [Pending            ▼]                 │    │
     │  │                   ├──────────────────────┤               │    │
     │  │                   │ Pending              │               │    │
     │  │                   │ Approved             │               │    │
     │  │                   │ Rejected             │               │    │
     │  │                   └──────────────────────┘               │    │
     │  └──────────────────────────────────────────────────────────┘    │
     └──────────────────────────────────────────────────────────────────┘
                                    │
                                    │ User selects "Approved"
                                    ▼
     ┌──────────────────────────────────────────────────────────────────┐
     │  STORAGE                                                          │
     │  ────────────────────────────────────────────────────────────────│
     │  Field: custbody_approval_status                                 │
     │  Stored Value: 2 (Internal ID)                                   │
     │  Display Text: Approved                                          │
     └──────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
     ┌──────────────────────────────────────────────────────────────────┐
     │  SCRIPT ACCESS                                                    │
     │  ────────────────────────────────────────────────────────────────│
     │  getValue() → 2                                                  │
     │  getText()  → "Approved"                                         │
     └──────────────────────────────────────────────────────────────────┘

Converting List to Custom Record

For lists that need additional fields (like color codes, thresholds, etc.), convert to custom record:

┌─────────────────────────────────────────────────────────────────────────────┐
│                    LIST VS CUSTOM RECORD                                     │
└─────────────────────────────────────────────────────────────────────────────┘

     CUSTOM LIST (Simple)                CUSTOM RECORD (Extended)
     ────────────────────────            ────────────────────────────
     • Value only                        • Multiple fields
     • Static options                    • Additional metadata
     • No relationships                  • Can have relationships
     • Quick setup                       • More flexible

     Example: Priority                   Example: Priority with Threshold
     ┌──────────────────┐               ┌──────────────────────────────────┐
     │ 1: Low           │               │ ID: 1                            │
     │ 2: Medium        │   →→→         │ Name: Low                        │
     │ 3: High          │               │ Color: #00FF00                   │
     │                  │               │ SLA Hours: 72                    │
     └──────────────────┘               │ Escalation Email: ...            │
                                        └──────────────────────────────────┘

Custom Record for Extended List

<?xml version="1.0" encoding="UTF-8"?>
<customrecordtype scriptid="customrecord_priority_config">
    <recordname>Priority Configuration</recordname>
    <includename>T</includename>

    <customrecordcustomfields>
        <customrecordcustomfield scriptid="custrecord_pc_color">
            <label>Color Code</label>
            <fieldtype>TEXT</fieldtype>
        </customrecordcustomfield>

        <customrecordcustomfield scriptid="custrecord_pc_sla_hours">
            <label>SLA Hours</label>
            <fieldtype>INTEGER</fieldtype>
        </customrecordcustomfield>

        <customrecordcustomfield scriptid="custrecord_pc_escalation_to">
            <label>Escalate To</label>
            <fieldtype>SELECT</fieldtype>
            <selectrecordtype>-4</selectrecordtype>
        </customrecordcustomfield>
    </customrecordcustomfields>
</customrecordtype>

Import Existing Lists

# Import all custom lists
suitecloud object:import --type customlist --destinationfolder Objects

# Import specific list
suitecloud object:import --type customlist --scriptid customlist_approval_status --destinationfolder Objects

Best Practices

Practice	Description
Meaningful scriptids	Use descriptive IDs: `val_approved` not `val_2`
Ordered lists	Use `isordered="T"` for logical display order
Include abbreviations	Helpful for reports and exports
Consider conversion	Use custom records for complex options
Inactive vs delete	Set inactive instead of deleting values

Inactive Values

Mark values as inactive instead of deleting:

<customvalue scriptid="val_old_status">
    <value>Legacy Status</value>
    <isinactive>T</isinactive>  <!-- Hidden from new selections -->
</customvalue>

Inactive values:

Don't appear in dropdowns
Still display on existing records
Preserve historical data integrity

Next Steps

Saved Searches - Filter by list values
Custom Records - Extended list alternatives
Custom Fields - Link lists to fields

When to Use Custom Lists​

Custom List Structure​

Basic Custom List XML​

List Value Properties​

Common Custom Lists​

Priority Levels​

Region List​

Product Categories​

Using Custom Lists in Fields​

In Custom Record Field​

In Transaction Body Field​

In Entity Field​

Working with Lists in Scripts​

Getting List Value by ID​

Setting List Value​

Searching by List Value​

Getting All List Values​

List Value Flow​

Converting List to Custom Record​

Custom Record for Extended List​

Import Existing Lists​

Best Practices​

Inactive Values​

Next Steps​