---
title: SAIF.Framework.Core operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Framework.Core
reference_type: package
---

# SAIF.Framework.Core operations and processes

`SAIF.Framework.Core` has no end-user business processes of its own — it is the base layer every domain business-object library builds on. What it does provide is a fixed set of framework lifecycle operations: editing, validation, creation, retrieval, persistence, low-level data-portal dispatch, and API-client routing. Every business object and collection in the repository that inherits `clsBusinessBase` or `clsBusinessCollectionBase` runs through these operations, so understanding them here explains behavior that recurs across the entire framework. This page is the operation catalog and cross-operation hub for this library; each operation's detailed, step-by-step logic lives in its own page under `operations/`.

## Operation catalog
| Operation | Intent | Trigger | Inputs | Outputs | Rules | Tables | SQL |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Manage edit session](operations/manage-edit-session.md) | Open, commit, or roll back an in-memory editing scope for a business object or collection graph, including its children. | Caller or data-binding infrastructure invokes `BeginEdit`, `CancelEdit`, or `ApplyEdit`. | Business object or collection instance, including child objects and collections. | State snapshot committed, restored, or discarded; child add/delete state reconciled. | — | — | — |
| [Evaluate business object rules](operations/evaluate-business-object-rules.md) | Execute registered rules in severity order, refresh broken-rule state, and expose validity to callers and data binding. | Caller invokes `IsValid` or `CheckRules`. | Business object or collection, plus an optional property/group rule identifier. | Boolean validity result and refreshed error, warning, and informational rule state. | [BR-001](business-rules.md#br-001-rule-registration-and-enforcement-framework), [BR-002](business-rules.md#br-002-broken-rule-tracking-and-surfacing) | — | — |
| [Create business object from criteria](operations/create-business-object-from-criteria.md) | Instantiate the business object type implied by a criteria instance and drive it through its create lifecycle. | Caller invokes `IDataAccess.CreateObject(criteria)`. | `IBusinessCriteria` or `IBusinessApiCriteria` instance with a populated `DataPortalInfo`. | Newly instantiated, fully initialized business object. | — | — | — |
| [Retrieve business object from criteria](operations/retrieve-business-object-from-criteria.md) | Instantiate the business object type implied by a criteria instance and hydrate it through its retrieve lifecycle. | Caller invokes `IDataAccess.RetrieveObject(criteria)`. | `IBusinessCriteria` or `IBusinessApiCriteria` instance with a populated `DataPortalInfo`. | Hydrated business object populated from the data source. | — | — | — |
| [Save business object](operations/save-business-object.md) | Validate a root or child business object and dispatch the correct delete, insert, or update path based on its state flags. | Caller invokes `Save()` on a root object or parent logic invokes `SaveChild()` on a child object. | Business object with its current state flags, criteria object, and `DataPortalInfo`. | Object persisted (or left unchanged when not dirty), `False` when errors remain, or a thrown exception for an invalid entry state. | [BR-001](business-rules.md#br-001-rule-registration-and-enforcement-framework), [BR-002](business-rules.md#br-002-broken-rule-tracking-and-surfacing) | — | — |
| [Save managed business collection](operations/save-managed-business-collection.md) | Validate a managed collection, persist deferred deletions first, then persist active children, stopping at the first failure. | Caller invokes collection `Save()` or parent logic invokes collection `SaveChild()`. | Managed business collection, including its deleted-child list and active child items. | Deleted children removed, active children saved, or an early stop with the failing child's rules propagated to the collection. | [BR-001](business-rules.md#br-001-rule-registration-and-enforcement-framework), [BR-002](business-rules.md#br-002-broken-rule-tracking-and-surfacing) | — | — |
| [Execute data-portal request](operations/execute-data-portal-request.md) | Turn a scalar, result-set, sequence, or XML request into a portal/data request and dispatch it through the active data portal. | Caller invokes a convenience helper on `IDataPortalInfo` or submits a prepared portal request. | Portal ID, request metadata, and caller-supplied SQL or sequence name. | Scalar value, next sequence value, result set, XML payload, or updated portal request. | — | — | — |
| [Resolve API client and route](operations/resolve-api-client-and-route.md) | Bind API-backed criteria to a named REST client and render route templates with call-site arguments. | Caller constructs API criteria or invokes `GetApiClient`/`FormatRoute`. | `IDataPortalInfo`, client key, optional controller name, route key, and route arguments. | Resolved `IApiClient`, formatted `IApiRoute`, or a thrown `ArgumentException` for a missing client. | [BR-004](business-rules.md#br-004-api-criteria-sql-properties-are-always-empty-by-design) | — | — |
| [Enforce retrieve-only criteria guard](operations/enforce-retrieve-only-criteria-guard.md) | Block create, insert, update, and delete SQL access on criteria types that are intentionally read-only. | Caller accesses a SQL property on a `clsRetrieveOnlyBusinessCriteria` instance. | Retrieve-only criteria instance. | Stored retrieve SQL, or an immediate `ApplicationException` for any mutating property. | [BR-003](business-rules.md#br-003-retrieve-only-criteria-sql-suppression) | — | — |

## Process flow diagram
The following diagram visualizes how a caller's request is routed to the appropriate framework operation, and how the creation, retrieval, and persistence operations converge on the same data-portal dispatch path.

```mermaid
flowchart TD
	Start([Caller request]) --> D{Requested framework workflow?}
	D -->|Edit in memory| Edit[Manage edit session]
	D -->|Validate| Validate[Evaluate business object rules]
	D -->|Create/Retrieve| Lifecycle[Create or retrieve business object]
	D -->|Persist| Save[Save business object or collection]
	D -->|API-backed criteria| Api[Resolve API client and route]
	D -->|Read-only misuse| Guard[Enforce retrieve-only criteria guard]
	Validate --> Save
	Lifecycle --> Portal[Execute data-portal request]
	Save --> Portal
	Portal --> EndOk([Return object or data result])
	Api --> EndOk
	Guard --> EndErr([Raise framework exception])
	Edit --> EndOk
```

## Failure and edge-case behavior
- `Save()` and `SaveChild()` throw `ApplicationException` when the target is read-only, in the wrong root/child role, still inside an edit level, or invalid after rule evaluation.
- Collection save stops on the first child that returns `False`, propagates that child's broken rules to the collection, and does not continue to later items.
- `CreateObject`, `RetrieveObject`, and portal-processing helpers wrap lower-level failures in `ApplicationException` and disconnect the portal in `Finally`.
- `GetApiClient()` throws `ArgumentException` when the expected API client key is missing from `IDataPortalInfo.ApiClients`.
- `clsRetrieveOnlyBusinessCriteria` throws `ApplicationException("SQL property not available.")` as soon as a mutating SQL property is accessed.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Configuration](configuration.md)
- [API reference](api/index.md)

## Sources
- SAIF.Framework.Core\V1\BaseItems\clsBusinessBase.vb
- SAIF.Framework.Core\V1\BaseItems\clsBusinessCollectionBase.vb
- SAIF.Framework.Core\V1\BaseItems\clsUndoableBase.vb
- SAIF.Framework.Core\V1\BaseItems\clsRetrieveOnlyBusinessCriteria.vb
- SAIF.Framework.Core\V1\Api\clsBusinessApiCriteriaBase.vb
- SAIF.Framework.Core\V1\DataAccessLayer\clsDataPortalInfo.vb
- SAIF.Framework.Core\V1\DataAccessLayer\clsDataAccess.vb
- SAIF.Framework.Core\V1\DataAccessLayer\MSOracle\MSOracleDataPortal.vb
- SAIF.Framework.Core\V1\DataAccessLayer\SQLServer\SQLDataPortal.vb
- SAIF.Framework.Core\V1\BusinessRules\clsRulesManager.vb