Documentation

Creatio development guide
PDF
This documentation is valid for Creatio version 7.15.0. We recommend using the newest version of Creatio documentation.

Working with database entity. The Entity class

Glossary Item Box

Introduction

The Terrasoft.Core.Entities.Entity class is designed to provide access to an object that represents a record in the database table.

The Terrasoft.Core.Entities.Entity class

NOTE

Use the “.NET class libraries of platform core” documentation to access the full list of the Entity class methods and properties, its parent classes and the implemented interfaces.

Constructors

  • public Entity(UserConnection userConnection) creates a new Entity class instance for the set UserConnection.
  • public Entity(UserConnection userConnection, Guid schemaUId) creates a new Entity class instance for the set UserConnection and the schemaUId schema set by the identifier.
  • public Entity(Entity source) creates a class instance that is a clone of the instance passed as an argument.

Properties

Table 1. Primary properties of the Entity class

Property Type Description
ChangeType EntityChangeType The type of changing the entity status (added, modified, deleted, unchanged)
EntitySchemaManager EntitySchemaManager Instance of the entity schema manager
EntitySchemaManagerName string Name of the entity schema manager
HasColumnValues bool Determines whether an object has at least one column.
HierarchyColumnValue Guid Value of column of the parent record relationship for hierarchical objects.
InstanceUId Guid Object instance identifier.
IsDeletedFromDB bool Determines whether the object is deleted from the database
IsInColumnValueChanged bool Determines whether the handling of the ColumnValueChanged event is performed
IsInColumnValueChanging bool Determines whether the handling of the ColumnValueChanging event is performed
IsInDefColumnValuesSet bool Determines whether the handling of the DefColumnValuesSet event is performed
IsInDeleted bool Determines whether the handling of the Deleted event is performed
IsInDeleting bool Determines whether the handling of the Deleting event is performed
IsInInserted bool Determines whether the handling of the Inserted event is performed
IsInInserting bool Determines whether the handling of the Inserting event is performed
IsInLoaded bool Determines whether the handling of the Loaded event is performed
IsInLoading bool Determines whether the handling of the Loading event is performed
IsInSaved bool Determines whether the handling of the Saved event is performed
IsInSaveError bool Determines whether the handling of the SaveError event is performed
IsInSaving bool Determines whether the handling of the Saving event is performed
IsInUpdated bool Determines whether the handling of the Updated event is performed
IsInUpdating bool Determines whether the handling of the Updating event is performed
IsInValidating bool Determines whether the handling of the Validating event is performed
IsSchemaInitialized bool Determines whether the entity schema is initialized
LicOperationPrefix string Prefix of the operation that is being licensed
LoadState EntityLoadState State of the object loading
PrimaryColumnValue Guid Initial column identifier
PrimaryDisplayColumnValue string Initial column value for displaying
Process Process The embedded process of an object
Schema EntitySchema Instance of the entity schema
SchemaName string Object schema name
StoringState StoringObjectState Object status (modified, added, deleted, unchanged)
UseAdminRights bool Determines whether permissions will be taken into account when inserting, updating, deleting and receiving data
UseDefRights bool Determines whether the default object permissions should be used
UseLazyLoad bool Determines whether to use the initial lazy loading of object data
UserConnection UserConnection User connection
ValidationMessages EntityValidationMessageCollection Collection of the messages output when validating an object
ValueListSchemaManager ValueListSchemaManager Instance of the object enumerations manager
ValueListSchemaManagerName string Name of the manager for object enumerations

Methods

Table 2. Primary methods of the Entity class

Methods Description

void AddDefRights()

void AddDefRights(Guid primaryColumnValue)

void AddDefRights(IEnumerable<Guid> primaryColumnValues)

 Sets the default permissions for the given object
virtual object Clone() Creates a clone of the current Entity instance
Insert CreateInsert(bool skipLookupColumnValues) Creates a query to insert data
Update CreateUpdate(bool skipLookupColumnValues) Creates a query to update data

virtual bool Delete()

virtual bool Delete(object keyValue)

 Deletes the object record from the database. The keyValue parameter determines the initial key of a record
bool DeleteWithCancelProcess() Deletes the object record from the database and cancels the launched process
static Entity DeserializeFromJson(UserConnection userConnection, string jsonValue) Creates an Entity type object using userConnection and populates the field values from the specified string of the JSON jsonValue format

bool ExistInDB(EntitySchemaColumn conditionColumn, object conditionValue)

bool ExistInDB(string conditionColumnName, object conditionValue)

bool ExistInDB(object keyValue)

bool ExistInDB(Dictionary<string,object> conditions)

 Determines whether a record matching the given condition of the conditionValue query to the conditionColumn object schema column or with the specified keyValue initial key exists in the database

bool FetchFromDB(EntitySchemaColumn conditionColumn, object conditionValue, bool useDisplayValues)

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

bool FetchFromDB(object keyValue, bool useDisplayValues)

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

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

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

By the specified condition, loads the object from the database.

Parameters:

  • conditionColumn – the column, for which the selection condition is specified
  • conditionColumnName – the name of the column, for which the selection condition is specified
  • conditionValue – the value of the condition column for the selected data
  • columnsToFetch – the list of columns to be selected
  • columnNamesToFetch – the list of column names to be selected
  • conditions – set of conditions for filtering the selection of object records
  • keyValue – the key field value
  • useDisplayValues - indicates that the query returns the primary display values. If the parameter is true, the query will return the primary display values.
bool FetchPrimaryColumnFromDB(object keyValue) By the set condition, keyValue loads the object with initial column from the database

bool FetchPrimaryInfoFromDB(EntitySchemaColumn conditionColumn, object conditionValue)

bool FetchPrimaryInfoFromDB(string conditionColumnName, object conditionValue)

 By the set condition, loads an object with initial columns including the initial display column from the database
byte[] GetBytesValue(string valueName) Returns the value of the specified object column as a byte array
IEnumerable<EntityColumnValue> GetChangedColumnValues() Returns the name collection of the object properties that have been modified
string GetColumnDisplayValue(EntitySchemaColumn column) Returns the value for display of the object property that matches the specified column of the entity schema

object GetColumnOldValue(string valueName)

object GetColumnOldValue(EntitySchemaColumn column)

 Returns the previous value of the specified object property

virtual object GetColumnValue(string valueName)

virtual object GetColumnValue(EntitySchemaColumn column)

 Returns the value of the object column with the specified name that matches the passed column of the object schema
IEnumerable<string> GetColumnValueNames() Returns the collection of object column names

virtual bool GetIsColumnValueLoaded(string valueName)

bool GetIsColumnValueLoaded(EntitySchemaColumn column)

 Returns whether the specified property of an object is loaded
virtual MemoryStream GetStreamValue(string valueName) Returns the value of the passed object schema column converted into the System.IO.MemoryStream type instance

virtual TResult GetTypedColumnValue<TResult>(string valueName)

TResult GetTypedColumnValue<TResult>(EntitySchemaColumn column)

 Returns the typed value of the object property that matches the specified column of the entity schema

TResult GetTypedOldColumnValue<TResult>(string valueName)

TResult GetTypedOldColumnValue<TResult>(EntitySchemaColumn column)

 Returns the typed previous value of the entity property that matches the specified column of the entity schema
virtual bool InsertToDB(bool skipLookupColumnValues, bool validateRequired)

Adds an entry of the current object to the database taking into account the passed parameters:

  • skipLookupColumnValues – parameter that determines whether the columns of the lookup type are to be added to the database. If the parameter is true, the columns of the lookup type will not be added to the base. Default value – false.
  • validateRequired - parameter that determines the necessity of validating the required values. Default value – true.

bool IsColumnValueLoaded(string valueName)

bool IsColumnValueLoaded(EntitySchemaColumn column)

 Determines whether the value of the object property with the specified name is loaded

virtual bool Load(DataRow dataRow)

virtual bool Load(DataRow dataRow, Dictionary<string,string> columnMap)

