Version: 10

Entity class

Level: advanced

Terrasoft.Core.Entities namespace.

The Terrasoft.Core.Entities.Entity class provides access to a record in the database table.

note

View the entire list of properties of the Entity class, its parent classes, as well as the interfaces it implements, in the .NET classes reference.

Constructors

Entity(UserConnection userConnection)

Creates a new Entity class instance for the set UserConnection user connection.

Entity(UserConnection userConnection, Guid schemaUId)

Creates a new Entity class instance for the set UserConnection user connection and the schema set by the schemaUId identifier.

Entity(Entity source)

Creates a class instance that is a clone of the instance passed as an argument.

Properties

EntityLoadState LoadState { get; }

The record load state.

Available values

Value	Description
NotLoaded	No column values are loaded from the database. The default state. The record also switches to this state after its schema changes.
PartialLoaded	Some column values are loaded from the database, for example, after you call the `FetchFromDB()` method for a subset of columns.
Loaded	All column values are loaded from the database.

EntitySchemaManager EntitySchemaManager { get; }

An instance of the object schema manager.

Guid HierarchyColumnValue { get; set; }

The value of the column that binds the parent record, for hierarchical objects.

Guid PrimaryColumnValue { get; set; }

The ID of the primary column.

string PrimaryDisplayColumnValue { get; set; }

The value of the primary display column.

EntitySchema Schema { get; set; }

An instance of the "Object" type schema.

string SchemaName { get; set; }

The name of the "Object" type schema.

StoringObjectState StoringState { get; set; }

The record status. Creatio changes the status automatically. We do not recommend setting it in custom code because this changes the behavior of the Save() method.

Available values

Value	Description
NotChanged (0)	The record is loaded or saved and has no unsaved changes.
New (1)	The record is not saved to the database yet. The default state.
Changed (2)	The record is loaded and has unsaved changes.
Deleted (3)	The record is deleted from the database.

bool UseAdminRights { get; set; }

Whether to check access permissions when inserting, updating, deleting, and selecting data. If true, Creatio checks access permissions. If false, Creatio skips the check. By default, true.

UserConnection UserConnection { get; set; }

The user connection.

EntityValidationMessageCollection ValidationMessages { get; }

The message collection displayed when validating a record.

Methods

virtual bool Delete()

virtual bool Delete(object keyValue)

Deletes the record from the database. Returns true if the record is deleted. Returns false if the Deleting event handler cancels the operation, no record matches, or the record is not saved yet.

Parameters

Parameter	Type	Description
keyValue	`object`	The key field value.

bool ExistInDB(EntitySchemaColumn conditionColumn, object conditionValue)

bool ExistInDB(string conditionColumnName, object conditionValue)

bool ExistInDB(object keyValue)

virtual bool ExistInDB(Dictionary<string,object> conditions)

Whether the database contains a record that matches the specified condition, primary key value, or set of conditions. Returns true if the record exists, otherwise false. If UseAdminRights is true and the user does not have permission to read the object, the method returns true.

Parameters

Parameter	Type	Description
conditionColumn	`EntitySchemaColumn`	The column for which to specify the selection condition.
conditionColumnName	`string`	The name of the column for which to specify the selection condition.
conditionValue	`object`	The value of the condition column for the selected data.
conditions	`Dictionary<string,object>`	A set of conditions to filter the record selection.
keyValue	`object`	The key field value.

virtual bool FetchFromDB(EntitySchemaColumn conditionColumn,
    object conditionValue, bool useDisplayValues = true)

bool FetchFromDB(string conditionColumnName, object conditionValue,
    bool useDisplayValues = true)

bool FetchFromDB(object keyValue, bool useDisplayValues = true)

virtual bool FetchFromDB(Dictionary<string,object> conditions,
    bool useDisplayValues = true)

bool FetchFromDB(EntitySchemaColumn conditionColumn, object conditionValue,
    IEnumerable<EntitySchemaColumn> columnsToFetch,
    bool useDisplayValues = true)

virtual bool FetchFromDB(string conditionColumnName, object conditionValue,
    IEnumerable<string> columnNamesToFetch, bool useDisplayValues = true)

bool FetchFromDB(IEnumerable<string> columnNamesToFetch, bool useDisplayValues)

