...
- The name of the Plugin should match the format
FooSource
. - The Plugin should implement a
FooSource
model and a corresponding controller (FoosController
FooSourcesController
).- This model should
belongTo OrgIdentitySource
. - The controller should extend
SOISController
. - When a new Org Identity Source is created, a skeletal row in the corresponding
foo_sources
table will be created. There is noadd
operation or view required. The skeletal row will point to the parent Org Identity Source. - When an Org Identity Source is edited, the entry point to the Plugin will be
foo_source/foo_sources/edit/#
. This will be called immediately after the parent Org Identity Source is created. - Note
OrgIdentitySource
has ahasOne
(ie: 1 to 1) relationship withFooSource
. - The table
foo_sources
should include a foreign key toorg_identity_sources:id
.- Other tables used by the plugin should reference
foo_source:id
.
- Other tables used by the plugin should reference
- This model should
- The Plugin should also implement a model named
FooSourceBackend
.- The backend is responsible for the implementation of the backend search and retrieval capabilities.
- The raw record returned by the
retrieve()
function should not change if the underlying backend record has not changed. Registry uses the raw record to determine when the related Org Identity record must be updated. - The Plugin should support
mail
(email address) as a searchable attribute. This capability is used by Enrollment Flows in various configurations, see Integration With Enrollment Flows, below. - As of Registry v3.1.0, Plugins may also implement
getChangeList()
, which determines the set of changed records for a given time period. When supported, OIS sync processes in Update Mode will run more efficiently.- As of Registry v3.2.0, if the
forcesyncorgsources
task is used,getChangeList()
cannot be used. - Because
getChangeList()
is designed to facilitate updating existing records, backends should only return IDs for records that were updated or deleted. The function should not return IDs for records that were added, as the Sync Job will separately determine which records were added (using the backend'sinventory()
call), and ifgetChangeList()
returns these IDs they may be processed twice.
- As of Registry v3.2.0, if the
- See also Supported Attributes, below.
- The raw record returned by the
- This model should extend
OrgIdentitySourceBackend
, and implement the abstract functions defined in the parent model (seeapp/Model/OrgIdentitySourceBackend.php
). - Note that the Plugin configuration for
FooSource
will be available to the backend in$this->pluginCfg
.
- The backend is responsible for the implementation of the backend search and retrieval capabilities.
- Registry will automatically track the current backend data via the org_identity_source_records table.
...
Attribute | Multi-valued? | Required? | Notes |
---|---|---|---|
Address | Yes | No | See note below. |
AdHocAttribute | Yes | No | |
EmailAddress | Yes | No | See note below. |
Identifier | Yes | No | Does not automatically include the unique key (SORID). See note below. |
Name | Yes | No | At least one Name must be returned, and exactly one Name must be flagged primary. See note below. |
OrgIdentity.affiliation | No | No | Possible values may vary by CO; see CoExtendedType::definedTypes |
OrgIdentity.title | No | No | |
OrgIdentity.o | No | No | |
OrgIdentity.ou | No | No | |
OrgIdentity.valid_from | No | No | Must be in UTC time, and database format, eg via strftime("%F %T", ...) |
OrgIdentity.valid_through | No | No | Must be in UTC time, and database format, eg via strftime("%F %T", ...) |
TelephoneNumber | Yes | No | See note below. |
Url | Yes | No | See note below. Available from Registry v3.1.0. |
...
Info |
---|
For multi-valued attributes, only one attribute of a given type is currently supported. For example, there can only be one Possible types may vary by CO, see |
Info |
---|
As of Registry v3.3.0, an identifier of type |
Example
Code Block | ||
---|---|---|
| ||
$myData = array( 'OrgIdentity' => array( 'title' => 'Researcher', 'o' => 'University of Impossible Equations', 'ou' => 'Department of Timey Wimey Stuff' ), 'Name' => array( array( 'given' => 'Pat', 'family' => 'Lee', 'type' => 'official', 'primary_name' => true ) ), // Note below here are multi-valued arrays 'Identifier' => array( array( 'identifier' => 'plee@university.edu', 'type' => 'eppn', 'login' => true ) ), 'EmailAddress' => array( array( 'mail' => 'plee@university.edu', 'type' => 'official', 'verified' => true ), array( 'mail' => 'plee@socialemail.com', 'type' => 'personal', 'verified' => false ) ) ); |
...
groupableAttributes()
defines the set of attributes the Plugin knows about that may be used for generating group memberships. This may be a static list of attributes, or (as of v3.1.0) it may be dynamically determined based on a given instantiation (via the configuration available in$this->pluginCfg
).resultToGroups()
converts a raw result into an array of attribute value/pairs. Note the array is not itself the group mapping, but rather the relevant attributes that will be used by the core code to determine if any group membership match. (This way the Plugin does not need to worry about parsing the mapping configuration.)
Info |
---|
...
Prior to v3.2.0, the Note that while it is possible for a backend to return multiple entries for the same group with different validity dates, these must be consolidated down to a single CoGroupMember record. (While the data format theoretically allows multiple CoGroupMember records for the same CO Person in the same CO Group with different validity windows, in practice this is not supported anywhere.) If multiple entries are found, the group membership mapping code will attempt to pick the "best" one, which is generally the current record, or the one with the latest valid through date. Plugins can implement more deterministic algorithms by setting the results from |
Example
Code Block | ||
---|---|---|
| ||
public function groupableAttributes() { return array( 'title' => _txt('fd.title'); ); } public function resultToGroups($raw) { // The core code will use this data to determine if the configured // OIS Group Mapping rules are matched. return array( 'title' => array( array( 'value' => 'Professor of Mysterious Events', 'valid_from' => '2017-08-01 00:00:00', 'valid_through' => '2018-07-31 23:59:59' ); ); ); } |
...