Este artículo explica cómo configurar la importación y sincronización de usuarios y agrupaciones en SMARTFENSE consultando una API externa. Detalla la configuración de la conexión, el mapeo de claves JSON, las reglas de creación y actualización, y el manejo de mayúsculas y campos vacíos.
La configuración está disponible en Usuarios y grupos > Importación y sincronización > Desde API.
Pre-requisitos
- Una API externa accesible que devuelva los datos de los usuarios en formato JSON.
- Token de autenticación válido para esa API.
- Acceso de administrador a la instancia de SMARTFENSE.
Conexión con la API
Complete los siguientes campos para que SMARTFENSE pueda consultar la API:
- URL de la API: dirección a la cual SMARTFENSE envía la solicitud.
- Token de autenticación: token de acceso correspondiente.
Correspondencia entre campos
Esta sección permite mapear los campos de SMARTFENSE con las claves del JSON que devuelve su API.
Ejemplo de mapeo
Si la API devuelve la clave user-id y desea utilizarla como nombre de usuario, establezca la correspondencia entre el campo username de SMARTFENSE y la clave user-id de la API.
Las claves se ingresan sin comillas.
Campos obligatorios
Los siguientes campos son obligatorios:
- Nombre
- Apellido
El resto de los campos son opcionales.
Cuándo se crea o se edita un usuario
- Si un usuario presente en la respuesta de la API no existe en SMARTFENSE, será creado.
- Si ya existe, será actualizado.
La identificación se hace por el nombre de usuario especificado en la respuesta de la API. Si no se especifica, la plataforma usa la primera parte del email (lo que está antes del @).
No es posible editar el nombre de usuario ni la dirección de correo electrónico de un usuario existente mediante esta funcionalidad.
Uso de mayúsculas
Nombres de usuario
SMARTFENSE no distingue mayúsculas y minúsculas para determinar si un usuario existe. Al crear un usuario nuevo, se respeta el formato devuelto por la API.
Agrupaciones
En grupos, áreas funcionales y niveles jerárquicos sí se distinguen mayúsculas. Si la API devuelve nombres sin coincidencia exacta, se intenta una segunda búsqueda ignorando mayúsculas.
Otros casos relevantes
- El email siempre se almacena en minúsculas.
- Nombre y apellido se formatean con mayúscula inicial en cada palabra.
- El UPN respeta el formato exacto devuelto por la API.
Comportamiento ante campos vacíos
| Campo | Comportamiento si falta en la respuesta |
|---|---|
| Lenguaje | Usuarios nuevos toman el del administrador que importa. Los existentes mantienen el actual. |
| Nombre de usuario | Se genera de la primera parte del email. |
| Sin email, el usuario no puede importarse. | |
| Estado | Usuarios nuevos se crean como Activo. Los existentes mantienen el actual. |
| Rol | Usuarios nuevos se crean como Usuario final. Los existentes mantienen el actual. |
| Teléfono, ID de empleado, UPN | Quedan vacíos. |
Ayuda en linea
Cada campo de la pantalla incluye un ícono (i) a su derecha. Al ubicar el cursor sobre el ícono, se abre una ventana emergente con ayuda específica para ese campo.
💡 Mejores prácticas
- Verifique que la API retorne siempre Nombre, Apellido y Email, ya que son obligatorios.
- Defina claramente el mapeo de claves JSON antes de habilitar la sincronización automática.
- Mantenga consistencia en los nombres de las agrupaciones para evitar duplicados por mayúsculas y minúsculas.
- Pruebe la integración en un entorno controlado antes de sincronizar usuarios en producción.
- Rote periódicamente el token de autenticación y actualícelo en SMARTFENSE para evitar interrupciones del servicio.