---
title: Image collection retrieval
summary: Retrieves a filtered, capped list of image records with joined code-table descriptions, and resolves externally-viewable document type/category metadata.
status: draft
owner: <owner>
last_reviewed: 2026-07-30
library: SAIF.Business.Imaging
reference_type: package
operation_id: OP-IMG-05
trigger: Caller populates clsImageCollection.Criteria (or requests external document info) and retrieves
---

# Image collection retrieval

Image collection retrieval builds a dynamic, filterable query over the `IMAGE`/`IMGSYS` tables and their code tables, returning up to 300 rows for the imaging list/search UI. A related helper, `clsExternalImageInfo`, retrieves the externally-viewable document type/category metadata (with localized descriptions) used to drive external-facing document pickers.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-IMG-05 |
| **Trigger** | Caller sets filter criteria on `clsImageCollection.Criteria` and retrieves the collection, or calls `clsExternalImageInfo.GetExternalDocumentInfo` |
| **Inputs** | Filter criteria: category codes, document types, file types, claim IDs, date ranges, EAIP period, external view code, batch ID, discovery flag, security level number; for external info: file code and culture code |
| **Outputs** | A `clsImageCollection` of `IMAGE` rows joined with code descriptions (capped at 300 rows), or a `List(Of ExternalImageInfo)` of externally-viewable document type/category metadata |
| **Primary components** | `clsImageCollection.BeforeRetrieve`, `clsImageCollection.Criteria.FormatRequest`, `clsExternalImageInfo.GetExternalDocumentInfo` |
| **Entry point** | `Business\SAIF.Business.Imaging\clsImageCollection.vb`, `Business\SAIF.Business.Imaging\clsExternalImageInfo.vb` |

## Steps

1. **Caller provides filter criteria** to `clsImageCollection.Criteria` (category codes, document types, file types, claim IDs, date ranges, EAIP period, external view code, batch ID, etc.).
2. **Default filter values.** The criteria defaults `DiscoveryFlag = "N"` (`clsConstants.No`) and `SecurityLevelNum = 0` unless the caller overrides them.
3. **Build the dynamic WHERE clause.** `Criteria.FormatRequest` appends optional filter predicates to the base SQL depending on which criteria were supplied — e.g., `AND nvl(IMAGE.IMAGE_DELETE_CODE,' ') = ' '` is always applied to exclude soft-deleted images, and `AND IMAGE.DISCOVERY_FLAG = :DiscoveryFlag` is added based on the resolved discovery flag.*
4. **Retrieve the collection.** `BeforeRetrieve` executes [SQL-021](../sql/SQL-021-saif-business-imaging.md), a dynamically-assembled SELECT joining [IMGSYS](../database-tables.md#imgsys), [IMAGE](../database-tables.md#image), and multiple code tables ([IMAGE_CATEGORY_CODE](../database-tables.md#image_category_code), [IMAGE_DOCUMENT_TYPE_CODE](../database-tables.md#image_document_type_code)).
5. **Cap the result set.** The default List-mode query wraps the assembled SQL in `where rownum <= 300`, limiting results to 300 rows regardless of how many rows match the filter.
6. **Retrieve external document info.** `clsExternalImageInfo.GetExternalDocumentInfo` executes [SQL-016](../sql/SQL-016-saif-business-imaging.md), joining [IMAGE_FILE_CODE](../database-tables.md#image_file_code), [IMAGE_CATEGORY_CODE](../database-tables.md#image_category_code), and [IMAGE_DOCUMENT_TYPE_CODE](../database-tables.md#image_document_type_code) (with optional localized `_GCODE` variants by culture code), filtered to currently-effective document types for the given file code.
7. **Post-process external info.** Callers use `GetExternalDocumentTypes`, `GetExternalDocumentCategories`, `GetDocumentTypeCodes`, and `GetDocumentCategoryCodes` to group and filter the retrieved list in memory for cascading drop-downs (document type → category → specific type code).

## Process flow

The following diagram visualizes the image collection retrieval flow.

```mermaid
flowchart TD
	Start([Caller sets filter criteria]) --> Defaults[Apply defaults:<br>DiscoveryFlag = N,<br>SecurityLevelNum = 0]
	Defaults --> Format[FormatRequest builds<br>dynamic WHERE clause]
	Format --> Retrieve[BeforeRetrieve: SELECT<br>IMGSYS/IMAGE/code tables]
	Retrieve --> Cap[Cap to 300 rows<br>rownum <= 300]
	Cap --> Done([Return image collection])
	StartExt([Caller requests external<br>document info]) --> QueryExt[GetExternalDocumentInfo]
	QueryExt --> Group[Group/filter in memory:<br>types, categories, codes]
	Group --> DoneExt([Return cascading<br>drop-down data])
```

## Failure and edge-case behavior

- The 300-row cap (`rownum <= 300`) means callers with broader filter criteria than expected will silently receive a truncated result set rather than an error or a count indicator.*
- Soft-deleted images (`IMAGE_DELETE_CODE <> ' '`) are always excluded from the collection regardless of other filter criteria.
- `SecurityLevelNum` defaults to `0`; a value of `-1` is used internally as a sentinel to indicate "no security filter applied".*

## Related documentation

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

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Sources

- `Business\SAIF.Business.Imaging\clsImageCollection.vb`
- `Business\SAIF.Business.Imaging\clsExternalImageInfo.vb`