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 REFRACT Platform for 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 REFRACT actions are present

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

Assign the REFRACT 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 REFRACT 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 REFRACT 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 refract_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 refract_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 → REFRACT Platform for D365 Sales → Environment variables
2. Confirm all five Dispatcher variables are populated:
   • refract_dispatcher_baseurl
   • refract_dispatcher_tenantid
   • refract_dispatcher_clientid
   • refract_dispatcher_clientsecret
   • refract_dispatcher_scope (api://<dispatcher-app-client-id>/.default)

All five must have current values. refract_dispatcher_clientid must be the Dynamics 365 Sales connector app's client ID, not the client ID of "REFRACT Dispatcher API". An expired or missing refract_dispatcher_clientsecret is the most common cause of authentication failures.

Rotate the Dispatcher Client Secret

1. In Azure Portal, open App Registrations → the Dynamics 365 Sales connector app
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 refract_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 (refract_dispatcher_baseurl) is correct and reachable

Verify Graph Environment Variables

1. Confirm all four Graph variables are populated:
   • refract_graph_tenantid
   • refract_graph_clientid
   • refract_graph_clientsecret
   • refract_graph_driveid

An expired refract_graph_clientsecret or incorrect refract_graph_driveid causes 403 errors.

Check Azure AD App Permissions

1. In Azure Portal, open App Registrations → REFRACT SharePoint Access
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 refract_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 refract_template and find the relevant template
2. Check the Template Variant ID field - this must match the exact filename/path used in the REFRACT 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 refract_template
2. Find the template used to generate the document on this record
3. Check Workflow Enforcement Mode:
   • Block - CRM operation is prevented with an error until workflow is complete
   • Validate - Also prevented with an error. A Dataverse pre-operation plugin cannot show a dismissible warning and then let the save continue, so Validate behaves the same as Block today
   • None - No enforcement

If enforcement is unwanted for this use case, only None disables the block; Validate will not help.

This only applies to Quote and Opportunity - the enforcement plugin has no registered step for any other entity, regardless of what enforcement mode a template on another entity specifies.

Clear a Stale Workflow Link

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

Contact sales@refractlogic.com 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 refract_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 sales@refractlogic.com 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.

Check for a Missing or Misconfigured Dispatcher URL

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

1. Verify refract_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 sales@refractlogic.com 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 sales@refractlogic.com 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