Aufruf
Dateiendungen
Zwei Dateiendungen sind in Windows mit dem OneOffixx-Client bereits verknüpft:
| Dateiendung | Beschreibung |
|---|---|
| .oocx | Beinhaltet Connect-konformes XML und wird von OneOffixx 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 Connect-Datei wird nach der Verarbeitung nicht gelöscht. |
| .ooconnect | Legacy: gleich wie .oocx |
Clientseitiger Aufruf über Konsole
Falls unstrukturiertes XML für den Aufruf verwendet wird, muss OneOffixx über die Konsole parametrisiert aufgerufen werden:
.../OneOffixx.exe /connector "<path to xml file>" /interfaceType "<interface name in XML-Transformer>"
Caution
OneOffixx 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.
Note
Eine falsche oder nicht existierende Template-Id führt zu einem Fehler.
Important
Der TemplatePicker wird asynchron ausgeführt. Er sollte nur verwendet werden, wenn nur genau ein Eintrag im Batch vorhanden ist.
Aufruf über den DocumentCreationServer (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.
Caution
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 OneOffixx-Shell
.../OneOffixx.exe /CreateConnectorResult /interfaceType "ContosoInterface"
Note
Die Gross-/Kleinschreibung wird beim Argumentnamen ignoriert.
Mögliche Argumente sind:
| Argument | Typ | Beschreibung |
|---|---|---|
| ActivateAddIn | string | Aktiviert das angegebene (ProgID) OneOffixx-AddIn. |
| Clean | - | OneOffixx 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 OneOffixx 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 | - | OneOffixx beenden |
| Silent | - | Unterdrückt den Startbildschirm. |
| Uri | string | Windows Protocol URI. Beispiel: oneoffixx:hidden. |
| ValidateConnector | - | Die Connector-Datei wird vor dem Ausführen validiert. |
| Argument | Parameter | Beschreibung | Windows-Befehle (WIN+ R) | HTML-Link | Shell |
|---|---|---|---|---|---|
| Clean | - | OneOffixx 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 OneOffixx ohne die Shell zu zeigen. Die Anwendung wird nicht sichtbar gestartet. Der Startbildschirm wird beim ersten Start angezeigt, wenn OneOffixx 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 | - | OneOffixx beenden | ✓ | ✓ | ✓ |
| Silent | - | Unterdrückt den Startbildschirm. | ✓ | ✓ | ✓ |
| Help | - | Zeigt die Hilfe an. | X | X | ✓ |
| ActivateAddIn | string | Aktiviert das angegebene (ProgID) OneOffixx-AddIn. | |||
| Uri | string | Windows Protocol URI. Beispiel: oneoffixx: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 OneOffixx, wird standardmässig ein Protokoll-Handler mitinstalliert. Der Protokoll Handler erlaubt es, dass OneOffixx direkt über einen Link im Browser aufgerufen werden kann.
<a href="oneoffixx:show">Zeige/Öffne OneOffixx Client</a>
<a href="oneoffixx:hidden">Verstecke OneOffixx Client</a>
<a href="oneoffixx:new=1d93046c-b3a2-4e96-ab5f-5b9b60afa86e">Öffne Vorlage mit ID 1d93046c-b3a2-4e96-ab5f-5b9b60afa86e</a>