File Source is an External Identity Source Plugin designed to integrate with upstream sources using CSV files.


  1. File Source is part of the FileConnector Registry Plugin, which must be activated.
  2. When adding a new External Identity Source, the Plugin is FileConnector.FileSources.

Archive Directory


Warning Threshold


File Format

CSV, or comma-separated value format, is not consistently implemented everywhere. While there is an RFC defining the format, a given implementation may or may not support it fully. For the avoidance of doubt, FileSource uses PHP's CSV parsing functions, and so for any particular inconsistency PHP's behavior should be considered normative.

CSV v3

The first line of the file is a header documenting which columns are present in the file:

  • The first column in this file must always be SORID, a unique string identifying the record.
  • Remaining columns are specified as follows:
    • external_identity.field, for example external_identity.date_of_birth
      • Note external_identity is singular, unlike other model names which are plural
    • external_identity_roles.rolekey.field, for example external_identity_roles.1.title
    • models.field.[type], for example email_addresses.mail.personal
      • type is the Database Value, not the Display Name
    • external_identity_roles.rolekey.models.field.type, for example
    • ad_hoc_attributes.tag, for example ad_hoc_attributes.color

CSV v3 supports multiple External Identity Roles. Each Role (even if there is only one) must be assigned a Role Key, all records loaded from the File Source will use the same Role Keys when Pipelined to a Person Role.

Remaining lines in the file each represent one inbound record, with columns as specified by the header.

Example files are attached to this page.

Date of Birth

Date of Birth must be specified in YYYY-MM-DD format.

Updating from CSV v1 and v2 to v3

CSV v3 is substantially similar to v2, changes are largely related to changes in the underlying data model. Specifically:

  • Models are now specified using plural underscore notation (eg: email_addresses) instead of singular camel case (eg: EmailAddress).
  • Most attributes that were part of OrgIdentity are now part of ExternalIdentityRole.
  • The type associated with most attributes is the Database Value.
  • It is no longer possible to specify login identifiers, as the login flag now only applies to Identifiers attached to People, not ExternalIdentities.
  • It is no longer possible to specify a Primary Name.

Conversion from CSV v1 requires the insertion of a header row

See Also

Changes From Earlier Versions

As of Registry v5.0.0

  • The only supported File Format is CSV v3.
  • If the same Source Key exists multiple times in the same file, the first record found will be returned. Previously, an error would be thrown. (In general, the same Source Key should not exist multiple times in the same file.)
  • No labels