ERP en la nube: Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina

Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina

(eFactory v4.0.1, también válido para versiones anteriores)

Ventana de Complementos - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Ventana de Complementos de eFactory
Los sistemas de información, como eFactory en sus diferentes presentaciones (ERP/CRM, Contabilidad, Nómina, IPOS...), proveen de muchas características funcionales que son comunes a la mayoría de las empresas. Adicionalmente a estas características comunes es posible desarrollar agregados o Complementos e integrarlos a eFactory como si fuesen parte del sistema original.

En este artículo explicaremos de forma general como se desarrolla un complemento para integrarlo en eFactory. El complemento descrito en el ejemplo puede ser encontrado en la carpeta de complementos de eFactory Administrativo ERP/CRM v4.0.1 o superior.

Preparación del Proyecto en Visual Studio

Los complementos en eFactory pueden ser programados usando cualquier herramienta de desarrollo, desde un simple editor de texto hasta un IDE completo como visual Studio. Para facilitar el proceso de desarrollo recomendamos usar Visual Studio en cualquiera de sus versiones que tenga soporte para programación web con asp.net + webforms. En este artículo utilizaremos Microsoft Visual Studio Express 2013 para el Web, disponible para ser descargado de forma gratuita en el website de Microsoft.

Si es la primera vez que desarrollas un complemento para eFactory deberás crear un proyecto nuevo siguiendo el procedimiento a continuación; en caso de que ya tengas creado un proyecto de desarrollo de complementos puedes abrirlo e ir directamente a la siguiente sección para comenzar a desarrollar.

  • Abre Visual Studio, y en el panel de inicio (o en el menú Archivo) selecciona la opción Nuevo Sitio Web.
Nuevo Proyecto en Visual Studio Express 2013 - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Nuevo Proyecto en Visual Studio Express 2013
  • En la ventana Nuevo Sitio Web selecciona la opción Sitio Web Vacío de ASP.
  • En la parte inferior de la ventana indica la carpeta donde se guardará el proyecto, y presionar Aceptar.
Nuevo Sitio Web ASP.NET - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Nuevo Sitio Web ASP.NET

  • El nuevo proyecto se mostrará en pantalla, pero solo tendrá un archivo creado, el web.config
  • Para programar los complementos de eFactory tendrás que crear una nueva carpeta llamada Bin y colocar allí las Librerías utilizadas por el complemento:
    • AjaxControlToolkit.dll: Esta librería proporciona algunas clases y controles utilizados frecuentemente en eFactory. 
    • cusDatos.dll y cusAplicacion.dll: Estas dos librerías proveen algunas clases y servicios básicos de eFactory.
    • cusAdministrativo.dll, cusContabilidad.dll o cusNomina.dll: Dependiendo del sistema eFactory donde utilizarás el complemento tal vez necesites una o más de estas librerías. 
    • vis1Controles.dll, vis2Controles.dll, vis3Controles.dll y vis2Formularios.dll: Estas librerías proveen los controles integrados de eFactory. 
  • Estas dlls son las mismas que se encuentran en la carpeta Bin donde se encuentra instalado eFactory. 
  • En principio ninguna de estas librerías es necesaria en el proyecto de desarrollo, sin embargo al incluirlas se contará con las clases, funciones, y métodos en intellisense, facilitando enormemente el proceso de desarrollo.   

Nuevo Proyecto Web - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Nuevo Proyecto Web

Nuevo Complemento: Actualizar Precios de Artículos por Cliente 

Actualmente en eFactory es posible establecer Precios por Cliente (ver imagen abajo); esta característica permite definir precios "especiales" de algunos artículos para algunos clientes en particular; por ejemplo, si queremos darle un precio menor al regular a ciertos artículos para los "mejores" clientes de la empresa.

Precios por Cliente - Programación de Complementos para eFactory ERP/CRM
Precios por Cliente - eFactory ERP/CRM

Para establecer los precios por cliente en eFactory, es necesario primero buscar al cliente y luego asignar todos los precios de los artículos a ese cliente, pero el sistema no cuenta con un formulario que permita seleccionar primero el artículo y luego asignar los precios de ese mismo artículo a diferentes clientes. Este será el complemento que desarrollaremos.

