Resumen
La integración SFTP predeterminada permite que KnowledgeCity intercambie datos con sistemas externos mediante una conexión FTP segura (SFTP) — sin requerir una integración de API directa desde el lado externo.
Admite tres flujos principales:
- Importar usuarios a KnowledgeCity desde una bandeja de entrada SFTP
- Exportar finalizaciones de cursos de KnowledgeCity a un destino SFTP
- Exportar datos del catálogo de cursos de KnowledgeCity a un destino SFTP
Todas las operaciones pueden programarse para ejecutarse automáticamente de forma diaria o semanal.
Introducción
El propósito de esta integración es permitir el intercambio de datos automatizado, basado en archivos, entre KnowledgeCity y un sistema externo a través de una conexión SFTP segura. Permite a los administradores:
- Aprovisionar y actualizar automáticamente a los usuarios en KnowledgeCity desde sistemas de RR. HH. o de directorio que generan exportaciones CSV
- Enviar los registros de finalización de cursos a sistemas externos de reportes o cumplimiento normativo mediante SFTP
- Compartir el catálogo de cursos de KnowledgeCity con plataformas externas en formato CSV
Esto es ideal para organizaciones que no cuentan con una integración de REST API directa disponible, pero que pueden intercambiar archivos mediante SFTP según un horario.
Requisitos
Antes de configurar la integración SFTP predeterminada, confirme los siguientes prerrequisitos:
Permisos de Administrador
- Debe tener acceso de Administrator en KnowledgeCity LMS para habilitar y configurar integraciones.
Acceso a la API de KnowledgeCity
- Se requiere una KnowledgeCity API Base URL y un API Secret válidos. Se recomienda crear un usuario dedicado para la integración y usar el API Secret de ese usuario.
- Use
api.knowledgecity.compara portales estándar, oapi-sa.knowledgecity.compara portales RB y MENA.
Detalles del Servidor SFTP
Debe tener listos los siguientes detalles de conexión SFTP para cada destino de exportación/importación:
- SFTP Host
- SFTP Port
- SFTP Username
- SFTP Private Key (codificada en base64)
- Target path (para exportaciones) o rutas Inbox/Received (para importaciones)
Nota: el contenido del archivo de clave privada debe estar codificado en base64 antes de pegarlo en la configuración. Puede usar un codificador base64 en línea para convertir su archivo de clave.
Preparación del Formato del Archivo CSV
- Para User Import: el archivo CSV de origen debe tener encabezados de columna que usted asignará a los campos de usuario de KnowledgeCity (por ejemplo,
UserLoginNameasignado al nombre de usuario). - Para Exports: usted definirá los títulos de las columnas y su orden en la configuración.
Pasos a Seguir
1) Habilitar la Integración Predeterminada
- Inicie sesión en KnowledgeCity LMS como Administrator.
- Vaya a la página Integrations.
- Encuentre la tarjeta Default Integration.
- Haga clic en Enable y asegúrese de que la casilla de nivel superior Turn On esté marcada.
Importante: el Turn On de nivel superior es un interruptor maestro. Si no está marcado, todas las configuraciones a nivel hijo (exportaciones e importación) serán ignoradas por el sistema, independientemente de su configuración individual.
2) Configurar los Ajustes de la API de KnowledgeCity
En la sección KnowledgeCity API, complete:
- Base API URL: La URL base de la API de KnowledgeCity con versión (por ejemplo,
https://api.knowledgecity.com/v1) - API Secret: El secreto de API del usuario dedicado a la integración
Guarde sus cambios.
3) Configurar Course Completion Export (Opcional)
Para exportar los registros de finalización de cursos de KnowledgeCity a su servidor SFTP:
- Expanda Export Setup y marque Turn On.
- Expanda Export Course Completion y marque Turn On.
- Establezca el patrón de nombre de archivo de exportación (use
[date]Ymd[/date]en el nombre para insertar automáticamente la fecha de exportación). - Establezca el formato de fecha de exportación para los campos de fecha de inicio y fecha de aprobación (déjelo en blanco para exportar como marca de tiempo Unix).
- Defina los CSV Fields: especifique los títulos de las columnas y su orden en el archivo de salida.
En la subsección FTP Destination:
- Marque Turn On.
- Complete los detalles de su conexión SFTP: host, puerto, nombre de usuario y clave privada codificada en base64.
- Establezca el Target path (relativo o absoluto) al que se transferirá el archivo generado.
En Schedule Setup:
- Marque Turn On y configure la recurrencia diaria o semanal.
4) Configurar Course Export (Opcional)
Para exportar el catálogo de cursos de KnowledgeCity a su servidor SFTP:
- En Export Setup, expanda Export Courses y marque Turn On.
- Establezca el patrón de nombre de archivo de exportación.
- Defina los CSV Fields: especifique los títulos de las columnas y su orden.
En la subsección FTP Destination:
- Marque Turn On y complete los detalles de su conexión SFTP y el Target path.
En Schedule Setup:
- Marque Turn On y configure la recurrencia deseada.
5) Configurar User Import (Opcional)
Para importar usuarios desde un archivo CSV en su servidor SFTP hacia KnowledgeCity:
- Expanda Import Setup y marque Turn On.
- Expanda Import Users y marque Turn On.
- En CSV Fields, asigne los encabezados de columna de su archivo de importación a los campos de usuario de KnowledgeCity (por ejemplo,
UserLoginName→ nombre de usuario).
En Metadata Handling, configure el comportamiento de la importación:
- Autoassign licence: Asigna la primera licencia disponible a los usuarios importados (se ignora si se especifica un Subscription ID)
- Subscription ID: Asigna una suscripción específica a los usuarios importados
- Assign license on user update: También intenta asignar una licencia a los usuarios existentes durante las actualizaciones
- Enable simulation mode: Modo de prueba en seco para realizar pruebas; no se escribirá ningún dato en KC
- Default group name: Agrega a los nuevos usuarios a un grupo predeterminado si no se especifica en el archivo de importación
- Succeed job on duplicate new user: Continúa con una advertencia en lugar de fallar si se detecta un usuario duplicado
- Activate and assign license to disabled user on update: Vuelve a habilitar y otorga licencia a un usuario que estaba previamente deshabilitado
- Skip user if exists on add_update action: Crea nuevos usuarios pero omite los existentes
- Assign Subscription by Group Name: Asigna suscripciones a nombres de grupo específicos
- Include/Exclude fields by action: Controla qué campos aplican para las acciones de agregar frente a actualizar
- Required fields: Especifica los campos que deben estar presentes para las acciones de agregar
Para deshabilitar a los usuarios que no están presentes en el archivo de importación, marque Turn On en Disable users not in the list y configure:
- Always disable o Disable when keyword is found in file name
- Minimum rows: Umbral de seguridad para evitar la desactivación masiva accidental por archivos pequeños o de prueba
En la subsección FTP Source:
- Marque Turn On y complete los detalles de su conexión SFTP.
- Establezca la Inbox path (donde el sistema busca archivos nuevos) y la Received path (adonde se mueven los archivos procesados después de descargarlos).
En Schedule Setup:
- Marque Turn On y configure la recurrencia deseada.
Resultado Esperado
Conexión y Sincronización Exitosas
- La integración está habilitada y las credenciales de la API de KnowledgeCity se validan.
- La conexión SFTP se verifica para cada sección de exportación/importación habilitada.
Course Completion Export (si está habilitado)
- Se genera un archivo CSV con los registros de finalización y se transfiere a la ruta de destino SFTP configurada según el horario definido.
- El nombre del archivo incluye la fecha de exportación cuando se usa el patrón
[date]Ymd[/date].
Course Export (si está habilitado)
- Se genera un archivo CSV con los datos del catálogo de cursos y se transfiere a la ruta de destino SFTP configurada según el horario definido.
User Import (si está habilitado)
- Los nuevos archivos CSV encontrados en la bandeja de entrada SFTP se descargan y procesan.
- Los usuarios se crean, actualizan, reactivan o desactivan en KnowledgeCity según la configuración de importación.
- Los archivos procesados se mueven de la bandeja de entrada a la ruta de recibidos.
Solución de Problemas
| Problema | Causa | Solución |
|---|---|---|
| La integración está habilitada pero nada se ejecuta | El Turn On de nivel superior no está marcado | Asegúrese de que la casilla maestra Turn On bajo Default Integration esté marcada. Todas las configuraciones hijas se ignoran si esto está desactivado. |
| La exportación o importación no se ejecuta según lo programado | Schedule Turn On no habilitado, o recurrencia configurada incorrectamente | Verifique que Turn On esté habilitado en la sección Schedule Setup de la exportación o importación relevante, y verifique la configuración de recurrencia. |
| Falla la conexión SFTP | Host, puerto, nombre de usuario o clave privada de SFTP incorrectos | Verifique todos los detalles SFTP con el administrador de su servidor. Asegúrese de que la clave privada esté correctamente codificada en base64 (no el archivo de clave sin procesar). |
| Los archivos se transfieren a la ubicación incorrecta | Ruta de destino/bandeja de entrada/recibidos incorrecta | Verifique nuevamente las rutas configuradas. Las rutas pueden ser relativas o absolutas — confirme con el administrador de su servidor SFTP cuál debe ser la ruta correcta. |
| Los usuarios no se importan | Import Users Turn On no habilitado, o no hay archivos en la ruta de la bandeja de entrada | Asegúrese de que tanto Import Setup como Import Users estén activados. Verifique que el archivo de importación esté presente en la ruta de bandeja de entrada configurada en el servidor SFTP. |
| El archivo de importación se procesa pero no se crean usuarios | Mapeo de columnas CSV incorrecto o faltan campos requeridos | Revise el mapeo de CSV Fields y asegúrese de que los encabezados de columna en el archivo de importación coincidan con lo configurado. Verifique que los campos requeridos estén presentes. |
| Los usuarios no reciben licencias | Autoassign licence no habilitado o Subscription ID no configurado | Habilite Autoassign licence o especifique un Subscription ID válido en la sección Metadata Handling. |
| Todos los usuarios se están deshabilitando inesperadamente | Disable users not in the list está habilitado sin un umbral mínimo de filas | Establezca un valor de minimum rows en la sección Disable users not in the list para evitar que archivos pequeños o de prueba desencadenen una desactivación masiva. |
| El trabajo de importación falla por usuarios duplicados | Existe un usuario duplicado y Succeed job on duplicate new user no está habilitado | Habilite Succeed job on duplicate new user para permitir que el trabajo continúe con una advertencia en lugar de fallar. |
| Falla la autenticación de la API de KC | Base API URL o API Secret incorrectos | Confirme que la Base API URL incluya la ruta de versión correcta y que el API Secret pertenezca a un usuario activo. Use api-sa.knowledgecity.com para portales RB/MENA. |