Template Configuration - VaultPDF Business Central

Template Configuration

Templates are the bridge between Business Central data and PDF output. A template defines which fields map to which PDF regions, how data is formatted, and how the resulting document is routed (e.g., for approval or signature).

Create the customer's first template

Navigate to VaultPDF Templates in Business Central.

Click New to open the Template Card. The card has two parts: the data source configuration (header) and the Variants subform (settings and routing).

Template Header (data source):

• Template Code - Unique identifier, e.g. SALES-ORDER
• Page ID - The Business Central page where this template appears in the gallery
• Source Table / Lines Table - Business Central tables providing header and line data
• Field Mapping Lines - Maps BC fields to the template JSON schema

Variants subform (settings per delivery style):

Every template automatically gets a default variant whose Variant ID matches the Template Code (e.g. SALES-ORDER). The default variant holds all generation settings: dispatch mode, watermark, e-signature, workflow, distribution, branding, and auto-generate.

Create additional variants when the same data source needs to produce PDFs with different configurations - for example, a SALES-ORDER-DRAFT variant with a DRAFT watermark alongside a clean SALES-ORDER final variant.

To configure a variant's settings, select its row in the Variants subform and click Edit Variant Settings.

Variant Settings

Variant Settings control how the generated PDF is handled after creation. Each variant has independent settings. Access them from the Variants subform on the Template Card by clicking Edit Variant Settings, or open VaultPDF Template Setup from Tell Me to manage all variants directly.

You have been invited to review and approve a document.
Document Reference: [No.] field.
Please complete the required action.
Do not forward or share this invitation.

Resetting Template Configuration

The Clear Settings action on the Variant Settings page resets all fields to defaults and deletes all signers, recipients, and workflow recipients. Use this to start a variant's routing configuration from scratch without deleting the template or the variant itself.

Branding (Logo)

The Branding section in Variant Settings controls how the logo is injected into the generated PDF. VaultPDF sends the logo as a base64-encoded string in the branding.logoBase64 field of the dispatch payload - the PDF template uses this field to render the logo at its configured position.

Logo injection is opt-in per template. The default is None - no logo is included unless you configure it.

Logo Source options

Example: Company logo on all sales templates

Open the Template Card for each sales template (e.g. SALES-ORDER), select the default variant in the Variants subform, click Edit Variant Settings, and in the Branding section set:

• Logo Source → Company Information

VaultPDF reads Company Information.Picture, converts it to base64, and includes it as branding.logoBase64 in every generated document for that template.

No additional template line mapping is needed.

Resulting payload:

{
  "branding": {
    "logoBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

Example: Location-based logos

Scenario: Your customer operates three warehouse locations - UK, DE, and US - each with its own brand logo. Sales Orders should use the logo of the fulfillment location rather than the company-wide logo.

How it works: extend the BC Location table with a base64 logo field, populate it per location, then point VaultPDF at that field via a template line hop.

tableextension 50100 "Location Logo Ext" extends Location
{
    fields
    {
        field(50100; "Logo (Base64)"; Text[2048])
        {
            Caption = 'Logo (Base64)';
            DataClassification = CustomerContent;
        }
    }
}

Resulting payload (Sales Order for location DE):

{
  "branding": {
    "logoBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

The value is the base64 string stored on the DE Location record.

Example: Logo stored on a linked entity (Template Line, multi-hop)

You can chain multiple hops to reach any linked table. For example, to use the Responsibility Center logo linked via Salesperson → Responsibility Center:

1. Add a Logo (Base64) field to the Responsibility Center table (table 5714) via extension
2. Add a template line with two hops:
   • Hop 1: Sales Header.Salesperson Code → Salesperson/Purchaser (table 13)
   • Hop 2: Salesperson/Purchaser.Resp. Center Code → Responsibility Center (table 5714)
3. Set Logo Source = Template Line → pick this line

The same TemplateLine mechanism resolves the full chain and reads the logo from the final record.

Template Setup (Variants)

Each template has one or more variants managed in the Variants subform on the Template Card. A variant connects the template's data source to a specific renderer file in SharePoint and holds all generation settings (dispatch mode, watermark, e-signature, branding, etc.).

The default variant is created automatically with the same Variant ID as the Template Code. To view or manage all variants across all templates, search for VaultPDF Template Setup in the Tell Me bar.

Variant identity and renderer fields (configured via Edit Variant Settings):

Adding a second variant:

In the Variants subform on the Template Card, click Duplicate Variant to copy the selected variant. The duplicate inherits all settings - change only what differs (e.g. Variant ID, watermark text, dispatch mode). The duplicate starts as Enabled = false until you verify the settings and enable it.

Additional Pages (Multi-Page Templates)

The Additional Pages subform on the Template Card (Configuration group) lets you register extra Business Central pages where the same template should appear in the gallery. This is useful when the same document type is processed from multiple pages - for example, a remittance template that should be available from both the Payment Journal page and the Vendor Card.

Navigate to VaultPDF Templates → open a template → Additional Pages subform to configure page mappings.

How it works: When a user opens the Template Gallery from any page listed in Additional Pages, VaultPDF includes this template in the gallery - alongside templates whose primary Page ID matches directly. Deduplication is automatic: if a template matches both the primary Page ID and an Additional Pages entry for the same page, it appears only once.

Example: A PURCH-REMITTANCE template has Page ID = 54 (Purchase Order). Adding page 51 (Purchase Invoice) to Additional Pages makes PURCH-REMITTANCE also appear in the gallery when opened from a Purchase Invoice card.

Multi-hop Field Traversal

Standard template field mapping reads fields directly from the source table (e.g. Sales Header) or its line table. Hop chains extend this to traverse foreign-key relationships - reaching tables that are not directly linked to the source document. For one-to-many relationships between a line record and another table, use Per-Line Array Nesting instead.

Example: A Purchase Order template that needs the vendor's bank account IBAN requires two hops: Purchase Header → Vendor (Buy-from Vendor No.) → Vendor Bank Account.

Configure hops on a template line via the Hops subpage (visible when the line has Via Table ID set):

Per-Line Array Nesting

Use Link Target Field ID to nest a related table's records as a JSON array inside each line item. This is the right pattern when a one-to-many relationship exists between a line record and another table - for example, one Sales Line can have multiple Sales Comment Lines.

How it works:

Set these fields on a Line-section template line:

At generation time, for each Sales Line VaultPDF filters Sales Comment Line where Document Line No. = Sales Line."Line No.", collects all matching records, and emits them as an array under lineComments.

Document-level arrays - when you want all records from a related table as a single array at the document level rather than nested per line, set Link Field ID = 0 and set a JSON Group. VaultPDF collects all records for the document (filtered from the header via its primary key) into one array item in lines[].

Example: Sales Comment Lines on a Sales Order

The default Sales templates include this pattern out of the box, producing:

{
  "lines": [
    { "headerComments": [
        { "Date": "2026-01-15", "Comment": "Please deliver before noon." }
      ]
    },
    {
      "No.": "ITEM-001",
      "Description": "Widget",
      "lineComments": [
        { "Date": "2026-01-15", "Comment": "Handle with care." }
      ]
    }
  ]
}

headerComments is a document-level array (Link Field ID = 0, JSON Group = headerComments) - all header-level comments for the order in one array. lineComments is per-line (Link Field ID = Sales Line Line No., Link Target Field ID = Sales Comment Line Document Line No., JSON Group = lineComments) - each Sales Line gets only its own comments.

Batch Filter Lines

Batch Filter Lines let you define per-template record filters that are applied automatically every time the template runs in batch mode. This replaces the need for users to manually filter the source record list before triggering a batch.

Access them via VaultPDF Templates → select a template → Batch Filters action (or the Batch Filters subpage on the Template Card).

Examples:

• Fixed status filter: A remittance advice template that should only process Open Payment Journal lines - Filter Field ID = Status, Filter Source = Fixed Value, Fixed Value = Open
• Current-month date filter: A nightly batch that should only process records posted this month - Filter Field ID = Posting Date, Filter Source = Date Formula, Fixed Value = CM (CM = current month in BC date formula notation)
• Prior-month date filter: A month-end run that processes only last month's records - Filter Field ID = Posting Date, Filter Source = Date Formula, Fixed Value = -1M..CM-1D (previous month start to last day of previous month)

Previewing Batch Configuration

Before committing to a full production batch run, use the Preview Batch action on the Template Card to verify that your Batch Filter Lines are selecting the right records and that your field mappings produce the expected output.

Action location: Template Card → action bar → Preview Batch (enabled only when the template has at least one variant with Dispatch Mode ≠ Standard)

How it works:

1. Click Preview Batch on an open Template Card
2. VaultPDF counts the records matching your current Batch Filter Lines and reports the count in a confirmation prompt
3. Confirm to download <TemplateCode>_preview.json - a sample JSON payload for the first matching group or record
4. Open the file to inspect the actual field values that would be dispatched

No documents are uploaded to SharePoint and no requests are sent to the Dispatcher. The preview runs the same filter logic and field-mapping pipeline as a real batch, so the JSON output is exactly what would be sent.

What to check in the preview file:

• Field values are populated (not blank or null) - blank values often indicate a misconfigured field mapping or missing data
• The header and lines sections contain the expected record structure
• Date fields are in the expected ISO format
• For Per Group mode, the group key value (e.g., vendor number) is correct

If Preview Batch reports 0 records, your Batch Filter Lines are too restrictive or the source table contains no matching rows. Adjust the filters and preview again before scheduling the batch.

Automation: Auto-Generate on Post

The Auto Generate on Post toggle (in the Dispatch section of Variant Settings) instructs VaultPDF to automatically queue a PDF generation request whenever a Business Central document from this template's source table is posted.

Requirements:

• Variant must have Dispatch Mode = Standard - batch modes are not supported for posting automation
• Variant must be Enabled
• A recurring Job Queue Entry for codeunit 77136 (VaultPDF Gen Processor) must be running

The posting subscriber fires after the posting transaction commits (OnAfterFinalizePosting), so a generation failure never rolls back a completed posting.

For full setup instructions, API integration patterns, and queue monitoring, see the Automated Document Generation guide.

Workflow Enforcement

When Template Type = Workflow and Workflow Enforcement Mode is set to Validate or Block, VaultPDF enforces document generation requirements at key BC operation points. Enforcement is wired into:

In Validate mode the user sees a warning dialog and can choose to proceed or cancel. In Block mode the operation throws an error and is prevented until the workflow reaches complete status.

Background sessions (Job Queue): enforcement always behaves as Block in headless context - there is no UI to show a warning dialog, so any pending or rejected workflow causes an error that stops the job.

To add enforcement for additional document types (Assembly Orders, Transfer Receipt, custom posting codeunits), or to bypass enforcement for specific records, see Workflow Enforcement in the Developer Guide.

Processing Documents

Once templates and settings are configured, end users and batch processes generate documents using the VaultPDF actions on standard Business Central pages.

Manual Document Processing

For documents in an active workflow, use the Sync Workflow Status action to refresh the workflow state from the REFRACT Platform engine. This action requires the VPDF-REVIEWER permission set or higher.

Batch Document Operations

Batch processing is triggered the same way as manual processing, but the selected variant must have a non-Standard Dispatch Mode.

VaultPDF iterates over the record set according to the mode:

• Per Group - Groups records by the configured field and generates one PDF per unique group value
• Per Record - Generates one PDF per record in the filtered set
• Single Array/Grouped Array - Combines all records into a single PDF payload

When the record count meets or exceeds the batch async threshold (default: 500), VaultPDF presents a choice: run immediately in the background, schedule for a specific date and time, or generate synchronously in the current session. See the Batch Operations tab in Template Configuration above for full details on execution options, job statuses, and monitoring. For recurring unattended runs (nightly, weekly, etc.) see Scheduled and Recurring Batch Jobs below.

Batch Render Log

The VaultPDF Batch Log Entries page records every successful batch PDF render for Single Array and Grouped Array dispatch modes. It gives finance and ops teams a permanent, searchable audit trail of what was generated, when, and by whom - without needing to open the Job Queue or Batch Jobs pages.

Access it via VaultPDF System Settings → View Batch Log, or search for VaultPDF Batch Log Entries in Tell Me.

What gets logged

A new entry is inserted automatically each time a batch render completes successfully. Only Single Array and Grouped Array dispatch modes write to this log - these are the modes that combine multiple records into a single array payload and dispatch it as one batch render request to the REFRACT Platform engine.

Per Group and Per Record modes are not logged here. Each render in those modes is a discrete, single-document request and is already traceable through standard Record Links on the source document.

Vault Lifecycle Workspace link

When the VAULTPDF_PORTAL_URL system setting is populated, each log entry shows a Vault Lifecycle Workspace link. Clicking it opens:

{VAULTPDF_PORTAL_URL}?batchId={Batch ID}

This navigates directly to the batch's document set in the REFRACT Platform portal - useful for reviewing render status, downloading PDFs, or checking workflow state for the entire batch in one view.

Synchronous vs. background logging

The log entry is inserted in both execution paths:

In both cases, User ID reflects the person who triggered the batch, not any background service account.

Scheduled and Recurring Batch Jobs

The execution options in the Template Gallery are document-context driven - they capture the page and record the user was viewing and apply any active list filters. For fully unattended, time-based batch runs (nightly remittance advice, weekly customer statements, end-of-month consolidations) use the Schedule Batch action on the Template Card instead.

Setting Up a Schedule

How Recurring Runs Differ from Ad-hoc Gallery Runs

Job Statuses

Every execution - whether one-time or recurring - creates a VaultPDF Batch Job Entry that passes through the same status lifecycle:

Retrying Failed Records

When a batch job completes with Partial status - some records succeeded and others failed - use the Retry Failed Records action on the VaultPDF Batch Jobs page to re-process only the failed detail lines without re-running the entire batch.

How to retry:

1. Open VaultPDF Batch Jobs from the Tell Me bar and locate the job with Partial status
2. Open the job entry and review the Record Details sub-list to see which records failed and what error each produced
3. Resolve any data issues indicated by the error messages (e.g., missing field values, connectivity problems)
4. Click Retry Failed Records in the action bar (the action is only enabled when Status = Partial)
5. Confirm the prompt - VaultPDF reprocesses only the detail lines marked Error, leaving successful lines untouched

After retry completes:

• Successfully reprocessed detail lines move to Completed
• If all errors are resolved, the parent job status becomes Completed
• Any remaining errors keep the job at Partial - retry as many times as needed

Monitoring and Managing the Schedule

Viewing run history:

Open VaultPDF Batch Jobs from the Tell Me bar and filter by Template Code. Each execution appears as its own row with independent status, timestamps, and (for Per Group / Per Record modes) a Record Details sub-list showing any per-record errors.

Rescheduling or changing the interval:

Use the Schedule Batch action on the Template Card again. If a recurring entry already exists for the template it is automatically replaced - no manual cleanup needed. The only restriction is that you cannot reschedule while the current run is In Process; wait for it to finish first.

Pausing without deleting:

1. Search for Job Queue Entries in Business Central
2. Filter by codeunit 77132 (VaultPDF Batch Job Runner) and Parameter String equal to the template code
3. Open the entry and set status to On Hold - the schedule is suspended until you set it back to Ready

Deleting a recurring schedule:

Delete the Job Queue Entry. Any VaultPDF Batch Job Entries already in progress are unaffected and complete normally. Historical entries remain and are not deleted.

Webhook Completion Notifications

VaultPDF can POST a JSON notification to any HTTP endpoint when an async batch job finishes. Use this to integrate with Slack, Microsoft Teams, monitoring systems, or custom dashboards without requiring a logged-in user.

Configuration

Navigate to VaultPDF System Settings and configure:

Both keys are created automatically by Initialize Default Keys.

Notification Payload

{
  "templateCode": "PAYMNT-ADV",
  "entryNo": 42,
  "status": "Partial",
  "statusMessage": "2 of 15 records failed. See VaultPDF Batch Jobs entry 42 for details.",
  "completedAt": "2026-06-21T08:00:00Z",
  "message": "VaultPDF Batch Job 42 (PAYMNT-ADV) completed with status: Partial."
}

Behavior Notes

• The webhook fires after the job runner writes the final status - all record processing is already complete at this point
• HTTP errors from the webhook endpoint are silently ignored - a webhook failure never causes a batch job to fail or be retried
• No retry on webhook delivery failure; if the endpoint is temporarily unavailable, that notification is lost
• For Teams or Slack incoming webhooks, point VAULTPDF_BATCH_NOTIFY_WEBHOOK_URL directly to the incoming webhook URL and set VAULTPDF_BATCH_NOTIFY_ON = Always to receive a notification for every run

AL Integration Event

Partners can subscribe to OnAfterSendCompletionNotification on codeunit 77132 (VaultPDF Batch Job Runner) to handle job completion in AL code without relying on HTTP:

[EventSubscriber(ObjectType::Codeunit, Codeunit::"VaultPDF Batch Job Runner",
  'OnAfterSendCompletionNotification', '', false, false)]
local procedure OnBatchJobComplete(BatchJobEntry: Record "VaultPDF Batch Job Entry")
begin
    if BatchJobEntry.Status = BatchJobEntry.Status::Failed then
        MyAlertMgt.SendUrgentAlert(
            BatchJobEntry."Template Code",
            BatchJobEntry."Status Message");
end;

This event fires after the HTTP webhook is attempted (or skipped). It receives the fully-populated VaultPDF Batch Job Entry record - Status, Template Code, Entry No., Status Message, and all timing fields are available.

Next Steps

• Automated Document Generation - Auto-generate on post, external API triggers, and queue monitoring
• Pre-built Templates & VaultPacks - Browse professionally-designed templates ready to import
• Developer Guide - Extend VaultPDF with custom AL code, events, and enums (advanced)
• Event Reference - Complete integration event and payload reference
• Troubleshooting Guide - Common issues and solutions