Deterministic 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 ~5ms overhead per render
• Creates 50-200KB trace file per document
• Requires Premium or Enterprise license

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

{
  "vpdf": {
    "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 (Standard): Best for low-volume compliance.
• Azure Blob (Enterprise): Recommended for volumes >1,000 docs/month. Costs ~$0.02 per month for 10,000 traces.

Report Formats

Explain Document generates three complementary formats:

1. Summary Report

Best for: Quick reviews, executive dashboards

Includes:

• Executive overview (1 page)
• Top rendering events
• Performance metrics
• Accessibility summary
• Quick troubleshooting tips

Size: 5-10 pages, <500KB

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

Size: 20-50 pages, 2-5MB

3. Trace Data (JSON)

Best for: Machine analysis, programmatic access

Includes:

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

Size: 50-200KB JSON

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 1-2 page overview   │
│                                     │
└─────────────────────────────────────┘

What Each Button Does

[Summary] - Quick PDF (1-2 pages)

• 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 (5-10 pages)

• 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 in 2 minutes

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

Generate Summary

# Get 1-page overview
GET /api/explain/generate-pdf?id={correlationId}&mode=summary

Generate Detailed Report

# Get full multi-page report
GET /api/explain/generate-pdf?id={correlationId}&mode=detailed

Get Raw Trace

# Get JSON trace for analysis
GET /api/explain/trace?id={correlationId}

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 a Compliance 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:

• Retention: Configurable per organization
• Default: 30 days auto-archive, 2 years retention
• Access: Via API anytime

Configure custom retention for regulatory compliance:

{
  "traceRetentionYears": 7,  // Keep for 7 years
  "autoArchiveAfterDays": 90  // Move to cold storage after 90 days
}

Performance Impact

Common Questions

Q: Does tracing slow down my renders?

A: Negligibly. Trace capture is ~5ms and 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: Default is 30 days before archival, with 2-year retention. Configure per your compliance needs.

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-REFRACT PDF.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-REFRACT PDF.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-REFRACT PDF.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:

• Active traces: Indefinite (accessible via API)
• Archive auto-retention: 30 days default
• Custom retention: Configure per customer

// Archive a trace permanently
await archiveService.StoreAsync(
  category: "compliance",
  traceFile: await GetExplanationTraceAsync(correlationId),
  retentionYears: 7
);

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. First generation takes 5-10 seconds (normal)
2. Subsequent requests cached for 1 hour (instant)
3. Complex multi-page documents take longer
4. Reports are generated on-demand, not pre-generated

Trace Storage Getting Large

Problem: Accumulated traces using lots of storage

Check:

1. Configure auto-archive to move old traces
2. Review retention policy for your compliance needs
3. Set reasonable retention periods (e.g., 1-2 years for audits)
4. Monitor storage costs

Related

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