File Source

The File Organizational Identity Source Plugin is designed to integrate using CSV files.

Modes

Installation

This is a non-core plugin, see Installing and Enabling Registry Plugins for more information.

Configuration

The path specified in File Path must be readable by the COmanage Registry web server.

Archive Directory

As of Registry v3.1.0, FileSource supports an Archive Directory. If specified, this directory must be writeable by the COmanage Registry web server, and FileSource will maintain two previous copies of the source file (using the basename of the file, appended with .1 or .2). This allows FileSource to perform a diff in order to determine changed records, which performs significantly better for larger files.

 Use of this configuration option is especially recommended for source files containing more than a few hundred sync'd records.

Change Threshold

As of Registry v4.0.0, FileSource supports a Warning Threshold, which can prevent processing if an unexpectedly large number of changes (including new records) are detected. The threshold is expressed as a percentage (integer).

If a large number of changes are expected, the Warning Threshold Override can be enabled to skip the threshold check. The override will be automatically unset after processing. Note the first time a source is processed, the threshold check is automatically skipped. (The Core Job Plugin Sync job force parameter will also skip threshold checking, but the override is the recommended mechanism.)

File Format

As of Registry v4.0.0, multiple file formats are supported:

• CSV v1: Legacy CSV format
• CSV v2: Flexible CSV format

For earlier versions, the only supported version is CSV v1.

CSV v2

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:
  • Model.field.[type], for example EmailAddress.mail.personal or OrgIdentity.affiliation
    • Values for OrgIdentity.valid_from and OrgIdentity.valid_through may be in any format supported by strtotime(), but are expected in UTC
    • Values for OrgIdentity.date_of_birth are expected in YYYY-MM-DD format
    • Name.primary_name.type may be used to specify a primary name, otherwise the first name found will be considered primary
    • [type] uses the type's name value, not the  type's display name value
  • Identifier.identifier.type+login, to flag that this column represents a login identifier, for example Identifier.identifier.network+login
  • AdHocAttribute.tag, for example AdHocAttribute.color

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

Example files are attached to this page.

CSV v2 format can be used with Pipeline Relationship Syncing by using the column names OrgIdentity.manager_identifier and OrgIdentity.sponsor_identifier.

  FileSource supports Ad Hoc attributes for creating Group Mappings.

CSV v1 (Legacy)

The file format is fixed, with the following columns:

See Also

• cm_file_sources