Manual de usuario para la parametrización de la integración Openbravo-Sugar

Transcripción

1 Manual de usuario para la parametrización de la integración Openbravo-Sugar Fichero: Manual usuario - Integración Openbravo- Sugar - Spanish Versión: 1.0 Sevilla, 3 de febrero de 2010

2 Histórico de cambios Responsable Fecha Cambios Alicia Palacios Serrano 03/02/10 Creación Alicia Palacios Serrano 13/09/10 Actualización Alicia Palacios Serrano 30/09/10 Actualización Miguel Márquez Romero 08/11/10 Cambio de nombre del módulo 2

3 Índice de contenido 1.Introducción Creación de una nueva parametrización Creación de puntos de sincronización Datos del punto de sincronización Registros de sincronización LOG de errores Registros pendientes Contraseñas para la sincronización Proceso Background Alertas...17 Página 3/17

4 1.Introducción El presente documento tiene como objetivo servir de guía a la hora de crear una nueva parametrización para la integración de Openbravo y una aplicación externa. Los pasos que se detallan a continuación tomarán como aplicación externa SugarCRM. Las versiones necesarias para poder instalar el módulo de sincronización son: Openbravo 2.50 MP16 o superior. SugarCRM 5.2.0k o superior Página 4/17

5 2.Creación de una nueva parametrización El primer paso es crear una nueva Parametrización de sincronización. Para ello desde Aplicación>Parametrización de sincronización pulsamos Nuevo. Se nos muestra el siguiente formulario: Significado de los campos: Orden de ejecución: con este campo le indicamos al proceso background en qué orden deben ejecutarse las distintas sincronizaciones, en caso de que exista más de una. Por defecto Openbravo, le asigna un valor autocalculado. Nombre: nombre con el que identificaremos la sincronización. Activo: si no marcamos este campo, esta sincronización no se ejecutará. Aplicación externa: aplicación con la que vamos a sincronizar Openbravo, en nuestro caso será SugarCRM. Versión: es la versión de la aplicación externa que vamos a utilizar. Endpoint: ruta de los servicios web. Normalmente tendrá el siguiente formato Versión del Web Service: versión de los servicios web de SugarCRM. Usuario conexión: nombre de usuario de SugarCRM que utilizarán los servicios web para obtener e insertar información. Este usuario debe tener permisos para acceder a toda la información que se está consultando o insertando. En esta ventana se muestra en solo lectura. Será en la ventana Contraseñas sincronización donde se podrán editar los campos Usuario y Password. Lanzar sincronización: mediante este botón podemos sincronizar manualmente todos los puntos contenidos en esa sincronización. Por ejemplo si lo ejecutamos en la sincronización de terceros, se sincronizarán los contactos y las cuentas. Este botón no debe usarse mientras el proceso de sincronización está programado para ejecutarse, ya que podría provocar duplicidad de datos en alguno de los dos sistemas. Página 5/17

6 3.Creación de puntos de sincronización Una vez creada la sincronización, tal y como se ha explicado en el punto anterior, el siguiente paso es crear los distintos puntos de sincronización. Cada punto de sincronización se corresponderá con una tabla a sincronizar. Para crear un punto nuevo, pulsamos Nuevo desde la pestaña 'Puntos de sincronización'. Se nos mostrará un formulario como el siguiente: Significado de los campos: Orden de ejecución: este campo nos servirá para indicarle al proceso background en qué orden queremos que se ejecuten los distintos puntos de sincronización. Es recomendable que primero se ejecuten los puntos correspondientes a las tablas maestras y después los puntos que hagan uso de dichas tablas. Activo: si no marcamos este campo, este punto de sincronización no se ejecutará. Nombre: nombre para identificar el punto de sincronización. Fecha última ejecución: este campo es de solo lectura y se actualizará después de cada ejecución del proceso de sincronización, para indicar cuándo fue la última vez que se sincronizó la tabla. Última ejecución: al igual que el campo anterior se actualizará con la hora de la Página 6/17

