Version: 4.0 (2026 H1)

Struktur

primedocs Connect ist eine XML-Schnittstelle, die verwendet werden kann, um die Dokumenterzeugung teilweise oder vollständig zu automatisieren. Connect kann sowohl client- als auch serverseitig verarbeitet werden.

<primedocsConnect>
   ...
</primedocsConnect>

Template

Über das Template-Element kann gezielt eine Vorlage angesprochen oder eine Filterung aufgrund von Tags vorgenommen werden.

Id

Über das Id-Attribut wird die Vorlage für die Dokumentverarbeitung gewählt. Als Angabe dafür muss die genaue GUID der Vorlage übergeben werden.

<primedocsConnect>
  <Template Id="30b55516-80b5-41d7-801b-b31d6da376ac" />
  ...
</primedocsConnect>

Version

Über das Version="Draft"-Attribut kann auf eine Vorlage im Entwurfsmodus zugegriffen werden.

<primedocsConnect>
  <Template Id="30b55516-80b5-41d7-801b-b31d6da376ac" Version="Draft" />
  ...
</primedocsConnect>

TagFilter

Über das TagFilter-Element können Tags zur Filterung angegeben werden.

<primedocsConnect>
  <Template>
    <TagFilter>
      <Tag>Tag1</Tag>
      <Tag>Tag2;Tag3;Tag4</Tag>
    </TagFilter>
  </Template>
  ...
</primedocsConnect>

AND-Verknüpfungen werden innerhalb eines Tag-Elements durch Semikolons getrennt definiert, OR-Verknüpfungen durch mehrere Tag-Elemente. Das obige Beispiel zeigt alle Vorlagen, die mit Tag1 oder Tag2, Tag3 und Tag4 markiert sind.

info

Standardmässig wird erwartet, dass die Filterung nur eine Vorlage als Ergebnis liefert.
Liefert die Abfrage mehrere Vorlagen, wird eine Fehlermeldung angezeigt. Insbesondere bei der serverseitigen Verarbeitung wird ein Fehler zurückgegeben, sollte die Abfrage mehr als eine Vorlage finden.

Über das AllowTemplatePicker-Attribut kann optional ein Auswahldialog (“TemplatePicker”) angezeigt werden, dieser zeigt dann alle resultierenden Vorlagen an.

<primedocsConnect>
  <Template>
    <TagFilter AllowTemplatePicker="true">
      <Tag>Tag1</Tag>
      <Tag>Tag2;Tag3;Tag4</Tag>
    </TagFilter>
  </Template>
  ...
</primedocsConnect>

Der “TemplatePicker” wird auch angezeigt, wenn gar kein Template-Element angeben wird.

DocumentLanguage

Über das DocumentLanguage-Element mit dem Code-Attribut kann die Zieldokumentsprache angegeben werden.

<primedocsConnect>
  <DocumentLanguage Code="de-ch" />
  ...
</primedocsConnect>

info

Wird keine DocumentLanguage angegeben, wird die Standardsprache der primedocs Datenquelle genommen.

DocumentLocation

Durch das DocumentLocation-Element in Kombination mit dem Source-Attribut kann ein zuvor mit primedocs erzeugtes Dokument aktualisiert werden.

Source kann ein Dateipfad sein oder eine URL.
Im Falle einer URL muss diese im Dashboard über die RemoteDocumentLocationPolicies freigegeben sein.

Details und Hinweise unter Aktualisieren von Dokumenten

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

Author

Das Author-Element kann genutzt werden um die Dokumenterzeugung mit einem bestimmten Profil und einem bestimmten Thema zu starten.

<primedocsConnect>
  <Author>
    <Profile Id="08be85c8-d12a-4e8c-b1aa-9f56e5f6ed38" ThemeId="Red" />
  </Author>
  ...
</primedocsConnect>

Über das Id-Attribut kann ein bestimmtes Profil ausgewählt werden. Das ThemeId-Attribut kann genutzt werden um ein bestimmtes Thema auszuwählen.

warnung

Ohne Angabe eines expliziten Profiles wird das aktuelle Profile des primedocs-Clients verwendet.
Serverseitig muss ein Profil angegeben werden, ansonsten wird ein Fehler zurückgegeben.

hinweis

Die benötigte ProfileId sowie weitere technische Informationen sind direkt im Detaildialog der Profilansicht einsehbar.

Forms

Die Dokumentfunktion Formulare (Forms) dient dazu Daten vor der Dokumentgenerierung abzufragen. Die konfigurierten Eigenschaften können auch über die Connect Schnittstelle vorausgefüllt werden.

Attribute

Attribut	Funktion
HideDialog	Wenn der Wert auf `true` gesetzt ist, wird kein Dialog angezeigt und stattdessen werden die Standardwerte und die im Connect übergebenen Werte für die Dokumentgenerierung übernommen. Hinweis: Schlägt die Validierung fehl, wenn beispielsweise ein als `required` markiertes Element nicht gesetzt wurde, kann das Dokument nicht generiert werden und ein Connect-Fehler wird erzeugt.

<primedocsConnect>
  <Forms HideDialog="true">
	<!-- "Simple" mappings to Text/Choice/Date/... -->
    <Value Key="Subject">Sample letter</Value>
	<Value Key="Note">Another sample</Value>
	
	<!-- Target is an Object -->
    <Object Key="Recipient">
      <Value Key="Name">John Doe</Value>
      <Value Key="Address">Sample Street 123, 12345 City</Value>
    </Object>

	<!-- Target is an ObjectCollection -->
	<ObjectCollection Key="Topics">
	  <Item>
	    <Value Key="Name">Sample 1</Value>
	  </Item>
	  <Item>
	    <Value Key="Name">Sample 2</Value>
	  </Item>
	  <Item>
	    <Value Key="Name">Sample 3</Value>
	  </Item>
	  <Item>
	    <Value Key="Name">Sample 4</Value>
	  </Item>
   </ObjectCollection>
  </Forms>
  ...
</primedocsConnect>

Über Connect wird nur die “Ziel-Id” des jeweiligen Elements angegeben samt dem Inhalt. Hierbei werden 3 verschiedene Typen unterschieden:

“Normale” Elemente können über <Value Key="ElementId">Wert</Value> befüllt werden.
Objekte (Object), wie z.B. Personenangaben über das Elternelement <Object Key="ElementId" /> samt <Value Key="ElementId">Wert</Value> für die Kindelemente.
Objektlisten (ObjectCollection) für Auflistungen von Daten, wobei jeder Datensatz in einem Item-Element ist.

Mehrzeilige Texte

Um mehrzeilige Texte zu übertragen kann das XML Line-Feed Element (
) genutzt werden bzw. im XML selbst eine neue Zeile eingefügt werden.

<Value Key="SampleWithLineFeed">Line1&#10;Line2</Value> 
          
<Value Key="SampleWithCData"><![CDATA[Line1
Line2]]></Value>

<Value Key="SampleWithoutCData">Line1
Line2</Value>

Data

Im Zusammenspiel mit der Dokumentfunktion Data kann über Data Daten über Connect übergeben werden, welche nicht im Forms-Eigenschaften Dialog vorher angezeigt oder abgefragt werden sollen.

