Protokollhandler

primedocs registriert bei der Installation den Windows-URL-Protokollhandler primedocs:. Damit lässt sich der installierte primedocs Desktop Client aus einer beliebigen Anwendung heraus aufrufen — über einen Link in einer Web- oder Fachapplikation, eine Verknüpfung, ein Skript oder «Ausführen» (Win+R). Ein typischer Anwendungsfall ist der Connect-Aufruf aus einer Webapplikation: Die Webseite öffnet primedocs:… und übergibt als Parameter eine URL auf eine API, welche die Connect-Datei liefert.

Voraussetzungen

• Der Protokollhandler gehört zum primedocs Desktop Client (Windows). Er startet die lokal installierte primedocs.exe — nicht die Web-App oder ein Office-Add-in.
• Der Client muss installiert sein. Die Registrierung erfolgt automatisch beim Setup (siehe Registrierung).

Aufbau eines Aufrufs

Ein Aufruf besteht aus dem Protokoll-Präfix primedocs:, gefolgt von einem oder mehreren durch & getrennten Befehlen. Ein Befehl ist entweder ein Schalter (nur der Name) oder ein Schlüssel-Wert-Paar (name=wert):

primedocs:<befehl>[&=<wert>&…]

Beispiel — neues Dokument aus einer Vorlage, Fenster versteckt:

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

Regeln:

• Präfix und Namen sind case-insensitiv. primedocs:SHOW und primedocs:show sind gleichwertig.
• & trennt Befehle, = trennt Name und Wert.
• Schalter wirken durch ihre Anwesenheit. Ein Schalter wie hidden oder show braucht keinen Wert — steht er im Aufruf, gilt er als gesetzt.
• Werte werden URL-dekodiert. Sonderzeichen in Pfaden und URLs müssen daher prozentkodiert werden (siehe Werte korrekt kodieren).
• Führendes Verb. Die Beispiele (und die interne Verwendung) beginnen oft mit einem Verb wie open. Der Handler wertet ausschliesslich die unten aufgeführten Namen aus; ein unbekanntes führendes Verb dient nur der Lesbarkeit und wird ignoriert. Das eigentliche Verhalten ergibt sich aus den gesetzten Befehlen.
• Legacy-Präfix. Aus Kompatibilitätsgründen wird zusätzlich oneoffixx: als Präfix akzeptiert und identisch behandelt. Für neue Integrationen primedocs: verwenden.

Befehle

Fenster und Anwendung

Befehl	Typ	Wirkung
show	Schalter	Bringt das Hauptfenster des laufenden Clients in den Vordergrund bzw. zeigt die Shell an.
hidden	Schalter	Startet den Client, ohne das Hauptfenster anzuzeigen (versteckt die Shell). Bei einer laufenden Instanz wird das Fenster ausgeblendet.
silent	Schalter	Unterdrückt den Splashscreen.
shutdown	Schalter	Beendet primedocs.
clean	Schalter	Beendet primedocs und löscht den lokalen Cache (ESENT-Cache).

Dokument erstellen

Befehl	Typ	Wirkung
new	GUID	Erstellt ein neues Dokument auf Basis der Vorlage mit der angegebenen Template-ID.
profileid	GUID	Wählt das angegebene Profil vor.
dlcid	Ganzzahl (LCID)	Dokumentsprache als Windows-LCID (z.B. 2055 für Deutsch (Schweiz), 2057 für Englisch (GB)).
outputurl	URL/Pfad	Zielort, an dem das erzeugte Dokument gespeichert wird (z.B. ein SharePoint-Speicherpfad).

Connect

Diese Befehle stossen einen Connect-Lauf an. connect bezieht sich auf das aktuelle primedocs-Connect-Format, connector auf das Legacy-Format.

Befehl	Typ	Wirkung
connect	URL/Pfad	Pfad oder URL zu einer primedocs-Connect-Datei.
keepconnect	Schalter	Löscht die Connect-Datei nach der Verarbeitung nicht.
connector	URL/Pfad	Pfad oder URL zur (Legacy-)Connector-XML.
keepconnector	Schalter	Löscht die Connector-Datei nach der Verarbeitung nicht.
validateconnector	Schalter	Validiert die Connector-Datei vor der Ausführung.
interfacetype	Text	Definiert das Format der Connector-XML.
interfaceversion	Text	Definiert die Version der Connector-XML.
createconnectorresult	Schalter	Schreibt eine XML-Datei mit dem Resultat des Connect-Aufrufs.
createconnectorresultonerror	Schalter	Schreibt die Resultat-XML nur bei einem Fehler (standardmässig aktiv).
silentconnectorerror	Schalter	Unterdrückt Fehlermeldungen während der Connect-Ausführung.
showerrormessages	true/false	Zeigt bei einem Fehler einen Fehlerdialog an (Standard: true).

URL-Quellen freigeben