7 última ejecución del proceso de sincronización. Usuario última ejecución: campo de solo lectura que nos indicará qué usuario ha realizado la sincronización. Deberá ser el usuario Openbravo el que realice el proceso de sincronización. Última ejecución Ap.externa->Openbravo: En este campo se almacenará la hora de modificación del último registro de la aplicación externa que se sincronizó desde la Ap.externa a Openbravo. De esta forma, la próxima vez que se ejecute la sincronización se buscarán los registros que ese hayan modificado después de esta fecha/hora. Última ejecución Openbravo->Ap.externa: En este campo se almacenará la hora de actualización del último registro de Openbravo que se sincronizó de Openbravo a la Aplicación externa. De esta forma, la próxima vez que se ejecute la sincronización se buscarán los registros que ese hayan modificado después de esta fecha/hora. Nota importante: para sincronizaciones que se realizan en los dos sentidos hay que tener en cuenta que para evitar que los registros que se acaban de sincronizar en un sentido lo hagan también en sentido contrario por la fecha de actualización, sin ser necesario, existe la restricción de que únicamente se sincronizarán: En Openbravo: registros que hayan sido modificados por un usuario que no sea el usuario Openbravo que es el que realiza el proceso de sincronización, excepto cuando el registro aún no exista en la aplicación externa. Es decir, se puede crear un registro con el usuario Openbravo y se sincronizará, pero no se puede actualizar con dicho usuario. Esto es útil en migraciones de datos, en las cuales el usuario asignado puede ser Openbravo. En la aplicación externa (SugarCRM) : registros que hayan sido modificados por un usuario que no sea el usuario admin, por el mismo motivo que en el caso anterior. La diferencia es que en este caso, tampoco se sincronizarán registros creados por el usuario admin, ya que en la aplicación externa no existe el registro de sincronización Última ejecución borrado: Fecha y hora en la cual se ejecutó por última vez un borrado en la aplicación externa. Coincide con la fecha y hora de borrado del último registro eliminado. Hay que tener en cuenta que en MySQL no se pueden almacenar milisegundos en los campos de tipo datetime, por tanto se puede dar el caso en el que varios usuarios borren o actualicen registros al mismo tiempo. Aquí habrá que tener en cuenta que en la siguiente sincronización obtendremos los registros con fecha mayor o igual que la última fecha de borrado, es decir, habrá que adaptar el valor del campo Nº máximo de registros al volumen de registros borrados o actualizados que tengan la misma fecha de actualización (esto es importante para actualizaciones o borrados masivos) para asegurarnos que obtenemos todos los registros. Sentido: nos indica en qué sentido se realizará la sincronización. Hay 3 posibles valores: Openbravo Ap. Externa : los datos se sincronizarán desde Openbravo hacia la Aplicación externa. Ap. Externa Openbravo : los datos se sincronizarán desde la Aplicación externa hacia Openbravo. Openbravo Ap. Externa: si seleccionamos esta opción se nos mostrará otro desplegable en cuál debemos indicar cuál de las dos aplicaciones tiene prioridad, es decir, en qué sentido se sincronizará primero. Página 7/17

