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.

To express subgroups, use the following typed membership format in the same configured membership file. Existing files require no conversion.

group_external_id,member_type,member_external_id
group-001,user,user-001
group-001,group,group-002
group-002,user,user-002

The parent always references groups.csv; member_type is user or group and selects the corresponding profile file for member_external_id. This makes identical ID strings in the user and group files unambiguous. References must exist, typed headers must be complete, and legacy user_external_id values must not be mixed into typed rows. Duplicate edges are collapsed while distinct parents of a shared group are retained. Resolve follows nested groups up to 10 subgroup levels by default, with the attached root at level 0; ROSTER_DIRECTORY_GROUP_MAX_DEPTH configures the server limit.

See group expansion limits.

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.

local storage is for standalone deployments. ROSTER_DEPLOYMENT_MODE=ha rejects enabled local-file CSV connectors because replica-local files can diverge; use S3 or SFTP for high-availability deployments.

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.