Version: 4.1 (2026 H2)

Aktualisieren von Dokumenten

Ein mit primedocs erstelltes Dokument lässt sich nachträglich mit neuen Daten aktualisieren, ohne es neu zu erstellen. Typischer Fall: Im Fachsystem, etwa einer GEVER-Lösung, haben sich die Geschäftsdaten seit der Erstellung geändert, und das bereits erstellte Dokument soll mit den aktuellen Daten nochmals generiert werden. primedocs erstellt das Dokument dabei nicht neu, sondern füllt nur die primedocs-Felder im bestehenden Dokument mit den aktuellen Daten. Alles, was jemand von Hand ausserhalb dieser Felder geschrieben oder geändert hat, bleibt erhalten.

Übersicht

Bei einer Aktualisierung gilt:

Bereich	Verhalten
Manuell erfasste Texte ausserhalb der primedocs-Felder	Bleiben unverändert, ebenso die Gestaltung des Dokuments. primedocs ersetzt nur die Inhalte der primedocs-Felder.
Mitgelieferte `Forms`- und `Data`-Werte	Ersetzen die bisherigen Werte im Dokument. Ein leer mitgelieferter Wert leert das Feld.
Nicht mitgelieferte `Forms`- und `Data`-Werte	Bleiben erhalten, siehe Mitgelieferte und nicht mitgelieferte Werte.
Absender	Bleibt der Absender, mit dem das Dokument erstellt wurde, auch wenn ein anderer Benutzer aktualisiert. Siehe Absender und Unterzeichnende.
Unterzeichnende	Bleiben ausgewählt, sofern der Connect keine anderen setzt.
Dokumentsprache	Bleibt erhalten, ausser sie wird mit `DocumentLanguage` überschrieben.
Farbthema	Bleibt erhalten.
Felder und Logik	Werden nach der aktuell veröffentlichten Version der Vorlage berechnet.

Ausgelöst wird eine Aktualisierung über eine Connect-Datei mit einem DocumentLocation-Element: aus primedocs Desktop mit primedocs Connect oder mit OneOffixx-Connect und primedocsConnectBridge, etwa für «Daten nachtragen» aus einem GEVER-System, oder serverseitig über die Connect API.

hinweis

Die ursprüngliche Datei wird nicht verändert. primedocs liest sie nur ein. Das aktualisierte Dokument wird geöffnet oder z.B. über Connect Commands (Nach der Dokumentgenerierung (Commands)) gespeichert.

Voraussetzungen

Das Dokument wurde mit primedocs erstellt und enthält dessen Dokumentdaten. Ein anderes Dokument bricht die Aktualisierung mit einem Fehler ab.
Der Benutzer, der die Aktualisierung durchführt, hat Zugriff auf die Vorlage, mit der das Dokument erstellt wurde.
Der Connect enthält weder Template noch Author. Vorlage und Absender ergeben sich aus dem Dokument. Ist eines der beiden Elemente gesetzt, bricht der Aufruf mit einem Fehler ab.

Absender und Unterzeichnende

Dokumente werden oft nicht von der Person aktualisiert, die sie erstellt hat, etwa wenn eine Kollegin in einem Geschäft Daten nachträgt. primedocs behält deshalb den Absender des Dokuments bei:

Absender: Die Profilwerte, die bei der Erstellung im Dokument gespeichert wurden, gelten weiter. Das gilt auch, wenn der Ersteller selbst aktualisiert und sein Profil inzwischen geändert hat, z.B. eine neue Telefonnummer. Nur Profilfelder ohne gespeicherten Wert, etwa seither neu angelegte, füllt primedocs aus dem Profil des Dokuments, sofern es verfügbar ist.
Profil des Dokuments nicht verfügbar: Kennt der aktualisierende Benutzer (primedocs Desktop) bzw. die Datasource (serverseitig) das Profil des Dokuments nicht, etwa beim Dokument eines Kollegen oder nach dem Löschen des Profils, läuft die Aktualisierung ohne Profil. Die Profilwerte kommen dann nur aus dem Dokument, Profilfelder ohne gespeicherten Wert bleiben leer. Im Dokument bleibt das Profil des Erstellers hinterlegt.
Unterzeichnende: Die im Dokument gespeicherten Unterzeichnenden bleiben ausgewählt. Kann der aktualisierende Benutzer das Profil eines Unterzeichnenden laden, übernimmt primedocs dessen aktuelle Werte. Sonst bleiben die im Dokument gespeicherten Werte erhalten. Setzt der Connect oder der Benutzer im Forms-Dialog eine andere Person, wird diese wie bei der Erstellung geladen.

