Creación de Librería de Funciones para DataCap

...

En el siguiente artículo se detalla cómo implementar una librería de funciones personalizadas para IBM DataCap, comenzando con la preparación del ambiente, continuando con el desarrollo en Visual Studio y terminando con el despliegue en el sistema donde se ejecuta el Taskmaster. 

Introducción

Al momento de implementar soluciones de digitalización utilizando IBM DataCap, nos encontramos con una cierta cantidad de funciones disponibles, definidas por las librerías del producto, que se adecuan a lo que necesitamos en gran medida. Sin embargo, hay veces que se requiere agregar un comportamiento específico durante el procesamiento de una imagen. Un ejemplo puede ser la invocación a un WebService para validar los datos de la imagen que se lee ante un sistema externo, o quizás algo más simple, como la transformación de uno de los datos. Para estos casos es posible desarrollar una librería con funciones personalizadas para luego ser utilizadas en DataCap. Esto es realizable utilizando un template provisto por IBM y trabajando con Visual Studio.

Paso 1: Preparación del Ambiente 

Para poder desarrollar una librería compatible con DataCap, se requiere lo siguiente:
.- Visual Studio como IDE de desarrollo. En mi caso, utilizo Microsoft Visual C# 2010 Express. Es de uso libre y alcanza para lo que es necesario desarrollar.
.- Template de creación de Custom Actions. Se puede descargar desde el siguiente link. El archivo comprimido que se descarga posee un PDF que explica cómo instalar los templates para que puedan ser utilizados en el Visual C#.

Una vez con el ambiente preparado, crear un nuevo proyecto. En la ventana de Nuevo Proyecto, elegir el tipo "Datacap RRS 8.1 .NET 4.0 Action Library".
Imagen1

 

Automáticamente se abrira el archivo Actions.cs. En este archivo es donde se desarrollarán las funciones, pero primero, desde el explorador de la solución, abrir la carpeta que dice "References". Se podrá notar que hay varias referencias con un signo de exclamación, indicando que no se encuentra la librería. Esto ocurre cuando se desarrolla en un ambiente diferente a donde está instalado el Task Master de DataCap.
imagen2

Para resolver esto, recomiendo obtener de los directorios donde está instalado DataCap (Generalmente están en: <instalacion_DataCap>\dcshared\NET) las dll que hacen falta y copiarlas en el equipo donde se está desarrollando. Luego haciendo boton derecho sobre la carpeta "References" > "Add Reference", se abrirá una ventana, clickear el tab de "Browse" y seleccionar todas las dll en donde se hayan copiado.
Si se cuenta con una instalación de DataCap en el ambiente local, se puede agregar el path: "<instalacion_DataCap>\dcshared\NET" a las referencias.

El siguiente problema que puede aparecer al referenciar las librerías es:
Imagen3

Este Warning se da cuando el entorno de desarrollo es x64 y las librerías referenciadas son x86. En ese caso se puede seguir las instrucciones indicadas en el problema: Hacer click derecho en la solución > Configuration Manager. En la ventana que se abre hacer click en el combo de la columna "Platform" (El que dice Any CPU), Elegir la opción "New..." y por ultimo en New Platform elegir x86.
imagen4

  

Paso 2: Desarrollo de la Librería

Archivo .rrx 

Con el proyecto creado y con las librerías importadas, solo resta trabajar en la solución. Lo primero a tener en cuenta es el archivo .rrx ubicado en la carpeta "Resources". Debería llamarse <NombreDelProyecto>.rrx. Este archivo es donde se definirán las funciones que tendrá la librería y será el que DataCap leerá para mostrar las funciones disponibles desde DataCap Studio.

Para este ejemplo, vamos a definir un metodo que recibirá el nombre de un campo a leer, obtendrá el valor de lo leido en el campo, lo procesará y almacenará el valor en otro campo, indicado también como parámetro. Entonces, el rrx debería verse así: 

 