8 Categoría del log: este desplegable tiene los siguiente valores: Escribir en tabla de LOG: los errores se escriben en la tabla de LOG. Escribir en fichero y tabla de LOG: los errores se escriben en la tabla de LOG y en el fichero de log de Openbravo situado en carpeta logs de Tomcat (normalmente denominado openbravo.log ). Tabla de Openbravo: indicamos qué tabla de Openbravo se va a sincronizar. Cond. WHERE Openbravo: este campo se rellenará en caso de que solo queramos sincronizar determinados registros de la tabla que se ha seleccionado en 'Tabla de Openbravo'. Por ejemplo si solo deseamos sincronizar los terceros que sean Alumnos escribiremos: ob.acdalumno=true Nótese que hay que utilizar el alias ob para referirnos a la tabla que estamos sincronizando. En cuanto al nombre de los campos, no se utilizará el nombre del campo en base de datos sino el nombre que toma dicho campo en la clase java (valor de la constante PROPERTY_nombre_campo). La sentencia que se escriba en este campo será la que utilice el proceso de sincronización como parte de la cláusula where, por lo que es importante que la sintaxis sea correcta. Para facilitar esta tarea, es recomendable instalar el módulo HQL Query Tool en el cual podemos crear y ejecutar sentencias HQL y ver el resultado. También podemos visualizar todas las propiedades de una determinada clase. Cond. orden Openbravo: este campo se rellenará en caso de que queramos obtener los resultados ordenados por algún campo en concreto de la tabla de Openbravo que estamos sincronizando. Tabla de aplic. Externa: en este campo indicaremos qué tabla de la aplicación externa queremos sincronizar. Nombre módulo apl. Externa: en el caso de SugarCRM nombre del módulo asociado a la tabla que hemos indicado en Tabla de aplic. Externa. A veces puede coincidir con el nombre de la tabla, pero hay que escribirlo respetando mayúsculas, por ejemplo, el módulo de la tabla contacts es Contacts Cond. WHERE aplic. Externa: este campo se rellenará en caso de que solo queramos sincronizar determinados registros de la tabla que se ha seleccionado en 'Tabla de aplic. Externa'. Por ejemplo si solo deseamos sincronizar los terceros que sean Alumnos escribiremos: contacts.alumno=1. En este caso debemos utilizar como alias el nombre de la tabla con la que estamos trabajando, y el nombre del campo de la base de datos. Cond. orden aplic. Externa : este campo se rellenará e caso de que queramos obtener los resultados ordenados por algún campo en concreto de la tabla de la aplicación externa que estamos sincronizando. Nº máximo de registros: Nº máximo de registros que se pueden obtener en la llamada a los servicios web de la aplicación externa Lanzar sincronización: mediante este botón podemos sincronizar manualmente el punto de sincronización en el cual nos encontramos. Este botón no debe usarse mientras el proceso de sincronización está programado para ejecutarse, ya que podría provocar duplicidad de datos en alguno de los dos sistemas. Página 8/17

9 3.1. Datos del punto de sincronización Desde esta ventana vamos a configurar cada campo que queramos sincronizar de Openbravo y el campo con el que se corresponde en la aplicación externa y viceversa. El campo debe pertenecer a la tabla indicada en el punto de sincronización en Tabla de aplic. Externa. Si pulsamos el botón Nuevo, se nos mostrará un formulario como el de la imagen: Significado de los campos: Nombre del dato: nombre del campo que queremos sincronizar. No es necesario que se corresponda con el nombre de la base de datos. Descripción: descripción del campo que vamos a sincronizar. Origen dato Openbravo: mediante esta lista desplegable indicamos de dónde procede la información que vamos a sincronizar de Openbravo. Las distintas opciones son : Columna: si la información que vamos a sincronizar es una columna de Openbravo. Sentencia SQL: si la información se obtiene mediante una consulta a la base de datos de Openbravo. Esta sincronización solo se ejecutará cuando el sentido de la misma sea Openbravo->Ap. Externa, y se ignorará si la sincronización es en sentido contrario, ya que la columna de la aplicación externa no tendría correspondencia con ninguna columna en Openbravo. Para obtener un determinado campo del registro que estamos sincronizando utilizaremos la en la clausula where y en el proceso será sustituida por el id del registro que se está sincronizando. Ejemplo: estamos sincronizando la tabla c_bpartner y en un campo de la aplicación externa queremos guardar el nombre del tercero y el dni concatenados. Entonces para obtenerlos en Openbravo crearíamos una SQL así: Página 9/17