Wird bei connect oder connector statt eines Dateipfads eine URL angegeben, muss diese in primedocs Admin (DataSourceAdminApp) unter Connect Settings → Connect – Remote Policies freigegeben werden. Details und HTTP-Header (z.B. Authentifizierung) unter Dokumentgenerierung starten.

tipp

Mehrere Befehle lassen sich frei kombinieren, z.B. primedocs:open&new=<GUID>&profileid=<GUID>&dlcid=2055&hidden.

Beispiele

Neues Dokument aus einer bestimmten Vorlage erstellen:

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

Laufenden Client in den Vordergrund holen:

primedocs:show

Client im Hintergrund vorstarten (ohne Fenster und ohne Splashscreen):

primedocs:hidden&silent

Connect-Lauf aus einer Webapplikation anstossen — die URL zeigt auf eine API, welche die Connect-Datei liefert (URL prozentkodiert):

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

Legacy-Connector über einen lokalen Pfad (Backslashes prozentkodiert):

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

Werte korrekt kodieren

Da & und = als Trennzeichen dienen, müssen Werte, die diese oder weitere Sonderzeichen enthalten, prozentkodiert (URL-encoded) werden. Das betrifft insbesondere URLs mit Query-Parametern und Windows-Pfade:

Zeichen	Kodiert
\ (Backslash)	%5C
:	%3A
/	%2F
?	%3F
&	%26
=	%3D

Wird eine unkodierte URL wie connect=https://host/get?token=x&foo=bar übergeben, interpretiert der Handler foo=bar als eigenen Befehl und schneidet den Wert ab. Bei connect und connector werden zusätzlich umschliessende doppelte Anführungszeichen (") automatisch entfernt.

HTTPS-Startlink

Manche Systeme akzeptieren in Links ausschliesslich http/https und lassen primedocs:-Links nicht zu — etwa SharePoint. Für diesen Fall stellt primedocs Web die Seite /web/launch bereit: Sie übersetzt die Query eines HTTPS-Links in einen primedocs:-Aufruf und löst ihn im Browser aus.

https://{instanz}/app/web/launch?<befehle>

Die Query wird unverändert als Befehlsliste übernommen — es gelten dieselben Befehle wie oben. Beispiel für ein neues Dokument aus einer Vorlage:

https://{instanz}/app/web/launch?open&new=6f9619ff-8b86-d011-b42d-00cf4fc964ff

Verhalten der Seite:

• Sie ist ohne Anmeldung erreichbar und lässt sich damit auch in Systemen hinterlegen, die keine primedocs-Sitzung haben.
• Der Aufruf wird beim Laden automatisch ausgelöst. Die Seite bleibt sichtbar und bietet «Erneut ausführen» an — hilfreich, wenn der Browser den Protokollaufruf blockiert oder eine Rückfrage unbeantwortet blieb.
• Je nach Browser und Einstellung erscheint zuerst eine Rückfrage, ob die Anwendung geöffnet werden darf.
• Enthält die Query keinen Befehl, meldet die Seite «Ungültiger Link».
• Ist der Desktop Client nicht installiert, passiert nichts; die Seite weist auf die fehlende Installation hin.

Kodierung: In der HTTPS-Query gelten die normalen Regeln für Links — Werte einmal prozentkodieren, wie in jeder URL. Die Umwandlung in den Protokollaufruf kodiert die Werte anschliessend selbst korrekt; Schalter ohne Wert bleiben Schalter.

Befehle werden nicht eingeschränkt

Die Seite reicht die Befehle unverändert weiter und prüft sie nicht. Damit sind alle oben aufgeführten Befehle möglich — auch solche, die den Client beenden (shutdown) oder den Cache löschen (clean). Startlinks entsprechend sorgfältig zusammenstellen.

Registrierung

Das Setup registriert die Protokolle pro Benutzer unter HKEY_CURRENT_USER\Software\Classes:

Schema	Zweck
primedocs	Aktuelles Protokoll.
oneoffixx	Legacy-Alias, identisches Verhalten.

Jeder Schlüssel enthält den Wert URL Protocol sowie unter shell\open\command den Aufruf:

"<Installationspfad>\primedocs.exe" /uri "%1"

Das Betriebssystem übergibt den vollständigen Aufruf (%1) als Argument /uri. Reagiert ein Client nicht auf Links, lässt sich anhand dieses Registry-Schlüssels prüfen, ob die Registrierung vorhanden ist und auf die korrekte primedocs.exe zeigt.

Kommandozeile

Dieselben Optionen stehen auch als Kommandozeilen-Schalter (mit /-Präfix) zur Verfügung, z.B. primedocs.exe /connect C:\Temp\pdconnect.xml /keepConnect true. Der Protokollhandler ist damit im Kern eine URL-Form dieser Argumente.

Separates Anmelde-Protokoll

Für den SSO-Anmelde-Rückruf registriert primedocs ein eigenes Schema (oneoffixx-winappauth). Dieses dient ausschliesslich der Authentifizierung und ist nicht Teil des hier beschriebenen Dokument-Protokollhandlers.