See also: Writing Registry Plugins
The interface requirements for Organizational Identity Sources is considered Experimental, and may change across minor releases.
Plugin Requirements
- The name of the Plugin should match the format
FooSource
. - The Plugin should implement a
FooSource
model and a corresponding controller (FoosController
).- 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. - 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.
Supported Attributes
The Org Identity Source Backend is expected to return both a raw record (directly representing the backend datasource), and a formatted record. The formatted record is expected to represent an OrgIdentity, in typical Cake array format, along with its associated Models. The Backend may return the following supported attributes:
Attribute | Multi-valued? | Required? | Notes |
---|---|---|---|
Address | Yes | No | See note below. |
EmailAddress | Yes | No | See note below. |
Identifier | Yes | No | Does not automatically include the unique key (SORID). See note below. |
Name | Yes | No | Do not include Primary Name. 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 | |
PrimaryName | No | Yes | This Name should not also be included in the Names array. |
TelephoneNumber | Yes | No | See note below. |
For multi-valued attributes, only one attribute of a given type is currently supported. For example, there can only be one official
EmailAddress, though a second EmailAddress may be provided if (eg) of type personal
.
Possible types may vary by CO, see CoExtendedType::definedTypes
for valid types.
Example
$myData = array( 'OrgIdentity' => array( 'title' => 'Researcher', 'o' => 'University of Impossible Equations', 'ou' => 'Department of Timey Wimey Stuff' ), 'PrimaryName' => 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 ) ) );
Integration With Enrollment Flows
Organizational Source Plugins can be integrated with Enrollment Flows by way of Enrollment Sources. See the Enrollment Sources documentation for an overview of the various modes and how they are used.
Authenticate Mode
Most modes are supported using the interfaces described in Plugin Requirements, above. However, Authenticate mode requires OIS Plugins to implement an additional interface. (Plugins should use this interface to support Authenticate mode, and not the general Enrollment Flow Plugin interface, since this interface will automatically handle configuration checking and plugin ordering.)
The Enrollment Flow will hand off control during the selectOrgIdentity
step to the entry point foo_source/foo_source_co_petitions/selectOrgIdentityAuthenticate/#/oisid:##
(where # is the relevant CO Petition ID, and ## is the Org Identity Source ID).
The easiest way to implement this is for the Plugin itself is to extend CoPetitionsController
. This way, most of the overhead of processing the request will be handled for you, and your plugin need only implement the function execute_plugin_selectOrgIdentityAuthenticate
, where control will be passed.Once your plugin is finished, it should return control to the flow by redirecting back to the main flow, using the URL passed in $onFinish
. The redirect URL is also available in the view variable $vv_on_finish_url
.
// Plugin/FooSource/Controller/FooSourceCoPetitionsController.php App::uses('CoPetitionsController', 'Controller'); class FooSourceCoPetitionsController extends CoPetitionsController { public $name = "FooSourceCoPetitions"; public $uses = array("CoPetition", // Your plugin will most likely need to use OrgIdentitySource to // create the OrgIdentity "OrgIdentitySource"); /** * @param Integer $id CO Petition ID * @param Array $oiscfg Array of configuration data for this plugin * @param Array $onFinish URL, in Cake format * @param Integer $actorCoPersonId CO Person ID of actor */ protected function execute_plugin_selectOrgIdentityAuthenticate($id, $oiscfg, $onFinish, $actorCoPersonId) { // Do some work here, then redirect when finished. // By default, Exceptions will be caught further up the stack, though you could catch them here. $myId = result_of_some_work(); // Create an Org Identity $this->OrgIdentitySource->createOrgIdentity($oiscfg['OrgIdentitySource']['id'], $myId, $actorCoPersonId, $this->cur_co['Co']['id'], $actorCoPersonId); // Create some history $this->CoPetition->CoPetitionHistoryRecord->record($id, $actorCoPersonId, PetitionActionEnum::IdentityLinked, _txt('pl.foosource.linked', array($myId))); $this->redirect($onFinish); } }
Standard MVC rules apply.