Insert a new record with GlideRecord

The critical distinction between setValue() and direct assignment isn't just style — it fundamentally changes how ServiceNow processes your data. setValue() triggers the full platform pipeline: display value conversion, data validation, ACL checks, and reference field resolution. Direct assignment writes the raw value straight to the database field. Most developers use them interchangeably and wonder why their reference fields are empty or their choice values are wrong. The pattern isn't about preference — it's about understanding what processing you need ServiceNow to perform on each field.

When to use this pattern

• Creating records in Business Rules, Script Includes, or Scheduled Jobs where you control the field values
• When you need the sys_id of the newly created record for additional processing or linking
• Creating one or a few records at a time — this isn't a bulk operation API
• When you need reference fields properly resolved and choice fields validated by the platform

When NOT to use this pattern

• In client scripts — use GlideAjax to call a Script Include that performs the insert server-side
• For bulk operations over hundreds of records — use GlideBulkProcessor or the Import Set API instead
• Inside loops over large result sets — each insert() is a separate database transaction that will kill performance
• When you need to bypass all Business Rules and ACLs — use direct database operations or Import Sets with transform maps

Key behaviors and gotchas

• initialize() sets default values from the table schema and runs any Business Rules that fire on before operations
• setValue('state', '1') accepts display values and converts them — state = 1 requires the exact integer
• Reference fields set with setValue() resolve display names to sys_id values — direct assignment requires the actual sys_id
• insert() returns the sys_id of the new record or null if the insert failed due to ACL restrictions or validation errors
• Auto-generated fields like number are populated after insert() completes — access them from the GlideRecord object, not the return value
• Business Rules with before and after insert conditions will fire — plan for this if you're creating records of the same table