Optional Provider: IEntityDataProviderProtected ActiveThe ContextCurrentUser is a property used to manually set the "current" user for scenarios, primarily on the server side, where the user changes per request. For situations where there is no global CurrentUser in the Metadata.Provider, you MUST set this property to the user you want to use for the current operation. If you used Metadata.GetEntityObject() to get the entity object, this property will be set automatically for you as that method has a parameter that can be provided for the ContextCurrentUser.
Protected Default value for whether async validation should be skipped. Subclasses can override this property to enable async validation by default. When the options object is passed to Save(), and it includes a value for the SkipAsyncValidation property, that value will take precedence over this default.
Returns true if the object is Dirty, meaning something has changed since it was last saved to the database, and false otherwise. For new records, this will always return true.
Access to the underlying metadata for the entity object.
Helper method to return just the first Primary Key
Returns true if any operation (Save, Delete, or Load) is currently in progress. This is a convenience property that combines IsSaving, IsDeleting, and IsLoading. Useful for disabling UI elements when any database operation is happening.
Returns true if a Delete operation is currently in progress. This is useful for UI components to show loading indicators or disable buttons while deleting.
Returns true if a Load operation is currently in progress. This is useful for UI components to show loading indicators while data is being fetched.
Returns true if the record has been saved to the database, false otherwise. This is a useful property to check to determine if the record is a "New Record" or an existing one.
Returns true if a Save operation is currently in progress. This is useful for UI components to show loading indicators or disable buttons while saving.
Returns the most recent result from the result history. If there are no results in the history, this method will return null.
Returns the primary key for the record. The CompositeKey class is a multi-valued key that can have any number of key/value pairs within it. Always traverse the full set of key/value pairs to get the full primary key for the record.
Returns an array of all primary key fields for the entity. If the entity has a composite primary key, this method will return an array of all primary key fields. If the entity has a single primary key, this method will return an array with a single field in it.
Returns this provider to be used for a given instance of a BaseEntity derived subclass. If the provider is not set, the BaseEntity.Provider is returned.
Returns a list of changes made to this record, over time. Only works if TrackRecordChanges bit set to 1 on the entity you're working with.
Returns true if the record has been loaded from the database, false otherwise. This is useful to check to see if the record is in a "New Record" state or not.
The result history shows the history of the attempted transactions (Save and Delete) for this particular entity object. This is useful for tracking the results of operations on the entity object.
Returns the RunQueryProvider to be used for a given instance of a BaseEntity derived subclass.
Returns the RunReportProvider to be used for a given instance of a BaseEntity derived subclass.
Returns the RunViewProvider to be used for a given instance of a BaseEntity derived subclass.
Transaction Groups are used to group multiple transactions into a single ATOMic transaction in a database. They are also useful even in situations with ATOMicity is less important but you want to submit a group of changes to the API server in a single network call.
Utility storage for vector embeddings that represent the active record. Each string in the Map can be any unique key relative to the object so you can use this to track vectors associated with
Static BaseWhen a BaseEntity class raises an event with MJGlobal, the eventCode property is set to this value. This is used to identify events that are raised by BaseEntity objects. Any MJGlobal event that is raised by a BaseEntity class will use a BaseEntityEvent type as the args parameter
Static ProviderStatic property to get/set the IEntityDataProvider that is used by all BaseEntity objects. This is a global setting that is used by all BaseEntity objects. It can be overriden for a given BaseEntity object instance by passing in a provider to the constructor of the BaseEntity object. Typically, a provider will pass itself into BaseEntity objects it creates to create a tight coupling between the provider and the BaseEntity objects it creates. This allows multiple concurrent connections to exist in the same process space without interfering with each other.
Called after an Action is executed by the AI Engine
Called before an Action is executed by the AI Engine This is intended to be overriden by subclass as needed, these methods called at the right time by the execution context
Utility method that returns true if the given permission being checked is enabled for the current user, and false if not.
This method MUST be called right after the class is instantiated to provide an async/await pair for any asynchronous operations a given entity needs to do when it is first created/configured. When you call Metadata/Provider GetEntityObject() this is done automatically for you. In nearly all cases you should go through GetEntityObject() anyway and not ever directly instantiate a BaseEntity derived class.
This method will copy the values from the other entity object into the current one. This is useful for things like cloning a record. This method will ONLY copy values for fields that exist in the current entity object. If the other object has fields that don't exist in the current object, they will be ignored.
the other entity object to copy values from
Optional includePrimaryKeys: booleanif true, the primary keys will be copied as well, if false, they will be ignored, defaults to false and generally you want to leave it that way
Optional replaceOldValues: booleanif true, the old values of the fields will be reset to the values provided in the other parameter, if false, they will be left alone, defaults to false and generally you want to leave it that way
This method deletes a record from the database. You must call Load() first in order to load the context of the record you are deleting.
Debounces multiple calls so that if Delete() is called again while a delete is in progress, the second call will simply receive the same result as the first.
Optional options: EntityDeleteOptionsPromise
Protected EmbedIn the BaseEntity class this method is not implemented. This method shoudl be implemented only in server-side sub-classes only by calling AIEngine or other methods to generate embeddings for a given piece of text provided. Subclasses that override this method to implement embedding support should also override
SupportsEmbedTextLocal and return true
Returns a promise that resolves when the current Delete operation completes. If no Delete operation is in progress, resolves immediately.
This is useful when you need to ensure a record is deleted before performing cleanup operations or navigating away from a view.
// Ensure any in-progress delete is complete before proceeding
await entity.EnsureDeleteComplete();
// Now safe to navigate away or perform cleanup
navigateToList();
Returns a promise that resolves when the current Load operation completes. If no Load operation is in progress, resolves immediately.
This is useful when you need to ensure data is loaded before accessing entity properties or performing operations that depend on loaded data.
// Ensure any in-progress load is complete before proceeding
await entity.EnsureLoadComplete();
// Now safe to access entity data
console.log(entity.Name);
Returns a promise that resolves when the current Save operation completes. If no Save operation is in progress, resolves immediately.
This is useful when you need to ensure data is persisted before performing a dependent operation, or when coordinating between multiple components that might trigger saves.
// Ensure any in-progress save is complete before proceeding
await entity.EnsureSaveComplete();
// Now safe to perform operations that depend on the saved state
await someOperationThatNeedsSavedData(entity);
Protected GenerateGenerates a vector embedding for a single text field using AI engine. Only generates embeddings for new records or when the source field has changed. Stores both the vector embedding and the model ID used to generate it.
The EntityField containing the text to embed
The EntityField to store the generated vector embedding (as JSON string)
The EntityField to store the ID of the AI model used
Promise that resolves to true if embedding was generated successfully, false otherwise
Protected GenerateGenerates a vector embedding for a single text field identified by field name. Retrieves the field objects and delegates to GenerateEmbedding method.
Name of the text field to generate embedding from
Name of the field to store the vector embedding
Name of the field to store the model ID used for embedding
Promise that resolves to true if embedding was generated successfully, false otherwise
Protected GenerateGenerates vector embeddings for multiple text fields using EntityField objects. Processes fields in parallel for better performance.
Array of field configurations with EntityField objects for source, vector, and model fields
Promise that resolves to true if all embeddings were generated successfully, false if any failed
Protected GenerateGenerates vector embeddings for multiple text fields by their field names. Processes fields in parallel for better performance.
Array of field configurations specifying source text field, target vector field, and model ID field names
Promise that resolves to true if all embeddings were generated successfully, false if any failed
NOTE: Do not call this method directly. Use the To method instead
Utility method to create an object and return it with properties in the newly created and returned object for each field in the entity object. This is useful for scenarios where you need to be able to persist the data in a format to send to a network call, save to a file or database, etc. This method will return an object with properties that match the field names of the entity object.
Optional oldValues: booleanWhen set to true, the old values of the fields will be returned instead of the current values.
Optional onlyDirtyFields: booleanWhen set to true, only the fields that are dirty will be returned.
Returns a partial object that contains only the fields that have changed since the last time the record was saved. This is useful for scenarios where you want to send only the changes to the server or to a client. It is also helpful for quickly finding the fields that are "dirty".
This utility method generates a completely new object that has properties that map to the fields and values in the entity at the time it is called. It is a copy, NOT a link, so any changes made to the object after calling this method will NOT be reflected in the object that is returned. This is useful for things like sending data to a client, or for use in a view model.
Optional params: DataObjectParamsThis utility method calls GetDataObject() internally and formats the result as a JSON string. If you want to get the data as an object instead of a string, call GetDataObject() directly.
Optional params: DataObjectParamsOptional minifyJSON: booleanConvenience method to access a field by name. This method is case-insensitive and will return null if the field is not found. You can do the same thing with more fine tune controlled by accessing the Fields property directly.
Optional filter: stringOptional maxRecords: numberOptional filter: stringOptional maxRecords: numberWrapper that holds an array of objects that contain the field name and value for the primary key of the record you want to load. For example, if you have a table called "Customers" with a primary key of "ID", you would pass in an array with a single object like this: {FieldName: "ID", Value: 1234}. *If you had a composite primary key, you would pass in an array with multiple objects, one for each field in the primary key. You may ONLY pass in the primary key fields, no other fields are allowed.
Optional EntityRelationshipsToLoad: string[]Optional, you can specify the names of the relationships to load up. This is an expensive operation as it loads up an array of the related entity objects for the main record, so use it sparingly.
true if success, false otherwise
Loads the Action Params record from the database
Optional EntityRelationshipsToLoad: string[](optional) the relationships to load
ActionParamEntity
Loads entity data from a plain object, typically from database query results.
This method is meant to be used only in situations where you are sure that the data you are loading is current in the database. MAKE SURE YOU ARE PASSING IN ALL FIELDS. The Dirty flags and other internal state will assume what is loading from the data parameter you pass in is equivalent to what is in the database.
A simple object that has properties that match the field names of the entity object
Optional _replaceOldValues: booleanPromise
Generally speaking, you should use Load() instead of this method. The main use cases where this makes sense are:
Important for Subclasses: As of v2.53.0, this method is now async to support subclasses that need to perform additional asynchronous loading operations (e.g., loading related data, fetching additional metadata).
Subclasses that need to perform additional loading should override BOTH this method AND Load() to ensure consistent behavior regardless of how the entity is populated. This is because these two methods have different execution paths:
// Subclass implementation
public override async LoadFromData(data: any, replaceOldValues: boolean = false): Promise<boolean> {
const result = await super.LoadFromData(data, replaceOldValues);
if (result) {
// Perform additional async loading here
await this.LoadRelatedData();
await this.LoadMetadata();
}
return result;
}
// Don't forget to also override Load() for consistency, unless you INTEND to have different behavior
// for Load() vs LoadFromData()
public override async Load(ID: string, EntityRelationshipsToLoad: string[] = null): Promise<boolean> {
const result = await super.Load(ID, EntityRelationshipsToLoad);
if (result) {
// Same additional loading as in LoadFromData
await this.LoadRelatedData();
await this.LoadMetadata();
}
return result;
}
This method will create a new state for the object that is equivalent to a new record including default values.
Optional newValues: FieldValueCollectionoptional parameter to set the values of the fields to something other than the default values. The expected parameter is an object that has properties that map to field names in this entity. This is the same as creating a NewRecord and then using SetMany(), but it is a convenience/helper approach.
Protected RaiseUsed for raising events within the BaseEntity and can be used by sub-classes to raise events that are specific to the entity.
Optional saveSubType: "create" | "update"Raises the transaction_ready event. This is used to indicate that the entity object is ready to be submitted for transaction processing. This is used by the TransactionGroup class to know when all async preprocessing is done and it can submit the transaction. This is an internal method and shouldn't be used by sub-classes or external callers in most cases. It is primarily used by Provider classes who are handling the tier-specific processing for the entity object.
This method can be used to register a callback for events that will be raised by the instance of the BaseEntity object. The callback will be called with a BaseEntityEvent object that contains the type of event and any payload that is associated with the event. Subclasses of the BaseEntity can define their own event types and payloads as needed.
If the entity object has a TransactionGroup associated with it, the TransactionGroup will be notified that we are doing some transaction pre-processing so that the TransactionGroup can properly wait for those pre-processing steps to complete before submitting the transaction. This method should generally NOT be called by anyone other than a provider that is handling the tier-specific processing for the entity object.
Saves the current state of the object to the database. Uses the active provider to handle the actual saving of the record. If the record is new, it will be created, if it already exists, it will be updated.
Debounces multiple calls so that if Save() is called again while a save is in progress, the second call will simply receive the same result as the first.
Optional options: EntitySaveOptionsPromise
NOTE: Do not call this method directly. Use the From method instead
Sets any number of values on the entity object from the object passed in. The properties of the object being passed in must either match the field name (in most cases) or the CodeName (which is only different from field name if field name has spaces in it)
Optional ignoreNonExistentFields: booleanif set to true, fields that don't exist on the entity object will be ignored, if false, an error will be thrown if a field doesn't exist
Optional replaceOldValues: booleanif set to true, the old values of the fields will be reset to the values provided in the object parameter, if false, they will be left alone
Optional ignoreActiveStatusAssertions: booleanif set to true, the active status assertions for the fields will be ignored, if false, an error will be thrown if a field is not active. Defaults to false.
Specifies if the current object supports the
EmbedTextLocal method or not - useful to know before calling it for conditional code that has fallbacks as needed. BaseEntity does not implement this method but server-side sub-classes often do, but it is not mandatory for any sub-class.
Protected ThrowThis method is used automatically within Save() and is used to determine if the state of the object is valid relative to the validation rules that are defined in metadata. In addition, sub-classes can override or wrap this base class method to add other logic for validation.
ValidationResult The validation result
Asynchronous validation method that can be overridden by subclasses to add custom async validation logic. This method is automatically called by Save() AFTER the synchronous Validate() passes.
IMPORTANT:
Subclasses should override this to add complex validations that require database queries or other async operations that cannot be performed in the synchronous Validate() method.
Promise
Static GetStatic Utility method to get RecordChanges for a given entityName/KeyValuePair combination
Optional provider: IEntityDataProvider
Action Params - strongly typed entity sub-class
Description
Tracks the input and output parameters for Actions.