Storage Providers

Overview

REFRACT PDF uses two storage providers. You configure which one handles each output library using storage-config.json.

SharePoint is always required. Azure Blob Storage is provisioned only when you route at least one output library to blob in your storage-config.json.

Step 1 -- Configure SharePoint

sp-config.json

REFRACT PDF needs the SharePoint site and library identifiers for your tenant. Provide these in sp-config.json, which is deployed alongside the REFRACT PDF service.

{
  "siteId": "contoso.sharepoint.com,<site-guid>,<web-guid>",
  "driveIds": {
    "Templates":            "<drive-id>",
    "System Templates":     "<drive-id>",
    "Configurations":       "<drive-id>",
    "Payloads":             "<drive-id>",
    "Generated Documents":  "<drive-id>",
    "Reports":              "<drive-id>",
    "Archive":              "<drive-id>",
    "Audit Logs":           "<drive-id>"
  },
  "lists": {
    "VAULTPDF_Activity": "<list-id>"
  },
  "features": {
    "generatedDocuments": true,
    "reports":            true,
    "archive":            true,
    "auditLogs":          true
  }
}

How to find your IDs:

Feature flags

The features object controls which output libraries are active. Set a flag to false to silently skip writes to that library.

SP_SECRETS environment variable

The SharePoint credentials are provided as a JSON string in the SP_SECRETS environment variable. Set this in your production app settings, backed by a Key Vault reference.

{
  "tenantId":     "<azure-ad-tenant-id>",
  "clientId":     "<app-registration-client-id>",
  "clientSecret": "<secret>"
}

The app registration must have the following Microsoft Graph application permissions on your SharePoint site:

• Sites.ReadWrite.All (or site-scoped Sites.Selected)
• Files.ReadWrite.All

Step 2 -- Choose Output Storage

By default, all generated documents are written back to SharePoint. If you want some or all output libraries routed to Azure Blob Storage instead, follow the steps below.

SharePoint only (default)

No additional configuration needed. Omit STORAGE_CONFIG_PATH from your app settings, or create a storage-config.json with all routes set to sharepoint:

{
  "libraryRoutes": {
    "generatedDocuments": "sharepoint",
    "reports":            "sharepoint",
    "archive":            "sharepoint",
    "auditLogs":          "basic"
  },
  "accountName": "",
  "blobContainers": {}
}

Azure Blob Storage (optional)

To route one or more output libraries to Azure Blob:

1. Create an Azure Storage account (general-purpose v2 or later).
2. Create a container for each library you want to route to Blob (e.g. generated-documents, document-archive).
3. Assign the Storage Blob Data Contributor role to the REFRACT PDF app's Managed Identity on the storage account.
4. Set STORAGE_CONFIG_PATH in your app settings to the path of your storage-config.json file.
5. Configure storage-config.json as described in the next section.

Blob naming convention

Files written to Azure Blob follow this path pattern:

{DocType}/{YYYY}/{MM}/{correlationId}_{fileName}.pdf

Examples:

Invoice/2026/03/BC-INV-001_Invoice_2026-03-31.pdf
Reports/RenderErrors/2026/03/abc-123_error_REFRACT PDF.pdf
document-archive/2026/01/abc-100_SO-00400-Invoice.pdf

SAS URLs

After every upload to Blob, REFRACT PDF generates a time-limited SAS URL. The expiry window is set by sasUrlExpiryDays in storage-config.json (default: 30 days, max recommended: 180 days). The SAS URL is returned in the X-REFRACTPDF-BlobSasUrl response header and stored in the Activity list item so users can open the document directly from SharePoint.

storage-config.json

storage-config.json controls which output libraries go to SharePoint and which go to Azure Blob. Deploy this file alongside the REFRACT PDF service and set STORAGE_CONFIG_PATH to its path.

Full schema

{
  "libraryRoutes": {
    "generatedDocuments": "sharepoint | blob",
    "reports":            "sharepoint | blob",
    "archive":            "sharepoint | blob",
    "auditLogs":          "basic | blob | enterprise"
  },
  "accountName":     "your-storage-account-name",
  "blobContainers": {
    "generatedDocuments": "generated-documents",
    "reports":            "reports",
    "archive":            "document-archive",
    "auditLogs":          "audit-logs"
  },
  "sasUrlExpiryDays": 30
}

Field reference

libraryRoutes valid values

Libraries omitted from libraryRoutes fall back to their defaults. If STORAGE_CONFIG_PATH is not set at all, every library defaults to SharePoint.

Example: Reports on SharePoint, everything else on Blob

A common production configuration -- reports stay in SharePoint so users can browse them, generated documents and archive go to Blob for cost efficiency:

{
  "libraryRoutes": {
    "generatedDocuments": "blob",
    "reports":            "sharepoint",
    "archive":            "blob",
    "auditLogs":          "enterprise"
  },
  "accountName": "REFRACT PDFstorage",
  "blobContainers": {
    "generatedDocuments": "generated-documents",
    "archive":            "document-archive",
    "auditLogs":          "audit-logs"
  },
  "sasUrlExpiryDays": 90
}

Example: SharePoint only

{
  "libraryRoutes": {
    "generatedDocuments": "sharepoint",
    "reports":            "sharepoint",
    "archive":            "sharepoint",
    "auditLogs":          "basic"
  },
  "accountName": "",
  "blobContainers": {}
}

Environment Variables

Set these in your production app settings. Use Key Vault references for all secrets.

Response Headers

REFRACT PDF sets the following headers on every successful render response. Which headers are present depends on your libraryRoutes configuration.

Your calling application should handle both X-REFRACTPDF-WebUrl and X-REFRACTPDF-BlobSasUrl -- the header that appears depends on your routing configuration.

Related Pages

• Audit Logs -- choose and configure an audit tier (basic, blob, enterprise)
• System Architecture -- how REFRACT PDF fits into your tenant