Table of Contents
Overview
Caveat
Create a Session & Obtain API Token
Generate a CSV File with User Information
Modify & Run Python Script
Creating Users Without Sending a Notification
Related Articles
Overview
Although we typically upload users in bulk via CSV during implementation, if you need to add more users in bulk after you’ve gone live, you may do so by using REST APIs to parse a CSV file.
This process includes three basic steps (each detailed below):
Create a session and obtain an API token for it.
Generate a CSV file with user information.
Modify and run Python script.
Caveat
Before you proceed with these steps, note that if you currently have any users added to your platform, uploading users in bulk via API will overwrite whatever is there.
If you want to preserve existing users (and their assigned roles), you will need to:
GET all of the users.
Add / update.
PUT the users back.
Create a Session & Obtain API Token
Step 1:
Using a tool such as Postman, send a POST request to the sessions endpoint and retrieve the token that is returned.
For Staging: https://staging.coursedog.com/api/v1/sessions
For Production: https://app.coursedog.com/api/v1/sessons
Payload: {"email":"user@example.com","plaintextPassword":"x"}; be sure to replace the information in quotation marks with the actual email address and password for the account you’re using.
Step 2:
Copy the token value that is returned (it will be used within the upload script).
This token will expire after 24 hours and will also expire if the same user logs into the web app.
Generate a CSV File with User Information
Overview
Use the CSV file attached to the bottom of this article as a template for the CSV file you will create with your user information. You will need to use the same set of columns and data formatting.
The CSV can be saved anywhere on your system that the Python script can access (you will pass the file path as a parameter).
Multiple values should be comma-separated.
Required Fields:
First name, last name, email, and a list of accessible products.
Note for products, you will need to list the product key rather than the display name. Available product keys are: scheduling, curriculum, syllabus, events, catalog, courseDemandProjections
- Optional Fields:
You can also specify a unique ID from an external system, a primary department name (under “department”), any secondary departments and one or more role IDs.
There should only be one primary partment listed; if the user belongs to any secondary departments, list those under a “Secondary Departments” header (separated by a comma).
We advise against assigning more than one prebuilt role. Learn more here.
Additional Note
Make sure the listed Role IDs reflect the true Role IDs in your environment and not the “name”.
You can find Role IDs by navigating to Product > Settings > Roles > (Find Role) > Role Settings
Modify & Run Python Script
How to Do It
Step 1: Create a coursedog.properties file, saved in the same location as your Python script, and set the token value using the token you obtained when creating a session. In other words, replace "addme" in the below screenshot with the token.
Step 2:
Use the Python 3 code attached to this article as a starting point for uploading your user data. NOTE: The script attached at the bottom of this article is intended to serve as a starting point; i.e., working code that specifically shows how to invoke the REST APIs for creating and updating users. You can modify it for your own needs.
Modify the ENDPOINT constant to reference the environment to which you are uploading.
For Staging: ENDPOINT = STAGING_ENDPOINT
For Production: ENDPOINT = PROD_ENDPOINT
Step 3:
Use a command prompt to run the Python script and import your CSV.
Create_users.py
Add the name of the CSV after “create_users.py”, e.g. create_users.py example_users.csv
Specify the “School Unique ID” of the environment this update applies to. A super admin at your institution can find this at Admin > Settings.
The final prompt should follow this formula, with the CSV name and School Unique ID modified to match your CSV file name and School Unique ID:
create_users.py example_users.csv SchoolUniqueID
If you created the CSV file in another location, e.g. a temp directory, the command would look something like:
create_users.py /tmp/user_snapshot_9_1_23.csv peoplesoft_example
Step 4:
Hit “Enter” to parse the CSV file.
It will read one row at a time, first attempting to create a new user, who will receive a registration email/request to set an initial password.
If a user with that email address already exists, it attempts to update that user with the latest information. It will then report back on the number of users successfully created and updated.
If you wish to prevent this notification from being sent, see “Creating Users Without Sending a Notification” below.
Additional Notes
The script assumes the requests package has been installed (pip install requests).
You can make changes in bulk following a similar process; however, when you run the same “Create Users” script again, it will detect the users already exist and will run an update.
Creating Users Without Sending a Notification
If you wish to create users via this method without them receiving a notification email, you can do so by changing disableRegistrationMail (under “Payload” in the Python script) to “True”.
