Versandsteuerung (Successor Documents)

Diese Dokumentfunktion (englisch Dispatch Manager) aktiviert die Versandverwaltung für Folgedokumente, die aus einem primären Dokument abgeleitet werden, beispielsweise Adressetiketten, Beilagen oder Begleitschreiben. Die Folgedokumente werden pro Objekt (z.B. pro Empfänger) erzeugt und über definierte Ziele und Aktionen weiterverarbeitet.

Der Dialog der Versandsteuerung: pro Empfänger ein Ziel (z.B. Etiketten), verarbeitet über die Aktionen im unteren Bereich.

Funktionsweise

Die Verteilung iteriert über die vom Benutzer ausgewählten Objekte einer ObjectCollection. Welche Collection verteilt wird, bestimmt das Attribut SourceObjectCollectionId. Sie kann aus Forms, Fields oder Data stammen. Ein optionaler Filter blendet einzelne Einträge aus, bevor der Dialog aufgebaut wird. Für jedes ausgewählte Objekt wird der Code des zugehörigen Target ausgewertet. Dieser Code liefert die Feld-Mappings (Forms- bzw. Datenfeldwerte) für das jeweilige Folgedokument, also die Werte, mit denen die Ziel-Vorlage befüllt wird. Anschliessend wird pro Objekt ein Folgedokument generiert. Die Ergebnisse eines Ziels werden zu einem PDF zusammengeführt.

Ausgelöst wird der Vorgang über die Aktionen (Actions): GenerateAction blendet im Versandsteuerung-Dialog (WPF) die Schaltfläche «Generieren» ein, PrintAction die Schaltfläche «Drucken».

Wird der Dialog bestätigt, wird die Zuordnung der Ziele zu den Empfängern im Dokument selbst gespeichert (CustomXMLPart), auch dann, wenn weder generiert noch gedruckt wird. Das Dokument kann geschlossen und erneut geöffnet werden, die Auswahl bleibt erhalten. Wird der Dialog abgebrochen, wird nichts gespeichert.

Beim erneuten Öffnen wird die gespeicherte Liste wiederhergestellt und ersetzt die Werte der ObjectCollection. Erst ohne gespeicherte Daten wird die Liste aus der ObjectCollection aufgebaut. Ein Ziel, das in der Konfiguration nicht mehr existiert, wird dabei als «kein Ziel» wiederhergestellt. Wiederhergestellt wird auch die zuletzt getroffene Auswahl der Empfänger, siehe Versanddialog.

Geltungsbereich

Die Versandsteuerung steht ausschliesslich im primedocs Desktop Client zusammen mit dem Word-COM-Add-In zur Verfügung (Legacy, Windows). In den Office Web Add-Ins und in primedocs Web gibt es keine Entsprechung. Ausgeliefert ab Version 4.1.10020.0. Die Quellen Fields und Data sowie Summary und Filter folgen mit einem späteren Build.

Über PrintAction lässt sich pro Ziel ein Drucker festlegen. «Drucken» öffnet die Druckerwahl je Versanddokument-Typ.

Grundaufbau

<SuccessorDocumentConfiguration>
  <DistributeByObject SourceObjectCollectionId="Forms.Empfaenger">
    <Targets>
      <Target Name="Etikett" Label="Adressetikett" Icon="Tag">
        <TagFilter>
          <Tag>label</Tag>
        </TagFilter>
        <Code>
          function main() { return $("RecipientId"); }
        </Code>
      </Target>
    </Targets>
    <Actions>
      <PrintAction Enabled="true">
        <Default TargetName="Etikett" Printer="LabelPrinter" Tray="Tray2" />
      </PrintAction>
      <GenerateAction Enabled="true" />
    </Actions>
    <Summary>
      <Field Id="Name" />
      <Field Id="Versandart" QuickAccess="true" />
    </Summary>
    <Filter>$("DistributeObject.Aktiv") === 'true'</Filter>
  </DistributeByObject>
</SuccessorDocumentConfiguration>

DistributeByObject

Steuert die Verteilung der Folgedokumente pro Objekt. Das Attribut SourceObjectCollectionId bestimmt, welche ObjectCollection verteilt wird. Die Kindelemente folgen in der Reihenfolge Targets (welche Folgedokumente), Actions (was damit geschieht), Summary (wie eine Zeile im Dialog beschriftet ist) und Filter (welche Einträge überhaupt erscheinen).

Quell-ObjectCollection (SourceObjectCollectionId)

Attribut	Pflicht	Beschreibung
DistributeByObject/@SourceObjectCollectionId	nur mit Summary	Die zu verteilende ObjectCollection in der Form <Quelle>.<Id>, z.B. Forms.Empfaenger. Ohne Attribut wird die erste ObjectCollection der Forms-Konfiguration verwendet.

Als Quelle sind Forms, Fields und Data zulässig. Für die Schreibweise gilt:

• Die Quelle wird ohne Beachtung der Gross-/Kleinschreibung erkannt: forms.Empfaenger und Forms.Empfaenger sind gleichwertig.
• Nur der erste Punkt trennt Quelle und Id. Eine Id, die selbst Punkte enthält, bleibt dadurch vollständig erhalten.
• Eine Id ohne Quellenpräfix wird als Konfigurationsfehler abgewiesen und nicht stillschweigend als Forms gelesen. Dasselbe gilt für Forms. und .Empfaenger.
• Referenzierbar sind nur ObjectCollections der obersten Ebene (direkte Elemente sowie Elemente innerhalb einer Gruppe). Eine Collection, die in einem Object oder in einer anderen ObjectCollection steckt, lässt sich nicht adressieren, ebenso wenig eine, die erst in einer adaptiven Dateneingabemaske entsteht. Global konfigurierte Collections (GlobalElements, GlobalGroups, globale Schemas) werden dagegen aufgelöst.

Die Vorlagenprüfung meldet einen Fehler, wenn die referenzierte Dokumentfunktion in der Vorlage nicht aktiv ist oder die Collection dort nicht existiert. Die Meldung listet die vorhandenen Ids auf. Im Word-Menüband wird die Versandsteuerung nur angeboten, wenn mindestens ein Ziel konfiguriert ist und die referenzierte Collection existiert.

Forms-Quelle mit UseDotsForHierarchy

Eine Forms-Konfiguration mit UseDotsForHierarchy="true" unterstützt die Versandsteuerung nicht: Der Versanddialog bricht mit einem Fehler ab. Die Quellen Fields und Data sind davon nicht betroffen, auch wenn Forms in derselben Vorlage die Option gesetzt hat.

Sobald ein Summary konfiguriert ist, wird SourceObjectCollectionId zur Pflicht, denn die Feld-Ids des Summary gelten nur für genau eine Collection, und die «erste in Forms»-Ersatzregel würde beim Umsortieren der Forms-Konfiguration unbemerkt auf ein anderes Schema zeigen.

Unterschiede zwischen den Quellen

Forms beschreibt eine Bedienoberfläche, Fields und Data beschreiben nur Daten. Daraus ergeben sich Einschränkungen für die Detailansicht einer Zeile (hinter dem Stift-Symbol):

	Forms	Fields	Data
Feldbeschriftung	Label, übersetzbar	keine, es wird die Id angezeigt	keine, es wird die Id angezeigt
QuickAccess-Auswahlfelder	ja	nein	nein
Pflichtfeld und Validierungsmeldung	ja	nein	nein
Data Provider im Zeileneditor	ja	nein	nein
Eigene Summary der Collection	ja	nein	nein

Die Versandliste selbst ist davon nicht betroffen: Sie zeigt bei allen drei Quellen nur die Werte, mit Komma verbunden. QuickAccess="true" auf einer Fields- oder Data-Quelle wird als Konfigurationsfehler gemeldet, statt wirkungslos zu bleiben.

Targets

Definiert die möglichen Ziele (Folgedokument-Typen).

Element / Attribut	Pflicht	Beschreibung
Target	–	Ein einzelnes Ziel. Mehrere Ziele sind möglich.
Target/@Name	ja	Eindeutiger Bezeichner des Ziels, der in den Aktionen über TargetName referenziert wird.
Target/@Label / @translate-Label	optional	Anzeigename bzw. Übersetzungsschlüssel des Ziels.
Target/@Icon	optional	Symbol für die Oberfläche.
Target/TagFilter/Tag	faktisch ja	Schränkt das Ziel auf Vorlagen mit den angegebenen Tags ein. Mehrere Tag-Einträge möglich. Das Schema erlaubt ein Ziel ohne TagFilter, zur Laufzeit wird ein solches Ziel aber übersprungen.
Target/Code	ja	JavaScript, das den Wert für die Verteilung pro Objekt liefert.
GlobalTargets/@Key	optional	Referenz auf eine globale Ziel-Definition statt eines inline definierten Target.

Actions

Definiert, was mit den erzeugten Folgedokumenten geschieht.

