--- title: DocumentRequestService summary: API reference for DocumentRequestService. status: draft owner: SAIF Doc Gen last_reviewed: 2026-09-24 library: SAIF.Services reference_type: package --- # DocumentRequestService Implements `IDocumentRequestService`, managing the lifecycle of document request logs and their distribution records: creating requests, transitioning status (new → pending → processing → completed/canceled), querying pending/processing work, and building an XML snapshot of a request's details. It depends on `IUnitOfWork` for persistence and `IUserProfileService` for stamping the acting user, and registers the Documents AutoMapper maps (code tables, template, request-log, request-log-search) in its static constructor. ## Purpose - Exposes the canonical document-request status string constants (`New`, `Completed`, `Pending`, `Canceled`, `Processing`, `Failed`) via typed accessor methods. - Submits new document requests against a template and retrieves request/distribution details by ID. - Advances requests and their distribution records through status transitions (mark in-process, mark complete, reset, or set an arbitrary valid status). - Queries pending/processing documents and builds a sortable list of pending requests for a user. - Creates, updates, and deletes individual document distribution log records. ## Context - Namespace: `SAIF.Services.Documents` - Assembly/package: `SAIF.Services` (packaged inside the `SAIF.SAIFCode.Core` NuGet package) ## Public members | Member | Signature | Purpose | | --- | --- | --- | | DocumentRequestService(...) | `public DocumentRequestService(IUnitOfWork unitOfWork, IUserProfileService userProfileService)` | Stores the unit of work and user-profile collaborators, requiring both to be non-null. | | NewRequestValue | `public string NewRequestValue()` | Returns the status constant used for a freshly submitted document request. | | CompletedRequestValue | `public string CompletedRequestValue()` | Returns the status constant used for a fully completed document request. | | PendingRequestValue | `public string PendingRequestValue()` | Returns the status constant used for a request awaiting distribution. | | CanceledRequestValue | `public string CanceledRequestValue()` | Returns the status constant used for a canceled document request. | | ProcessingRequestValue | `public string ProcessingRequestValue()` | Returns the status constant used while a request's distribution is actively being processed. | | ProcessingFailureValue | `public string ProcessingFailureValue()` | Returns the status constant used when distribution processing has failed. | | GetRequestDetailsOrDefault | `public Contract.RequestLog GetRequestDetailsOrDefault(long requestLogId)` | Returns the request log with `requestLogId` mapped to the contract type, or a default/null mapping if not found. | | GetRequestLogXElement | `public XElement GetRequestLogXElement(long inId)` | Builds an XML snapshot (`RequestData`/`TemplateData`) of the request's core and template fields, or an `Error` element with a "Request not found" message if `inId` does not resolve to a request. | | GetLatestMacroRequestForUserOrDefault | `public Contract.RequestLog GetLatestMacroRequestForUserOrDefault(string userId)` | Returns the most recent `New`-status request for `userId` whose template run type is `"MACRO"`. | | GetLatestRequestForUserOrDefault | `public Contract.RequestLog GetLatestRequestForUserOrDefault(string userId)` | Returns the most recent `New`-status request for `userId`, regardless of template run type. | | GetLatestXpRequestForUserOrDefault | `public Contract.RequestLog GetLatestXpRequestForUserOrDefault(string userId)` | Returns the most recent `New`-status request for `userId` whose template run type is not `"MACRO"` (i.e., the XPression path). | | GetPendingDocuments | `public IEnumerable GetPendingDocuments()` | Returns all distribution log entries whose owning request is in `Pending` status. | | GetProcessingDocuments | `public IEnumerable GetProcessingDocuments()` | Returns all distribution log entries whose owning request is in `Processing` status. | | IsWordDocument | `public bool IsWordDocument(long docId)` | Returns true when the template identified by `docId` has a `WORD` output profile configured. | | GetPendingRequests | `public IEnumerable GetPendingRequests(string requestedSort, string overrideUserId)` | Returns pending requests created by or assigned to `overrideUserId`, each annotated with its latest planned distribution date, sorted by name, date, or context per `requestedSort` (defaulting to date). | | GetOneXDeferredPrint | `public Contract.XDeferredPrint GetOneXDeferredPrint(long recordId)` | Returns the deferred-print record with `recordId`, mapped to the contract type. | | GetDocumentDistributionLogById | `public Contract.DocumentDistributionLog GetDocumentDistributionLogById(long logId)` | Returns the distribution log entry with `logId`, mapped to the contract type. | | GetDocumentDistributionLogsForRequest | `public IEnumerable GetDocumentDistributionLogsForRequest(long requestNumber)` | Returns all distribution log entries belonging to request `requestNumber`. | | UpdateDocumentDistributionLogStatusForRequest | `public void UpdateDocumentDistributionLogStatusForRequest(long requestNumber, string newStatus)` | Updates the status of every distribution log entry belonging to `requestNumber` to `newStatus`, one at a time via `UpdateDocumentDistributionLogStatus`. | | UpdateDocumentDistributionLogStatus | `public void UpdateDocumentDistributionLogStatus(long logId, string newStatus)` | Sets the status of distribution log `logId` to `newStatus` (resetting the actual-distribution date and setting a new planned date when transitioning back to `Pending`), stamping the update user/date; throws `DocumentRequestServiceException` if the log does not exist. | | UpdateDocumentDistributionLogXmlField | `public void UpdateDocumentDistributionLogXmlField(long logId, string newXml)` | Replaces the stored XML payload on distribution log `logId` with `newXml`, stamping the update user/date; throws `DocumentRequestServiceException` if the log does not exist. | | UpdateDocumentDistributionLogCompleted | `public void UpdateDocumentDistributionLogCompleted(long logId)` | Marks distribution log `logId` as `Completed`, sets its actual distribution date to now, and stamps the update user/date; throws `DocumentRequestServiceException` if the log does not exist. | | MarkDocumentRequestsInProcess | `public void MarkDocumentRequestsInProcess(DateTime endDateToGet, string specificRequestId)` | Transitions all (or one specific) `Pending`/`Processing`, non-Word, past-due distribution records — and their owning requests — to `Processing` status in one transaction. | | UpdateDocumentRequestAndDistribution | `public void UpdateDocumentRequestAndDistribution(long requestId, string newStatus)` | Sets `newStatus` on the owning request (once) and on every distribution record for `requestId`, resetting planned/actual distribution dates when transitioning back to `Pending`. | | ResetDocumentRequest | `public void ResetDocumentRequest(long requestId)` | Resets request `requestId` and its distribution records back to `Pending` status via `UpdateDocumentRequestAndDistribution`. | | UpdateDocumentDistributionRecord | `public void UpdateDocumentDistributionRecord(Contract.DocumentDistributionLog distributionLog)` | Overwrites the stored distribution log matching `distributionLog.Id` with all of `distributionLog`'s fields (status, dates, print/fax/email/imaging settings) in one transaction. | | GetNextDistributionRecordKey | `public long GetNextDistributionRecordKey()` | Inserts a throwaway distribution log to obtain the next database-generated key, then rolls back the transaction so the record is never actually persisted, returning the previewed key. | | CreateDocumentDistributionRecord | `public long CreateDocumentDistributionRecord(Contract.DocumentDistributionLog distributionLog)` | Persists a new distribution log populated from `distributionLog`'s fields and returns its generated ID. | | DeleteRequestDistributionById | `public void DeleteRequestDistributionById(long logId)` | Deletes the distribution log with `logId`. | | SetRequestAsComplete | `public void SetRequestAsComplete(long requestLogId)` | Marks request `requestLogId` as `Completed`, stamping update user/date and incrementing `UpdateNumber`; throws `DocumentRequestServiceException` if the request does not exist. | | UpdateRequestStatus | `public void UpdateRequestStatus(long requestLogId, string requestStatus)` | Validates `requestStatus` against the `DocRequestLogStatusCode` code table, then sets it on request `requestLogId`, stamping update user/date and incrementing `UpdateNumber`; throws `DocumentRequestServiceException` for an invalid status or missing request. | | SubmitDocumentRequest | `public long SubmitDocumentRequest(Contract.DocumentRequest documentRequest)` | Creates a new `New`-status request log against `documentRequest`'s template for the current user and returns its generated ID; throws if the template does not exist. | ## Behavioral notes - Most mutating methods (`UpdateDocumentDistributionLogStatus`, `MarkDocumentRequestsInProcess`, `UpdateDocumentRequestAndDistribution`, `CreateDocumentDistributionRecord`, `SetRequestAsComplete`, `SubmitDocumentRequest`, etc.) wrap their writes in `UnitOfWork.Begin()`/`Commit()`, but several do not explicitly roll back on exception, relying on the unit of work's own error handling*. - `GetNextDistributionRecordKey` deliberately calls `Rollback()` after insert so the "peeked" key is never committed — a pattern specific to obtaining a sequence value without a side effect*. - Several methods (`UpdateDocumentDistributionLogStatus`, `UpdateDocumentDistributionLogXmlField`, `UpdateDocumentDistributionLogCompleted`, `SetRequestAsComplete`, `UpdateRequestStatus`) throw the library-specific `Contract.DocumentRequestServiceException` when the targeted record is missing, rather than a generic exception. ## Sources - Services/SAIF.Services/Documents/DocumentRequestService.cs