Creación de una integración de servicio web segura
Descripción general
Las integraciones de servicios web son una excelente manera de automatizar la impresión mediante una solicitud web. Estas solicitudes se realizan a través de HTTP, que no es seguro. ¿Es posible enviar esto por HTTPS y proteger los datos dentro de la solicitud web?
Es posible, aunque no directamente a través de Integration Builder o la Consola de administración. En su lugar, se envía una solicitud web a BarTender Print Portal, la aplicación web de BarTender. BarTender Print Portal cuenta con una funcionalidad segura llamada Integration Passthrough, que reenvía las solicitudes de servicios web a la integración que escucha en el mismo sistema.
Este ejemplo te guiará sobre cómo asegurar Internet Information Services (IIS) que funciona debajo de BarTender Print Portal, tu integración y tu archivo de etiqueta.
Aplicable a
BarTender 2021 hasta BarTender 2022 R4
Print Portal
Requisitos previos
Para usar la funcionalidad Integration Passthrough de BarTender Print Portal, necesitarás lo siguiente:
- Internet Information Services (IIS) Manager. Es una característica de Windows y se puede instalar usando la aplicación Activar o desactivar características de Windows.
- BarTender Print Portal
- Una aplicación para enviar la solicitud web. Este tutorial cubre Postman e Insomnia, pero puedes usar la que prefieras.
Además, aquí tienes los documentos de ejemplo para seguir este caso:
Habilitar HTTPS
Para que la conexión sea segura para Integration Passthrough, debes vincular HTTPS a BarTender Print Portal. Esto se hace en el IIS Manager.
Microsoft tiene una guía paso a paso sobre cómo configurar tu sitio web para HTTPS. Por defecto, BarTender Print Portal aparece como BarTender en la lista de Sitios en IIS Manager. Esta guía explica cómo crear y usar un certificado autofirmado. Sin embargo, si tienes un certificado de una Autoridad Certificadora, puedes seguir los mismos pasos (omitiendo la sección de autofirmado) para usar tu propio certificado.
Una vez que hayas terminado de vincular, verás tanto HTTP como HTTPS en la sección de Site Bindings, como en la captura de pantalla a continuación:
No es necesario reiniciar el sitio ni el sistema. La vinculación tendrá efecto inmediatamente después de configurarla.
Activar Integration Passthrough
Integration Passthrough es una configuración en el archivo de configuración de BarTender Print Portal. Por defecto, esta opción está desactivada, así que si intentas enviar la solicitud web ahora, BarTender Print Portal la ignorará.
Para cambiar la configuración, deberás abrir el archivo de configuración en una aplicación de edición de texto como Administrador o con una app que pueda elevar sus permisos. Windows no te permitirá guardar el archivo como usuario estándar. Por favor, haz lo siguiente:
- Si usas Notepad:
- Busca Notepad en tu Menú de inicio.
- Haz clic derecho y selecciona Ejecutar como administrador.
- Navega a C:\inetpub\wwwroot\BarTender\ y abre settings.xml
- Desplázate hacia abajo casi al final y localiza el parámetro IntegrationPassthrough
- Cambia Enabled a "true"
Una vez que guardes el archivo, deberás reiniciar varios componentes para que todo lo que trabaja con el Passthrough sepa que está habilitado.
Reiniciar los servicios
- Abre el complemento Servicios desde el Menú de inicio o el Panel de control.
- Haz clic derecho en BarTender System Service y selecciona Reiniciar.
- Te notificará que también se reiniciarán las dependencias. Haz clic en OK.
- Una vez que desaparezcan los diálogos, todos los servicios de BarTender deberían mostrar "en ejecución" junto a su nombre.
Reiniciar el App Pool de IIS
- Abre el IIS Manager
- Haz clic en Application Pools
- Haz clic en BPP_AppPool
- Haz clic en Detener en la lista de acciones de la derecha, espera un momento y luego haz clic en Iniciar.
Configurar la integración
La integración en sí se puede configurar como cualquier otra integración de servicio web. Aquí tienes un resumen breve de la configuración para cada tipo de solicitud de servicio web:
GET
- La etiqueta debe usar fuentes de datos con nombre.
- La integración debe sobrescribir las fuentes de datos con nombre en la acción Imprimir documento.
- Un solo registro se envía como parte de la URL de la solicitud.
POST
Hay dos configuraciones diferentes para una solicitud POST dependiendo de cuántos registros envíes.
Si deseas enviar un solo registro, puedes configurar la integración y el archivo de etiqueta igual que para una solicitud GET. Los datos se envían en el cuerpo de la solicitud en lugar de en la URL.
Si deseas enviar varios registros, la configuración es la siguiente:
- La etiqueta está conectada a una base de datos de texto como JSON o CSV.
- La integración sobrescribe la base de datos en la acción Imprimir documento para usar %EventData%.
- Uno o más registros se envían como cuerpo de la solicitud en el mismo formato que usa la base de datos de texto conectada a la etiqueta.
Para este ejemplo, los archivos de muestra son un solo registro que se puede enviar tanto por solicitud GET como POST. Esta es una configuración bastante común y la más sencilla.
Para más información y solución de problemas, puedes consultar estos artículos:
- ¿Puedo enviar varios registros en una integración de servicio web?
- Guía de solución de problemas: Integraciones
Desempaquetar el ejemplo
Sigue estos pasos para desempaquetar el ejemplo y configurarlo:
- Descarga el paquete de ejemplo: TempIntegration.zip
- Descomprime los archivos de integración y etiqueta en C:\TempIntegration\
- Abre la integración
- Haz clic en la acción Imprimir documento y luego en la pestaña Opciones de impresión.
- Cambia la impresora por una que tengas en tu sistema.
Configurar la solicitud
Para esta sección, necesitarás Insomnia, Postman o una aplicación similar para enviar una solicitud web. Tanto para POST como para GET, la URL de la solicitud requiere una URL de integración. Puedes encontrar esta URL en Integration Builder en la sección Servicio. Esta captura de pantalla es del archivo de integración de ejemplo. La sección resaltada en amarillo será la URL de integración:
Si ya has usado integraciones de servicios web antes, esta URL te resultará familiar. Al enviar una solicitud de servicio web normal, envías la solicitud a esta ruta URL completa para activar la integración e imprimir. Sin embargo, al usar el passthrough, enviamos la solicitud a BarTender Print Portal, pero necesita saber a qué integración enviarla. Se lo indicamos proporcionando la URL de integración.
Para GET y POST, la URL de la solicitud web tendrá este formato:
https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=[IntegrationURL]
Observa que esta URL es diferente a la que aparece en el archivo de integración. Está enviando la solicitud a través del Integration Passthrough, que luego la reenvía a la targetURL.
Para nuestros archivos de ejemplo, completando la URL de integración, la URL completa de la solicitud será:
https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
Los siguientes ejemplos usan la URL anterior. Si usas tus propios archivos, reemplaza la URL de integración de ejemplo por la que corresponda a tu integración.
http://localhost/BarTender/API/Integration/WebServiceIntegration/Execute
Crear una solicitud GET
Una solicitud GET envía toda la información en la URL. Esto suele hacerse completando la información del encabezado. Sin embargo, como Integration Passthrough requiere el parámetro targetURL, los datos de la etiqueta deben colocarse en otra ubicación.
Para Insomnia (en la captura de pantalla de abajo), la ubicación correcta es Query. Para Postman, la ubicación es Params.
Si estás construyendo tu propia URL, agrega cada parámetro a la URL como un par clave-valor, separados por un & entre cada par, como en la vista previa de la URL en la captura de pantalla anterior.
Estos son los datos usados en este ejemplo:
- URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
- Pares clave-valor:
- Company: company
- IDNumber: 3
Crear una solicitud POST
Una solicitud POST envía los datos en el cuerpo de la solicitud en lugar de en la URL. Al igual que la solicitud GET, la solicitud POST tiene un parámetro targetURL para indicar a Integration Passthrough a dónde enviar la información.
Si revisaste todas las configuraciones en el archivo de integración, habrás notado que los Datos de entrada están configurados como JSON. La integración es capaz de analizar automáticamente los pares clave-valor de JSON en variables utilizables sin que tengas que hacer trabajo adicional ni agregar acciones. Si planeas enviar solo un registro, esta puede ser una buena opción para ti.
Estos son los datos usados en este ejemplo:
- URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
- Datos del cuerpo: {"Company": "The Company", "IDNumber": "3"}
Enviar la solicitud
Con todo configurado, ya puedes enviar tu solicitud.
- Inicia la integración. Haz clic en la pestaña Probar y luego en el gran botón verde Iniciar
- En la app Insomnia o Postman, haz clic en el botón Enviar. Si usas una app personalizada, inicia la solicitud normalmente.
- Vuelve a la integración. Deberías ver mensajes que empiezan a aparecer en la sección de mensajes.
- Cuando veas el mensaje indicando que el trabajo se ha enviado a la cola de impresión, ¡felicidades! Has enviado la solicitud a través del sistema Integration Passthrough y has impreso una etiqueta.
Solución de problemas
¿No salió como esperabas? Aquí tienes algunos problemas comunes que puedes encontrar.
El certificado SSL del par o la clave remota SSH no es válida
Al enviar la solicitud por primera vez, aparece este error (la captura es de Insomnia):
Este error aparece cuando usas un certificado autofirmado. Simplemente desactiva la validación SSL y vuelve a enviar la solicitud.
404 No encontrado
Al enviar la solicitud, recibes el siguiente mensaje de error como respuesta del servicio Integration Passthrough (la captura es de Insomnia):
Estas son las causas más comunes de este error:
Este error puede indicar que la integración no está en ejecución. Cuando el Passthrough intenta reenviar la información, no hay ninguna integración para recibirla. El servicio Passthrough asume que la URL es incorrecta y te responde con un 404 No encontrado. Asegúrate de iniciar tu integración antes de enviarle datos.
Este error también puede indicar que el parámetro targetURL falta o es incorrecto. Revisa la sección Configurar la solicitud para asegurarte de que tu URL sea correcta y cómo encontrar la URL de integración.
Además, este error puede indicar que Integration Passthrough no está activado. Consulta la sección Integration Passthrough para ver cómo configurarlo.
Los datos se imprimen como %VariableName% en lugar de un valor real
En tu etiqueta, puedes ver valores con % en lugar de la información real. La notación % indica una variable en el lenguaje de integración. Cuando la integración no tiene valores para poner en estas variables, simplemente envía el nombre de la variable para imprimirlo.
Cuando esto sucede, el valor (lado izquierdo) no está escrito correctamente en tu app de solicitud web o falta. El valor debe coincidir con las variables listadas en la integración. Estas variables están en la acción Imprimir documento, en la pestaña Fuentes de datos con nombre. Observa en la captura de pantalla a continuación cómo los valores de Insomnia (en negro) coinciden con los nombres de las variables en la integración (en blanco):
Lo mismo ocurre con los datos JSON del ejemplo POST.
Solo para solicitudes GET, si ves que las Fuentes de datos con nombre están configuradas y coinciden correctamente con los datos que envías pero aún así solo ves los nombres de las variables, revisa dónde estás colocando los datos para enviar. Si pones los datos en la sección Header (tanto en Insomnia como en Postman), estos datos no se transmiten a través del servicio Integration Passthrough. Vuelve a la sección Configurar la solicitud para asegurarte de que estás poniendo los datos en el lugar correcto.
Errores de integración
¿Recibes un error de integración? Consulta esta guía detallada: Guía de solución de problemas: Integraciones