virtual bool Load(IDataReader dataReader)

virtual bool Load(IDataReader dataReader, IDictionary<string,string> columnMap)

virtual bool Load(object dataSource)

virtual bool Load(object dataSource, IDictionary<string,string> columnMap)

Populates the object with the passed data

Parameters:

  • dataRow – The System.Data.DataRow instance from which the data is loaded to the object
  • dataRow – The System.Data.IDataReader instance from which the data is loaded to the object
  • dataSource – The System.Object instance from which the data is loaded to the object
  • columnMap – object properties populated with data

void LoadColumnValue(string columnValueName, IDataReader dataReader, int fieldIndex, int binaryPackageSize)

void LoadColumnValue(string columnValueName, IDataReader dataReader, int fieldIndex)

void LoadColumnValue(string columnValueName, object value)

void LoadColumnValue(EntitySchemaColumn column, object value)

Loads the value from the passed instance for the property with the specified name

Parameters:

  • columnValueName – name of the object property
  • column – object schema column
  • dataReader – the System.Data.IDataReader instance from which the property value is loaded
  • fieldIndex – index of the field loaded from System.Data.IDataReader
  • binaryPackageSize – size of the loaded value
  • Value – value of the property that is being loaded
static Entity Read(UserConnection userConnection, DataReader dataReader) Returns the current property value of the Entity type from the output stream

void ReadData(DataReader reader)

void ReadData(DataReader reader, EntitySchema schema)

 Reads data from the object schema and saves them in the specified object of the System.Data.IDataReader type
void ResetColumnValues() Cancels changes for all object properties
void ResetOldColumnValues() Reverts all object properties to previous values
bool Save(bool validateRequired) Saves the object to the database. The validateRequired parameter determines the necessity of validating the required values. Default value – true.
static string SerializeToJson(Entity entity) Converts the entity object into a JSON format string
virtual void SetBytesValue(string valueName, byte[] streamBytes) Sets the passed value of the System.Byte type for the specified object property

bool SetColumnBothValues(EntitySchemaColumn column, object value, string displayValue)

bool SetColumnBothValues(string columnValueName, object value, string displayColumnValueName, string displayValue)

Sets the passed value and displayValue to the object property matching the specified schema column

bool SetColumnValue(string valueName, object value)

bool SetColumnValue(EntitySchemaColumn column, object value)

Sets the passed value to the specified schema column

void SetDefColumnValue(string columnValueName, object defValue)

void SetDefColumnValue(string columnValueName)

Sets the property with the specified name to the default value
void SetDefColumnValues() Sets default values for all object properties
bool SetStreamValue(string valueName, Stream value) Sets the passed value of the System.IO.Stream type for the specified object property
virtual bool UpdateInDB(bool validateRequired) Updates the object record in the database. The validateRequired parameter determines the necessity of validating the required values. Default value – true.
bool Validate() Verifies if the required fields are populated

static void Write(DataWriter dataWriter, Entity entity, string propertyName)

static void Write(DataWriter dataWriter, Entity entity, string propertyName, bool couldConvertForXml)

Records the value of the Entity type to the output stream with the specified name

Parameters:

  • dataWriter – instance of the Terrasoft.Common.DataWriter class that provides methods for sequential recording of values to the output stream
  • entity – value for record of the Entity type
  • propertyName — name of the object
  • couldConvertForXml – allows converting for xml-serialization

void Write(DataWriter dataWriter, string propertyName)

 Records the value of the Entity type to the output stream with the specified name

void WriteData(DataWriter writer)

void WriteData(DataWriter writer, EntitySchema schema)

 Records to the output stream for the specified object schema

Events

Table 3. The Entity class events

Events Description Event data
event EventHandler<EntityColumnAfterEventArgs> ColumnValueChanged Event handler used after modifying the value of an entity column

The event handler receives an argument of the EntityColumnAfterEventArgs type

The EntityColumnAfterEventArgs properties that provide information referring to the event:

  • ColumnValueName
  • DisplayColumnValueName
