UTIL_SObject

Class · Group: Utilities

global inherited sharing class UTIL_SObject

SObject runtime operations — filtering, field extraction, list-to-map conversion, and dot-notation field value retrieval.

Example

Set<Id> accountIds = UTIL_SObject.extractIds(contacts, Contact.AccountId, true);
Map<Id, List<SObject>> contactsByAccount = UTIL_SObject.groupByKey(contacts, Contact.AccountId);
List<SObject> changed = UTIL_SObject.getChangedRecords(newRecords, oldRecords, Account.Name);

---

Methods

Method	Description
global static Set<Id> extractIds(List<SObject> objects)	Extracts a unique set of Ids from a list of SObjects using the Id field.
global static Set<Id> extractIds(List<SObject> objects, Boolean ignoreNulls)	Extracts a unique set of Ids from a list of SObjects using the Id field.
global static Set<Id> extractIds(List<SObject> objects, SObjectField objectField)	Extracts a unique set of Ids from a list of SObjects using a typed field token.
global static Set<Id> extractIds(List<SObject> objects, SObjectField objectField, Boolean ignoreNulls)	Extracts a unique set of Ids from a list of SObjects using a typed field token with null filtering.
global static Set<Id> extractIds(List<SObject> objects, String fieldName)	Extracts a unique set of Ids from a list of SObjects using a named field.
global static Set<Id> extractIds(List<SObject> objects, String fieldName, Boolean ignoreNulls)	Extracts a unique set of Ids from a list of SObjects using a named field with null filtering.
global static Set<String> extractUniqueValues(List<SObject> objects, SObjectField objectField)	Extracts a unique set of field values as strings from a list of SObjects using a typed field token.
global static Set<String> extractUniqueValues(List<SObject> objects, SObjectField objectField, Boolean ignoreBlankValues)	Extracts a unique set of field values as strings from a list of SObjects using a typed field token with blank filtering.
global static Set<String> extractUniqueValues(List<SObject> objects, String fieldName)	Extracts a unique set of field values as strings from a list of SObjects.
global static Set<String> extractUniqueValues(List<SObject> objects, String fieldName, Boolean ignoreBlankValues)	Extracts a unique set of field values as strings from a list of SObjects with blank filtering.
global static List<String> extractValues(List<SObject> objects, SObjectField objectField)	Extracts field values as strings from a list of SObjects using a typed field token.
global static List<String> extractValues(List<SObject> objects, SObjectField objectField, Boolean ignoreBlankValues)	Extracts field values as strings from a list of SObjects using a typed field token with blank filtering.
global static List<String> extractValues(List<SObject> objects, String fieldName)	Extracts field values as strings from a list of SObjects.
global static List<String> extractValues(List<SObject> objects, String fieldName, Boolean ignoreBlankValues)	Extracts field values as strings from a list of SObjects with blank filtering.
global static List<SObject> findWhere(List<SObject> objects, Map<String, Object> filter)	Filters a list of SObjects by multiple field-value matches.
global static List<SObject> findWhere(List<SObject> objects, String fieldName, Object value)	Filters a list of SObjects by a single field-value match.
global static List<SObject> findWhereIn(List<SObject> objects, String fieldName, List<Object> values)	Filters a list of SObjects where a field value is in the provided list.
global static List<SObject> getChangedRecords(List<SObject> newRecords, List<SObject> oldRecords, Set<SObjectField> fields)	Returns only the records where any of the specified fields have changed between the old and new versions.
global static List<SObject> getChangedRecords(List<SObject> newRecords, List<SObject> oldRecords, SObjectField field)	Returns only the records where a specific field value has changed between the old and new versions.
global static Object getFieldValue(SObject anObject, String fieldName)	Retrieves the value for a field on an SObject using dot-notation for related objects.
global static Map<Id, List<SObject>> groupByKey(List<SObject> objectList, SObjectField keyField)	Converts a list of SObjects into a grouped map by an Id field using a typed field token.
global static Map<Id, List<SObject>> groupByKey(List<SObject> objectList, String keyFieldName)	Converts a list of SObjects into a grouped map by an Id field.
global static Map<String, List<SObject>> groupByStringKey(List<SObject> objectList, SObjectField keyField)	Converts a list of SObjects into a grouped map by a String field using a typed field token.
global static Map<String, List<SObject>> groupByStringKey(List<SObject> objectList, String keyFieldName)	Converts a list of SObjects into a grouped map by a String field.
global static Boolean hasFieldChanged(SObject newRecord, SObject oldRecord, SObjectField field)	Checks whether a specific field value has changed between the old and new versions of a record.
global static Map<Id, SObject> indexById(List<SObject> objectList, SObjectField keyField)	Converts a list of SObjects into a single-value map by an Id field using a typed field token.
global static Map<Id, SObject> indexById(List<SObject> objectList, String keyFieldName)	Converts a list of SObjects into a single-value map by an Id field.
global static Map<String, SObject> indexByStringKey(List<SObject> objectList, SObjectField keyField)	Converts a list of SObjects into a single-value map by a String field using a typed field token.
global static Map<String, SObject> indexByStringKey(List<SObject> objectList, String keyFieldName)	Converts a list of SObjects into a single-value map by a String field.
global static Boolean matches(SObject obj, Map<String, Object> filterMap)	Checks if an SObject matches the field-value pairs in the provided filter map.
global static List<SObject> omitWhere(List<SObject> objects, Map<String, Object> filter)	Removes items from a list where the fields match the filter map.
global static List<SObject> omitWhere(List<SObject> objects, String fieldName, Object value)	Removes items from a list where the field matches a single value.
global static Id validateId(String stringId)	Will return an Id if the string is a valid Id else null

