Artículo técnico

Combinar formularios PDF: reglas de campos duplicados

Escribe un nombre en la casilla Applicant de la página 1 de un paquete de solicitudes recién combinado, pasa al campo siguiente, y en muchos visores la casilla Applicant de la página 6 se rellena con el mismo texto. Nadie conectó esos dos controles. Las partes 1 y 3 del paquete las escribió gente distinta, ambas llamaron Applicant a un campo de nivel superior, y un formulario PDF identifica un campo por su nombre completo. Dos campos con un mismo nombre son, para el formato de archivo, un mismo campo dibujado dos veces

La solución es decidir qué debe significar un nombre compartido antes de que la combinación ocurra: rechazarlo, conservarlo a propósito o renombrar al recién llegado. Decidirlo después es mucho más difícil de lo que suena

Qué entiende ISO 32000 por nombre de campo

El nombre de un campo es su identidad, y la especificación lo dice. ISO 32000-1 §12.7.3.2 construye el nombre completo a partir del nombre parcial (la entrada T) de un campo y de cada uno de sus ancestros, unidos con puntos. La misma sección permite que varios diccionarios de campo compartan un nombre completo y los describe como representaciones distintas del mismo campo subyacente, que solo deberían diferir en el aspecto. Concatenar los arrays Fields de dos formularios escritos de forma independiente produce exactamente esa situación por accidente

El daño depende de lo que contuvieran los campos en colisión. Un Date que significaba fecha de nacimiento en un formulario y fecha de firma en otro tiene ahora una única ranura de valor, y el valor por el que se decante el visor aterriza en los dos sitios. Un Total en una hoja de gastos y un Total en un formulario de depósito discrepan en cuanto se calcula cualquiera. Los campos de firma son el peor caso: dos widgets de firma en páginas distintas, un nombre, y ninguna respuesta limpia sobre cuál de los dos widgets aprobó realmente el firmante

Las mayúsculas también importan. Los nombres parciales son cadenas de texto y nada en la especificación los normaliza, así que Total y total son dos campos distintos. Una comprobación de colisiones que pase los nombres a minúsculas antes de comparar informa de conflictos que no existen, y bajo una política de renombrado renombra campos que nadie necesitaba tocar

Comprobar los nombres antes de que nada se mueva

PDF Library for Delphi trata la colisión en MergeDocumentEx(DocumentID, DuplicateFieldStrategy), que combina el documento identificado por DocumentID en el documento seleccionado actualmente y resuelve cada conflicto de nombres antes de renumerar un solo objeto. La estrategia es un valor TPDFlibDuplicateFieldStrategy: dfsReject, dfsMerge o dfsAutoNumber. El MergeDocument normal sigue concatenando los dos arrays de campos raíz sin cambios, que es la decisión correcta cuando ambos formularios son tuyos y sabes que sus nombres no se cruzan

El orden es todo el diseño. Una combinación tiene que desplazar los números de objeto del documento entrante para que no choquen con los del destino, coser sus páginas en el árbol de páginas del destino y añadir sus campos al formulario. Si una colisión solo asoma después de esos pasos, rechazar ya no es gratis — el destino ya absorbió páginas, los objetos del origen llevan números con los que ningún archivo empezó, y el que llama no tiene estado al que volver salvo recargar ambos archivos desde disco. MergeDocumentEx recopila primero los nombres de campo de nivel superior de ambos documentos en un conjunto ordenado y sensible a mayúsculas, y aplica la estrategia contra ese conjunto. Con dfsReject, una colisión hace que la llamada devuelva 0 con LastErrorCode a 705, y ambos documentos quedan tal cual estaban cargados: puedes leer un valor de campo del documento de origen justo después del rechazo y recuperar el texto original

El barrido en sí es barato. Con n nombres en el destino y m en el origen, ordenarlos en un solo conjunto cuesta del orden de (n + m) log(n + m) comparaciones, así que un paquete de unos cientos de campos no añade nada que puedas notar junto al parseo de los archivos

PDF Library for Delphi: Diagrama de orden de operaciones que contrasta la fusión antigua, que descubre nombres de campo duplicados solo tras renumerar y coser el árbol de páginas, con MergeDocumentEx, que recopila nombres primero, de modo que un rechazo deja ambos documentos intactos
La renumeración y la costura del árbol de páginas ocurren antes de que la fusión heredada examine los nombres de campo, sin dejar rollback limpio. MergeDocumentEx compara de antemano un conjunto ordenado de nombres sensibles a mayúsculas, lo que convierte el rechazo en un no-op limpio

Tres propiedades del barrido se dejan ver en paquetes de formularios reales:

  • Solo se comparan los campos de nivel superior. En un formulario jerárquico eso significa el nombre parcial del padre, así que dos formularios que cada uno tenga un padre llamado applicant colisionan aunque sus hijos difieran, y la numeración automática renombra al padre: los hijos entrantes pasan a leerse applicant_2.name y applicant_2.address
  • Los nombres entrantes se unen al conjunto a medida que se comprueban. Un documento de origen que ya lleve dos campos de nivel superior con el mismo nombre dispara la estrategia con el segundo, aunque el destino no tenga ningún campo con ese nombre
  • Los campos con nombre parcial vacío se saltan, y cuando alguno de los dos documentos no tiene AcroForm no hay nada que comparar, así que la combinación prosigue bajo cualquier estrategia

El lado de la carga tiene su propia trampa. LoadFromFile añade un documento nuevo a la biblioteca y lo selecciona, así que el identificador que hay que conservar es el que SelectedDocument devuelve tras cada carga. Cógelo antes de la carga y estarás sujetando un documento distinto del que crees que es tu destino de combinación

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;   // se lee después de la carga, no antes

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

    Lib.SelectDocument(TargetDoc);       // el documento seleccionado recibe la combinación
    if Lib.MergeDocumentEx(SourceDoc, dfsReject) = 0 then
    begin
      if Lib.LastErrorCode <> 705 then
        raise Exception.CreateFmt('Merge failed, error %d', [Lib.LastErrorCode]);

      // Nombres de nivel superior duplicados: ambos documentos quedan intactos,
      // así que SourceDoc puede ir directo a un segundo intento
      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;

Primero estricto, luego indulgente. Esa forma de dos pasos solo funciona porque el rechazo deja SourceDoc cargado e intacto; con una combinación que falla a medias, la rama de reserva tendría que empezar recargando ambos archivos. Comprobar específicamente el 705 también importa, porque un identificador de documento inválido o un valor de estrategia fuera de rango hacen fallar la llamada con otro código, y reintentar con otra estrategia no arregla ninguno de los dos

Elegir estrategia: rechazar, compartir o renumerar

Para pipelines desatendidos, haz de dfsReject el valor por defecto y trata el 705 como un tiquete para quien posea los formularios de origen. Renombrar un campo arriba en la cadena una vez sale más barato que descubrir meses después que un mapeo de exportación dejó de encajar en silencio porque una combinación inventó Total_2. Las estrategias automáticas se ganan su sitio cuando una persona ha mirado los formularios y decidido qué significan los nombres compartidos

dfsMerge conserva el nombre compartido a propósito. Antes de añadir nada, el valor y el valor predeterminado del campo de destino se copian en el campo entrante, así que el archivo combinado arranca consistente y un visor que agrupa widgets por nombre ve un campo lógico con un valor. Los dos diccionarios de campo siguen siendo objetos separados, cada uno con su página, su apariencia y sus acciones. Fundirlos en un diccionario tiraría formato y comportamiento que pertenecen al formulario entrante, y ese intercambio no vale la pena por una simplificación cosmética

dfsAutoNumber renombra los duplicados entrantes añadiendo un sufijo numérico, empezando en _2 y tomando el primero libre. Si el destino ya tiene Shared y Shared_2, el recién llegado se convierte en Shared_3. El resultado depende solo de los nombres presentes, nunca de los números de objeto, así que combinar el mismo par de archivos dos veces da los mismos nombres ambas veces — una propiedad de la que dependen las importaciones FDF de aguas abajo y los mapeos de base de datos