Antes de comenzar con la programación debemos decidir donde colocar el complemento. Debido a que la intensión de nuestro complemento de ejemplo es seleccionar primero el artículo, el lugar más apropiado sería justamente en la ficha Avanzados del formulario de Artículos. Para que el complemento esté disponible debemos añadirlo al XML de definición de complementos que se encuentra en la carpeta "eFactory\Administrativo\Xml". Este será el fragmento XML que define nuestro complemento:

  • Código: Es un código simple consecutivo, para diferenciar este complemento del resto. 
  • Nombre: Es el texto que se mostrará en la lista de complementos.
  • Formulario: Este será el identificador que indica a cual formulario estará vinculado el complemento; en este caso al formulario de Artículos. 
  • Tipo: por ahora el único tipo de complemento disponible es Formulario. 
  • Archivo: es el nombre del archivo principal del complemento (el archivo con extensión ASPX). Si se coloca simplemente el nombre del archivo entonces se buscará el complemento en la carpeta de Complementos del sistema administrativo (o contabilidad, o nómina, según el caso). También se puede indicar una ruta absoluta (comenzando por "http://") o relativa (comenzando por "../../").
  • Parámetros: Este elemento puede tener el valor true o false, e indica si el complemento necesita recibir información del formulario de origen. Por ejemplo, el complemento "Recostear Artículos" actúa sobre todos los artículos del sistema (o el artículo seleccionado dentro del complemento), por lo que no requiere parámetros, mientras que el complemento "Recostear Cotización" necesita el número de documento que estaba seleccionado en el formulario de cotizaciones al momento de abrir el complemento. 

Definición del Nuevo Complemento - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Definición del Nuevo Complemento
Nueva Entrada en la Lista de Complementos - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Nueva Entrada en la Lista de Complementos

Programación del Complemento: La Interfaz Gráfica

La forma más rápida de desarrollar un complemento para eFactory es haciendo una copia de otro complemento similar para adaptarlo a la nueva necesidad. En este artículo crearemos el complemento usando una plantilla básica, que puedes encontrar en la sección de Descargas de nuestro sitio web:

  • Lo primero será copiar los dos archivos de la plantilla, llamados frmPlantilla.aspxfrmPlantilla.aspx.vb en la carpeta raíz del proyecto en visual Studio. Recuerda reservar una copia de la plantilla para reutilizarla posteriormente en otros complementos. 
  • Debemos cambiar el nombre del primer archivo a frmAjustarPreciosArticuloPorCliente.aspx, que es el nombre registrado en el XML de complementos. El nombre del segundo archivo se actualizará automáticamente. 
  • En las cabeceras de ambos archivos hay una referencia a la clase "frmPlantilla", cambiamos manualmente esta referencia para que tenga el mismo nombre del complemento.  
  • En el archivo de extensión ASPX debemos cambiar el título para que coincida con el nombre registrado en el XML de complementos, mantener consistencia entre el listado del complemento y el formulario que se abrirá. 
  • Recuerda actualizar la fecha y nombre del desarrollador en la bitácora, al pié del archivo de extensión VB. Esto es para facilitar más adelante el mantenimiento del complemento. 

Veamos ahora el contenido del archivo ASPX:

Complemento - Archivo ASPX (Encabezado) - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Complemento - Archivo ASPX (encabezado)
El encabezado archivo incluye:
  • Referencias a los ensamblados de los controles integrados de eFactory, además de una referencia al AjaxControlToolKit, que es usado en algunos formularios. 
  • Referencias a las hojas de estilo integradas del sistema eFactory Administrativo. Si el complemento es de Nómina o Contabilidad debe ajustarse la ruta y nombre de la referencia correspondiente. 
  • Referencia a la librería jQuery, utilizada en la mayoría de los formularios. Nótese que es una referencia local, y no una referencia a un CDN externo; ésto, para permitir el funcionamiento en una red privada sin acceso a Internet. 
  • Estilos en línea: Estos son los que ajustan el layout de este complemento, y pueden ser modificados libremente si es necesario. 
  • Scripts en línea: Este incluye dos manejadores de eventos para cerrar el formulario con el botón Cancelar o al presionar la tecla ESC; además de la redimensión del formulario a un tamaño inicial apropiado para el contenido. Estos scripts pueden ser modificados según se necesite. 

Complemento - Archivo ASPX (GUI) - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Complemento - Archivo ASPX (GUI)
El layout del archivo contienen algunos elementos básicos para iniciar con la programación del GUI:

  • Un Script Manager y un Update Panel: usados para la actualización del formulario mediante AJAX. Si deseas programar el formulario enteramente con AJAX puedes eliminar ambos controles y encargarte manualmente de la actualización. 
  • Un DIV con el layout general del formulario. Este consiste en una tabla para organizar los controles en pantalla. 
  • Un DIV para la botonera al pue del documento. esta contiene los botónes básicos para Aceptar o Cancelar la acción del formulario. 
  • Un Update Proggress: simplemente para mostrar una animación durante la actualización del formulario. Puedes eliminarlo si no usarás el Update Panel. 
  • Los cuatro controles al pie del formulario son clases integradas para el manejo de ventanas y mensajes modales. estas no serán usadas directamente por el complemento, sino internamente por el sistema. 
El complemento que desarrollaremos utilizará el UpdatePanel y los controles integrados de eFactory; aunque en su lugar se puede programar completamente con controles HTML y Javascript, con servicios web para ejecutar el código de servidor (acceso a base de datos, acceso a los parámetros, etc..). La interfaz del complemento será como sigue:

Interfaz del Complemento - Archivo ASPX (GUI) - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Interfaz del Complemento - Archivo ASPX (GUI) 

  • La etiqueta con el título (barra azul) viene incluida en la plantilla, solo hay que establecer el texto. 
  • Agregaremos una etiqueta nueva con el texto "Artículo:"; para ello usamos un control de tipo vis1Controles:lblNormal.
  • Junto a la etiqueta colocamos un control de tipo vis3Controles:txtCampoBusqueda, llamado también caja de búsqueda. Este tiene una o más cajas de texto y un botón de búsqueda para buscar y seleccionar un registro; en este caso el artículo cuyos precios se van a configurar por cliente.  
  • Lo siguiente será un control de tipo vis3Controles:grdListaRenglones, también llamado grid de renglones. Este, al igual que la caja de búsqueda, es un control compuesto, que incluye botones estándar para agregar y eliminar renglones, botones para seleccionar cada renglón, y una o más columnas de datos de diferentes tipos. 
  • Al pié del formulario tendremos dos botones (de tipo vis1Controles:cmdNormal): Aceptar, para guardar los nuevos precios configurados, y Cancelar, para cerrar el formulario. Ambos botones viene incluidos en la plantilla; el botón Cancelar ya está programado para cerrar el formulario (además, el formulario se cerrará al presionar ESC en el teclado). 

Puedes abrir el archivo frmAjustarPreciosArticuloPorCliente.aspx que se encuentra en la carpeta de complementos de eFactory Administrativo (a partir de eFactory v4.0.1) para ver el detalle de las propiedades de estos controles.

Programación del Complemento: El Código del lado del Servidor

Los complementos de eFactory están programados con ASP.NET + Visual Basic, con el .NET Framework 3.0. 

En el evento LOAD del formulario se realiza la configuración inicial de los controles, y se reciben los parámetros enviados por el formulario de origen (en este caso el formulario de Artículos). Veamos la configuración de la caja de búsqueda:  

Código Complemento: Configuración 1 - Archivo VB - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Código Complemento: Configuración de la Caja de Búsqueda - Archivo VB

La configuración del grid de renglones requiere que se indique las configuración de cada columna de datos que se desea mostrar. Para el complemento de ejemplo también se agregó un botón adicional en la botonera del grid, que se usará para reestablecer al valor original los precios del artículo seleccionado para todos los renglones. También se configuró una columna de tipo botón para hacer lo mismo con cada renglón de forma adicional. 

Código Complemento: Configuración 2 - Archivo VB - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Código Complemento: Configuración del Grid - Archivo VB
Después de especificar las columnas se indica la configuración adicional de las mismas: número de decimales, longitud máxima, y en el caso del código del cliente se configurará también un asistente de búsqueda:

