ExistingListDataProvider

Mit dem ExistingListDataProvider können Benutzer auf ihre eigenen Excel-Dateien zugreifen, ohne dass diese zentral erfasst und konfiguriert werden müssen. Die Auswahl der Excel-Datei erfolgt direkt über eine Dateiauswahl auf dem jeweiligen Gerät. Aus der gewählten Arbeitsmappe wird jeweils ein einzelnes Tabellenblatt eingelesen.

info

Für «verwaltete» CSV- oder Excel-Dateien, welche z.B. zentral hinterlegt sind, eignet sich der CsvDataProvider oder ExcelDataProvider besser.

Aufbau der Excel-Datei

primedocs liest das Tabellenblatt Zeile für Zeile ab Zelle A1 ein und übernimmt jede Zeile als Datensatz. Formatierungen, Titel oder Leerzeilen erkennt primedocs dabei nicht als solche. Das Tabellenblatt muss deshalb eine einfache, «saubere» Tabelle enthalten:

• Beginn in Zelle A1: Die Tabelle beginnt in der ersten Zeile und der ersten Spalte. Leere Zeilen oder Spalten davor werden als eigene Zeilen bzw. Spalten eingelesen. Ist die erste Zeile leer, gilt sie mit Kopfzeile trotzdem als Kopfzeile: Die Spalten heissen dann A, B, C usw., und die eigentlichen Überschriften erscheinen als erster Datensatz.
• Kopfzeile (optional): Zeile 1 enthält die Spaltenüberschriften. Jede Spalte sollte eine eigene, eindeutige Überschrift haben. Leere und doppelte Überschriften ergänzt primedocs, siehe Leere und doppelte Überschriften. Ein Titel oder eine Beschreibung oberhalb der Kopfzeile ist nicht möglich.
• Ein Datensatz pro Zeile: Jede Zeile unterhalb der Kopfzeile enthält genau einen Datensatz. Zwischenüberschriften und Zwischensummen übernimmt primedocs als zusätzliche Datensätze, ein über mehrere Zeilen verteilter Datensatz wird zu mehreren Datensätzen.
• Keine leeren Zeilen: Leere Zeilen innerhalb oder unterhalb der Tabelle erscheinen als leere Datensätze. Das gilt auch für Zeilen, die nur formatiert sind (z.B. mit Rahmen oder Hintergrundfarbe). Nicht benötigte Zeilen unterhalb der Tabelle deshalb ganz löschen (z.B. über das Kontextmenü der Zeilenköpfe), nicht nur ihren Inhalt leeren.
• Keine verbundenen Zellen: Bei verbundenen Zellen steht der Wert nur in der ersten Zelle, die übrigen Zellen sind leer.
• Nur eine Tabelle pro Tabellenblatt: Weitere Tabellen, Notizen oder Auswertungen auf ein eigenes Tabellenblatt verschieben. Mit EnableCustomSheetSelection="true" kann der Benutzer das passende Tabellenblatt auswählen.

Beispiel für ein korrekt aufgebautes Tabellenblatt:

	A	B	C	D
1	Vorname	Nachname	Ort	Eintritt
2	Anna	Muster	Bern	01.03.2024
3	Peter	Meier	Zug	15.08.2025

Ausgeblendete oder herausgefilterte Zeilen werden ebenfalls eingelesen. Eine als Tabelle formatierte Excel-Tabelle (Als Tabelle formatieren) funktioniert, sofern sie in Zelle A1 beginnt.

Kopfzeile oder nicht

Beim Laden der Datei legt der Benutzer mit einem Kontrollkästchen fest, ob die Tabelle eine Kopfzeile hat. Standardmässig ist es aktiviert.

• Mit Kopfzeile: Die Überschriften dienen als Spaltennamen im Mapping-Dialog. Entspricht eine Überschrift der Id eines Schema-Felds (ohne Beachtung der Gross-/Kleinschreibung), ordnet primedocs die Spalte automatisch zu, siehe Zusammenspiel mit Mapping und Schema.
• Ohne Kopfzeile: Bereits Zeile 1 gilt als Datensatz. Die Spalten heissen wie in Excel A, B, C usw. und werden im Mapping-Dialog manuell zugeordnet.

Leere und doppelte Überschriften

Damit jede Spalte einen eigenen Namen hat, ergänzt primedocs leere und mehrfach vorkommende Überschriften:

• Leere Überschrift: Die Spalte erhält ihren Spaltenbuchstaben, z.B. B.
• Doppelte Überschrift: Ab dem zweiten Vorkommen erhält die Spalte einen Zähler, z.B. Name (2).

Kommt ein so gebildeter Name bereits als Überschrift vor, zählt primedocs weiter, z.B. B (2).

Beispiel: Die Kopfzeile Name, (leer), Name, (leer), Name ergibt die Spaltennamen Name, B, Name (2), D und Name (3). Hat ein Schema-Feld die Id Name, ordnet primedocs nur die erste dieser Spalten automatisch zu. Die übrigen Spalten lassen sich im Mapping-Dialog manuell zuordnen.

Werte und Formate

primedocs übernimmt den Wert einer Zelle, nicht ihre Anzeige in Excel:

• Zahlen werden ohne Zahlenformat übernommen, z.B. 1234.5 statt CHF 1'234.50.
• Datumswerte werden im Format JJJJ-MM-TT übernommen, z.B. 2024-03-01.
• Formeln liefern den zuletzt in Excel berechneten Wert.
• Führende Nullen (z.B. bei Postleitzahlen oder Personalnummern) bleiben nur erhalten, wenn die Spalte als Text formatiert ist.

Dateiformat

Unterstützt werden Excel-Arbeitsmappen im Format .xlsx, in primedocs Desktop zusätzlich .xlsm. In primedocs Web darf die Datei höchstens 5 MB gross sein. CSV-Dateien und das alte Format .xls werden nicht unterstützt.

In primedocs Desktop darf die Arbeitsmappe beim Laden in Excel geöffnet bleiben. primedocs liest dann den zuletzt gespeicherten Stand der Datei.

Konfiguration

Der ExistingListDataProvider kann in der Dokumentfunktion Forms optional mit einem Namen versehen werden (z.B. «Excel-Export aus CRM»), um die Erkennung für Benutzer zu erleichtern. Eine weitere Konfiguration ist nicht zwingend erforderlich.

<ExistingListDataProvider DisplayName="Excel Export aus CRM" 
 DefaultSheetName="Daten" EnableCustomSheetSelection="true" AutoAddAllEntries="true"
 SkipMappingIfComplete="true" />

Neben dem DisplayName können folgende optionale Attribute definiert werden. Diese steuern, wie die Excel-Datei beim Import verarbeitet wird und welche Auswahlmöglichkeiten dem Benutzer angezeigt werden:

• DefaultSheetName: Name des vorausgewählten Tabellenblatts der Excel-Datei. Ist kein Wert definiert oder wird das Tabellenblatt nicht gefunden, wird automatisch das erste Tabellenblatt verwendet.
• EnableCustomSheetSelection (true/false): Zeigt dem Benutzer ein Dropdown zur manuellen Auswahl des Tabellenblatts an.
• AutoAddAllEntries (true/false): Fügt automatisch alle Listeneinträge hinzu, sodass keine manuelle Auswahl durch den Benutzer erforderlich ist.
• SkipMappingIfComplete (true/false): Überspringt den Mapping-Dialog, wenn alle Felder automatisch zugeordnet werden können, d.h. wenn die Spalten der Excel-Datei mit dem konfigurierten Mapping bzw. Schema übereinstimmen.

Enthält das eingelesene Tabellenblatt keinen Datensatz (z.B. ein leeres Blatt oder eines mit nur einer Kopfzeile), meldet primedocs Web «Das Arbeitsblatt enthält keine Einträge.» und primedocs Desktop «Die Datei konnte nicht gelesen werden. […]». Das kann auch passieren, wenn das Tabellenblatt aus DefaultSheetName fehlt und primedocs deshalb auf ein leeres erstes Tabellenblatt ausweicht. Danach ein anderes Tabellenblatt wählen (mit EnableCustomSheetSelection="true") oder eine andere Datei laden.

Zusammenspiel mit Mapping und Schema

Wie bei den übrigen Providern werden die eingelesenen Spalten über ein Mapping auf das Schema des Object bzw. der ObjectCollection abgebildet. Können anhand der Spaltenüberschriften alle Schema-Felder automatisch zugeordnet werden, lässt sich der Mapping-Dialog mit SkipMappingIfComplete="true" überspringen. Andernfalls nimmt der Benutzer die Zuordnung im Mapping-Dialog vor.