Tres desenlaces de campos duplicados de PDF Library for Delphi tras MergeDocumentEx: dfsReject devolviendo el error 705 con ambos formularios intactos, dfsMerge sincronizando widgets de nombre compartido en un único valor lógico, y dfsAutoNumber añadiendo un sufijo _2 reproducible
dfsReject mantiene ambos documentos intactos para un reintento informado, dfsMerge trata varios widgets del mismo nombre como un campo lógico que contiene un valor sincronizado, y dfsAutoNumber reparte nombres estables con sufijo que los mapeos externos deben prever

Elegir entre las dos estrategias automáticas se reduce a una pregunta: ¿rellenar un control debe rellenar el otro? Para el nombre del firmante repetido en cada parte de un paquete, sí, y dfsMerge encaja. Para un total que se calcula de forma distinta en cada formulario, no. Allí elige dfsAutoNumber, o mejor, renombra el campo en el formulario de origen para que el sufijo nunca aparezca

¿Qué contiene el formulario combinado después?

Toma un destino con un campo de texto de nivel superior Shared que lleva «Target value» y un origen con su propio Shared. Tras dfsMerge, FormFieldCount cuenta dos campos, ambos titulados Shared, ambos informando «Target value». Tras dfsAutoNumber, la misma entrada da Shared y Shared_2, y el campo entrante conserva el valor que tuviera en el archivo de origen

El resultado de dfsMerge tiene un filo peligroso, y está en tu propio código de relleno. FindFormFieldByTitle devuelve el primer índice cuyo título encaja, y SetFormFieldValue escribe exactamente en un campo. Una rutina que busca Shared una vez y lo establece actualiza la copia del destino y deja la copia entrante con el valor que recibió en el momento de la combinación. El archivo guardado contiene ahora dos campos con un nombre y dos valores distintos, y cuál muestra el visor depende del visor. Escribe en todas las coincidencias en su lugar:

// Establece cada campo que lleve Title; devuelve cuántos se escribieron.
// Tras una combinación dfsMerge, un campo lógico puede aparecer en varios índices
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]));   // los campos de solo lectura acaban aquí
    end;
end;

Antes de enchufar un paquete combinado a un flujo de datos, vuelca lo que la combinación produjo realmente. Un bucle de dos líneas basta, y caza a los padres renombrados y los sufijos _2 antes de que lo haga un trabajo de importación:

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

Ensamblar un paquete de formularios en la práctica

Una combinación exitosa consume el documento de origen. Se elimina de la lista de documentos de la biblioteca, así que DocumentCount baja en uno, y el viejo identificador SourceDoc no debe volver a usarse. El documento combinado toma la mayor de las dos versiones PDF: combinar un formulario PDF 2.0 en un documento 1.7 da un archivo 2.0, algo que importa si un paso de archivado de aguas abajo espera una versión concreta

El orden de combinación decide qué nombres sobreviven. El documento seleccionado conserva todos sus nombres, y los renombrados o copias de valor solo se aplican jamás a los campos entrantes, así que combinar A en B y combinar B en A dan resultados de numeración automática distintos. Cuando un paquete tiene un formulario principal — el formulario cuyos nombres de campo ya conoce tu back office — hazlo el destino y combina los complementos dentro

Firma al final. Una firma cubre los bytes de la revisión que firmó, y combinar reescribe el archivo, así que una parte firmada antes del ensamblaje ya no lleva una firma que corresponda con el documento. Ensambla el paquete, revisa la lista de campos y aplica después las firmas al archivo terminado. Si el trabajo es solo coser páginas y los formularios no importan, la combinación rápida de PDF con desplazamiento de referencias de byte es la vía más rápida

Planifica el lado de los datos junto con la combinación. Si los valores de campo llegan de un sistema externo que direcciona los campos por nombre, cierra el tema de nombres antes de elegir dfsAutoNumber, porque Shared_2 no encajará con un mapeo que espera Shared. Los formatos de importación y exportación de valores están tratados en el intercambio de datos de formulario FDF, XFDF y XFA. Los scripts de cálculo y las acciones que referencian campos por nombre sufren el renombrado igual, y las acciones de formulario interactivas y JavaScript muestra dónde viven esas referencias

La combinación de formularios consciente de duplicados, el relleno de campos y la firma digital forman parte de la misma biblioteca para proyectos Delphi, C++Builder y Free Pascal. La página de producto de PDF Library for Delphi lista el resto de la API de formularios y ensamblado de documentos