👥 ggLeap Importar Usuarios

1. 🧭 Introducción

Para importar usuarios a ggLeap, necesitas configurar cómo se asignan los campos de entrada CSV a la base de datos interna de usuarios de ggLeap. Esta guía te explica qué campos de usuario se soportan y cómo configurar tu asignación de importación.

---

2. 📋 Campos de Usuario Soportados

Los siguientes campos se soportan actualmente para importar usuarios:

• UniversityUserId (Exclusivo para Universidades y Centros K–12)
• Email
• Username
• FirstName
• LastName

---

3. 📦 Procedimientos de Importación

La funcionalidad de importación de ggLeap soporta la creación, actualización y archivado de usuarios.

• Si tu CSV usa nombres de columna personalizados, envía un ejemplo al equipo de soporte de ggCircuit para que te ayude a configurar las asignaciones.
• Alternativamente, puedes configurar la asignación tú mismo usando la API (actualmente no hay configuración disponible en la UI).

---

4. ⚙️ Configuración de Asignación

4.1 Configuración de Delimitador

El delimitador por defecto es , pero puedes configurarlo como "auto-detect" especificando null.

---

4.2 Asignación de Columnas: CSV → Campos de ggLeap

Ejemplo de configuración de asignación:

{
"Config": {
"Mappings": {
"UniversityUserId": {
"TargetFieldName": "UniversityUserId",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "UniversityIdNumber"
},
"MembershipPlaytime": {
"TargetFieldName": "MembershipPlaytime",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "Playtime",
"IsCustomField": false
},
"Membership Start Date": {
"TargetFieldName": "Membership Start Date",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "MembershipStartDate",
"IsCustomField": true
},
"Membership End Date": {
"TargetFieldName": "Membership End Date",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "MembershipEndDate",
"IsCustomField": true
},
"Affiliation": {
"TargetFieldName": "Affiliation",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": null,
"IsCustomField": true
}
},
"Enabled": true,
"Delimiter": null,
"DateFormats": ["yyyy-MM-dd"],
"BooleanValues": {
"FalseValues": ["N", "F", "No", "False", "0"],
"TrueValues": ["Y", "T", "Yes", "True", "1"]
},
"NullValues": ["NULL"]
}
}

Referencia de Campos:

• TargetFieldName: El campo de destino en ggLeap.
• IgnoreField: Coloca en true para excluir este campo de la importación.
• RequireValue: Indica si se requiere un valor no nulo.
• SourceHeaderName: Nombre del campo en el CSV de origen.
• IsCustomField: Coloca en true para campos que no están nativamente en ggLeap (asegúrate de que existan en la configuración de detalles de usuario).

---

4.3 Campo Deleted

• true: Archiva el usuario
• false: Desarchiva el usuario

---

4.4 MembershipPlaytime

Define la duración del tiempo de juego de Gamepass para usuarios importados.

---

4.5 Fechas de Membresía

Configura las fechas de inicio y fin de Gamepass para cada usuario.

---

4.6 Actualizar Configuración de Importación CSV

Usa la API de Actualización de Configuración de Importación CSV para modificar la asignación.

---

4.7 Obtener Configuración Actual

Usa la API de Obtención de Configuración de Importación CSV para obtener la configuración existente.

---

4.8 Cancelar Trabajo de Importación

Para cancelar una importación en ejecución, usa la API de Cancelación de Trabajo de Importación de Usuario.

---

5. ✅ Valores Booleanos

Valores aceptados para campos verdadero/falso:

• Verdadero: Y, T, Yes, True, 1
• Falso: N, F, No, False, 0

---

6. 📅 Formatos de Fecha

Formatos de fecha soportados en CSV:

• yyyy-MM-dd
• dd/MM/yyyy
• MM/dd/yy
• dd.MM.yyyy

---

7. 🗺️ Consejos de Asignación de Columnas CSV

Asigna los encabezados de tu CSV de origen a los campos esperados de ggLeap usando el formato de ejemplo. Puedes personalizar esto según la estructura y datos de tu centro.

---

🧠 Lógica de Importación Adicional e Información

Coincidencia de Usuarios Existentes

1. Intenta encontrar el usuario por UniversityIdNumber (asignado a StudentId).
2. Si no se encuentra, intenta hacer coincidir por EmailAddress.
3. Si aún no se encuentra:

• Si otro centro tiene el mismo correo: registra un conflicto, omite el registro.
• Si el mismo nombre de usuario existe en el centro actual: registra un conflicto, omite el registro.
• Si no: crea un nuevo usuario, opcionalmente asigna un Gamepass.

Actualización de Usuarios Existentes

• Actualiza todos los campos del CSV.

• Antes de actualizar Username, verifica la unicidad en el centro actual.

• Antes de actualizar EmailAddress, verifica la unicidad global en ggLeap.

• Si el usuario está archivado, colócalo como eliminado.

• Si los valores de membresía cambiaron, actualiza o elimina Gamepass:

• Si MembershipStartDate es NULL: elimina Gamepass.

• Si no: reemplaza con nuevo MembershipPlaytime.

Manejo de Errores y Registro

• Todos los errores deben registrarse en el registro de importación.
• Si ocurren 5 o más errores internos, aborta el proceso de importación.
• Para cada usuario actualizado/agregado, registra la acción.
• Actualiza el estado/resumen de importación cada 2–5 segundos.