Table of Contents

Die Datenschnittstelle kann über die Formulare (Forms)-Dokumentfunktion genutzt werden.

Note

Diese Funktion steht nicht in “classic” Vorlagen zur Verfügung.

Als Alternative für “classic” Vorlagen kann über die Adressschnittstellen auf Kontaktdaten zugegriffen werden. Weitere Informationen zu den verschiedenen Vorlagen Versionen finden Sie hier.

Zweck und Einsatz

Über die Datenschnittstelle können Daten verschiedener Types von unterschiedlichen Datenquellen geladen oder auch manuell eingegeben werden. Über ein Schema können die Datentypen beschrieben und als Object oder ObjectCollection für die Dokumentgenerierung bereitgestellt werden.

Datenschnittstelle.mp4

Objects und ObjectCollections

Ein Object beschreibt ein Objekt, welches durch ein Schema definiert ist. Das Objekt hat neben dem Schema eine Id und ein (übersetzbares) Label. Ein Beispiel für ein Objekt ist z.B. der Empfänger eines Briefes - auf dem Dokument ist genau einen Empfänger genannt und dieser kann über ein solches Objekt beschrieben werden.

Eine ObjectCollection ist hingegen eine Liste von Objekten. Die Liste von Objekten wird ebenfalls über ein Schema definiert und enthält eine Id und ein (übersetzbares) Label. Ein Beispiel für solch eine Liste von Objekten wäre z.B. Rechnungspositionen aus einem CRM. Auf einer Rechnung, mit einem Empfänger, erscheinen mehrere Rechnungspositionen. Die ObjectCollection erlaubt es, dass man mehrere Objekte, desselben Types, abspeichert.

MERKE
Möchten Sie in einer Vorlage einen Empfänger erlauben, benutzen Sie Objects. Möchten Sie mehrere Empfänger erlauben (z.B. in einem Protokoll), benutzen Sie eine ObjectCollection.

Aufbau

Code Block

language	xml

<FormsConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Elements>
    <Object Id="MAdaten" Label="Mitarbeiterdressen">
      [...]
    </Object>
    <ObjectCollection Id="Kundendaten" Label="Kundenadressen">
      [...]
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

Schema

Über das Schema wird die Struktur des Datentypes definiert. Dieses Schema kann verschiedene Elemente enthalten, die Informationen sammeln oder anzeigen können. Unterstützt werden hierbei dieselben Typen wie in der Formulare (Forms) Dokumentfunktion (Text, Date, YesNo, Choice), mit der Ausnahme, dass eine Group nicht unterstützt wird.

Aufbau

Code Block

language	xml

<FormsConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Elements>
    <ObjectCollection Id="Kundendaten" Label="Kundenadressen">
      <!-- Defines the ObjectCollection's elements to use in JavaScript -->
      <Schema>
        <Text Id="CompanyName" Label="Firmenname"  />
        <Text Id="Street" Label="Strasse" />
        <Text Id="PostalCode" Label="PLZ" />
        <Text Id="City" Label="Ort" />
        <Text Id="Country" Label="Land" />
      </Schema>
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

Summary

Grundsätzlich werden alle Text- und Choice-Schema-Elemente für die Anzeige eines Objects/ObjectCollection kommasepariert in der Liste der Suchresultate bzw. in der Auswahlliste angezeigt.
Möchte man hingegen nur bestimmte Felder in der Listenansicht anzeigen, kann man über Summary die angezeigten Felder konfigurieren:

Code Block

language	xml

<FormsConfiguration>
  <Elements>
    <ObjectCollection Id="Kundendaten" Label="Kundenadressen">
      <!-- Defines what schema fields are shown in the result list -->
      <Summary>
        <Text Id="CompanyName" />
        <Text Id="City" />
      </Summary>
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

Das Field muss hierbei über die Id auf ein Feld des Schema verweisen.

DataProviders

Um Daten von anderen Quellen zu laden, können DataProviders definiert werden. Für jedes Object bzw. ObjectCollection kann einer oder mehrere DataProvider hinterlegt werden.

Jeder DataProvider hat hierbei folgende Konfigurationsmöglichkeiten:

Attribute

Attributname	Beschreibung
`DisplayName`	Dient als Name für den DataProvider.

Inhalte

Elementname	Beschreibung
`SearchParameters`	Eine Suchmaske muss für den entsprechenden DataProvider konfiguriert werden. Als Syntax kommen die selben Elemente wie in der Formulare (Forms) Funktion (`Text`, `Date`, `YesNo`, `Choice`) zum Einsatz.
`Mapping`	Um die empfangenen Daten auf das `Schema` zu mappen, wird der Mapping-Syntax genutzt.
	Jeder DataProvider kann noch weitere, spezifische, Konfigurationsmöglichkeiten anbieten.

Liste der DataProviders

Folgende DataProvider stehen zur Verfügung:

Name	Beschreibung	Link
`CsvDataProvider`	Zugriff auf .csv-Dateien	CsvDataProvider
`ExcelDataProvider`	Zugriff auf Excel-Dateien	ExcelDataProvider
`HttpDataProvider`	Zugriff auf HTTP/HTTPs APIs (REST/Web APIs)	HttpDataProvider
`SqlDataProvider`	Zugriff auf SQL-Datenbanken	SqlDataProvider

Beispiel für einen DataProvider

In folgendem Beispiel wird global ein CsvDataProvider konfiguriert:

Code Block

language	xml

<FormsGlobalDataProviders>
  <CsvDataProvider DisplayName="Kundenadressen">
    <GlobalSchemaAndSummary Key="Recipients.Objects.DefaultSchema" />
    <Options>
      <FilePath>C:\home\site\wwwroot\addressdata.csv</FilePath>
      <HasHeaders>true</HasHeaders>
      <Delimiter>,</Delimiter>
    </Options>
    <SearchParameters>
      <Text Id="Firma" Label="Firmenname" />
      <Text Id="Ort" Label="Ort" />
    </SearchParameters>
    <Mapping>
      <Map Source="Firma" Target="CompanyName" />
      <Map Source="Strasse" Target="Street" />
      <Map Source="PLZ" Target="PostalCode" />
      <Map Source="Ort" Target="City" />
      <Map Source="Land" Target="Country" />
    </Mapping>
  </CsvDataProvider>
</FormsGlobalDataProviders>

Umfassendes Beispiel

In folgendem Beispiel wird zur Auswahl der Empfänger in einer Briefvorlage eine ObjectCollection mit zwei Datenschnittstellen konfiguriert: einem CsvDataProvider und einem HttpDataProvider.

XML-Konfiguration

Code Block

language	xml

<FormsConfiguration>
  <Elements>
    <ObjectCollection Id="RecipientAddressData" Label="Empfängeradressen">
    
      <!-- Defines the ObjectCollection's elements to use in JavaScript -->
      <Schema>
        <Text Id="CompanyName"  Label="Firmenname" />
        <Text Id="Street"       Label="Strasse" />
        <Text Id="PostalCode"   Label="PLZ" />
        <Text Id="City"         Label="Ort" />
        <Text Id="Country"      Label="Land" />
      </Schema>
    
        <!-- Defines what fields are shown in the result list -->
      <Summary>
        <Field Id="CompanyName" />
        <Field Id="City" />
      </Summary>
      
      <!-- Defines the DataProviders -->
      <DataProviders>
        <!-- Address data from a csv file-->
        <CsvDataProvider DisplayName="Kundenadressen">
          <Options>
            <FilePath>\\fileshare\addressdata.csv</FilePath>
            <HasHeaders>true</HasHeaders>
            <Delimiter>,</Delimiter>
          </Options>
          <SearchParameters>
            <Text Id="Firma" Label="Firmenname" />
            <Text Id="Ort" Label="Ort" />
          </SearchParameters>
          <Mapping>
            <Map Source="Firma"   Target="CompanyName" />
            <Map Source="Strasse" Target="Street" />
            <Map Source="PLZ"     Target="PostalCode" />
            <Map Source="Ort"     Target="City" />
            <Map Source="Land"    Target="Country" />
          </Mapping>
        </CsvDataProvider>
        <!-- TelSearch address provider -->
        <HttpDataProvider DisplayName="TelSearch">
          <SearchParameters>
            <Text Id="What" Label="Suchbegriff" />
          </SearchParameters>
          <Configuration>
            <Step>
              <Request Method="Get">
                <Url><![CDATA[https://tel.search.ch/api/?was={What}&key=[...]&maxnum=100]]></Url>
              </Request>
              <Response>
                <Data XPath="*[local-name()='feed']/*[local-name()='entry']">
                  <Mapping>
                    <Map Source="*[local-name()='name']" Target="CompanyName" />
                    <Map Target="Street">
                      <Map.SourceExpression><![CDATA[
                            function main()
                            {
                              const street = source("*[local-name()='street']");
                              const streetno = source("*[local-name()='streetno']");
                              return street + " " + streetno; 
                            }
                          ]]></Map.SourceExpression>
                    </Map>
                    <Map Source="*[local-name()='zip']" Target="PostalCode" />
                    <Map Source="*[local-name()='city']" Target="City" />
                    <Map SourceValue="CH" Target="Country" />
                  </Mapping>
                </Data>
              </Response>
            </Step>
          </Configuration>
        </HttpDataProvider>
      </DataProviders>
    </ObjectCollection>
    <!-- More letter related elements... -->
  </Elements>
</FormsConfiguration>

Screenshots

Manuell erfasste Objekte

1) Listenansicht: ohne hinzugefügte Objekte

3) Listenansicht mit hinzugefügten Objekten

Die unter Summary definierten Felder werden in der Listenansicht angezeigt.

2) Objekte manuell erfassen

Die unter Schema definierten Daten werden in diesem Dialog erfasst.

Über Datenschnittstelle gesuchte Objekte

1) Listenansicht: ohne hinzugefügte Objekte

4) Listenansicht mit hinzugefügten Objekten

Die unter Summary definierten Felder werden in der Listenansicht angezeigt.

2) Objekte in DataProvider suchen

3) Resultate aus DataProvider und Objekte hinzufügen

Die unter Schema definierten Daten werden mit den im DataProvider gefundenen Daten ausgefüllt.

Versions Compared

Old Version 17

New Version Current

Key

Zweck und Einsatz

Objects und ObjectCollections

Schema

Summary

DataProviders

Attribute

Inhalte

Liste der DataProviders

Beispiel für einen DataProvider

Umfassendes Beispiel

XML-Konfiguration

Screenshots

Manuell erfasste Objekte

Über Datenschnittstelle gesuchte Objekte

Page Comparison

Versions Compared

Old Version 17

New Version Current

Key

Zweck und Einsatz

Objects und ObjectCollections

Schema

Summary

DataProviders

Attribute

Inhalte

Liste der DataProviders

Beispiel für einen DataProvider

Umfassendes Beispiel

XML-Konfiguration

Screenshots

Manuell erfasste Objekte

Über Datenschnittstelle gesuchte Objekte