Loads the record from the database by the specified condition. The overload that takes only columnNamesToFetch loads the record whose primary key equals the current PrimaryColumnValue property value. If PrimaryColumnValue is empty, the method throws NullOrEmptyException.

Returns true if the record is loaded, otherwise false. If UseAdminRights is true and the user does not have permission to read the object, the method clears all column values and returns true.

Parameters

Parameter	Type	Description
conditionColumn	`EntitySchemaColumn`	The column for which to specify the selection condition.
conditionColumnName	`string`	The name of the column for which to specify the selection condition.
conditionValue	`object`	The value of the condition column for the selected data.
columnsToFetch	`IEnumerable<EntitySchemaColumn>`	The list of columns to select.
columnNamesToFetch	`IEnumerable<string>`	The list of column names to select.
conditions	`Dictionary<string,object>`	A set of conditions to filter the record selection.
keyValue	`object`	The key field value.
useDisplayValues	`bool`	Whether the query returns display values. By default, `true`.

bool FetchPrimaryColumnFromDB(object keyValue)

Loads the primary column of the record from the database by the specified keyValue primary key value. Returns true if the record is loaded, otherwise false.

Parameters

Parameter	Type	Description
keyValue	`object`	The key field value.

bool FetchPrimaryInfoFromDB(EntitySchemaColumn conditionColumn,
    object conditionValue)

bool FetchPrimaryInfoFromDB(string conditionColumnName, object conditionValue)

Loads the primary column and the primary display column of the record from the database by the specified condition. Returns true if the record is loaded, otherwise false.

Parameters

Parameter	Type	Description
conditionColumn	`EntitySchemaColumn`	The column for which to specify the selection condition.
conditionColumnName	`string`	The name of the column for which to specify the selection condition.
conditionValue	`object`	The value of the condition column for the selected data.

virtual byte[] GetBytesValue(string valueName)

Returns the value of the specified object column as a byte array.

Parameters

Parameter	Type	Description
valueName	`string`	The name of the object column.

IEnumerable<EntityColumnValue> GetChangedColumnValues()

Returns the values of the object columns that were modified after the last load or save. Inside the Saved event handler, the collection is empty. Use the ModifiedColumnValues property of the event arguments instead.

string GetColumnDisplayValue(EntitySchemaColumn column)

Returns the display value of the object column that matches the specified column of the "Object" type schema.

Parameters

Parameter	Type	Description
column	`EntitySchemaColumn`	A specific column of the "Object" type schema.

object GetColumnOldValue(string valueName)

object GetColumnOldValue(EntitySchemaColumn column)

Returns the previous value of the specified "Object" type schema column.

Parameters

Parameter	Type	Description
column	`EntitySchemaColumn`	A specific column of the "Object" type schema.
valueName	`string`	The column name of the "Object" type schema.

virtual object GetColumnValue(string valueName)

virtual object GetColumnValue(EntitySchemaColumn column)

Returns the value of the object column that matches the specified column or column name of the "Object" type schema.

Parameters

Parameter	Type	Description
column	`EntitySchemaColumn`	A specific column of the "Object" type schema.
valueName	`string`	The column name of the "Object" type schema.

IEnumerable<string> GetColumnValueNames()

Returns the collection of object column names.

virtual MemoryStream GetStreamValue(string valueName)

Returns the value of the passed object schema column converted into the System.IO.MemoryStream type instance.

Parameters

Parameter	Type	Description
valueName	`string`	The column name of the "Object" type schema.

virtual TResult GetTypedColumnValue<TResult>(string valueName)

TResult GetTypedColumnValue<TResult>(EntitySchemaColumn column)

Returns the typed value of the object column that matches the specified column or column name of the "Object" type schema.

Parameters

Parameter	Type	Description
column	`EntitySchemaColumn`	A specific column of the "Object" type schema.
valueName	`string`	The column name of the "Object" type schema.

TResult GetTypedOldColumnValue<TResult>(string valueName)

TResult GetTypedOldColumnValue<TResult>(EntitySchemaColumn column)

Returns the typed previous value of the object column that matches the specified column of the "Object" type schema.

Parameters

Parameter	Type	Description
column	`EntitySchemaColumn`	A specific column of the "Object" type schema.
valueName	`string`	The column name of the "Object" type schema.