10 SELECT (C_BPARTNER.NAME ' ' C_BPARTNER.TAXID) FROM C_BPARTNER WHERE C_BPARTNER.C_BPARTNER_ID= Valor fijo: si seleccionamos esta opción se nos mostrará un campo con el nombre Valor fijo Openbravo en el cual indicaremos qué valor se va a asignar siempre al campo correspondiente en la aplicación externa. Tipo dato Openbravo: en esta lista desplegable indicaremos el tipo de la información de Openbravo que queremos sincronizar. Hay varias opciones: Boolean Decimal Fecha Hora Numérico Sin definir Texto Columna Openbravo: en esta lista desplegable se nos muestran todos los campos de la tabla de Openbravo que hayamos seleccionado en el punto de sincronización. Este campo se mostrará en caso de haber seleccionado la opción Columna en el campo Origen dato Openbravo. Origen dato aplic. Externa: mediante esta lista desplegable indicamos de dónde procede la información que vamos a sincronizar de la aplicación externa. Las distintas opciones son : Columna: si la información que vamos a sincronizar es una columna de la aplicación externa. Sin correspondencia en Ap. externa: seleccionaremos esta opción cuando el campo de Openbravo que queremos sincronizar no tiene ningún campo que se corresponda en la aplicación externa, sino que dicho valor lo podemos obtener de tablas propias de Openbravo. Al seleccionar este desaparecen los campos Columna de aplic. externa Es Id. aplic. externa Es clave ajena de ap. externa Y se nos muestran otros tres: Clave ajena en Openbravo: marcamos este campo para indicar que el valor que queremos obtener es clave ajena de otra tabla de Openbravo. Tabla de la clave ajena: indicamos la tabla de la cual es clave ajena el campo. Valor por defecto: en caso de que no se encuentre el valor que tiene el campo Columna Openbravo en la tabla Tabla de la clave ajena se asignará el valor que hayamos designado como valor por defecto en este campo. Valor fijo: si seleccionamos esta opción se nos mostrará un campo con el nombre Valor fijo Ap. externa en el cual indicaremos qué valor se va a asignar siempre al campo correspondiente en Openbravo. Tipo dato aplic. Externa: en esta lista desplegable indicaremos el tipo de la Página 10/17

11 información de la aplicación externa que queremos sincronizar. Hay varias opciones: Boolean Decimal Fecha Hora Numérico Sin definir Texto Nota: es muy importante indicar correctamente de qué tipo es cada campo que queremos sincronizar para evitar errores de formato en el proceso de inserción o modificación de los datos. Columna de aplic. Externa:en este campo indicamos el nombre del campo de la aplicación externa que queremos sincronizar. Es Id. aplic. Externa: si se marca este campo, estamos indicando que los campos que estamos sincronizando se corresponden con la clave principal de la tabla de la aplicación externa. Es clave ajena de ap. externa: si se marca esta opción, estamos indicando que el campo que estamos sincronizando en la aplicación externa es clave ajena de otra tabla. Cuando marcamos el check se nos muestran dos campos: Módulo de ap. externa: aquí indicaremos de qué módulo es clave ajena el campo en la aplicación externa. Para el caso de SugarCRM hay que tener especial cuidado con las mayúsculas y minúsculas, y tener en cuenta que algunas veces el nombre de la tabla difiere del nombre del módulo. Por ejemplo si ponemos como nombre del módulo contacts el servicio web no reconocería este nombre como nombre de un módulo, pero sin ponemos Contacts si lo haría. En este caso no hay que indicar con qué columna de la aplicación externa se relaciona la columna de Openbravo, ya que al indicar que es clave ajena y decirle el módulo de la clave ajena el servicio web relacionará los dos registros. Indicar campo relacionado: este campo únicamente se marcará en el caso de que el campo que estamos sincronizando en la aplicación externa sea una clave ajena de otra tabla pero no haya definida una relación entre las dos tablas. Por ejemplo, en Contactos existe el campo País que hace referencia a la tabla donde se encuentran los países, sin embargo no existe una relación creada entre estos dos módulos, por lo tanto hay que indicar el campo con el cual se relaciona por ejemplo: id_paises. Al marcar este campo se nos muestra de nuevo Columna de aplic. Externa para indicar el campo relacionado. Módulo de ap. externa: en este campo indicamos el nombre del módulo de la aplicación externa del cual es clave ajena el campo que estamos sincronizando. Se debe rellenar tanto en el caso de seleccionar Módulo de ap. externa como Indicar campo relacionado. Página 11/17