<rrx>  
	<!-- === .NET === -->  
	<!-- format: <net ref="dotNETnamespace"> -->
	<net ref="MGCustomLib.Actions">
		<method name="calculateTaxes" qi="calcula los impuestos del precio">
		<!-- Parametros -->
			<p name="fieldPrice" type="string" qi="Nombre del campo precio">
			<p name="fieldTax" type="string" qi="Nombre del campo impuesto">     
		</method>
	</net>
</rrx>

La propiedad qi es opcional y sirve a modo informativo en DataCap Studio para entender qué hace y qué requiere el método.

Actions.cs

Ya con el método definido en el rrx, se puede trabajar con la implementación del método en Actions.cs. Lo principal que hay que saber es que las funciones definidas para DataCap siempre deben tener como tipo de retorno bool. El siguiente fragmento de código muestra la implementación del método "calculateTaxes": 

public bool calculateTaxes(string fieldPrice, string fieldTax){
	try{
		string price = CurrentDCO.Parent().FindChild(fieldPrice).Text;
		double tax = (Convert.ToDouble(price) * 21) / 100;
		CurrentDCO.Parent().FindChild(fieldTax).Text = tax.toString();
		return true;
	}catch(Exception e){
		WriteLog("Exception ocurred: " + e.Message);
		return false;
	}
}

Con CurrentDCO.Parent().FindChild(<nombreCampo>).Text obtenemos el valor de algún campo del documento digitalizado por DataCap y, como se ve, también se utiliza para asignarle un valor un campo. Si todo funcionó correctamente, se devuelve true. Si hubo una excepción, se retorna false. Si se precisa que el error se visualice en pantalla, se puede asignar el texto del error a otro campo (Por ejemplo, un campo destinado a mostrar mensajes de la ejecución).

Paso 3: Despliegue de la Librería 

Terminado el desarrollo de la librería, queda hacer un build de la misma y luego desplegarla en el equipo donde se ejecuta el Taskmaster. Para empezar, hacer click derecho en el proyecto y elegir la opción properties. En la ventana nueva que se abre, elegir la opción de la izquierda "Build", luego buscar la sección "Output" y modificar el output path al directorio donde se quiera exportar el build.

imagen5

Segundo, Hacer click derecho en el archivo rrx y elegir la opción propiedades. Ubicar la opción "Copy to Output Directory" y asignarle el valor "Copy Always".
imagen6

Hacer build de la solución, navegar al directorio elegido como Output y copiar el archivo <proyecto>.dll y el rrx generado en la carpeta Resources.
Cerrar el Data Cap Studio, luego ingresar a <DirectorioInstalacionDataCap>/dcshared/NET y pegar <proyecto>.dll en dicho directorio. Luego, pegar <proyecto>.rrx en <DirectorioInstalacionDataCap>/RRS. Abrir un cmd y completar los siguientes pasos para registrar la dll:
1.- Navegar con cmd hasta C:\Windows\Microsoft.NET\Framework\<versión 4 más reciente>
2.- Ejecutar el siguiente comando: RegAsm.exe
<DirectorioInstalacionDataCap>/dcshared/NET/MGCustomLib.dll /codebase

Hecho esto, iniciar nuevamente el DataCap Studio. 

Invocación de la Función en DataCap

Una vez iniciado el servidor de DataCap, volver a abrir el DataCap Studio y abrir la aplicación que se está trabajando. Lo primero que hay que verificar es si DataCap lee correctamente la librería. Esto se puede comprobar verificando la solapa de "Actions Library". Allí, debe aparecer un nuevo item llamado como se nombró al proyecto y, si se expande el item, se podrá ver la funcion "calculateTaxes". Basta con agregar la invocación a la función en el ruleset como cualquier otra función para que DataCap la ejecute cuando se procese la imagen.

Nota: En caso que no se pueda ver la librería en DataCap Studio, probar pegando la librería en <DirectorioInstalacionDataCap>/RRS.


Modificado por última vez en Jueves, 16 Julio 2015 13:06

Acerca del autor

Federico Luppi

Federico cuenta con más de 4 años de experiencia en el desarrollo de aplicaciones Web bajo plataformas Java EE y 3 años de experiencia en el liderazgo de equipos de desarrollo. Actualmente se desempeña como Líder de Proyecto en el área de operaciones de MicroGestion Software.