SObject Class

addError(errorMsg)

Marks a trigger record with a custom error message and prevents any DML operation from occurring.

Signature

public Void addError(String errorMsg)

Parameters

errorMsg: Type: String; The error message to mark the record with.

Return Value

Type: Void

Usage

When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before delete triggers, the error message is displayed in the application interface.

See Triggers and Trigger Exceptions.

This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

Note

When used in Visualforce controllers, the generated message is added to the collection of errors for the page. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer's Guide.

Example

addError(errorMsg, escape)

Marks a trigger record with a custom error message, specifies if the error message should be escaped, and prevents any DML operation from occurring.

Signature

public Void addError(String errorMsg, Boolean escape)

Parameters

errorMsg: Type: String; The error message to mark the record with.
escape: Type: Boolean; Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Return Value

Type: Void

Usage

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(String errorMsg) instead.

Warning

Example

addError(exceptionError)

Marks a trigger record with a custom error message and prevents any DML operation from occurring.

Signature

public Void addError(Exception exceptionError)

Parameters

exceptionError: Type: System.Exception; An Exception object or a custom exception object that contains the error message to mark the record with.

Return Value

Type: Void

Usage

When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before delete triggers, the error message is displayed in the application interface.

See Triggers and Trigger Exceptions.

This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

Note

When used in Visualforce controllers, the generated message is added to the collection of errors for the page. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer's Guide.

Example

addError(exceptionError, escape)

Marks a trigger record with a custom exception error message, specifies whether or not the exception error message should be escaped, and prevents any DML operation from occurring.

Signature

public Void addError(Exception exceptionError, Boolean escape)

Parameters

exceptionError: Type: System.Exception; An Exception object or a custom exception object that contains the error message to mark the record with.
escape: Type: Boolean; Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Return Value

Type: Void

Usage

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(Exception e) instead.

Warning

Example

addError(errorMsg)

Places the specified error message on a trigger record field in the Salesforce user interface and prevents any DML operation from occurring.

Signature

public Void addError(String errorMsg)

Parameters

errorMsg: Type: String

Return Value

Type: Void

Usage

Note:

When used on Trigger.new in before insert and before update triggers, and on Trigger.old in before delete triggers, the error appears in the application interface.
When used in Visualforce controllers, if there is an inputField component bound to field, the message is attached to the component. For more information, see Validation Rules and Standard Controllers in the Visualforce Developer's Guide.
This method is highly specialized because the field identifier is not actually the invoking object—the sObject record is the invoker. The field is simply used to identify the field that should be used to display the error.

See Triggers and Trigger Exceptions.

This method escapes any HTML markup in the specified error message. The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

Note

Example

addError(errorMsg, escape)

Places the specified error message, which can be escaped or unescaped, on a trigger record field in the Salesforce user interface, and prevents any DML operation from occurring.

Signature

public Void addError(String errorMsg, Boolean escape)

Parameters

errorMsg: Type: String; The error message to mark the record with.
escape: Type: Boolean; Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Return Value

Type:

Usage

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call field.addError(String errorMsg) instead.

Warning

Example

addError(fieldName, errorMsg)

Dynamically add errors to fields of an SObject associated with the specified field name.

Signature

public void addError(String fieldName, String errorMsg)

Parameters

fieldName: Type: String; The field name of the SObject .
errorMsg: Type: String; The error message to be added. HTML special characters in the error message string are always escaped.

Return Value

Type: void

Usage

If the field name is an empty string or null, the error is associated with the SObject and not with a specific field.

Example

addError(fieldToken, errorMsg)

Dynamically add errors to an SObject instance associated with the specified field.

Signature

