1 Zweck und Einsatz
2 Objects und ObjectCollections
3 Schema
4 Summary
5 DataProviders
- 5.1 Attribute
- 5.2 Inhalte
- 5.3 Liste der DataProviders
- 5.4 Beispiel für einen DataProvider
6 Umfassendes Beispiel
- 6.1 XML-Konfiguration
- 6.2 Screenshots
  - 6.2.1 Manuell erfasste Objekte
  - 6.2.2 Über Datenschnittstelle gesuchte Objekte

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

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

Als Alternative für “classic” Vorlagen kann über die Adressschnittstellen (classic) 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.

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

<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

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

<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

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

Inhalte

Elementname	Beschreibung

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

Name	Beschreibung	Link
`CsvDataProvider`	Zugriff auf .csv-Dateien	CsvDataProvider
`ExcelDataProvider`	Zugriff auf Excel-Dateien	ExcelDataProvider
`ExistingListDataProvider`	Zugriff auf lokale Excel-Dateien, welche der Benutzer selbst auswählen kann.	ExistingListDataProvider
`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:

<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

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