What is roles.csv?
The roles.csv file allows System Administrators to assign, update, or remove user roles across Watermark products in bulk. This file must be used alongside people.csv, which only creates or updates user records, not their permissions.
roles.csv Format Requirements
Each row in the roles.csv must include the following fields:
- person_id – Unique identifier for each user (from SIS). Not case-sensitive.
- product – The product the role applies to. Accepted values (any casing): PSS, SLL, IH.
-
roles – The role(s) to assign, or none to remove all roles for that user/product.
- Use a pipe (|) to separate multiple roles (when allowed).
Valid Roles per Product
| Product | Accepted Roles |
|---|---|
| PSS (Planning & Self Study) | Administrator, Contributor |
| SLL (Student Learning & Licensure) | Administrator, Faculty, Student (only one role allowed per user) |
| IH (Insights Hub) | Administrator, Contributor |
| (all) | none (removes all roles for the product for that user) |
Note: Users must already exist in the system via a people.csv import before you can assign them roles in roles.csv.
Example
Scenario: A university needs to update roles for faculty and students in their system.
Previous Method (Using people.csv):
- Importing people.csv with updated roles caused errors due to the inability to overwrite or remove existing roles.
New Method (Using roles.csv):
- Import people.csv to ensure all users exist in the system.
- Import roles.csv to update or remove roles as needed.
Sample roles.csv Format:
- Each row represents one product per user, ensuring proper role management.
- Marking none in the roles column removes all product roles for that user, effectively revoking their access.
Visual Example: How to Import and Export the roles.csv in System Admin
Above image shows how to import roles in System Admin and where to download the roles.csv template.
Above image shows how to export roles. Only Users with roles will be included in the export.
Preparing for the Change
To ensure a smooth transition:
- Begin using roles.csv
- Update any automated ZIP or API-based imports to include roles.csv for all future role assignments.
- Remove reliance on roles within the people.csv file.
We will provide additional notice as the roles column is officially deprecated in people.csv. Early adoption of roles.csv will prevent disruptions to your import processes and support a cleaner, more maintainable role structure.
For more detailed instructions, please see CSV Import Guidelines.
Pro Tips for Using Roles.csv
- Export People.csv first: Use the People.csv export to find Person IDs for users you want to update.
-
Use Specified Formatting:
- Multiple roles must use the pipe (|) delimiter.
- For a product allowing only one role, ensure only one valid role is listed.
- Review Validation Errors: Errors provide row-specific feedback to help you correct issues quickly.