Render Trace Auditing (Explain)

Explain Document captures a complete trace of what happened during PDF generation and generates interactive reports for troubleshooting template issues or creating compliance audit trails.

The Problem: The "Static PDF" Wall

Without an audit trail, a PDF is just a file. When an auditor asks why a field was masked or how a total was calculated, developers usually have to dig through old code. Explain Document removes the guesswork.

Overview

When enabled, Explain Document:

• Captures complete render event trace
• Generates three output formats (summary, detailed, raw JSON)
• Enables template debugging and troubleshooting
• Creates compliance documentation automatically
• Adds asynchronous overhead per render
• Creates a trace file per document
• Availability depends on your licence.

When to Enable

Enable Explain Document when you need:

• Template debugging and troubleshooting
• Root cause analysis of render failures
• Compliance audit trails for regulated documents
• Performance analysis and optimization
• Template consistency verification

Configuration

Enable Feature

{
  "templateSettings": {
    "explainDocument": true
  }
}

Storage & Sovereignty

Audit traces are stored as lightweight JSON files. To minimize costs and maximize performance, REFRACT PDF supports two backends:

• SharePoint: Best for low-volume compliance.
• Azure Blob: Recommended for higher volumes. Actual storage cost depends on your Azure Blob pricing tier and trace volume - check your own Azure billing rather than relying on a fixed estimate.

Report Formats

Explain Document generates three complementary formats:

1. Summary Report

Best for: Quick reviews, executive dashboards

Includes:

• Executive overview
• Top rendering events
• Performance metrics
• Accessibility summary
• Quick troubleshooting tips

2. Detailed Report

Best for: Compliance audits, root cause analysis

Includes:

• Complete event timeline
• Performance breakdown
• Data transformation log
• Element-by-element analysis
• Full accessibility report
• Error and warning details

3. Trace Data (JSON)

Best for: Machine analysis, programmatic access

Includes:

• Raw event JSON
• Page statistics
• Accessibility metrics
• Performance data
• All rendering decisions

How Users Download Reports (SharePoint UI)

When explainDocument: true is enabled in your template, users see an "Explain This Document" button in SharePoint:

From SharePoint Library

1. Click on any PDF generated from your template
2. Click the "..." menu (three dots)
3. Select "Explain This Document"

A dialog appears with three buttons:

┌─────────────────────────────────────┐
│  Explain This Document              │
├─────────────────────────────────────┤
│                                     │
│  [Summary]  [Detailed]  [Trace]    │
│                                     │
│  Summary: Quick overview            │
│                                     │
└─────────────────────────────────────┘

What Each Button Does

[Summary] - Quick PDF

• One-page overview of what changed
• What fields were redacted and why
• What transformations were applied
• Perfect for: Email, quick review, manager dashboard

[Detailed] - Full PDF

• Every change with complete details
• Full audit trail
• Compliance verification
• Perfect for: Auditors, legal, compliance review

[Trace] - JSON file

• Raw data in machine-readable format
• Import into audit systems
• Analyze with Splunk/Power BI
• Perfect for: Compliance systems, analytics

User Workflow Example

Auditor's process:

1. Opens Invoice PDF in SharePoint
2. Clicks "Explain This Document" → "Detailed"
3. Gets PDF showing exactly what was redacted
4. Downloads JSON trace for their audit system
5. Compliance verified

Finance Manager's process:

1. Receives payment notification
2. Clicks PDF, then "Explain This Document" → "Summary"
3. Sees what fields were hidden for security
4. Approves payment with confidence

How to Access Reports

All three routes require an Entra JWT bearer token, validated by tenant scope, that carries the Lifecycle.Reader role. Without the role they return 403 with code ROLE_MISSING.

Generate Summary or Detailed Report

The report is generated by a POST with the correlation or document ID in the JSON body, not a GET with an id query parameter:

curl -X POST "https://your-dispatcher.azurewebsites.net/api/explain/generate-pdf?mode=summary" \
  -H "Authorization: Bearer $ENTRA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "correlationId": "..." }'

Use ?mode=detailed for the full multi-page report. documentId also works in place of correlationId in the body.

Get Raw Trace

The trace route is a GET with correlationId or documentId as query parameters:

curl "https://your-dispatcher.azurewebsites.net/api/explain/trace?correlationId=..." \
  -H "Authorization: Bearer $ENTRA_ACCESS_TOKEN"

The response is served with Cache-Control: no-store - it is never cached, so every call re-fetches the trace.

Use Cases

Use Case 1: Multi-Page Template Debugging

When your complex invoice template renders unexpectedly:

