Before you start
- The CSV Importer is for bulk uploading users into an instance (GAN platform); if you solely wish to add, update, or archive a singular user then it is more time-efficient to do this via the user interface (UI) of the GAN platform.
- Access and gather your company employee data in an exportable data format (eg. spreadsheet).
- Ensure all email addresses are in lowercase as your users may otherwise encounter access issues.
- Verify that special characters (e.g. Æ,Ö,Ã,Ś,Û) appear correctly in your CSV file - Save CSV with UTF-8 encoding, so these characters appear the way they are supposed to in the GAN platform.
- Ensure to download the CSV template unique to your instance.
- Employee (user data) can be uploaded by a user with the Identity Manager role.
- Confirm that the data contained in the CSV file is reflective of the import action i.e. ADD, UPDATE, REPLACE, or ARCHIVE.
- Confirm there are no duplicate user accounts.
DISCLAIMER: Provided client data in correct formatting of the CSV template is very important. If the template is not formatted correctly, the upload will fail or result in user errors.
What upload types (and templates) are available to import and manage employees in the GAN Platform?
All employee account uploads (and edits for ongoing user management) are completed from the Employees tab in the left sidebar followed by Import Employees.
Employee uploads are segregated into 4 types of import actions:
- Add Employees
- Update Employees Information
- Replace Employee List
- Archive Employees
Add Employees
This type of import allows you to add multiple new accounts to the system using one CSV.
Note: With an ADD, the user account (id's and email addresses) must be unknown to the system, otherwise the upload will fail to process i.e. only new user accounts can be added to the GAN platform, which is to safeguard against duplicates.
Update Employee Information
This type of import allows you to update existing account information for multiple accounts, using one CSV.
Note: With an UPDATE, all user accounts must exist in the system, otherwise the upload will fail to process i.e. users are known to the GAN Platform are able to be corrected with new information ( e.g. new email address)
Archive Employees
This type of import allows you to restrict employees to access the GAN platform. When an account is Archived it means the employee will not be able to access the platform.
Note: With an ARCHIVE, the column header of id in a CSV file is sufficient to accomplish this import action. Once users are archived, they will lose access to the GAN platform.
Replace (entire) Employee List
This type of import replaces all your employee data (replaces all your users) with the data contained in the CSV file.
Note: With a REPLACE, the actions of ADD, UPDATE, and ARCHIVE are carried out simultaneously. When carrying out a REPLACE, it's crucial that you validate the data fields you are about to upload as the data is permanently overwritten. Before carrying out a REPLACE, it is suggested to export any existing user data from the Employee Table.
Method
When preparing your CSV file, there are column headers with mandatory fields (System Attributes) that are critical in the platform. There are also columns that could have optional fields, where data can be included at your discretion. Last but not least with Custom Attributes, there could be a combination of mandatory as well as optional fields, which will depend on your attribute configuration. Unless marked as required, custom attributes are optional to form a part of the CSV user import process.
1. A user with the Compliance Manager or Identity Manager role needs to Download the CSV template from your instance of the GAN Platform. The template includes all attributes, irrespective of whether they are mandatory system attributes or required/optional custom attributes.
2. Optionally, a user with the Compliance Manager role is able to validate if Custom Attributes are required or not, which is found under the Attribute Settings menu from the Employee table. If the attribute is required then the associated data fields must contain data content; blank fields may replace data content that should be valid.
3. Add your employee data following the column headers in the template.
4. Do remember to remove the John Doe example in row 2 from your template.
5. In order for the upload of users to be processed by the platform, the CSV column headers and data fields must be formatted correctly, which can be ensured by Validating the CSV file.
Formatting the CSV File
- The column headers are both case- and space-sensitive (i.e. an exact match is required between the CSV template and technical requirements imposed by the platform).
- Confirm there are no duplicate user accounts.
- Furthermore, the columns, as well as associated data fields, must be separated by commas (,).
- The CSV File must be saved with UTF-8 encoding.
- Save the file name with a reference-able naming convention for your own records, where we suggest the type of import action as well as the date of uploading the file into the GAN platform.
Mandatory (System Attributes) columns & data fields for CSV import
The column headers (exact name of the attribute), as well as its associated data fields, must be included in the CSV file otherwise, the import will fail.
Mandatory Column Header | Description | Example |
id | this field will be the Username or Email depending on the configuration |
employee1@company.com or 000dEf456 |
employee’s email address (lowercased email address of the user) |
employee1@company.com |
|
username |
chosen by the client (GAN suggests a data field that will not change over time like an Employee ID) |
AbC123 or employee2@company.com |
firstName |
employee's first name |
Forename or Given Name |
lastName |
employee's last name | Surname or Family Name |
attributes.External ID |
usually determined by the system hosting employee information at the client (e.g. an HR system with a unique identifier associated to each employee). This field needs to be a data field that will not change over time as it is a user attribute used to map employees in a configuration Note: It is MANDATORY to use a Unique Nonchanging Identifier in this field (one from your internal HR system or provided elsewhere in your business). In case the client can not provide a unique ID, the employee email (e.g. employee1@company.com) could be used instead. IMPORTANT: If the client chooses the employee email option and the emails change (e.g. due to last name change) it could create duplicate accounts within the GAN platform that might lead to login issues, data access loss on one of the duplicate accounts and affect reporting. |
000dEf456 |
Note: Employee id's with leading zeros (i.e. 0s like 000dEf456) may be removed in Excel, so we recommend using a text editor to ensure leading zeros are retained.
Configuration specific: Required Custom attributes are Mandatory for CSV Import
The column headers (exact name of the required custom attribute), as well as its associated data fields (e.g. required options), must be included in the CSV file otherwise, the import will fail.
Custom attributes can be configured on a client instance to capture any additional data that should be part of a user profile. A non-exhaustive list of examples includes Department, Country, Date of Employment, etc. A user with the Compliance Manager role can determine whether a Custom attribute is required or not; if the custom attribute is marked as required then the associated column, as well as data fields, are mandatory for the CSV Import.
- custom attribute name: custom attributes are data fields that the customer would like to retain in the GAN system. If marked as required in the user interface (UI) of the platform then the column headers for attributes.Custom is mandatory for the CSV Import.
Optional (System Attributes) columns & data fields for CSV import
The column headers (exact name of the required custom attribute), as well as its associated data fields (e.g. required options), must be included in the CSV file otherwise, the import will fail.
- status: this field is generally used to unarchive users and should not form a part of your continuous import schedule. Please see table summary below:
Status | CSV "status" column |
Can be updated to |
PENDING | PENDING accounts can only be set to archived | ARCHIVED |
ACTIVE | ACTIVE accounts can be set to archived or left as active |
ACTIVE ARCHIVED |
ARCHIVED | ARCHIVED accounts can only be set to pendingActivation |
PENDING ARCHIVED |
Note: if an account is ARCHIVED or PENDING you can only set the status to pendingActivation
- roles: this field is used to bulk assign roles to users; if you want to assign more than one role to an account the roles must be separated by a forward slash ( / ). Generally speaking, this is done during the first import of users into an instance. Adding roles via a CSV Import should only be used to facilitate bulk add/update of roles. Ongoing management of roles should be done via the UI of the platform.
Want to know more?
Suggested next read: How to import employee data in your CSV file into the GAN platform?
Questions are always welcome
Contact us through your GAN Solution Delivery Manager, GAN Relationship Manager, or GAN Support.
© 2022 GAN INTEGRITY INC. ALL RIGHTS RESERVED | The information contained in this document is solely for the intended recipient and may not be used, published, or redistributed without the prior written consent of GAN INTEGRITY INC. While every care has been taken in preparing this document, GAN INTEGRITY INC. reserves the right to revise its contents without prior notice.