Enviar Correos Electrónicos HTML Con SOA Suite 12c Usando El Adaptador UMS

Algo muy requerido hoy en día es la necesidad de notificar sobre alguna advertencia y/o errores en la ejecución de un proceso (sea OSB o BPEL) por medio de envío de correos electrónicos a quienes se encargan de solventar estos incidentes.

Esto es posible gracias al Adaptador UMS que provee SOA Suite 12c, haciendo que lograr esto no resulte tan complejo ni caotico.


Prerrequisitos

• Verificar que el Adaptador UMS se esté ejecutando y funcionando (ver mas adelante)
• Configurar el driver de correos para un servidor de correos (ver el siguiente articulo: https://soajp.blogspot.com/2018/01/configurar-gmail-como-proveedor-de.html)



Verificando el estado del Adaptador UMS en WebLogic

Antes de empezar a programar un proxy OSB o proceso BPEL, es necesario corroborar el estado del Adaptador UMS, ya que el mismo por defecto se encuentra en estado "Installed" lo cual significa que solo se encuentra instalado y que no esta activo ni funcionando:

En cuyo caso, será necesario activar el adaptador. Para realizar esto, nos dirijimos a la consola de WebLogic (http://localhost:7001/console) y desde el panel izquierdo Domain Structure hacemos clic en Deployments:

Buscar el Adaptador UMS (UMSAdapter) y accede a su configuración haciendo clic en su nombre:

Luego accede a la pestaña "Targets" y marca todos los servidores y manejados (donde AdminServer es totalmente requerido) por el cual queramos que UMSAdapter sea alcanzado. Haga clic en el botón Save para guardar los cambios:

Advertencia: es probable que este cambio necesite que el componente UMSAdapter sea actualizado o tenga que reiniciar el dominio.

Finalmente veremos como el componente UMSAdapter ahora se encuentra activo y funcionando:

Enviar Mensajes HTML con UMS Adapter en JDeveloper 12c

La configuración de este Adaptador tanto en OSB como en BPEL es exactamente igual... el proceso varia un poco en ciertos puntos por las característica que los diferencias. Mas adelante veremos como hacer este proceso en BPEL, pero se aclarará como debería hacerse en OSB. Como extra, adjuntaré un proyecto en OSB que funciona a la perfección por si quieres revisarlo.

Para este ejemplo, se usará un proyecto SOA tipico con un proceso BPEL Síncrono que nos permitirá mostrar como realizar los ajustes en el adaptador UMS. El composite inicial es el siguiente:

Y el proceso BPEL:

Arrastrar y soltar un adaptador UMS en el carril de Referencias en el composite.xml:

Darle un nombre al Adaptador y hacer clic en el botón Next >:

Aceptar el eis JNDI por defecto (eis/ums/UMSAdapterOutbound) y hacer clic en el botón Next >:

Dejar seleccionada la opción "Outbound Send Notification" y el nombre de la operación por defecto"SendNotification" como se muestra en la siguiente figura:

Seleccionar la opción "Email" y completar los campos: Subject, From y To con datos ficticios ya que estos datos serán reemplazados dinamicamente a traves del mensaje de entrada (request):

Seleccione la opción "Message is Opaque (Base64Binary)" para poder mandar el HTML encriptado en Base 64:

Para terminar de crear el Adaptador, hacer clic en el botón Finish:

Una vez terminado de crear el adaptador, en el caso de BPEL debemos conectar el proceso BPEL con el Adaptador usando un cable... en el caso de OSB, es necesario llamar al "Business Service" que ha creado el Adaptador con un "Service Callout":

ACLARACIÓN:
El Adaptador UMS al configurarlo que acepte mensajes en Base64Binary es necesario encriptar el mensaje HTML a Base64, esto se realiza muy facilmente con 4 o 5 lineas en Java. Para el caso de BPEL basta con usar una actividad "Java Embedding" y en OSB basta con crear una Clase Java que sea llamada desde un "Java Callout".

A continuación el codigo Java para BPEL y el codigo Java para OSB, que si bien son similares son distintos para cada tecnología:


Código Java para codificar a Base64 en BPEL:

addAuditTrailEntry("Base64encode started");  
try {  
  java.lang.String input_str = (String)getVariableData("htmlString");
  addAuditTrailEntry("Input String = " + input_str);
  oracle.soa.common.util.Base64Encoder encoder = new oracle.soa.common.util.Base64Encoder();      
  java.lang.String encoded = null;     
  encoded = encoder.encode(input_str);  
  addAuditTrailEntry("Base64 String = " + encoded);  
  setVariableData("encodedHtmlString", encoded);  
} catch (Exception e) {  
  addAuditTrailEntry("Base64encode Exception: " + e.getMessage());  
}  
addAuditTrailEntry("Base64encode ended");

Las variables remarcadas con color rojo, deben ser variables del tipo xsd:string que deben crearse globalmente en el proceso BPEL.



Clases Java para codificar a Base64 en OSB

Clase: Base64Utils.java

package encoding.utils;

public class Base64Utils {

    public static String getBase64String(String html_str) {
        try {
            html_str = html_str.replaceAll("]]>", "");
            byte[] htmlbytes = html_str.getBytes();
            java.util.Base64.Encoder encoder = java.util.Base64.getEncoder();
            String encoded = encoder.encodeToString(htmlbytes);
            return encoded;
        } catch (Exception e) {
            return("Base64encode Exception: " + e.getMessage());
        }
    }
}

Para el caso de BPEL, primero cree las 2 variables (htmlString y encodedHtmlString) del tipo xsd:string:

Arrastre y suelte un actividad "Assign" para guardar el HTML como string en la variable htmlString:

Ahora realice el mapeo del HTML como string a la variable htmlString para asignar la variable y que luego la actividad "Java Embedding" tome la variable  htmlString para realizar la encriptación a Base64.

Aclaracion: el contrato del proceso BPEL establece 3 variables del tipo xsd:string como parametros de entrada (Para, Asunto y MensajeHTML) esto se logra modificando el XSD del contrato.

Aclaración 2: en OSB este mapeo debe hacerse con un <![CDATA[]]> el cual se realiza con la función fn:concat(). Esto es necesario porque OSB maneja de otra manera el elemento xsd:string que lleva el mensaje en HTML.

Arrastre y suelte una actividad "Java Embedding" justo debajo de la actividad "Assign" anterior:

Luego abra la actividad "Java Embedding" haciendo doble clic sobre ella, y coloque el codigo Java anteriormente mencionado en su interior:

Ahora debe pasarle el Base64 al mensaje de entrada al Adaptador UMS (UMS Request), para esto, arrastre y suelte una actividad "Assign" debajo de la actividad "Java Embedding":

Y realice el mapeo correspondiente haciendo doble clic sobre la actividad "Assign" y mapeando la variable encodedHtmlString a la variable del mensaje de entrada al UMS Adapter como muestra la siguiente figura:

Es hora de invocar el Adaptador UMS pasandole como parámetro el Base64, para esto es necesario que arrastre y suelte una actividad "Invoke" justo debajo de la actividad "Assign" configurada anteriormente:

Posterior a esto, debe conectar con un cable la actividad "Invoke" con el Adaptador UMS y configurar la variable de entrada al Adaptador UMS:

Ahora, vuelva a hacer doble clic sobre la actividad "Invoke" y configure las propiedades:
    • jca.ums.to
    • jca.ums.subject
    • jca.ums.msg.content-type

Aclaración: En OSB, estas propiedades deben pasarse usando una actividad "Transport Header".

También agregue una actividad "Assign" mas para establecer la respuesta del servicio (response) y hacer un mapeo de un string literal como se muestra en la siguiente figura:

Finalmente deploye su aplicación SOA y ejecútela a travez de la consola del Enterprise Manager (EM Console: http://localhost:7001/em) y podrá ver como la aplicación SOA usa correctamente el Adaptador UMS y manda mensajes con estilos usando HTML:

 

 

Archivos Adjuntos

Estos archivos son para JDeveloper 12.2.1.2.0:

BPEL:  sca_EnviarEmailConMensajesHTML.jar

OSB: EnviarMensajesHTMLConUMS_OSBProject12.2.1.2.0.jar