Background

Pipeline Plugins allow for modification of External Identity Data as it flows through a Pipeline. Pipeline Plugins are connected to Pipelines via Flanges.

Integration Points

Pipelines support Plugins at specific points, which is selected at instantiation time via the Flange Status. Plugins only need to support Integration Points of interest. Available Integration Points are

  • Build Person Role: Called after the Person Role is constructed from the External Identity Role, but before it is saved.
  • Retrieve External Identity: Not yet implemented.

Entry Point Models

Pipeline Plugins implement an Entry Point Model for each supported Integration Point. The corresponding controller should extend StandardPluginController, and implement an edit-only fields.inc.

buildPersonRole()

For Pipeline Plugins that support Build Person Role, the Entry Point Model must implement a buildPersonRole() function with the following signature:

public function buildPersonRole(
  \App\Model\Entity\Flange $flange,
  array $newdata,
  \App\Model\Entity\ExternalIdentityRole $eirdata
): array 

where

  • flange: The Flange configuration associated with this instantiation, and which includes the Plugin configuration as a related model
  • newdata: The currently assembled array of Person Role data, including any changes made by Flanges that have already run
  • eirdata: The original External Identity Role data from the External Identity Source Plugin, including related models

The return value is an array in the same format as $newdata.

The plugin may throw an InvalidArgumentException or a RuntimeException if any condition warrants stopping the Pipeline.

buildRelatedAttributes()

For Pipeline Plugins that support Build Related Attributes, the Entry Point Model must implement a buildRelatedAttributes() function with the following signature:

public function buildRelatedAttributes(
  \App\Model\Entity\Flange $flange,
  array $newdata,
  string $model,
  ?\Cake\ORM\Entity $entity=null
): array 

where

  • flange: The Flange configuration associated with this instantiation, and which includes the Plugin configuration as a related model
  • newdata: The currently assembled array of entity data, including any changes made by Flanges that have already run
  • model: The name of the model whose data is being provided in $entity (eg: Identifiers)

  • entity: The original entity (unmodified), may be null for new records

The return value is an array in the same format as $entity.

The Plugin may throw an InvalidArgumentException or a RuntimeException if any condition warrants stopping the Pipeline.

Plugins can tell whether the attributes are directly attached to the External Identity or are attached to the External Identity Role by examining the foreign keys set in the record data (ie: external_identity_id or external_identity_role_id).

(warning) Because processing of the Flag All Email Addresses as Verified configuration and management of Primary Name flags happen after Flanges are called for the Build Related Attributes context, it is not possible for Pipeline Plugins to override decisions made by these configurations.

Example

// $plugin/src/config/plugin.json
 
{
  "types": {
    "pipeline": [
      "DataMunger"
    ]
  }
}
 
// $plugin/src/Model/Table/DataMungersTable.php
  
namespace PipelineMunger\Model\Table;
   
class DataMungersTable extends Table {
  public function buildPersonRole(
    \App\Model\Entity\Flange $flange,
    array $newdata,
    \App\Model\Entity\ExternalIdentityRole $eirdata
  ): array {
    $ret = $newdata;

    $ret['title'] = "Modified Title per HR";

    return $ret;
  }

  public function buildRelatedAttributes(
    \App\Model\Entity\Flange $flange,
    array $newdata,
    string $model,
    ?\Cake\ORM\Entity $entity=null
  ): array {
    $ret = $newdata;
    
    if($model == 'Identifiers') {
      $ret['identifier'] = "external-" . $newdata['identifier'];
    }

    return $ret;
  }
}

See Also

Changes From Earlier Versions

As of Registry v5.1.0

  • buildRelatedAttributes() is available.
  • No labels