extractIds

global static Set<Id> extractIds(List<SObject> objects)

Extracts a unique set of Ids from a list of SObjects using the Id field.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract Ids

Returns Id — Extracted Ids, could include a null

Example

Set<Id> accountIds = UTIL_SObject.extractIds(accounts);

global static Set<Id> extractIds(List<SObject> objects, Boolean ignoreNulls)

Extracts a unique set of Ids from a list of SObjects using the Id field.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract Ids
ignoreNulls	SObject	Set to true to exclude null Ids

Returns Id — Extracted Ids

Example

Set<Id> accountIds = UTIL_SObject.extractIds(accounts, true);

global static Set<Id> extractIds(List<SObject> objects, SObjectField objectField)

Extracts a unique set of Ids from a list of SObjects using a typed field token.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract Ids
objectField	SObject	The field token containing the Id

Returns Id — Extracted Ids, could include a null

Example

Set<Id> accountIds = UTIL_SObject.extractIds(contacts, Contact.AccountId);

global static Set<Id> extractIds(List<SObject> objects, SObjectField objectField, Boolean ignoreNulls)

Extracts a unique set of Ids from a list of SObjects using a typed field token with null filtering.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract Ids
objectField	SObject	The field token containing the Id
ignoreNulls	SObjectField	Set to true to exclude null Ids

Returns Id — Extracted Ids

Example

Set<Id> accountIds = UTIL_SObject.extractIds(contacts, Contact.AccountId, true);

global static Set<Id> extractIds(List<SObject> objects, String fieldName)

Extracts a unique set of Ids from a list of SObjects using a named field.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract Ids
fieldName	SObject	The API name of the field containing the Id (supports dot-notation)

Returns Id — Extracted Ids, could include a null

Example

Set<Id> accountIds = UTIL_SObject.extractIds(contacts, 'AccountId');

global static Set<Id> extractIds(List<SObject> objects, String fieldName, Boolean ignoreNulls)

Extracts a unique set of Ids from a list of SObjects using a named field with null filtering.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract Ids
fieldName	SObject	The API name of the field containing the Id (supports dot-notation)
ignoreNulls	String	Set to true to exclude null Ids

Returns Id — Extracted Ids

Example

Set<Id> accountIds = UTIL_SObject.extractIds(contacts, 'AccountId', true);

extractUniqueValues

global static Set<String> extractUniqueValues(List<SObject> objects, SObjectField objectField)

Extracts a unique set of field values as strings from a list of SObjects using a typed field token.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract values
objectField	SObject	The field token to extract

Returns String — A set of string values (includes blanks)

Example

Set<String> industries = UTIL_SObject.extractUniqueValues(accounts, Account.Industry);

