REFRACT Platform for Dynamics 365 Business Central
Complete integration guide for Business Central consultants and developers. Install, configure, and extend REFRACT PDF with on-demand PDF generation, SharePoint storage, e-signature workflows, and audit trails.
From Installation to First Document: Four Steps. One Working Session.
No database to provision. No portal to build or host. No separate identity system.
REFRACT Platform deploys into your existing Microsoft environment and uses services you already govern - Azure, SharePoint, Dataverse, and Microsoft Entra ID.
- Provision Storage: SharePoint libraries and configuration are created automatically
- Deploy Runtime Services: Dispatcher and Processor are deployed into your Azure subscription
- Load Starter Packs: Templates, field mappings, and Business Central integrations are loaded and ready
- Generate and Open Lifecycle: Generate your first Business Central document and open the Lifecycle Workspace with full audit visibility
Most organizations can deploy REFRACT Platform, generate a first document, and open the Lifecycle Workspace in a single working session.
Overview
REFRACT Platform extends Microsoft Dynamics 365 Business Central with document capabilities. Business Central comes pre-configured with ready-to-use templates for common documents (invoices, orders, remittances). All templates are fully customizable - no development required. Installation and system settings are pre-configured for immediate import.
Generate formatted PDFs from any Business Central record, automatically store them in SharePoint, optionally route them through workflow engines for approvals and e-signing, and maintain searchable audit trails of every document lifecycle event.
Pre-built Templates Ready to Go
Business Central ships with templates in the REFRACT Packs library. No custom development needed - import and use immediately, or customize to match your brand.
Key characteristics:
- Schema-driven rendering - Templates are JSON definitions that map Business Central data to PDF layouts
- In-tenant processing - All PDF generation runs inside the customer's Azure environment
- SharePoint integration - Documents store natively in SharePoint via Microsoft Graph
- Flexible workflows - Sequential or parallel approval and e-signature routing with audit capture
- Append-only audit records - Every document event (generation, approval, signature, delivery) logs to an append-only archive, so tampering is detectable
Architecture Overview
The REFRACT Platform for Business Central uses a single-tenant architecture. Each Business Central environment connects directly to its organization's REFRACT Dispatcher deployment hosted within the customer's Azure subscription. All document generation, governance workflows, and lifecycle processing occur within infrastructure controlled by the customer. REFRACT Delivery and REFRACT eSign use a REFRACT-hosted portal to reach recipients and signers, while rendering, storage, and audit remain in the customer's Azure subscription.
Microsoft Dynamics 365 Business Central
↓
REFRACT AL Extension
↓
JWT Token Issuance
(Entra App Registration, client-credentials flow)
↓
JWT Validation (Bearer token only)
↓
Customer-hosted REFRACT Dispatcher Function App
↓
REFRACT Platform Services
├─ REFRACT PDF
│ ├─ Document Generation
│ ├─ PDF/UA Accessibility
│ ├─ Structured Annexes
│ └─ Evidence Packages
│
├─ REFRACT Workflow
│ ├─ Approval Workflows
│ ├─ Validation Rules
│ ├─ Exception Reviews
│ └─ Governance Routing
│
├─ REFRACT Dispatch
│ ├─ Secure Delivery
│ ├─ Recipient Verification
│ ├─ Delivery Tracking
│ └─ Confirmation Auditing
│
├─ REFRACT eSign
│ ├─ Signature Requests
│ ├─ OTP Identity Verification
│ ├─ Attestations
│ └─ Signing Evidence
│
└─ REFRACT Lifecycle
├─ Activity Tracking
├─ Lifecycle Search
├─ Audit Evidence
├─ Compliance Reporting
└─ Governance AnalyticsCapabilities at a Glance
| Capability | Description | Use Case |
|---|---|---|
| PDF Generation | Render formatted PDFs from any Business Central document using configurable templates | Invoices, orders, reports, agreements |
| SharePoint Storage | Automatically upload generated PDFs and JSON payloads to SharePoint for centralized document management | Compliance document retention, team collaboration |
| E-Signature | Route documents to signers sequentially or in parallel through the REFRACT Platform engine | Contracts, approval forms, purchase agreements |
| Approval Workflows | Trigger validation workflows with configurable enforcement (validate or block processing) | Purchase requisitions, expense reports, policy updates |
| Distribution | Send documents to configurable recipient lists with delivery tracking and access logs | Customer statements, vendor remittances, partner communications |
| Batch Processing | Generate multiple PDFs in a single operation by record, group, or combined array | Monthly statement cycles, remittance runs, bulk document distribution |
Prerequisites
Before installation, ensure the following are in place:
Environment Requirements
- Business Central version 2024 Wave 1 (v27) or later
- Microsoft 365 tenant with Azure AD
- Azure subscription for Microsoft Graph API access
- SharePoint site with at least one document library for PDF output
Required Credentials and Configuration
Prepare the following before starting installation:
-
REFRACT SharePoint Access app registration (Business Central's own SharePoint uploads)
- Application (client) ID
- Client secret (Certificates & Secrets)
- API permissions: Microsoft Graph
Sites.ReadWrite.All(application) with admin consent
-
Microsoft Graph Identifiers
- Tenant ID (Azure AD Overview)
- SharePoint site ID (via Microsoft Graph Explorer)
- Drive IDs for output and template libraries
-
Business Central connector app registration (Business Central's calls to the Dispatcher)
- Application (client) ID and client secret of an app registration you create for Business Central
- Application permissions
Render.AccessandLifecycle.Readeron "REFRACT Dispatcher API", with admin consent - See Connect a source system
-
Business Central Setup
- SUPER or VPF-ADMIN permission set assigned to the setup user
- Deployment of the REFRACT Dispatcher (Azure Function)
Critical Dependency
The Dispatcher is a separately deployed Azure Function, deployed in your own Azure subscription. It is not included in the Business Central extension and must be provisioned before you can generate PDFs. Contact sales@refractlogic.com to arrange deployment. The credentials Business Central uses belong to app registrations in your own tenant: you create the Business Central connector app yourself, as described in Connect a source system.
Installation
Install the REFRACT PDF Extension
Search for Extension Management in the Business Central Tell Me bar (Alt+Q).
Click Manage → Upload Extension and select the REFRACT PDF extension .app file.
Alternatively, search for REFRACT PDF on AppSource if available in your region and install directly.
After installation completes, refresh your browser. You will see new REFRACT PDF actions appear on supported document types: Sales Orders, Purchase Orders, Sales Invoices, Purchase Invoices, and more.
No Page Restart Required
Business Central loads the extension immediately. No server restart is needed. The new action bar items appear instantly after the browser refresh.
Assign Permission Sets
Navigate to Users in Business Central and open each user's record.
In the User Permission Sets section, add the appropriate permission set:
| Permission Set | Purpose |
|---|---|
VPF-USER | Users who generate documents or open generated PDFs |
VPF-REVIEWER | Users who need to trigger workflow status synchronization |
VPF-ADMIN | Consultants and administrators managing templates, settings, and system configuration |
Assign permissions before the user's first visit to any REFRACT PDF page. Users without assigned permissions receive a clear error message with remediation steps.
Permission Requirement
Missing permission sets are the most common cause of access errors during initial setup. Verify all users have the required permission set before they access REFRACT PDF features.
Verify Extension Status
Search for Extension Management and locate the REFRACT PDF extension by Refract Logic.Confirm its status is Installed.
Search for View Permission Sets to verify that VPF-USER, VPF-REVIEWER, and VPF-ADMIN are all present.
This confirms the extension is correctly registered in the customer's Business Central environment and ready for configuration.
Initial System Setup
All connection settings, credentials, and configuration are managed through the REFRACT System Settings page. This single page is the customer's control center for the entire REFRACT Platform integration.
Access System Settings
Search for REFRACT System Settings in the Tell Me bar. You will see page open with an empty list.
Initialize Default Keys
Click the Initialize Default Keys action in the action bar.
This creates all 19 setting keys with empty values and displays them on the page, ready to populate. 14 of the 19 are required before the extension can generate documents; the remaining 5 (batch and notification keys, covered below) are optional and only need to be changed if you want non-default behavior.
Safe to Rerun
This action is idempotent. Running it multiple times only inserts missing keys and never overwrites values you have already entered. Use it safely during upgrades or to recover accidentally deleted keys.
Configure Microsoft Graph and SharePoint
For each setting key in the table below, click the row, enter the value in the Setting Value column, and click OK.
Fields marked with Is Secret = Yes are stored in Business Central Isolated Storage and never displayed after saving.
| Key | Where to Find It |
|---|---|
REFRACTPDF_TENANT_ID | Azure Portal → Azure Active Directory → Overview → Tenant ID |
REFRACTPDF_CLIENT_ID | Azure Portal → App Registrations → REFRACT SharePoint Access → Application (client) ID |
REFRACTPDF_CLIENT_SECRET | Azure Portal → App Registrations → REFRACT SharePoint Access → Certificates & Secrets (create if missing) (Is Secret) |
REFRACTPDF_GRAPH_SITE_ID | Microsoft Graph Explorer: GET /sites/{hostname}:/sites/{siteName} → copy id field |
REFRACTPDF_GRAPH_DRIVE_ID | Microsoft Graph Explorer: GET /sites/{siteId}/drives → copy the id of the customer's output document library |
REFRACTPDF_SITE_URL | The customer's SharePoint site base URL, e.g. https://yourorg.sharepoint.com/sites/Finance |
REFRACTPDF_GRAPH_TEMPLATES_DRIVE_ID | Drive ID of the SharePoint library containing REFRACT templates |
REFRACTPDF_SOURCE_SYSTEM | Root folder name in the templates drive, e.g. RefractLogic or BusinessCentral |
Azure AD App Permissions
REFRACT SharePoint Access must hold the Microsoft Graph application permission Sites.ReadWrite.All, admin-consented by a Privileged Role Administrator. Without this consent, SharePoint uploads fail with a 403 Forbidden error. This app is only for SharePoint: the Dispatcher connection below uses the Business Central connector app.
Configure the Dispatcher Connection
The Dispatcher is the Azure Function in your subscription that processes document payloads and renders PDFs. Populate these keys with your Business Central connector app's values (see Connect a source system):
| Key | Description |
|---|---|
REFRACTPDF_DISPATCHER_BASE_URL | Azure Function base URL, e.g. https://func-dispatcher-contoso-prod.azurewebsites.net/api |
REFRACTPDF_DISPATCHER_TENANT_ID | Your Microsoft Entra tenant ID |
REFRACTPDF_DISPATCHER_CLIENT_ID | The Business Central connector app's client ID. Not the client ID of "REFRACT Dispatcher API", and not REFRACT SharePoint Access. |
REFRACTPDF_DISPATCHER_CLIENT_SECRET | The Business Central connector app's secret value (Is Secret) |
REFRACTPDF_DISPATCHER_SCOPE | api://<dispatcher-app-client-id>/.default, where <dispatcher-app-client-id> is the client ID of "REFRACT Dispatcher API" |
REFRACTPDF_PORTAL_URL | REFRACT Platform Lifecycle Portal URL, e.g. https://portal.refractplatform.com |
The connector app needs Render.Access
The Business Central connector app, named by REFRACTPDF_DISPATCHER_CLIENT_ID, must hold the Render.Access application permission on "REFRACT Dispatcher API", with admin consent, for every call, including the System Status Check and document generation. Open Document and Sync Workflow Status also need Lifecycle.Reader. The sealed workflow PDF action also needs Lifecycle.Reader. See Integrations that use app tokens.
No function key
The extension authenticates to the Dispatcher with an OAuth2 client-credentials Bearer token only. There is no function-key setting; requests never append a ?code= query parameter.
Test System Connectivity
Click the System Status Check action in the action bar.
Business Central sends an HTTP GET request to {REFRACTPDF_DISPATCHER_BASE_URL}/render with an Authorization: Bearer header, and downloads the response body as REFRACTPDF_StatusReport.pdf. If the PDF opens successfully, connectivity to the Dispatcher is confirmed and healthy.
If the check fails:
- Review the error dialog for the HTTP status code and response body
- Verify the
REFRACTPDF_DISPATCHER_BASE_URLis correct - Confirm the
REFRACTPDF_DISPATCHER_CLIENT_SECREThas not expired - Check that the customer's Azure AD tenant can reach the Dispatcher Azure Function
Run this check after every change to Dispatcher settings to confirm the connection remains healthy.
Validation Best Practice
Make the System Status Check part of your weekly maintenance checklist, especially before running batch operations or critical document generation cycles.
Import Pre-configured Settings
A pre-configured JSON file is generated by the deployment installer, containing all system settings. Click Import System Settings and select the file.
The file must contain a REFRACTPDFSettings array at its root, with one object per setting (SettingKey, SettingValue, Description); the extension errors if that root key is missing. The legacy .vpdf file extension is also accepted for the same content.
Two secret values are left blank by the installer and must be filled in after import: REFRACTPDF_CLIENT_SECRET (the REFRACT SharePoint Access app's client secret) and REFRACTPDF_DISPATCHER_CLIENT_SECRET (the Business Central connector app's secret). The installer also leaves REFRACTPDF_DISPATCHER_CLIENT_ID empty: enter the Business Central connector app's client ID there. Any setting key containing _SECRET or _PASSWORD is automatically stored in Isolated Storage regardless of how the JSON file marks it.
Configure Batch Processing (optional)
The following keys control batch execution thresholds, log retention, and completion notifications.
| Key | Default | Description |
|---|---|---|
REFRACTPDF_BATCH_ASYNC_THRESHOLD | 500 | Minimum record count at which REFRACT shows the execution-choice prompt (Run now in background / Schedule for later / Generate now). |
REFRACTPDF_LOG_RETENTION_DAYS | 90 | Days to retain completed and failed batch job entries before automatic purge. Set to 0 to disable auto-purge entirely. |
REFRACTPDF_BATCH_NOTIFY_WEBHOOK_URL | (blank) | URL to POST a JSON completion notification when a batch job finishes. Leave blank to disable. See Webhook Completion Notifications for full details. |
REFRACTPDF_BATCH_NOTIFY_ON | FailureOnly | Set to Always to also notify on a Completed run. A Partial run (one that finished but had individual record errors) always notifies once a webhook URL is configured, regardless of this setting. A run that throws and aborts never reaches the notification step, so no webhook fires for it - the setting's own description ("FailureOnly = only Partial and Failed") overstates what the code actually checks for Failed. |
All four keys are created by Initialize Default Keys - you only need to edit them if you want non-default behaviour. None are secrets and all are safe to share in configuration exports.
Recurring Schedules
For unattended, time-based batch runs (nightly remittance, weekly statements), use the Schedule Batch action on the REFRACT Template to create a recurring Job Queue entry. No user needs to be logged in for scheduled runs to execute. See Scheduled and Recurring Batch Jobs in the Template Configuration guide.
Configure Automated Generation (optional)
The REFRACTPDF_GEN_QUEUE_MAX_RETRIES key exists but does not control per-record generation retries - it only prefills the "Max Attempts" field when scheduling a batch job, which feeds Business Central's own Job Queue Entry retry mechanism for that scheduled task.
Per-record retries are fixed at 3
Every generation request queued for automatic processing (via posting or the API) gets a maximum of 3 attempts, hardcoded at the point the request is queued. There is no backoff between attempts and no setting that changes this number. Once a request has failed 3 times it is marked Dead.
To enable automated generation, you also need to create a recurring Job Queue Entry for codeunit 73524611 ("VPF Gen Processor"). See Automated Document Generation for full setup instructions.
Next Steps
- Template Configuration - Configure templates, dispatch modes, e-signature, batch operations, batch filters, multi-hop traversal, and workflow enforcement
- Automated Document Generation - Auto-generate on post, external API triggers, and Generation Queue monitoring
- Pre-built Templates & REFRACT Packs - Browse professionally-designed templates ready to import
- Developer Guide - Extend REFRACT PDF with custom AL code, integration events, and enums
- Event & Payload Reference - Complete integration event table and dispatcher payload structure
- Troubleshooting Guide - Common issues and solutions
Append-Only Archive - Retention Policy
Retention period, write-lock behaviour, and GDPR considerations for the REFRACT Audit archive.
Template Configuration - REFRACT PDF Business Central
Configure REFRACT PDF templates for PDF generation, batch dispatch, e-signature, approval workflows, distribution, and multi-hop field traversal in Business Central.