Data Imports - Object: Users

Introduction

This article covers the bulk import of users from a file, one-time or on a scheduled basis. The main Data Imports - An Overview article should also be reviewed for information on importing data to SkillSync in general.

Users in SkillSync can represent learners, instructors, administrators, reporters, course authors, etc - essentially any person or (sometimes) application that needs to interact with SkillSync in some way, for the purposes of tracking their permission and activity in the LMS. See this article for more information about Users. For the purposes of this article, we'll assume that you are already familiar with creating and managing users manually in SkillSync through the admin portal.

Just looking for information on our self-service User Import tool? Click here. 

Quick Start

There are quite a few options available for processing users, but here are the minimum pieces of input that we'll need from you in order to set things up:

• Sample file (see Preparing the File below)
• Column Mappings
• Unique Identifier (Also used for Supervisor lookup unless otherwise specified)
• Department Lookup
• Fallback Department
• Password Management

Additionally, if admins are being provided:

• Admin Handling
• Default Admin Role
• Default User Management
• User Management Records To Process

Preparing the File

Ensure you've downloaded the most recent SkillSync Data Mapping document from this helpdesk article. Refer to the Users tab for a list of fields that can be included, including the minimum required fields and any dependencies. Once your file is created, please take a moment to validate the content by considering the items noted here.

Configuration

In addition to the generic configuration options available to all modules, the following configuration options are available for Users (mandatory marked with *):

Column Mappings

The Data Imports - Configuration article covers column mapping in general. You will need to specify which SkillSync fields should be mapped to each column in the file based on column headers (e.g. The column with header "EID" should be mapped to the SkillSync "External ID" field). The following fields/columns are mandatory for Users:

• Username
• Email Address (optional if not used as unique identifier)
• FirstName
• LastName
• Password (only if assigning password from file)
• Department
• ExternalId (optional if not used as unique identifier)

There are a few columns with special considerations:

Role Assignment
This will assign the specified admin Role to this user, assuming their admin flag is true. The name of the desired role should be included in this column (must be unique - assignment will fail if multiple roles with the same name are found in SkillSync). Note that any configured Default Admin Role or Default Instructor Role will also be applied on top of this. If "Skip assignment if other roles are present" is enabled, it will apply to roles assigned from this column as well.

Custom Fields
Custom fields should be setup in SkillSync under Portal Settings before configuring the testing the import. Provide us with the column names in your file and the names of your custom fields that they map to.

Field Mappings
Some fields will only accept certain values. For example the IsAdmin field accepts a 0 if the user is not an admin, and a 1 if they are an admin. If your file has something different, for example Yes and No instead of 0 and 1, you will need to let us know the mappings for those field values. Some common fields to request these field value mappings are:

• IsLearner, IsAdmin, & IsInstructor: We accept 0 & 1, but often clients will provide other values like Yes or No.
• Province/State or Country: We accept the fully spelled out Province/States name (e.g. Alabama) or two-letter province/state codes for Canada and United States (e.g. AL). We accept the two or three letter ISO country codes (e.g. US or USA). Often clients will want to provide different representations of these values (e.g. U.S.A. instead of US). 

Processing

Correlation Properties

Unique Identifier*
This property will be used to uniquely identify the record for the purposes of updating existing records (i.e. the key). Options available:

• Username
• External ID*
• Email*
• Employee Number*

*SkillSync does not enforce uniqueness on these fields, but the import will require a unique match in order to successfully process. Duplicate matches for a unique identifier will result in skipped records. Username is sometimes the best option because of this.

Department Lookup*
This property will be used to look up and assign the user's department (e.g. Bob belongs to the HR department). Note that departments should either be setup ahead of time through the admin portal or imported with your users (see Related Objects section). Options available:

• External ID (recommended)
• Name

Fallback Department
Specifies the department to assign users to when the department defined in the import file is invalid. If this department does not already exist, it will be created underneath the very top level department (for this reason, it's usually best to pre-create it). Keep your admin permissions in mind here; it's sometimes safest to create the fallback department near the bottom of your hierarchy to avoid inadvertently granting admin permissions over a large portion of your department tree. Options available:

• None (default; users are not created if the department is invalid)
• Specific department external ID
• Specific department name (must be unique)
• Top Level Department

A common example would be creating a department called "Unknown" and defining it as the fallback department for the users import. Users with invalid departments in the import file are still created and can login, but they belong to "Unknown" until they are updated to a valid department. The correction can be made manually through the admin portal or by sending across updated records in subsequent user import files.

Note: If the import applies certain Admin / User Management settings, they will still be applied if a user is added to the Fallback Department. This could lead to an admin having User Management over the Fallback Department itself, depending on your settings. Consider not using a Fallback Department if this is a concern, so that users are simply not created without a valid department. 

Supervisor Lookup
This property will be used to look up and assign the user's supervisor (assuming that column has been provided). The default is whatever Unique Identifier is chosen for your user records, but the Unique Identifier and Supervisor Lookup can be different. Options available:

• Username (the supervisor's)
• External ID (the supervisor's)
• Email (the supervisor's)
• Employee Number (the supervisor's)

Admin & Roles

Admin Handling*
This option defines how the Admin flag (whatever column is mapped to IsAdmin) is set when processing the file. Options available:

• File values
  The admin status for each user will be set based on whatever is provided in the file. Manual changes in SkillSync can be overwritten by whatever is in the file.
• File values for new users only
  The import will not change admin status for an existing user. The admin status for new users created by the import will be based on the file. This is a good option if the majority of admins are being set correctly by your file, but some manual edits in SkillSync are desired.
• Existing admins remain as admin
  The import will not disable admin status for an existing user. The admin status for each user will be set based on whatever is provided in the file except for existing admin users. This is a good option if you know you need to manually turn on admin status in SkillSync for some users, and don't want the import to overwrite those changes. Existing non-admins can still be switched to admins by the import.
  
• Existing non-admins remain as non-admin
  The import will not enable admin status for an existing user. The admin status for each user will be set based on whatever is provided in the file except for existing non-admin users. This is a good option if you know you need to manually turn off admin status in SkillSync for some users, and don't want the import to overwrite those changes. Existing admins can still be switched to non-admins by the import.
  
• Existing admins with specific role(s) remain as admin
  The import will not disable admin status for existing users with exactly this set of roles. The admin status for each user will be set based on whatever is provided in the file for all other users. This is a good option if you know you need to manually manage admin status for a certain set of users, by effectively excluding them from updates based on role assignment.
• Existing admins without specific role(s) remain as admin
  The import will not disable admin status for existing users with exactly this set of roles. The admin status for each user will be set based on whatever is provided in the file for all other users. This is a good option if you only have one default role being used by the import, for which you want the admin status to be governed by the import. Assigning users other roles effectively excludes them from admin status updates by the import, allowing you to manage them manually.
  

Default Admin Role
Defines the Role assigned each time admin status is assigned by the import file. Not enabled by default.

Default Instructor Role
Defines the Role assigned to users with both instructor and admin status assigned by the import file. Note that instructor status (IsInstructor) can be assigned without also assigning a role. Not enabled by default.

Skip assignment if other roles are present
Optionally, skip assigning the default Admin and/or Instructor roles if an existing admin already has other roles assigned. Not enabled by default.

Force Supervisor Admin Status
Users must have admin status in order to be assigned as Supervisors. If this option is disabled (default), and a non-admin is assigned as a supervisor in the import file, supervisor assignment in SkillSync will fail. With this option enabled, the import will forcefully make the supervisor an admin in order to allow their assignment as a supervisor to go through. When forcing admin status for supervisors, the following options are available:

• Apply Role & User Management Settings: Give the supervisor whatever default role and user management settings are defined for the import.
• No Role or User Management Settings: Although admin status is assigned, no Role or User Management settings are applied. This leaves the supervisor with extremely limited admin access until it is assigned manually or by a subsequent import.

Note: This option overrides any exclusions chosen as part of Admin Handling above.

User Management  

Note that more advanced User Management setups may require separate Department Admin and/or Group Admin files (refer to the SkillSync Data Mapping document from this helpdesk article for more information on these).

Default User Management*
Defines the type of User Management that will be applied each time admin status is assigned by the import file. It's usually best to setup & test a few examples manually through the admin portal before choosing an option to be applied in bulk by the import. Options available:

• None (Default)
  New users are given the LMS default, which is 'All'. Existing users do not have their user management settings updated.
  
  
• All admin
  No restriction on which users the admin can see.
  
  
• Department admin
  The admin can only see users in the department they themselves belong to. Additional sub-options:
  
  Include Sub-Departments: The admin can see users in their own department plus users in any sub-departments.
  
  Reset Department List: If enabled, the admin will only be set to manage the department they currently belong to. Any additional departments that are manually assigned will also be removed on import. If disabled, the import will simply add their currently assigned department to the list of existing departments managed (i.e. if they move departments, they will still manage the old one in addition to the new one).
  
  Exclude existing All Admins: Admins already setup to manage 'All' will not be assigned the default Department Admin settings.
  
  Exclude existing Department Admins: Admins already setup to manage other departments will not be assigned the default Department Admin settings.
  
  
• Group admin
  The admin can only see users in a specific group. The group is automatically created and assigned to the admin if it does not already exist. Additional sub-options:
  
  Group Name Mapping: When a group is created, it is named using a value from the associated admin profile. The fields available to pull this value from are Username, External ID, Employee Number, Email, First Name, Last Name, FirstName.Lastname, or whatever is the currently configured Unique Identifier for the user import. 
  e.g. If Username is chosen, and the admin's username is JDoe, the group created for that admin will be JDoe.
  
  Group External ID Mapping: When a group is created, its External ID is set using a value from the associated admin profile. The fields available to pull this value from are Username, External ID, Employee Number, Email, First Name, Last Name, FirstName.Lastname, or whatever is the currently configured Unique Identifier for the user import. 
  e.g. If Username is chosen, and the admin's username is JDoe, the group created for that admin will have an External ID value of JDoe.
  
  Automatic Groups: If disabled, the user import will not handle adding or removing users from the groups created by the user import (Behavior=Manual). This will need to be done manually or by providing a separate Group Assignments file. If enabled, the group's Behavior will be set to Automatic and rules will be added to keep the list of users inside the group up to date. The rules should be structured like: User Field (any text field supported in group rules)  |  Starts With / Contains / Equals / Ends With  |  Admin Field Value (any text field from the admin's profile).
  e.g. Custom Field 1 | Contains | External ID  > This would result in a group with a rule that checks for any users whose Custom Field 1 contains this particular admin's External ID. This can be useful in creating supervisor-based user management models.
  
  Exclude existing All Admins: Admins already setup to manage 'All' will not be assigned the default Group Admin settings.
  
  Exclude existing Group Admins: Admins already setup to manage other groups will not be assigned the default Group Admin settings.
  

Note that for both default Department Admin and default Group Admin settings above, an existing Group Admin will not be overwritten by the default Department Admin setting and vice versa. In other words, the Default User Management settings will not switch existing users between Department and Group admin types. 

User Management Records to Process*
Defines which types of records have User Management settings applied to them:

• All records
• Only new users
• Only existing users

User Management Exclusion Rules
If set, users with or without specific roles can be excluded from default User Management settings. This is particularly useful for excluding users with the System Admin role, since those users should generally not have restricted access. Not enabled by default.

Manager & Manager Roles 

Manager handling

Independently from Admin User Management, Users can be set to manage users; these users are called Direct Reports. The following rules are in place for Managers:

• Users can only have one manager assigned at a time.
• Manager relationships cannot be configured such that they contain circular references.

The following fields are required to configure a manager relationship:

• Manager Unique Identifier
• Direct Report Unique Identifier
• Manager Role

Note: Multiple Manager Roles can be assigned.

The following fields can be used as the unique Identifier for Managers and Direct Reports:

• Username
• ExternalID
• Email Address
• Employee Number
• ID

Each line in the file represents one Manager – User relationship.

Sample Data Format:

Manager_Username, Direct_Report_Username, Manager_Role

Sample Data:

John.Smith, Jack.Miller, Manager

More  

Password Management*
Defines how passwords are initially set and updated. Keep in mind that the "Force New Learner Password Change" option in Portal Settings will still further apply once the user logs in for the first time. The following options are available for the import:

• New users only - from file: New user passwords will be set based on the provided password column. Existing users will not have their password overwritten.
• New users only - random password: New user passwords will be randomly generated. This option should be used when users don't need to know their initial password up front, usually because they are using Single Sign-On or because they are setting their password using a link in the welcome email. Existing users will not have their password overwritten.

Department Updates
By default the import will assign a user to whatever department is specified in the file, however the import can optionally skip updating the department for existing users.

Deactivate by Date Terminated
By default, the Date Terminated field is used for reporting & reference only. Optionally, the import can automatically deactivate users based on their Date Terminated value. Note that this deactivation will only occur if the user is provided in the import file (simply populating the field in SkillSync manually will not trigger any kind of automatic deactivation). Options available:

• Date Terminated is present
• Date Terminated is on or after today
• Date Terminated is on or after yesterday
• Date Terminated is on or after a specific date value
• Date Terminated is on or before a specific date value

Related Objects

Users are an incredibly important object in SkillSync, with a large list of related objects. The following list of objects are often imported alongside users:

Departments
Enrollments
Department Admins
Group Admins
Group Assignments

Refer to the SkillSync Data Mapping document from this helpdesk article for more information on the objects above.

Emails to Users

It's very important to discuss and identify which emails (if any) you would like to go out to your users upon import. When a user is created via a data import, SkillSync will trigger whatever emails are configured for your portal. By default the New User (welcome) email is enabled, but it's possible that other emails such as enrollment notifications will go out depending on your LMS configuration.

If you do not want emails to go out as part of the initial user import (usually from a previous LMS), it's important that emails are temporarily disabled through the admin interface prior to importing users.

Data Examples

Spreadsheet

 

Text

Username,Password,FirstName,LastName,ActiveStatus,Department_ExternalId,ExternalId,IsAdmin,IsLearner,EmailAddress,CustomField,Supervisor_ExternalId
[e-mail],Password5467,John,Doe,0,00002,100012,1,1,[e-mail],Custom Value,
[e-mail],Password5812,Jane,Doe,0,00002,100013,0,1,[e-mail],Custom Value 2,100012