The Execution Context

Every script runs within an IScriptContextBridge. This context injects strongly-typed variables representing the current state of the application.

1. Core State Properties

These properties provide access to the current transaction, the executing user, and the data being manipulated.

Property	Type	Description	Available In
`Entity`	`T`	The strongly-typed instance of the current entity. Modifying properties here auto-saves during `BeforeCreate` and `BeforeUpdate`.	All Hooks
`OldEntity`	`T?`	The pristine database state of the entity before current modifications were applied.	`BeforeUpdate`, `AfterUpdate`
`Db`	`DbContext`	The EF Core database context scoped to the current tenant. Use `Db.Set<T>()` to query other tables.	All Hooks
`User`	`ClaimsPrincipal`	The currently authenticated user. Use `User.IsInRole("Admin")` to verify permissions.	All Hooks
`RecordId`	`string`	The string representation of the ID passed in the HTTP request. Essential when handling `OnLoad` for Virtual Entities.	All Hooks
`TransactionId`	`string`	The OpenTelemetry distributed tracing ID for the current request. Useful for logging.	All Hooks
`ParentContext`	`JsonElement?`	Read-only contextual data passed from a parent view if the current form is rendered as a Linked Nested Form.	`OnReady`, `BeforeCreate`

2. Event-Specific Properties

These properties are populated only during specific UI or orchestration events.

Property	Type	Description	Hook
`ChangedFieldName`	`string`	Identifies which specific field lost focus and triggered the server roundtrip.	`OnChange`
`ActionName`	`string`	The exact key of the button that was clicked by the user.	`CustomAction`
`WorkflowContext`	`IScriptWorkflowContext?`	Contains `WorkflowId`, `ReferenceKey`, and mutable `Variables` dictionary.	`CustomAction` (If triggered by a Workflow node)

3. Virtual Entity & Data Grid Properties

When intercepting a Grid query via the OnQuery hook (e.g., to feed external API data into a virtual table), you must manipulate these properties.

Property	Type	Description
`Entities`	`IEnumerable<T>?`	Assign the final list of items here to return them to the Grid or Export pipeline.
`GridFilter`	`FilterNode?`	The JSON representation of the current Advanced Filter applied by the user. Modifiable.
`GridTotalCount`	`int`	Assign the total number of available records (before pagination) for accurate UI rendering.
`GridPage`	`int`	(Read-Only) The page number requested by the UI.
`GridPageSize`	`int`	(Read-Only) The number of items per page requested by the UI.
`GridSortField`	`string?`	(Read-Only) The field name designated for sorting.
`GridSortDirection`	`string?`	(Read-Only) Indicates `"asc"` or `"desc"`.

4. Flow Control Methods

Methods to halt execution, report errors, or prevent default platform behavior.

AddError(string message): Adds a global form error and marks the transaction as failed. Does not throw an exception immediately.
AddError(string fieldName, string message): Marks the transaction as failed and highlights the specific input field in red on the frontend.
Abort(string message): Throws a ScriptAbortException. Immediately halts execution and triggers a database rollback.
Log(string message): Writes a persistent entry to Struktural_Sys_ActivityLog under the current transaction ID.
Cancel (bool Property): Set to true (e.g., Cancel = true;) to instruct the engine to skip the default EF Core database operation. Vital for Virtual Entities or soft-delete overrides.

5. Data Fetching Methods

Optimized extensions that prevent full Change Tracking overhead when resolving Navigation Properties.

LoadItemAsync<TProperty>(Expression<Func<T, TProperty>> selector): Asynchronously resolves a Many-to-One Foreign Key into its full object. Example: var customer = await LoadItemAsync(x => x.Customer);
LoadCollectionAsync<TElement>(Expression<Func<T, ICollection<TElement>>> selector): Asynchronously resolves a One-to-Many collection. Example: var orderLines = await LoadCollectionAsync(x => x.OrderLines);
LoadCollection<TElement>(...): Returns an IQueryable instead of a List, allowing you to append filters before executing the query against the database. Example: var recentLines = await LoadCollection(x => x.OrderLines).Where(L => L.Total > 100).ToListAsync();

6. The UI Controller (`Ui`)

The Ui property exposes the IUiContext interface, allowing backend logic to dispatch reactive commands to the Vue.js frontend. Valid primarily during OnReady, OnChange, and CustomAction.

Method	Description	Example
`ShowToast(string msg, string type)`	Displays a non-blocking toast notification. Types: `"info"`, `"success"`, `"warning"`, `"danger"`.	`Ui.ShowToast("Saved", "success");`
`ShowAlert(string msg, string title, string type)`	Displays a blocking modal alert.	`Ui.ShowAlert("Account locked.", "Error", "danger");`
`ShowConfirm(string msg, string title, string yesAction, string noAction)`	Displays a dialog with Yes/No buttons. If clicked, they trigger the specified `CustomAction` names.	`Ui.ShowConfirm("Delete?", "Confirm", "ConfirmDelete", "");`
`Navigate(string viewId, int? entityId)`	Redirects the user to a different View. Use constants from the `Views` class.	`Ui.Navigate(Views.Customer_Grid_1);`
`Focus(string fieldName)`	Forces the browser to focus the specified input cursor.	`Ui.Focus("EmailAddress");`
`SetReadOnly(string fieldName, bool isReadOnly)`	Dynamically locks or unlocks a field in the form.	`Ui.SetReadOnly("TotalAmount", true);`