event EventHandler<EntityColumnBeforeEventArgs> ColumnValueChanging Event handler used before modifying the value of an entity column

The event handler receives an argument of the EntityColumnBeforeEventArgs type

The EntityColumnBeforeEventArgs properties that provide information referring to the event:

  • ColumnStreamValue
  • ColumnValues
  • ColumnValueName
  • DisplayColumnValue
  • DisplayColumnValueName
event EventHandler<EventArgs> DefColumnValuesSet Event handler used after setting default values for the object fields
event EventHandler<EntityAfterEventArgs> Deleted Event handler used after deleting an object

The event handler receives an argument of the EntityAfterEventArgs type

The EntityAfterEventArgs properties that provide information referring to the event:

  • ModifiedColumnValues
  • PrimaryColumnValue
event EventHandler<EntityBeforeEventArgs> Deleting Event handler used before deleting an object

The event handler receives an argument of the EntityBeforeEventArgs type

The EntityBeforeEventArgs properties that provide information referring to the event:

  • AdditionalCondition
  • IsCanceled
  • KeyValue
event EventHandler<EntityAfterEventArgs> Inserted Event handler used after inserting an object

The event handler receives an argument of the EntityAfterEventArgs type

The EntityAfterEventArgs properties that provide information referring to the event:

  • ModifiedColumnValues
  • PrimaryColumnValue
event EventHandler<EntityBeforeEventArgs> Inserting Event handler used before inserting an object

The event handler receives an argument of the EntityBeforeEventArgs type

The EntityBeforeEventArgs properties that provide information referring to the event:

  • AdditionalCondition
  • IsCanceled
  • KeyValue
event EventHandler<EntityAfterLoadEventArgs> Loaded Event handler used after loading an object.

The event handler receives an argument of the EntityAfterLoadEventArgs type

The EntityAfterLoadEventArgs properties that provide information referring to the event:

  • ColumnMap
  • DataSource
event EventHandler<EntityBeforeLoadEventArgs> Loading Event handler used before loading an object

The event handler receives an argument of the EntityBeforeLoadEventArgs type

The EntityBeforeLoadEventArgs properties that provide information referring to the event:

  • ColumnMap
  • DataSource
  • IsCanceled
event EventHandler<EntityAfterEventArgs> Saved Event handler used after saving an object

The event handler receives an argument of the EntityAfterEventArgs type

The EntityAfterEventArgs properties that provide information referring to the event:

  • ModifiedColumnValues
  • PrimaryColumnValue
event EventHandler<EntitySaveErrorEventArgs> SaveError Event handler used when an error occurs while saving an object

The event handler receives an argument of the EntitySaveErrorEventArgs type

The EntitySaveErrorEventArgs properties that provide information referring to the event:

  • Exception
  • IsHandled
event EventHandler<EntityBeforeEventArgs> Saving Event handler used before saving an object

The event handler receives an argument of the EntityBeforeEventArgs type

The EntityBeforeEventArgs properties that provide information referring to the event:

  • AdditionalCondition
  • IsCanceled
  • KeyValue
event EventHandler<EntityAfterEventArgs> Updated Event handler used after updating an object

The event handler receives an argument of the EntityAfterEventArgs type

The EntityAfterEventArgs properties that provide information referring to the event:

  • ModifiedColumnValues
  • PrimaryColumnValue
event EventHandler<EntityBeforeEventArgs>Updating Event handler used before updating an object

The event handler receives an argument of the EntityBeforeEventArgs type

The EntityBeforeEventArgs properties that provide information referring to the event:

  • AdditionalCondition
  • IsCanceled
  • KeyValue
event EventHandler<EntityValidationEventArgs> Validating Event handler used when validating an object

The event handler receives an argument of the EntityValidationEventArgs type

The EntityValidationEventArgs properties that provide information referring to the event:

  • Messages

Use cases

You can download the package with the configuration web serice implementing the below described cases using the following link.

Example 1

Receiving the value of the [City] schema column with [Name].

