Configurar el conector genérico de sincronización de datos

SmartOSH dispone de un módulo de importación y sincronización que permite cargar datos masivamente mediante un archivo de intercambio (Excel o CSV) depositado en un servidor FTP. Este documento describe el formato, el nombrado y la configuración necesaria para usar el conector genérico.

Formatos de archivo admitidos

Excel (XLS / XLSX)

El archivo de datos puede entregarse en formato Microsoft Excel (.xls o .xlsx). En este formato, cada tabla se representa como una pestaña (hoja) dentro del mismo libro. Los nombres y el orden de las pestañas deben coincidir con los descritos en la especificación de campos.

CSV

También puede usarse CSV, con un archivo por cada tabla. Reglas obligatorias:

• Delimitador: ;
• Carácter de escape para textos literales: comilla doble "
• Codificación: UTF-8
• Primera fila: nombres de columnas

Ejemplo:

Codigo;Nombre;TipoIdentificacion;Identificador
001;ACME S.A.;0;A554668987
002;"LUSIANA S.A";0;A00046879

Fotografías de empleado (opcional)

El archivo opcional de fotografías debe entregarse como ZIP con las imágenes en el directorio raíz, con extensión .jpg, .gif o .png.

Nombrado de archivos

El nombre debe empezar siempre por KB020 e incluir, separados por guion, los datos básicos del archivo.

Excel (XLS/XLSX)

Patrón: KB020-ORDEN-Nombre descriptivo.xlsx

Ejemplo: KB020-1000-Carga datos MiEmpresa 20170622.xlsx

CSV

Como hay un archivo por tabla, el nombre debe incluir el nombre de la tabla en lugar del descriptivo. El prefijo numérico garantiza que se carguen en el orden correcto.

Ejemplos:

• KB020-100-Empresas.csv
• KB020-200-Centros.csv
• KB020-300-Secciones.csv
• KB020-400-Puestos.csv
• KB020-500-Empleados.csv
• KB020-600-Asignaciones.csv
• KB020-700-InvestigacionAccidente.csv
• KB020-800-Formaciones.csv
• KB020-900-Convocatorias.csv
• KB020-1000-Convalidaciones.csv
• KB020-1100-SesionesFormativas.csv
• KB020-1200-AccionesFormativas.csv
• KB020-1300-Cargo.csv
• KB020-1400-AsignacionCargo.csv

Sistemas legacy con nombres cortos

Si por limitaciones técnicas el cliente no puede usar nombres largos, puede entregar los archivos con nombre corto y añadir un archivo index.txt en la raíz de la carpeta con las equivalencias.

Formato de cada línea: [nombrecorto];[nombrelargo]

Ejemplo:

emp.csv;KB020-100-Empresas.csv
cen.csv;KB020-200-Centros.csv
secci.csv;KB020-300-Secciones.csv

Ubicación del archivo (FTP)

El cliente debe depositar los archivos en un servidor FTP. Hay dos opciones:

• FTP seguro propio del cliente (FTP, FTPS o SFTP).
• FTP seguro proporcionado por SmartOSH (solicitándolo al equipo de consultoría).

Si se usa el servicio de SmartOSH, los datos de conexión son:

Parámetro	Valor
Servidor	sync.smartosh.com
Tipo	FTP / FTPS
Usuario	Proporcionado por consultoría
Contraseña	Proporcionada por consultoría

Configurar el conector en SmartOSH

1. Acceder al tenant correspondiente con un usuario Administrador.
2. Ir a Opciones → Conexión de datos y añadir un nuevo conector con los siguientes valores:

Campo	Valor
Código importación	GENERIC
Tipo	FTP / FTPS (o SFTP si lo proporciona el cliente)
URL	sync.smartosh.com (o el servidor del cliente)
Ruta	Dejar en blanco salvo indicación de soporte
Usuario	Proporcionado por consultoría
Contraseña	Proporcionada por consultoría
Activo	Sí
Sobreescribir	Sí

3. Guardar la configuración.
4. La importación puede forzarse en cualquier momento con la acción Sincronizar ahora.

Servidor FTP del cliente

Si el cliente proporciona su propio servidor, debe especificarse el tipo (FTP / FTPS / SFTP) según corresponda. Para SFTP se admite que los archivos estén en una subcarpeta concreta, indicándola en el campo Ruta.

Contenido de los archivos

• En Excel, las pestañas deben llamarse y ordenarse como indica la especificación.
• En CSV, cada tabla va en un archivo, con prefijo numérico para fijar el orden de carga.
• En cualquier caso, solo se incluyen las columnas con datos a traspasar. No es necesario crear todas las columnas de todos los campos.

Especificación detallada de campos

La lista completa de pestañas, nombres de tablas y campos disponibles está publicada en smart.smartosh.com/kb020 (requiere autenticación).

Anexo: errores controlados

Durante el procesamiento, el conector puede emitir los siguientes errores:

Mensaje	Explicación
El formato no está correctamente definido y no se dispone de información sobre el mapeo '{0}'	Falta la columna Operación en el Excel.
No hay valor en la columna '{0}' y este es necesario, {1}	Faltan campos obligatorios o están vacíos.
Se ha encontrado más de un registro a actualizar basándose en el identificador. La operación no puede continuar.	Los registros identificados por código deben ser únicos.
No existe la {1} con Código {0} ni tampoco en los códigos equivalentes...	Error de datos: no se puede determinar si insertar o actualizar.
Error al asignar el valor '{0}' al campo '{1}'	Formato incorrecto del valor (depende del campo).
Error al EscribirFTP en la conexión	Problema de conexión o permisos al escribir en el FTP.

Precaución

Si una sincronización finaliza con errores, revise siempre el historial del conector antes de relanzar la operación. Forzar Sincronizar ahora con datos defectuosos solo repetirá el error.

---

Fuente: KB020 «Conector genérico para la sincronización de datos vía archivos de intercambio», módulo Consultoría, versión 1.5, 19-04-2021.