virtual bool InsertToDB(bool skipLookupColumnValues = false,
    bool validateRequired = true)

Adds the record to the database. Returns true if the record is added, otherwise false. Unlike the Save() method, the method does not set default column values and does not fire the Saving and Saved events. We recommend using the Save() method instead.

Parameters

Parameter	Type	Description
skipLookupColumnValues	`bool`	Whether to skip the columns of the lookup type when adding the record to the database. If set to `true`, Creatio does not add the columns of the lookup type to the database. By default, `false`.
validateRequired	`bool`	Whether to validate the required values. By default, `true`.

bool IsColumnValueLoaded(string valueName)

bool IsColumnValueLoaded(EntitySchemaColumn column)

Whether the value of the object column with the specified name is loaded.

Parameters

Parameter	Type	Description
column	`EntitySchemaColumn`	A specific column of the "Object" type schema.
valueName	`string`	The column name of the "Object" type schema.

bool Save(bool validateRequired = true, bool setColumnDefValue = true)

virtual bool Save(EntitySaveConfig saveConfig)

Saves the record to the database. Returns true if the record is saved or has no changes to save. Returns false if the Saving, Inserting, or Updating event handler cancels the operation.

If the SaveError event handler sets IsHandled to true, the method returns true and the Saved event fires, even though Creatio does not save the record.

Parameters

Parameter	Type	Description
saveConfig	`EntitySaveConfig`	The save settings. Available properties: `ValidateRequired` (`bool`). Whether to validate the required values. By default, `true`. `SetColumnDefValue` (`bool`). Whether to set default values for columns before inserting the record. By default, `true`.
setColumnDefValue	`bool`	Whether to set default values from the schema for columns that have them before inserting the record. Does not apply when updating the record. By default, `true`.
validateRequired	`bool`	Whether to validate the required values. By default, `true`.

Parameter

Type

Description

saveConfig

EntitySaveConfig

The save settings. Available properties:

ValidateRequired (bool). Whether to validate the required values. By default, true.
SetColumnDefValue (bool). Whether to set default values for columns before inserting the record. By default, true.

setColumnDefValue

bool

Whether to set default values from the schema for columns that have them before inserting the record. Does not apply when updating the record. By default, true.

validateRequired

bool

Whether to validate the required values. By default, true.

virtual void SetBytesValue(string valueName, byte[] streamBytes)

Sets the specified column to the passed byte array.

Parameters

Parameter	Type	Description
streamBytes	`byte[]`	A value of the `System.Byte` type set for the specified object column.
valueName	`string`	The name of the object column.

virtual bool SetColumnValue(string valueName, object value)

virtual bool SetColumnValue(EntitySchemaColumn column, object value)

Sets the specified schema column to the passed value. Returns true if the value is changed. Returns false if the new value equals the current value or the ColumnValueChanging event handler cancels the change.

Since version 10.1, if you pass a non-empty byte[] value to the "Data" column of a file object, Creatio saves it as file content on the Save() method call. The null value and an empty byte[] value do not set file content. To keep the current file content, do not set the "Data" column value. Learn more: Manage files using Entity class.

Parameters

Parameter	Type	Description
column	`EntitySchemaColumn`	The object schema column.
value	`object`	The loaded value of the column.
valueName	`string`	The name of the object column.

void SetDefColumnValue(string columnValueName, object defValue)

void SetDefColumnValue(string columnValueName)

Sets the column with the specified name to the default value.

Parameters

Parameter	Type	Description
columnValueName	`string`	The name of the object column.
defValue	`object`	The default value.

void SetDefColumnValues()

Sets default values for all object columns.

virtual bool SetStreamValue(string valueName, Stream value)

Sets the specified object column to the passed value of the System.IO.Stream type. Returns true if the value is changed. Returns false if the new value equals the current value or the ColumnValueChanging event handler cancels the change.

Parameters

Parameter	Type	Description
value	`Stream`	The loaded value of the column.
valueName	`string`	The name of the object column.

virtual bool UpdateInDB(bool validateRequired = true)

Updates the record in the database. Returns false only if the Updating event handler cancels the operation. Returns true even if no record is updated. We recommend using the Save() method instead.

Parameters

Parameter	Type	Description
validateRequired	`bool`	Whether to validate the required values. By default, `true`.

bool Validate()