1. Enable explainDocument in template
2. Render the document
3. Get detailed report showing:
   • Which pages took longest
   • Which conditional rules fired
   • Data validation warnings
   • Styling issues per page

Use Case 2: Compliance Audit Trail

For regulated documents requiring proof of rendering:

1. Enable all three premium features
2. Render document
3. Automatically create:
   • Accessibility verification
   • Metadata tracking
   • Complete render trace
   • Store in compliance archive

Use Case 3: Template Consistency Testing

Verify template renders the same way each time:

1. Render same data twice
2. Compare trace files
3. Verify identical page counts, timings, metrics

What Gets Captured

Explain Document traces:

Accessibility Validation

If Section 508 is also enabled, the Explain report includes an Accessibility Scorecard:

• Heading Hierarchy: PASS/FAIL
• Contrast Ratios: AAA/AA/FAIL
• Alt-Text Coverage: % of images tagged

Storage and Retention

Traces are stored separately from your PDF and looked up later by correlationId or documentId.

traceRetentionYears and autoArchiveAfterDays are not template or request settings - there is no per-organization or per-request retention configuration for explain traces. Retention is a property of the storage account's own lifecycle policy, set at deployment, not of the explainDocument feature.

Performance Impact

No verified latency, storage, or scalability figures are available for trace capture, report generation, or batch rendering - measure them against your own templates rather than relying on a fixed benchmark. Trace capture happens asynchronously, storage is separate from the PDF, and report generation is not cached: the API returns Cache-Control: no-store, so each request regenerates the report.

Common Questions

Q: Does tracing slow down my renders?

A: Negligibly. Trace capture happens asynchronously. Your render returns immediately.

Q: Can I combine this with other premium features?

A: Yes. All three features work independently:

{
  "options": {
    "features": {
      "section508Accessibility": true,
      "xmpMetadata": true,
      "explainDocument": true
    }
  }
}

Q: How long are traces kept?

A: Retention is set at the storage account level (a deployment-time lifecycle policy), not per template or per request. Confirm your deployment's storage lifecycle policy with whoever manages your infrastructure.

Q: What if I need to debug a production issue?

A: Two ways to investigate:

Option 1: From SharePoint (Easiest)

1. Click the PDF in SharePoint
2. Click menu ("...") → "Explain This Document"
3. Click "Detailed" button
4. Get a PDF showing exactly what happened step-by-step

Option 2: From Command Line (Programmatic)

# Get the PDF and check its XMP for the correlationId
exiftool -XMP:CorrelationId document.pdf
# Output: XMP:CorrelationId: abc-def-123-xyz

# Download detailed report
curl https://your-dispatcher.azurewebsites.net/api/explain/generate-pdf \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"correlationId": "abc-def-123-xyz", "mode": "detailed"}' \
  -o detailed-report.pdf

# Or download summary
curl https://your-dispatcher.azurewebsites.net/api/explain/generate-pdf \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"correlationId": "abc-def-123-xyz", "mode": "summary"}' \
  -o summary-report.pdf

# Or get raw trace (JSON)
curl https://your-dispatcher.azurewebsites.net/api/explain/trace \
  -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "?correlationId=abc-def-123-xyz" \
  -o trace.json

Both methods do the same thing - the SharePoint button just calls these APIs behind the scenes and opens the downloaded PDF in your browser.

Q: How long are traces retained?

A: Retention is set at the storage account level (a deployment-time lifecycle policy), not per template or per request. There is no archiveService.StoreAsync-style API or a retentionYears request parameter for explain traces - confirm your deployment's storage lifecycle policy with whoever manages your infrastructure.

Q: Can I use XMP without Section 508?

A: Yes. Each feature is independent:

{
  "features": {
    "section508Accessibility": false,
    "xmpMetadata": true,  // Only this
    "explainDocument": false
  }
}

Troubleshooting

Trace Not Generated

Problem: Correlation ID returned but trace not accessible

Check:

1. Verify feature is enabled in template
2. Confirm license includes Explain Document
3. Wait a few seconds (async trace capture)
4. Check correlation ID is correct

Report Generation Slow

Problem: Detailed report takes a long time to generate

Check:

1. Complex multi-page documents take longer to build
2. Every request is generated fresh - the response is served with Cache-Control: no-store, so repeated requests are not faster
3. Reports are generated on-demand, not pre-generated

Trace Storage Getting Large

Problem: Accumulated traces using lots of storage

Check:

1. Review your storage account's lifecycle management policy with whoever manages your infrastructure
2. Confirm the policy's retention and archive tiers match your compliance needs
3. Monitor storage costs

Related

• Premium Features Overview
• Section 508 Accessibility
• XMP Metadata Embedding