Skip to content

OP-EXTRACT-PAGES: Extract pages

Validates that the source document is a real PDF, then extracts the requested page ranges (with clamping, skipping, and reversal semantics) into a new output document.

Field Value
Operation ID OP-EXTRACT-PAGES
Trigger Client submits POST v1/extract with an ExtractPagesRequest body
Entry endpoint POST v1/extract
Owning component ExtractController.Extract(ExtractPagesRequest) → IPdfService.ExtractPages(request)
Inputs ExtractPagesRequest (a DocumentRange pairing a source Document with one or more PageRange values), SourceSystemId
Outputs PdfResult (Status, Message, Document, TrackingId); a PDFTracking row created/updated
Failure response Caught exceptions are logged and returned as Ok(new PdfResult(message)) — HTTP 200

Steps

  1. The action wraps the call in try/catch (BR-PDFAPI-017).
  2. On any exception: _logService.LogException("pdfapi", "Extract", "<detail>", ex), then Ok(new PdfResult(ex.Message, request: request)) — HTTP 200, produced by the action's own catch block.
  3. If tracking is enabled (default, or forced on by SendHeatEmailOnFailure, BR-PDFAPI-010), PdfTrackingService.CreateTrackingRecord inserts a PDFTracking row.
  4. When pdfapi.saveInputToTemp is enabled, the inbound document is written to temporary storage before extraction (BR-PDFAPI-016).
  5. PdfClientService.ValidatePdf(request.DocumentRange.Document) validates the %PDF- file signature before any extraction work (BR-PDFAPI-004, BR-PDFAPI-005).
  6. On failure: a PdfException is thrown reporting that the file is not a valid PDF document (exact message text is not visible in this repository) and caught by step 1's try/catch — HTTP 200 with a failure PdfResult.

This validation is implemented in PdfAPI.Core (PdfClientService.ValidatePdf), documented in full at Validate PDF bytes (OP-01); its behavior is summarized here only as observed on this request path.

Origin: The PDF-signature validation behavior described in this step is implemented in PdfAPI.Core, not in PdfAPI. See the linked operation page for the full delegated logic. 5. PdfExtractor.Extract applies each page range: ranges are clamped to the document's page count, out-of-range ranges are skipped rather than erroring, descending ranges extract pages in reverse order, and a single IsOriginal range short-circuits and returns the original file untouched (BR-PDFAPI-018).

This extraction logic is implemented in PdfApi.SyncFusionCore (PdfExtractor.Extract), documented in full at Extract page ranges from a PDF (OP-SFC-011); its behavior is summarized here only as observed on this request path.

Origin: The page-range clamping, skipping, and reversal behavior described in this step is implemented in PdfApi.SyncFusionCore, not in PdfAPI. See the linked operation page for the full delegated logic. 6. SourceConversionType.Pdf is stamped on the result and SourceSystemId is parsed into ImageId. 7. FinalizeResult stamps TrackingId, PdfProcessorType, FilePath, then persists the terminal tracking status via PdfTrackingService.UpdateTrackingRecord. 8. The controller returns Ok(result) — HTTP 200 regardless of whether extraction succeeded or failed.

Process flow

The following diagram shows the validation, extraction, and tracking sequence for a page-extraction request.

flowchart TD
    A["POST v1/extract"] --> B["Create tracking record"]
    B --> C["ValidatePdf: check file signature"]
    C -->|Invalid| D["PdfException caught:<br>failure PdfResult, 200"]
    C -->|Valid| E["PdfExtractor.Extract applies page ranges"]
    E --> F["Stamp SourceConversionType and ImageId"]
    F --> G["FinalizeResult: persist terminal status"]
    G --> H["Ok result"]

Transaction and side effects

Aspect Finding
Unit of work IUnitOfWorkFactory("oracle"), InstancePerRequest
Commit point PdfTrackingService.CreateTrackingRecord and UpdateTrackingRecord, each bracketed by _uow.Begin()/_uow.Commit()
Records written PDFTracking (data model)
Downstream calls None (extraction is a fully local, single-request operation)
Repeat-call behavior Each call creates a new tracking record; not idempotent

Logging

Surface Written content
ILogService.LogException "pdfapi", "Extract", and exception detail, on any caught failure

Error handling

  • Non-PDF source document: PdfException thrown by PdfClientService.ValidatePdf, caught in the action, logged, returned as Ok(new PdfResult(message)) — HTTP 200 (BR-PDFAPI-017).
  • Out-of-range or descending page ranges: not an error — tolerated per BR-PDFAPI-018.

Sources

  • PdfAPI\Controllers\v1\ExtractController.cs
  • PdfAPI\Services\PdfService.cs
  • PdfAPI\Services\PdfTrackingService.cs
  • PdfAPI.Core\Services\PdfClientService.cs
  • PdfAPI.Core\Extract\PageRange.cs
  • PdfApi.SyncFusionCore\Extract\PdfExtractor.cs