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.
- 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:SHOWundprimedocs:showsind gleichwertig. &trennt Befehle,=trennt Name und Wert.- Schalter wirken durch ihre Anwesenheit. Ein Schalter wie
hiddenodershowbraucht 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 Integrationenprimedocs: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). |
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.
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.
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.
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.
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.