Troubleshooting - REFRACT Platform for Dynamics 365 Sales

Verify the Managed Solution Is Installed

1. Open Power Platform Admin Center
2. Select the target environment → Solutions
3. Confirm VaultPlatform D365 Sales is listed with status Installed

If the solution is not listed, import it from the solution file provided by Refract Logic.

Hard Refresh the Browser

1. Close all Dynamics 365 tabs
2. Open a new tab and navigate to Dynamics 365
3. Open a Quote or Opportunity record
4. Check for the Command Bar buttons

Command Bar customisations load from the server-side metadata cache. A hard refresh forces the browser to reload this cache.

Verify Command Bar in App Designer

If buttons are still missing after a hard refresh:

1. Open Power Apps (make.powerapps.com)
2. Select Apps → find and open the model-driven app your sales team uses (e.g. Sales Hub)
3. Click Edit → navigate to the relevant entity form (Quote, Opportunity, etc.)
4. In the Command Bar editor, confirm Vault actions are present

If buttons are missing from the App Designer, the managed solution may need reimporting into the correct environment.

Assign the Vault User Security Role

1. In Dynamics 365, navigate to Settings → Security → Users
2. Open the affected user's record
3. Click Manage Roles
4. Check the Vault User role and click OK

The role is included in the managed solution. If it does not appear in the role list, the solution may not be installed correctly.

Verify the Role Exists

1. Navigate to Settings → Security → Security Roles
2. Confirm Vault User appears in the list
3. If missing, reimport the managed solution - the role is delivered as part of the solution package

Sign Out and Sign Back In

Security role changes take effect after the user's next sign-in. Ask the affected user to sign out of Dynamics 365 and sign back in.

Confirm Templates Exist

1. Open Power Apps, select your environment, and navigate to Tables. Search for vault_template
2. Navigate to Templates
3. If the list is empty, create at least one template. See the main setup guide for steps.

Check Template Is Active

1. In the Templates list, confirm Is Active is Yes for the relevant template
2. Inactive templates are excluded from the gallery even if assigned

Verify Template Assignment

1. In Power Apps → Tables, open vault_templateassignment
2. Confirm an assignment exists for the relevant template with the correct Entity Logical Name

Example: For Quotes, the entity logical name is quote (all lowercase). If the assignment uses Quote or Quotes, it will not match.

Check Context Setting

1. On the Template Assignment record, confirm Context is set to form, view, or both
2. If Context = view and the user is on a record form, the template does not appear
3. Adjust the context to both to make the template available in all locations

Verify Dispatcher Environment Variables

1. In Power Platform Admin Center, open the environment → Solutions → VaultPlatform D365 Sales → Environment variables
2. Confirm all four Dispatcher variables are populated:
   • vault_dispatcher_baseurl
   • vault_dispatcher_tenantid
   • vault_dispatcher_clientid
   • vault_dispatcher_clientsecret

All four must have current values. An expired or missing vault_dispatcher_clientsecret is the most common cause of authentication failures.

Rotate the Dispatcher Client Secret

1. In Azure Portal, open App Registrations → the Dispatcher app registration
2. Click Certificates & Secrets
3. Check the Expires date on the secret in use
4. If expired, click New client secret - set expiry to 24 months and copy the Value
5. Update vault_dispatcher_clientsecret in Power Platform with the new value

Test Dispatcher Reachability

Ask your network or Azure team to confirm:

• The Dispatcher Function App is running
• Outbound HTTPS connections from Dataverse to the Dispatcher domain are allowed
• The Dispatcher base URL (vault_dispatcher_baseurl) is correct and reachable

Verify Graph Environment Variables

1. Confirm all four Graph variables are populated:
   • vault_graph_tenantid
   • vault_graph_clientid
   • vault_graph_clientsecret
   • vault_graph_driveid

An expired vault_graph_clientsecret or incorrect vault_graph_driveid causes 403 errors.

Check Azure AD App Permissions

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

If status shows "Needs admin consent":

1. Click Grant admin consent for [your tenant]
2. Confirm in the dialog

Verify the Drive ID

1. Use Microsoft Graph Explorer
2. Authenticate with your Azure AD account
3. Run: GET /sites/{siteId}/drives
4. Find the drive for your output document library and copy its id
5. Update vault_graph_driveid with this value

A Drive ID from the wrong library or a SharePoint site ID (not a drive ID) causes upload failures.

Verify Template Variant ID

1. In Power Apps → Tables, open vault_template and find the relevant template
2. Check the Template Variant ID field - this must match the exact filename/path used in the Vault template library
3. Confirm with your Refract Logic deployment contact that the template is published to SharePoint

