domingo, 17 de agosto de 2008

Aportando contenido en UCM a través de Web Services

Tuve la oportunidad de hacer una prueba sencilla de interacción con UCM en la cual se pudiera aportar un documento a través de una aplicación externa. En este ejercicio usé Jdeveloper para construir una interfaz web que permitiera capturar algunos datos básicos acerca del documento y del contribuidor del contenido, y a través de web services llevar esos metadatos y el documento como tal a UCM de tal forma que entrara en un flujo preestablecido al coincidir los metadatos.

Partimos del hecho de tener instalado UCM en la máquina, para comenzar debemos verificar que el servidor web esté corriendo (deberíamos ver la siguiente página):
Si es así, debemos verificar que el proceso del Content Server también se encuentre arriba, si hacemos clic en Login dentro de la página de Inicio de UCM y nos aparece algo como esto:
Se debe a que nuestro proceso está detenido debemos entrar a la consola de administración del proceso de Content Server haciendo clic donde nos indica la página de error e ingresar con los datos del administrador.


Acá simplemente debemos levantar el proceso haciendo clic en el ícono de “Play”.



Una vez arriba nuestro servidor ya podremos entrar a la consola del UCM y estamos listos para empezar. Antes de comenzar a interactuar con el servidor de UCM debemos realizar algunos pasos previos para crear nuestra metadata en el servidor, y configurar el flujo de trabajo que usaremos en el ejercicio.
Para crear los metadatos propios que usaremos en el ejemplo debemos usar el applet del Configuration Manager, lo podemos encontrar siguiendo el menú inicio o a través de la consola web de UCM conectados como usuarios administradores, ingresando a la opción Administration --> Admin Applets:

En el applet del Configuration Manager, nos situamos en el tab de Information Fields y creamos los siguientes campos: p_cedula, p_nombre, p_email y p_tipo, con las características siguientes:

Estos son los metadatos que vamos a recibir junto con el contenido del archivo a través de la invocación por Web Service.

Con estos datos ya estamos listos para construir nuestro Workflow de aprobación. Para ello debemos usar el Applet de Workflow Admin.

Allí iremos al tab de Criteria ya que crearemos un flujo de trabajo que será disparado al coincidir metadatos del archivo aportado. Hacemos clic en el botón Add y llenamos algunos datos básicos de nuestro flujo:

Con esto definimos que nuestro flujo de aprobación se disparará para todos aquellos documentos que tengan el valor PRUEBA para el metadato p_tipo. Es importante recordar acá que los campos creados por el usuario (en nuestro caso p_tipo, etc..) en realidad tienen un nombre interno que consta del prefijo x más el nombre que le dimos al crearlo; UCM lo guarda con ese nombre para distinguir los campos creados por el usuario (x de extendidos) de los metadatos que ya vienen con la herramienta. Este dato es importante porque luego tendremos que llamarlos con su prefijo para poder llenarles un valor desde la invocación del Web Service.

Una vez creado el flujo, comenzamos a crearle los diferentes pasos. Nuestro flujo va a ser muy sencillo, solo tendrá tres pasos: NotificarCiudadano, VerificarExpediente y NotificarCiudadanoReleased. Tanto el primero como el último son solo pasos de notificación, en el cual enviaremos un correo a la persona que aportó el contenido, en el primer paso para comunicarle que ya fue recibido y en el segundo caso para contarle que su documento fue aceptado. Para poder hacer referencia al Autor Original del contenido debemos crear un token, para ello debemos ir al submenú Tokens que se encuentra dentro del menú Options del Applet de Workflow Admin.

Allí creamos un nuevo token llamado originalAuthor que contenga el código de scripting que aparece en la imagen. Con este paso ya estamos en la capacidad de referir al autor original del contenido sin importar el paso del proceso de aprobación en el que estemos.

Configuremos el primer paso del proceso: NotificarCiudadano, refiriendo que la persona a notificar es el autor del documento.

Pasamos al tab de Exit Conditions para configurar que no esperemos revisión, ya que esto es solo un paso de notificación.

Al siguiente paso: RevisarExpediente, si vamos a configurarle un usuario específico:

Y así estaremos definiendo que debemos esperar al menos una revisión para continuar el flujo.

Y en el tercer paso NotficarCiudadanoReleased repetimos los pasos que llevamos a cabo para la primera etapa de nuestro workflow.