Código Complemento: Configuración 3 - Archivo VB - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Código Complemento: Configuración de las Columnas del Grid - Archivo VB

Luego de esto, se capturan los parámetros del formulario, pero esto solo se hace la primera vez que el formulario se abre: 

Código Complemento: Configuración 4 - Archivo VB - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Código Complemento: Leyendo Parámetros - Archivo VB

Cuando el usuario abre el formulario por primera vez, se mostrarán los precios por cliente configurados para el artículo que tenía seleccionado en el formulario de Artículos al momento de abrir este complemento desde allí. Si el usuario selecciona en el complemento un artículo diferente en la caja de búsqueda, ya sea mediante el botón de búsqueda o escribiendo el código manualmente, se mostrarán los precios configurados para ese artículo. Esto se hace programando el evento mResultadoBusquedaValido de ese control; adicionalmente, el evento mResultadoBusquedaNoValido se usará para borrar el contenido del grid cuando el usuario ingrese un código de artículo no válido; veamos:  

Código Complemento: Eventos de la Caja de Búsqueda - Archivo VB - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Código Complemento: Eventos de la Caja de Búsqueda - Archivo VB

Para ver el detalle del método mCargarPreciosArticulo(), que busca los precios por cliente y los carga en el grid puedes revisar el archivo del complemento en la carpeta correspondiente de eFactory.

Los botones del encabezado del grid y de la columna tipo botón se usarán para reestablecer los precios asignados a todos los clientes o al cliente de esa fila, respectivamente, a los valores actuales del precio del artículo seleccionado:

Código Complemento: Eventos de los Botones del Grid - Archivo VB - Programación de Complementos para eFactory ERP/CRM, Contabilidad y Nómina
Código Complemento: Eventos de los Botones del Grid - Archivo VB 
Cuando el usuario selecciona un cliente en un renglón del grid se cargarán los precios configurados para ese cliente, y si el cliente no tiene precios configurados se cargarán los precios actuales del artículo. Al configurar la columna del código de cliente en el grid, se indicó que ese campo requiere validación en el servidor (es uno de los parámetros booleanos de mRegistrarColumna). Cuando se cambia el código del cliente del renglón se dispara el evento mFilaRequiereActualizar del grid, indicando mediante parámetros del evento cual es el nombre de la columna modificada (cod_cli), el número de renglón, y el nuevo valor. Puedes consultar el código de este evento en el archivo del complemento como se indicó anteriormente.


Cuando el usuario ha terminado de cargar los datos del grid presionará el botón Aceptar, el cual hará lo siguiente:

  • Verificar que haya un artículo seleccionado. 
  • Recorrerá uno a uno los renglones del grid y para cada renglón que tenga un código de cliente seleccionado creará un Precio por Cliente. 
  • La información del grid será incluida en un Script SQL (creado dentro del mismo método) que hará lo siguiente:
    • Crear una tabla temporal con toda la información del grid (los nuevos precios por cliente).
    • Borrar todos los precios por cliente que estén asociados al articulo a modificar.
    • Insertar en la tabla de Precios por Cliente los nuevos precios. 
    • Reenumerar los Precios por Cliente: para cada cliente los precios de los artículos tienen un número de renglón consecutivo, por lo que al eliminar e insertar precios en esta tabla es necesario reestablecer los números que hayan cambiado. 

El Código completo de este botón se puede consultar en el archivo del complemento como se indicó más arriba.

En general, al programar complementos en eFactory se cuenta con varios controles integrados para generar rápidamente la interfaz del mismo, y clases de ayuda como goDatos (para consultar la base de datos) o goServicios (para formatear datos) que facilitan enormemente la tarea de programar un complemento.

Videos Relacionados:






Ing. Roimer García
rjgarcia@efactoryerp.com
Departamento de Desarrollo
Factory Soft
www.efactoryerp.com


Entradas populares de este blog

ERP Cloud: Actualizaciones de las Versiones de eFactory ERP/CRM

Comprobantes de Retenciones Fiscales y Parafiscales