Verifies whether the required fields are populated. Returns true if the ValidationMessages collection contains no errors, otherwise false.

Events

event EventHandler<EntityColumnAfterEventArgs> ColumnValueChanged

Event handler used after modifying the object column value.

The event handler receives an argument of the EntityColumnAfterEventArgs type. The argument provides the following properties:

Property	Type	Description
ColumnValueName	`string`	The name of the changed column.

event EventHandler<EntityColumnBeforeEventArgs> ColumnValueChanging

Event handler used before modifying the object column value.

The event handler receives an argument of the EntityColumnBeforeEventArgs type. The argument provides the following properties:

Property	Type	Description
ColumnValue	`object`	The new column value. The handler can replace the value.
ColumnStreamValue	`Stream`	The new stream value. Read-only. Populated only when you call the `SetStreamValue()` method.
ColumnValueName	`string`	The name of the column to change.
IsCanceled	`bool`	Set to `true` to cancel the change. By default, `false`.

event EventHandler<EventArgs> DefColumnValuesSet

Event handler used after setting default object column values.

event EventHandler<EntityAfterEventArgs> Deleted

Event handler used after deleting a record.

The event handler receives an argument of the EntityAfterEventArgs type.

event EventHandler<EntityBeforeEventArgs> Deleting

Event handler used before deleting a record.

The event handler receives an argument of the EntityBeforeEventArgs type. The argument provides the following properties:

Property	Type	Description
IsCanceled	`bool`	Set to `true` to cancel the operation. By default, `false`.
KeyValue	`object`	The primary key value of the record to delete.

event EventHandler<EntityAfterEventArgs> Inserted

Event handler used after inserting a record.

The event handler receives an argument of the EntityAfterEventArgs type.

event EventHandler<EntityBeforeEventArgs> Inserting

Event handler used before inserting a record.

The event handler receives an argument of the EntityBeforeEventArgs type. The argument provides the following properties:

Property	Type	Description
IsCanceled	`bool`	Set to `true` to cancel the operation. By default, `false`.

event EventHandler<EntityAfterEventArgs> Saved

Event handler used after saving a record.

The event handler receives an argument of the EntityAfterEventArgs type. The argument provides the following properties:

Property	Type	Description
ModifiedColumnValues	`EntityColumnValueCollection`	The column values changed by the operation.
PrimaryColumnValue	`Guid`	The primary key value of the record.

event EventHandler<EntitySaveErrorEventArgs> SaveError

Event handler used if an error occurs while saving a record.

The event handler receives an argument of the EntitySaveErrorEventArgs type. The argument provides the following properties:

Property	Type	Description
Exception	`Exception`	The exception that occurred when saving the record.
IsHandled	`bool`	Set to `true` to suppress the exception. In this case, the `Save()` method returns `true`. By default, `false`.

event EventHandler<EntityBeforeEventArgs> Saving

Event handler used before saving a record.

The event handler receives an argument of the EntityBeforeEventArgs type. The argument provides the following properties:

Property	Type	Description
IsCanceled	`bool`	Set to `true` to cancel the operation. By default, `false`.

event EventHandler<EntityAfterEventArgs> Updated

Event handler used after updating a record.

The event handler receives an argument of the EntityAfterEventArgs type. The argument provides the following properties:

Property	Type	Description
ModifiedColumnValues	`EntityColumnValueCollection`	The column values changed by the operation.
PrimaryColumnValue	`Guid`	The primary key value of the record.

event EventHandler<EntityBeforeEventArgs> Updating

Event handler used before updating a record.

The event handler receives an argument of the EntityBeforeEventArgs type. The argument provides the following properties:

Property	Type	Description
AdditionalCondition	`QueryCondition`	An additional condition that Creatio adds to the update query using the AND operator. By default, `null`.
IsCanceled	`bool`	Set to `true` to cancel the operation. By default, `false`.

event EventHandler<EntityValidationEventArgs> Validating

Event handler used when validating a record.

The event handler receives an argument of the EntityValidationEventArgs type. The argument provides the following properties:

Property	Type	Description
Messages	`EntityValidationMessageCollection`	The validation messages. Add an error message to fail validation. The collection is the same as the `ValidationMessages` property of the record.

Constructors​

Properties​

Methods​

Events​

See also​

Constructors

Properties

Methods

Events

See also