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

Updated on: 24/11/2025