Aktualisieren von Dokumenten

Übersicht

Wenn Forms / Data -Werte in einem mit primedocs erzeugten Dokument aktualisiert werden sollen, kann dies mithilfe der DocumentLocation erfolgen.

hinweis

Wichtig: Die ursprüngliche Datei wird selbst nicht verändert, sondern wird nur eingelesen und kann dann z.B. über Connect Commands ( Nach der Dokumentgenerierung (Commands)) wieder gespeichert werden.

“DocumentLocation”

Durch das DocumentLocation-Element in Kombination mit dem Source-Attribut muss das Dokument dabei nicht neu erstellt werden, sodass bereits vorhandene Anpassungen im generierten Dokument erhalten bleiben.

<primedocsConnect>
  <DocumentLocation Source="\\MyServer\share\doc\...\documentxyz.docx" />
  ...
</primedocsConnect>

Es ist dabei zwingend erforderlich, dass das Dokument ursprünglich mit primedocs erstellt wurde. Ausserdem benötigt ein Benutzer, der die Aktualisierung durchführt, Zugriff auf die Vorlage, auf dessen Grundlage das Dokument generiert wurde.

info

Der Author kann durch eine Aktualisierung nicht verändert werden — das Profil des bestehenden Dokuments bleibt massgebend (eine Aktualisierung funktioniert deshalb auch ohne Author-Element). Die Dokumentsprache bleibt standardmässig erhalten, lässt sich aber über ein DocumentLanguage-Element gezielt überschreiben (siehe Sprache überschreiben).

“Source”-Attribut

Beim Source-Attribut ist es möglich, sowohl eine lokale als auch eine Remote-Quelle zu verwenden. Wird eine Remote-Quelle genutzt, ist es zwingend erforderlich, diese zuvor in primedocs Admin (DataSourceAdminApp) unter Connect Settings über die Einstellung Connect - Remote Document Location Policies (RemoteDocumentLocationPolicies) freizugeben.

Connect - Remote Document Location Policies

In diesem Beispiel werden zwei Remote DocumentLocation-Policies verwendet, wodurch es Remote-Adressen nur möglich ist, Dokumente innerhalb der konfigurierten Locations zu bearbeiten.

<RemoteDocumentLocationPolicies>
  <Policy uriStartsWith="https://example1.com">
    <Headers>
      <Header name="header1" value="value1"/>
    </Headers>
  </Policy>
  <Policy uriStartsWith="https://example2.com" />
....
</RemoteDocumentLocationPolicies>

Pflicht ist nur das Attribut uriStartsWith. Der Headers-Block ist optional — benötigt die Quelle keine zusätzlichen HTTP-Header (z.B. weil sie anonym erreichbar ist), genügt das Policy-Element allein, wie im zweiten Beispiel oben. Dasselbe gilt für die Policies unter Connect - Remote Policies (siehe Abruf von URL).

Authentifizierte Remote-Quellen (ConnectedServiceKey)

Benötigt die Remote-Quelle eine benutzerbezogene Authentisierung, kann am DocumentLocation das Attribut ConnectedServiceKey gesetzt werden. Der Platzhalter {__ConnectedService.AccessToken__} in einem Policy-Header wird dann serverseitig durch das Access Token des referenzierten Connected Service ersetzt.

<DocumentLocation Source="https://cmi.example.ch/api/documents/4711" ConnectedServiceKey="CMI" />

<Policy uriStartsWith="https://cmi.example.ch/api/documents/">
  <Headers>
    <Header name="Authorization" value="Bearer {__ConnectedService.AccessToken__}"/>
  </Headers>
</Policy>

ConnectedServiceKey ist nur in Kombination mit Source zulässig und setzt einen angemeldeten Benutzer voraus (Connect Session). In benutzerlosen (Headless-)Aufrufen der Connect API führt ein gesetzter ConnectedServiceKey zu einem Fehler; dort können nur statische Policy-Header verwendet werden.

---

Serverseitige Aktualisierung über die Connect API

Neben dem Aufruf aus dem Desktop-Client kann eine Aktualisierung auch serverseitig über den Endpunkt POST /api/v3/{datasourceId}/Connect/Update ausgelöst werden. Das bestehende Dokument wird dabei auf eine von drei Arten übergeben:

• als Datei im document-Teil eines multipart/form-data-Requests (zusammen mit dem Connect-XML im connect-Teil),
• inline als Base64 über <DocumentLocation Format="DocxBase64">…base64…</DocumentLocation>,
• oder per serverseitigem Abruf über <DocumentLocation Source="https://…"/> (nur freigegebene Remote-Quellen, siehe Source-Attribut).

Das aktualisierte Dokument wird als Datei zurückgegeben (conversion=Pdf möglich).

---

Merge oder Replace (UpdateBehavior)

Wie eingehende Forms/Data-Werte auf das bestehende Dokument angewendet werden, steuert das Attribut UpdateBehavior am DocumentLocation (bzw. der Query-Parameter behavior am /Update-Endpunkt):

Wert	Verhalten
Replace (Standard)	Die im Connect übermittelten Werte ersetzen die bestehenden; nicht übermittelte Werte bleiben unverändert.
Merge	Die übermittelten Werte werden mit den im Dokument gespeicherten zusammengeführt: Objekte werden rekursiv gemergt, ganze Listen werden ersetzt, eine explizit leere Liste löscht die Werte.

<DocumentLocation Source="\\MyServer\share\doc\...\documentxyz.docx" UpdateBehavior="Merge" />

hinweis

Merge benötigt die im Dokument gespeicherten Felddaten (PrimeDocsFieldPart). Fehlen diese, ist kein Merge möglich — in diesem Fall Replace verwenden.

---

Sprache überschreiben (DocumentLanguage)

Standardmässig behält ein aktualisiertes Dokument seine ursprüngliche Sprache. Mit einem optionalen DocumentLanguage-Element lässt sich die Sprache für die Aktualisierung gezielt überschreiben — z.B. damit Datumsfelder bei einer PDF-Konvertierung korrekt lokalisiert werden:

<primedocsConnect>
  <DocumentLocation Source="\\MyServer\share\doc\...\documentxyz.docx" />
  <DocumentLanguage Code="fr-CH" />
  ...
</primedocsConnect>

---

Beispiel

Im nachfolgenden Beispiel werden Forms und Data Werte via primedocsConnect aktualisiert.

<primedocsConnect>
  <DocumentLocation Source="\\MyServer\share\doc\...\documentxyz.docx" />

  <Forms HideDialog="true">
   <Value Key="FormsKey">New value after update</Value>
  </Forms>
  
  <Data>
    <Value Key="MyTestValue">New value</Value>
    <Object  Key="MyTestObject">
        <Value Key="Name">New Name</Value>
	   	<Value Key="Address">New Address</Value>
    </Object>
 </Data>

<!-- Save updated document  -->
 <Commands>
   <OnSuccess>
	<SaveFile FileName="\\MyServer\share\doc\...\documentxyz-New.docx"
		      Overwrite="true"
		      CreateFolder="true">
	<Document />
	 </SaveFile>
	</OnSuccess>
 </Commands>
  
</primedocsConnect>

warnung

Zuviel übermittelte Forms oder Data werden ignoriert.

Aktualisierte Dokumente können über die verfügbaren Commands gespeichert werden. Erfolgt der connect-Aufruf ohne Angabe von Commands, wird das aktualisierte Dokument unmittelbar geöffnet.