12 3.2. Registros de sincronización En esta ventana se van a ir almacenando para cada punto de sincronización parejas de identificadores identificador Openbravo identificador Ap. externa las cuales representan las relaciones entre los registros de Openbravo y los registros de la aplicación externa. Esta ventana es de solo lectura y se irá actualizando con los nuevos registros que vayamos sincronizando. Veamos el significado de cada campo: Activo: este campo nos indica si la relación existe o si los registros han sido eliminados de ambos sistemas. Cada vez que un registro que haya sido sincronizado anteriormente se elimina, el campo Activo se actualiza a 'N' quedando desmarcado el check. Punto de sincronización: nos indica el punto de sincronización al cual pertenecen los registros sincronizados. Tabla de Openbravo: tabla de Openbravo que se ha sincronizado. Identificador Openbravo: identificador del registro que se ha sincronizado. Tabla Ap. externa: tabla de la ap. externa que se ha sincronizado. Identificador aplic. Externa: registro de la aplic. Externa que se ha sincronizado y con el cual se corresponde el registro Identificador Openbravo. Última sincronización: nos indica fecha y hora de la última vez que se sincronizaron ambos registros (la hora es visible en la vista grid) LOG de errores En esta ventana también de solo lectura, se irán registrando los errores que se vayan produciendo durante el proceso de sincronización. Cada registro de la ventana recogerá los errores ocurridos en un punto de sincronización a lo largo del día. La ventana muestra los siguientes campos: Punto de sincronización: punto al cual pertenecen los errores que se muestran. Fecha/hora: fecha en la cual se han producido los errores. La hora corresponde con la última hora en laque se produjo un error el día en cuestión. Cada registro del LOG de errores se corresponde con un día. Mensaje de error: en este campo se irán concatenando los errores que se vayan produciendo en el punto de sincronización a lo largo del día. Página 12/17

13 Por cada entrada de LOG de errores se generará una Alerta en Openbravo, indicando en qué punto se ha producido el error Registros pendientes En esta ventana se almacenarán los registros que por algún motivo no se han podido sincronizar desde la aplicación externa a Openbravo para tenerlos en cuenta en sucesivas sincronizaciones. La ventana muestra los siguientes campos: Punto de sincronización: es el punto al cual pertenece el registro que ha producido el error. Identificador: es el identificador del registro en la aplicación externa. Inserción o actualización: nos indica si el error se produjo al intentar insertar o actualizar el registro desde la aplicación externa a Openbravo. Borrado: nos indica si el error se produjo al intentar eleiminar el registro de Openbravo. Una vez el registro se haya sincronizado correctamente será eliminado de esta tabla. Página 13/17

14 4. Contraseñas para la sincronización En esta ventana se establecerán el usuario y contraseña de la aplicación externa que nos permitirá conectarnos a través de los servicios web para obtener la información necesaria. El usuario debe tener permisos de administrador en la aplicación externa para poder acceder a todos los registros que queramos sincronizar. Página 14/17

15 5. Proceso Background Al instalar el módulo de Sincronización, tanto el proceso background encargado de ejecutar la sincronización como la alerta que se genera en caso de error, se crearán al cargar el módulo para la organización * desde: Configuración General Organización Gestión del módulo de Empresa El proceso background se creará desprogramado. Para configurar la frecuencia e intervalo con el cual queremos que se ejecute, vamos a la ventana Configuración General Planificador de procesos Procesamiento de Peticiones y buscamos el proceso llamado Proceso Sincroniz. (Background) como se ve en la siguiente imagen: Una vez se haya indicado la frecuencia e intervalo deseados se programa el proceso Página 15/17

16 pulsando el botón Reprogramar Proceso. A partir de entonces la ejecución periódica del proceso aparecerá en el monitor de procesos junto con el resto de procesos que se ejecutan en la aplicación. Para más información, ver la ventana Configuración General Planificador de procesos Monitor de Procesos. Página 16/17

17 6. Alertas En el proceso de carga de módulo que se ha explicado en el punto anterior, se creará una alerta denominada SYNCHRONIZATION ERROR, a la que se le tendrán que definir los receptores y proceder a activarla: La alerta se traduce a es_es como Errores de sincronización y será lanzada una vez por cada punto de sincronización en el que se de el error. Al pulsar sobre el Registro se mostrará la solapa LOG de errores en la cual se podrá ver el mensaje completo del error. Página 17/17