Bulk import allows you to assign the same access to a list of learners with a simple upload vias a CSV file.
Use Case Information
The bulk import functionality is an alternative to individually adding or updating learners in your instance one-by-one. You can also bulk upload via API but this will require developer support. Understanding the options for Bulk upload will allow you to do the following:
- Add learners to your system and create user records in bulk
- Update Learner details in bulk
- Provision content in bulk
- Update content status such as Started or Completed in bulk
Note
For information on importing new learners, see our Importing New Learners in Bulk article.
File Format
To import new learners to the platform, you will use our standard import template. In addition to basic learner information, our import template contains the following columns:
| Field/Value | Description |
| firstName (Required) | Learner's first name |
| lastName (Required) | Learner's last name |
| email (Required) | Learner's email address |
| externalCustomerId | Used as identifiers for SSO. This field matches the unique identifier (nameID) in the IdP. |
| status | Update learner status on specified content as not-started, started completed, or not-completed |
| completionDate |
Record a completion date for specific content For record creation only, not updates. No completion date should have been previously recorded for the learner/content combination. |
| sendInvite | To control whether or not an invite should be sent to a learner, enter yes or no |
| ref1-ref10 | Create or update learner reference fields |
| address1, address2, city, state, zipCode, country, telephone | Learner's address information |
| language | Will only appear if Thought Industries' Multilingual Package is enabled in your instance and used to update a learner's language preference |
| sfContactId |
Connect new learners to an existing contact record in Salesforce, used in relation to Salesforce Managed Package |
| sfAccountId |
Connect new learners to an existing account in Salesforce, used in relation to Salesforce Managed Package |
| balance, balanceAdd |
Used in relation to Training Credits |
How to Update Existing Learners in Bulk
- From your homepage, select Users.
- From the left menu, select Learners.
- At the top of the page, click the blue gear icon.
- Click Bulk Import Learners.
- Click Download CSV Template.
- Open the downloaded CSV and revise the learner information, as needed (one row per unique learner).
- Save CSV.
- Next, go back to the platform and click I've Downloaded and Filled in the Template.
- Click Choose File and locate your saved CSV file. Click Open.
- Specify what content the learner should have access to by adding the content, subscription, Learning Path or client/Panorama access that will be applicable to all learners in the import batch (whether applicable for status or access).
- Complete the Invite Message field to send a customized invitation (optional).
- Click Next Step.
- Review your import. If there are issues with your CSV, you'll be notified of the specific errors and have the option to correct the errors or upload the successful rows.
- If needed, correct your errors, then click Let me try uploading again, then repeat this step to review the import. If there are no errors in your CSV, the confirmation page will summarize all learners who will be imported.
- If needed, correct your errors, then click Let me try uploading again, then repeat this step to review the import. If there are no errors in your CSV, the confirmation page will summarize all learners who will be imported.
- ClickThat Looks Good to complete the import.
Notes, Tips, and Considerations
Learner Invitation
A learner invitation must include firstName, lastName, and email fields, which are used as learner identifiers for bulk imports in order to add or update the correct learner.
Feature Enablement
Feature-specific fields appear in the bulk import template only when you have specific features enabled on your instance. For example, the Salesforce field column of external customerID won’t show up on the bulk import template unless you have it enabled or integrated on your instance. Training credits also need to be enabled on the instance for that value to appear on the bulk import template.
Row Limit
There is a limit of 1000 rows for bulk import CSV files.
Row Names
Do not rename any fields in the file format CSV.
Assigning Content
Ensure the content you assign is correct since content access can only be removed individually from learners.
Date Format
All dates should be formatted in ISO Date & Time.
- Format structure: YYYY-MM-DDTHH:mm:ss.SSSZ
- Example: 2021-02-01T15:30:00.000Z
Import Queue
Check if files are queued by going back to the Bulk Import page (Users > Learners > Blue gear Icon > Bulk Import Learners). Bulk updates are not immediate and there will be a completion delay depending on the size of the imported CSV.
Special Considerations
Updating Content Access for Existing Learners
The following content items are available to add to learner access through the bulk import:
- Courses
- Webinars/VILTs
- Articles Video
- Single SCO content
The following cannot be updated through the bulk import:
- Learning paths
- Subscriptions
- Client/Panorama access (See more in the Managing Learners in Panorama article
- Existing access will not be removed through granting additional access.
- Learner details will not be changed.
- No invitations are sent to existing learners.
Updating the Content Status of Existing Learners
Use bulk import to update learners' content status to reflect the content status of the following
- Not Started
- Started
- Not-Complete
- Completed
If the learner already has access to content, then only the content status will be updated in the bulk import update.
Note
The Reset Course Progress endpoint, in the Thought Industries API, allows you to reset progress for a specific learner and a specific course. It accepts an email address, externCustomerID, or UUID as a learner identifier. courseId, courseSlug or courseSku must also be specified. Resetting progress will delete all assignments and assessment attempts. If revokeAccess is set to true, learner access to the content item is also revoked. (API doc can be found here.)
Tip
If a content status is not specified in the bulk import, there will be no change to content status. Previously-accessed content will not update to not-started, even though that is the default content status.
Note
The completion date can only be utilized if the learner hasn't already recorded a completion date for the selected piece of content - it's meant to create a completion date record (not to update a record).
If the user has no recorded completion date for a piece of content, you can set a date manually using the bulk import process by filling out the status column as 'completed' and using ISO date format for the completed date. Select the content that should get the new completion date during the bulk import process.
How to Import a Learner's Language Preference in Multilingual Package
Use bulk import to update learners' content status to reflect the content status of the following
Valid language values include any available language key, defined as a two-character reference to Languages (default and custom) in the Translations area of the platform. Language keys can be found at the end of the URL when on the tab of the desired language in the Translations area of the platform. You may import one preferred language per learner.
Note
When you use bulk import API endpoints that accept an asset property, the URL you provide must be accessible by our system. For sensitive information stored in a cloud-hosted document like a CSV, the URL could be made public for a short time (~10-30 minutes) and back to private once the job is complete.
If your setup allows, you could transform the private URL to a presigned and tokenized URL specifically for our use with a short expiration timespan and provide that in the call to our API. Bulk imports for users and content are handled in a queue; the required time for us to access and read the data may vary on our end based on pending jobs.
More info on presigned URLs of popular cloud services: