Updating documents

Overview

If Forms-/ Data-values in a document created with primedocs need to be updated, this can be done using DocumentLocation.

note

Important: The original file itself is not changed, instead, it is only read in and can then be saved again, for example, via Connect Commands ( After document generation (Commands) )

“DocumentLocation”

By using the DocumentLocation-element in combination with the Source-attribute, the document does not need to be recreated, meaning that existing customizations in the generated document are retained.

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

It is essential that the document was originally created with primedocs. In addition, the user performing the update must have access to the template on which the document was based.

info

The Author cannot be changed by an update — the profile of the existing document remains authoritative (an update therefore also works without an Author element). The document language is kept by default, but can be overridden explicitly with a DocumentLanguage element (see Override the language).

“Source”-Attribute

With the Source-attribute, it is possible to use both a local and a remote source. If a remote source is used, it is essential to enable it beforehand in primedocs Admin (DataSourceAdminApp) under Connect Settings via the Connect - Remote Document Location Policies (RemoteDocumentLocationPolicies) setting.

Connect - Remote Document Location Policies

In this example, two Remote DocumentLocation policies are used, which means that remote addresses can only edit documents within the configured locations.

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

Only the uriStartsWith attribute is mandatory. The Headers block is optional — if the source needs no additional HTTP headers (for example because it is reachable anonymously), the Policy element on its own is sufficient, as in the second example above. The same applies to the policies under Connect - Remote Policies (see Retrieval from URL).

Authenticated remote sources (ConnectedServiceKey)

If the remote source requires user-based authentication, the ConnectedServiceKey attribute can be set on the DocumentLocation. The placeholder {__ConnectedService.AccessToken__} in a policy header is then replaced server-side with the access token of the referenced connected service.

<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 is only allowed in combination with Source and requires a signed-in user (Connect session). In headless (user-less) calls of the Connect API, a ConnectedServiceKey results in an error; only static policy headers can be used there.

---

Server-side update via the Connect API

Besides being triggered from the Desktop Client, an update can also be triggered server-side via the POST /api/v3/{datasourceId}/Connect/Update endpoint. The existing document is supplied in one of three ways:

• as a file in the document part of a multipart/form-data request (together with the connect XML in the connect part),
• inline as Base64 via <DocumentLocation Format="DocxBase64">…base64…</DocumentLocation>,
• or fetched server-side via <DocumentLocation Source="https://…"/> (only enabled remote sources, see Source attribute).

The updated document is returned as a file (conversion=Pdf possible).

---

Merge or Replace (UpdateBehavior)

How incoming Forms/Data values are applied to the existing document is controlled by the UpdateBehavior attribute on the DocumentLocation (or the behavior query parameter on the /Update endpoint):

Value	Behavior
Replace (default)	The values transmitted in the connect replace the existing ones; values not transmitted remain unchanged.
Merge	The transmitted values are merged with those stored in the document: objects are merged recursively, whole lists are replaced, and an explicitly empty list clears the values.

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

note

Merge requires the field data stored in the document (PrimeDocsFieldPart). If it is missing, a merge is not possible — use Replace in that case.

---

Override the language (DocumentLanguage)

By default, an updated document keeps its original language. An optional DocumentLanguage element overrides the language for the update — for example so that date fields are localized correctly in a PDF conversion:

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

---

Example

In the following example, Forms and Data values are updated via primedocsConnect.

<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>

warning

Any excess Forms or Data transmitted will be ignored.

Updated documents can be saved using the available Commands. If the connect call is made without specifying any Commands, the updated document is opened immediately.