Estrenando la pequeña navaja suiza

Hace un buen tiempo que no escribo artículos técnicos en este blog, así que he decidido publicar un pequeño tutorial acerca de una herramienta de interoperabilidad que nos ha sido útil en los últimos años.

En el artículo anterior, mencionábamos las características principales de Mirth Connect. 

El presente artículo, más que pretender ser una manual de usuario o una capacitación en el uso de Mirth Connect, es un sencillo ejemplo práctico de creación de un par se canales, para que los miembros de la comunidad HL7 en Español, puedan familiarizarse con el uso de esta herramienta.

El primer paso será obviamente la instalación de Mirth Connect.

Los archivos de instalación (disponibles para diversos sistemas operativos) se encuentra en la página de descargas del sitio web de Mirth Corporation.

A continuación recordamos los requerimientos del sistema:

• Java 6 o superior
• Al menos 100 MB de espacio libre en disco.
• Sistema operativo: 
• Windows (XP, Vista, 7, Server; 32 o 64 bits).
• Linux (Kernel 2.4 o superior)
• Mac OS X (10X).

El ejemplo descrito en el presente artículo funciona sobre de Mirth Connect Versión 2.2.1.5861, instalado en un sistema operativo Microsoft Windows 7 Professional de 32 bits.

Iniciando Mirth Connect.

Una vez instalado el sistema (este artículo no describe el proceso de instalación), puede apreciarse que el paquete de herramientas Mirth Connect está compuesto por cuatro (4) aplicaciones:

1. Un Servidor.
2. Un Administrador del Servidor.
3. Una Interfaz de Línea de Comandos.
4. Un Administrador del sistema.

Servidor (Mirth Connect Server): Es el corazón del sistema, encargado del funcionamiento de los canales de conexión entre aplicaciones.

La siguiente imagen ilustra como Mirth Connect, funciona como un servicio del sistema.

Administrador del Servidor (Mirth Connect Server Manager): Es la aplicación encargada de controlar el inicio, parada o reinicio del sistema, además de brindar opciones para la configuración de puertos y la conexión a la base de datos.

Interfaz de Línea de Comandos (Mirth Connect CLI): Es una aplicación que permite de controlar el funcionamiento del sistema, a través de instrucciones de líneas de texto simple.

Administrador del sistema (Mirth Connect Administrator): Es una aplicación que permite controlar el funcionamiento del sistema, a través de una interfaz gráfica de usuario, con una estética mejorada, en comparación con la Interfaz de Línea de Comandos.

A través de Mirth Connect Administrator, es posible crear, configurar y monitorear los canales de conexión, que funcionan sobre Mirth Connect Server.

El ejemplo descrito en el presente artículo, se centra en el uso de Mirth Connect Administrator.

Mirth Connect Administrator.

Para ingresar por primera vez al administrador del sistema, es necesario emplear el siguiente nombre de usuario y contraseña (por defecto).

Username: 'admin'.

Password: 'admin'.

Una vez la aplicación está en ejecución, puede apreciarse en la interfaz gráfica que el ambiente de trabajo se divide en tres áreas principales:

• El área de trabajo: Dónde se despliegan diversos formularios, de acuerdo a las opciones elegidas en los menús de opciones.
• El área de menús: Es una zona vertical localizada en la parte izquierda de la interfaz gráfica, donde se albergan tres (3) tipos de menús:

1. Menú principal: Que contiene las opciones principales de la aplicación.
2. Menú de tareas: Que contiene diversas opciones que se despliegan de acuerdo a la opción elegida en el menú principal.
3. Menú adicional: Que contiene opciones de ayuda e información general acerca del sistema.

• El área de notificación: Es una barra horizontal localizada en la parte inferior de la interfaz gráfica, donde se despliegan notificaciones de texto con información sobre el estado y funcionamiento del sistema.

El menú principal cuenta con siete (7) opciones:

Tablero de Control (Dashboard). Canales de Conexión (Channels). Usuarios (Users). Configuración (Settings). Alertas (Alerts). Eventos (Events). Extensiones (Extensions).

Cada una de las opciones del menú principal despliega un menú de tareas particular.

Tablero de Control.

Esta opción permite acceder a una tabla de visualización de comportamiento de los canales desplegados en el servidor, proporcionando información acerca del estado de la conexión, cantidad de mensajes enviados, recibidos, errores, alertas, logs, etc.

Canales de Conexión.

Esta opción permite acceder a un listado de canales, facilitando tareas como:

• El despliegue de canales en el servidor.
• La creación de nuevos canales.
• La edición de canales.
• La edición de scripts globales.
• La exportación e importación de canales.

Usuarios.

Esta opción permite acceder al listado de usuarios del sistema, facilitando tareas como la creación, edición y eliminación de éstos.

Configuración.

Esta opción permite acceder a los formularios de configuración del servidor, de administración del sistema y de depuración de mensajes.

Alertas.

Esta opción permite acceder a un formulario de configuración de alertas, que facilita el envío de mensajes de correo electrónico a los usuarios del sistema, de acuerdo a la programación de una serie de eventos.

Estas alertas ofrecen la posibilidad de que los encargados de los diferentes canales de interoperabilidad estén enterados del funcionamiento, sin necesidad de acceder directamente a Mirth Connect Administrator.

Eventos.

Esta opción permite acceder al listado de registro de eventos del sistema.

Extensiones.

Esta opción permite acceder al listado de extensiones (plugins y connectors) del sistema, facilitando tareas para instalar/des-instalar, habilitar/inhabilitar y actualizar los mismos.

A esta altura, el lector ha tenido un primer acercamiento con Mirth Connect y con el ambiente de trabajo de Mirth Connect Administrator, así que nos pondremos manos a la obra con el ejemplo práctico.

Ejemplo Práctico.

El escenario de interoperabilidad.

El escenario planteado para este ejemplo, es muy sencillo, pero su finalidad, tal como ya se había mencionado, es permitir que el lector se familiarice con el ambiente de trabajo de Mirth Connect y comprenda en forma práctica los conceptos básicos de la creación de canales de conexión.

Se trata de crear dos canales:

El primero, se encarga de exponer un Servicio Web (SOAP), cuya función es recibir mensajes en formato XML, los cuales posteriormente almacena como archivos en un directorio local llamado 'InBox'.

El segundo, se encarga de leer nuevos archivos XML de un directorio local llamado 'OutBox', y codificarlos  dentro del SOAP Envelope correspondiente para ser enviados al Servicio Web del primer canal.

Supondremos que el lector está previamente familiarizado con los conceptos empleados en el escenario, tales como, XML, Web Services, WSDL, SOAP, etc.

Paso 1: Crear un canal nuevo.

En el menú principal, seleccionar la opción 'Channels' y elegir la opción 'New Channel' en el menú de tareas de canal (Channel Tasks), tal como se ilustra en la siguiente imagen.

A continuación se despliega la interfaz gráfica de edición de un nuevo canal de conexión, tal como se aprecia en la siguiente imagen.

Paso 2: Diligenciar el formulario de sumario y configuración general del canal.

El formulario ubicado en la primera pestaña de edición (creación) del canal, permite ingresar información como:

• El nombre del canal.
• El tipo de datos que administrará el canal.
• Su estado inicial.
• Los parámetros de configuración general de los mensajes.
• Una descripción del canal.

La siguiente imagen muestra los parámetros que deben asignarse.

Paso 3: Elegir los tipos de datos.

El botón 'Set Data Types' del formulario de sumario, despliega una ventana emergente, que permite elegir los tipos de datos o formatos estándar de mensajes entrada y salida de la fuente, así como del destino del canal de conexión.

Mirth Connect permite los siguientes formatos de mensajes: HL7 v2.x, HL7 v3.0, X12, EDI, XML, NCPDP, DICOM o Texto delimitado.

En la siguiente imagen se aprecia los tipos de datos que deben elegirse, para el caso de este ejemplo.

Paso 4: Diligenciar el formulario de fuente del canal.

La segunda pestaña de edición (creación) del canal, permite asignar los parámetros de configuración de la fuente de conexión.

Dichos parámetros dependerán del tipo de conector elegido.

Por defecto, la fuente emplea conector tipo MLLP (LLP Listener), el cual es el protocolo de comunicación usual empleado en mensajería HL7 v2.x (Sockets).

Sin embargo, Mirth Connect permite elegir entre, varios tipos de conectores (Database Reader, File Reader, HTTP Listener, JMS Reader, TCP Listener, etc.).

Para el caso de este ejemplo, se debe elegir la opción 'Web Service Listener' y diligenciar el formulario correspondiente, para crear un servicio web, cuyos parámetros se aprecian en la siguiente imagen.

Mirth Connect creará un servicio web por defecto, cuya función es únicamente recibir mensajes SOAP, publicado a través de la siguiente URL WSDL: http://localhost:7001/services/example?wsdl.

Paso 5: Crear y configurar un destino para el canal.

La segunda pestaña de edición (creación) del canal, permite asignar los parámetros de configuración del destino del canal, a través del cual la información va a ser enviada al (las) aplicación(es) finales.

Mirth Connect permite el funcionamiento de múltiples destinos (salidas de información) del canal.

Al igual que en la configuración de la fuente del canal, es necesario elegir un tipo de conector.

Por defecto, Mirth Connect emplea conector destino de tipo 'File Writer', sin embargo, permite elegir entre, varios tipos de conectores (Channel Writer, DICOM Sender, Database Writer, Document Writer, HTTP Sender, JMS Writer, JavaScript Writer, MLLP Sender, SMTP Sender, TCP Sender y WebSerivce Sender). 

Para el caso de este ejemplo, se debe elegir la opción 'File Writer' y diligenciar el formulario correspondiente, para que el mensaje XML recibido a través del Servicio Web, sea almacenado en un directorio local.

El formulario debe diligenciarse de acuerdo a los parámetros que se observan en las siguientes imágenes:

Paso 6: Guardar (salvar) el canal.

Una vez configurados el sumario, la fuente y el destino del canal, es necesario preservar los parámetros, guardando (salvando), la información.

Para ello, se debe hacer click en el icono 'Save Changes' localizado en el menú de tareas del canal.

Paso 7: Desplegar el canal en el servidor.

Para poner en producción (en funcionamiento) en canal de conexión, es necesario que Mirth Connect Administrator instale en Mirth Connect Server, el script que contiene los parámetros del canal de conexión. Este procedimiento se conoce como 'Desplegar el Canal' (Deploy Channel).

Para ello, siga las siguientes instrucciones:

• En el menú principal, elija la opción 'Channels'.

• En el área de trabajo se desplegará la lista de canales, donde se incluye el canal recién creado.

• Seleccione el canal correspondiente, haga click derecho sobre él y seleccione la opción 'Habilitar Canal' (Enable Channel) en el menú desplegable.

• Seleccione nuevamente el canal, haga click derecho sobre él y seleccione la opción 'Desplegar Canal' (Deploy Channel) en el menú desplegable.

• Inmediatamente se desplegará el 'Tablero de Control', donde puede apreciarse que el canal está disponible en Mirth Connect Server.

Paso 8: Comprobar el funcionamiento del canal.

Con el fin de verificar si el canal funciona correctamente, es necesario probar si el Servicio Web (fuente del canal), está disponible.

Para ello, es necesario abrir un navegador web (web browser) y digitar en la barra de direcciones la URL WSDL correspondiente (http://localhost:7001/services/example?wsdl).

Si en el navegador se visualiza la estructura del WSDL (Web Service Description Language), el canal está funcionando correctamente.

Paso 9: Crear y configurar el canal que envía los datos al Servicio Web.

Los pasos 1 a 8 especificaron como crear, parametrizar, desplegar y comprobar el funcionamiento del primer canal; es necesario realizar un proceso similar para crear un segundo canal, cuya finalidad es enviar los datos hacia el Servicio Web.

Para ello, siga las siguientes instrucciones:

• Crear un nuevo canal, para formatos o tipos de datos XML, de acuerdo a los parámetros que se observan en la siguiente imagen:

• Crear la fuente del canal con un conector tipo 'File Reader', de acuerdo a los parámetros que se observan en la siguiente imagen:

• Crear un destino del canal, con un conector de tipo 'Web Service Sender', de acuerdo a los parámetros que se observan en la siguiente imagen:

• Insertar la URL WSDL del Servicio Web del canal 'Receptor-WebService' (dicho canal debe estar desplegado en Mirth Connect Server) y visualizarse como 'Iniciado' (Started) en el 'Tablero de Control'.

• Hacer click en el botón 'Get Operations' del formulario, para obtener automáticamente los parámetros de 'Servicio' y 'Puerto', descritos en el WSDL del Servicio Web.

• Hacer click en el botón 'Generate Envelope', para obtener la estructura del 'SOAP Envelope' descrito en el WSDL del Servicio Web.

• Embeber la variable que contiene el archivo XML transformado (serializado), dentro del mensaje, arrastrando las variables de mapeo (Destination Mappings) al interior del nodo '/soapenv:Envelope/soapenv:Body/ws:acceptMessage[1]/arg0[1]' de la estructura del SOAP Envelope.

• Otra opción para embeber la variable que contiene el archivo XML transformado (serializado), dentro del mensaje, es digitar la línea '${XmlUtil.encode(${message.encodedData})}' al interior del nodo '/soapenv:Envelope/soapenv:Body/ws:acceptMessage[1]/arg0[1]' de la estructura del SOAP Envelope.

• Guardar (salvar), habilitar y desplegar el canal de conexión.

Paso 10: Compruebe el funcionamiento de los canales.

Ya tenemos dos canales desplegados en Mirth Connect Server; para verificar su funcionamiento:

• Abrir el directorio local 'D:/OutBox'.
• Guardar un archivo XML dentro del directorio.
• El canal 'Emisor-WebService', leerá el archivo y empleando el protocolo SOAP, enviará este archivo al Servicio Web.
• El canal 'Receptor-WebService', recibirá el mensaje SOAP y almacenará el archivo en el directorio local 'D:/InBox'.
• El archivo XML será borrado automáticamente del directorio 'D:/OutBox' y éste será almacenado dentro del directorio 'D:/InBox'.

En este enlace, podrán encontrar una copia de los canales relacionado con el ejemplo descrito (MC versión 3.0.0).

Copia de los canales de ejemplo (MC versión 3.2.1).

Cambios de versión de los canales de conexión.

Es frecuente que al instalar una nueva versión de Mirth Connect, sea necesario importar canales de conexión que funcionaban bajo versiones anteriores.

El ejercicio descrito en este post, fue realizado en Mirth Connect versión 3.0.0.

Si usted está utilizando versiones posteriores (p ej: v3.2.1), y desea importar los canales de ejemplo, deberá realizar previamente una actualización de éstos, para que funcionen correctamente.

Cambio de versión del canal de conexión (automáticamente).

En el momento de realizar el procedimiento de importación de los canales en Mirth Connect, el administrador del sistema detectará la diferencia de versiones y sugerirá convertir el canal al formato de la nueva versión.

Elija "Si" (Yes).

Cambio de versión del canal de conexión (manualmente).

Si el administrador de Mirth Connect no detecta automáticamente la diferencia de versiones, trate de realizar la conversión manualmente.

Antes de proceder a importar los canales, abra los archivos en un editor XML y modifique el valor de la versión en el atributo @version, de cada uno de los siguientes elementos:

XPath	Elemento
/channel/@version	<channel version="3.2.1">
/channel/sourceConnector/@version	<sourceConnector version="3.2.1">
/channel/sourceConnector/properties/@version	<properties class="com.mirth.connect.connectors. file.FileReceiverProperties" version="3.2.1">
/channel/sourceConnector/properties/ pollConnectorProperties/@version	<pollConnectorProperties version="3.2.1">
/channel/sourceConnector/properties/ responseConnectorProperties/@version	<responseConnectorProperties version="3.2.1">
/channel/sourceConnector/transformer/ @version	<transformer version="3.2.1">
/channel/sourceConnector/transformer/ inboundProperties/@version	<inboundProperties class="com.mirth.connect.plugins.datatypes. xml.XMLDataTypeProperties" version="3.2.1">
/channel/sourceConnector/transformer/ inboundProperties/serializationProperties/@version	<serializationProperties class="com.mirth.connect.plugins.datatypes. xml.XMLSerializationProperties" version="3.2.1">
/channel/sourceConnector/transformer/ outboundProperties/@version	<outboundProperties class="com.mirth.connect.plugins. datatypes.xml.XMLDataTypeProperties" version="3.2.1">
/channel/sourceConnector/transformer/ outboundProperties/serializationProperties/@version	<serializationProperties class="com.mirth.connect.plugins. datatypes.xml.XMLSerializationProperties" version="3.2.1">
/channel/sourceConnector/filter/@version	<filter version="3.2.1">
/channel/destinationConnectors/connector/@version	<connector version="3.2.1">
/channel/destinationConnectors/ connector/properties/@version	<properties class="com.mirth.connect.connectors.ws. WebServiceDispatcherProperties" version="3.2.1">
/channel/destinationConnectors/connector/ properties/queueConnectorProperties/@version	<queueConnectorProperties version="3.2.1">
/channel/destinationConnectors/connector/ transformer/@version	<transformer version="3.2.1">
/channel/destinationConnectors/connector/ transformer/inboundProperties/@version	<inboundProperties class="com.mirth.connect.plugins.datatypes xml.XMLDataTypeProperties" version="3.2.1">
/channel/destinationConnectors/connector/transformer/ inboundProperties/serializationProperties/@version	<serializationProperties class="com.mirth.connect.plugins. datatypes.xml.XMLSerializationProperties" version="3.2.1">
/channel/destinationConnectors/connector/ transformer/outboundProperties/@version	<outboundProperties class="com.mirth.connect.plugins. datatypes.xml.XMLDataTypeProperties" version="3.2.1">
/channel/destinationConnectors/connector/transformer/ outboundProperties/serializationProperties/@version	<serializationProperties class="com.mirth.connect.plugins. datatypes.xml.XMLSerializationProperties" version="3.2.1">
/channel/destinationConnectors/connector/ responseTransformer/@version	<responseTransformer version="3.2.1">
/channel/destinationConnectors/connector/ responseTransformer/inboundProperties/@version	<inboundProperties class="com.mirth.connect.plugins. datatypes.xml.XMLDataTypeProperties" version="3.2.1">
/channel/destinationConnectors/connector/ responseTransformer/inboundProperties/ serializationProperties/@version	<serializationProperties class="com.mirth.connect.plugins. datatypes.xml.XMLSerializationProperties" version="3.2.1">
/channel/destinationConnectors/connector/ responseTransformer/outboundProperties/@version	<outboundProperties class="com.mirth.connect.plugins. datatypes.xml.XMLDataTypeProperties" version="3.2.1">
/channel/destinationConnectors/connector/ responseTransformer/outboundProperties/ serializationProperties/@version	<serializationProperties class="com.mirth.connect.plugins. datatypes.xml.XMLSerializationProperties" version="3.2.1">
/channel/destinationConnectors/ connector/filter/@version	<filter version="3.2.1">
/channel/properties/@version	<properties version="3.2.1">

NOTA: El ejemplo descrito en este artículo es trivial, así que, si el lector lo considera oportuno y desea aprender un poco más por su cuenta, lo invito a que realice una prueba un poco más compleja, empleando dos equipos de cómputo en red, instalando Mirth Connect en cada equipo, desarrollando canales con formatos de datos y protocolos o metodologías de transporte diferentes para intercambiar mensajes entre dos puntos.

Guía de usuario.

En el siguiente enlace puede descargar la guía de usuario de Mirth Connect (versión 3.1).

http://info.mirth.com/Connect_Documentation_Download.html

Fuente de la imagen info.mirth.com.

Más sobre Mirth Connect.

Para más información acerca del uso de Mirth Connect, recomiendo los siguientes vídeo enlaces:

Part 1 – Overview (25:30) 

Part 2 – Installation (8:00)

Part 3 – Administrator (21:54)

Part 4 – HL7 Mapping and Routing (10:12)

Part 5 – HL7 Message Building (6:53)

Part 6 – Scripting and Code Templates (5:59)

Part 7 – Administrative Operation (6:38)

Mirth Connect 3.0 - Advanced Alerting Demo.

El artículo "Mirth Connect Introduction and Tutorial", de Reza Alemy, es un excelente material de consulta.

Post recomendados.

Mirth Connect (I): introducción a la herramienta.

Informática Sana.

Autor: Francisco J. Carrasco

Fecha: 2014-04-11

Mirth Connect (II): canales y conectores.

Informática Sana.

Autor: Francisco J. Carrasco

Fecha: 2014-04-15

Mirth Connect (III): el panel de administración.

Informática Sana.

Autor: Francisco J. Carrasco

Fecha: 2014-04-23

Mirth Connect (IV): consejos útiles y buenas prácticas (i).

Informática Sana.

Autor: Francisco J. Carrasco

Fecha: 2014-05-06

Mirth Connect (V): consejos útiles y buenas prácticas (ii).

Informática Sana.

Autor: Francisco J. Carrasco

Fecha: 2014-05-15

Espero que este artículo haya sido de utilidad para que el lector comprenda los conceptos básicos del uso de Mirth Connect.

Si desea profundizar en el uso de esta herramienta de interoperabilidad, estoy seguro que la investigación,  el estudio de nuevos casos, la práctica, la capacitación y la asesoría especializada, le permitirá emplear Mirth Connect como una alternativa en ciertos escenarios de interoperabilidad.