Operational runbook

PdfAPI is an IIS-hosted ASP.NET Web API 2 service with no in-code authorization, three coexisting error-handling mechanisms, and a single Oracle-backed tracking dependency. This runbook records deployment, health, status-code, logging, error-scenario, and monitoring findings as observed in source and pipeline configuration.

Deployment

Attribute	Value
Host	IIS
Site / virtual directory	Not determined from source**
Application pool	Not determined from source**
Deployment mechanism	Azure Pipelines — Pipelines\build-vars.yml (AppType: api)
Artifact	Deployed to IIS, not packaged as a NuGet artifact — see Dependencies: Produced packages for the two packages produced from this repository (PdfAPI.Client, Pdf.Local.Client), neither of which is the deployed API application itself

Environments

Environment	Base address	Environment track	Notes
DEV	Not determined from source**	entdev01 (ApplicationHost committed in Web.config)	Development host name committed to source control with no active transform override — see Tech debt
TEST	Not determined from source**	enttest03 (observed in PdfAPI.Tests\App.config)	Sibling-project evidence only; not asserted as the live TEST value for the deployed API
PROD	Not determined from source**	netprod (observed in PdfApiClientTester\PdfApiClientTester\App.config)	Sibling-project evidence only; not asserted as the live PROD value for the deployed API

Health verification

Check	Request	Expected result
Service responds	GET buildVersion	200 OK with build metadata key/value pairs — no dedicated health-check endpoint exists in this service, so this is the lightest read operators can safely call
API documentation surface reachable	GET /swagger/ui/index (Swagger UI, default route)	200 OK with the Swagger UI page — Swagger is live via PreApplicationStartMethod in SwaggerConfig.cs

Status codes

Code	Meaning	Operator action
200 OK	Success, and every processing failure on POST v1/convert, POST v1/convert/{fileExtension}, POST v1/extract, POST v1/merge, and GET v1/legacy/download/{trackingId} — inspect PdfResult.Status/Message in the body, not the HTTP status, for these five endpoints	None for a true success; inspect body for a failure PdfResult
500 Internal Server Error	Unhandled exception on any of the eight endpoints with no try/catch (InfoController's seven actions, ApiInfoController's one action) — the framework produces exception detail (IncludeErrorDetailPolicy.Always) before ApiResponseHandler runs; the final client-visible envelope is unknown** (see Endpoints: Error response shape)	Escalate with the logged exception detail; treat any exception detail reaching operators as sensitive and avoid forwarding it externally
404 Not Found	Route does not match — e.g. a non-numeric {trackingId} segment, produced by the framework's routing	Verify the route and the identifier supplied by the caller

Logs

Surface	Location	Content	Retention
ILogService.LogException / TraceError / TraceWarn / TraceDebug	Not determined from source** — backend implementation is supplied by the SAIF framework and configured outside this repository	Exception details from ConvertController, ExtractController, MergeController, LegacyController, ActivePdfService, PdfService.SendIncidentEmail	Not determined from source**
log4net 2.0.5	Not determined from source**	Referenced in packages.config; no log4net.config appender configuration is present in this repository	Not determined from source**
Stray console output	Process standard output (IIS-hosted; not surfaced to a log file by this repository)	Console.WriteLine(result.ToString()) at the end of SyncfusionPdfService.FinalizeResult — see Tech debt	Not applicable

Environment configuration

Setting	Key	Purpose
Processor selector	pdfapi.pdfservicetype	Selects ActivePDF vs Syncfusion processor
Working directory	pdfapi.rootdirectory	Filesystem root for conversion working/output files
Temp-save toggle	pdfapi.saveInputToTemp	Enables writing inbound documents to temp storage
Failure notification sender	noreplyemailsenderaddress	From-address for incident emails
Failure notification recipient	pdfapi.ErrorEmail.Recipient	To-address for incident emails
ActivePDF retry codes	pdfApi.ErrorsToRetry	CSV of vendor error codes that trigger an ActivePDF retry

See Configuration for the complete settings catalog, including the runtime resolution of the database connection.

Error scenarios

Scenario	Symptom	Impact	Recovery
Environment API unavailable	Failure during dependency registration or first configuration read (e.g. pdfapi.rootdirectory read in the PdfService base constructor)	Requests fail at DI resolution time; the affected controller cannot be constructed	Verify Environment API availability for the configured ApplicationHost track
Oracle connection resolution fails	Exception from DbConnectionManager.GetOracleConnectionString or the underlying NHibernate session	All tracking-dependent endpoints fail; non-tracking v1/info/* endpoints continue to function	Verify the EnvironmentConfigKeys.OracleDatabase environment key and the hard-coded "IMG" schema argument, then confirm Oracle availability
pdfApi.ErrorsToRetry misconfigured	FormatException from long.Parse during ActivePdfService construction (unguarded parse)	Every request routed to the ActivePDF processor fails at construction	Correct the CSV value in the Environment API configuration for pdfApi.ErrorsToRetry
SMTP host unreachable	Incident email send fails silently or throws inside SendIncidentEmail	Failure notifications are not delivered; the triggering request's own result is unaffected*	Verify connectivity to the hard-coded mail.saif.com host
Application pool recycled under load	Intermittent request failures; in-flight tracking rows may be left in PROC with no terminal update	Tracked requests may appear permanently Processing to polling clients	Investigate via GET v1/info/track/{trackingId}; manually reconcile stuck tracking rows if the external persistence tooling allows

Monitoring and alerting

No telemetry or alerting is configured. A grep for ConfigureOpenTelemetry( across PdfAPI, PdfAPI.Core, and PdfApi.SyncFusionCore returned zero matches, and no Application Insights, OpenTelemetry, or metrics package appears in PdfAPI\packages.config. The only observability in force is logging through ILogService and log4net. No alert rules are defined in this repository.

Related documentation

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

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

• PdfAPI\Global.asax.cs
• PdfAPI\App_Start\WebApiConfig.cs
• PdfAPI\App_Start\SwaggerConfig.cs
• PdfAPI\Controllers\v1\ApiInfoController.cs
• PdfAPI\Services\ActivePdf\ActivePdfService.cs
• PdfAPI\Services\PdfService.cs
• Pipelines\build-vars.yml
• PdfAPI\Web.config
• PdfAPI.Tests\App.config
• PdfApiClientTester\PdfApiClientTester\App.config