Script de sincronización con BOLDXML2

Un script de sincronización también se denomina “sincro” y lo que hace es transportar datos entre un sistema y otro, efectuando alguna transformación por en medio. Por ejemplo puede utilizarse para cargar los datos de empleadas o empleados, contratos, ausencias, necesidades, horarios, etc…

Existen scripts “estándar” que implementan tareas de sincronización entre algunos sistemas conocidos como a3EQUIPO o cierto formato de relojes. Si el sistema es diferente, habrá que implementar una serie de scripts para personalizar la integración entre BOLD y los otros sistemas.

Prerrequisitos

Es necesario tener preinstalado y configurado el módulo BOLDXML2.

Los scripts se implementan en javascript y se utiliza nodejs para su ejecución.

Formato del script

El contenido típico de un script sería similar a éste (en este caso implementa la carga de un fichero maestro de empleados proveniente de un sistema externo y lo introduce en BOLD):

var assert = require("assert");
var fs = require("fs");
var path = require("path");
var util = require("util");
var logger = require("../../../../../../BOLDXML2/scripts/core/util/logger.js");
var gpsdates = require("../../../../../../BOLDXML2/scripts/core/util/gps_dates_commons.js");
var BOLDXML_tools = require("../../../../../../BOLDXML2/scripts/BOLDXML_tools.js");
var SyncWait = require("../../../../../../BOLDXML2/scripts/core/util/SyncWait.js");

var API_Custom = require("./API_Custom.js");
var api = new API_Custom();


//--------------------------------------------------------------------------------
// logger.setLevel(logger.TRACE); // uncomment to TRACE HTTP messages
logger.setLevel(logger.DEBUG); // uncomment to TRACE HTTP messages
//--------------------------------------------------------------------------------


exports.sincro = function(taskController) {
  // Returns a "sincroObj"
  return {
    name: "Empleados",
    description: "",
    
    beforeRunTask : function(sincroObj) {
      sincroObj.description = sincroObj.BOLDXML.param(0);
      return true;
    },

    initFunc : function(sincroObj) {
      if (sincroObj.BOLDXML.paramCount() < 1) {
        throw new Error("Debe indicar el tipo de cambio que quiere procesar: CATEGORIA, CONVENIO, POSICION, UNIDAD_ORGANIZATIVA, REDUCCIONES_DE_JORNADA, CENTRO_DE_COSTE o TODOS");
      }
    },

    extract: {
      xmlFile: "Empleados.json",
      extractFunction: function(sincroObj) {    
        var idPersona, FechaInicio, FechaFin;
        var FechaInicio = "2017-01-01T00:00:00";
        var FechaFin = "2019-01-01T00:00:00";
        var sessionID = api.login();
        var data = api.getEmpleados(FechaInicio, FechaFin);
        api.logout();
        return data;
      }
    },
    transform: {
      queryFunction: function(sincroObj, json_input) {
        var list = BOLDXML_tools.toArray(json_input); // cuando solo retorna 1 elemento, lo normaliza en un array
        logger.debug(JSON.stringify(list.slice(0,2), null, 2));
        return { 
          list: list,
          ConvFecha: ConvFecha
        };
      },
      transformFile: "Empleados.xml"
    },
    process: {
      importXML: "Worker"
    },
  };
};


/**
 * @param f example: 4000-01-01T00:00:00.000Z
 */
function ConvFecha(f) {  
  if (f.indexOf("4000") !== -1)
    return gpsdates.maxDate2ISO;
  else
    return f.substring(0, 10); // trim time zone
}

Secciones del script

extract: sección que configura la extracción del sistema nativo (por ejemplo)

transform: sección que configura la transformación de las datos de entrada en los de salida. En las primeras versiones se utilizaba el lenguaje XSLT, pero luego ha sido sustituido por un scripting de plantillas mucho más flexible y simple. Ver el artículo Documento de definición de una transformación XML.

process: sección para configurar el destino de los datos transformados. Normalmente se indica la clase de objetos resultante y se activa su importación en el servidor de bold. En el caso anterior el resultado son objetos de tipo Worker (empleados/as)

initFunc (función opcional): se ejecuta para efectuar inicializaciones globales útiles para el resto de etapas o también para comprobar los parámetros adicionales, como en este ejemplo.

beforeRunTask (función opcional): si se especifica esta función, se ejecuta antes de la ejecución del resto de etapas del script. Si la función está implementada, un valor de retorno false indicará que se debe cancelar la ejecución de la tarea y esta ejecución no dejará ninguna traza en la pantalla de resumen de las interfaces. En el caso anterior se utiliza para personalizar la etiqueta de la descripción de la tarea, resulta útil cuando el script se le pasan parámetros que cambian el funcionamiento de la tareas y de esta forma se puede distinguir en la pantalla de resumen cada una de las diferentes modalidades del mismo script.