Element / Attribut	Beschreibung
PrintAction/@Enabled	Aktiviert die Druckaktion und die Schaltfläche «Drucken» im Versandsteuerung-Dialog (Standard: true).
PrintAction/Default/@TargetName	Referenziert das zu druckende Target über dessen Name.
PrintAction/Default/@Printer / @Tray	Optionaler Drucker bzw. Papierfach.
GenerateAction/@Enabled	Aktiviert die Generierungsaktion und die Schaltfläche «Generieren» im Versandsteuerung-Dialog (Standard: true).
GlobalActions/@Key	Referenz auf eine globale Aktions-Definition.

hinweis

Ziele und Aktionen lassen sich über GlobalTargets bzw. GlobalActions als Globale Konfiguration zentral pflegen und über mehrere Vorlagen wiederverwenden.

Summary

Legt fest, welche Felder eine Zeile im Versanddialog beschriften. Die Darstellung in Forms bleibt davon unberührt. Das Summary wirkt nur im Versanddialog. Ohne Summary gilt die Ersatzregel: Eine Forms-Collection verwendet ihre eigene Summary, eine Collection aus Fields oder Data zeigt alle Felder ihres Schemas.

Element / Attribut	Pflicht	Beschreibung
Summary/Field	mindestens eines	Ein Feld der Zeile. Die Reihenfolge der Einträge bestimmt die Reihenfolge in der Liste.
Summary/Field/@Id	ja	Feld-Id aus dem Schema der über SourceObjectCollectionId gewählten ObjectCollection. Zulässig sind nur Wertfelder. Verschachtelte Object- und ObjectCollection-Elemente lassen sich nicht referenzieren, denn eine Zeile bleibt eine Zeile.
Summary/Field/@QuickAccess	optional	true erzeugt eine direkt in der Liste bearbeitbare Spalte (Standard: false). Nur für Auswahlfelder (Choice) einer Forms-Quelle zulässig.

Ein leeres Summary und doppelte Feld-Ids sind Konfigurationsfehler. Feld-Ids, die das Schema der gewählten Collection nicht kennt, werden ebenfalls gemeldet.

Filter

Optionales JavaScript-Prädikat, das entscheidet, welche Einträge der ObjectCollection überhaupt in den Versanddialog gelangen. Es wird einmal pro Eintrag ausgewertet. Die Felder des jeweiligen Eintrags sind dabei über $("DistributeObject.<FeldId>") lesbar, genau wie im Code eines Ziels bei der Generierung. Die übrigen Felder des Dokuments sind wie gewohnt über $() lesbar. Im Vorlageneditor wird der Inhalt von Filter wie ein Code-Element als JavaScript hervorgehoben und mit Autovervollständigung unterstützt.

<Filter>$("DistributeObject.Aktiv") === 'true'</Filter>

Zulässig sind entweder reine Ausdrücke oder Funktionsdeklarationen mit einer main-Funktion (dieselben beiden Formen wie beim Code eines Ziels). Ein vorhandenes, aber leeres Filter-Element ist ein Konfigurationsfehler.

Ausgefilterte Einträge erscheinen nur im Versanddialog nicht. Im Formular selbst bleiben sie unverändert sichtbar und die Forms-Daten werden nicht angetastet.

Der Filter bestimmt die Ausgangsliste des Dialogs. Sie wird beim Öffnen ohne gespeicherte Versanddaten verwendet, beim Zurücksetzen über «Einträge auf Dokumentwerte zurücksetzen» und als Auswahl für «Kopie einfügen». Sind bereits Versanddaten im Dokument gespeichert, zeigt der Dialog diese gespeicherte Liste unverändert an. Ein Eintrag, der erst nachträglich ausgefiltert würde (z.B. weil im Formular Aktiv abgewählt wurde), verschwindet deshalb erst nach dem Zurücksetzen aus der Liste.

Fehler im Filter blenden nichts aus

Lässt sich der Filter nicht auswerten, zeigt der Dialog alle Einträge und meldet «Der konfigurierte Filter konnte nicht angewendet werden. Es werden alle Einträge angezeigt.». Der Fehler wird protokolliert. Ein fehlerhafter Filter schränkt den Versand also nicht ein, sondern hebt die Einschränkung auf.

Versanddialog

Auswahl der Empfänger. Beim ersten Öffnen sind alle Zeilen angehakt. Der Versand an alle ist der Normalfall, Ausnahmen werden abgewählt. Sobald Versanddaten im Dokument gespeichert sind, gilt wieder die zuletzt getroffene Auswahl.

Schaltflächen. Beide Aktionen verarbeiten ausschliesslich die ausgewählten Zeilen. Solange keine Zeile ausgewählt ist, sind «Generieren» und «Drucken» deshalb deaktiviert und der Dialog zeigt links davon den Hinweis «Bitte mindestens einen Eintrag auswählen.».

Pflichtfelder. Eine ausgewählte Zeile mit leerem Pflichtfeld blockiert beide Aktionen, auch in verschachtelten Objekten und Sammlungen der Zeile. Nach dem ersten Klick erscheint der Fehlertext unter der Liste. Er verschwindet, sobald die Zeile abgewählt, gelöscht oder über «Bearbeiten» korrigiert ist. Abgewählte Zeilen zählen nicht, weil sie nicht verschickt werden. Zeilen aus dem Formular sind im Dialog gesperrt und lassen sich bei einem leeren Pflichtfeld nur abwählen.

Werte für alle Zeilen setzen. Über der Ziel-Spalte und über jeder QuickAccess-Spalte steht ein Auswahlfeld, das den gewählten Wert in alle Zeilen schreibt. Für ein als ReadOnly konfiguriertes Auswahlfeld entsteht kein solches Kopfzeilen-Feld. Es ist ein reiner Setz-Befehl und zeigt nicht den Zustand der Zeilen: Nach dem Anwenden springt es auf den Leereintrag zurück, damit derselbe Wert erneut gesetzt werden kann. Zeilen, die aus dem Formular übernommen und dort gesperrt sind, werden nie überschrieben.

Ausgabe

Die Schaltfläche «Generieren» legt die erzeugten Dateien immer im Ordner <Downloads>\primedocs ab. Fehlt der Ordner, wird er angelegt. Nach Abschluss wird er automatisch im Explorer geöffnet.

• Dateiname: {TargetName}_{yyyyMMddHHmmss}.pdf. Der Zielname stammt aus Target/@Name, ergänzt um den Zeitstempel der Generierung.
• Format: immer PDF. Ein anderes Ausgabeformat (z.B. DOCX) gibt es nicht.
• Bündelung: eine Datei pro Ziel, unabhängig von der Anzahl Empfänger. Fünf Empfänger für das Ziel «Etikett» ergeben ein einzelnes PDF mit fünf Seiten.

Ablageort, Dateiname und Format sind nicht konfigurierbar, denn das Schema der Dokumentfunktion kennt dafür kein Element und kein Attribut. Für die gesteuerte Ablage in GEVER, SharePoint oder auf einem Netzlaufwerk gibt es die Ausgabeverwaltung und Connect. Beide wirken jedoch auf das generierte Hauptdokument, nicht auf die Folgedokumente der Versandsteuerung.

Ziele ohne eindeutige Vorlage werden still übersprungen

Der TagFilter eines Ziels muss in der Sprache des Dokuments genau eine Word-Vorlage treffen. Trifft er keine oder mehrere Vorlagen, wird dieses Ziel ohne Meldung übersprungen. Dasselbe gilt für ein Ziel ganz ohne TagFilter und für ein Ziel, dessen Name in der Konfiguration nicht mehr vorkommt. Die Generierung meldet trotzdem Erfolg, das PDF des betroffenen Ziels fehlt aber einfach. Tags und Dokumentsprache deshalb so wählen, dass die Auflösung immer eindeutig ist.

Drucken

Die Schaltfläche «Drucken» öffnet die Druckerwahl mit je einem Drucker- und einem Fach-Auswahlfeld pro ausgewähltem Ziel. Konfigurierbar sind ausschliesslich PrintAction/@Enabled (Standard: true) sowie pro Ziel ein Default-Eintrag mit @TargetName, @Printer und @Tray.

Alles Weitere ist fest vorgegeben: Die Anzahl Kopien ist auf 1 gesetzt. Der Druckauftrag setzt ausser Drucker und Papierfach keine weiteren Optionen. Duplex, Papierformat und Farbwahl folgen den Standardeinstellungen des Druckertreibers und lassen sich weder in der Vorlage noch im Dialog steuern.

«Default» ist nur eine Erstbelegung

Der Drucker wird in drei Stufen ermittelt: zuerst die gemerkte Benutzerauswahl, dann PrintAction/Default, zuletzt der Windows-Standarddrucker (und falls keiner als Standard markiert ist, der erste verfügbare Drucker). Die Konfigurationsvorgabe greift damit nur, solange der Benutzer noch keine eigene Auswahl bestätigt hat. Ab der ersten Benutzerauswahl wird sie dauerhaft überschrieben. Die gemerkte Auswahl liegt in den benutzerbezogenen Client-Einstellungen des Desktop Clients und ist weder über die Organisationseinheit noch über das Benutzerprofil steuerbar.