Datenschnittstelle

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

warnung

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 sind hier verfügbar.

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.

hinweis

MERKE
Für genau einen Empfänger in einer Vorlage Objects verwenden. Für mehrere Empfänger (z.B. in einem Protokoll) eine ObjectCollection verwenden.

Aufbau

<FormsConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Elements>
    <Object Id="MAdaten" Label="Mitarbeiteradressen">
      [...]
    </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>
        <Field Id="CompanyName" />
        <Field 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 translate-DisplayName	Vordefinierter Anzeigename bzw. dynamischer Anzeigename aus den Globalen Übersetzungen. Hinweis: Nur eines der Attribute darf gesetzt werden. translate-DisplayName kann ab der Version 4.0.30114.0 verwendet werden.

Inhalte

Elementname	Beschreibung
SearchParameters (optional)	Suchmaske für den entsprechenden DataProvider. Als Syntax kommen die selben Elemente wie in der Formulare (Forms) Funktion (Text, Date, YesNo, Choice) zum Einsatz. Fehlt das Element, wird ohne Eingabemaske automatisch über den gesamten Bestand gesucht (z.B. statische Abfragen oder Endpunkte ohne Filter).
Mapping	Um die empfangenen Daten auf das Schema zu mappen, wird der Mapping-Syntax genutzt.
…	Jeder DataProvider kann noch weitere, spezifische, Konfigurationsmöglichkeiten anbieten.

hinweis

Für Laufzeitwerte, die ein DataProvider an ein YesNo-Feld liefert, werden true und false unabhängig von der Gross-/Kleinschreibung sowie mit umgebenden Leerzeichen akzeptiert. Auch 1 für wahr und 0 für falsch sind gültig. Dies gilt für alle DataProvider.

Andere Werte wie yes, no oder eine leere Zeichenfolge sind ungültig. Solche Werte werden bereits beim Laden der Daten erkannt und als Fehler gemeldet, der das betroffene Feld und den Wert nennt — die Fehlkonfiguration fällt damit früh auf, statt ein falsches Dokument zu erzeugen. In der Suchmaske eines DataProviders bleibt der Dialog offen und zeigt einen Suchfehler an.

Für Konfigurationswerte im Vorlagen-XML gelten weiterhin ausschliesslich die kanonischen XML-Boolean-Werte true, false, 1 und 0; True ist dort ungültig.

Liste der DataProviders

Folgende DataProvider stehen zur Verfügung:

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
LdapDataProvider	Zugriff auf LDAP-/LDAPS-Verzeichnisse (z.B. Active Directory)	LdapDataProvider
CodeDataProvider	Liefert Daten über ein JavaScript-Snippet (berechnet, aus Suchparametern oder Connect-Daten).	CodeDataProvider
ProviderPipeline	Mit diesem speziellen DataProvider können Daten nach der Suche automatisch nachgeladen werden. Dabei kann man getrennte DataProvider für Searching und Loading definieren.	ProviderPipeline

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>

Screenshots

Manuell erfasste Objekte

1) Listenansicht: ohne hinzugefügte Objekte

2) Objekte manuell erfassen

Die unter Schema definierten Daten werden in diesem Dialog erfasst.

3) Listenansicht mit hinzugefügten Objekten

Die unter Summary definierten Felder werden in der Listenansicht angezeigt.

Über Datenschnittstelle gesuchte Objekte

1) Listenansicht: ohne hinzugefügte Objekte

2) Objekte in DataProvider suchen

3) Resultate aus DataProvider hinzufügen

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

4) Listenansicht mit hinzugefügten Objekten

Die unter Summary definierten Felder werden in der Listenansicht angezeigt.