REFRACT Platform for Dynamics 365 Business Central
Event & Payload Reference - REFRACT PDF Business Central
Complete integration event reference for all 22 REFRACT PDF AL events, plus the full dispatcher payload structure with all fields documented.
Dispatcher Payload Reference
The payload sent to the Dispatcher has the following structure. The templateSettings object is omitted entirely when no settings are configured on the template.
{
"templatePath": "SourceSystem/Module/templateId",
"payloadPath": "SourceSystem/Module/DOC001_MYTEMPLATE.json",
"options": {
"documentId": "DOC001",
"docType": "SalesOrder",
"generatedBy": "PADMA",
"sourceSystem": "RefractLogic",
"customColumns": {},
"features": {
"generatedDocuments": true
}
},
"templateSettings": {
"watermark": {
"enabled": true,
"value": "CONFIDENTIAL"
},
"distribution": {
"enabled": true,
"approversEmail": "approver@example.com"
},
"delivery": {
"recipients": [
{
"email": "r@example.com",
"displayName": "Recipient Name"
}
]
},
"esign": {
"enabled": true,
"signingMode": "sequential",
"expiresInMinutes": 10080,
"signers": [
{
"slotIndex": 1,
"role": "Signer",
"email": "s@example.com",
"namePrefill": "John Doe"
}
]
},
"approvalPanel": {
"user": "approver-id"
},
"workflow": {
"enabled": true,
"recipients": [
{
"email": "r@example.com",
"displayName": "Reviewer"
}
],
"message": "You have been invited to review document DOC001."
}
}
}Payload Fields
| Field | Type | Description |
|---|---|---|
templatePath | string | Full path to the template definition in SharePoint: {SourceSystem}/{Module}/{TemplateId} |
payloadPath | string | Full path to the payload JSON stored in SharePoint: {SourceSystem}/{Module}/{DocumentId}_{TemplateId}.json |
options.documentId | string | Unique identifier for this document. Used in the PDF filename and audit logs |
options.docType | string | Source document type, e.g. SalesOrder, PurchaseInvoice |
options.generatedBy | string | System that generated the request, e.g. PADMA (Business Central) |
options.sourceSystem | string | Root folder name from VAULTPDF_SOURCE_SYSTEM setting. Omitted when the setting is empty |
templateSettings | object | Routing, workflow, and delivery configuration (omitted if not configured) |
templateSettings Fields
| Field | Type | Description |
|---|---|---|
watermark.enabled | boolean | Print a watermark on the PDF |
watermark.value | string | Watermark text, e.g. CONFIDENTIAL |
distribution.enabled | boolean | Activate document delivery routing |
distribution.approversEmail | string | Approver email (token-resolved at dispatch time) |
delivery.recipients | array | Email recipients for direct delivery |
esign.enabled | boolean | Route PDF to signers after generation |
esign.signingMode | string | sequential or parallel |
esign.expiresInMinutes | integer | Signing link validity period (0 = Dispatcher default, 7 days) |
esign.signers | array | Ordered list of signers with slotIndex, role, email, namePrefill |
approvalPanel.user | string | Approval panel user identifier |
workflow.enabled | boolean | Trigger a REFRACT Platform approval workflow |
workflow.recipients | array | Workflow notification recipients |
workflow.message | string | Message body sent to workflow recipients (token-resolved) |
Inspect the live payload
Use the Sample Request action on the Template Card (search REFRACT PDF Templates → open a template → Sample Request) to see the exact JSON that would be sent for that template with all configured settings, without generating a real document.
Complete Integration Event Reference
All integration events published by REFRACT PDF, grouped by codeunit. All use [IntegrationEvent(false, false)]. Events marked IsHandled support override - set IsHandled := true to skip the default behaviour. See the Developer Guide for full signatures and code examples for each event.
| Event | Codeunit | ID | IsHandled | Purpose |
|---|---|---|---|---|
OnBeforeGetDefaultLinesTableId | REFRACT PDF Template Header | 77100 | Yes | Override lines table auto-detection for custom header/lines document structures |
OnBeforeFindParentFieldId | REFRACT PDF Template Header | 77100 | Yes | Override the field ID linking a lines table to its parent header when the default convention-based lookup does not apply |
OnBeforeBuildJson | REFRACT PDF JSON Builder | - | Yes | Replace the JSON payload entirely before field mapping runs |
OnAfterBuildJson | REFRACT PDF JSON Builder | - | No | Transform JSON after field mapping; inject additional fields |
OnFormatField | REFRACT PDF JSON Builder | - | Yes | Override how a specific field value is serialised (e.g. custom date format, enum label) |
OnBeforeAddField | REFRACT PDF JSON Builder | - | Yes | Skip or rename a field before it is written to the JSON object |
OnResolveQuerySection | REFRACT PDF JSON Builder | - | Yes | Inject a Query-backed JSON section into the payload |
OnBeforeGetDefaultFolderName | REFRACT PDF Dispatcher | 77119 | Yes | Override the PDF storage folder name in SharePoint |
OnBeforeGetDocumentIdentifier | REFRACT PDF Dispatcher | 77119 | Yes | Override the document ID used in the PDF filename and documentId payload field |
OnBeforeGetDispatcherAccessToken | REFRACT PDF Dispatcher | 77119 | Yes | Bypass OAuth; inject a pre-fetched or test dispatcher token |
OnBeforeBuildJson | REFRACT PDF SharePoint Provider | 77117 | Yes | Replace JSON payload before SharePoint upload |
OnAfterBuildJson | REFRACT PDF SharePoint Provider | 77117 | No | Transform JSON after build, before the SharePoint PUT |
OnBeforeGetFolderName | REFRACT PDF SharePoint Provider | 77117 | Yes | Override the SharePoint folder for payload JSON upload |
OnBeforeUpload | REFRACT PDF SharePoint Provider | 77117 | Yes | Cancel or mock the SharePoint PUT (used in test extensions) |
OnAfterUpload | REFRACT PDF SharePoint Provider | 77117 | No | Post-upload actions; receives the computed SharePoint URL |
OnUploadError | REFRACT PDF SharePoint Provider | 77117 | No | Handle upload failure; receives the raw error response body |
OnBeforeGetAccessToken | REFRACT PDF SharePoint Provider | 77117 | Yes | Bypass built-in OAuth for Graph calls; inject Managed Identity or Key Vault token |
OnAfterGetAccessToken | REFRACT PDF SharePoint Provider | 77117 | No | Observe or transform the Graph access token after acquisition |
OnBeforeGetSetting | REFRACT PDF Settings Mgt | 77110 | Yes | Intercept setting reads; provide values from Key Vault or custom config tables |
OnAfterGetSetting | REFRACT PDF Settings Mgt | 77110 | No | Log or transform a setting value after it is read |
OnBeforeSetContext | REFRACT PDF Gallery Context | 77111 | Yes | Replace the gallery source record before the Template Gallery opens |
OnAfterSetContext | REFRACT PDF Gallery Context | 77111 | No | Observe context after the gallery is initialised |
OnBeforeQueueForTable | REFRACT PDF Posting Subscriber | - | Yes | Intercept posting-triggered generation requests; skip or redirect to a different template code |
OnAfterSendCompletionNotification | REFRACT PDF Batch Job Runner | 77132 | No | Fire after an async batch job finishes and the webhook has been sent; use for AL-based post-completion logic |
OnBeforeWorkflowEnforcement | REFRACT PDF Workflow Enforcer | 77129 | Yes | Conditionally exempt a record or operation from workflow enforcement checks. Fires from CheckBeforeOperation - the public API partners call to extend enforcement to additional document types |
Developer Guide - REFRACT PDF Business Central
Extend REFRACT PDF with custom AL code. Subscribe to integration events, override templates, customize storage paths, and integrate with third-party systems.
Troubleshooting - REFRACT PDF Business Central
Diagnose and resolve common REFRACT PDF issues. Permission errors, authentication failures, SharePoint connectivity, template problems, and batch operation failures.