public string GetEntityColumnData()
{
    var result = "";
    // Creating a query to the "City" schema, adding the "Name" column to the query.
    var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "City");
    var colName = esqResult.AddColumn("Name");
    // Executing query to the database and receiving the object with the specified identifier. You can receive the object UId from a browser string with an open record edit page.
    var entity = esqResult.GetEntity(UserConnection, new Guid("100B6B13-E8BB-DF11-B00F-001D60E938C6"));
    // Receiving value of the object column.
    result += entity.GetColumnValue(colName.Name).ToString();
    return result;
}

Example 2

Receiving the collection of the [City] schema column names.

public IEnumerable<string> GetEntityColumns()
{
    // Creating an object of the "City" schema data string (by schema identifier received from the database).
    var entity = new Entity(UserConnection, new Guid("5CA90B6A-93E7-4448-BEFE-AB5166EC2CFE"));
    // Receiving the object with the specified identifier from the darabase. You can receive the object UId from a browser string with an open record edit page.
    entity.FetchFromDB(new Guid("100B6B13-E8BB-DF11-B00F-001D60E938C6"),true);
    // Receiving the collecton of the object column names.
    var result = entity.GetColumnValueNames();
    return result;
}

Example 3

Deleting the [Order] schema record from the database.

public bool DeleteEntity()
{
    // Creating a query to the "Order" schema, adding all schema columns to the query.
    var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Order");
    esqResult.AddAllSchemaColumns();
    // Executing query to the database and receiving the object with the specified identifier. You can receive the object UId from a browser string with an open record edit page.
    var entity = esqResult.GetEntity(UserConnection, new Guid("e3bfa32f-3fe9-4bae-9332-16c162c51e0d"));
    // Deleting the object from the database.
    entity.Delete();
    // Verifying whether the object with the specified identifier exists in the database.
    var result = entity.ExistInDB(new Guid("e3bfa32f-3fe9-4bae-9332-16c162c51e0d"));
    return result;
}

Example 4

Order status change.

public bool UpdateEntity()
{
    // Creating a query to the "Order" schema, adding all schema columns to the query.
    var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Order");
    esqResult.AddAllSchemaColumns();
    // Executing the database query and receiving the object with the specified identifier. You can receive the object UId from a browser string with an open record edit page.
    var entity = esqResult.GetEntity(UserConnection, new Guid("58be5223-715d-4b16-a5c4-e3d4ec0412d9"));
    // Creating the object of the OrderStatus schema data string.
    var statusSchema = UserConnection.EntitySchemaManager.GetInstanceByName("OrderStatus");
    var newStatus = statusSchema.CreateEntity(UserConnection);
    // Receiving the object with the specified name from the darabase.
    newStatus.FetchFromDB("Name", "4. Completed");
    // Assigns a new value to the "StatusId" column.
    entity.SetColumnValue("StatusId", newStatus.GetTypedColumnValue<Guid>("Id"));
    // Saving the changed object in the database.
    var result = entity.Save();
    return result;
}

Example 5

Adding the city with the specified name with connecting it to the specified country.

public bool InsertEntity(string city, string country)
{
    city = city ?? "unknown city";
    country = country ?? "unknown country";
    var citySchema = UserConnection.EntitySchemaManager.GetInstanceByName("City");
    var entity = citySchema.CreateEntity(UserConnection);
    entity.FetchFromDB("Name", city);
    // Sets the default values to the object columns.
    entity.SetDefColumnValues();
    var contryEntity = new Entity(UserConnection, new Guid("09FCE1F8-515C-4296-95CD-8CD93F79A6CF"));
    contryEntity.FetchFromDB("Name", country);
    // Assigns the passed city name to the "Name" column.
    entity.SetColumnValue("Name", city);
    // Assigns the UId of the passed country to the CountryId column.
    entity.SetColumnValue("CountryId", contryEntity.GetTypedColumnValue<Guid>("Id"));
    var result = entity.Save();
    return result;
}

© Creatio 2002-2020.

Did you find this information useful?

How can we improve it?