<primedocsConnect>
  <Data>
	<!-- "Simple" mappings to Text -->
    <Value Key="InternalId">123456789</Value>

    <!-- FormattedText via Html (HtmlBase64 is also possible) -->
    <Value Key="TextWithFormatting" Format="Html">
		<![CDATA[
		<p><b>Important:</b> This message...</p>
		]]>
    </Value>

    <!-- WordContent via FlatOpc (FlatOpcBase64 or DocxBase64 is also possible) -->
    <Value Key="TextWithWordFormatting" Format="FlatOpc">
		<![CDATA[
		<?mso-application progid="Word.Document"?>
        <pkg:package xmlns:pkg="http://schemas.microsoft.com/office/2006/xmlPackage">
        ...
        </pkg:package>
		]]>
    </Value>
    
	<!-- Target is an Object -->
    <Object Key="Invoice">
      <Value Key="Name">John Doe</Value>
      <Value Key="Number">123</Value>
    </Object>

	<!-- Target is an ObjectCollection -->
	<ObjectCollection Key="Items">
	  <Item>
	    <Value Key="Name">Sample 1</Value>
	  </Item>
	  <Item>
	    <Value Key="Name">Sample 2</Value>
	  </Item>
   </ObjectCollection>
  </Data>
  ...
</primedocsConnect>

Die Logik ist hier identisch wie bei der Übergabe zu Forms, d.h. es gibt:

<Value Key="...">...</Value>
<Object Key="...">...</Object>
<ObjectCollection Key="...">...</ObjectCollection>

Es gibt eine Besonderheit bei den Zieltypen WordContent und FormattedText. Diese Typen verlangen beim Connect-Aufruf ein explizit gesetztes Format.

Für FormattedText werden folgende Formate unterstützt:

Html: <Value Key="..." Format="Html">...</Value>, in diesem Fall wird HTML als Text erwartet.
HtmlBase64: <Value Key="..." Format="HtmlBase64">...</Value>, der Inhalt entspricht demselben HTML-Format, allerdings Base64 kodiert.

Für WordContent werden folgende Formate unterstützt:

FlatOpc: <Value Key="..." Format="FlatOpc">...</Value>, in diesem Fall wird der Inhalt im FlatOpc-Format als Text erwartet.
FlatOpcBase64: <Value Key="..." Format="FlatOpcBase64">...</Value>, der Inhalt entspricht demselben FlatOpc-Format, allerdings Base64 kodiert.
DocxBase64: <Value Key="..." Format="DocxBase64">...</Value>, als Inhalt kann eine komplette Word Datei im .docx-Format Base64 kodiert übergeben werden.

Outlook

info

Dieses Element wird nur im Zusammenhang mit Outlook-Vorlagen beachtet.

Outlook Vorlagen haben mehrere Typen bzw. Aufrufarten, daher gibt es ein eigenes Element für den Umgang mit diesen Vorlagentyp.

<primedocsConnect>
  <Outlook ContentType="Html" />
  ...
</primedocsConnect>

ContentType steuert die Vorlage für Html oder PlainText an.

Commands

Nach der eigentlichen Dokumenterstellung können Commands angewendet werden (z. B. die Umwandlung in ein PDF-Dokument). Gleichzeitig werden zu diesem Zeitpunkt die Fehler- und Abbruch-Commands auf Dokumentebene ausgewertet.

Commands können nach den folgenden Ereignissen gestartet werden:

OnSuccess: Bei einer erfolgreichen Dokumentgenerierung.
OnError: Falls während der Dokumentgenerierung ein Fehler auftritt, z.B. eine fehlerhafte Template-Id angegeben wird.
OnCancel: Wenn der Benutzer die Dokumentgenerierung z.B. über den Forms-Dialog abbricht.
OnExit: Nach Beendigung der Dokumentgenerierung, hierbei ist es egal, ob alles erfolgreich durchlief oder nicht.

Ablauf

Der Ablauf der Commands ist Abhängig vom Status der Dokumentgenerierung:

Erfolg:
OnSuccess, dann OnExit
Fehler:
OnError, dann OnExit
Abbruch:
OnCancel, dann OnExit
Bei Fehler in OnSuccess:
OnError, dann OnExit

Bei Fehler in OnError, OnCancel, OnExit:

Sofortiger Abbruch

Beispiel:

