Troubleshooting - VaultPDF Business Central

Verify Permission Set Assignment

1. Open Users in Business Central
2. Find the affected user
3. Check the User Permission Sets section for one of:
   • VPDF-USER (minimum for any VaultPDF access)
   • VPDF-REVIEWER (for workflow status actions)
   • VPDF-ADMIN (for configuration and settings)

If none are present, add the appropriate permission set.

Clear Browser Cache and Restart

1. Close the Business Central browser tab
2. Clear your browser's cookies and cached files
3. Open Business Central in a new tab
4. Search for VaultPDF System Settings again

Permission changes can take a few minutes to propagate in the client cache.

Verify Permission Set Exists

If the permission set does not appear in the User Permission Sets lookup:

• Search for Permission Sets in the Tell Me bar (Alt+Q)
• Confirm VPDF-USER, VPDF-REVIEWER, and VPDF-ADMIN are listed with VaultPDF as the source extension
• If missing, the extension may not have installed correctly. Uninstall and reinstall the VaultPDF extension

Verify Dispatcher Credentials

1. Open VaultPDF System Settings
2. Check these keys are populated:
   • VAULTPDF_DISPATCHER_TENANT_ID
   • VAULTPDF_DISPATCHER_CLIENT_ID
   • VAULTPDF_DISPATCHER_CLIENT_SECRET

All three must have values, otherwise the Dispatcher cannot issue an OAuth token.

Rotate the Client Secret

1. In Azure Portal, open App Registrations → your app registration
2. Click Certificates & Secrets
3. Check if the secret in use has an Expires date in the past
4. If expired, create a new secret:
   • Click New client secret
   • Copy the Value (not the ID)
   • Set expiry to 24 months or longer

Update Business Central Settings

1. Return to Business Central and open VaultPDF System Settings
2. Click the VAULTPDF_DISPATCHER_CLIENT_SECRET row
3. Replace the old secret with the new value from Azure
4. Click OK

Rerun System Status Check

Click System Status Check again. If the PDF downloads, the connection is restored.

Verify Dispatcher Base URL

1. Verify the URL with your deployment team or contact enterprise@vaultpdf.io
2. Open VaultPDF System Settings
3. Click VAULTPDF_DISPATCHER_BASE_URL
4. Verify the URL matches exactly, e.g. https://func-vaultpdf.azurewebsites.net/api
5. Confirm no typos, trailing slashes, or extra spaces

Verify Host Key (Function Code)

1. Check VAULTPDF_DISPATCHER_CODE is populated
2. This is the Azure Function host key, provided by Refract Logic
3. If missing, contact the customer's deployment team or reach out to enterprise@vaultpdf.io

Test Connectivity from Business Central

1. Use System Status Check to verify the URL is reachable
2. If still failing, contact your network team to confirm:
   • Outbound HTTPS connections to the Dispatcher domain are allowed
   • No firewall rules block Microsoft Dynamics 365 to Azure Function calls

Check Azure AD App Registration Consent

1. In Azure Portal, open App Registrations → your app
2. Click API permissions
3. Look for Sites.ReadWrite.All (or your equivalent scope)
4. Confirm the status is Granted for your tenant (not "Needs admin consent")

If admin consent is needed, click Grant admin consent for your tenant and confirm.

Verify App Role Assignment

If your organization uses managed identities or role-based access control on the Dispatcher:

1. Contact your deployment team or enterprise@vaultpdf.io to confirm the app registration has the required roles assigned
2. Check that the app's object ID is registered in the Dispatcher's authentication policy

Confirm Templates Exist

1. Open VaultPDF Templates
2. If the list is empty, you must create at least one template first

See the main setup guide for steps to create a template.

Verify Source System Setting

1. Open VaultPDF System Settings
2. Check the value of VAULTPDF_SOURCE_SYSTEM, e.g. RefractLogic or BusinessCentral
3. In SharePoint, navigate to the templates document library
4. Confirm a folder exists at the root level with the same name

