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)

Los comandos se ejecutan normalmente desde un shell o ventana de comandos cmd del sistema operativo. Para acceder a los comandos BOLDXML debe ejecutar las siguientes acciones:

• Situarse en una carpeta cliente “Integration” ( ej.: C:\Program Files (x86)\Global Planning Solutions\Custom_Files\Integration\configuration\production )
• Abrir un intérprete de comandos (ej.: cmd.exe) allí
• Ejecutar el comando: BOLDXMLConfig.bat
• A continuación ya podremos escribir los comandos de integración detallados más abajo.

Generación del archivo de inicialización BOLDXMLConfig.bat

Si este archivo no existiera, debe generarse automáticamente con el siguiente procedimiento:

1. Abrir un cmd.exe o un powershell en la carpeta BOLDXML2.
2. Ejecutar el comando (cambiar por la carpeta que corresponda en cada caso):

.\generate_BOLDXMLConfig.bat "C:\Program Files (x86)\Global Planning Solutions\Custom_Files\Integration\configuration\production\boldserver"

El comando BOLDXMLConfig.bat debe estar ahora disponible en la carpeta ..\production

Comandos de sincro

sincro: para ejecutar tareas relacionadas con la sincronización e integración de sistemas. Ver Comando sincro para más información.

sincroa3: para ejecutar tareas relacionadas con la integración específica con la solución a3EQUIPO. Ver Interface con a3EQUIPO para más información.

sincroics: para ejecutar tareas relacionadas con la integración con el SAP ICS. Ver Comando sincroics para más información.

Para ver un listado de las opciones de cada comandos escriba: <comando>

Comando de reinicio de los servidores RestartWorkPlanner

Habitualmente se suele programar una tarea de reinicio de los servidores o instancias de WorkPlanner 1 vez al día. En entornos con IIS lo que hace es ejecutar un iisreset.bat. sin embargo existe un comando que efecuta otras tareas y además deja rastro en los logs del BOLDXML

RestartWorkPlanner: ejecuta un reinicio de todos los servidores con BOLD Cluster o sin él y los arranca de nuevo cargando la lista de planes en su caso.

Es necesario ejecutar el comando anterior con el usuario WP_USER=administrador, en caso contrario el comando generará un error.

Lo normal es crear un script de sincro (ej.: en la carpeta integration/sincro/RESETWP.bat) como el siguiente:

cd..
call boldxmlconfig.bat
set WP_USER=administrador
set WP_PWD=administrador
restartworkplanner

El script anterior puede lanzarse como tarea programada igual que el resto. En entornos donde esté instalado un BOLD Cluster habrá que definir una entrada en el fichero de configuración BOLDServer.json como la siguiente:

"CLUSTER": "http://xxlocalhost/bold/BOLDCluster.dll/soap"

Ver también Reiniciar WorkPlanner

Otros comandos

Para obtener una lista de todos los comandos documentados de BOLDXML basta con ejecutar, desde la línea de comandos preparada para ello (BOLDXMLConfig.bat) el comando “sincro” sin parámetros.

Añadir nuevos comandos al BOLDXML

Los comandos se implementan en su mayoría dentro del fichero .\scripts\BOLDXML.js. Es relativamente fácil añadir nuevos fijándonos en cualquiera de los actuales.

Los documentos de transformación determinan el comportamiento de las etapas de transformación dentro de un script de “sincro” (sincronización) entre sistemas. Se utiliza habitualmente para transformar un documento desde el formato del sistema origen al formato BOLDXML. Guarda cierta similitud con las transformaciones que se implementan habitualmente con XSLT.

El documento de transformación determina el formato final del documento BOLDXML que realmente se podrá enviar al servidor para su proceso. Los pasos entonces son los siguientes:

Documento XML/JSON nativo --> Documento de transformación --> Documento XML en formato BOLDXML

El documento generado a través del documento de transformación deberá tener un formato válido XML: ver Estructura de un documento XML en formato BOLDXML.

Localización de los ficheros de transformación

Con el módulo BOLDXML se distribuyen una serie de ficheros de transformación estándar. Por ejemplo: los de la interface de a3EQUIPO están en la carpeta BOLDXML2\a3 y tienen extensión .xml

Cuando se quiere personalizar alguno de estos ficheros (o bien realizar una transformación nueva, por ejemplo al implementar una nueva sincro) es necesario copiar el fichero .xml en la carpeta de nombre xslt base de configuración de la instancia, por ejemplo:

C:\Program Files (x86)\Global Planning Solutions\Custom_Files\Integration\configuration\development\xslt

Los scripts de integración miran primero si existe el fichero en esta carpeta, y sólo en el caso de que no exista, van a mirar luego a la carpeta dentro de BOLDXML2.

Ejemplo de documento XML de transformación

A continuación se muestra un documento de ejemplo de una transformación XML real:

<?xml version="1.0"?>
<IntContainerVector>
  {%- if CECOS_asPlanArea -%} {# Acerinox #}
    <UpdateFields UpdateOnly="1" COLNAME0="LabourAgreement" COLNAME1="ProfessionalCategory" COLNAME2="SystemProps.Grupo" COLNAME3="SystemProps.Nivel" ImportType="PropertyIntervalSet" UseLastContractWorkerDataForNewCut="1" MergeCutDuplicates="1"/>
  {%- else -%}
    <UpdateFields UpdateOnly="1" COLNAME0="LabourAgreement" COLNAME1="PlanArea" ImportType="PropertyIntervalSet" UseLastContractWorkerDataForNewCut="1" MergeCutDuplicates="1"/>
  {%- endif -%}  
  <CustomParams Control="A3"></CustomParams>

<!-- jsonquery=QueryResult.Record -->

{% for o in list %}
  <!-- {% set dummy=JSON.stringify(o) %} {{ dummy|safe }} -->
  <ContractWorker>
    <Worker valueExt="{{ o.EmployeeID }}"/>
    <PropertyStart value="{{ o.DateLaborLife|parseA3Date(1) }}"/>
    <PropertyEnd value="{{ o.DateEndLaborLife|parseA3Date }}"/>
    {%- if !CECOS_asPlanArea -%}
      <PlanArea valueExt="{{ o.WorkplaceID }}"/>
    {%- endif -%}
    <LabourAgreement valueRef="{{ o.AgreementCode }}"/>
    {%- if o.JobTitle == "" -%} 
      {% set msg = "Atención! Empleado sin JobTitle: " + o.CompanyCode + "-" + o.EmployeeCode %}
      {% set dummy=logger.warn(msg) %} {% set dummy=sincroObj.logging.incWarningCount() %}
      <ProfessionalCategory valueRef="MODIFICAR"/>
    {%- else -%}
      <ProfessionalCategory valueRef="{{ o.JobTitle }}"/> <!-- {{ o.WorkplaceCode }} {{ o.WorkplaceName }} -->
    {%- endif -%}
    {%- if CECOS_asPlanArea -%}
    <SystemProps>
      <Grupo value="{{ o.ClassificationCode }}"/> {% if grupoPorEmpleado[o.CompanyCode + "-" + o.EmployeeCode].length > 1 %} <!-- EMPLEADO CON CAMBIOS DE GRUPO --> {% endif %}
      <Nivel value="{{ o.SubClassificationCode }}"/>  {% if nivelPorEmpleado[o.CompanyCode + "-" + o.EmployeeCode].length > 1 %} <!-- EMPLEADO CON CAMBIOS DE NIVEL --> {% endif %}
    </SystemProps>
    {%- endif -%}
    <BOLDXML_info>
        <WorkerName>{{ o.CompanyCode + '-' + o.EmployeeCode}}</WorkerName
        <CompanyName>{{ o.CompanyCode }}</CompanyName>
        <PlanArea>{{ o.WorkplaceCode }} {{ o.WorkplaceName }}</PlanArea>
        <LabourAgreement>{{ o.AgreementDescription }}</LabourAgreement> <!-- {{ o.AgreementDescription | xml_c }} -->
    </BOLDXML_info>
  </ContractWorker>
{% endfor %}

</IntContainerVector>

Como se puede ver, la plantilla define el formato del documento destino (en este caso, un documento de importación de contratos, ver Formato XML para contratos. Ver también Categoría:Esquema XML)

Templating engine

La transformación se realiza utilizando el lenguaje de plantillas SWIG (originalmente era: https://github.com/paularmstrong/swig, pero dejó de ser mantenido y actualmente debería ser este otro: https://github.com/node-swig/swig-templates).

El documento se modela utilizando las variables que dan acceso a los datos en el documento origen que suele ser una lista de registros. Los datos de cada registro se inyectan en la plantilla en formato JSON.

Funciones pipe de transformación

A menudo resulta útil poder realizar pequeñas transformaciones directamente desde dentro de la propia plantilla de transformación.

Por ejemplo, se puede ver cómo se aplica la función transformación xml_c a un valor obtenido del documento de entrada (campo LabourAgreement). Las funciones de transformación internas reciben como parámetro un valor y retornan otro diferente. Las funciones pipe disponibles son las siguientes:

Sobre valores strings

• xml_c: convierte el valor en un valor válido que siempre será válido dentro de un comentario XML. Por ejemplo dentro de un comentario XML no es válido incluir doble caracter “–“. Esta función lo sustituye por el caracter “-“.
• padWithZeros(lenght): alarga el valor hasta la longitud indicada añadiendo los ceros delante que sean necesarios. Ej.: “67” | padWithZeros(5) –> “00067”

Convertir fechas a diferentes formatos

• parseA3Date: Decodifica una fecha-hora en el formato “a3”. Ej.: “31/05/2014 9:30:00” y la pasa a formato ISO: “2014-05-31T09:30:00”
• parseA3DateOnly: Decodifica una fecha-hora en el formato “a3”. Ej.: “31/05/2014 9:30:00” y la pasa a formato ISO (pero descartando las horas): “2014-05-31T00:00:00”
• parseMDYY2ISODateTime: Converts a string in in format dd/MM/YY into a javascript date
• parse_MDYY_2_YYYYMMDD: Transforms a string in in format dd/MM/YY into YYYY-MM-DD

…

Sobre valores numéricos

• incNumber: convierte el valor a un nº entero y luego lo incrementa en 1. Ej.: “1” | incNumber –> “2”

Otras

• today: retorna la fecha actual en formato ISO. Ej.: “” | today –> “2018-04-12T00:00:00”
• now: retorna la fecha-hora actual en formato ISO. Ej.: “” | today –> “2018-04-12T12:38:54”

Implementación de transformaciones custom

Sin embargo a veces no existe ninguna función de transformación que satisfaga los requerimientos. Entonces es necesario implementar una nueva. Para ello podemos utilizar toda la potencia del lenguaje javascript. Los pasos a seguir son los siguientes:

1. Implementar la función en el script de transformación
2. Publicar la función para que sea accesible desde la plantilla de transformación pseudo “xslt”.
3. Modificar la plantilla de transformación para utilizarla

Objetos disponibles desde la plantilla de transformación

• list: contiene la lista de registros obtenidos del documento de entrada. Ejemplo list[0] accedería al primer elemento.
• sincroObj: objeto Sincro que encapsula la tarea de sincronización. Desde él se puede acceder a otros objetos de contexto como son:
  • sincroObj.logging: acceso al controlador de los logs de resumen
  • sincroObj.BOLDXML: acceso al controlador BOLDXML
  • sincroObj.bold: acceso a la API SOAP del servidor
  • sincroObj.boldREST: acceso a la API REST del servidor

Acceder a los archivos de configuración desde dentro de la plantilla de transformación

A veces puede ser necesario acceder a variables o métodos desde la propia plantilla. El siguiente ejemplo muestra cómo hacerlo:

 <CustomParams UseExtCodeAsKeyField="1" Control="A3" KeepWPData="{{ sincroObj.BOLDXML.getKeepWPData() }}">

En este ejemplo el atributo KeepWPData se decide en función de lo que se haya configurado en el fichero BOLDXML.json (pero encapsulado con el método getKeeyWPData)

Control de errores y log desde dentro de la plantilla de transformación

Anotar el objeto JSON de entrada a transformar en el mismo resultado XML

Una opción bastante útil es poder ver directamente dentro del resultado de la transformación los datos del objeto original a transformar. Esto se realiza con la línea (opcional) siguiente:

 <!-- {% set dummy=JSON.stringify(o) %} {{ dummy|safe }} -->

El resultado en el fichero de salida será algo similar a los siguiente:

<!--  {"CompanyID":"a66844ce-d271-49cf-ba91-ad6864429e22","CompanyCode":"1722","EmployeeID":"95764b3e-e12b-4143-aefa-1117d7dbc139","EmployeeCode":"002128","DateLaborLife":"","DateEndLaborLife":"31/10/2015 0:00:00","SecondName1":"LOPEZ","SecondName2":"DIAZ","GivenName":"DOLORES","IdentifierNumber":"0900000Z","PhoneNumber1":"99999999","PhoneNumber2":"9999999","JobTitle":"STRUCTURE CD","WorkplaceID":"6d605342-beb8-40ed-be6f-b0360b66e9f7","WorkplaceCode":"306","WorkplaceName":"TARRAGONA 1","WorkplaceLocation":"MA1","SeniorityCompanyDate":"16/04/2009 0:00:00","AgreementID":"88ab035e-23b7-49eb-9c8c-e8b504ae860b"} -->
  <ContractWorker>
    <Worker valueExt="95764b3e-e12b-4143-aefa-1117d7dbc139"/>
    <PropertyStart value="1950-01-01T00:00:00"/>
    <PropertyEnd value="2015-10-31T00:00:00"/><LabourAgreement valueRef="00000172200305"/>
  ...
  <ContractWorker>

Con lo cual podremos ver más fácilmente el efecto de la transformación en función de los datos de entrada.

Uso de comandos de log dentro de la plantilla de transformación

En el ejemplo anterior la sección siguiente genera un aviso en el log e incrementa el contador de avisos correspondiente a la etapa de transformación que se está ejecutando:

    {%- if o.JobTitle == "" -%} 
      {% set msg = "Atención! Empleado sin JobTitle: " + o.CompanyCode + "-" + o.EmployeeCode %}
      {% set dummy=logger.warn(msg) %} {% set dummy=sincroObj.logging.incWarningCount() %}
      <ProfessionalCategory valueRef="MODIFICAR"/>
    {%- else -%}
      <ProfessionalCategory valueRef="{{ o.JobTitle }}"/> <!-- {{ o.WorkplaceCode }} {{ o.WorkplaceName }} -->
    {%- endif -%}

En este caso cuando el registro que se está procesando (objeto o) contiene la propiedad JobTitle en blanco, se genera un mensaje en el log: set dummy=logger.warn(msg) y se incrementa el contador de avisos: set dummy=sincroObj.logging.incWarningCount() que aparecerá luego en la página de resumen de la interface.

Acceso a la configuración del BOLDXML para controlar qué transformaciones se realizan

Otro ejemplo posible sería cuando no se quiere incluir una parte de la transformación en función de si alguna de las sincros ha sido desactivada. En el ejemplo siguiente, el campo LabourAgreement sólo se rellenerá si la sincro STD_ObtenerConvenios está habilitada:

 {%- if sincroObj.BOLDXML.isSincroEnabled("STD_ObtenerConvenios") %}
 <LabourAgreement valueRef="Plantilla:O.Laborales.CodigoConvenio"/>
 {% endif -%}

Formato general

La estructura de cualquier documento de importación/exportación de entidades de WorkPlanner es la siguiente:

<?xml version="1.0" encoding="ISO-8859-1"?>
<IntContainerVector>
<UpdateFields UpdateOnly="0" COLNAME0="nombre_de_campo_0_a_actualizar" .COLNAME1=" nombre_de_campo_1_a_actualizar " …/>
<CustomParams MergeCustomProperties="1" />
<NombreEntidad>
	… campos específicos de la entidad …
</NombreEntidad >
</IntContainerVector>

Paramétros de configuración

Estos parámetros determinan el tratamiento que se hará en el servidor del documento.

IntContainerVector: este nodo indica el inicio de un documento de importación de WorkPlanner y es el mismo con independencia de la entidad a tratar.

UpdateFields: este nodo es opcional y se utiliza para indicar los campos que se actualizarán en el caso de que la entidad que se esté importando ya existiera en WorkPlanner. Por ejemplo, si la profesional con código “12345” ya existe, si el proceso de importación se la encuentra sólo trataría de actualizar los campos que aquí se indicaran, ignorando el resto de ellos.

UpdateOnly: este atributo booleano es opcional. Indica si el único objetivo del documento de importación es la actualización de los datos (1-true) o bien tanto la creación como la actualización (0-false). Este último es el valor por defecto.

COLNAMEi: para el caso de una actualización indica si el valor de este campo se tendrá en cuenta o no.

UpdateAll: este atributo booleano indica si, cuando el objeto ya exista, se han de actualizar todos sus atributos según los nuevos valores del documento XML actual o no. Por defecto es “0” o false. Sólo se actualizan los que se especifiquen exactamente.

DebugLevel: regula el número de mensajes que genera una operación de importación de objetos. Si es 0 tan sólo salen los errores. Si es 1 aparecen mensajes informativos. Superior a 1 todo tipo de información adicional.

Opciones de configuración dentro del nodo CustomParams

Este nodo es opcional y se utiliza para pasar parámetros adicionales al servidor. Las propiedades específicas adicionales dependen de la entidad a sincronizar. De forma general existen las siguientes:

• MergeCustomProperties: boolean. Cuando se sincronizan propiedades auxiliares (ver CustomProperties) indica si se respetarán las propiedades auxiliares ya existentes en las entidades a actualizar –valor 1- o bien se reemplazarán totalmente por las que se definan en el documento de importación –valor 0- (no confundir con las propiedades definidas como CustomProps que definen una estructura más rígida)
• UseIDAsKeyField: boolean. Indica que los objetos a actualizar dentro de BOLD se identificarán en función del campo ID que se proporcione en el documento de carga.
• UseExtCodeAsKeyField: boolean. Indica que los objetos a actualizar se identificarán en función del campo ExtCode que se proporcione en el documento de carga.
• TotalImport: boolean. 0 Indica que la importación es incremental. Es el valor por defecto. 1 Indica que la importación es total. Una importación total lo que hace es borrar primero todo lo que hay en la base de datos que no aparece en el documento XML de entrada para esa clase de objetos (CUIDADO!).
• MaxPercentToDelete: integer. Si no se indica este valor por defecto se toma un valor del 40%. Como TotalImport es una opción muy peligrosa, se abortará la importación si se intenta borrar una cantidad de datos superior a MaxPercentToDelete. Por defecto este valor es del 40%.
• GlobalTransaction: boolean. 0 Indica que la importación se hará con transacciones objeto por objeto. Es el valor por defecto. 1 Indica que la importación se ejecuta con una transacción global.

Nota: en algunas entidades es posible identificar el objeto o entidad a actualizar utilizando otros atributos diferentes de los anteriores (ID, Name o ExtCode), dependiendo de la versión de la aplicación. Por ejemplo, en el caso de la entidad ContractWorker, es posible identificar el contrato a actualizar utilizando los campos código de empleado/a y una fecha cualquiera (Worker y ContractStart): el módulo de importación tratará de localizar en el sistema un contrato vigente de esa profesional durante la fecha indicada y ese será el que se actualizará según lo nuevos datos del documento de importación. Para más detalles ver la sección correspondiente.

Entidad a importar: nodo NombreEntidad

Cada entidad a importar debe encerrar su definición dentro de este nodo. En un mismo documento de importación todos los nodos NombreEntidad deben corresponder a la misma entidad. Es decir: no se admitiría que en un mismo documento coexistieran, por ejemplo, una entidad horario (Schedule) junto a un/a empleado/a (Worker).

Para ver el detalle del formato de cada tipo de objetos XML disponible ver Categoría:Esquema XML.

Otros parámetros menos frecuentes

• NoExactIdentify: boolean. Esta opción sirve solo para la importación de las clasificaciones ( WP_Clasificaciones) . Si este modo está activo, la importación intentará hacer un matching lo más fiel posible entre el fichero XML que se importa y lo que ya existe en la base de datos. Este modo sirve para pasar de un sistema de clasificación no fechado a un sistema de clasificación fechado. Por defecto vale 0.
• SearchValidPath: boolean. Cuando en el documento de importación no llega información suficiente para identificar el path completo donde va colgado un objeto, se ha definido este modo. En este caso el programa de importación identifica los nodos a partir del nombre y las fechas. Por defecto vale 0.
• TotalImporByNeed: boolean. Si está activo indica que se importarán en un modo especial las necesidades. Este modo borrará todas las necesidades cuyo código externo aparezca en el documento de entrada excepto aquellas que estén en el documento. Es decir:

Llega un documento con 3 needs.

Need A1. Código externo A
Need A2. Código externo A
Need A3. Código externo A

En la BD existen las siguientes Needs:

Need A1. Código externo A
Need A2. Código externo A
Need A3. Código externo A
Need A4. Código externo A
Need A5. Código externo A

Need B1. Código externo B
Need B2. Código externo B
Need C4. Código externo C

Lo que se ha de hacer es, de aquellos códigos externos que vienen en el documento, borramos todas menos las que están en el documento. En el documento se habla de needs con código externo A. Por tanto, borramos A4, A5 (son las únicas con código externo mencionado en el documento, y que a la vez, no vienen en el mismo) Las necesidades B1, B2 y C4 se dejan tal cual pues sus códigos externos no figuran en el documento.