Einschränkungen bei Unterzeichnenden

Nicht erhalten bleiben Unterzeichnende in den Einträgen einer ObjectCollection sowie Unterzeichnende mit Punkt in der Id (z.B. Presentation.Signer bei UseDotsForHierarchy). Öffnet sich beim Aktualisieren der Forms-Dialog und kann der Benutzer das Profil eines Unterzeichnenden nicht laden, zeigt der Dialog für ihn keine Auswahl an. Der gespeicherte Unterzeichnende bleibt trotzdem erhalten, solange niemand anderes gewählt wird.

`DocumentLocation`

Das DocumentLocation-Element mit dem Source-Attribut gibt an, welches Dokument aktualisiert wird. Das Dokument wird dabei nicht neu erstellt, sodass bereits vorhandene Anpassungen erhalten bleiben.

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

`Source`-Attribut

Beim Source-Attribut ist es möglich, sowohl eine lokale als auch eine Remote-Quelle zu verwenden. Eine Remote-Quelle muss vorher freigegeben werden, im Web-Admin unter Richtlinien für Dokumentablagen bzw. in primedocs Admin (DataSourceAdminApp) unter Connect Settings über die Einstellung Connect - Remote Document Location Policies (RemoteDocumentLocationPolicies).

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 primedocs Desktop 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). Serverseitig öffnet sich kein Forms-Dialog.

Mitgelieferte und nicht mitgelieferte Werte

Die im Dokument gespeicherten Forms- und Data-Werte bilden die Grundlage jeder Aktualisierung. Die mitgelieferten Werte überschreiben sie Schlüssel für Schlüssel:

Mitgelieferter Wert: ersetzt den gespeicherten Wert.
Nicht mitgelieferter Wert: bleibt erhalten. Wird nur Forms.Subject nachgetragen, behält Forms.Reference den Wert aus dem Dokument.
Leer mitgelieferter Wert: leert das Feld. Eine explizit leere Liste leert die bisherigen Einträge.
Objekte werden Schlüssel für Schlüssel zusammengeführt, Listen (ObjectCollection) als Ganzes ersetzt.
Leere Pflichtwerte im Dokument: Gespeicherte Pflichtfelder ohne Wert, etwa aus einer Erstellung über die Connect API ohne diese Werte, verhindern die Aktualisierung nicht. Serverseitig bleiben sie leer, solange kein Wert mitgeliefert wird. Öffnet sich in primedocs Desktop der Forms-Dialog, markiert er die leeren Pflichtfelder, und die Aktualisierung läuft erst nach dem Ausfüllen weiter. Mit ausgeblendetem Dialog (HideDialog="true") wird die Aktualisierung mit dem Fehler Forms.ValidationFailed und den betroffenen Feldern abgewiesen.

Das gilt auf allen Wegen gleich: in primedocs Desktop mit primedocs Connect und mit OneOffixx-Connect samt primedocsConnectBridge, auch bei ausgeblendetem Forms-Dialog (HideDialog="true"), und serverseitig über die Connect API. Öffnet sich in primedocs Desktop der Forms-Dialog, startet er mit den zusammengeführten Werten. Was der Benutzer dort ändert, gilt.

Absender und Unterzeichnende bleiben unabhängig davon erhalten (siehe Absender und Unterzeichnende).

Gespeicherte Felddaten vorausgesetzt

Die Aktualisierung liest die im Dokument gespeicherten Felddaten (den Custom-XML-Teil PrimeDocsFieldPart). Word- und PowerPoint-Dokumente erhalten ihn bei jeder Erstellung mit primedocs. Fehlt er, etwa weil ein Werkzeug die Custom-XML-Daten aus dem Dokument entfernt hat, bricht die Aktualisierung mit einem Fehler ab.

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 einzelne Forms- und Data-Werte nachgetragen. Die übrigen Werte des Dokuments bleiben erhalten. Das aktualisierte Dokument wird unter einem neuen Namen gespeichert.

<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

Mitgelieferte Forms- oder Data-Werte, die die Vorlage nicht kennt, werden ignoriert.

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

Übersicht​

Voraussetzungen​

Absender und Unterzeichnende​

DocumentLocation​

Source-Attribut​

Authentifizierte Remote-Quellen (ConnectedServiceKey)​

Serverseitige Aktualisierung über die Connect API​

Mitgelieferte und nicht mitgelieferte Werte​

Sprache überschreiben (DocumentLanguage)​

Beispiel​