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. 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 updating existing learners, see our Updating Existing 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 Assign Access to a List of Learners
- From your homepage, select Users > Learners.
- At the top of the page, click the blue gear icon.
- In the dropdown, select Bulk Import Learners.
- Click Download CSV Template.
- Open the downloaded CSV and enter information for each learner (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.
- Click That Looks Good to complete the import. Learners will receive an email invitation to join the site.
Tips for Import
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
Invitation Expiration
Learner invitations do not expire. If you would like to revoke the invitation, disable the user and the invitation will no longer be valid.
Invitation Branding
The email invitation will match client (Panorama) branding, if a client is specified in the bulk import.
Vaild Emails
If sendInvite has a positive value, each learner will receive an email invitation to the learning site, so it's important to use a valid email address for each learner.
When each learner accepts the invite, they will be prompted to generate a unique password for future logins and agree to terms and conditions before proceeding to the learner dashboard.
Import Queue
Check if files are queued by going back to the Bulk Import page (Users > Learners > 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
Choosing Whether or Not to Send Email Invitations to Learners
- Using the sendInvite Field If set to "True", the platform will send an email invitation to the learner.
- Use any of the following case-insensitive sendInvite values include y, n, t, f, yes, no, true, false.
- An empty field defaults to "False".
- If the learner already exists, no invitation will be sent (regardless of what is specified in the sendInvite column).
Importing Learners Without Assigning Any Content (No content access)
- Imported learners will simply become part of the Registrant role.
- Importing existing learners without selecting content will result in no change to content access.
How to Import a Learner's Language Preference in Multilingual Package
- 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.
Single Sign On / SSO
If you plan to use SSO, the customerID column should be populated, otherwise you run the risk of duplicating users later on. We recommend adding an external ID if you are using SSO or planning to use SSO in the future. For more information, reach out to your CSM.
How to Specify Salesforce IDs in Salesforce-Specific Fields of the Bulk Import Template
When importing new learners:
- If sfContactId is provided and valid, the learner will be connected to the contactId and corresponding accountId in Salesforce. The account is derived from the contact in Salesforce, not the sfAccountId field on the bulk import template.
- If sfAccountId is provided and valid OR sfContactId is invalid, the learner will be created as a new contact in Salesforce, connected to the specified sfAccountId.
- If neither sfAccountId nor sfContactId are provided OR if both are invalid, the learner will be created as a new contact in Salesforce and the account will be connected based on an email address domain lookup in Salesforce for the best account match.
Warning
When using the Salesforce fields, the records cannot be updated once the records are set for the learner in Thought Industries.
Using Bulk Import to Import or Update a Learner's Content Status
- Valid case-insensitive status values include: not-started, not started, notstarted, started, completed, complete.
- Empty fields default to not-started for new learners. Course, webinar, article, video, and single SCO content status can be updated.
- Content status updates can not be applied for learning paths, subscriptions, and client access.
- 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.
Webinars
- Not-started and started statuses will add learners to the registration list on both Thought Industries and the webinar provider's interface.
- Completed statuses will not add learners to the registration list on either Thought Industries and webinar provider's interface.
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: