Implementar Integraciones IRIS con .NET o Java usando PEX

Metodo	Implementación Inicial
OnInit	OnInit public override void OnInit()         {             LOGINFO("PEX.Webinar.FirstDemo.FirstOperation:OnInit()");         }
OnTearDown	OnTearDown public override void OnTearDown()        {            LOGINFO("PEX.Webinar.FirstDemo.FirstOperation:OnTearDown()");        }
OnMessage	OnMessage public override object OnMessage(object request)        {            LOGINFO("PEX.Webinar.FirstDemo.FirstOperation:OnMessage()");            return request;        }

 

Con esto, se puede compilar esta versión Inicial del proyecto .NET, con el Menú "Build Solution". Esto genera el fichero siguiente, que se utiliza a continuación  desde IRIS:

Creación de una Producción de Interoperabilidad InterSystems IRIS

Ahora, desde el Portal de Gestión de IRIS, se puede escoger el menú "Interoperability", el namespace "Ensemble",  y los menus "Configure", "Production". La pestaña "Actions", y el botón "New" permiten definir una nueva producción de Integración de IRIS.

Para activar el Servicio de Pruebas, se selecciona la pestaña "Settings" y en el último apartado de la lista ("Development and Debugging") se habilita "Testing Enabled" y se hace click sobre el botón Apply:

 

Añadir el NET Gateway a la Producción

Para poder trabajar con PEX, se debe arrancar el Gateway de Java o .NET correspondiente. InterSystems recomienda configurar y arrancar estos gateway desde el menú "System Administration / Configuration / Connectivity / Object Gateways" par entornos de producción  (live). Para este entorno de desarrollo, se puede añadir directamente un componente a la producción para arrancar el Gateway. Esto permite arrancar y parar el gateway al mismo tiempo que la producción en un solo click, y así liberar el acceso a la .DLL de proyecto de .NET cuando se quiere re- compilarla (Visual Studio no la puede recompilar si el .NET gateway está arrancado).

 

Para añadir el componente ".Net Gateway", se añade un Business Service a la producción con el botón "+" al lado de "Services". El nombre de clase del componente (Service Class) a añadir es "EnsLib.DotNetGateway.Service", y se selecciona "Enable now" para habilitar el componente.

 

Se editan los parámetros de configuración del componente añadido, haciendo click sobre este, y rellenando a continuación los valores en la pestaña "Settings", seleccionado finalmente el botón "Apply":

 

Añadir el Business Operation creado en .NET 

Se añade ahora un Business Operation de PEX para referenciar el código .NET creado anteriormente, con el botón "+" al lado de "Operations". El tipo de clase es "EnsLib.PEX.BusinessOperation", se nombra el componente (opcional) "PEX.Webinar.FirstOperation",  se habilita con "Enable Now".

 

A continuación, se configura el componente (haciendo click sobre el componente añadido) y seleccionando la pestaña "Settings" a la derecha: 

Para aplicar los cambio, se hace click sobre el botón "Apply":

 

Arrancar la Producción y Probar

El botón "Start" permite arrancar la producción y todos sus componentes:

InterSystems IRIS permite probar de manera simple y aislada un componente. Se hace click para seleccionar el "Business Operation" llamado "PEX.Webinar.FirstOperation",  y se selecciona el botón "Test" de la pestaña Actions:

 

En la pantalla siguiente, se rellenan los datos como sigue:

 

Cuando se hace click en "Invoke Testing Service", el framework de Interoperabilidad de IRIS envía el mensaje al componente y el código .NET se ejecuta.

Haciendo click sobre el "Visual Trace", se pueden ver los detalles. El punto blanco numerado "3" muestra la traza "LOGINFO" implementada en .NET. 

El Log de Eventos de IRIS contiene un recopilatorio de todos los mensajes LOGINFO() generados, incluidos en OnInit() y OnTearDown().

 

Siguientes Pasos con PEX: Completando la producción

A continuación se crean componentes de otros tipos en .NET: 

• Mensajes .NET
• Business Services .NET
• Business Process .NET 

Creación y uso de un mensaje PEX con datos

Para pasar información desde Ensemble a componentes PEX, se define una clase en  .NET como subclase de InterSystems.EnsLib.PEX.Message, con las propiedades para la información que se quiere pasar. Siguiendo con un ejemplo simplificado, añadimos una propiedad "value" de tipo string al mensaje. El Business Operation PEX devolverá el mismo tipo de mensaje, con el contenido transformado a majusculas.

Clase de mensaje en .NET

Se añade un nuevo fichero "FirstMessage.cs" as proyecto .NET, con la siguiente definición:

FirstMessage

 

Uso del mensaje desde .NET

En el Business Operation FirstOperation, el tipo de Datos de OnMessage está definido como Object. Se tiene que hacer el cast a la clase "FirstMesssage" para usarlo:

 

OnMessageV2

Es necesario parar la producción de IRIS (con el botón "Stop"), o como mínimo deshabilitar el .NET Gateway (doble-click sobre el componente), y recompilar el proyecto .NET

Uso de la clase desde InterSystems IRIS

El botón "Test" (Testing Service) no permite rellenar las propiedades dinámicas de la clase EnsLib.PEX.Message. Sin embargo, se puede usar el Testing Service con un mensaje de tipo "Ens.StringRequest" nativo de IRIS, y transformar (Con una Transformación de Datos) este mensaje en un mensaje PEX desde una transformaciçon de datos. La transformación se invocar desde un Business Process de tipo Enrutador ya pre-construido.

Transformación de Datos

Se crea una Transformación de Datos para copiar los datos del mensaje nativo ensemble:

 

La Transformación de Datos se puede crear desde el portal de gestión "Interoperability" / "Build" / "Data Transformations", con el botón "New":

 

A continuación se definen las transformaciones del mensaje "source" al "target" como descrito en la tabla anterior, usando la herramienta gráfica y completando el texto en la pestaña "Action" a la derecha, para obtener las 2 líneas de texto mostradas abajo. Después, se puede guardar (botón "Save"), Compilar (botó "Compile") y probar con la pestaña "Tools".

 

Ahora, abriendo la pestaña tools, se puede probar esta Transformación de Datos:

 

Se abre la Ventana de Pruebas, donde se puede especificar valores para el mensaje de origen (en StringValue) y verificar el resultado:

Como se puede ver, el mensaje PEX usa una representación interna en json para traspasar los valores entre IRIS y Java o .NET.

 

Creación de un Business Process de tipo Enrutador

Ahora es posible añadir un Business Process de tipo Enrutador a la Producción, y definir una regla de Enrutamiento que llame a la Transformación de Datos creada e envie en mensaje al Business Operation existente.

En el portal de getión, se vuelve a la pantalla de Configuración de Producción ( "Interoperability" / "Configure" / "Production"), y se añade el Business Process de tipo "EnsLib.Message.Router", haciendo "click" sobre el "+" al lado de "Processes", y rellenando como sigue:

 

Queda por Editar la Regla de Enrutamiento de este Componente. Par esto se selecciona el componente "MessageRouter" en la producción, y se hace "click" sobre la lupa al lado de la Regla de Enrutamiento (Business Rule Name):

 

El editor de Reglas permite editar la Regla para enviar todos los mensajes de tipo "Ens.StringRequest" al Business Operation llamado "PEX.Webinar.FirstOperation" después de aplicarles la transformación. El botón "+" permite añadir elementos a las reglas, y se puede editar un elemento seleccionando-lo previamente. La regla a guardar debe estar como sigue:

Por defecto este componente no espera respuesta. Se cambia su configuración en la pestaña "Settings" del componente, para recibir la respuesta del Business Operation:

 

Prueba del Enrutador con el Servicio de Pruebas

De vuelta a la página de la producción, se puede usar el botón "Start" para arrancar la producción, seleccionar el componente "MessageRouter", y con la pestaña "Actions", hacer click sobre el botón "Test", para enviar un mensaje de tipo "Ens.StringRequest":

 

El mensaje de Respuesta de la prueba se puede ver en "Test Results", y la traza de mensaje completa muestra todos los detalles de la ejecución en los distintos componentes de la producción de Interoperabilidad de IRIS:

Respuesta:

 

Traza de los mensajes:

 

Business Service en .NET

Implementación en .NET

Se vuelve a Visual Studio para crear un Business Service en .NET. En este ejemplo Inicial, este Business Service no tiene "Inbound Adapter" especifico asociado; Se usa el "EnsLib.InboundAdapter", un componente que se ejecuta a intervalos regulares (según el valor de CallInterval) y hace una llamada al Business Service cada CallInterval. 

En Visual Studio, se genera un nuevo fichero "FirstService.cs", para la clase "FirstService". El procesamiento de cada evento detectado por el Inbound Adapter se hace en el método "OnProcessInput". El objeto pasado en parámetro depende de la implementación del InboundAdapter, es este caso no se usa:

FirstService:OnProcessInput

FirstService:OnProcessInput

 

Para poder enviar el mensaje a cualquier componente de la producción si tener que recompilar, se puede usar un parámetro que se configure desde el portal de gestión; los valores se especifican en formato de una cadena json dentro del parámetro de configuración "RemoteSettings".

Parameters

 

Si el valor especificado parar "TargetConfigName" esta a null, el Business Service no podrá enviar el mensaje a ningún destino. Para detectar este problema lo antes posible, una opción es validar el valor de TargetConfigName cuando se inicia el componente, en la llamada a OnInit():

FirstService:OnInit

Ahora, se puede Cambiar el OnProcessInput para  usar el valor de TargetConfigName:

OnProcessInput

 

Business Service PEX en InterSystems IRIS

En el portal de Gestión, en la definición de la Producción se añade un componente de tipo Business Service, haciendo click sobre el "+" al lado de 

 

A continuación, se configura el componente (haciendo click sobre el componente añadido) y seleccionando la pestaña "Settings" a la derecha: 

 

Al Activar este Business Service, cada CallIntervall el OnTask() del adaptador asociado (Ens.InboundAdapter) se ejecuta. Aquí, el OnTask simplemente llama FirstService.OnProcessInput(). Es Decir, cada callInterval, FirstService.OnProcessInput() genera un mensaje que envia al componente definido en "TargetConfigName". La Traza de Mensajes (Message Viewer) permite verificar esto:

 

Con los detalles de una llamada:

 

 

Business Process .NET

Implementación .NET

Como Cada Business Host, el Business Process tiene los Metodos de CallBack OnInit() y OnTearDown(). Los Metodos especificos de un Business Process son los siguientes:

Es importante notar que un Business Process puede tener una ejecución que se alarga en el tiempo (horas o días, esperando una respuesta asíncrona). Para permitir esto, el Framework de IRIS puede interrumpir y reanudar la ejecución de un proceso. Todos los valores que se quieren mantener durante un proceso se tienen que poner en propiedades de la clase que IRIS guarda de manera persistente. Para esto, es necesario indicarlo con la anotación "[persistent]".

En este Ejemplo, se realiza una implementación minimalista, donde el Business Process enruta a un destino el mensaje PEX que recibe:

Se usan 2 variables que se pueden modificar desde el portal de Gestión:

FirstProcess

 

Cuando recibe un mensaje se envia de manera asincrona al TargetConfigName:

FirstProces:OnRequest

En OnResponse permite gestionar las respuestas de las llamadas:

FirstProcess:OnResponse

Y al finalizar el proceso, se devuelve la respuesta:

FirstProcess:OnComplete

 

Business Process PEX en Intersystems IRIS

Se añade un Business Process de tipo EnsLib.PEX.BusinessProcess, se configura como sigue, y se cambia el TargetConfigName del Business Service "PEX.Webinar.FirstProcess" para enviar los mensajes al nuevo Processo en vez de enviarlos dicectamente al BO. 

 

Los "Settings" del componente se definen así:

El Resultado en la traza es este:

 

Conclusión

PEX permite implementar integraciones en .NET o Java de manera muy fluida y ofrece toda la potencia y robustez de la capa de interoperabilidad de InterSystems IRIS para desarrolladores con experiencia en estos lenguajes.