REFRACT Platform for Dynamics 365 Business Central
Event & Payload Reference - REFRACT PDF Business Central
Complete integration event reference for all 28 REFRACT AL integration 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 REFRACTPDF_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 | Each signer's window, in minutes. 0 leaves it out of the payload, so the Dispatcher default of 7 days applies. Otherwise it must be from 60 to 10080; a value outside that range refuses the render. |
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 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 28 integration events published by the extension, grouped by publisher object. All use [IntegrationEvent(false, false)] unless noted. 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 | Publisher | ID | IsHandled | Purpose |
|---|---|---|---|---|
OnBeforeGetDefaultLinesTableId | table "VPF Template Header" (global procedure, not local) | 73524578 | Yes | Override lines table auto-detection for custom header/lines document structures. Subscribe with ObjectType::Table, not ObjectType::Codeunit. |
OnBeforeFindParentFieldId | codeunit "VPF JSON Builder" | 73524587 | Yes | Register a custom alias for a child key field name on a parent table when the default convention-based lookup does not apply |
OnBeforeBuildJson | codeunit "VPF JSON Builder" | 73524587 | Yes | Replace the JSON payload entirely before field mapping runs |
OnAfterBuildJson | codeunit "VPF JSON Builder" | 73524587 | No | Transform JSON after field mapping; inject additional fields |
OnFormatField | codeunit "VPF JSON Builder" | 73524587 | Yes | Override how a specific field value is serialised (e.g. custom date format, enum label) |
OnBeforeAddField | codeunit "VPF JSON Builder" | 73524587 | Yes | Skip or rename a field before it is written to the JSON object |
OnAfterAddField | codeunit "VPF JSON Builder" | 73524587 | No | Observe a field after it has been written to the JSON object |
OnBeforeGetRootNodeName | codeunit "VPF JSON Builder" | 73524587 | Yes | Override the root JSON node name for a table |
OnResolveQuerySection | codeunit "VPF JSON Builder" | 73524587 | Yes | Inject a Query-backed JSON section into the payload |
OnBeforeGetDefaultFolderName | codeunit "VPF Dispatcher" | 73524594 | Yes | Override the PDF storage folder name in SharePoint |
OnBeforeGetDocumentIdentifier | codeunit "VPF Dispatcher" | 73524594 | Yes | Override the document ID used in the PDF filename and documentId payload field |
OnBeforeGetDispatcherAccessToken | codeunit "VPF Dispatcher" | 73524594 | Yes | Bypass OAuth; inject a pre-fetched or test dispatcher token |
OnBuildBatchLineEntries | codeunit "VPF Batch Dispatcher" | 73524596 | Yes | Inject additional expanded line entries into a batch generation run |
OnBeforeBuildJson | codeunit "VPF SharePoint Provider" | 73524592 | Yes | Replace JSON payload before SharePoint upload. A distinct event from the JSON Builder's OnBeforeBuildJson above - pick the right publisher object. |
OnAfterBuildJson | codeunit "VPF SharePoint Provider" | 73524592 | No | Transform JSON after build, before the SharePoint PUT |
OnBeforeGetFolderName | codeunit "VPF SharePoint Provider" | 73524592 | Yes | Override the SharePoint folder for payload JSON upload |
OnBeforeUpload | codeunit "VPF SharePoint Provider" | 73524592 | Yes | Cancel or mock the SharePoint PUT (used in test extensions) |
OnAfterUpload | codeunit "VPF SharePoint Provider" | 73524592 | No | Post-upload actions; receives the computed SharePoint URL |
OnUploadError | codeunit "VPF SharePoint Provider" | 73524592 | No | Handle upload failure; receives the raw error response body |
OnBeforeGetAccessToken | codeunit "VPF SharePoint Provider" | 73524592 | Yes | Bypass built-in OAuth for Graph calls; inject Managed Identity or Key Vault token. A distinct event from the Dispatcher's OnBeforeGetDispatcherAccessToken above - pick the right publisher object. |
OnAfterGetAccessToken | codeunit "VPF SharePoint Provider" | 73524592 | No | Observe or transform the Graph access token after acquisition |
OnBeforeGetSetting | codeunit "VPF Settings Mgt" | 73524585 | Yes | Intercept setting reads; provide values from Key Vault or custom config tables |
OnAfterGetSetting | codeunit "VPF Settings Mgt" | 73524585 | No | Log or transform a setting value after it is read |
OnBeforeSetContext | codeunit "VPF Gallery Context" | 73524586 | Yes | Replace the gallery source record before the Template Gallery opens |
OnAfterSetContext | codeunit "VPF Gallery Context" | 73524586 | No | Observe context after the gallery is initialised |
OnBeforeQueueForTable | codeunit "VPF Posting Subscriber" | 73524612 | Yes | Skip the default posting-triggered queuing for a table entirely. The signature has no template-code parameter - no specific template is chosen yet at this point, so a subscriber can suppress the default behaviour but not redirect it to a substitute template. |
OnAfterSendCompletionNotification | codeunit "VPF Batch Job Runner" | 73524607 | No | Fire after an async batch job finishes and the webhook notification step has run; use for AL-based post-completion logic |
OnBeforeWorkflowEnforcement | codeunit "VPF Workflow Enforcer" (global procedure, not local) | 73524604 | 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.