> ## 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 User Import


## 1. 🧭 Introduction

Importing users into ggLeap requires configuring how CSV input fields are mapped to the internal ggLeap user database. This guide explains supported user fields and how to set up your import mapping configuration.

---

## 2. 📋 Supported User Fields

The following fields are currently supported for importing users:

* `UniversityUserId` (Exclusive to University and K–12 Centers)
* `Email`
* `Username`
* `FirstName`
* `LastName`

---

## 3. 📦 Import Procedures

ggLeap’s import functionality supports the **creation**, **updating**, and **archiving** of users.

* If your CSV uses custom column names, submit a sample to the ggCircuit support team to help configure the mappings.
* Alternatively, you can configure the mapping yourself using the API (no UI configuration is currently available).

---

## 4. ⚙️ Mapping Configuration

### 4.1 Delimiter Setup

The default delimiter is `,` but it can be set to `"auto-detect"` by specifying `null`.

---

### 4.2 Mapping Columns: CSV → ggLeap Fields

Example mapping configuration:

```
{
"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"]
}
}
```

**Field Reference:**

* `TargetFieldName`: The destination field in ggLeap.
* `IgnoreField`: Set to true to exclude this field from import.
* `RequireValue`: Indicates whether a non-null value is required.
* `SourceHeaderName`: Name of the field in the source CSV.
* `IsCustomField`: Set to `true` for fields not natively in ggLeap (ensure these exist in user details config).

---

### 4.3 Deleted Field

* `true`: Archive the user
* `false`: Unarchive the user

---

### 4.4 MembershipPlaytime

Defines the Gamepass playtime duration for imported users.

---

### 4.5 Membership Dates

Configure Gamepass `start` and `end` dates for each user.

---

### 4.6 Update CSV Import Configuration

Use the **Update CSV Import Configuration API** to modify the mapping.

---

### 4.7 Get Current Configuration

Use the **Get CSV Import Configuration API** to fetch existing config.

---

### 4.8 Cancel Import Job

To abort a running import, use the **Cancel User Import Job API**.

---

## 5. ✅ Boolean Values

Accepted values for true/false fields:

* **True**: `Y`, `T`, `Yes`, `True`, `1`
* **False**: `N`, `F`, `No`, `False`, `0`

---

## 6. 📅 Date Formats

Supported date formats in CSV:

* `yyyy-MM-dd`
* `dd/MM/yyyy`
* `MM/dd/yy`
* `dd.MM.yyyy`

---

## 7. 🗺️ CSV Column Mapping Tips

Map your source CSV headers to the expected ggLeap fields using the example format. You may customize this based on your center’s structure and data.

---

## 🧠 Additional Import Logic & Notes

### Matching Existing Users

1. Try to find the user by `UniversityIdNumber` (mapped to `StudentId`).
2. If not found, try to match by `EmailAddress`.
3. If still not found:

* If another center has the same email: log a **conflict**, skip the record.
* If same username exists in the current center: log a **conflict**, skip the record.
* Otherwise: **create a new user**, optionally assign a Gamepass.

### Updating Existing Users

* Update all fields from the CSV.
* Before updating `Username`, check uniqueness in current center.
* Before updating `EmailAddress`, check global ggLeap uniqueness.
* If user is archived, set as deleted.
* If membership values changed, update or delete Gamepass:

* If `MembershipStartDate` is `NULL`: remove Gamepass.
* Otherwise: replace with new `MembershipPlaytime`.

### Error Handling & Logging

* All errors should be recorded in the **import log**.
* If 5+ internal errors occur, abort the import process.
* For each updated/added user, log the action.
* Update **import state/summary** every 2–5 seconds.

---