public void addError(Schema.SObjectField fieldToken, String errorMsg

Parameters

fieldToken: Type: Schema.SObjectField; The field of the SObject instance.
errorMsg: Type: String; The error message to be added. HTML special characters in the error message string are always escaped.

Return Value

Type: void

Usage

Use this method to add errors to the specified field token of a standard or custom object. If fieldTokenis null, the error is associated with the SObject and not with a specific field.

Example

addError(fieldName, errorMsg, escape)

Dynamically add errors to fields of an SObject associated with the specified field name.

Signature

public void addError(String fieldName, String errorMsg, Boolean escape)

Parameters

fieldName: Type: String; The field name of the SObject .
errorMsg: Type: String; The error message to be added.
escape: Type: Boolean; Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Return Value

Type: void

Usage

If the field name is an empty string or null, the error is associated with the SObject and not with a specific field.

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

The escape parameter cannot be disabled in Lightning Experience and in the Salesforce mobile app, and will be ignored.
Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(String fieldName, String errorMsg) instead.

Warning

Example

addError(fieldToken, errorMsg, escape)

Dynamically add errors to an SObject instance associated with the specified field.

Signature

public void addError(Schema.SObjectField fieldToken, String errorMsg, Boolean escape)

Parameters

fieldToken: Type: Schema.SObjectField; The field of the SObject instance.
errorMsg: Type: String; The error message to be added.
escape: Type: Boolean; Indicates whether any HTML markup in the custom error message should be escaped (true) or not (false). This parameter is ignored in both Lightning Experience and the Salesforce mobile app, and the HTML is always escaped. The escape parameter only applies in Salesforce Classic.

Return Value

Type: void

Usage

Use this method to add errors to the specified field token of a standard or custom object. If fieldTokenis null, the error is associated with the SObject and not with a specific field.

The escaped characters are: \n, <, >, &, ", \, \u2028, \u2029, and \u00a9. As a result, HTML markup is not rendered; instead, it is displayed as text in the Salesforce user interface.

The escape parameter cannot be disabled in Lightning Experience and in the Salesforce mobile app, and will be ignored.
Be cautious if you specify false for the escape argument. Unescaped strings displayed in the Salesforce user interface can represent a vulnerability in the system because these strings might contain harmful code. If you want to include HTML markup in the error message, call this method with a false escape argument. Make sure that you escape any dynamic content, such as input field values. Otherwise, specify true for the escape argument or call addError(Schema.SObjectField fieldToken, String errorMsg) instead.

Warning

Example

clear()

Clears all field values

Signature

public Void clear()

Return Value

Type: Void

Example

clone(preserveId, isDeepClone, preserveReadonlyTimestamps, preserveAutonumber)

Creates a copy of the SObject record.

Signature

public SObject clone(Boolean preserveId, Boolean isDeepClone, Boolean preserveReadonlyTimestamps, Boolean preserveAutonumber)

Parameters

preserveId

Type: Boolean

(Optional) Determines whether the ID of the original object is preserved or cleared in the duplicate. If set to true, the ID is copied to the duplicate. The default is false, that is, the ID is cleared.

isDeepClone

Type: Boolean

(Optional) Determines whether the method creates a full copy of the SObject field or just a reference:

If set to true, the method creates a full copy of the SObject. All fields on the SObject are duplicated in memory, including relationship fields. Consequently, if you make changes to a field on the cloned SObject, the original SObject is not affected.
If set to false, the method performs a shallow copy of the SObject fields. All copied relationship fields reference the original SObjects. Consequently, if you make changes to a relationship field on the cloned SObject, the corresponding field on the original SObject is also affected, and vice versa. The default is false.

preserveReadonlyTimestamps

Type: Boolean

(Optional) Determines whether the read-only timestamp fields are preserved or cleared in the duplicate. If set to true, the read-only fields CreatedById, CreatedDate, LastModifiedById, and LastModifiedDate are copied to the duplicate. The default is false, that is, the values are cleared.

preserveAutonumber

Type: Boolean

(Optional) Determines whether auto number fields of the original object are preserved or cleared in the duplicate. If set to true, auto number fields are copied to the cloned object. The default is false, that is, auto number fields are cleared.

Return Value

Type: SObject (of same type)

Usage

For Apex saved using Salesforce API version 22.0 or earlier, the default value for the preserveId argument is true, that is, the ID is preserved.

Note

Example

get(fieldName)

Returns the value for the field specified by fieldName, such as AccountNumber.

Signature

public Object get(String fieldName)

Parameters

fieldName: Type: String

Return Value

Type: Object

Usage

For more information, see Dynamic SOQL.

Example

get(field)

Returns the value for the field specified by the field token Schema.sObjectField, such as, Schema.Account.AccountNumber.

Signature

public Object get(Schema.sObjectField field)

Parameters

field: Type: Schema.SObjectField

Return Value

Type: Object

Usage

For more information, see Dynamic SOQL.

Field tokens aren't available for person accounts. If you access Schema.Account.fieldname, you get an exception error. Instead, specify the field name as a string.

Note

Example

getCloneSourceId()

Returns the ID of the entity from which an object was cloned. You can use it for objects cloned through the Salesforce user interface. If you don’t use a preserveId parameter, of if you use a preserveId value of false, you can also used it for objects created using the System.SObject.clone(preserveId, isDeepClone, preserveReadonlyTimestamps, preserveAutonumber) method.

Signature

public Id getCloneSourceId()

Return Value

Type: Id

Usage

If A is cloned to B, B is cloned to C, and C is cloned to D, then B, C, and D all point back to A as their clone source.

Example

getErrors()

Returns a list of Database.Error objects for an SObject instance. If the SObject has no errors, an empty list is returned.

Signature

public List<Database.Error> getErrors()

Return Value

Type: List<Database.Error>

getOptions()

Returns the database.DMLOptions object for the SObject.

Signature

public Database.DMLOptions getOptions()

Return Value

Type: Database.DMLOptions

Example

getPopulatedFieldsAsMap()

Returns a map of populated field names and their corresponding values. The map contains only the fields that have been populated in memory for the SObject instance.

Signature

public Map<String,Object> getPopulatedFieldsAsMap()

Return Value

Type: Map<String,Object>

A map of field names and their corresponding values.

Usage

The returned map contains only the fields that have been populated in memory for the SObject instance, which makes it easy to iterate over those fields. A field is populated in memory in the following cases.

The field has been queried by a SOQL statement.
The field has been explicitly set before the call to the getPopulatedFieldsAsMap() method.

Fields on related objects that are queried or set are also returned in the map.

The following example iterates over the map returned by the getPopulatedFieldsAsMap() method after a SOQL query.

This example iterates over the map returned by the getPopulatedFieldsAsMap() method after fields on the SObject are explicitly set.

The following example shows how to use the getPopulatedFieldsAsMap() method with related objects.

Versioned Behavior Changes

In API version 39.0 and later, getPopulatedFieldsAsMap returns all values set on the SObject, even if values were set after the record was queried. This behavior is dependent on the version of the apex class calling this method and not on the version of the class that generated the SObject. If you query an SObject at API version 20.0, and then call this method in a class with API version 40.0, you will get the full set of fields.

getSObject(fieldName)

Returns the value for the specified field. This method is primarily used with dynamic DML to access values for external IDs.

Signature

public SObject getSObject(String fieldName)

Parameters

fieldName: Type: String

Return Value

Type: SObject

Example

getSObject(field)

Returns the value for the field specified by the field token Schema.sObjectField, such as, Schema.MyObj.MyExternalId. This method is primarily used with dynamic DML to access values for external IDs.

Signature

public SObject getSObject(Schema.SObjectField field)

Parameters

field: Type: Schema.SObjectField

Return Value

Type: SObject

Usage

If the method references polymorphic fields, a Name object is returned. Use the TYPEOF clause in the SOQL SELECT statement to directly get results that depend on the runtime object type referenced by the polymorphic field. See Working with Polymorphic Relationships in SOQL Queries.

Example

getSObjects(fieldName)

Returns the values for the specified field. This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.

Signature

public SObject[] getSObjects(String fieldName)

Parameters

fieldName: Type: String

Return Value

Type: SObject[]

Usage

For more information, see Dynamic DML.

Example

getSObjects(fieldName)

Returns the value for the field specified by the field token Schema.fieldName, such as, Schema.Account.Contact. This method is primarily used with dynamic DML to access values for associated objects, such as child relationships.

Signature

public SObject[] getSObjects(Schema.SObjectType fieldName)

Parameters

fieldName: Type: Schema.SObjectType

Return Value

Type: SObject[]

getSObjectType()

Returns the token for this SObject. This method is primarily used with describe information.

Signature

public Schema.SObjectType getSObjectType()

Return Value

Type: Schema.SObjectType

Usage

For more information, see apex_dynamic_describe_objects_understanding.

Example

getQuickActionName()

Retrieves the name of a quick action associated with this SObject. Typically used in triggers.

Signature

public String getQuickActionName()

Return Value

Type: String

Example

hasErrors()

Returns true if an SObject instance has associated errors. The error message can be associated to the SObject instance by using SObject.addError(), validation rules, or by other means.

Signature

public Boolean hasErrors()

Return Value

Type: Boolean

isClone()

Returns true if an entity is cloned from something, even if the entity hasn’t been saved.

Signature

public Boolean isClone()

Return Value

Type: Boolean

Example

isSet(fieldName)

Returns information about the queried sObject field. Returns true if the sObject field is populated, either by direct assignment or by inclusion in a SOQL query. Returns false if the sObject field is not set. If an invalid field is specified, an SObjectException is thrown.

Signature

public Void isSet(String fieldName)

Parameters

fieldName: Type: String

Return Value

Type: Boolean

Usage

The isSet method doesn’t check if a field is accessible to a specific user via org permissions or other specialized access permissions.

Example

isSet(field)

Returns information about the queried sObject field. Returns true if the sObject field is populated, either by direct assignment or by inclusion in a SOQL query. Returns false if the sObject field is not set. If an invalid field is specified, an SObjectException is thrown.

Signature

public Void isSet(Schema.SObjectField field)

Parameters

field: Type:SObjectField Class

Return Value

Type: Boolean

Usage

The isSet method doesn’t check if a field is accessible to a specific user via org permissions or other specialized access permissions.

Example

put(fieldName, value)

Sets the value for the specified field and returns the previous value for the field.

Signature

public Object put(String fieldName, Object value)

Parameters

fieldName: Type: String
value: Type: Object

Return Value

Type: Object

Example

put(field, value)

Sets the value for the field specified by the field token Schema.sObjectField, such as, Schema.Account.AccountNumber and returns the previous value for the field.

Signature

public Object put(Schema.SObjectField field, Object value)

Parameters

field: Type: Schema.SObjectField
value: Type: Object

Return Value

Type: Object

Example

Field tokens aren't available for person accounts. If you access Schema.Account.fieldname, you get an exception error. Instead, specify the field name as a string.

Note

putSObject(fieldName, value)

Sets the value for the specified field. This method is primarily used with dynamic DML for setting external IDs. The method returns the previous value of the field.

Signature

public SObject putSObject(String fieldName, SObject value)

Parameters

fieldName: Type: String
value: Type: SObject

Return Value

Type: SObject

Example

putSObject(fieldName, value)

Sets the value for the field specified by the token Schema.SObjectType. This method is primarily used with dynamic DML for setting external IDs. The method returns the previous value of the field.

Signature

public SObject putSObject(Schema.SObjectType fieldName, SObject value)

Parameters

fieldName: Type: Schema.SObjectType
value: Type: SObject

Return Value

Type: SObject

recalculateFormulas()

Recalculates all formula fields on an SObject, and sets updated field values. Rather than inserting or updating objects each time you want to test changes to your formula logic, call this method and inspect your new field values. Then make further logic changes as needed.

Signature

public Void recalculateFormulas()

Return Value

Type: Void

Usage

This method doesn’t recalculate cross-object formulas. If you call this method on objects that have both cross-object and non-cross-object formula fields, only the non-cross-object formula fields are recalculated.

Each recalculateFormulas call counts against the SOQL query limits. See Execution Governors and Limits.

setOptions(DMLOptions)

Sets the DMLOptions object for the SObject.

Signature

public Void setOptions(database.DMLOptions DMLOptions)

Parameters

DMLOptions: Type: Database.DMLOptions

Return Value

Type: Void

Apex Reference Guide

Namespace

Usage

SObject Methods

addError(errorMsg)

Signature

Parameters

Return Value

Usage

Example

addError(errorMsg, escape)

Signature

Parameters

Return Value

Usage

Example

addError(exceptionError)

Signature

Parameters

Return Value

Usage

Example

addError(exceptionError, escape)

Signature

Parameters

Return Value

Usage

Example

addError(errorMsg)

Signature

Parameters

Return Value

Usage

Example

addError(errorMsg, escape)

Signature

Parameters

Return Value

Usage

Example

addError(fieldName, errorMsg)

Signature

Parameters

Return Value

Usage

Example

addError(fieldToken, errorMsg)

Signature

Parameters

Return Value

Usage

Example

addError(fieldName, errorMsg, escape)

Signature

Parameters

Return Value

Usage

Example

addError(fieldToken, errorMsg, escape)

Signature

Parameters

Return Value

Usage

Example

clear()

Signature

Return Value

Example

clone(preserveId, isDeepClone, preserveReadonlyTimestamps, preserveAutonumber)

Signature

Parameters

Return Value

Usage

Example

get(fieldName)

Signature

Parameters

Return Value

Usage