Technischer Artikel

PDF-Formulare vereinen: Regeln für doppelte Felder

Man tippt einen Namen in das Applicant-Feld auf Seite 1 eines frisch zusammengeführten Antragspakets, tabt weiter, und in vielen Viewern füllt sich das Applicant-Feld auf Seite 6 mit demselben Text. Niemand hat diese beiden Steuerelemente verbunden. Teil 1 und Teil 3 des Pakets stammen von unterschiedlichen Autoren, beide nannten ein Top-Level-Feld Applicant, und ein PDF-Formular identifiziert ein Feld über seinen vollqualifizierten Namen. Zwei Felder mit einem Namen sind, was das Dateiformat angeht, ein Feld, das zweimal gezeichnet wird

Die Lösung ist, vor dem Merge zu entscheiden, was ein geteilter Name bedeuten soll: verweigern, mit Absicht behalten oder den Neuankömmling umbenennen. Hinterher zu entscheiden ist viel schwerer, als es klingt

Was ISO 32000 unter einem Feldnamen versteht

Ein Feldname ist Identität, und die Spezifikation sagt das. ISO 32000-1 §12.7.3.2 baut den vollqualifizierten Namen aus dem partiellen Namen (dem T-Eintrag) eines Felds und jedes seiner Vorfahren auf, verbunden mit Punkten. Dieselbe Seite erlaubt mehreren Field-Dictionaries, sich einen vollqualifizierten Namen zu teilen, und beschreibt sie als unterschiedliche Repräsentationen desselben zugrunde liegenden Felds, die sich eigentlich nur in der Darstellung unterscheiden sollten. Die Fields-Arrays zweier unabhängig erstellter Formulare aneinanderzuhängen erzeugt genau diese Anordnung aus Versehen

Der Schaden hängt davon ab, was die kollidierenden Felder enthielten. Ein Date, das auf dem einen Formular das Geburtsdatum und auf dem anderen das Unterschriftsdatum meinte, hat jetzt einen einzigen Wert-Slot, und welcher Wert sich der Viewer zurechtlegt, landet an beiden Stellen. Ein Total auf einem Spesenblatt und ein Total auf einem Einzahlungsformular werden auseinanderlaufen, sobald einer von beiden berechnet wird. Signaturfelder sind der schlimmste Fall: zwei Signatur-Widgets auf verschiedenen Seiten, ein Name, und keine saubere Antwort darauf, welches Widget der Unterzeichner tatsächlich gebilligt hat

Groß- und Kleinschreibung zählt ebenfalls. Partielle Namen sind Text-Strings, und nichts in der Spezifikation faltet sie, also sind Total und total zwei verschiedene Felder. Eine Kollisionsprüfung, die Namen vor dem Vergleich lowercased, meldet Konflikte, die nicht existieren, und benennt unter einer Umbenennungs-Strategie Felder um, die niemand anfassen musste

Namen prüfen, bevor sich etwas bewegt

PDF Library for Delphi behandelt die Kollision in MergeDocumentEx(DocumentID, DuplicateFieldStrategy), das das durch DocumentID identifizierte Dokument in das aktuell ausgewählte Dokument zusammenführt und jeden Namenskonflikt klärt, bevor ein einziges Objekt umnummeriert wird. Die Strategie ist ein TPDFlibDuplicateFieldStrategy-Wert: dfsReject, dfsMerge oder dfsAutoNumber. Das schlichte MergeDocument verkettet die beiden Wurzel-Feld-Arrays weiterhin unverändert, was die richtige Wahl ist, wenn man beide Formulare besitzt und weiß, dass ihre Namen disjunkt sind

Die Reihenfolge ist der ganze Entwurf. Ein Merge muss die Objektnummern des eingehenden Dokuments verschieben, damit sie nicht mit denen des Ziels kollidieren, seine Seiten in den Seitenbaum des Ziels einnähen und seine Felder an das Formular anhängen. Taucht eine Kollision erst nach diesen Schritten auf, ist die Verweigerung nicht mehr gratis — das Ziel hat bereits Seiten geschluckt, die Objekte der Quelle tragen Nummern, mit denen keine der Dateien begann, und der Aufrufer hat keinen Zustand, auf den er zurückfallen könnte, außer beide Dateien neu von der Platte zu laden. MergeDocumentEx sammelt zuerst die Top-Level-Feldnamen beider Dokumente in eine geordnete, groß-/kleinschreibungssensible Menge und wendet die Strategie gegen diese Menge an. Unter dfsReject lässt eine Kollision den Aufruf 0 zurückgeben, mit LastErrorCode auf 705 gesetzt, und beide Dokumente bleiben exakt wie geladen: Sie können direkt nach der Verweigerung einen Feldwert aus dem Quelldokument lesen und bekommen den originalen Text zurück