Example: If VAULTPDF_SOURCE_SYSTEM = "RefractLogic", SharePoint must have a folder named RefractLogic at the root of the templates drive.

Verify Template Drive Settings

1. Confirm VAULTPDF_GRAPH_TEMPLATES_DRIVE_ID is set to the Drive ID of the templates document library (not the output library)
2. Verify this is different from VAULTPDF_GRAPH_DRIVE_ID (the output library)

Verify Template Path in SharePoint

1. In SharePoint, navigate to the templates document library
2. Open the folder path: {SourceSystem}/{Module}/{TemplateId}
3. Confirm the template JSON file exists, e.g. MyTemplate.json

Check Graph Permissions on Template Library

1. The app registration must have read access to the templates drive
2. In Azure Portal, open App Registrations → your app → API permissions
3. Confirm Sites.ReadWrite.All is granted (this includes read access)

Check Template Field Mapping

1. Open the template in VaultPDF Templates
2. Verify all field references in the template match actual Business Central field names
3. Use the AL Lookup feature or Business Central's table inspector to confirm field names

Review Token Usage

If the template uses field tokens (field names in braces):

1. Ensure the token field exists in the source Business Central table
2. Token names are case-sensitive
3. Field references must match the exact field caption in Business Central

Verify Admin Consent

1. In Azure Portal, open App Registrations → your app
2. Click API permissions
3. Find Sites.ReadWrite.All → check status is Granted for your tenant

If status is "Needs admin consent":

1. Click the permission
2. Click Grant admin consent for your tenant
3. Confirm in the modal

Test SharePoint Connectivity

