primedocs Connect is an XML interface that can be used to partially or fully automate document generation. Connect can be processed on both the client and server side.

<primedocsConnect>
   ...
</primedocsConnect>

Template

The Template-element can be used to specifically address a template or filter based on tags.

Id

The Id-attribute is used to select the template for document processing. The exact GUID of the template must be transferred as the specification for this.

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

Version

The Version="Draft" attribute can be used to access a template in draft mode.

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

TagFilter

The TagFilter is only implemented on the client side.

The TagFilter-element can be used to specify tags for filtering.

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

AND-links are defined within a tag element separated by semicolons, OR-links by several tag elements. The example above shows all templates that are marked with Tag1 or Tag2, Tag3 and Tag4.

By default, filtering is expected to return only one template as a result.
If the query returns several templates, an error message is displayed.

The AllowTemplatePicker attribute can be used to optionally display a selection dialog (“TemplatePicker”), which then shows all resulting templates.

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

The “TemplatePicker” is also displayed if no Template-element is specified.

DocumentLanguage

The target document language can be specified via the DocumentLanguage-element with the code attribute.

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

If no DocumentLanguage is specified, the default language of the primedocs data source is used.

Author

The Author-element can be used to start document generation with a specific profile and a specific theme.

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

A specific profile can be selected via the Id-attribute. The ThemeId-attribute can be used to select a specific theme.

If no explicit profile is specified, the current profile of the primedocs client is used.
A profile must be specified on the server side, otherwise an error will be returned.

Forms

The documentfunction Forms is used to query data before the document is generated. The configured properties can also be pre-filled via the Connect interface.

<primedocsConnect>
  <Forms>
	<!-- "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>

Connect is only used to specify the “target ID” of the respective element together with the content. A distinction is made between 3 different types:

“Normal” elements can be filled via <Value Key="ElementId">Value</Value>.
Objects (Object), such as personal details via the parent element <Object Key="ElementId" /> together with <Value Key="ElementId">Value</Value> for the child elements.
Object lists (ObjectCollection) for lists of data, where each data record is in an Item-element.

Data

In conjunction with the Data document function, Data can be used to transfer data via Connect that should not be displayed or queried in the Forms properties dialog beforehand.

<primedocsConnect>
  <Data>
	<!-- "Simple" mappings to Text -->
    <Value Key="InternalId">123456789</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>

The logic here is identical to the transfer to forms, i.e. there are:

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

Commands

Commands can be applied after the actual document creation (e.g. conversion to a PDF document). At the same time, the error and abort commands are evaluated at document level.

Commands can be started after the following events:

OnSuccess: On successful document generation.
OnError: If an error occurs during document generation, e.g. an incorrect template ID is specified.
OnCancel: If the user cancels the document generation, e.g. via the Forms dialog.
OnExit: After completion of the document generation, it does not matter whether everything ran successfully or not.

Sequence

The Command sequence depends on the status of the document generation:

Success:
OnSuccess, then OnExit
Error:
OnError, then OnExit
Cancel:
OnCancel, then OnExit
On Error in OnSuccess:
OnError, then OnExit

In the event of an error in OnError, OnCancel, OnExit:

Immediate abort

Example:

<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 this example, a document is generated with the template 30b55516-80b5-41d7-801b-b31d6da376ac with the Subject “Hello Connect”.
After successful document generation, the document is saved to a folder using the SaveFile- command.

All available commands are documented here: After document generation (Commands)

XSD-Schema

Below you will find the schematic in 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="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="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: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>

Structure