Environment: Import Learners
Summary: Importing or exporting learners to the Security Awareness training account using CSV files.
Formatting CSV Files
The easiest way to format a CSV file is to download a starter template from the portal. To do this navigate to the “Learners” section using the top navigation bar, click the “Import & Sync” button then click the “Download a starter template” button.
When preparing your CSV file, it is important that you follow two formatting requirements.
- You will need to create an Email column in your CSV file. Email is the only field Security Awareness Training requires of CSV files; without it, any attempt to import data will fail. When you import your learners’ email addresses, the Security Awareness Training platform will automatically create a corresponding learner in the system.
- Make sure to use proper column labels for the data in your CSV file. Although Security Awareness Training only requires an Email field, including additional fields of data will save you some legwork on the back end as you manage learners and run detailed reports.
- First names of your learners — firstname
- Last names of your learners — lastname
- Learner status (Active or Inactive) — status
- Departments — department
- Tags — cltag_[tag slug]
- Employee ID numbers — employee_id
You can always add this information once your learners are in the platform if you prefer, but including it in your CSV file will spare you the tedium of updating this data individually for your learners.
Here’s an example of a properly formatted CSV file:
(NOTE: If you would prefer building your CSV file from a pre-programmed template before importing, the Security Awareness Training platform can generate one for you. See the Exporting CSV Files section below for instructions.)
Importing CSV Files
Once you complete your CSV file, you will be ready to import your learners into Security Awareness Training's platform.
Go to the admin portal. On the left-hand side of the Learners tab, click 'Import & Sync.'
You will now be taken to the selected group’s (with the default of “Staff” automatically created in all accounts) group settings. By default, the Sync Type will be set to “Standard / CSV File”. If you see one of the other options selected such as Microsoft Graph, then you can switch to CSV import by changing the ‘Type’ and hitting update.
(NOTE: Once learners are in the platform you can easily sort them into the appropriate groups from the Learner’s tab. Check the boxes beside the learners you need to move. A dropdown entitled Change Group will appear. Select the target group from the drop-down list for these learners and they will be transferred immediately.)
If you have not already done so, download a starter template here and create your properly formatted csv file to import.
Next, click the “Choose file” button to select your CSV file. Once your file is selected and uploaded, click the “Preview & Sync” button to preview the changes before approving them.
You will now see a Preview of the changes proposed along with summary statistics on what actions would be performed if you were to click “Apply Manual Sync”.
It is important to pay attention to these fields:
- Would Fail: These rows have errors and would not be processed. For more detail, click on “Log” and look for the lines marked in red starting with “failed”
- Would Create: the number of completely new learners to be added in this import
- Would Update: the number of existing learners that have updates to fields like first name or department
- Would Be Unchanged: Learners that exist and would be completely unimpacted by the sync
Clicking on “Log” shows details of how each row of your CSV was processed including which learners failed due to formatting issues, which learner already exists but has fields that would be updated, and which learners would be created.
You can now either Cancel the change or Apply Manual Sync.
The newly imported learners will appear in the Learners tab, sorted under the group you selected.
If you are attempting to upload a CSV but are running into issues…Three things you should do:
- Download the Starter Template noted above and double-check your formatting.
- Re-read column heads and learner data for any spelling errors.
- Create a new version of the file and try to re-upload.