<primedocsConnect>
  <Template Id="30b55516-80b5-41d7-801b-b31d6da376ac" />
  <Forms>
    <Value Key="Subject">Hello Connect</Value>
  </Forms>
  <Commands>
    <OnSuccess>
      <SaveFile FileName="\\MyServer\share\organization\...\documentxyz.docx"
                Overwrite="true"
                CreateFolder="true">
          <Document />
        </SaveFile>
    </OnSuccess>
  </Commands>
</primedocsConnect>

In diesem Beispiel wird ein Dokument mit der Vorlage 30b55516-80b5-41d7-801b-b31d6da376ac mit dem Subject “Hello Connect” generiert.
Nach der erfolgreichen Dokumentgenerierung wird das Dokument über den SaveFile-Command in einen Ordner abgespeichert.

Alle verfügbaren Commands sind hier dokumentiert: Nach der Dokumentgenerierung (Commands)

XSD-Schema

Nachfolgend finden Sie das Schema im XSD-Format:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="primedocsConnect">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="Template">
					<xs:complexType>
						<xs:sequence>
							<xs:element name="TagFilter">
								<xs:complexType>
									<xs:sequence>
										<xs:element maxOccurs="unbounded" name="Tag" type="xs:string" />
									</xs:sequence>
									<xs:attribute name="AllowTemplatePicker" type="xs:boolean" use="optional" />
								</xs:complexType>
							</xs:element>
						</xs:sequence>
						<xs:attribute name="Id" type="xs:string" use="optional" />
						<xs:attribute name="Version" type="xs:string" use="optional" />
					</xs:complexType>
				</xs:element>
				<xs:element name="DocumentLanguage">
					<xs:complexType>
						<xs:attribute name="Code" type="xs:string" use="required" />
					</xs:complexType>
				</xs:element>
				<xs:element name="DocumentLocation">
					<xs:complexType>
						<xs:attribute name="Source" type="xs:string" use="required" />
					</xs:complexType>
				</xs:element>				
				<xs:element name="Author">
					<xs:complexType>
						<xs:sequence>
							<xs:element name="Profile">
								<xs:complexType>
									<xs:attribute name="Id" type="xs:string" use="required" />
									<xs:attribute name="ThemeId" type="xs:string" use="optional" />
								</xs:complexType>
							</xs:element>
						</xs:sequence>
					</xs:complexType>
				</xs:element>
				<xs:element name="Forms">
					<xs:complexType>
						<xs:sequence>
							<xs:element minOccurs="0" maxOccurs="unbounded" name="Value" type="ValueElement" />
							<xs:element minOccurs="0" maxOccurs="unbounded" name="Object" type="ObjectElement" />
							<xs:element minOccurs="0" maxOccurs="unbounded" name="ObjectCollection" type="ObjectCollectionElement" />
						</xs:sequence>
					</xs:complexType>
				</xs:element>
				<xs:element name="Data">
					<xs:complexType>
						<xs:sequence>
							<xs:element minOccurs="0" maxOccurs="unbounded" name="Value" type="ValueElement" />
							<xs:element minOccurs="0" maxOccurs="unbounded" name="Object" type="ObjectElement" />
							<xs:element minOccurs="0" maxOccurs="unbounded" name="ObjectCollection" type="ObjectCollectionElement" />
						</xs:sequence>
					</xs:complexType>
				</xs:element>
				<xs:element name="Outlook">
					<xs:complexType>
						<xs:attribute name="ContentType" type="xs:string" use="optional" />
					</xs:complexType>
				</xs:element>				
				<xs:element name="Commands">
					<xs:complexType>
						<xs:sequence>
							<xs:element name="OnSuccess">
								<xs:complexType>
									<xs:sequence>
                                        <xs:element name="SaveFile" minOccurs="0" maxOccurs="1" type="CommandSaveFileElement" />
                                        <xs:element name="OpenFile" minOccurs="0" maxOccurs="1" type="CommandOpenFileElement" />
                                        <xs:element name="InvokeProcess" minOccurs="0" maxOccurs="1" type="CommandInvokeProcessElement" />
                                        <xs:element name="InvokeUrl" minOccurs="0" maxOccurs="1" type="CommandInvokeUrlElement" />
									</xs:sequence>
								</xs:complexType>
							</xs:element>
							<xs:element name="OnError">
								<xs:complexType>
									<xs:sequence>
										<xs:element name="SaveFile" minOccurs="0" maxOccurs="1" type="CommandSaveFileElement" />
										<xs:element name="InvokeProcess" minOccurs="0" maxOccurs="1" type="CommandInvokeProcessElement" />
                                        <xs:element name="InvokeUrl" minOccurs="0" maxOccurs="1" type="CommandInvokeUrlElement" />										
									</xs:sequence>
								</xs:complexType>
							</xs:element>
							<xs:element name="OnExit">
								<xs:complexType>
									<xs:sequence>
										<xs:element name="SaveFile" minOccurs="0" maxOccurs="1" type="CommandSaveFileElement" />
										<xs:element name="InvokeProcess" minOccurs="0" maxOccurs="1" type="CommandInvokeProcessElement" />
                                        <xs:element name="InvokeUrl" minOccurs="0" maxOccurs="1" type="CommandInvokeUrlElement" />										
									</xs:sequence>
								</xs:complexType>
							</xs:element>
							<xs:element name="OnCancel">
								<xs:complexType>
									<xs:sequence>
										<xs:element name="SaveFile" minOccurs="0" maxOccurs="1" type="CommandSaveFileElement" />
										<xs:element name="InvokeProcess" minOccurs="0" maxOccurs="1" type="CommandInvokeProcessElement" />
                                        <xs:element name="InvokeUrl" minOccurs="0" maxOccurs="1" type="CommandInvokeUrlElement" />										
									</xs:sequence>
								</xs:complexType>
							</xs:element>
						</xs:sequence>
					</xs:complexType>
				</xs:element>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
	<!-- Data / Forms Element Types -->
	<xs:complexType name="ValueElement">
		<xs:simpleContent>
			<xs:extension base="xs:string">
				<xs:attribute name="Key" type="xs:string" use="required" />
				<xs:attribute name="Format" type="xs:string" use="optional" />
			</xs:extension>
		</xs:simpleContent>
	</xs:complexType>
	<xs:complexType name="ObjectElement">
		<xs:sequence>
			<xs:element maxOccurs="unbounded" name="Value" type="ValueElement" />
		</xs:sequence>
		<xs:attribute name="Key" type="xs:string" use="required" />
	</xs:complexType>
	<xs:complexType name="ObjectCollectionElement">
		<xs:sequence>
			<xs:element maxOccurs="unbounded" name="Item">
				<xs:complexType>
					<xs:sequence>
						<xs:element maxOccurs="unbounded" name="Value" type="ValueElement" />
					</xs:sequence>
				</xs:complexType>
			</xs:element>
		</xs:sequence>
		<xs:attribute name="Key" type="xs:string" use="required" />
	</xs:complexType>

    <!-- Command Types -->
    <xs:complexType name="CommandSaveFileElement">
        <xs:sequence>
            <xs:element name="Document" minOccurs="0" maxOccurs="1" type="DocumentElement" />
            <xs:element name="Report" minOccurs="0" maxOccurs="1" />
        </xs:sequence>
        <xs:attribute name="FileName" type="xs:string" use="optional" />
        <xs:attribute name="field-FileName" type="xs:string" use="optional" />
        <xs:attribute name="Overwrite" type="xs:boolean" use="optional" />
        <xs:attribute name="CreateFolder" type="xs:boolean" use="optional" />
    </xs:complexType>
    <xs:complexType name="CommandOpenFileElement">
        <xs:attribute name="FileName" type="xs:string" use="optional" />
        <xs:attribute name="field-FileName" type="xs:string" use="optional" />
    </xs:complexType>
    <xs:complexType name="CommandInvokeProcessElement">
        <xs:sequence>
            <xs:element name="Arguments" minOccurs="0" maxOccurs="1" type="ElementWithFieldSupport" />
        </xs:sequence>
        <xs:attribute name="Name" type="xs:string" use="required" />
    </xs:complexType>
    <xs:complexType name="CommandInvokeUrlElement">
        <xs:sequence>
            <xs:element name="Step" maxOccurs="unbounded">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="Request">
                            <xs:complexType>
                                <xs:sequence>
                                    <xs:element name="Url"  minOccurs="0" maxOccurs="1" type="ElementWithFieldSupport" />
                                    <xs:element name="Body" minOccurs="0" type="ElementWithFieldSupport" />
                                    <xs:element name="Header" minOccurs="0" maxOccurs="unbounded" type="CommandInvokeUrlElementRequestHeaderOrFormElement" />
                                </xs:sequence>
                                <xs:attribute name="Method" type="xs:string" use="required" />
                            </xs:complexType>
                        </xs:element>
                        <xs:element name="MultipartFormDataRequest" minOccurs="0" maxOccurs="1">
                            <xs:complexType>
                                <xs:sequence>
                                    <xs:element name="File">
                                        <xs:complexType>
                                            <xs:sequence>
                                                <xs:element name="Document" minOccurs="0" maxOccurs="1" type="DocumentElement" />
                                                <xs:element name="Report" minOccurs="0" maxOccurs="1" />
                                            </xs:sequence>
                                            <xs:attribute name="Name" type="xs:string" use="optional" />
                                            <xs:attribute name="ContentType" type="xs:string" use="optional" />
                                            <xs:attribute name="FileName" type="xs:string" use="optional" />
                                            <xs:attribute name="field-FileName" type="xs:string" use="optional" />
                                        </xs:complexType>
                                    </xs:element>
                                    <xs:element name="Url" type="ElementWithFieldSupport" />
                                    <xs:element name="Header" maxOccurs="unbounded" minOccurs="0"  type="CommandInvokeUrlElementRequestHeaderOrFormElement" />
                                    <xs:element name="FormData" maxOccurs="unbounded" minOccurs="0" type="CommandInvokeUrlElementRequestHeaderOrFormElement" />
                                </xs:sequence>
                            </xs:complexType>
                        </xs:element>
                        <xs:element name="Response" minOccurs="0" maxOccurs="1">
                            <xs:complexType>
                                <xs:sequence>
                                    <xs:element name="Property" maxOccurs="unbounded" minOccurs="0">
                                        <xs:complexType>
                                            <xs:attribute name="Name" type="xs:string" use="required" />
                                            <xs:attribute name="JsonPath" type="xs:string" use="optional" />
                                            <xs:attribute name="XPath" type="xs:string" use="optional" />
                                        </xs:complexType>
                                    </xs:element>
                                </xs:sequence>
                            </xs:complexType>
                        </xs:element>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="CommandInvokeUrlElementRequestHeaderOrFormElement">
        <xs:attribute name="Name" type="xs:string" use="required" />
        <xs:attribute name="Value" type="xs:string" use="optional" />
        <xs:attribute name="field-Value" type="xs:string" use="optional" />
    </xs:complexType>

    <!-- Common Elements -->
    <xs:complexType name="ElementWithFieldSupport">
        <xs:simpleContent>
            <xs:extension base="xs:string">
                <xs:attribute name="field-Content" type="xs:string" use="optional" />
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>

    <xs:complexType name="DocumentElement">
        <xs:attribute name="Conversion" type="xs:string" use="optional" />
    </xs:complexType>
</xs:schema>

Template​

Id​

Version​

TagFilter​

DocumentLanguage​

DocumentLocation​

Author​

Forms​

Attribute​

Data​

Outlook​

Commands​

Ablauf​

XSD-Schema​

Template

Id

Version

TagFilter

DocumentLanguage

DocumentLocation

Author

Forms

Attribute

Data

Outlook

Commands

Ablauf

XSD-Schema