Updating documents

A document created with primedocs can be updated with new data afterwards without creating it again. A typical case: the business data in a business application, such as a GEVER solution, has changed since the document was created, and the existing document is to be generated again with the current data. primedocs does not create the document again but only fills the primedocs fields in the existing document with the current data. Everything that someone has written or changed manually outside these fields is kept.

Overview

An update works as follows:

Area	Behaviour
Manually entered text outside the primedocs fields	Remains unchanged, as does the formatting of the document. primedocs only replaces the content of the primedocs fields.
Supplied Forms and Data values	Replace the previous values in the document. A value supplied empty clears the field.
Forms and Data values not supplied	Are kept, see Supplied and omitted values.
Sender	Remains the sender the document was created with, even if another user performs the update. See Sender and signers.
Signers	Remain selected unless the connect sets others.
Document language	Is kept unless it is overridden with DocumentLanguage.
Colour theme	Is kept.
Fields and logic	Are calculated according to the currently published version of the template.

An update is triggered with a connect file containing a DocumentLocation element: from primedocs Desktop with primedocs Connect or with OneOffixx Connect and primedocsConnectBridge, for example when adding data from a GEVER system, or server-side via the Connect API.

note

The original file is not changed. primedocs only reads it. The updated document is opened or saved, for example via Connect Commands (After document generation (Commands)).

Prerequisites

• The document was created with primedocs and contains its document data. With any other document, the update stops with an error.
• The user performing the update has access to the template the document was created with.
• The connect contains neither Template nor Author. The template and the sender are taken from the document. If either element is set, the call stops with an error.

Sender and signers

Documents are often not updated by the person who created them, for example when a colleague adds data in a business file. primedocs therefore keeps the sender of the document:

• Sender: The profile values stored in the document when it was created remain in effect. This also applies if the creator performs the update and has changed their profile in the meantime, for example a new phone number. Only profile fields without a stored value, such as fields added since, are filled by primedocs from the profile of the document, provided it is available.
• Profile of the document not available: If the user performing the update (primedocs Desktop) or the datasource (server-side) does not know the profile of the document, for example for a colleague's document or after the profile has been deleted, the update runs without a profile. The profile values then come from the document only, and profile fields without a stored value remain empty. The document keeps the creator's profile.
• Signers: The signers stored in the document remain selected. If the user performing the update can load a signer's profile, primedocs uses its current values. Otherwise the values stored in the document are kept. If the connect or the user in the Forms dialog sets another person, that person is loaded as during creation.

Limitations for signers

Signers in the entries of an ObjectCollection and signers with a dot in their Id (for example Presentation.Signer with UseDotsForHierarchy) are not kept. If the Forms dialog opens during the update and the user cannot load a signer's profile, the dialog shows no selection for that signer. The stored signer is kept nevertheless, as long as nobody else is selected.

DocumentLocation

The DocumentLocation element with the Source attribute specifies which document is updated. The document is not created again, so existing customisations are kept.

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

Source attribute

With the Source attribute, it is possible to use both a local and a remote source. A remote source must be enabled beforehand, in the Web Admin under Document location policies or 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 primedocs Desktop, 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). No Forms dialog opens server-side.

---

Supplied and omitted values

The Forms and Data values stored in the document are the baseline of every update. The supplied values override them key by key:

• Supplied value: replaces the stored value.
• Omitted value: is kept. If only Forms.Subject is supplied, Forms.Reference keeps its value from the document.
• Value supplied empty: clears the field. An explicitly empty list clears the previous entries.
• Objects are merged key by key, lists (ObjectCollection) are replaced as a whole.
• Empty required values in the document: stored required fields without a value, for example from a creation through the Connect API without those values, do not prevent the update. Server-side they stay empty as long as no value is supplied. If the Forms dialog opens in primedocs Desktop, it marks the empty required fields, and the update continues only after they are filled in. With the dialog hidden (HideDialog="true"), the update is rejected with the error Forms.ValidationFailed naming the affected fields.

This applies in the same way on every path: in primedocs Desktop with primedocs Connect and with OneOffixx Connect including primedocsConnectBridge, also when the Forms dialog is hidden (HideDialog="true"), and server-side via the Connect API. If the Forms dialog opens in primedocs Desktop, it starts with the merged values. Whatever the user changes there applies.

The sender and the signers are kept regardless (see Sender and signers).

Stored field data required

The update reads the field data stored in the document (the custom XML part PrimeDocsFieldPart). Word and PowerPoint documents receive it whenever they are created with primedocs. If it is missing, for example because a tool has removed the custom XML data from the document, the update stops with an error.

---

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 localised correctly in a PDF conversion:

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

---

Example

In the following example, individual Forms and Data values are added. The other values of the document are kept. The updated document is saved under a new name.

<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

Supplied Forms or Data values that the template does not know are ignored.

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