Configuration

Most of VerseDocs needs no configuration at all. This page covers the few things you can change: which tables show the Generate document button, who can see usage, and what leaves your tenant.

The VerseDocs Admin app

The app ships inside the managed solution — you do not build it, add pages to it, or wire anything up. Open the maker portal, go to Apps, and open VerseDocs Admin.

App navigation

VerseDocs
├── Authoring
│   └── Template Studio    author, validate and preview templates
└── Administration
    ├── Configuration      which tables show the Generate document button
    ├── Usage              the vdocs_usage table, Recent Calls view, dashboards
    └── Licensing          license status, buy, activate, telemetry, feedback

If you want your own variant — extra pages, your own branding, a different navigation — copy the app rather than editing it in place. Editing a managed app introduces an unmanaged customisation layer that complicates future VerseDocs updates.

Enabling the Generate document button

The button ships switched off for every table. Turning it on is a tick box, and it takes effect on the next form load — there is nothing to publish and nothing is written into your table’s own ribbon.

1Open VerseDocs Admin → Administration → Configuration.
2Tick each table that should offer document generation.
3Save. Reload a form or grid for one of those tables and the Generate document button is there.

The button is defined once on the All Entities ribbon, and its enable rule reads this setting per table at runtime. That is why enabling a table requires no publish, and why uninstalling VerseDocs cleanly removes the button from every table — it never lived in your customisations. The setting itself is stored in the vdocs_EnabledRibbonTables environment variable.

The button appears in the form’s Save group rather than Actions. That is deliberate: on a typical compiled ribbon the Actions group renders far enough right that a button placed there lands in the … overflow at ordinary window widths.

Security roles

VerseDocs ships three security roles. Assign one of them to anyone who will generate documents or author templates — without one, the Generate document button’s template picker is empty, because the template catalogue is a custom table that no built-in role can read.

Role	For	Grants
VerseDocs User	Anyone who generates documents from a record or a list.	Read on the template catalogue, and nothing else. No access to the admin app.
VerseDocs Template Author	Whoever writes and maintains templates.	Create, read and update templates, plus Template Studio. Cannot delete a template, and cannot change licensing or configuration.
VerseDocs Administrator	Whoever owns licensing and configuration.	Everything above, plus deleting templates, the usage dashboard, licensing, and which tables offer the button.

A Template Author still needs read access to the tables their templates are bound to, through their own existing role. VerseDocs deliberately does not grant privileges on your business tables — an ISV solution handing itself access to customer data is exactly what a security review should reject.

Why Template Author cannot delete. Deactivating a template retires it while keeping the provenance stamp on every document already generated from it resolvable. Deleting breaks that trail. Authors deactivate; administrators delete.

Beyond these roles, VerseDocs adds no security model of its own. Every action runs as the calling user and is subject to that user’s existing Dataverse privileges — a user who cannot read an account cannot generate a document from it, whatever role they hold.

To do this	A user needs
Call any `vdocs_*` action	Nothing beyond whatever role already lets them use Power Apps or Power Automate with the Dataverse connector. Custom APIs are actions, not table operations, so no table privilege gates the call itself.
Generate a document from a record	Read on that record, and Create on Note (annotation) if the result is attached to the timeline.
See the usage dashboard	Read on `vdocs_usage`. The table is Organization-owned; typically only admins need this.
Author templates in Template Studio	Create, Read, Write on `vdocs_template`.
Activate a license key	Privilege to write environment variable values, or an admin to paste the key for them.

Environment variables

All of these ship unset. In normal operation you will only ever touch the first two.

Variable	Purpose
`vdocs_LicenseKey`	Your license key. See Licensing.
`vdocs_EnabledRibbonTables`	Which tables show the Generate document button. Managed for you by the Configuration page — edit it there, not by hand.
`vdocs_TelemetryOptOut`	Set to `true` to stop telemetry. Equivalent to the toggle on the Licensing page.
`vdocs_TelemetryEndpoint`	Where telemetry, registration and feedback are sent. Ships unset, and while it is unset none of those three actions send anything anywhere.
`vdocs_RegisteredCompanyName`	Company name recorded by `vdocs_Register`. Optional.
`vdocs_RegisteredContactEmail`	Contact email recorded by `vdocs_Register`. Optional.
`vdocs_LicensingBaseUrl`	The licensing service base URL. Ships with a working default; only change it if VerseBlocks support asks you to.
`vdocs_EnableExportPdfDocument`	Leave unset. See below.
`vdocs_DebugForceConversionFailure`	Diagnostic only. Forces the PDF conversion ladder to fall through, for support investigations. Never set this in production.

Never export a solution from an environment with these values set and give the zip to someone else. A solution export bakes the source environment’s environment-variable values into the package — including your license key.

PDF conversion: nothing to configure

vdocs_ConvertToPdf, and any templating call with "outputFormat":"pdf", produce a real PDF out of the box. The conversion engine is compiled into the plug-in package. There is no OneDrive step, no Graph permission, no managed identity and no per-tenant configuration.

The response’s Meta.engine names which renderer actually ran, which is useful when comparing fidelity across documents.

vdocs_EnableExportPdfDocument

This gates an additional Dataverse-internal conversion path. Leave it unset. It was investigated and found to be the wrong tool for converting an arbitrary customer .docx: it is a Dynamics Word-template mail-merge export rather than a general converter, and it rejects a template-free document before conversion is attempted. It remains in the ladder as an off-by-default rung that always falls through, but enabling it will not do anything useful.

Telemetry, registration and feedback

Three actions can send information to VerseBlocks. All three are separate Custom APIs that only run when something explicitly calls them — none of them run as part of generating or converting a document.

Action	Sends	Runs when
`vdocs_SendTelemetry`	Org id, tenant id, license edition, template count, and call counts by action and by month, read from the vdocs_usage table this environment already keeps.	A flow you set up, or the admin app.
`vdocs_Register`	Your company name and a contact email.	You submit the form.
`vdocs_SubmitFeedback`	A free-text message you typed.	You send it.

Telemetry never sends document content, file names, template content, or field values.

To turn telemetry off: use the toggle on the Licensing page, or set vdocs_TelemetryOptOut to true.
To send nothing at all, ever: leave vdocs_TelemetryEndpoint unset. With no endpoint configured, none of the three actions transmit anything.

Template StudioCreate your first template.Generating from a recordUse the button you just enabled.