---
title: Employee directory retrieval
summary: Returns filtered employee collections by reusing the shared ADP employee retrieval SQL and appending query-type-specific predicates.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Business
reference_type: package
operation_id: OP-SB-02
trigger: Caller requests a filtered employee collection.
---

# Employee directory retrieval

This operation returns lists of employees for directory-style use cases. `clsEmployeeDataCollection` reuses the same base employee query used by single-record lookups, then appends a literal predicate that matches the requested directory slice.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-SB-02 |
| **Trigger** | Caller invokes one of the collection factory methods such as `GetEmployeeDataByDepartment` or `GetAllEmployeeData`. |
| **Inputs** | Query type, query value, include-virtual flag |
| **Outputs** | `clsEmployeeDataCollection` |
| **Primary components** | `clsEmployeeDataCollection.GetEmployeeDataByDepartment`, `clsEmployeeDataCollection.Criteria.BeforeRetrieve`, `clsEmployeeDataCollection.AfterRetrieve` |
| **Entry point** | `Business\SAIF.Business\clsEmployeeDataCollection.vb` |

## Steps

1. The caller selects a query type such as department, title, location, active employees, or all employees and packages the query value inside `Criteria` ([BR-SB-011](../business-rules.md#br-sb-011-employee-collection-retrieval-appends-literal-filter-predicates)).
2. `BeforeRetrieve` starts from the shared employee SQL template and appends the query-type-specific predicate directly onto the statement, such as `DepartmentName = ...`, `JobTitle = ...`, `Location = ...`, or `ActiveInd = 1` ([BR-SB-011](../business-rules.md#br-sb-011-employee-collection-retrieval-appends-literal-filter-predicates), [SQL-026](../sql/SQL-026-employee-collection-retrieval.md), [ADP_EMPLOYEE](../database-tables.md#adp-employee)).
3. When the caller requested the all-employees variant with virtual rows enabled, the criteria appends the `UNION ALL` virtual-employee branch so the directory contains both ADP and `VIRTUAL_EMPLOYEE` records ([SQL-026](../sql/SQL-026-employee-collection-retrieval.md), [VIRTUAL_EMPLOYEE](../database-tables.md#virtual-employee)).
4. The data portal runs the finished SQL and returns the result set as directory rows ([SQL-026](../sql/SQL-026-employee-collection-retrieval.md), [ADP_EMPLOYEE](../database-tables.md#adp-employee), [VIRTUAL_EMPLOYEE](../database-tables.md#virtual-employee)).
5. `AfterRetrieve` creates one `clsEmployeeData` object per row, loads its fields from the result set, and appends it to the collection.
6. Collection helpers such as `GetByEmployeeID`, `Contains`, and `RemoveByEmployeeID` operate only against the in-memory list built in the previous step.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
    Start([Collection request]) --> Type[Choose query type]
    Type --> Build[Append literal filter predicate]
    Build --> Virtual{Include virtual employees?}
    Virtual -->|Yes| Union[Append virtual union]
    Virtual -->|No| Query[Run ADP query]
    Union --> Query
    Query --> Hydrate[Hydrate employee objects]
    Hydrate --> End([Return collection])
```

## Failure and edge-case behavior

- A query type with no matching rows returns an empty collection rather than raising an application error.
- Virtual employees appear only on the all-employees path that explicitly enables the union branch.
- The directory filters are concatenated as literals, so the exact filter shape is determined entirely by the selected query type and supplied value ([BR-SB-011](../business-rules.md#br-sb-011-employee-collection-retrieval-appends-literal-filter-predicates)).

## 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\clsEmployeeData.vb`
- `Business\SAIF.Business\clsEmployeeDataCollection.vb`