> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.ggcircuit.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 👥 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.