global static Set<String> extractUniqueValues(List<SObject> objects, SObjectField objectField, Boolean ignoreBlankValues)

Extracts a unique set of field values as strings from a list of SObjects using a typed field token with blank filtering.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract values
objectField	SObject	The field token to extract
ignoreBlankValues	SObjectField	Set to true to exclude blank values

Returns String — A set of string values

Example

Set<String> industries = UTIL_SObject.extractUniqueValues(accounts, Account.Industry, true);

global static Set<String> extractUniqueValues(List<SObject> objects, String fieldName)

Extracts a unique set of field values as strings from a list of SObjects.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract values
fieldName	SObject	The API name of the field (supports dot-notation)

Returns String — A set of string values (includes blanks)

Example

Set<String> industries = UTIL_SObject.extractUniqueValues(accounts, 'Industry');

global static Set<String> extractUniqueValues(List<SObject> objects, String fieldName, Boolean ignoreBlankValues)

Extracts a unique set of field values as strings from a list of SObjects with blank filtering.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract values
fieldName	SObject	The API name of the field (supports dot-notation)
ignoreBlankValues	String	Set to true to exclude blank values

Returns String — A set of string values

Example

Set<String> industries = UTIL_SObject.extractUniqueValues(accounts, 'Industry', true);

extractValues

global static List<String> extractValues(List<SObject> objects, SObjectField objectField)

Extracts field values as strings from a list of SObjects using a typed field token.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract values
objectField	SObject	The field token to extract

Returns String — A list of string values (includes blanks)

Example

List<String> names = UTIL_SObject.extractValues(accounts, Account.Name);

global static List<String> extractValues(List<SObject> objects, SObjectField objectField, Boolean ignoreBlankValues)

Extracts field values as strings from a list of SObjects using a typed field token with blank filtering.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract values
objectField	SObject	The field token to extract
ignoreBlankValues	SObjectField	Set to true to exclude blank values

Returns String — A list of string values

Example

List<String> names = UTIL_SObject.extractValues(accounts, Account.Name, true);

global static List<String> extractValues(List<SObject> objects, String fieldName)

Extracts field values as strings from a list of SObjects.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract values
fieldName	SObject	The API name of the field (supports dot-notation)

Returns String — A list of string values (includes blanks)

Example

List<String> names = UTIL_SObject.extractValues(accounts, 'Name');

global static List<String> extractValues(List<SObject> objects, String fieldName, Boolean ignoreBlankValues)

Extracts field values as strings from a list of SObjects with blank filtering.

Parameters

Parameter	Type	Description
objects	List	The SObjects from which to extract values
fieldName	SObject	The API name of the field (supports dot-notation)
ignoreBlankValues	String	Set to true to exclude blank values

Returns String — A list of string values

Example

List<String> names = UTIL_SObject.extractValues(accounts, 'Name', true);

findWhere

global static List<SObject> findWhere(List<SObject> objects, Map<String, Object> filter)

Filters a list of SObjects by multiple field-value matches.

Parameters

Parameter	Type	Description
objects	List	The SObjects to filter
filter	SObject	A map of field API names and their expected values

Returns SObject — Matching SObjects

Example

Map<String, Object> filter = new Map<String, Object>{ 'Industry' => 'Technology', 'Active__c' => true };
List<SObject> matches = UTIL_SObject.findWhere(accounts, filter);

global static List<SObject> findWhere(List<SObject> objects, String fieldName, Object value)

Filters a list of SObjects by a single field-value match.

Parameters

Parameter	Type	Description
objects	List	The SObjects to filter
fieldName	SObject	The field API name to match
value	String	The value to match against

Returns SObject — Matching SObjects

Example

List<SObject> techAccounts = UTIL_SObject.findWhere(accounts, 'Industry', 'Technology');

findWhereIn

global static List<SObject> findWhereIn(List<SObject> objects, String fieldName, List<Object> values)

Filters a list of SObjects where a field value is in the provided list.

Parameters

Parameter	Type	Description
objects	List	The SObjects to filter
fieldName	SObject	The field API name to match
values	String	The values to match against

Returns SObject — Matching SObjects

Example

