---
title: Support order connection management
summary: Attaches and detaches individual claims to a support order's connection collection through inline SQL.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Business.Claim.SupportOrder
reference_type: package
operation_id: OP-SO-02
trigger: Caller retrieves or creates a clsClaimSupportOrderConnectionCollection for a SupportOrderID, adds or removes claim connections, and calls Save()
---

# Support order connection management

Support order connection management owns the `CL_CLAIM_SUPPORT_ORDER_CONN` link rows that tie individual claims to a support order. `clsClaimSupportOrderConnectionCollection` retrieves the connections for a support order and tracks in-memory additions and removals; `clsClaimSupportOrderConnection` performs the underlying insert/delete for a single link row. The header's `Connections` property (documented in [Support order retrieval and maintenance](support-order-retrieval-and-maintenance.md)) lazily hydrates this collection but does not cascade its save automatically.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-SO-02 |
| **Trigger** | Caller calls `clsClaimSupportOrderConnectionCollection.GetClaimSupportOrderConnectionCollection(dpi, supportOrderID)` (or `NewClaimSupportOrderConnectionCollection`), calls `CreateConnection`/`DeleteConnection` to attach or detach claims, and calls `Save()` |
| **Inputs** | `SupportOrderID`; `ClaimID` values to attach or detach; acting user from the data-portal info (used only when creating a connection) |
| **Outputs** | Persisted or removed `CL_CLAIM_SUPPORT_ORDER_CONN` rows; populated `clsClaimSupportOrderConnectionCollection`; `InsertError` / `DeleteError` messages on a rows-affected mismatch |
| **Primary components** | `clsClaimSupportOrderConnection` (`Create`, `BeforeInsert`/`AfterInsert`, `BeforeDelete`/`AfterDelete`, `NewClaimSupportOrderConnection`), `clsClaimSupportOrderConnectionCollection` (`GetClaimSupportOrderConnectionCollection`, `NewClaimSupportOrderConnectionCollection`, `BeforeRetrieve`/`AfterRetrieve`, `CreateConnection`, `DeleteConnection`, `Save`, `Item`, `Contains`, `ContainsDeleted`) |
| **Entry point** | `Business\SAIF.Business.Claim.SupportOrder\clsClaimSupportOrderConnection.vb` |

## Steps