Der Scan selbst ist billig. Bei n Namen im Ziel und m in der Quelle kostet das Sortieren in eine Menge in der Größenordnung von (n + m) log(n + m) Vergleichen, also fügt ein Paket mit ein paar hundert Feldern nichts hinzu, was neben dem Parsen der Dateien auffiele

PDF Library for Delphi: Reihenfolgediagramm: die Legacy-Zusammenführung findet doppelte Feldnamen erst nach Umnummerierung und Seitenbaumvernähen, während MergeDocumentEx zuerst Namen sammelt, sodass eine Zurückweisung beide Dokumente unberührt lässt
Umsortierung und Seitenbaum-Verkettung erfolgen, bevor der Legacy-Merge Feldnamen überhaupt prüft — ein sauberes Rollback bleibt unmöglich. MergeDocumentEx vergleicht vorab eine geordnete, groß-/kleinschreibungssensible Namensmenge, was aus der Verweigerung einen sauberen No-Op macht

Drei Eigenschaften des Scans zeigen sich in echten Formularpaketen:

  • Verglichen werden nur Top-Level-Felder. In einem hierarchischen Formular heißt das der partielle Name des Elternteils, also kollidieren zwei Formulare, die je einen Elternteil namens applicant haben, selbst wenn ihre Kinder differieren, und die Auto-Nummerierung benennt das Elternteil um: Die eingehenden Kinder lesen sich dann als applicant_2.name und applicant_2.address
  • Eingehende Namen kommen geprüft in die Menge. Ein Quelldokument, das bereits zwei Top-Level-Felder mit demselben Namen trägt, triggert die Strategie beim zweiten, selbst wenn das Ziel überhaupt kein Feld dieses Namens hat
  • Felder mit leerem partiellen Namen werden übersprungen, und hat eines der Dokumente kein AcroForm, gibt es nichts zu vergleichen, also läuft der Merge unter jeder Strategie durch

Die Ladeseite hat eine eigene Falle. LoadFromFile fügt der Bibliothek ein neues Dokument hinzu und wählt es aus, also ist die zu behaltende Kennung die, die SelectedDocument nach jedem Laden zurückgibt. Greift man vor dem Laden zu, hält man ein anderes Dokument in der Hand als das, in das man zu mergen glaubt

uses
  SysUtils, PDFlibrary;

procedure BuildPack(const Part1, Part2, OutFile: WideString);
var
  Lib: TPDFlib;
  TargetDoc, SourceDoc: Integer;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile(Part1, '') = 0 then
      raise Exception.CreateFmt('Cannot load %s', [Part1]);
    TargetDoc := Lib.SelectedDocument;   // nach dem Laden lesen, nicht davor

    if Lib.LoadFromFile(Part2, '') = 0 then
      raise Exception.CreateFmt('Cannot load %s', [Part2]);
    SourceDoc := Lib.SelectedDocument;

    Lib.SelectDocument(TargetDoc);       // das ausgewählte Dokument empfängt den Merge
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // Doppelte Top-Level-Namen: beide Dokumente sind unberührt,
      // also kann SourceDoc direkt in einen zweiten Versuch zurück
      WriteLn('Duplicate field names in ', Part2, ', retrying with auto-numbering');
      if Lib.MergeDocumentEx(SourceDoc, dfsAutoNumber) = 0 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);
    end;

    Lib.SaveToFile(OutFile);
  finally
    Lib.Free;
  end;
end;

