GlideRecord.insert() — ServiceNow API

insert()→ string

beginnerTested on Xanadu

What It Does

The insert() method takes all field values currently set on the GlideRecord object and creates a new record in the target table. ServiceNow assigns a new sys_id, sets audit fields like sys_created_on and sys_created_by, and persists the record to the database. The method executes synchronously and blocks until the database transaction completes.

Internally, ServiceNow validates the insert operation through multiple layers. ACL checks run first to ensure the current user has create rights on the table. Required field validation follows, checking that all mandatory fields contain values. The platform then executes 'before' Business Rules, which can modify field values or abort the operation entirely by setting current.setAbortAction(true).

The method returns the sys_id as a 32-character string if successful. It returns null when the insert fails due to ACL violations, Business Rule aborts, or database constraints. Unlike some ServiceNow APIs, insert() does not throw exceptions for typical failure scenarios—it simply returns null and logs the error.

Edge cases include attempting to insert with a pre-set sys_id (which ServiceNow ignores, generating a new one), inserting into tables with complex field dependencies, and working with reference fields that point to non-existent records. The method also handles display value resolution differently than update()—reference fields must contain valid sys_ids, not display values, unless you explicitly use setDisplayValue() before inserting.

The method differs from update() in that it creates rather than modifies, and from insertMultiple() in that it handles only single records. Unlike newRecord(), which only initializes a GlideRecord for population, insert() commits data to the database immediately.

When to Use This

Use insert() when creating new records programmatically in server-side scripts. Common scenarios include generating child records from parent records, creating follow-up tasks in Business Rules, importing data from external systems, and auto-generating records based on scheduled job logic. This is the primary method for single-record creation when you need full Business Rule execution and proper audit trail generation.

Avoid insert() for bulk operations where you need to create hundreds or thousands of records—use the Import Sets API or insertMultiple() instead for better performance. Don't use it in client-side scripts (it won't work), and avoid it in loops within Business Rules where the same Business Rule might trigger recursively. For simple logging or audit records where Business Rules aren't needed, consider direct database APIs for better performance.

Common misuse includes calling insert() on a GlideRecord object that was retrieved with get() or next()—this creates duplicate records rather than updating existing ones. Always use newRecord() or a fresh GlideRecord instantiation for inserts.

Return Value

Success returns a 32-character hexadecimal string representing the new record's sys_id (e.g., '2b1e8d4f1b8f4450b89b7a4c2e4f6g8h'). This sys_id is immediately usable for queries, references, and API calls. Failure returns null (JavaScript null, not the string 'null'). The GlideRecord object itself is also updated with the new sys_id on successful insert, making subsequent operations on the same object reference the newly created record.

Always check for null return values before using the result. Common safe patterns include if (sysId) { ... } or var sysId = gr.insert(); if (!sysId) { gs.error('Insert failed'); return; }. The sys_id can be safely stored in string variables, passed to other functions, or used as reference field values without further processing.

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

Platform Behavior & Side Effects

Executes 'before' Business Rules first, then 'after' Business Rules following the database insert, with full access to the new sys_id
Performs ACL checks for 'create' operation on the target table, returning null if user lacks permissions rather than throwing exceptions
Automatically populates sys_created_on, sys_created_by, sys_updated_on, sys_updated_by, and generates a unique sys_id
Triggers notifications, workflow activities, and other record-watch mechanisms configured for the table
Creates audit log entries if auditing is enabled for the table, recording the insert operation and field values
Performance is moderate—faster than complex queries but slower than bulk operations; expect 10-50ms per insert depending on Business Rules
Commits immediately in most contexts, but respects transaction boundaries when called within explicit database transactions

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Code Examples

Basic incident creation with required fieldsbasic

// Create a new incident with minimal required information
var incident = new GlideRecord('incident');
incident.short_description = 'Database connection timeout';
incident.caller_id = gs.getUserID(); // Current user as caller
incident.category = 'software';
incident.subcategory = 'database';
incident.priority = 3;
incident.state = 1; // New

var sysId = incident.insert();
if (sysId) {
    gs.info('Created incident: ' + sysId);
    gs.info('Incident number: ' + incident.number); // Auto-generated
} else {
    gs.error('Failed to create incident - check ACLs and required fields');
}

Demonstrates basic record creation with proper null checking. The incident number is auto-generated by Business Rules after insert, making it available on the GlideRecord object.

Creating child records with reference relationshipsintermediate

// Create a catalog task for each item in a request
var reqItem = new GlideRecord('sc_req_item');
if (reqItem.get('sys_id', current.sys_id)) {
    
    // Create approval record linked to the request item
    var approval = new GlideRecord('sysapproval_approver');
    approval.sysapproval = reqItem.sys_id; // Parent request item
    approval.approver = reqItem.request.requested_for; // Manager approval
    approval.state = 'requested';
    approval.due_date = new GlideDateTime().addDaysUTC(3);
    
    var approvalId = approval.insert();
    if (approvalId) {
        gs.info('Created approval: ' + approvalId + ' for request ' + reqItem.number);
    }
}

Shows how to create related records using reference fields. The parent record's sys_id becomes the reference value in the child record, establishing the relationship.

The classic mistake - inserting existing recordsadvanced

// WRONG: This creates duplicates instead of updating
var user = new GlideRecord('sys_user');
if (user.get('user_name', 'john.doe')) {
    user.email = 'john.doe@newcompany.com';
    user.insert(); // WRONG! Creates duplicate user
}

// RIGHT: Check existence and update or create appropriately
var user = new GlideRecord('sys_user');
if (user.get('user_name', 'john.doe')) {
    user.email = 'john.doe@newcompany.com';
    user.update(); // Updates existing record
} else {
    user.user_name = 'john.doe';
    user.email = 'john.doe@newcompany.com';
    user.first_name = 'John';
    user.last_name = 'Doe';
    user.insert(); // Creates new record only if not found
}

Demonstrates the most common insert() mistake—calling it on records retrieved with get() or next(). Always use update() for existing records and insert() only for genuinely new records.

Gotchas

Calling insert() on a GlideRecord retrieved with get() or next() creates a duplicate record instead of updating the existing one.

The method returns null for ACL violations without throwing exceptions, so always check the return value before assuming success.

Setting sys_id manually before insert() is ignored—ServiceNow always generates a new unique sys_id for inserted records.

Reference fields must contain valid sys_ids, not display values, unless you use setDisplayValue() before calling insert().

Business Rules can abort the insert by calling current.setAbortAction(true), causing insert() to return null with no clear error message.

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue