GGLeap User Import

1. Introduction

To import users into ggLeap, it is essential to configure how the CSV input maps to the ggLeap users' database. This manual outlines the supported user fields for importing and the necessary steps to set up the import configuration.

2. Supported User Fields

The following user fields are currently supported for importing:

• UniversityUserId (exclusive to University and K-12 Centers)

• Email

• Username

• FirstName

• LastName

3. Import Procedures

The import procedure enables the creation, updating, and deletion of users. If your CSV has different column names, etc., provide an example to the ggCircuit support team for mapping setup. Alternatively, you can set up the mapping using the API method since there is no current UI for configuration management.

4. Mapping Configuration

4.1 Setting up the Delimiter

The delimiter, the character or string separating values in the CSV file, can be configured. The default is ',', but it can also be set to "auto-detect" (null).

4.2 Mapping Columns from Original CSV to Target Fields

Here is an example configuration for mapping columns: 

{
  "Config": {
    "Mappings": {
      "UniversityUserId": {
        "TargetFieldName": "UniversityUserId",
        "IgnoreField": false,
        "RequireValue": false,
        "SourceHeaderName": "UniversityIdNumber",
        // Other properties specific to the UniversityUserId mapping
      },
      // ... Other mappings for different fields
      
        "MembershipPlaytime": {
        "TargetFieldName": "MembershipPlaytime",
        "IgnoreField": false,
        "RequireValue": false,
        "SourceHeaderName": "Playtime",
        "Formats": null,
        "BooleanValues": null,
        "IsCustomField": false
      },

      "Membership Start Date": {
        "TargetFieldName": "Membership Start Date",
        "IgnoreField": false,
        "RequireValue": false,
        "SourceHeaderName": "MembershipStartDate",
        "Formats": null,
        "BooleanValues": null,
        "IsCustomField": true
      },
      "Membership End Date": {
        "TargetFieldName": "Membership End Date",
        "IgnoreField": false,
        "RequireValue": false,
        "SourceHeaderName": "MembershipEndDate",
        "Formats": null,
        "BooleanValues": null,
        "IsCustomField": true
      },
      "Affiliation": {
        "TargetFieldName": "Affiliation",
        "IgnoreField": false,
        "RequireValue": false,
        "SourceHeaderName": null,
        "Formats": null,
        "BooleanValues": 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"]
  }
}

• "TargetFieldName": The corresponding field in ggLeap.

• "IgnoreField": Indicates whether to ignore this field during the import.

• "RequireValue": Indicates whether a value for this field is required.

• "SourceHeaderName": The column name in the CSV to be imported.

• "IsCustomField":true: Indicates that these fields are custom and allow additional flexibility for importing data.

Note: If a field is marked as a custom field ("IsCustomField": true), ensure to add this field in the user details configuration if it does not exist.

4.3 Deleted Field Configuration

• True: Archives user.

• False: UnArchives the user.

4.4 MembershipPlaytime Configuration

Specifies the Gamepass that will be added to the user during the import.

4.5 Membership Start and End Dates

Configure the Gamepass validity start and end dates.

4.6 Update CSV Import Configuration

• To update the CSV import configuration, use the Update CSV Import Configuration API.

4.7 Get CSV Import Configuration

• To retrieve the CSV import configuration, use the Get CSV Import Configuration API.

4.8 Cancel User Import Job

• To cancel a user import job, use the Cancel User Import Job API.

5. Boolean Values Formatting

Use specific words or characters for true/false values:

• True: Y, T, Yes, True, 1

• False: N, F, No, False, 0

6. Date Formatting

Ensure that dates in the CSV file follow one of these formats:

• yyyy-MM-dd

• dd/MM/yyyy

• MM/dd/yy

• dd.MM.yyyy

7. Mapping Columns from CSV to Target Fields

Map columns from the CSV to target fields with the provided example configuration. Adjustments can be made based on specific CSV structures and requirements.

Other Notes:

Single record import details

• Try to find the user by UniversityIdNumber. The target field is StudentId.

• If not found, try to find the user by EmailAddress (in target center).

• If not found

  • if there is another user with the same email in other center

    • report the conflict, go to next record.

  • if there is another user with the same username in the center

    • report the conflict, go to next record.

  • add new user by specifying all the fields from the import and optionally create a membership gamepass.

• If user is found

  • update all changed fields with those received in the import file

  • before updating Username, make sure it's unique for the center

  • before updating EmailAddress, make sure it's unique for the whole ggLeap user base

  • in case the user is Archived, mark user as deleted

  • in case MembershipStartDate or MembershipPlaytime has changed, update the membership gamepass

    • if new MembershipStartDate is NULL - delete the gamepass

    • otherwise, replace the gamepass total MembershipPlaytime to MembershipPlaytime

• In case any error occured, report it to the import log.

• In case of too many internal errors (e.g. 5+), the import process should be aborted (faulted).

• In case user is added or any changes made to the existing user - report this to the import log.

• Adjust import state/summary ~ each 2-5 seconds.