Managing User Role in Bulk with roles.csv

Upcoming Change to people.csv (Anticipated for a July 15, 2025 release)

To support more accurate and flexible role management, Watermark will be removing the roles column from the people.csv file in a future release.

All clients who wish to assign or update Watermark roles via CSV, ZIP, or API must transition to using the dedicated roles.csv file going forward.

The roles.csv file provides enhanced functionality that not only supports assigning roles, but also accurately updates or removes them. Unlike the people.csv, which only allows additive actions, roles.csv reflects the true current state of each user’s roles for a given product—ensuring consistency, reducing errors, and enabling full control of user access.

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

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):

1. Import people.csv to ensure all users exist in the system.
2. 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

1. Export People.csv first: Use the People.csv export to find Person IDs for users you want to update.
2. Use Specified Formatting:
   • Multiple roles must use the pipe (|) delimiter.
   • For a product allowing only one role, ensure only one valid role is listed.
3. Review Validation Errors: Errors provide row-specific feedback to help you correct issues quickly.