--- title: PolicyDocumentsApiService summary: API reference for PolicyDocumentsApiService. status: draft owner: SAIF Doc Gen last_reviewed: 2026-09-24 library: SAIF.Services reference_type: package --- # PolicyDocumentsApiService Implements `IPolicyDocumentApiService` to retrieve and assemble policy documents for external consumers, combining `IPolicyDocumentsService` (document/packet metadata), `IImagingClient` (page image retrieval), `IPdfClient` (PDF merge), `IPayrollReportService` (payroll report lookup by report ID), and `IPolicyQueryProvider` (policy status) with `IUserProfileService` authorization checks against the `PolicyPayrollReportExternal` and `PolInfoMntUpdtExt` security resources. ## Purpose - Produces a merged payroll-report PDF for a given report ID by locating the report's packet document, retrieving each page image, and merging them via the PDF API client. - Determines whether policy documents are viewable to a policyholder based on the policy's status group (documents are hidden while the policy is in `"APP"` status). - Retrieves the set of documents a policyholder is allowed to view, optionally filtered by document category, converting internal `PolicyDocument` data into `PolicyDocumentModel` view objects. - Validates report IDs and payroll-report readiness (existence, release status) before a report is surfaced to a caller. - Reports whether the current user has any of the payroll-report, policy-update, or SAIF-employee access rights. ## Context - Namespace: `SAIF.Services.Policies.PolicyDocumentsApi` - Assembly/package: `SAIF.Services` (packaged inside the `SAIF.SAIFCode.Core` NuGet package). ## Public members | Member | Signature | Purpose | | --- | --- | --- | | PolicyDocumentsApiService (constructor) | `public PolicyDocumentsApiService(IUnitOfWork unitOfWork, IUserProfileService profile, IPolicyDocumentsService policyDocumentsService, IPayrollReportService payrollReportService, IImagingClient imagingClient, IPdfClient pdfClient, IPolicyQueryProvider policyQueryProvider)` | Wires the user-profile, policy-document, payroll-report, imaging, PDF, and policy-query collaborators; all parameters except the unit of work name are null-checked via `Enforce.ArgumentNotNull`. | | GetPayrollReport | `public PolicyDocumentApi.PayrollReportPdf GetPayrollReport(long reportId)` | Validates the report ID and its documents' release status, then locates the payroll report's packet document, merges its page images into a single PDF via `IPdfClient.Merge`, and returns it wrapped in a `PayrollReportPdf`; returns an empty-byte `PayrollReportPdf` if validation fails or no packet document exists. | | AreDocumentsViewableToPolicyholder | `public bool AreDocumentsViewableToPolicyholder(long policyNumber)` | Returns `true` unless the policy's status group is `"APP"` (application-stage policies hide their documents from the policyholder). | | GetPolicyholderViewableDocuments | `public IEnumerable GetPolicyholderViewableDocuments(long policyNumber, string documentCategory)` | Returns the policyholder-viewable documents for the policy, restricted to the given category when `documentCategory` is non-empty, mapped to `PolicyDocumentModel`. | | HasValidCurrentUserAccess | `public bool HasValidCurrentUserAccess()` | Returns `true` if the current user holds the payroll-report access resource, the policy-update access resource, or belongs to the `SAIF` domain. | | GetPolicyNumberForPayrollReport | `public long GetPolicyNumberForPayrollReport(long reportId)` | Returns the policy number associated with the payroll report for the given report ID, or `0` if no report is found. | | ValidateReportId | `public int ValidateReportId(long reportId)` | Returns the `PolicyDocumentsReturnCodeList.InvalidReportId` code if no payroll report (or a report with `ReportId == 0`) is found for the ID, otherwise `Success`. | | GetPayrollReportDocs | `public IEnumerable GetPayrollReportDocs(long reportId)` | Returns the raw policy documents associated with the payroll report for the given report ID. | | ValidatePayrollReportStatus | `public static int ValidatePayrollReportStatus(Collection policyDocuments)` | Returns `UnknownError` for a null collection, `HistoricalReportNotFound` for an empty collection, `ReportNotReleased` if any document's status is not released, otherwise `Success`. | ## Behavioral notes - `GetPayrollReport` chains three validations (`ValidateReportId`, then `ValidatePayrollReportStatus` on the retrieved documents) before attempting to merge PDFs, short-circuiting to an empty `PayrollReportPdf` at the first failure. - The private `GetPacketPdfs` method retrieves each non-null image page (ordered by `DocumentType.SortOrder`) through `IImagingClient.GetPdf`, loads each as a `Document`, and merges them via `IPdfClient.Merge`; it catches all exceptions and returns an empty byte array rather than propagating the error.* - `GetPolicyholderViewableDocuments`, `GetPayrollReportDocs`, and the packet lookup in `GetPayrollReport` all delegate to `IPolicyDocumentsService` rather than querying the database directly. - `HasValidCurrentUserAccess` and the private access-check helpers rely on `IUserProfileService.GetCurrentUser().IsAuthorized(...)`/`.Domain`, matching the same authorization pattern used elsewhere in the Policies services.* ## Constraints and usage notes - `PolicyPayrollReportExternal` and `PolInfoMntUpdtExt` are the two security resources gating payroll-report and policy-update access respectively; SAIF-domain users bypass both checks. - `GetPacketPdfs` swallows all exceptions during PDF retrieval/merge and returns an empty result instead of surfacing the failure to the caller, so callers cannot distinguish "no packet" from "merge failed".* > **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. ## Sources - `Services/SAIF.Services/Policies/PolicyDocumentsApi/PolicyDocumentsApiService.cs`