Background

External Identity Source Plugins are designed to read records from external systems (External Identity Sources, or alternately Systems of Record) and convert them to Registry's standard format for use with Pipelines and connection to Registry People.

Plugins that also implement a Provisioner interface should be named Connectors (eg: WidgetConnector). This is not a technical requirement, and if the Plugin is named following a different pattern no functionality will be lost.

Entry Point Model

Each Entry Point model for External Identity Source plugins will be made available as a potential source when a new External Identity Source is instantiated. The corresponding controller should extend StandardPluginController, and implement an edit-only fields.inc.

retrieve()

The Entry Point Model must implement a retrieve() function with the following signature:

public function retrieve(
  \App\Model\Entity\ExternalIdentitySource $source,
  string $source_key
): array

where

• source: An entity holding the configuration for the requested ExternalIdentitySource
  • The configuration of the instantiated backend is available as a related model, eg $source->widget_sources
• source_key: The backend-specific key identifying the record to retrieve

The return value is an array with the following entries:

• source_key: The source key for the record
  • If the returned value does not match the requested value, Registry will not automatically update the Source Key
• source_record: An encoding of the raw record returned by the source
  • This record should not be changed across calls to retrieve() if the underlying record has not changed, as Registry uses it to determine if the External Identity created from this record needs to be updated
• entity_data: The record returned by the source, normalized to a Registry External Identity (including associated models)
  • See Data Model Considerations, below

retrieve() may throw Exceptions on error.

search()

The Entry Point Model must implement a search() function with the following signature:

public function search(
  \App\Model\Entity\ExternalIdentitySource $source,
  array $searchAttrs
): array

where

• source: An entity holding the configuration for the requested ExternalIdentitySource
  • The configuration of the instantiated backend is available as a related model, eg $source->widget_sources
• searchAttrs: An array of search attributes and values

The return value is an array with 0 or more records in the same format as entity_data returned by retrieve(), keyed on the source key. If no matches are found, an empty array should be returned. On error, a suitable Exception should be thrown.

searchableAttributes()

The Entry Point Model must implement a searchableAttributes() function with the following signature:

public function searchAttributes(): array

The return value is an array with a set of one or more attributes that may be searched on by this backend. The key is a short label for the attribute, suitable for passing in HTML forms, and the value is the localized text string describing the attribute.

Whenever possible, backends should use a single searchable attribute q that is used to search any relevant backend field (see the example, below). Specific attributes (such as email or family name) should only be used when required by the backend search functionality.

Data Model Considerations

Record Identifiers

The source_key (or System of Record Identifier, or SORID) should not be included in the set of Identifiers, it will be automatically inserted.

A role_key must be included for each role asserted by the backend. Role Keys need only be unique within the individual's External Identity Source record, they do not need to be unique in any other context.

Date of Birth

Currently, Plugins are expected to return Date of Birth in YYYY-MM-DD format.

Names

At least one Name must be included in the returned entity. Backends should not assert a Primary Name.

Status

Plugins may assert select status values for each External Identity Role they return via retrieve(). Valid statuses are those defined in ExternalIdentityStatusEnum, as follows:

• Active: The Role is Active within the organization.
  • This status should also be used when the valid from date is in the future, to indicate the Role is expected to become active.
  • This status should also be used when the valid through date is in the past, to indicate the Role has expired.
• Archived: The Role is no longer in use and is not expected to be reactivated.
  
  • This status should not be used when a valid through date is specified, use Active instead.
• Duplicate: The Role is a duplicate of another and should not be used.
• Grace Period: The Role is no longer Active, but services have not yet been deprovisioned.
• Suspended: The Role is not currently Active.
  
  • This status should not be used when a valid through date is specified, use Active instead.
• Deleted: This status may not be directly asserted by the Plugin, as it is used for internal purposes. Use Archived instead.

Status may only be asserted for External Identity Roles, not the overall External Identity itself. That status will automatically be calculated based on the Role statuses.

If no status is provided, External Identity Roles will be assigned Active status unless validity dates determine otherwise.

Types

For attributes with types (such as Name or Email Address), the type string should be used (eg: personal or official) and not the database foreign key. The Pipeline will automatically convert the type string to the internal foreign key.

Handling Inactive Roles

There are several ways to handle External Identity Roles that are no longer active, each with somewhat different characteristics. In the chart below, the following definitions are used:

• External Identity Role Status: The status of the External Identity Role when viewed from the Person record.
• Person Role Status: The status of the Person Role when viewed from the Person record.
• Person Role MVEAs: What happens to Multi-Valued Entity Attributes attached to the synced Person Role, such as Telephone Numbers and AdHoc Attributes.
• Configured Status: The Role Status on Delete status configured in the Pipeline.

*Does not apply if Person Role is Frozen.

†Does not apply if MVEA is Frozen.

Example

// $plugin/src/config/plugin.json

{
  "types": {
    "source": [
      "WidgetSources"
    ]
  }
}

// $plugin/src/Model/Table/WidgetSourcesTable.php
 
namespace WidgetConnector\Model\Table;

use \App\Model\Entity\ExternalIdentity;
use \App\Lib\Enum\ExternalIdentityStatusEnum;
 
class WidgetSourcesTable extends Table {
  public function retrieve(
    \App\Model\Entity\ExternalIdentitySource $source, 
    string $source_key
  ): array {
    // Query the backend here
    $data = $this->retrieveFromMyDataSource($source_key);

    return [
      'source_key'    => $source_key,
      'source_record' => json_encode($data),
      'entity_data'   => $this->myDataConversionFunction($data)
    ];
  }

  public function search(
    \App\Model\Entity\ExternalIdentitySource $source, 
    array $searchAttrs
  ): array {
    // Query the backend here
    $results = $this->searchMyDataSource($searchAttrs);

    $ret = [];
	
	foreach($results as $r) {
	  $ret[ $r->source_key ] = $this->myDataConversionFunction($data);
    }
	
    return $ret;
  }

  public function searchableAttributes(): array {
    return [
      'q' => __d('field', 'search.placeholder')
    ];
  }

// $plugin/src/Controller/WidgetSourcesController.php
 
namespace WidgetConnector\Controller;
 
use App\Controller\StandardPluginController;
 
class WidgetSourcesController extends StandardPluginController {
  // Standard Cake controller stuff here
}

See Also

• Writing Registry PE Plugins
• Registry PE External Identity Sources
• Person and External Identity Status