| The File Organizational Identity Source Plugin is designed to integrate using CSV files. |
|
This is a non-core plugin, see Installing and Enabling Registry Plugins for more information.
The path specified in File Path must be readable by the COmanage Registry web server.
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.
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.)
As of Registry v4.0.0, multiple file formats are supported:
For earlier versions, the only supported version is CSV v1.
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. |
The first line of the file is a header documenting which columns are present in the file:
SORID, a unique string identifying the record.Model.field.[type], for example EmailAddress.mail.personal or OrgIdentity.affiliationOrgIdentity.valid_from and OrgIdentity.valid_through may be in any format supported by strtotime(), but are expected in UTCOrgIdentity.date_of_birth are expected in YYYY-MM-DD formatName.primary_name.type may be used to specify a primary name, otherwise the first name found will be considered primaryIdentifier.identifier.type+login, to flag that this column represents a login identifier, for example Identifier.identifier.network+loginAdHocAttribute.tag, for example AdHocAttribute.colorRemaining 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.
The file format is fixed, with the following columns:
| Column | Description | Required? | Notes |
|---|---|---|---|
| 1 | Unique Record Key | Yes | |
| 2 | blank | ||
| 3 | blank | ||
| 4 | Given Name | Yes | |
| 5 | blank | ||
| 6 | Family Name | ||
| 7 | Street Address | ||
| 8 | Locality | ||
| 9 | blank | ||
| 10 | State | ||
| 11 | Postal Code | ||
| 12 | Country | ||
| 13 | Email Address | ||
| 14 | Telephone Number | ||
| 15 | Telephone Country Code | ||
| 16 | National Identifier | ||
| 17 | Title | ||
| 18 | Organization | ||
| 19 | Match Reference Identifier | ||
| 20 | Valid From | Any format supported by strtotime(), expected in UTC | |
| 21 | Valid Through | Any format supported by strtotime(), expected in UTC | |
| 22 | Personal URL | Added in v3.1.0 | |
| 23 | Affiliation | Affiliation corresponding to values of AffiliationEnum (Extended Types not supported) Added in v3.2.0 | |
| 24 | Identifiers | Semi-colon ( Added in v3.2.0 | |
| 25 | Date of Birth | YYYY-MM-DD format. Added in v3.3.0. | |
| 26 | Ad Hoc Attributes | A JSON encoded list of ad hoc attributes, as tag/value pairs. The JSON document cannot contain linefeeds, and must be appropriately escaped for CSV. For example:
Note the comma is handled by the outer quotes. Added in v3.3.0 |