1. Use Microsoft Graph Explorer (https://developer.microsoft.com/graph/graph-explorer)
2. Authenticate with your Azure AD account
3. Run: GET /me/drive
4. Confirm you can access SharePoint drives
5. Run: GET /sites/{yourSiteId}/drives to list available drives

If these calls fail, SharePoint permissions are not correctly configured.

Verify Output Drive ID

1. In Microsoft Graph Explorer, run: GET /sites/{siteId}/drives
2. Identify the drive for your output document library
3. Copy its id field
4. In Business Central, update VAULTPDF_GRAPH_DRIVE_ID with this ID

Verify Folder Path in SharePoint

1. In SharePoint, navigate to the output document library
2. Check that the folder path exists: {SourceSystem}/{TableName}/{DocumentId}.pdf
3. If the folder does not exist, it was not created during upload

This suggests a permissions issue on the parent drive. Retry the upload and check the detailed error in the Upload Log.

Check Upload Log

1. Open VaultPDF System Settings
2. Click View Upload Log
3. Find the most recent entry for your document
4. Check the Status and Error Details columns

Verify Token Syntax

Token format is: double braces around the field name with no spaces, e.g. FieldName → token becomes FieldName in braces.

Correct formats: No., Sell-to Customer Name Incorrect formats: No. (spaces), No. (single braces), or backslash escapes

Confirm Field Exists

1. Open the source document table in Business Central
2. Use the AL table inspector or Development Tools
3. Verify the exact field name matches your token

Example: If your token references approverEmail, verify that a field named approverEmail exists on the header table.

Test the Template

1. Generate a test document using the template
2. Open the Upload Log and view the JSON payload that was sent to the Dispatcher
3. Confirm the workflow.message field shows the correct values, not literal tokens

Verify Workflow Settings

On the template's Template Settings page:

1. Confirm Workflow Enabled is toggled ON
2. Confirm Workflow Recipients table has at least one row with an email address
3. Confirm the email addresses are valid and reachable

Check Dispatcher Logs

Contact your deployment team or enterprise@vaultpdf.io to review the Dispatcher logs for your tenant. Provide:

• Document ID
• Timestamp of document generation
• Template ID

Logs reveal whether the Dispatcher received the workflow request and what happened during processing.

Sync Workflow Status

On the generated document:

1. Click the VaultPDF action group
2. Click Sync Workflow Status
3. Check if the workflow status updates to "In Progress" or "Completed"

If the status does not update, the Dispatcher does not have a record of the workflow. Regenerate the document and confirm settings are correct.

Verify eSign Configuration

On the template's Template Settings page:

1. Confirm eSign Enabled is toggled ON
2. Confirm Signers table has at least one row
3. Confirm each signer has a valid email address

Check Email Delivery

1. Ask the signer to check their spam and junk email folders
2. Verify the signer's email address is spelled correctly in the template
3. Confirm the email address is active and monitored

Review Dispatcher eSign Logs

Contact your deployment team or enterprise@vaultpdf.io for dispatcher logs. Include:

• Document ID
• Signer email address
• Timestamp of document generation

Logs reveal whether the Dispatcher attempted to send invitations and what email service returned.

Verify Portal URL

1. Open VaultPDF System Settings
2. Check VAULTPDF_PORTAL_URL is set correctly, e.g. https://portal.vaultpdf.com
3. Confirm the URL is reachable from the signer's network

Check Link Expiry

1. On the template, verify eSign Expiry (minutes)
2. If set to 0, the default is 10,080 minutes (7 days)
3. If the signer received the link more than 7 days ago, it has expired
4. Regenerate the document and send a new signing link

Verify Group By Field

On the template's Template Settings page:

1. Confirm Dispatch Mode is set to Per Group
2. Confirm Group By Field ID is populated with a valid field ID
3. The field ID should be a Business Central field number from the source table

Example: To group sales invoices by customer, set Group By Field ID to the field ID for the customer field (e.g., 3 for Bill-to Customer No.).

Test the Field

1. Open the source Business Central table
2. Confirm the field exists and contains values
3. If unsure of the field ID, click the field lookup in template settings

Check Upload Log

1. Open VaultPDF System Settings
2. Click View Upload Log
3. Filter by timestamp to find entries from your batch operation
4. Look for entries with Status = Failed and review Error Details

Review Common Batch Failures

Common reasons for partial batch failures:

• Some records have missing or invalid data that does not map to template fields
• Some records have token fields that are empty (tokens remain literal)
• SharePoint upload rate-limiting caused some uploads to timeout

For each failed record, check the error details and correct the data before retrying.

Check the Threshold Key

1. Open VaultPDF System Settings
2. Locate VAULTPDF_BATCH_ASYNC_THRESHOLD
3. Confirm the value is a positive integer (e.g. 500)
4. If the value is blank, non-numeric, or larger than your typical batch size, update it to a suitable number

The background prompt only appears when the record count is greater than or equal to this value.

Check Job Queue Entries

1. Search for Job Queue Entries in the Tell Me bar
2. Find the entry for VaultPDF Batch Job Runner
3. Confirm the entry status is Ready and not On Hold
4. If on hold, open the entry and click Set Status to Ready

Confirm a Worker Is Scheduled

1. In Job Queue Entries, verify at least one entry is scheduled to run and not blocked
2. If no workers are active, contact your Business Central administrator to restart the Job Queue

Read the Status Message

1. Search for VaultPDF Batch Jobs in the Tell Me bar
2. Locate the failed entry by job number or timestamp
3. Open the entry and read the Status Message field - it contains the full error detail

Resolve the Error and Retry

Common causes include missing template fields, invalid Group By Field configuration, or Dispatcher connectivity issues. Resolve the reported error, then re-trigger the batch from the Template Gallery.

Review Record-Level Errors

1. Search for VaultPDF Batch Jobs and open the Partial job entry
2. Open the Record Details sub-list to see which records failed and the error message for each
3. Common per-record errors: missing required field values, invalid document numbers, SharePoint rate limiting

Fix the Data and Retry

Correct the data issue on the failing source records. Then use Retry Failed Records in the action bar - it reprocesses only the failed detail lines without re-running successful records.

Retry Failed Records is available for Per Record and Per Group dispatch modes only. For Single Array or Grouped Array, re-run the full batch from the Template Gallery after fixing the data.

Verify the Webhook URL Setting

1. Open VaultPDF System Settings
2. Confirm VAULTPDF_BATCH_NOTIFY_WEBHOOK_URL is set to a valid HTTPS URL with no trailing spaces
3. Test the URL independently (e.g. use a service like webhook.site to verify the endpoint is reachable from Business Central's outbound network)

Check the Notification Filter

1. Open VaultPDF System Settings
2. Check VAULTPDF_BATCH_NOTIFY_ON - if it is FailureOnly (the default), the webhook only fires for Partial and Failed jobs
3. If you expect notifications for every completed job, set the value to Always

Check for Silent Webhook Errors

Webhook HTTP errors are silently ignored by design - a failed webhook delivery never surfaces as a BC error. If the endpoint is temporarily unavailable or returns a non-2xx response, the notification is lost for that run. Verify the endpoint's own logs to confirm whether the request arrived.

Add the Portal URL Setting

1. Open VaultPDF System Settings in Business Central
2. Locate the VAULTPDF_PORTAL_URL key (or click Initialize Default Keys if it is missing)
3. Enter your REFRACT Platform portal base URL, e.g. https://portal.vaultpdf.com
4. Click OK

New batch renders will immediately show the Vault Lifecycle Workspace link. Existing rows without a stored Batch ID will remain blank.

Check Dispatcher Version

Contact your deployment team or enterprise@vaultpdf.io to confirm the deployed Dispatcher version supports the x-vaultpdf-batchid response header. Provide the timestamps of the affected batch renders so the team can correlate with Dispatcher logs.

Verify Portal URL Is Configured

1. Open VaultPDF System Settings
2. Confirm VAULTPDF_PORTAL_URL has a value, e.g. https://portal.vaultpdf.com

If the portal URL is missing, no rows will show the link - regardless of whether a Batch ID was stored.

Use Background Execution

For batches at or above the async threshold (default: 500 records), VaultPDF automatically offers to run the batch as a background Job Queue entry. Accept the prompt to offload processing from your browser session entirely.

If the prompt does not appear, check that VAULTPDF_BATCH_ASYNC_THRESHOLD in VaultPDF System Settings is set to a value at or below your batch size. See Batch job stuck on Queued if the job does not start after queuing.

Optimize Batch Size

If background execution is not available or you must run synchronously:

1. Split the batch into smaller operations (e.g., 25 documents each)
2. Run each batch separately with a few minutes between them
3. This avoids hitting Business Central's request timeout

Simplify Template

1. Review the template schema for unnecessary fields or complex conditional logic
2. Contact your deployment team or enterprise@vaultpdf.io to optimize template rendering performance

Monitor Dispatcher Queue

Contact your deployment team or enterprise@vaultpdf.io if batch operations consistently time out. The Dispatcher may be experiencing high load and processing your request slower than expected.

Confirm the Source Record Is an Open Purchase Order

The PURCH-3WAY subscriber only processes records from Database::"Purchase Header" (table 38 - open orders). It does not process Posted Purchase Orders (table 122).

Verify the template is triggered from an open Purchase Order page, not a Posted Purchase Order or Archive.

Verify Receipt and Invoice Links

The subscriber links receipt lines via Order No. + Order Line No. on Purch. Rcpt. Line and Purch. Inv. Line.

Run these queries in a BC query tool or AL debugger to confirm data exists:

• Purch. Rcpt. Line where Order No. = <your PO number> and Order Line No. = <line no.>
• Purch. Inv. Line where Order No. = <your PO number> and Order Line No. = <line no.>

If these return no rows but receipts/invoices were posted, the posting may have originated from a different order number or via a manual invoice not linked to the order.

Open Company Information in Business Central and fill in the Address, City, Post Code, and Country/Region Code fields. Re-generate the document.