--- title: AgencyService summary: API reference for AgencyService. status: draft owner: SAIF Doc Gen last_reviewed: 2026-09-24 library: SAIF.Services reference_type: package --- # AgencyService Implements `IAgencyService`, the facade for agency lookup, paperless-status management, document-notification email lists, and paperless-agreement confirmation emailing/imaging. It depends on `IUnitOfWork` for repository access and transactions, `IUserProfileService` to detect demo users (for masking producer/agent names) and resolve the current user's contact email, `IDocumentService` to send confirmation emails and distribute a generated PDF document, `IEnvironmentService` to gate active-user checks by production status, and `IImagingClient` (from the external `ImagingAPI.Client`/`ImagingAPI.Core` packages) to upload the signed paperless agreement PDF. ## Purpose - Retrieves agency search results and full agency details (masking producer/agent names for demo users), including for a given producer. - Determines whether an agency currently has any active external users, accounting for production test-user exclusions. - Builds email address lists for agency- or producer-level document notifications, and reads/creates/deletes individual `DocumentNotification` records. - Updates an agency's paperless-request and paperless-enrollment flags, each within its own transaction with rollback on failure. - Processes a paperless-agreement confirmation: emails the agent the signed PDF, and images both a notification-email record and the signed agreement itself via the imaging API. - Computes the set of paperless agencies that are "reverting" (no longer have active users) and thus need paperless status reconsidered. ## Context - Namespace: `SAIF.Services.Agencies` - Assembly/package: `SAIF.Services` (packaged inside the `SAIF.SAIFCode.Core` NuGet package) ## Public members | Member | Signature | Purpose | | --- | --- | --- | | AgencyService(...) | `public AgencyService(IUnitOfWork unitOfWork, IUserProfileService userProfileService, IDocumentService documentService, IEnvironmentService environmentService, IImagingClient imagingApiClient)` | Validates all five collaborators are non-null and stores them; registers the agency and agency-search-result AutoMapper maps in its static constructor. | | GetAgencySearchResults() | `public IEnumerable GetAgencySearchResults()` | Returns every agency mapped to lightweight `AgencySearchResult` contracts. | | GetAgency | `public Agency GetAgency(long agencyId)` | Returns the full `Agency` (with contracts, producers, agent, underwriter, document notifications) for `agencyId`, masking producer and agent names to "Producer" when the current user is a demo user; returns `null` if not found. | | GetPaperlessAgencyIds | `public ReadOnlyCollection GetPaperlessAgencyIds()` | Returns the IDs of all agencies flagged as paperless for agency copies of documents. | | GetRevertingAgencies | `public ReadOnlyCollection GetRevertingAgencies()` | Returns the full `Agency` records for paperless agencies that currently have no active external users. | | GetAgencyForProducer | `public Agency GetAgencyForProducer(long producerId)` | Returns the owning agency's full details for the given producer/agent ID, or `null` if the producer is not found. | | GetAgencyActiveUserStatus | `public bool GetAgencyActiveUserStatus(long agencyId)` | Returns `true` for `agencyId == 0`; otherwise returns whether the agency has any non-deleted external user who (in production) is not a test/production-test user, or (outside production) any non-deleted external user. | | GetEmailListForAgencyNotification | `public ReadOnlyCollection GetEmailListForAgencyNotification(long agencyId)` | Returns the distinct active email addresses of external users registered for document notifications at the agency level. | | GetEmailListForProducerNotification | `public ReadOnlyCollection GetEmailListForProducerNotification(long producerId)` | Returns the distinct active email addresses of external users registered for document notifications at the individual-producer level. | | GetDocumentNotification | `public DocumentNotification GetDocumentNotification(long agencyId, long userSeqNumber)` | Returns the agency's `DocumentNotification` entry matching `userSeqNumber`, or `null` if none exists. | | UpdateEmailNotification | `public bool UpdateEmailNotification(long agencyId, long userSeqNumber, bool isUserNotified)` | Creates a document-notification record when `isUserNotified` is true (and none exists), or deletes the existing one when false; returns whether the operation succeeded. | | UpdatePaperlessRequest | `public bool UpdatePaperlessRequest(long agencyId, bool requested, string updateUserId)` | Within a transaction, sets `IsPaperlessForAgencyRequested`, stamps update date/user, and commits; rolls back and rethrows a wrapping `Exception` on failure. Returns `false` if the agency is not found. | | UpdateAgencyPaperless | `public bool UpdateAgencyPaperless(long agencyId, bool paperless, string updateUserId)` | Within a transaction, sets `IsPaperlessForAgencyCopyOfDocuments`, stamps update date/user, and commits; rolls back and rethrows a wrapping `Exception` on failure. Returns `false` if the agency is not found. | | ProcessConfirmationEmail | `public bool ProcessConfirmationEmail(long agencyId, string pathToPaperlessAgreementPdf, string emailAttachmentFileName)` | Returns `false` if no PDF path is supplied; otherwise emails the current user's contact address the signed agreement, images a copy of the notification email, and images the signed agreement itself, returning `true`. | | GetAgencySearchResults(searchTerm, maxHits) | `public IEnumerable GetAgencySearchResults(string searchTerm, int maxHits = 0)` | Returns agencies whose ID or name (case-insensitive) matches `searchTerm`; when `maxHits` is non-zero, ranks results (active first, then name-starts-with, then name-contains, then alphabetically) and takes the top `maxHits`. | ## Behavioral notes - `UpdatePaperlessRequest` and `UpdateAgencyPaperless` are the only members that wrap writes in `unitOfWork.Begin()`/`Commit()`/`Rollback()` with a catch-and-rethrow, giving them transactional safety that other mutating members (`UpdateEmailNotification`'s private helpers) also apply individually. - `CreateEmailNotification`/`DeleteEmailNotification` (invoked via `UpdateEmailNotification`) each independently begin/commit/rollback their own transaction and throw a wrapping `Exception` with a description of the failed operation. - `ProcessConfirmationEmail` performs external I/O: reading the PDF from disk, sending an email through `IDocumentService.EmailService`, calling `IDocumentService.DistributeDocument` to generate/route an XML-described email-notification document, and calling `IImagingClient.Upload` against the external Imaging API. - Demo-user masking in `GetAgency` replaces producer and agency-agent names with the literal string "Producer" whenever `userProfileService.GetCurrentUser().IsDemoUser()` is true, guarding against null user/profile at each step. ## Sources - Services/SAIF.Services/Agencies/AgencyService.cs