Ejemplo: generar archivos PDF a partir de archivos XML
Este ejemplo explica cómo crear un trabajo de FlowForce Server que toma varios archivos XML como entrada y devuelve varios archivos PDF como resultado. El trabajo de FlowForce Server invocará a MapForce Server para generar el resultado XML a partir de los archivos XML de origen y a StyleVision Server para convertir el resultado XML en archivos PDF.
Antes de leer este ejemplo se recomienda tener un conocimiento básico previo del funcionamiento de asignaciones de datos de MapForce y de transformaciones de StyleVision. Si hasta ahora no ha trabajado con StyleVision ni con MapForce, es el momento de leer los tutoriales que ofrece la documentación de ambos productos:
•Tutorial rápido de StyleVision
Requisitos
•Licencias necesarias:
oMapForce Enterprise o Professional. Esta herramienta permite diseñar una transformación de asignación (archivo .mfd) que convierte (en este ejemplo) archivos XML de un esquema en otro.
oMapForce Server o MapForce Server Advanced Edition. Esta herramienta permite ejecutar la asignación en un servidor como un trabajo.
oStyleVision Enterprise o Professional. Esta herramienta permite diseñar una hoja de estilos (archivo .sps) que convierte un archivo XML de entrada en un archivo PDF.
oStyleVision Server. Esta herramienta permite ejecutar la transformación en un servidor como un trabajo.
oFlowForce Server. Esta herramienta permite ejecutar las transformaciones de los puntos anteriores en trabajos bajo demanda, cambiar los archivos de entrada y controlar la ejecución.
•Los servicios FlowForce Web Server y FlowForce Server deben escuchar en la en la dirección de red y en el puerto configurados previamente.
•Su cuenta de usuario de FlowForce Server debe tener permiso para acceder a uno de los contenedores (el contenedor /public que se usa para este ejemplo ofrece acceso a todos los usuarios que inicien sesión).
•El trabajo que se crea en este ejemplo genera varios archivos en disco. Por tanto, en el sistema operativo donde se ejecute FlowForce Server deberá tener permiso para crear archivos en algún directorio (p. ej. para este ejemplo usamos el directorio C:\FlowForceExamples\GeneratePdfs).
Archivos de ejemplo utilizados
Para este ejemplo usamos varios archivos de muestra que están en la ruta de acceso <Documentos>\Altova\MapForce2023\MapForceExamples.
•MultipleInputToMultipleOutputFiles.mfd (el archivo de asignación de datos de MapForce).
•PersonListWithGrouping.sps (el archivo de transformación de datos de StyleVision).
•Nanonull-Branch.xml, Nanonull-HQ.xml (los archivos XML de entrada).
Qué hace la asignación de datos de MapForce
Tal y como puede ver en la siguiente imagen, la asignación de datos está compuesta por un componente de origen (Altova_Hierarchical), un componente de destino (PersonList) y varias funciones integradas de MapForce intermedias que sirven para generar varias cadenas que se escribirán en los resultados de la asignación.
MultipleInputToMultipleOutputFiles.mfd
La asignación toma como entrada todos los archivos XML del directorio <Documentos>\Altova\MapForce2023\MapForceExamples que empiecen por "Nanonull-". Esto se definió en la configuración del componente de origen (compruébelo haciendo clic con el botón derecho en el título del componente Altova_Hierarchical y seleccionando Propiedades en el menú contextual). Observe que Archivo de entrada tiene el valor Nanonull-*.xml, donde el asterisco hace de comodín. Es decir, el archivo de entrada será cualquier archivo que empiece por "Nanonull-" y que tenga la extensión .xml.
El componente de destino (PersonList) está configurado para generar nombres de archivo de forma dinámica en base al nombre del archivo XML de origen. Esta configuración se consigue haciendo clic con el botón derecho en el botón Archivo/Cadena situado en el título del componente y seleccionando Usar nombres de archivo dinámicos dados por la asignación en el menú contextual. La conexión con el nodo "Archivo <dinámico>" significa que se creará un archivo nuevo por cada valor del nodo de origen. La función remove-folder se usa para obtener el nombre de archivo (sin la carpeta) de la ruta de acceso de origen. Después se pasa este nombre de archivo como valor para la primera función concat, que genera una cadena tipo Persons-<nombre archivo origen>.
La segunda función concat genera una cadena tipo Generated by Altova... seguida de la ruta de acceso completa del archivo de asignación de datos. El resultado se escribe en forma de comentario en el archivo XML de destino.
La tercera función concat utiliza el resultado de la función count para generar una cadena que indica cuántos registros se asignaron desde el origen de datos. Su resultado se escribe en forma de comentario en el archivo XML.
Por último, la conexión entrante del nodo Person de destino copia los datos de las personas del componente de origen al componente de destino. Existe una conexión por cada elemento secundario de Person que debe asignarse.
Además, el componente de destino está configurado para convertir los resultados generados en PDF (por cada archivo XML de salida se crea un PDF). Haga clic con el botón derecho en el título del componente de destino, seleccione Propiedades y observe que en el cuadro de texto Archivo Power Stylesheet de StyleVision se especificó una ruta de acceso relativa para una hoja de estilos .sps de StyleVision. Esta hoja de estilos es la que lleva a cabo la conversión de XML a PDF (como se explica más abajo).
Para consultar una vista previa de los resultados de esta asignación en MapForce haga clic en la pestaña Resultados situada en la parte inferior del panel de asignación. Para ver el resultado PDF de la transformación de StyleVision haga clic en la pestaña PDF. Observe que en la pestaña Resultados se generan varios archivos XML (o PDF):
Llegados a este punto se recomienda guardar uno de los archivos XML de salida en disco (porque MapForce genera archivos temporales por defecto). El archivo servirá de muestra (XML de trabajo) para probar la hoja de estilos de StyleVision (ver más abajo). Para guardar un archivo de salida primero debe hacer clic en la pestaña Resultados y después elegir el comando de menú Resultados | Guardar el archivo de salida.
Qué hace la transformación de datos de StyleVision
Inicie StyleVision y abra el archivo de transformación PersonListWithGrouping.sps. Recuerde que este archivo está en el mismo directorio que la asignación de MapForce descrita más arriba y que el componente de destino de dicha asignación hace referencia a este archivo de transformación.
PersonListWithGrouping.sps
La hoja de estilos .sps de StyleVision (imagen anterior) usa un solo archivo XML como fuente y crea un documento PDF a partir de este XML. El documento PDF incluye un título ("h2"), un párrafo introductorio, una tabla que se rellena de forma dinámica y un párrafo de cierre. El título y el párrafo introductorio contienen texto estático, mientras que la tabla y el párrafo de cierre se rellenan con datos de los nodos del XML de origen, tal y como indican las etiquetas.
Siga estas instrucciones para consultar la vista previa de esta transformación desde StyleVision Directamente:
1.En el panel Vista general del diseño, haga clic en el icono 
del campo XML de trabajo.
2.En el menú contextual seleccione Asignar archivo XML de trabajo... y navegue hasta el archivo XML de salida que se guardó desde MapForce (ver más arriba).
3.Haga clic en la pestaña PDF.
Es importante tener en cuenta que a la hoja de estilos .sps le es indiferente el nombre o la procedencia del archivo XML de origen. Simplemente procesa el archivo XML dado como entrada (siempre y cuando cumpla con el esquema XML especificado) y crea un PDF a partir de dicho archivo. Para automatizar la hoja de estilos y poder generar varios archivos PDF de salida deberá estar implementada en FlowForce Server (ver más abajo).
Implementar archivos en FlowForce Server
Ahora ya conoce el objetivo de la asignación de datos de MapForce y de la transformación de StyleVision que estamos utilizando en el ejemplo. Si necesita obtener más información sobre cómo diseñar asignaciones y hojas de estilos, consulte la documentación de MapForce y StyleVision respectivamente (https://www.altova.com/es/documentation.html).
Para que la automatización sea posible ambos archivos deben estar implementados en FlowForce Server. Tal y como se explica en la sección Requisitos, FlowForce Server debe tener asignada una licencia válida y estar en ejecución. Además, MapForce Server y StyleVision Server deben tener asignadas licencias válidas y estar bajo control de FlowForce Server. En Windows puede usar el comando verifylicense de cada producto servidor para comprobar el estado de su licencia. En los demás sistemas operativos la ejecución dará lugar a error cuando no se encuentre la licencia o la licencia no sea válida.
Siga estas instrucciones para implementar la hoja de estilos de StyleVision en FlowForce Server:
1.Haga clic en el comando de menú Archivo | Implementar en FlowForce. Si este comando aparece en gris, es decir, desactivado, cambie primero a la pestaña Diseño.
2.La aplicación le avisa de que el diseño debe guardarse en formato PXF (formulario XML portátil). Haga clic en Aceptar para confirmar.
3.Aparece un cuadro de diálogo donde puede seleccionar qué archivos se incluyen en el paquete implementado. Deje las opciones predeterminadas como están. Aunque para este ejemplo solo vamos a generar archivos PDF, en este cuadro de diálogo puede seleccionar varios formatos de salida, como HTML y RTF. Haga clic en Aceptar.
4.Aparece el cuadro de diálogo "Implementar transformación". Rellene los datos de la conexión con FlowForce Web Server. En este ejemplo vamos a implementar la transformación en el equipo local en el puerto 8082 por HTTP, pero también se puede especificar una dirección remota e implementar los archivos por una conexión con cifrado SSL, siempre y cuando el servidor web de FlowForce Server esté configurado para aceptar dichas conexiones (véase Definir la configuración de red). En el ejemplo usamos el usuario raíz y su contraseña, pero se puede usar cualquier otro usuario de FlowForce (siempre y cuando tenga permiso para escribir datos en la ruta de acceso especificada). En este ejemplo dejamos sin marcar la casilla Abrir el explorador web para crear un trabajo nuevo porque nos ocuparemos de crear y configurar el trabajo más adelante.
5.Como en otros ejemplos, recomendamos usar como ruta de destino /public/Examples/PersonListWithGrouping.transformation.
Para implementar la asignación de MapForce en FlowForce Server:
•Haga clic en Archivo | Implementar en FlowForce Server. Las opciones de conexión son las mismas que las de StyleVision. Recomendamos usar como ruta de destino /public/Examples/MultipleInputToMultipleOutputFiles.mapping.
Una vez finalizada la implementación de los archivos, las entradas correspondientes aparecen en el contenedor de FlowForce elegido ("/public/Ejemplos" en nuestro caso) cuando iniciamos sesión en FlowForce Server:
Observe que estas entradas del contenedor "/public" no son trabajos todavía. Son funciones de FlowForce a partir de las cuales debemos crear los trabajos, tal y como se explica a continuación.
Crear y configurar el trabajo de FlowForce
Ahora que la asignación de MapForce y la transformación de StyleVision están implementadas en FlowForce ya podemos usarlas para crear trabajos:
1.Navegue hasta el contenedor /public de FlowForce y haga clic en la función MultipleInputToMultipleOutputFiles.mapping que acabamos de implementar. Observe que el componente de origen de la asignación de MapForce que comentamos al principio del ejemplo ahora es un parámetro de entrada de la función de FlowForce. Además tiene un valor predeterminado que es la ruta de acceso de los archivos XML de instancia que procesa la asignación. Este valor se puede sobrescribir más adelante si se necesita. FlowForce añade automáticamente el parámetro "Working-directory", cuyo papel explicamos más abajo.
2.Haga clic en Crear trabajo.
3.Introduzca el nombre del trabajo y, si quiere, una descripción.
4.Configure la parte Pasos de ejecución del trabajo tal y como muestra esta imagen:
5.En el grupo de opciones Servicio marque la casilla Permitir acceso a este trabajo por HTTP en la dirección URL... e introduzca el nombre del servicio web que desencadenará el trabajo bajo demanda. Si prefiere programar la ejecución del trabajo o ejecutarlo cuando se detecte cierto archivo en el sistema, por ejemplo "GeneratePdfsService", debe crear y configurar los desencadenadores correspondientes (véase Desencadenadores).
6.En el grupo de opciones Credenciales introduzca el nombre de usuario y la contraseña de la cuenta de usuario del sistema operativo (el trabajo se ejecutará como este usuario). No se debe confundir esta contraseña con la contraseña de la interfaz de administración web de FlowForce Server (véase la sección Credenciales).
7.Haga clic en Guardar.
Ahora vamos a detenernos en la configuración del grupo Pasos de ejecución para comprender cómo funciona este trabajo. El primer paso de ejecución llama a la asignación implementada. El segundo parámetro define el directorio de trabajo (C:\FlowForceExamples\GeneratePdfs).
El resultado que devuelve el primer paso de ejecución representa los datos que devuelve la asignación. Se le llamó salida para poder hacerle referencia en el siguiente paso.
El segundo paso del trabajo es un paso for-each. Observe que el paso for-each usa una expresión de FlowForce results(salida) para acceder a los datos que devuelve el primer trabajo (es decir, los resultados que genera la asignación). Concretamente, la expresión llama a la función results(), que toma como argumento el resultado que devuelve el paso anterior (véase Funciones para resultados de los pasos). Para aprender a trabajar con expresiones de FlowForce consulte la sección Lenguaje de expresiones de FlowForce.
El paso for-each está compuesto por dos pasos de ejecución:
1.el primero llama a la función integrada /system/compute para convertir el resultado de la asignación en un archivo (que recibe el nombre genérico archivo). Es importante tener en cuenta que el resultado de la expresión results(salida) es una secuencia de datos y no un archivo. Si la asignación devuelve varios resultados (como en el caso que nos ocupa), el resultado de la asignación representará una secuencia de secuencias. Por este motivo usamos la función de expresión de FlowForce as-file para convertir la secuencia actual (la que se está recorriendo) en un archivo real.
2.el segundo paso llama a la transformación de StyleVision que está implementada una vez por cada secuencia que se recorre. Es decir, por cada iteración, se llama a StyleVision Server, se aporta como entrada un archivo XML y se devuelve un archivo PDF como resultado. La expresión de FlowForce {filename(archivo)}.pdf crea el nombre del archivo PDF en el disco. Esta operación tiene lugar en el directorio de trabajo que especifica el parámetro "Working-directory".
| Nota: | en nuestro ejemplo usamos el mismo directorio de trabajo en el paso que ejecuta la asignación y en el paso que ejecuta la transformación de StyleVision. En algunos casos puede ser necesario utilizar directorios de trabajo distintos para evitar conflictos entre nombres de archivos y eventuales errores de ejecución. |
Ejecutar el trabajo
Para preparar los datos de entrada para el trabajo copie Nanonull-Branch.xml y Nanonull-HQ.xml de <Documents>\Altova\MapForce2023\MapForceExamples al directorio de trabajo (C:\FlowForceExamples\GeneratePdfs). De esta forma el primer paso del trabajo tiene archivos de los que leer datos cuando se ejecute el trabajo.
Puede ejecutar el trabajo de varias maneras:
•Vaya a Inicio y haga clic en Ver los desencadenadores y servicios activos. Después haga clic en la URL del trabajo que aparece en la columna "Información".
•Introduzca http://127.0.0.1:4646/service/GeneratePdfsService en la barra de direcciones del explorador. Tenga en cuenta que esta URL solo funciona si el servicio FlowForce Server escucha en la dirección host y el nombre de puerto predeterminados. Si su puerto y host tienen otra configuración vaya a la Configuration page y cambie la dirección.
•Si configura el campo Nombre de host de FlowForce Server desde la página de configuración puede ejecutar la llamada al servicio web directamente desde la página de configuración del trabajo. Para ello haga clic en el botón 
que hay junto a la casilla Permitir acceso a este trabajo por HTTP. Este botón solo se habilita si configura este campo Nombre de host. Si no lo ha hecho, puede llamar al servicio web escribiendo la URL manualmente en la barra de dirección.
Si la aplicación le pide credenciales al acceder al servicio web, use las mismas que usó para acceder a FlowForce Server.
Recomendamos usar las credenciales de FlowForce Server para la autenticación HTTP solo en casos de prueba. Para producción es mejor crear un usuario nuevo, darle el permiso Servicio - Uso en el contenedor en el que está el trabajo y después acceder al servicio web con esa cuenta. Para desactivar la autenticación HTTP y hacer público el servicio web debe dar el permiso Servicio - Uso al usuario Anónimo, véase ¿Cómo funcionan los permisos?. |
Si el trabajo se ejecuta correctamente los archivos PDF que genera el trabajo se encuentran en el directorio de trabajo C:\FlowForceExamples\GeneratePdfs. Recuerde que en este trabajo no se configuró ningún control de errores así que el explorador emitirá un error aunque la ejecución finalice correctamente (se trata de algo esperado porque el trabajo produce archivos PDF que no se pueden presentar en el explorador). Si por algún motivo no se pudiera ejecutar el trabajo, el explorador emitirá el mensaje "No se puede ejecutar el servicio". En este caso revise el registro de errores del trabajo para ver qué paso está causando el problema y por qué. Puede que necesite volver a revisar los requisitos del principio de este apartado para solucionar el problema.