Developer Guide - REFRACT Platform for Dynamics 365 Sales

Integration Architecture

The REFRACT Platform for Dynamics 365 Sales uses a native server-side processing layer within Dataverse. Each Command Bar action routes through a Custom Dataverse API to server-side logic that builds the document payload, uploads it to SharePoint, and calls the REFRACT Dispatcher.

Dispatcher Contract

The Dispatcher is source-agnostic. It is a pure request-response service with four operations, and it only reads and writes SharePoint.

The Dispatcher never calls back to Dynamics 365. There is no push, no webhook, and no write to Dataverse. All state updates in CRM happen when a CRM user explicitly triggers an action - pull model throughout.

Action Summary

Each Command Bar button routes to a dedicated Custom Dataverse API. The table below describes what each action does and when to use it.

Dataverse Custom Tables

The managed solution installs six custom tables. All table names are prefixed with refract_.

refract_template

Stores template definitions - one row per template.

refract_templatefield

Stores field mappings for each template - one row per mapped field.

refract_templateassignment

Controls which templates appear on which entities and contexts.

refract_templatesigner

Stores e-signature signer configuration per template. Fields reference CRM field logical names resolved at generation time - they are not hardcoded email addresses.

refract_templaterecipient

Stores delivery and workflow recipient configuration per template. Recipients can be either dynamic (resolved from the CRM record) or static (hardcoded email address).

refract_documentlink

The runtime document link table. One row per generated document per record per link type.

Write rules:

Link type policy: A record can hold one standard link and one workflow link simultaneously. A new standard document never deletes a workflow link, and vice versa. The latest document of each type overwrites the previous.

Custom APIs

The solution includes eight Custom Dataverse APIs. The four command actions are invoked by Command Bar buttons. The four admin APIs are intended for one-time or periodic administrative use.

Command Actions

Admin APIs

refract_InitializeDefaults parameters:

refract_ValidateSettings outputs:

Workflow Enforcement

A pre-operation plugin checks whether a pending workflow should block or warn before certain CRM operations complete. It reads the last-known workflow state saved on the record - it never calls the Dispatcher directly. If a user has not recently synced the workflow status, enforcement acts on the most recently saved state.

Enforcement modes (configured per template):

Suggested Enforcement Triggers by Entity

Enforcement mode (Block / Validate / None) is configured per template and stored in refract_documentlink.enforcementMode at the time of document generation.

Batch Dispatch Modes

The Dispatcher detects the operation mode from the payload schema. The plugin code is identical for single and batch operations - both call POST /render and receive a PDF buffer in response.

For batch operations, the Dispatcher accepts the job, immediately generates and returns an Intake Receipt PDF as acknowledgment, then processes the batch asynchronously and writes results to SharePoint. The CRM user receives the Intake Receipt immediately - the same hand-in-hand experience as a single record operation.

Initial release scope:

Batch Safety Thresholds

Thresholds are stored as Dataverse Environment Variables and can be adjusted per customer without a solution update.

Managed Solution Contents

RefractPlatform_D365Sales (Managed Solution)
├── Dataverse Tables (6)
│   ├── refract_template
│   ├── refract_templatefield
│   ├── refract_templateassignment
│   ├── refract_templatesigner
│   ├── refract_templaterecipient
│   └── refract_documentlink
├── Custom Dataverse APIs (8)
│   ├── refract_ProcessDocument         - Command Bar action
│   ├── refract_OpenDocument            - Command Bar action
│   ├── refract_SyncWorkflowStatus      - Command Bar action
│   ├── refract_GetSealedDocument       - Command Bar action
│   ├── refract_BrowseSharePointFolder  - Admin: browse template library
│   ├── refract_ImportTemplate          - Admin: import .vpdf from SharePoint
│   ├── refract_InitializeDefaults      - Admin: seed default templates (8 entities)
│   └── refract_ValidateSettings        - Admin: check environment variable config
├── Web Resources
│   ├── refract_/scripts/refract_actions.js    - Command Bar button handlers
│   ├── refract_/scripts/refract_gallery.js    - Template gallery + progress dialog
│   ├── refract_/scripts/refract_browser.js    - Template browser + import dialog
│   ├── refract_/stylesheets/refract_gallery.css
│   ├── refract_/stylesheets/refract_browser.css
│   ├── refract_/pages/refract_gallery.html
│   └── refract_/pages/refract_browser.html
├── Command Bar Customisations (8 entities)
│   ├── quote, opportunity, account, contact
│   ├── salesorder, invoice, incident, lead
│   └── Buttons: [Process Document] [Open Document] [Sync Workflow Status] [Get Signed Document]
├── Security Roles
│   └── REFRACT User
└── Environment Variables (12)
    ├── refract_graph_tenantid
    ├── refract_graph_clientid
    ├── refract_graph_clientsecret           (secret)
    ├── refract_graph_driveid                (output document library)
    ├── refract_graph_templatesdriveid       (templates library)
    ├── refract_graph_templatessourcefolder  (folder path within templates library)
    ├── refract_dispatcher_baseurl
    ├── refract_dispatcher_tenantid
    ├── refract_dispatcher_clientid
    ├── refract_dispatcher_clientsecret      (secret)
    ├── refract_batchwarningthreshold        (default: 25)
    └── refract_batchmaxthreshold            (default: 100)

Deployment and ALM