1. **Retrieve connections for a support order.** `GetClaimSupportOrderConnectionCollection(dataPortal, supportOrderID)` builds a `Criteria(dataPortal, supportOrderID)` and calls `DataAccessLayer.RetrieveObject`.
2. **Issue the read.** `BeforeRetrieve` binds `SupportOrderID` and issues the connection select ([SQL-005](../sql/sql-005-select.md), [CL_CLAIM_SUPPORT_ORDER_CONN](../database-tables.md#cl-claim-support-order-conn)).
3. **Load each row.** `AfterRetrieve` reads the cursor; for each row it constructs a `clsClaimSupportOrderConnection`, calls `Load()` — which fills `ClaimID`, `SupportOrderID`, `UpdateDate`, and `UpdateUser`, rebuilds `Criteria(dataPortalInfo, ClaimID, SupportOrderID)`, and marks the object old — and adds it to the collection.
4. **Create a new connection in memory.** `CreateConnection(inClaimID)` calls `clsClaimSupportOrderConnection.NewClaimSupportOrderConnection(dataPortalInfo, inClaimID, MyCriteria.SupportOrderID)`.
   - `Create()` on the new connection seeds `ClaimID` and `SupportOrderID` from the criteria and sets `UpdateUser` from `MyCriteria.DataPortalInfo.UserID` — unlike `clsClaimSupportOrder`, this class does populate the acting user automatically at creation time (see [Support order retrieval and maintenance](support-order-retrieval-and-maintenance.md#steps)).
   - The new connection is added to the collection's in-memory list.
5. **Remove a connection from the collection in memory.** `DeleteConnection(inClaimID)` walks the list comparing each item's `SupportOrderID` (not `ClaimID`) to the supplied `inClaimID` argument and removes the first match.
   - The parameter is named `inClaimID` but is actually compared against each connection's `SupportOrderID` property, so this method removes an item by matching `SupportOrderID`, not by the claim it names — a caller intending to detach a specific claim from a support order that has more than one connection could remove the wrong row or none at all.**
   - The item is removed with the base list's `Remove()` rather than the collection's tracked-delete mechanism, so it is unclear whether the removed connection is retained on a deleted-items list for the subsequent `Save()` to delete from the database, or simply dropped from memory without ever being deleted from `CL_CLAIM_SUPPORT_ORDER_CONN`.**
6. **Save the collection.** `Save()` calls `ApplyEdit()` and then the inherited collection `Save()`, which persists new and deleted connection items tracked by the base collection.
7. **Insert a new connection.** `BeforeInsert` binds `ClaimID`, `UpdateUser`, and `SupportOrderID` and issues the insert ([SQL-002](../sql/sql-002-insert.md), [CL_CLAIM_SUPPORT_ORDER_CONN](../database-tables.md#cl-claim-support-order-conn)).
   - `AfterInsert`: rows affected other than `1` adds an `InsertError` with the DB contention message; otherwise the error is removed ([BR-004](../business-rules.md#br-004-connection-inserts-must-affect-one-row)).
8. **Delete a connection.** `BeforeDelete` binds `ClaimID` and `SupportOrderID` and issues the delete ([SQL-008](../sql/sql-008-delete.md), [CL_CLAIM_SUPPORT_ORDER_CONN](../database-tables.md#cl-claim-support-order-conn)).
   - The delete statement's `WHERE` clause references only `CLAIM_ID`; the bound `SupportOrderID` parameter has no matching predicate and does not narrow which row is removed.*
   - `AfterDelete`: rows affected other than `1` adds a `DeleteError` with the DB contention message; otherwise the error is removed ([BR-003](../business-rules.md#br-003-connection-deletes-must-affect-one-row)).
9. **Query the in-memory collection.** `Item(index)`, `Item(supportOrderID)`, `Contains(...)`, and `ContainsDeleted(...)` operate only on the in-memory list and deleted-list; they perform no database access.
10. **Lazily hydrate from the header.** `clsClaimSupportOrder.Connections` calls `GetClaimSupportOrderConnectionCollection` the first time it is accessed for a given header object and caches the result for the life of that object, tying this operation to the header's lifecycle without cascading its `Save()` automatically.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([GetClaimSupportOrderConnectionCollection<br>or header.Connections]) --> Retrieve[BeforeRetrieve reads<br>connections for SupportOrderID]
	Retrieve --> Load[AfterRetrieve loads each row]
	Load --> Edit{Caller action?}
	Edit -->|CreateConnection| Create[Create new connection;<br>UpdateUser set from portal info]
	Edit -->|DeleteConnection| Remove[Remove from in-memory list<br>by matching SupportOrderID]
	Create --> Save[Collection Save cascades<br>new / deleted items]
	Remove --> Save
	Save --> Which{New or deleted item?}
	Which -->|New| Ins[BeforeInsert / AfterInsert]
	Which -->|Deleted| Del[BeforeDelete / AfterDelete]
	Ins --> Rows{RowsAffected = 1?}
	Del --> Rows2{RowsAffected = 1?}
	Rows -->|No| InsErr([InsertError added])
	Rows -->|Yes| InsOk([Error cleared; item marked old])
	Rows2 -->|No| DelErr([DeleteError added])
	Rows2 -->|Yes| DelOk([Error cleared; item removed])
```

## Failure and edge-case behavior

- `DeleteConnection(inClaimID)` compares its argument against each item's `SupportOrderID` rather than `ClaimID`, so removal by claim identifier does not behave as its name and parameter suggest.**
- The connection delete statement filters only on `CLAIM_ID`, so the `SupportOrderID` parameter bound in `BeforeDelete` is inert; if the same claim were ever connected to more than one support order, the delete could remove the wrong link (no evidence in this library that a claim can have more than one active connection, so the practical exposure is unconfirmed).*
- `AfterInsert`/`AfterDelete` on `clsClaimSupportOrderConnection` clear the corresponding error message on success, matching [BR-003](../business-rules.md#br-003-connection-deletes-must-affect-one-row) and [BR-004](../business-rules.md#br-004-connection-inserts-must-affect-one-row); no equivalent clearing is confirmed to occur for whatever in-memory delete-tracking `DeleteConnection` relies on.**
- The connection collection is not saved automatically when the parent header (`clsClaimSupportOrder`) is saved; a caller must call `Save()` on `Connections` separately, or connection changes will be lost.

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with `**` could not be confirmed; treat as unknown until verified.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.md)

## Sources
- `Business\SAIF.Business.Claim.SupportOrder\clsClaimSupportOrderConnection.vb`
- `Business\SAIF.Business.Claim.SupportOrder\clsClaimSupportOrderConnectionCollection.vb`