Protocol Handler

During installation, primedocs registers the Windows URL protocol handler primedocs:. It lets any application invoke the installed primedocs Desktop Client — from a link in a web or line-of-business application, a shortcut, a script, or the Run dialog (Win+R). A typical use case is a Connect call from a web application: the page opens primedocs:… and passes a URL to an API that returns the Connect file.

Prerequisites

• The protocol handler belongs to the primedocs Desktop Client (Windows). It launches the locally installed primedocs.exe — not the web app or an Office add-in.
• The client must be installed. Registration happens automatically during setup (see Registration).

Anatomy of a call

A call consists of the protocol prefix primedocs: followed by one or more commands separated by &. A command is either a switch (name only) or a key-value pair (name=value):

primedocs:<command>[&=<value>&…]

Example — create a new document from a template, with the window hidden:

primedocs:open&new=6f9619ff-8b86-d011-b42d-00cf4fc964ff&hidden

Rules:

• Prefix and names are case-insensitive. primedocs:SHOW and primedocs:show are equivalent.
• & separates commands, = separates name and value.
• Switches take effect by their presence. A switch such as hidden or show needs no value — if it appears in the call, it is considered set.
• Values are URL-decoded. Special characters in paths and URLs must therefore be percent-encoded (see Encode values correctly).
• Leading verb. The examples (and the internal usage) often begin with a verb such as open. The handler only evaluates the names listed below; an unknown leading verb is purely for readability and is ignored. The actual behaviour is determined by the commands that are set.
• Legacy prefix. For compatibility, oneoffixx: is also accepted as a prefix and treated identically. Use primedocs: for new integrations.

Commands

Window and application

Command	Type	Effect
show	Switch	Brings the running client's main window to the front, or shows the shell.
hidden	Switch	Starts the client without showing the main window (hides the shell). For a running instance, the window is hidden.
silent	Switch	Suppresses the splash screen.
shutdown	Switch	Quits primedocs.
clean	Switch	Quits primedocs and clears the local cache (ESENT cache).

Create a document

Command	Type	Effect
new	GUID	Creates a new document based on the template with the given template ID.
profileid	GUID	Pre-selects the given profile.
dlcid	Integer (LCID)	Document language as a Windows LCID (e.g. 2055 for German (Switzerland), 2057 for English (UK)).
outputurl	URL/path	Target location where the generated document is saved (e.g. a SharePoint save path).

Connect

These commands trigger a Connect run. connect refers to the current primedocs Connect format, connector to the legacy format.

Command	Type	Effect
connect	URL/path	Path or URL to a primedocs Connect file.
keepconnect	Switch	Does not delete the Connect file after processing.
connector	URL/path	Path or URL to the (legacy) connector XML.
keepconnector	Switch	Does not delete the connector file after processing.
validateconnector	Switch	Validates the connector file before execution.
interfacetype	Text	Defines the format of the connector XML.
interfaceversion	Text	Defines the version of the connector XML.
createconnectorresult	Switch	Writes an XML file with the result of the Connect call.
createconnectorresultonerror	Switch	Writes the result XML only on error (enabled by default).
silentconnectorerror	Switch	Suppresses error messages during Connect execution.
showerrormessages	true/false	Shows an error dialog on error (default: true).

Approve URL sources

If a URL (rather than a file path) is used for connect or connector, it must be approved in primedocs Admin (DataSourceAdminApp) under Connect Settings → Connect – Remote Policies. For details and HTTP headers (e.g. authentication), see Start Document Generation.

tip

Multiple commands can be combined freely, e.g. primedocs:open&new=<GUID>&profileid=<GUID>&dlcid=2057&hidden.

Examples

Create a new document from a specific template:

primedocs:open&new=6f9619ff-8b86-d011-b42d-00cf4fc964ff

Bring the running client to the front:

primedocs:show

Pre-start the client in the background (no window, no splash screen):

primedocs:hidden&silent

Trigger a Connect run from a web application — the URL points to an API that returns the Connect file (URL percent-encoded):

primedocs:connect=https%3A%2F%2Fapp.example.com%2Fapi%2Fconnect%3FdocId%3D4711

Legacy connector via a local path (backslashes percent-encoded):

primedocs:connector=C%3A%5CTemp%5Cpdconnect.xml&keepconnector

Encode values correctly

Because & and = act as separators, values that contain these or other special characters must be percent-encoded (URL-encoded). This applies in particular to URLs with query parameters and to Windows paths:

Character	Encoded
\ (backslash)	%5C
:	%3A
/	%2F
?	%3F
&	%26
=	%3D

If an unencoded URL such as connect=https://host/get?token=x&foo=bar is passed, the handler interprets foo=bar as a separate command and truncates the value. For connect and connector, surrounding double quotes (") are additionally removed automatically.

Registration

Setup registers the protocols per user under HKEY_CURRENT_USER\Software\Classes:

Scheme	Purpose
primedocs	Current protocol.
oneoffixx	Legacy alias, identical behaviour.

Each key holds the URL Protocol value and, under shell\open\command, the call:

"<installation path>\primedocs.exe" /uri "%1"

The operating system passes the full call (%1) as the /uri argument. If a client does not respond to links, this registry key can be used to check whether the registration exists and points to the correct primedocs.exe.

Command line

The same options are also available as command-line switches (with a / prefix), e.g. primedocs.exe /connect C:\Temp\pdconnect.xml /keepConnect true. The protocol handler is essentially a URL form of these arguments.

Separate sign-in protocol

For the SSO sign-in callback, primedocs registers its own scheme (oneoffixx-winappauth). It is used solely for authentication and is not part of the document protocol handler described here.