---
title: Manage the transaction envelope
summary: Starts or stops a portal transaction only when the requested boundary state has not already been reached.
status: draft
owner: SAIF Documentation Generation
last_reviewed: 2026-07-31
library: SAIF.Application.Policy
reference_type: package
operation_id: OP-09
trigger: Framework asks the manager to start or stop a transaction
---

# Manage the transaction envelope

This operation exposes the transaction-boundary hooks inherited by `PolicyAppManager`. The hooks are present for completeness, but the library's write path is permanently disabled.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-09 |
| **Trigger** | Framework asks the manager to start or stop a transaction |
| **Inputs** | Portal transaction state and commit/rollback intent |
| **Outputs** | Idempotent begin or end transaction behavior |
| **Primary components** | `PolicyAppManager.OnTransactionStart`, `OnTransactionStop`, `OnWrite`, `Write` |
| **Entry point** | `Application\SAIF.Application.Policy\PolicyAppManager.vb` |

## Steps

1. When transaction start is requested, check `DPI.TransactionPending`.
   - If no transaction is pending, call `DataLayer.DAL.BeginTransaction(DPI.PortalID)`.
2. When transaction stop is requested, check `DPI.TransactionPending` again.
   - If a transaction is pending, call `DataLayer.DAL.EndTransaction(DPI.PortalID, inCommit)`.
3. Return `False` from `OnWrite` so callers never execute a write path through this manager ([BR-128](../business-rules.md#br-128-the-manager-never-writes)).
4. Mirror the same read-only behavior through `Write()` by delegating to `OnWrite` and returning `False`.

## Process flow

The following diagram visualizes transaction guarding.

```mermaid
flowchart TD
    Start([Transaction boundary requested]) --> Kind{Start or stop?}
    Kind -->|Start| Pending{Transaction pending?}
    Pending -->|No| Begin[Begin transaction]
    Pending -->|Yes| Skip1[Skip]
    Kind -->|Stop| Pending2{Transaction pending?}
    Pending2 -->|Yes| End[End transaction]
    Pending2 -->|No| Skip2[Skip]
    Begin --> Done([Return read-only manager])
    Skip1 --> Done
    End --> Done
    Skip2 --> Done
```

## Failure and edge-case behavior
- Because [BR-128](../business-rules.md#br-128-the-manager-never-writes) disables writes, these hooks primarily guard against accidental nested transaction changes rather than enabling a real write workflow.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Configuration](../configuration.md)

## Sources
- `Application\SAIF.Application.Policy\PolicyAppManager.vb`