Otros detalles del script

SyncWait: como en nodejs casi todas las llamadas son asíncronas, esta clase nos permite convertir un código asíncrono en síncrono lo cual facilita mucho la implementación de las interfaces puesto que son siempre muy secuenciales.

API_Custom: en esta clase implementaremos los accesos al sistema externo (mediante webservices, u otros mecanismos…)

sincroObj: este objeto que reciben como primer parámetro muchas funciones proporciona acceso a una serie de objetos de contexto y métodos muy útiles. Son los siguientes:

• sincroObj.BOLDXML: este objeto propciona una API para acceder a toda la información útil relacionada con las tareas de sincro en ejecución.
  Ver Contexto de una sincro: objeto BOLDXML
• TBD

Depuración

• La forma más rápida de depurar los scripts consiste casi siempre en añadir una traza dentro del código.
• Si el script ni siquiera arranca por errores sintácticos lo mejor es pasarlo por un validador de javascript como éste: http://esprima.org/demo/validate.html
• Si lo que está mal sintácticamente es un archivo JSON de configuración o de entrada de datos usar este validador JSON como éste: https://jsonlint.com/

Sin embargo, también es posible preparar el entorno para debugar scripts de nodejs…el último usado fue node-inspector (hay un readme en la carpeta de BOLDXML2/docs)…TBD

Configuración del entorno de trabajo del script

La primera tarea que debe realizar un script es leer las variables de entorno de trabajo. Para ello ejecuta el archivo BOLDXMLConfig.bat preparado para cada instalación (utilizar la herramienta de configuración boldxmlcfg.exe).

Variables de entorno de trabajo para scripts de servidor

Una forma de inicializar las variables de entorno std. para que estén disponibles desde un script de servidor (por ejemplo para pasarlas a una tarea enlazada con algún evento de servidor) es implementar dicho script como en el siguiente ejemplo:

set START_DIR=%CD%
cd %~dp0
set SCRIPT_DIR=%CD%
cd ..\sincro
echo Ejecutando import IT....
call "90 Sincro_IncidenciasYAbsentismos.bat" 
echo Comprobando resultados...analizando el fichero %BOLDXML_LOG%...
cd %START_DIR%
echo "%BOLD_CSCRIPT%"
echo "%SCRIPT_DIR%\Sincro_CheckIT.wsf"
call "%BOLD_CSCRIPT%" "%SCRIPT_DIR%\Sincro_CheckIT.wsf"
echo Final...

El ejemplo anterior implementa un script de servidor (por ejemplo: que se ejecuta escogiendo una opción en menú) que lo que hace es lanzar primero una tarea de sincro global 90 Sincro_IncidenciasYAbsentismos.bat (que inicializará las variables de entorno) y posteriormente ejecuta el script Sincro_CheckIT.wsf. Desde dentro del código de Sincro_CheckIT se podrá acceder a las variables de entorno como la ubicación de la carpeta de ficheros BOLDXML de trabajo (variable de entorno DATA_BOLDXML).

Funciones de gestión de tareas del log

Gestionan la apertura y cierre de las tareas que aparecen en la página web del log de seguimiento del sistema BOLDXML.

Importante! las etiquetas de tareas y subtareas no pueden contener caracteres especiales, aunque sí espacios.

TASK_New

TASK_NewSubtask(task_name, “Aplicando transformacion 1”)

TASK_SaveSubtask

TASK_SaveResults

TASK_Save

Funciones de log

Log_Info Envía mensajes tipo Info a la salida standard (que también son capturados por el log de seguimiento (ver BOLDXML)

Log_Debug Envía mensajes tipo Debug a la salida standard (que también son capturados por el log de seguimiento (ver BOLDXML)

Importante! Las funciones anteriores sólo puede usarse dentro del contexto de una tarea o subtarea. No puede usarse después de TASK_Save o TASK_SaveSubtask ya que la salida estándar ya habrá sido cerrada.

Snippets de código útiles

Visualización correcta de caracteres especiales en la consola

Para visualizar correctamente los caracteres especiales como acentos o diéresis en la ventana de cmd.exe es necesario añadir al inicio del script la siguiente instrucción:

chcp 65001

Acceso a la carpeta NativeXML

Obtener el directorio (sin la \) donde se dejan los ficheros nativos del sistema origen o propietario):

const nativeXMLDir = sincroObj.BOLDXML.getNativeML()

Ejemplos de scripts

• Ejemplo 1: Script BOLDXML implementado con javascript
• Ejemplo 2: Script BOLDXML implementado con batch file (.bat)