Nach der Dokumentgenerierung (Commands)

---

Nach der eigentlichen Dokumentgenerierung können Commands (Befehle) aufgerufen werden. Gewisse Commands können nur im Erfolgsfall (OnSuccess) verwendet werden.

Zugriff auf das Ergebnis

Es gibt zwei Arten von Ergebnissen einer Dokumentgenerierung:

• <Document />: Dieses Document-Element ist das eigentliche Ergebnis nach der Dokumentgenerierung, welches das Word, PowerPoint, Excel oder auch die externe Datei beinhaltet.
  Dieses Element ist nur im Erfolgsfall, d.h. im OnSuccess verfügbar!
• <Report />: Der Report ist eine Abbild des Zustands der Dokumentgenerierung bzw. der Zustand der Abarbeitung der Commands.
  Bei einem Abbruch der Generierung oder in einem Fehlerfall, kann der Report genutzt werden um die Fehlerinformation an das aufrufende System weiterzugeben.

Commands müssen das Ergebnis explizit angeben, d.h. entweder muss Document oder Report konfiguriert sein.

Dokument

Das Document enthält das eigentliche Resultat der Dokumentgenerierung und kann nur im OnSuccess-Fall genutzt werden.

Konvertierung zu PDF

Um das Dokument in ein PDF umzuwandeln, gibt es ein extra Attribut:

<Document Conversion="..." />

warnung

Aktuell wird die Conversion nur für Word-Vorlagen unterstützt!

Ein Dokument kann entweder Microsoft Office konvertiert werden:

<Document Conversion="PdfViaOffice" />

… oder über den in primedocs integrierten PDF Konverter:

<Document Conversion="Pdf" />

Report

Der Report ist insbesondere für Fehler oder manuelle Abbrüche der Generierung geeignet.

Allerdings steht der Report in allen Fällen (OnSuccess, OnError, OnCancel, OnExit) zur Verfügung.

Wichtig: Initial erhält der Report den Status der Dokumentgenerierung. Danach wird jeder definierte Command nach der Reihe abgearbeitet und jeder Command beeinflusst daraufhin den Report.

Der Report selbst ist eine XML-Datei, welche folgende Struktur aufweisst:

<primedocsConnectReport>
  <Status>Error</Status>
  <Input>
    <File>C:\Temp\ConnectFile.pdck</File>
  </Input>
  <CreatedOnUtc>...</CreatedOnUtc>
  <Message><![CDATA[Something failed due to ....

Overview
========
  --> [exception #1] System.ExampleException1: An error occurred while ...
    --> [exception #2] System.ExampleException2: Unable to ...]]>
    </Message>
</primedocsConnectReport>

• Status: Der Status kann folgende Werte beinhalten:
  • OK: Keine Fehler, die Dokumentgenerierung oder alle Commands bis zu diesem Punkt liefen erfolgreich durch.
  • Cancelled: Dieser Status tritt auf, wenn der Benutzer die Dokumentgenerierung abbricht.
  • Error: Fehler bei der Dokumentgenerierung oder falls ein vorangegangener Command fehlt schlug.
• Input & File: Wenn primedocs über eine primedocs Connect Datei aufgerufen wird, dann enthält dieses Element den Dateipfad dieser Datei.
• CreatedOnUtc: Zeitangabe, wann der Report erstellt wurde.
• Message: Beinhaltet Meldungen des Reports.

Dynamische Parameter

Connect Commands können über ihre jeweiligen Attribute bzw. Elementen mit Werten ausgestattet werden, so z.B. kann man den Speicherpfad bei SaveFile angeben:

<SaveFile FileName="\\MyServer\share\organisation\...\Letter.docx" ...

Möchte man allerdings den Pfad oder Dateinamen dynamisch zusammenbauen, kann man über das field-Attribut auf die Felder der Dokumentgenerierung (“User”, “Forms”, “Field”, “Data” etc.) zugreifen.

<SaveFile field-FileName="SavePath" ...

Der Einsatz hier ist nur exemplarisch. Nicht jedes Attribut oder Element unterstützt den Zugriff auf Felder.

Grundsätzlich:

• Attribute, welche den Zugriff auf Felder unterstützen sind in dem Stil benannt:
  • Attribut="statischer Wert" bzw. field-Attribut="FeldName"
• Elemente, welche den Zugriff auf Felder unterstützen sind in diesem Stil benannt:
  • <Element>statischer Wert</Element> bzw. <Element field-Content="FeldName" />

warnung

Der Zugriff auf die Felder funktioniert nur im OnSuccess-Fall.

Commands

Die folgende Tabelle führt alle verfügbaren Commands auf und zeigt, in welchen Umgebungen sie verfügbar sind: im Desktop-Client, in primedocs Web (inkl. Office Web Add-Ins, Connect Sessions und WebOutput) und über die API — die reine serverseitige Generierung via Connect/Document API.

Übersicht

Command	Beschreibung	Desktop	Web	API
SaveFile	Speichert das Dokument am angegebenen Zielort im angegebenen Format.	✓	–	–
OpenFile	Öffnet Office-Dateien mit dem Standardprozess, der in Windows für den Dateityp registriert ist.	✓	–	–
OpenDocumentInOffice	Öffnet das generierte Dokument direkt in der Office-Anwendung.	✓	–	–
InvokeProcess	Ruft eine externe Anwendung auf. Aus Sicherheitsgründen muss der Prozess vorher konfiguriert werden.	✓	–	–
InvokeUrl	Sendet die Datei bzw. den Report an einen HTTP/HTTPS-Endpunkt. Aus Sicherheitsgründen muss die Ziel-URL vorher konfiguriert werden.	✓	✓	✓
ShowDialog	Zeigt dem Benutzer einen Dialog mit Titel, Meldung und optionalem Button/Link an.	✓	✓	–
DownloadFile	Stellt das Dokument bzw. den Report als Datei-Download bereit.	–	✓	–

Verfügbarkeit

• Nur Desktop: SaveFile, OpenFile, OpenDocumentInOffice und InvokeProcess greifen auf das lokale System zu und stehen nur im Desktop-Client zur Verfügung.
• Desktop & Web: ShowDialog zeigt dem Benutzer einen Dialog an — im Desktop-Client und in primedocs Web. DownloadFile ist auf primedocs Web beschränkt.
• API (serverseitige Generierung): Über die Connect/Document API wird das Dokument direkt an den Aufrufer zurückgegeben. Von den Commands steht hier nur InvokeUrl (serverseitiger HTTP-Aufruf) zur Verfügung; interaktive bzw. client-/web-spezifische Commands wie ShowDialog, DownloadFile oder SaveFile wirken in der serverseitigen Generierung nicht.
• Web umfasst auch die Ausführung von Connect Sessions (/{sessionId}/Execute der Connect Session API) sowie die WebOutput-/WebSeriesOutput-Ausgabe.
• Commands lassen sich in allen Handler-Gruppen (OnSuccess, OnExit, OnError, OnCancel) verwenden — Commands mit <Document /> jedoch nur im OnSuccess.

Beschreibungen

SaveFile

Desktop

Der SaveFile-Command speichert das Dokument am angegebenen Zielort.

Attribute:

• FileName: Absoluter Pfad mit Dateiendung
• field-FileName: Alternative zu FileName um dynamische Pfade über die Felder zu ermöglichen.
• Overwrite: True/False; gibt an, ob eine bestehende Datei überschrieben werden soll.
• CreateFolder: True/False; gibt an, ob Ordner, die im Filename angegeben sind, erstellt werden sollen.

Elemente:

• Document oder Report: Siehe Abschnitt “Zugriff auf das Ergebnis”

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <SaveFile FileName="\\MyServer\share\organisation\...\Letter.docx"
                Overwrite="true"
                CreateFolder="true">
        <Document />          
      </SaveFile>
    </OnSuccess>
  </Commands>
</primedocsConnect>

OpenFile

Desktop

Der OpenFile-Command öffnet Office-Dateien mit dem Standardprozess, der in Windows für den Dateityp registriert ist. Beispielsweise wird die generierte Datei an einem bestimmten Dateiort gespeichert und soll hinterher im Word weiterbearbeitet werden.

Attribute:

• FileName: Absoluter Pfad mit Ziel-Dateiendung
• field-FileName: Alternative zu FileName um dynamische Pfade über die Felder zu ermöglichen.

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <SaveFile FileName="\\MyServer\share\organization\...\Letter.docx"
                Overwrite="true"
                CreateFolder="true">
          <Document />
      </SaveFile>
      <OpenFile FileName="\\MyServer\share\organization\...\ShortLetter.docx" />      
    </OnSuccess>
  </Commands>
</primedocsConnect>

OpenDocumentInOffice

Desktop

Der OpenDocumentInOffice-Command öffnet das generierte Dokument direkt in der Office-Anwendung, ohne dass es zuvor gespeichert werden muss.

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <OpenDocumentInOffice />      
    </OnSuccess>
  </Commands>
</primedocsConnect>

InvokeProcess

Desktop

Der InvokeProcess-Command ruft eine externe Anwendung auf. Aus Sicherheitsgründen müssen im Dashboard die zulässigen Applikationen zuerst whitelisted werden. Die Konfiguration dafür kann unter Settings → Connect Settings → InvokeProcess - Configuration gefunden werden und sieht ansatzweise wie folgt aus:

<CommandConfig>
    <Process name="OurSystemNotepad" executablePath="%systemroot%/notepad.exe" />
    <Process name="..." executablePath="..." />
</CommandConfig>

Der Aufruf in der Connect-Datei muss mit dem Namen einer zuvor im Dashboard freigegebenen Applikation übereinstimmen.

Attribute:

• Name: Konfigurierter Prozessname

Elemente:

• Arguments: Argumente für den Prozessaufruf
• Arguments mit field-Content: Alternative zu Arguments. Erlaubt es auf Feldwerte zuzugreifen.

Der Aufruf kann optional Argumente enthalten und sieht folgendermassen aus:

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <InvokeProcess Name="OurSystemNotepad">
          <Arguments>...</Arguments>
          <!-- or -->
          <Arguments field-Content="FieldName" />
      </InvokeProcess>    
    </OnSuccess>
  </Commands>
</primedocsConnect>

InvokeUrl

Desktop Web API

Der InvokeUrl-Command sendet die Datei bzw. den Report an einen HTTP/HTTPS Endpunkt. Aus Sicherheitsgründen müssen im Dashboard die zulässigen Applikationen zuerst whitelisted werden. Die Konfiguration dafür kann unter Settings → Connect Settings → InvokeUrl - Configuration gefunden werden und sieht ansatzweise wie folgt aus:

<CommandConfig>
    <Url startsWith="https://example1.com" />
    <Url startsWith="https://example2.com/subfolder" />
</CommandConfig> 

Grundsätzlicher Aufbau:

Im InvokeUrl können HTTP-Requests als Schritte (Step) definiert werden.
Ein Step besteht aus einem Request bzw. MultipartFormDataRequest und optional einer Response.

Der Aufbau ist ähnlich dem HttpDataProvider, allerdings kann über den MultipartFormDataRequest das Document bzw. der Report an einen Endpunkt gesendet werden.

Der Command arbeitet alle Step-Elemente in der definierten Reihenfolge ab. Ein Step hat keine weiteren Attribute.

Authentifizierung über einen Connected Service:

Mit dem optionalen Attribut ConnectedServiceKey am InvokeUrl-Element wird der HTTP-Aufruf über einen Connected Service authentifiziert (OAuth-2.0-Access-Token). Ist der Schlüssel gesetzt und der Benutzer in primedocs Web noch nicht am Dienst angemeldet, zeigt die Web App vor der Ausführung einen Anmelde-Hinweis.

hinweis

ConnectedServiceKey steht nicht über die Connect/Document API (reine serverseitige Generierung) zur Verfügung, da diese ohne angemeldeten Benutzer-Kontext (Client Credentials) läuft. Für Szenarien mit Connected-Service-Authentifizierung die Connect Session (/Execute) verwenden, die im Kontext des angemeldeten Benutzers ausgeführt wird.

<InvokeUrl ConnectedServiceKey="MSGraph">
  <Step>
    ...
  </Step>
</InvokeUrl>

Request-Element:

• Attribute:
  • Method: Angabe der HTTP Methode (POST, GET, etc.)
• Elemente:
  • Url: Angabe der Ziel URL, welche aus Sicherheitsgründen im Dashboard konfiguriert werden muss.
  • Url mit field-Content: Alternative zu Url. Erlaubt es auf Feldwerte zuzugreifen.
  • Body: Angabe des HTTP Bodies.
  • Body mit field-Content: Alternative zu Body. Erlaubt es auf Feldwerte zuzugreifen.
  • Header: Liste von HTTP Headern aus Key und Value bzw. field-Value

MultipartFormDataRequest-Element:

• Elemente:
  • Url: Angabe der Ziel URL, welche aus Sicherheitsgründen im Dashboard konfiguriert werden muss.
  • Url mit field-Content: Alternative zu Url. Erlaubt es auf Feldwerte zuzugreifen.
  • Header: Liste von HTTP Headern aus Key und Value bzw. field-Value
  • FormData: Liste von FormData Elementen aus Key und Value bzw. field-Value
  • File: Übergabe der eigentlichen Datei als multipart/form-data Request.
    • Attribute:
      • Name: Optionaler Name - abhängig vom Serverendpunkt. Die binären Daten werden als multipart/form-data unter diesem Namen in den Request serialisiert.
      • FileName: Optionaler Dateiname.
      • field-FileName: Alternative zu FileName um dynamische Namen über die Felder zu ermöglichen.
    • Elemente:
      • Document oder Report: Siehe Abschnitt “Zugriff auf das Ergebnis”

Response-Element:

• Elemente:
  • Property: Abrufen bestimmter Daten aus dem Ergebnis des HTTP Requests.
    • Attribute:
      • Name: Name der Eigenschaft. Über den {PropertyName} Syntax kann man in einem darauffolgenden Request auf diesen Wert zugreifen.
      • JsonPath: Über den JsonPath wird der Wert der Eigenschaft ermittelt. Hierbei muss die HTTP Antwort ein valides JSON sein.
      • XPath: Über den XPath wird der Wert der Eigenschaft ermittelt. Hierbei muss die HTTP Antwort ein valides XML sein.

Beispiel:

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
        <InvokeUrl>
          <Step>
            <Request Method="Post">
              <Header Name="FieldHeader" field-Value="Forms.TestFoobar" />
              <Url field-Content="Forms.Url" />
              <Body field-Content="Forms.Body" />
            </Request>
            <Response>
              <Property Name="AccessToken" JsonPath="$.AccessToken" />
            </Response>
          </Step>
          <Step>
            <MultipartFormDataRequest>
              <File Name="Foobar" field-FileName="Forms.FileName">
                <Document Conversion="PDF" />
              </File>
              <Url field-Content="Forms.DataUrl" />
              <Header Name="AccessToken" Value="{AccessToken}" />
              <Header Name="AnotherHeader" field-Value="Forms.Header" />
              <FormData Name="SomethingOne" field-Value="Forms.FormData" />
              <FormData Name="SomethingTwo" Value="SomeValue2" />
            </MultipartFormDataRequest>
          </Step>
        </InvokeUrl>  
    </OnSuccess>
  </Commands>
</primedocsConnect>

ShowDialog

Desktop Web

Der ShowDialog-Command zeigt dem Benutzer einen Dialog an — z.B. eine Erfolgs- oder Fehlermeldung mit einem optionalen Button, der auf eine URL verweist. Er steht sowohl im Desktop-Client als auch in primedocs Web und über die Connect Session API zur Verfügung.

Attribute (jeweils auch als field--Variante verfügbar, um Feldwerte zu verwenden):

• Title / field-Title: Titel des Dialogs.
• Message / field-Message: Meldungstext.
• ButtonLabel / field-ButtonLabel: Beschriftung des optionalen Buttons.
• ButtonUri / field-ButtonUri: Ziel-URL des Buttons.

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <ShowDialog Title="Fertig"
                  Message="Das Dokument wurde erstellt."
                  ButtonLabel="Im CRM öffnen"
                  ButtonUri="https://crm.example.com/doc/42" />
    </OnSuccess>
  </Commands>
</primedocsConnect>

DownloadFile

Web

Der DownloadFile-Command stellt das generierte Dokument bzw. den Report in der Web App (Connect Session, WebOutput, WebSeriesOutput) als Datei-Download bereit. Werden mehrere DownloadFile-Commands definiert, werden die Dateien zu einem ZIP-Archiv zusammengefasst.

Attribute:

• FileName / field-FileName / replacer-FileName: Dateiname des Downloads.

Elemente:

• Document oder Report: Siehe Abschnitt «Zugriff auf das Ergebnis». Document ist nur im OnSuccess gültig.

<primedocsConnect>
  ...
  <Commands>
    <OnSuccess>
      <DownloadFile FileName="Offerte">
        <Document />
      </DownloadFile>
    </OnSuccess>
  </Commands>
</primedocsConnect>