Zuerst streng, dann nachsichtig. Diese Zwei-Schritt-Form funktioniert nur, weil die Verweigerung SourceDoc geladen und intakt lässt; bei einem Merge, der auf halbem Weg scheitert, müsste der Fallback-Zweig mit dem Neuladen beider Dateien beginnen. Speziell auf 705 zu prüfen ist ebenfalls wichtig, denn eine ungültige Dokument-Kennung oder ein außerhalb des Bereichs liegender Strategie-Wert scheitert mit einem anderen Code, und ein Retry mit einer anderen Strategie repariert beides nicht

Eine Strategie wählen: verweigern, teilen oder umnummerieren

Für unbeaufsichtigte Pipelines: dfsReject zum Standard machen und 705 als Ticket für denjenigen behandeln, dem die Quellformulare gehören. Ein Feld stromaufwärts einmal umzubenennen ist billiger, als Monate später zu entdecken, dass ein Export-Mapping still aufgehört hat zu passen, weil ein Merge ein Total_2 erfand. Die automatischen Strategien verdienen ihren Platz, wenn ein Mensch die Formulare angesehen und entschieden hat, was die geteilten Namen bedeuten

dfsMerge behält den geteilten Namen mit Absicht. Bevor irgendetwas angehängt wird, werden Wert und Standardwert des Zielfelds in das eingehende Feld kopiert, also startet die zusammengeführte Datei konsistent, und ein Viewer, der Widgets nach Namen gruppiert, sieht ein logisches Feld mit einem Wert. Die beiden Field-Dictionaries bleiben getrennte Objekte, jedes mit seiner eigenen Seite, seiner Darstellung und seinen Aktionen. Sie in ein Dictionary zu falten würde Formatierung und Verhalten wegwerfen, die zum eingehenden Formular gehören, und diesen Tausch ist eine kosmetische Vereinfachung nicht wert

dfsAutoNumber benennt eingehende Duplikate um, indem es ein numerisches Suffix anhängt, beginnend bei _2, und nimmt die erste freie. Hat das Ziel bereits Shared und Shared_2, wird der Neuankömmling zu Shared_3. Das Ergebnis hängt nur von den vorhandenen Namen ab, nie von Objektnummern, also liefert das zweimalige Mergen derselben Dateien beide Male dieselben Namen — eine Eigenschaft, auf die sich nachgelagerte FDF-Importe und Datenbank-Mappings verlassen

PDF Library for Delphi: drei Ausgänge für doppelte Felder nach MergeDocumentEx: dfsReject gibt Fehler 705 mit intakten Formularen zurück, dfsMerge synchronisiert gleichnamige Widgets zu einem logischen Wert, und dfsAutoNumber hängt ein reproduzierbares _2-Suffix an
dfsReject hält beide Dokumente unangetastet für einen informierten Wiederholungsversuch, dfsMerge behandelt mehrere gleichnamige Widgets als ein logisches Feld mit einem synchronisierten Wert, und dfsAutoNumber vergibt stabile Namen mit Suffix, mit denen externe Zuordnungen rechnen müssen

Die Wahl zwischen den beiden automatischen Strategien läuft auf eine Frage hinaus: Soll das Füllen eines Steuerelements das andere mitfüllen? Bei dem Namen des Unterzeichners, der auf jedem Teil eines Pakets wiederkehrt: ja, und dfsMerge passt. Bei einer Summe, die auf jedem Formular anders berechnet wird: nein. Dort dfsAutoNumber wählen, oder besser, das Feld im Quellformular umbenennen, damit das Suffix nie auftaucht

Was enthält das zusammengeführte Formular danach?

Nehmen wir ein Ziel mit einem Top-Level-Textfeld Shared, das "Target value" hält, und eine Quelle mit ihrem eigenen Shared. Nach dfsMerge zählt FormFieldCount zwei Felder, beide betitelt Shared, beide melden "Target value". Nach dfsAutoNumber liefert dieselbe Eingabe Shared und Shared_2, und das eingehende Feld behält, welchen Wert es in der Quelldatei hatte

Das dfsMerge-Ergebnis hat eine scharfe Kante, und die sitzt in Ihrem eigenen Füllcode. FindFormFieldByTitle gibt den ersten Index zurück, dessen Titel passt, und SetFormFieldValue schreibt in genau ein Feld. Eine Routine, die Shared einmal nachschlägt und setzt, aktualisiert die Kopie des Ziels und lässt die eingehende Kopie den Wert halten, den sie zum Merge-Zeitpunkt empfing. Die gespeicherte Datei enthält nun zwei Felder mit einem Namen und zwei unterschiedlichen Werten, und welcher angezeigt wird, entscheidet der Viewer. Jede Übereinstimmung schreiben:

// Setzt jedes Feld, das Title trägt; liefert zurück, wie viele geschrieben wurden.
// Nach einem dfsMerge-Merge kann ein logisches Feld an mehreren Indizes auftauchen
function SetAllFieldsNamed(Lib: TPDFlib; const Title, Value: WideString): Integer;
var
  I: Integer;
begin
  Result := 0;
  for I := 1 to Lib.FormFieldCount do
    if Lib.GetFormFieldTitle(I) = Title then
    begin
      if Lib.SetFormFieldValue(I, Value) = 1 then
        Inc(Result)
      else
        WriteLn(Format('Field %d (%s) not written, error %d',
          [I, Title, Lib.LastErrorCode]));   // schreibgeschützte Felder landen hier
    end;
end;

Bevor ein zusammengeführtes Paket in einen Datenfeed gegabelt wird, ausgeben, was der Merge tatsächlich erzeugt hat. Eine Zwei-Zeilen-Schleife genügt, und sie fängt die umbenannten Eltern und _2-Suffixe ab, bevor es ein Import-Job tut:

for I := 1 to Lib.FormFieldCount do
  WriteLn(Format('%3d  %-30s  %s',
    [I, Lib.GetFormFieldTitle(I), Lib.GetFormFieldValue(I)]));

Ein Formularpaket in der Praxis zusammenbauen

Ein erfolgreicher Merge konsumiert das Quelldokument. Es wird aus der Dokumentenliste der Bibliothek entfernt, also fällt DocumentCount um eins, und die alte SourceDoc-Kennung darf nicht wieder verwendet werden. Das zusammengeführte Dokument nimmt die höhere der beiden PDF-Versionen an: Ein PDF-2.0-Formular in ein 1.7-Dokument zu mergen ergibt eine 2.0-Datei, was zählt, wenn ein nachgelagerter Archivierungsschritt eine bestimmte Version erwartet

Die Merge-Reihenfolge entscheidet, wessen Namen überleben. Das ausgewählte Dokument behält jeden seiner Namen, und Umbenennungen oder Wertkopien treffen immer nur die eingehenden Felder, also liefern A in B mergen und B in A mergen unterschiedliche auto-nummerierte Ergebnisse. Hat ein Paket ein primäres Formular — dasjenige, dessen Feldnamen Ihr Backoffice bereits kennt —, machen Sie es zum Ziel und mergen die Ergänzungen hinein

Zuletzt signieren. Eine Signatur deckt die Bytes der Revision ab, die sie signierte, und ein Merge schreibt die Datei neu, also trägt ein Teil, das vor der Montage signiert wurde, keine Signatur mehr, die zum Dokument passt. Bauen Sie das Paket, prüfen Sie die Feldliste, dann setzen Sie Signaturen auf die fertige Datei. Geht es im Job nur darum, Seiten aneinanderzunähen, und zählen die Formulare nicht, ist schnelles PDF-Merge mit Byte-Referenz-Verschiebung der schnellere Weg

Planen Sie die Datenseite neben dem Merge. Kommen Feldwerte von einem externen System, das Felder per Name adressiert, klären Sie die Benennung, bevor Sie dfsAutoNumber wählen, denn ein Shared_2 passt nicht auf ein Mapping, das Shared erwartet. Wert-Import- und Export-Formate behandelt FDF-, XFDF- und XFA-Formulardatenaustausch. Berechnungsskripte und Aktionen, die Felder per Name referenzieren, sind von Umbenennungen auf dieselbe Weise betroffen, und interaktive Formularaktionen und JavaScript zeigt, wo diese Referenzen leben

Duplikat-bewusstes Formular-Merging, Feldfüllung und digitale Signatur sind alle Teil derselben Bibliothek für Delphi-, C++Builder- und Free-Pascal-Projekte. Die Produktseite von PDF Library for Delphi listet den Rest der Formular- und Dokumentmontage-API auf