List<Object> targetIndustries = new List<Object>{ 'Technology', 'Finance' };
List<SObject> filtered = UTIL_SObject.findWhereIn(accounts, 'Industry', targetIndustries);

getChangedRecords

global static List<SObject> getChangedRecords(List<SObject> newRecords, List<SObject> oldRecords, Set<SObjectField> fields)

Returns only the records where any of the specified fields have changed between the old and new versions. Compares each record in the new list against the corresponding record in the old list by index.

Parameters

Parameter	Type	Description
newRecords	List	The new versions of the records (from Trigger.new).
oldRecords	SObject	The old versions of the records (from Trigger.old).
fields	List	The set of fields to check for changes. A record is included if any field changed.

Returns SObject — A list containing only the new records where at least one of the specified fields changed.

Example

List<SObject> addressChanged = UTIL_SObject.getChangedRecords
(
    newRecords, oldRecords,
    new Set<SObjectField>{ Foobar__c.Text__c, Foobar__c.Email__c }
);

global static List<SObject> getChangedRecords(List<SObject> newRecords, List<SObject> oldRecords, SObjectField field)

Returns only the records where a specific field value has changed between the old and new versions. Compares each record in the new list against the corresponding record in the old list by index.

Parameters

Parameter	Type	Description
newRecords	List	The new versions of the records (from Trigger.new).
oldRecords	SObject	The old versions of the records (from Trigger.old).
field	List	The field to check for changes.

Returns SObject — A list containing only the new records where the specified field value changed.

Example

List<SObject> statusChanged = UTIL_SObject.getChangedRecords(newRecords, oldRecords, Foobar__c.Status__c);

getFieldValue

global static Object getFieldValue(SObject anObject, String fieldName)

Retrieves the value for a field on an SObject using dot-notation for related objects.

Parameters

Parameter	Type	Description
anObject	SObject	The SObject (can include related object data)
fieldName	String	A single field name or dot-notation path (e.g. 'Contact.Name')

Returns Object — The value of the field

Example

Object name = UTIL_SObject.getFieldValue(account, 'Name');
Object contactName = UTIL_SObject.getFieldValue(myCase, 'Contact.Name');

groupByKey

global static Map<Id, List<SObject>> groupByKey(List<SObject> objectList, SObjectField keyField)

Converts a list of SObjects into a grouped map by an Id field using a typed field token.

Parameters

Parameter	Type	Description
objectList	List	The SObjects to group
keyField	SObject	The field token for the key

Returns SObject — A map of Id to list of SObjects

Example

Map<Id, List<SObject>> contactsByAccount = UTIL_SObject.groupByKey(contacts, Contact.AccountId);

global static Map<Id, List<SObject>> groupByKey(List<SObject> objectList, String keyFieldName)

Converts a list of SObjects into a grouped map by an Id field.

Parameters

Parameter	Type	Description
objectList	List	The SObjects to group
keyFieldName	SObject	The API name of the Id field (supports dot-notation)

Returns SObject — A map of Id to list of SObjects

Example

Map<Id, List<SObject>> contactsByAccount = UTIL_SObject.groupByKey(contacts, 'AccountId');

groupByStringKey

global static Map<String, List<SObject>> groupByStringKey(List<SObject> objectList, SObjectField keyField)

Converts a list of SObjects into a grouped map by a String field using a typed field token.

Parameters

Parameter	Type	Description
objectList	List	The SObjects to group
keyField	SObject	The field token for the key

Returns SObject — A map of String to list of SObjects

Example

Map<String, List<SObject>> accountsByIndustry = UTIL_SObject.groupByStringKey(accounts, Account.Industry);

global static Map<String, List<SObject>> groupByStringKey(List<SObject> objectList, String keyFieldName)

Converts a list of SObjects into a grouped map by a String field.

Parameters

Parameter	Type	Description
objectList	List	The SObjects to group
keyFieldName	SObject	The API name of the String field (supports dot-notation)

Returns SObject — A map of String to list of SObjects

Example

Map<String, List<SObject>> accountsByIndustry = UTIL_SObject.groupByStringKey(accounts, 'Industry');

hasFieldChanged

global static Boolean hasFieldChanged(SObject newRecord, SObject oldRecord, SObjectField field)