Verify SharePoint Template Library Access

The same Graph API app registration must have read access to the templates library. Confirm Sites.ReadWrite.All is granted - this covers both read and write access.

Sync the Workflow Status

1. Open the blocked CRM record
2. Click [Sync Workflow Status] in the Command Bar
3. Check the dialog for the current workflow state

If the workflow is Complete, the enforcer will allow subsequent operations. If the workflow is still In Progress, the enforcer correctly blocks the operation until the workflow completes.

Check Enforcement Mode on the Template

1. In Power Apps → Tables, open vault_template
2. Find the template used to generate the document on this record
3. Check Workflow Enforcement Mode:
   • Block - CRM operation is prevented until workflow is complete
   • Validate - Warning is shown, but the operation is allowed to proceed
   • None - No enforcement

If enforcement mode is too restrictive for this use case, update it to Validate or None.

Clear a Stale Workflow Link

If a workflow was abandoned and the document link is blocking operations incorrectly, an administrator can update vault_documentlink.workflowState to complete directly in Dataverse (Advanced Find or a custom admin page). This releases the enforcer block.

Contact enterprise@vaultpdf.io if you need a supported admin utility for this operation.

Verify the Workflow Was Triggered

Workflow routing requires the template to have Workflow Enabled = Yes and at least one workflow recipient configured. If these were not set at generation time, no workflow was created - regenerate the document with a correctly configured template.

Check for Workflow Expiry

REFRACT Platform workflows expire after a configured period (default: 7 days for e-signature). If the workflow has expired, the Dispatcher discards the workflow instance.

Regenerate the document to initiate a new workflow.

Verify Recipient Configuration

1. In Power Apps → Tables, open vault_templaterecipient
2. Confirm at least one recipient has Recipient Type = Workflow and a valid email address
3. Check for typos in the email address

Check Dispatcher Workflow Logs

Contact enterprise@vaultpdf.io with:

• Document ID
• Timestamp of generation
• Recipient email address

Dispatcher logs reveal whether the workflow engine received the request and what the email delivery service returned.

Verify Template Assignment Context

1. In Power Apps → Tables, open vault_templateassignment
2. Find the assignment for the relevant entity
3. Confirm Context is set to view or both

Templates assigned with Context = form do not appear in list view batch operations.

Check Dispatch Mode

Only templates with Dispatch Mode set to Per Record or Single Array are meaningful for batch operations from a list view.

A Standard (single-record) template generates one document from the first selected record. If batch behaviour is expected, update the template's Dispatch Mode.

Reduce the Selection

Select 100 or fewer records and rerun the batch operation.

For large volumes, consider splitting the selection into multiple smaller batches or contacting enterprise@vaultpdf.io to discuss scheduled processing options for high-volume scenarios.

Adjust the Batch Threshold (Optional)

The 100-record limit is stored as a Dataverse Environment Variable. If the default threshold does not suit your deployment, contact your implementation team or enterprise@vaultpdf.io to adjust the threshold Environment Variable value.

Check for a Missing or Misconfigured Dispatcher URL

A wrong vault_dispatcher_baseurl will cause the connection to hang until Dataverse times out the operation.

1. Verify vault_dispatcher_baseurl is set correctly in Environment Variables
2. Confirm the Dispatcher Function App is running in Azure Portal
3. If the URL is correct but the Dispatcher is down, contact enterprise@vaultpdf.io with the error detail from the Plugin Trace Log

Check SharePoint Upload Performance

Slow SharePoint uploads are the most common cause of long execution times. Common causes:

• The SharePoint Drive ID points to a library in a different region from the Dataverse environment
• Transient Microsoft Graph throttling (HTTP 429)

If SharePoint uploads are consistently slow, contact enterprise@vaultpdf.io for guidance.

Enable Plugin Trace Logging

1. In Dynamics 365, navigate to Settings → Administration → System Settings
2. On the Customization tab, set Enable logging to plug-in trace log to All
3. Retry the failing action
4. Navigate to Settings → Plugin Trace Log to view error details

Common Plugin Errors

Always Use Managed Solution Imports for Upgrades

Upgrading by importing a new managed solution version preserves all existing Dataverse table data. The import process performs a schema upgrade, adding new columns or tables as needed.

Do not delete the solution before importing the new version - this removes all template configuration data.

Back Up Configuration Before Upgrading

Before importing a new solution version:

1. Export your template configuration as a Dataverse export or use Power Platform Dataflows
2. Document your Environment Variable values (except secrets)
3. Confirm with your implementation team that the new version is backward-compatible with existing template variant IDs