Integraciones SFTP - Master de personas
  • Identificarse

    • Integraciones SFTP - Master de personas

    1. Introducción

    1.1. Objetivo de este Documento

    El propósito de este documento es servir como una guía técnica interna para los equipos de implementación y consultoría de Rankmi. Su objetivo es detallar, paso a paso, el proceso de configuración de la funcionalidad de importación automatizada de datos a través de SFTP, asegurando una implementación consistente, eficiente y exitosa para nuestros clientes.

    1.2. Descripción General de la Funcionalidad

    El importador automatizado desde SFTP es una poderosa herramienta de la plataforma Rankmi diseñada para mantener la información de los clientes sincronizada y actualizada con su sistema de origen (generalmente un HRIS o ERP).

    La funcionalidad permite conectarse de forma segura a un servidor SFTP del cliente para leer archivos estructurados (como CSV, XLSX, XLS, etc). Una vez leído el archivo, la plataforma permite mapear las columnas del documento con las distintas entidades de Rankmi (usuarios, estructura organizacional, cargos, etc.). Esto elimina la necesidad de cargas manuales, reduce la probabilidad de errores humanos y asegura la integridad y consistencia de los datos en la plataforma.

    El flujo de trabajo se puede programar para que se ejecute de forma periódica (diaria, semanal, etc.), creando una automatización robusta que requiere mínima supervisión una vez configurada.

    1.3. Fases Principales de la Configuración

    El proceso de configuración de una nueva integración de este tipo se divide en las siguientes fases principales:

    1. Configuración de la Conexión SFTP: Se establece el vínculo seguro con el servidor del cliente donde se alojan los archivos.
    2. Definición del Archivo y Parámetros de Lectura: Se especifica el nombre del archivo a procesar y cómo debe ser interpretado (ej. delimitador en un CSV, hoja de un XLSX).
    3. Mapeo y Transformación de Datos: Es el corazón de la integración. Se asocia cada columna del archivo de origen con un campo específico en Rankmi y se pueden aplicar transformaciones a los datos si es necesario.
    4. Programación (Scheduling): Se define la frecuencia y el horario en que la plataforma buscará y procesará automáticamente los nuevos archivos.
    5. Activación y Monitoreo: Se activa la integración y se revisan los registros (logs) de ejecución para asegurar su correcto funcionamiento.

    2. Fase 1: Configuración de la Conexión SFTP

    2.1. Acceso a la Configuración

    Para llegar a la pantalla de configuración de la integración SFTP, sigue estos pasos desde el panel de administración de la empresa del cliente:

    1. Ir a Integraciones: En la vista principal de la empresa, dirígete a la sección "Configuración". Dentro de esta, ubica la opción "Integraciones" y haz clic en el ícono de engranaje para "Configurar".


    2. Seleccionar Integración SFTP/FTP: Se mostrará una lista con los tipos de integración disponibles. Localiza la opción "SFTP/FTP" y presiona el botón "Configurar" que se encuentra a su derecha.


    3. Acceder al Centro de Integración: Serás dirigido al "Rankmi Integration Center". Esta es la pantalla principal donde se gestiona toda la configuración de la conexión, los archivos y las entidades a importar.


    2.2. Descripción General

    Esta es la etapa inicial y fundamental del proceso de integración. El objetivo de esta fase es establecer una conexión segura y confiable entre la plataforma Rankmi y el servidor SFTP del cliente. A través de esta conexión, Rankmi podrá acceder de forma automatizada a los archivos que se utilizarán para la importación.

    2.3. Prerrequisitos

    Antes de continuar, asegúrate de tener la siguiente información del cliente:

    • Dominio o Dirección IP del servidor SFTP.
    • Puerto de conexión (usualmente 22).
    • Path de entrada (la ruta o carpeta donde estarán los archivos).
    • Usuario y Contraseña para la conexión.
    • (Si aplica) Api Rankmi Secret, en caso de que la integración lo requiera.

    2.4. Pasos para la Configuración en Pantalla

    Una vez en el "Rankmi Integration Center":

    1. Verificar el Entorno: Asegúrate de que el selector "Entorno" esté en "Test" para realizar las configuraciones iniciales sin afectar datos productivos.
    2. Completar Campos de Configuración: Rellena los campos del apartado "Configuración" con los datos del cliente.
    3. Validar Conexión: Haz clic en el botón verde "Validar conexión". Esta acción es indispensable.
      • ✅ Éxito: Un mensaje confirmará que la conexión se estableció correctamente.
      • ❌ Error: Si falla, revisa los parámetros (Dominio/IP, Puerto, Usuario, Contraseña, Path). Confirma con el cliente que los datos son correctos y que sus firewalls permiten el acceso desde Rankmi.
    4. Guardar Cambios: Una vez validada la conexión, presiona el botón azul "Guardar cambios".

    2.5. Descripción de los Campos

    • Tipo: Selector del tipo de conexión. Para este caso, debe estar seleccionado "SFTP".
    • Dominio/IP: La dirección del servidor SFTP del cliente. Ejemplo: sftp.miempresa.com o 35.83.25.153.
    • Puerto: El puerto para la conexión. Por defecto es 22. Modificar solo si el cliente lo indica.
    • Path de entrada: La ruta absoluta a la carpeta dentro del servidor donde se alojan los archivos a importar. Ejemplo: /Incoming/tests/.
    • Usuario: El nombre de usuario para el login en el SFTP.
    • Contraseña: La contraseña asociada a dicho usuario.
    • Api Rankmi Secret: Campo para una clave secreta de API.
      • Nota Importante: Este campo se utiliza únicamente para las integraciones de documentos (como liquidaciones de sueldo, contratos, etc.) que requieren una capa adicional de autenticación. Para el resto de las entidades (usuarios, áreas, cargos), este campo debe dejarse en blanco.

    3. Fase 2: Configuración de Entidades y Campos

    3.1. Descripción General

    Después de configurar la conexión SFTP, el siguiente paso es definir las estructuras de datos maestras que son permitidas en la plataforma Rankmi. A esto lo llamamos Entidades y Campos.

    • Una Entidad representa un modelo de datos maestro en Rankmi. Por ejemplo, MasterUser es la entidad que define todos los posibles atributos que puede tener un colaborador en la plataforma.
    • Un Campo es un atributo o una pieza de información específica de esa entidad. Por ejemplo, firstname, email o rut son campos válidos dentro de la entidad MasterUser.

    Aclaración Importante: En esta pantalla no se realiza el mapeo de columnas de un archivo. Aquí únicamente se define el "esquema" o el "diccionario" de datos que Rankmi es capaz de recibir.

    La asociación de las columnas de un archivo específico (ej. la columna "Nombre_Empleado" de un CSV) con un campo de una entidad (ej. el campo firstname de MasterUser) se realiza en la siguiente fase: "Configurar Documentos".

    Esta sección, por lo tanto, sirve para asegurar que todas las entidades y los campos que el cliente necesita importar estén correctamente declarados en el máster de Rankmi antes de proceder al mapeo.

    3.2. Vista Principal y Entidades por Defecto

    Al acceder a esta sección (haciendo clic en el botón "Configurar entidades" en la pantalla principal de la integración), verás un listado de las entidades ya configuradas.

    La plataforma incluye un set de entidades predefinidas para los casos de uso más comunes:

    • MasterUser: Para la creación y actualización masiva de usuarios.
    • MasterArea: Para crear o modificar la estructura organizacional (áreas/centros de costo).
    • MasterPosition: Para el catálogo de cargos de la compañía.
    • MasterOrganizationPosition: Para gestionar las posiciones (la unión de un cargo, un área y una persona).
    • MasterUserDeactivation: Para procesar la baja o desactivación de usuarios.
    • FileSignature: Para la carga de documentos que requieren un proceso de firma electrónica.

    3.3. Cómo Crear una Nueva Entidad

    Si necesitas importar un tipo de dato que no corresponde a las entidades por defecto, puedes crear una nueva.

    1. Desde la vista principal, haz clic en el botón azul + Crear entidad y campos.
    2. Aparecerá la ventana modal "Crear Entidad y Campo".


    3. Completa los siguientes datos:
      • Entidad*: Asigna un nombre único y descriptivo a tu nueva entidad.
      • Campo: Define el primer campo de la entidad:
        • Nombre: El nombre del campo. Se recomienda que coincida con el nombre de la columna en el archivo de origen.
        • Tipo: El tipo de dato (String, Integer, Date, etc.).
          • string (Cadena de texto)
            • ¿Qué es? Es el tipo de dato más común y versátil. Permite cualquier combinación de letras, números y símbolos. Piense en él como un campo de "texto libre".
            • Úsalo para: Nombres de personas, correos electrónicos, cargos, áreas, direcciones, RUT (ya que incluye puntos y guión), números de teléfono (ya que pueden incluir "+", espacios o guiones).
            • Ejemplos: "Ana Pérez", "jperez@empresa.com", "Gerente de Operaciones", "12.345.678-9".
          • integer (Número entero)
            • ¿Qué es? Se usa exclusivamente para números enteros, es decir, sin decimales.
            • Úsalo para: Datos que se pueden contar y no tienen fracciones, como la edad, el número de hijos o un ID de empleado numérico.
            • Ejemplos: 35 (Edad), 4 (Hijos), 10524 (ID Empleado).
            • Importante: No lo uses para un RUT o un teléfono, ya que esos datos usan el tipo string.
          • decimal (Número con decimales)
            • ¿Qué es? Sirve para números que sí pueden tener decimales.
            • Úsalo para: Valores monetarios como sueldos, bonos, comisiones, o para datos que requieren precisión como porcentajes o métricas (ej. FTE, horas extra).
            • Ejemplos: 1250000.50 (Sueldo), 1.5 (Días de vacaciones), 0.75 (Porcentaje).
          • date (Fecha)
            • ¿Qué es? Se usa específicamente para guardar fechas.
            • Úsalo para: Fechas de nacimiento, fechas de ingreso a la compañía, fechas de término de contrato, etc.
            • Importante: La plataforma espera las fechas en un formato consistente (ej. AAAA-MM-DD o DD-MM-AAAA). Es crucial asegurar que los datos en el archivo de origen respeten siempre el mismo formato para evitar errores.
            • Ejemplos: "2024-09-01", "15-05-1990".
          • boolean (Booleano / Verdadero o Falso)
            • ¿Qué es? Es el tipo de dato más simple. Solo puede tener dos valores posibles, como un interruptor de "encendido" o "apagado".
            • Úsalo para: Representar respuestas de SÍ o NO. Por ejemplo: ¿Es un usuario activo? ¿Tiene personal a cargo? ¿Cuenta con licencia de conducir?
            • Ejemplos: El sistema suele interpretar true / false, 1 / 0, o SI / NO como valores válidos para este tipo.
        • Longitud: El largo máximo de caracteres para este campo.
        • Requerido: Selecciona "Sí" o "No" para indicar si este campo es obligatorio para la importación.
    5. Para añadir más campos a la entidad, presiona el botón + Agregar campo y repite el paso anterior.
    6. Una vez definidos todos los campos, haz clic en "Guardar". La nueva entidad aparecerá en el listado principal.

    3.4. Cómo Editar una Entidad Existente

    Es común necesitar ajustar las entidades existentes, ya sea para añadir un campo personalizado que el cliente necesita o para modificar uno existente.

    1. En el listado de entidades, ubica la que deseas modificar y haz clic en el botón "Editar".
    2. Se abrirá la ventana modal "Editar Entidad y Campo", mostrando todos los campos actuales de la entidad.


    3. Desde esta vista puedes:
      • Modificar atributos: Cambiar el Tipo, Longitud o si un campo es Requerido.
      • Agregar nuevos campos: Usa el botón + Agregar campo al final de la lista



      • Eliminar campos: Haz clic en el ícono de la papelera 🗑️ a la derecha del campo que deseas quitar.
    4. Al finalizar tus cambios, presiona "Guardar".

    4. Fase 3: Configuración de Documentos y Mapeo

    4.1. Descripción General

    Esta es la fase donde se conecta todo el trabajo anterior. Aquí se define un "documento", que es una regla de procesamiento que le indica a Rankmi:

    1. Qué archivo debe buscar en el SFTP (usando un prefijo).
    2. Cómo debe leerlo (formato, codificación, etc.).
    3. A qué entidad de Rankmi corresponden los datos de ese archivo.
    4. Cómo mapear cada columna del archivo a un campo específico de la entidad.

    El proceso se realiza en dos etapas: primero, se crea la configuración general del documento y, segundo, se edita para realizar el mapeo detallado de las columnas.

    4.2. Creación del Documento de Importación

    Desde la pantalla de "Configuración de archivos", verás un listado de los procesos ya existentes.

    Para crear uno nuevo:

    1. Haz clic en el botón azul + Crear archivos.
    2. Completa los campos en la ventana modal "Crear archivo":

    • Entidad*: Selecciona la entidad (definida en la Fase 2) a la cual pertenecen los datos de este archivo. Ej: MasterUser.
    • Prefijo*: El inicio del nombre del archivo que Rankmi debe buscar en el SFTP. Es sensible a mayúsculas y minúsculas. Ejemplo: si los archivos se llaman users-2024-05-20.csv, el prefijo sería users-.
    • Frecuencia de actualización*: La calendarización de la tarea. Define cuándo se ejecutará la importación (diariamente, semanalmente, etc.).
    • Tipo*: El formato del archivo. Selecciona calcsheet para .xlsx y .xls, o csv para archivos de texto delimitado.
    • Número de intentos: La tolerancia a fallos. Es el número máximo de filas con error que se permitirán antes de que el proceso se detenga y se marque como fallido.
    • Separador: Solo para archivos CSV. El carácter que separa las columnas (ej: , o ;).
    • Codificación: La codificación de caracteres del archivo. UTF-8 es el estándar recomendado. Usar otra solo si el cliente lo especifica (ej: ISO-8859-1).
    • Método*: El método de procesamiento. Generalmente se asocia a la entidad seleccionada, pero para documentos (FileSignature) se usa una API específica.
    • Notificar a: Una lista de correos electrónicos (separados por coma) que recibirán una notificación sobre el resultado de cada ejecución.
    1. Haz clic en "Guardar". El documento se creará, pero aún no estará listo para usarse.

    4.3. Mapeo de Columnas (Editando el Documento)

    Inmediatamente después de crear el documento, debes configurarle el mapeo.

    1. Busca el documento que acabas de crear en el listado y haz clic en "Editar".



    2. La ventana modal se abrirá de nuevo, pero ahora incluirá la sección "Tipo de configuración" en la parte inferior.
    3. Aquí es donde se realiza el mapeo:
    • Tipo de configuración:
      • Por nombre de la columna (Recomendado): El mapeo se basa en los encabezados del archivo. Es más robusto ante cambios en el orden de las columnas.
      • Por posición de la columna: El mapeo se basa en el número de la columna (1, 2, 3...). Es más frágil si el cliente altera el archivo.
    • Mapeo de Campos:
      • Campo Rankmi: Despliega y selecciona el campo de la entidad de destino (ej: rut, email, firstname).
      • Nombre del campo en archivo empresa: Escribe el nombre exacto del encabezado de la columna en el archivo del cliente que corresponde a ese campo Rankmi.
    1. Usa el botón + Agregar campo para añadir todas las filas de mapeo que necesites.
    2. Una vez que todas las columnas del archivo que deseas importar estén mapeadas a un campo de Rankmi, haz clic en "Guardar".

    5. Fase 4: Monitoreo y Verificación de Ejecuciones

    5.1. Descripción General

    Una vez que la integración está configurada y activa, es crucial monitorear sus ejecuciones para asegurar que los datos se están procesando correctamente. La plataforma ofrece un historial detallado que permite verificar el resultado de cada proceso y diagnosticar rápidamente cualquier error que pueda surgir.

    5.2. Historial de Ejecución

    Para acceder al resumen de todas las ejecuciones, debes hacer clic en el botón "Ver historial" desde la pantalla principal de la integración SFTP.

    Esto te llevará a la pantalla de "Historial de ejecución", donde verás un registro de cada vez que la integración ha intentado procesar un archivo.

    En esta vista puedes identificar rápidamente el estado de cada proceso:

    • Entidad: Muestra qué tipo de datos se intentó procesar (ej: MasterOrganizationPosition).
    • Fecha/Hora Ejecución: El momento exacto en que se ejecutó la tarea.
    • Resultado: El estado final del proceso.
      • ✅ Finalizado: El archivo fue procesado con éxito.
      • 🔴 Error: Ocurrieron problemas durante el procesamiento que impidieron que se completara.
    • ver detalles: Un enlace para investigar los errores específicos de una ejecución fallida.

    Puedes usar el selector de "Estado" en la esquina superior derecha para filtrar la lista y encontrar rápidamente las ejecuciones que fallaron.

    5.3. Detalles de la Ejecución y Diagnóstico de Errores

    Al hacer clic en "ver detalles" en una ejecución con estado "Error", accederás a una pantalla con el desglose de los problemas encontrados.

    Esta vista es la herramienta más importante para el diagnóstico. La columna Mensaje te dará información precisa sobre la causa del fallo. Analizando estos mensajes, el equipo puede identificar distintos tipos de problemas:

    • Errores de Formato de Datos: Ocurren cuando un dato no cumple con el tipo esperado. Por ejemplo, Invalid Format of column activation_date, expected type [Decimal], indica que la columna "activation_date" no tiene el formato numérico correcto.
    • Errores de Lógica de Negocio: Ocurren cuando los datos, aunque formalmente correctos, no cumplen con las reglas de negocio de la plataforma. Esta pantalla es clave para detectarlos. Por ejemplo:
      • [104] Invalid user data. El rut ya está en uso: Indica que se está intentando crear un usuario con un RUT que ya existe, violando la regla de que este identificador debe ser único.
      • [101] The assigned Area does not exist in the company: Muestra que se está intentando asignar un usuario a un código de área que no ha sido creado previamente en Rankmi. El dato referencial no existe.
    • Superación de la Tolerancia a Fallos: Mensajes como Impossible to continue cause invalid errors rows count 1 indican que el proceso se detuvo porque el número de filas con error superó el umbral definido en la configuración del documento.

    Analizando esta información, el equipo de implementación puede contactar al cliente con feedback específico para que corrija los datos en su archivo de origen, asegurando el éxito de la siguiente ejecución.

    6. Consulta para Usuarios Finales: Centro de Importación

    Además del historial de ejecución disponible para los administradores de Rankmi, los usuarios finales designados por el cliente (generalmente del área de RRHH) tienen acceso a una vista similar en el Centro de Importación de la plataforma.

    En esta sección, los usuarios pueden:

    1. Ver el resultado de las ejecuciones automáticas que se han procesado.
    2. Descargar el archivo original que fue procesado en cada carga.
    3. Descargar un nuevo archivo que contiene únicamente las filas que presentaron errores, junto con una descripción del problema en cada una.

    Esta última funcionalidad es especialmente útil, ya que permite al cliente aislar rápidamente los problemas, corregirlos en el archivo de errores y volver a cargarlo de forma manual, agilizando enormemente el proceso de corrección de datos.