No olvidar habilitar el workflow, haciendo clic en el botón Enable al tener seleccionado el flujo de aprobación. Con esto ya estamos listos para construir nuestro cliente externo. Pero antes vamos a realizar un paso previo en la consola de UCM. Debido a que vamos a permitir que un usuario en general adicione contenido (aunque no sea lo que haríamos en producción), vamos a habilitar que un usuario se registre automáticamente si es la primera vez que adiciona contenido.

Entramos a la consola de UCM y vamos al Menú AdministrationàSoap Wsdls para revisar aquellos servicios de UCM que están habilitados a través de Web Services. Acá vemos que aparece el servicio de hacer CheckIn un documento, pero no el de registrar un usuario.

Aquí seleccionamos la Opción de crear un servicio, le llenamos sus datos básicos.

Luego seleccionamos la opción de Añadir un Servicio.

El cual puede tener el nombre que queramos darle, pero el atributo de IdcService si debe corresponder al de un servicio definido en la documentación del producto. Le añadimos los parámetros descritos en la documentación para este servicio del UCM y con esto ya tenemos expuesta como servicio web la funcionalidad de Registrar un usuario en UCM.

Nuestro servicio ya nos debe salir en la lista de wsdls del UCM, nuestro ejemplo se llama prueba y debe mostrarnos el wsdl al seleccionarlo.

Con esto ya lo único que nos queda es contruir la aplicación web que capturará los datos e invocará el servicio. Acá vamos a Jdeveloper y creamos una aplicación siguiendo el template de Web Application.

Nuestra aplicación es la más simple posible, sólo tenemos un jsp que se llama a sí mismo sea que hubo fallo o éxito en la operación contra UCM.

Para acceder a los servicios Web podemos usar los asistentes de Jdeveloper para construir un Web Service proxy que nos facilite la interacción con cada uno de los servicios. Este asistente nos construye una serie de clases Java que esconden la complejidad de invocación del webservice como si fuera un simple llamado a un método Java, también nos crea un Cliente java que usa dicho proxy para simplificarnos más el trabajo.

A este código que genera el asistente del Web Service Proxy solo nos faltaría añadirle los datos de conexión al web service, incluyendo los tokens de seguridad. Para ello configuramos los stubs, acá podemos dejarlo tan flexible como queramos al leer las propiedades de conexión al WS desde un properties. Para este ejercicio rápido quemé dicho código en el Stub.

public CheckInSoap_Stub(HandlerChain handlerChain) {
super(handlerChain);
_setProperty(USERNAME_PROPERTY, "sysadmin");
_setProperty(PASSWORD_PROPERTY, "idc");
_setProperty(ENDPOINT_ADDRESS_PROPERTY, "http://RST-ACT3CT2/idc/idcplg");
setSoapVersion(SOAPVersion.SOAP_11);
setServiceName( new QName("http://www.stellent.com/CheckIn/","CheckIn"));
setPortName( new QName("http://www.stellent.com/CheckIn/","CheckInSoap"));
setupConfig("proxy/runtime/CheckInSoap_Stub.xml");
}

No sería más por hacer en la capa de servicios de negocio. Ahora construimos el cuerpo de nuestro Jsp, con un formulario sencillo.

Acá capturaremos los metadatos a enviar al UCM y al oprimir el botón enviar invocamos un método del backing bean que realiza una sencilla validación de los campos y luego registra al usuario, para después aportar el documento.

El Botón Enviar invoca al método validar() del backing bean:

public String validar() {
System.out.println("Entrando al m'etodo validar");
String next = "success";
try{

if (archivo == null archivo.getValue() == null)
throw new Exception("Debe seleccionar un archivo");
if (nombre == null nombre.getValue() == null)
throw new Exception("Debe digitar su nombre");
if (cc == null cc == null)
throw new Exception("Debe digitar su documento de identidad");

registerUser();

String result = checkInFile();

FacesContext.getCurrentInstance().addMessage(null, new FacesMessage("El expediente fue enviado con exito. Detalle ["+ result + "]"));
}
catch(Exception e){
next = "failure";
FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(FacesMessage.SEVERITY_FATAL,e.getMessage(),null));
e.printStackTrace();
}
return next;
}


Despues de la validación se invoca el método registerUser() que hace la invocación a nuestro servicio prueba usando el cliente que nos creó el asistente.

private void registerUser() throws Exception {
PruebaSoapClient port = new PruebaSoapClient();
System.out.println("Llamando a : " + port.getEndpoint());
String dName, dFullName, dPassword,dEmail;
IdcPropertyList extraProps = null;

dFullName = (String)nombre.getValue();
dName = (String)cc.getValue();
dPassword = dName;
dEmail = (String)email.getValue();

port.prueba(dName, dFullName, dPassword, dEmail, extraProps);
}



Y posteriormente haremos el checkIn del archivo, enviando además del contenido la metadata capturada (Atención: Usando los nombres de los campos asignados por UCM, es decir x + nombreCampo).

private String checkInFile() throws IOException, Exception
{
UploadedFile theFile = (UploadedFile) archivo.getValue();
//Establecer conexion con el UCM y enviar los datos seteando el p_tipo = PRUEBA
CheckInSoapClient port = new CheckInSoapClient();
System.out.println("Llamando a : " + port.getEndpoint());
String dDocName=null, dDocTitle=null, dDocType=null, dDocAuthor=null, dSecurityGroup=null, dDocAccount=null;
IdcFile file = new IdcFile();
IdcPropertyList customDocMetaData = new IdcPropertyList(), extraProps= new IdcPropertyList();

// dDocName = "ImagenDocumento";
dDocTitle = "Expediente de "+((String)nombre.getValue());
dDocType = "ADHR";
dDocAuthor = (String)cc.getValue();//"sysadmin";
dSecurityGroup = "PUBLIC";
dDocAccount = null;//"sysadmin";

file.setFileName(theFile.getFilename());
byte[] contenido = getContenido(theFile.getInputStream());
//file.setFileContent(uuencode(contenido, 0, contenido.length ));
file.setFileContent(contenido);

IdcProperty[] propiedades = new IdcProperty[4];
IdcProperty prop = new IdcProperty();
prop.setName("xp_nombre");
prop.setValue((String)nombre.getValue());
propiedades[0] = prop;
prop = new IdcProperty();
prop.setName("xp_tipo");
prop.setValue("PRUEBA");
propiedades[1] = prop;
prop = new IdcProperty();
prop.setName("xp_cedula");
prop.setValue((String)cc.getValue());
propiedades[2] = prop;
prop = new IdcProperty();
prop.setName("xp_email");
prop.setValue((String)email.getValue());
propiedades[3] = prop;

customDocMetaData.setProperty(propiedades);
extraProps = customDocMetaData;
String result = port.checkInUniversal(dDocName, dDocTitle, dDocType, dDocAuthor, dSecurityGroup, dDocAccount, customDocMetaData, file, null, extraProps).getStatusInfo().getStatusMessage();
return result;
}

Usamos estos métodos auxiliaries para manipular el contenido del archive como lo require el UCM .


private byte[] getContenido(InputStream is) throws Exception{

return copyToByteArray(is);
}

/**
* Copy the contents of the given InputStream into a new byte array.
* @param in the stream to copy from
* @return the new byte array that has been copied to
* @throws IOException in case of I/O errors
*/
public static byte[] copyToByteArray(InputStream in) throws IOException {
ByteArrayOutputStream out = new ByteArrayOutputStream();
copy(in, out);
return out.toByteArray();
}

/**
* Copy the contents of the given Reader to the given Writer.
* Closes both when done.
* @param in the Reader to copy from
* @param out the Writer to copy to
* @throws IOException in case of I/O errors
*/
public static void copy(InputStream in, OutputStream out) throws IOException {
try {
byte[] buffer = new byte[BLOCK_SIZE];
int nrOfBytes = -1;
while ((nrOfBytes = in.read(buffer)) != -1) {
out.write(buffer, 0, nrOfBytes);
}
out.flush();
}

finally {
try {
in.close();
}
catch (IOException ex) {
System.out.println("Could not close Reader");
}
try {
out.close();
}
catch (IOException ex) {
System.out.println("Could not close Writer");
}
}
}


Con esto ya tenemos todo listo solo debemos correr nuestra aplicación cliente y obtendremos un escenario básico de interacción con UCM a través de servicios Web. Acá anexo un viewlet con un escenario de uso, enfocado al tema de ventanilla única de una entidad gubernamental.







2 comentarios:

Unknown dijo...

Que tal Pedro, bienvenido a la comunidad blogger the Oracle. Se que desde la experiencia de Consultoria va a poder aportar excelente material.

Sobre el articulo me gustaron mucho los archivos de prueba...jajaja. No mentiras esta muy bueno, lo invito a que visite mi blog http://oracleradio.blogspot.com, voy a hacer un link a este blog y estare siguiendo los articulos.

Saludos

Juan Camilo

Alejandro Bibiano Cortés dijo...

Excelente Material, de gran utilidad!