Aufruf
Dateiendungen
Zwei Dateiendungen sind in Windows mit dem primedocs-Client bereits verknüpft:
| Dateiendung | Beschreibung |
|---|---|
| .oocx | Beinhaltet OneOffixx Connect-konformes XML und wird von primedocs direkt (ohne Rückfrage) ausgeführt. Die Datei wird – sofern im XML nicht anders definiert – nach der Dokumenterstellung gelöscht. |
| .oock | Gleich wie .oocx, das k steht aber für keep. Die OneOffixx Connect-Datei wird nach der Verarbeitung nicht gelöscht. |
Clientseitiger Aufruf über Konsole
Falls unstrukturiertes XML für den Aufruf verwendet wird, muss primedocs über die Konsole parametrisiert aufgerufen werden:
...\primedocs.exe /connector "<path to xml file>" /interfaceType "<interface name in XML-Transformer>"
Als path to xml file kann ein Dateipfad oder eine URL angegeben werden.
Wenn eine URL angegeben wird, muss diese zuvor über die Connect Remote Policies im Admin-Dashboard freigegeben werden. Bei Verwendung einer URL wird die Einstellung keepConnect ignoriert.
WICHTIG
primedocs löscht nach der Verarbeitung automatisch die Connect-Datei. Wird das zusätzliche Argument /keepConnector übergeben, kann dieses Verhalten unterdrückt werden. Wird via Shell aufgerufen, dann muss die Dateiendung ".oock" verwendet werden.
TemplatePicker
Falls keine oder keine eindeutige Vorlage im XML für den Aufruf definiert wurde, dann erscheint der TemplatePicker. Das passiert, wenn
- keine Template-Id und kein Tag-Filter gesetzt sind
- oder der Tag-Filter mehr als ein Resultat zurückgibt.
HINWEIS
Eine falsche oder nicht existierende Template-Id führt zu einem Fehler.
WICHTIG
Der TemplatePicker wird asynchron ausgeführt. Er sollte nur verwendet werden, wenn nur genau ein Eintrag im Batch vorhanden ist.
Aufruf über den Document Creation Server (DCS)
Um über den DCS ein Dokument zu erstellen, muss die Connect-API angesprochen werden. Diese kann unter {ServerAddress}/connect/api/v1/connect aufgerufen werden. Mit {ServerAddress}/connect/ kann die allgemeine Beschreibung der API eingesehen werden. Die API nimmt als Body ein Connect-XML entgegen. Die Anmeldung am Server funktioniert über die Basic Authentication mit dem Format username:password als Base64-String. Benutzername und Passwort entsprechen dem Eintrag "basicAuth" in der serverseitigen OneOffixx.config.
ACHTUNG
Auf dem DCS kann kein unstrukturiertes XML verarbeitet werden. Es muss zwingend ein Connect-XML mitgesendet werden. Ebenfalls gibt es für den DCS keinen TemplatePicker. Ein Aufruf über den DCS muss also immer alle Informationen betreffend Vorlagen eindeutig im Connect-XML enthalten.
Resultat
Über Commands können einzelne Dokumente (oder im Fall der Batch-Verarbeitung das Endresultat als Ganzes) konvertiert oder gespeichert werden. Im Fall des Server-Aufrufs wird bei erfolgreicher Ausführung als Response auf den API-Call immer das fertige Dokument zurückgeliefert. Bei nicht erfolgreicher Verarbeitung wird der Server, abhängig von der Schwere des aufgetretenen Fehlers, einen 400-Bad-Request oder einen 500-Internal-ServerError Statuscode zurückgeben. Aus Sicherheitsgründen werden bei dieser Response in den meisten Fällen keine Details mitgeliefert. Diese müssen im Server Log der Connect-API eingesehen werden (über das Dashboard, oder direkt auf dem Dateisystem des Servers).
Im Fall der Batch-Verarbeitung muss das Merge-Command auf Batch-Ebene zwingend angegeben werden. Ist dies nicht angegeben, so wird der Server mit Statuscode 400-Bad-Request und der Fehlermeldung, dass das Merge-Command angegeben werden muss, antworten.
Beispiel Aufruf über DCS (mit Batch-Verarbeitung)
POST /{ServerFolder}/connect/api/v1/connect HTTP/1.1
Host: {ServerAddress}
Content-Type: text/xml
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
User-Agent: PostmanRuntime/7.15.0
Accept: */*
Cache-Control: no-cache
Postman-Token: 5c37ad5f-0ba0-464c-b0cc-33db5d46ce3d,05f57e43-dc8e-4a3e-a57c-a121f50a71f5
Host: {ServerAddress}
accept-encoding: gzip, deflate
content-length: 1004
Connection: keep-alive
cache-control: no-cache
<?xml version="1.0" encoding="utf-8"?>
<OneOffixxConnectBatch xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schema.oneoffixx.com/OneOffixxConnectBatch/1">
<Commands>
<Command Name="Merge">
<Parameters>
<Add key="PageNumberStart">10</Add>
</Parameters>
</Command>
<Command Name="ConvertToDocument" />
<Command Name="DefaultProcess">
<Parameters>
<Add key="Start">true</Add>
</Parameters>
</Command>
<OnCancel>
<Command Name="CreateConnectorResult" />
</OnCancel>
</Commands>
<Entries>
<OneOffixxConnect>
<Arguments>
<TemplateId>52945b6c-b65a-436d-8045-619e4e41af51</TemplateId>
</Arguments>
</OneOffixxConnect>
<OneOffixxConnect>
<Arguments>
<TemplateId>52945b6c-b65a-436d-8045-619e4e41af51</TemplateId>
</Arguments>
</OneOffixxConnect>
</Entries>
</OneOffixxConnectBatch>
Aufruf der primedocs-Shell
.../primedocs.exe /CreateConnectorResult /interfaceType "ContosoInterface"
HINWEIS
Die Gross-/Kleinschreibung wird beim Argumentnamen ignoriert.
Mögliche Argumente sind:
| Argument | Typ | Beschreibung |
|---|---|---|
| ActivateAddIn | string | Aktiviert das angegebene (ProgID) primedocs-AddIn. |
| Clean | - | primedocs beenden und den Cache löschen |
| Connector | string | Dateipfad auf Connector-XML |
| CreateConnectorResult | - | Erstellt eine XML-Datei mit dem Resultat des Connector-Aufrufs. |
| CreateConnectorResultOnError | - | Erstellt eine XML-Datei mit dem Resultat des Connector-Aufrufs beim Auftreten eines Fehlers. |
| DatasourceId | guid | ID der Datenquelle, die verwendet werden soll |
| DLCID | int | Auswahl der Dokumentsprache |
| ForceRestart | int | Neustart erzwingen |
| Help | - | Zeigt die Hilfe an. |
| Hidden | - | Startet primedocs ohne die Shell zu zeigen. Die Anwendung wird nicht sichtbar gestartet. Der Startbildschirm wird beim ersten Start angezeigt. |
| InterfaceType | string | Definiert das Format des Connector-XML. |
| InterfaceVersion | string | Definiert die Version des Connector-XML. |
| KeepConnector | - | Die Connector-Datei wird nicht automatisch gelöscht. |
| New | guid | Öffnet ein Dokument in Abhängigkeit einer bestimmten Vorlage. Parameter: Template-Id als GUID. |
| OutputUrl | string | Speicherpfad für Dokumente, die im SharePoint gespeichert werden sollen |
| ProfileId | guid | Vorgewählte ProfileID |
| Show | - | Ob der Client angezeigt werden soll |
| Shutdown | - | primedocs beenden |
| Silent | - | Unterdrückt den Startbildschirm. |
| Uri | string | Windows Protocol URI. Beispiel: primedocs:hidden. |
| ValidateConnector | - | Die Connector-Datei wird vor dem Ausführen validiert. |
| Argument | Parameter | Beschreibung | Windows-Befehle (WIN+ R) | HTML-Link | Shell |
|---|---|---|---|---|---|
| Clean | - | primedocs beenden und den Cache löschen | ✓ | ✓ | ✓ |
| Connector | string (Pfad zu XML-File) | Dateipfad auf Connector-XML | ✓ | X | ✓ |
| InterfaceType (Zusätzliches Argument für Connector) | string (Name des Interfaces) | Definiert das Format des Connector-XML. | |||
| KeepConnector (Zusätzliches Argument für Connector) | - | Die Connector-Datei wird nicht automatisch gelöscht. | |||
| InterfaceVersion (Zusätzliches Argument für Connector) | string (Versionsnummer) | Definiert die Version des Connector-XML. | |||
| CreateConnectorResult (Zusätzliches Argument für Connector) | - | Erstellt eine XML-Datei mit dem Resultat des Connector-Aufrufs. | |||
| CreateConnectorResultOnError (Zusätzliches Argument für Connector) | - | Erstellt eine XML-Datei mit dem Resultat des Connector-Aufrufs beim Auftreten eines Fehlers. | |||
| Hidden | - | Startet primedocs ohne die Shell zu zeigen. Die Anwendung wird nicht sichtbar gestartet. Der Startbildschirm wird beim ersten Start angezeigt, wenn primedocs beendet ist, wenn es geöffnet ist wird das Fenster gschlossen. | ✓ | ✓ | ✓ |
| New | guid GUID der Vorlage | Öffnet ein Dokument in Abhängigkeit einer bestimmten Vorlage. Parameter: Template-Id als GUID. | ✓ | ✓ | ✓ |
| ProfileId (Zusätzliches Argument für New) | guid GUID des Profils | Vorgewählte ProfileID | |||
| DLCID (Zusätzliches Argument für New) | int LCID-Nummer | Auswahl der Dokumentsprache | |||
| Show | - | Ob der Client angezeigt werden soll | ✓ | X | ✓ |
| DatasourceId (Zusätzliches Argument für Show) | guid GUID der DataSource | ID der Datenquelle, die verwendet werden soll | |||
| Shutdown | - | primedocs beenden | ✓ | ✓ | ✓ |
| Silent | - | Unterdrückt den Startbildschirm. | ✓ | ✓ | ✓ |
| Help | - | Zeigt die Hilfe an. | X | X | ✓ |
| ActivateAddIn | string | Aktiviert das angegebene (ProgID) primedocs-AddIn. | |||
| Uri | string | Windows Protocol URI. Beispiel: primedocs:hidden. | |||
| ValidateConnector | - | Die Connector-Datei wird vor dem Ausführen validiert. | |||
| ForceRestart | int | Neustart erzwingen | |||
| OutputUrl | string | Speicherpfad für Dokumente, die im SharePoint gespeichert werden sollen |
Aufruf über den Protokoll-Handler
Bei der Installation von primedocs, wird standardmässig ein Protokoll-Handler mit installiert. Der Protokoll Handler erlaubt es, dass primedocs direkt über einen Link im Browser aufgerufen werden kann.
<a href="primedocs:show">Zeige/Öffne primedocs Client</a> <br />
<a href="primedocs:hidden">Verstecke primedocs Client</a> <br />
<a href="primedocs:new=1d93046c-b3a2-4e96-ab5f-5b9b60afa86e">Öffne Vorlage mit ID 1d93046c-b3a2-4e96-ab5f-5b9b60afa86e</a> <br />
<a href="primedocs:clean">Cache zurücksetzen</a> <br />