OP-CONVERT-FILE: Convert (file-shaped)

Converts raw document bytes submitted directly in the request body to PDF or PDF/A, using the route-supplied fileExtension in place of a ConvertRequest.FileExtension field. All other processing is identical to OP-CONVERT-REQUEST.

Field	Value
Operation ID	OP-CONVERT-FILE
Trigger	Client submits POST v1/convert/{fileExtension} with raw bytes in the body
Entry endpoint	POST v1/convert/{fileExtension}
Owning component	ConvertController.Convert(byte[] file, string fileExtension, PdfFormat format) → IPdfService.Convert(request)
Inputs	fileExtension route segment, raw byte[] body
Outputs	PdfResult (Status, Message, Document, TrackingId); a PDFTracking row created/updated; optionally an incident email
Failure response	Caught exceptions are logged and returned as Ok(new PdfResult(message)) — HTTP 200

Steps

1. The action constructs a ConvertRequest internally from fileExtension and the raw bytes, then wraps the call in try/catch (BR-PDFAPI-017).
2. On any exception: _logService.LogException("pdfapi", "Convert", "<detail>", ex), then Ok(new PdfResult(ex.Message, request: request)) — HTTP 200, produced by the action's own catch block.
3. PdfServiceFactory.Create() reads pdfapi.pdfservicetype and selects the processor (BR-PDFAPI-003) — identical selection logic to OP-CONVERT-REQUEST.
4. Tracking record creation, temp-storage save, processor dispatch, FinalizeResult, and incident-email notification follow the same shared path as OP-CONVERT-REQUEST steps 3–8:
5. If tracking is enabled (default, or forced on by SendHeatEmailOnFailure, BR-PDFAPI-010), PdfTrackingService.CreateTrackingRecord inserts a PDFTracking row with status SCHED (data model), then updates it to PROC.
6. When pdfapi.saveInputToTemp is enabled, the inbound bytes are written to temporary storage before conversion (BR-PDFAPI-016).
7. On the Syncfusion path (default), ConverterFactory.Convert(request) dispatches on the lower-cased, trimmed file extension: an unrecognized extension returns a failure PdfResult whose Status is left at the enum default NotTracked (BR-PDFAPI-008), and plain-text (.txt) input is converted twice — to an intermediate document, then to PDF (BR-PDFAPI-009).
8. On the ActivePDF path (pdfapi.pdfservicetype == "activepdf"): if SkipPdf is set (default true) and the input is already a PDF, conversion is short-circuited and the input is returned as the output (BR-PDFAPI-019). A PDF/A production failure is retried as plain PDF, and configured pdfApi.ErrorsToRetry error codes trigger a whole-operation retry (BR-PDFAPI-020).
9. FinalizeResult stamps TrackingId, PdfProcessorType, FilePath on the result, then persists the terminal tracking status (SUCC/ERROR) via PdfTrackingService.UpdateTrackingRecord.
10. If the result failed and SendHeatEmailOnFailure is set, PdfService.SendIncidentEmail sends a notification using noreplyemailsenderaddress/pdfapi.ErrorEmail.Recipient and the tracking record's ApplicationError.HeatEmailSubject (BR-PDFAPI-015).

Origin: Steps 3.1–3.6 are the shared conversion path implemented for both convert endpoints. They are documented in full at OP-CONVERT-REQUEST steps 3–8; this page embeds them here so the file-shaped operation's behavior is complete without cross-page lookup. 4. The controller returns Ok(result) — HTTP 200 regardless of whether the conversion succeeded or failed.

Process flow

The following diagram shows the route-binding, processor-selection, tracking, and incident-email sequence for a file-upload conversion request.

flowchart TD
    A["POST v1/convert/fileExtension"] --> B["Build ConvertRequest from route and body"]
    B --> C["PdfServiceFactory.Create selects processor"]
    C --> D["Create tracking record<br>SCHED to PROC"]
    D --> E{"Processor"}
    E -->|Syncfusion default| F["ConverterFactory.Convert"]
    E -->|ActivePDF| G["ActivePdfService.Convert"]
    F --> H["FinalizeResult: persist terminal status"]
    G --> H
    H --> I{"Result failed and<br>SendHeatEmailOnFailure?"}
    I -->|Yes| J["Send incident email"]
    I -->|No| K["Ok result"]
    J --> K

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	Outbound SMTP email on failure when SendHeatEmailOnFailure is set
Repeat-call behavior	Each call creates a new tracking record; not idempotent

Logging

Surface	Written content
ILogService.LogException	"pdfapi", "Convert", and exception detail, on any caught failure
ILogService.TraceError / TraceWarn / TraceDebug	Emitted from ActivePdfService on the ActivePDF processor path

Error handling

• Any exception during processing: caught in the action, logged, returned as Ok(new PdfResult(message)) — HTTP 200 (BR-PDFAPI-017).
• Unrecognized file extension: a failure PdfResult with Status == NotTracked (BR-PDFAPI-008).

Related documentation

• API index
• Overview
• Architecture
• Endpoints
• Authentication and authorization
• Dependencies
• Configuration
• Operations and processes
• Business rules
• Data model
• Operational runbook
• Tech debt

Sources

• PdfAPI\Controllers\v1\ConvertController.cs
• PdfAPI\Services\PdfServiceFactory.cs
• PdfAPI\Services\PdfService.cs
• PdfAPI\Services\PdfTrackingService.cs
• PdfAPI\Services\ActivePdf\ActivePdfService.cs
• PdfApi.SyncFusionCore\Convert\ConverterFactory.cs