Checks whether a specific field value has changed between the old and new versions of a record.

Parameters

Parameter	Type	Description
newRecord	SObject	The new version of the record (from Trigger.new).
oldRecord	SObject	The old version of the record (from Trigger.oldMap).
field	SObjectField	The field to check for changes.

Returns Boolean — True if the field value differs between the old and new records.

Example

if(UTIL_SObject.hasFieldChanged(newRecord, oldRecord, Foobar__c.Status__c))
{
    // Handle status change
}

indexById

global static Map<Id, SObject> indexById(List<SObject> objectList, SObjectField keyField)

Converts a list of SObjects into a single-value map by an Id field using a typed field token.

Parameters

Parameter	Type	Description
objectList	List	The SObjects to map
keyField	SObject	The field token for the key

Returns SObject — A map of Id to SObject

Example

Map<Id, SObject> accountById = UTIL_SObject.indexById(accounts, Account.Id);

global static Map<Id, SObject> indexById(List<SObject> objectList, String keyFieldName)

Converts a list of SObjects into a single-value map by an Id field.

Parameters

Parameter	Type	Description
objectList	List	The SObjects to map
keyFieldName	SObject	The API name of the Id field (supports dot-notation)

Returns SObject — A map of Id to SObject

Example

Map<Id, SObject> accountById = UTIL_SObject.indexById(accounts, 'Id');

indexByStringKey

global static Map<String, SObject> indexByStringKey(List<SObject> objectList, SObjectField keyField)

Converts a list of SObjects into a single-value map by a String field using a typed field token.

Parameters

Parameter	Type	Description
objectList	List	The SObjects to map
keyField	SObject	The field token for the key

Returns SObject — A map of String to SObject

Example

Map<String, SObject> accountByName = UTIL_SObject.indexByStringKey(accounts, Account.Name);

global static Map<String, SObject> indexByStringKey(List<SObject> objectList, String keyFieldName)

Converts a list of SObjects into a single-value map by a String field.

Parameters

Parameter	Type	Description
objectList	List	The SObjects to map
keyFieldName	SObject	The API name of the String field (supports dot-notation)

Returns SObject — A map of String to SObject

Example

Map<String, SObject> accountByName = UTIL_SObject.indexByStringKey(accounts, 'Name');

matches

global static Boolean matches(SObject obj, Map<String, Object> filterMap)

Checks if an SObject matches the field-value pairs in the provided filter map.

Parameters

Parameter	Type	Description
obj	SObject	The SObject to check.
filterMap	Map	A map containing field API names and their expected values.

Returns Boolean — True if all fields in the filter map match the corresponding SObject fields.

Example

SObject account = new Account(Name = 'Test Account', Industry = 'Technology');
Map<String, Object> filterMap = new Map<String, Object>{'Name' => 'Test Account', 'Industry' => 'Technology'};
Boolean doesMatch = UTIL_SObject.matches(account, filterMap); // True

omitWhere

global static List<SObject> omitWhere(List<SObject> objects, Map<String, Object> filter)

Removes items from a list where the fields match the filter map.

Parameters

Parameter	Type	Description
objects	List	The SObjects to filter
filter	SObject	A map of fields and values that cause exclusion

Returns SObject — SObjects not matching the exclusion criteria

Example

Map<String, Object> filter = new Map<String, Object>{ 'Status' => 'Closed', 'IsDeleted' => true };
List<SObject> activeRecords = UTIL_SObject.omitWhere(allRecords, filter);

global static List<SObject> omitWhere(List<SObject> objects, String fieldName, Object value)

Removes items from a list where the field matches a single value.

Parameters

Parameter	Type	Description
objects	List	The SObjects to filter
fieldName	SObject	The field API name to match for exclusion
value	String	The value that causes exclusion

Returns SObject — SObjects not matching the exclusion criteria

Example

List<SObject> nonTech = UTIL_SObject.omitWhere(accounts, 'Industry', 'Technology');

validateId

global static Id validateId(String stringId)

Will return an Id if the string is a valid Id else null

Parameters

Parameter	Type	Description
stringId	String	A string containing the ID

Returns Id — Either a valid ID or null

Example

Id result = UTIL_SObject.validateId('001000000000001');