CSV Connector

The CSV connector reads directory data from files and normalizes it into Roster users, groups, and memberships.

Storage Modes

Mode	Use case
local	Files mounted into the Roster data volume.
s3	Files read through an object-storage reader.
sftp	Files read through an SFTP storage reader.

Required Files

users.csv

external_id,user_name,primary_email,display_name
user-001,user001,user001@example.com,User 001

groups.csv

external_id,display_name,mail
group-001,Engineering,engineering@example.com

user-groups.csv

user_external_id,group_external_id
user-001,group-001

The connector uses external_id as the stable provider key. The membership file links user external IDs to group external IDs.

Mounted Volume Path

For mounted-volume storage mode (local), mount files under the Roster data volume:

${ROSTER_DATA_DIR}/connectors/csv

In Docker, mount that directory through the /data volume used by Roster.

Field Mappings

Connector field mappings are stored on the provider connection config as field_mappings, with users and groups objects. The keys are normalized Roster fields and the values are source CSV column names.

{
  "field_mappings": {
    "users": {
      "external_id": "employee_id",
      "user_name": "login",
      "primary_email": "email",
      "display_name": "name"
    },
    "groups": {
      "external_id": "team_id",
      "display_name": "team_name",
      "mail": "team_email"
    }
  }
}

Production Notes

• Use durable storage for CSV files.
• Keep source files under operational change control.
• Refresh on a predictable schedule.
• Validate source column names before changing field mappings.