Background

Provisioner Plugins are designed to write Registry objects to external systems, or Provisioning Targets.

(info) Plugins that also implement an External Identity Source 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 Provisioner plugins will be made available as a type of Provisioner when a new Provisioning Target is instantiated. The corresponding controller should extend StandardPluginController, and implement an edit-only fields.inc.

Declaring Supported Models

The Entry Point Model should use \App\Lib\Traits\ProvisionerTrait (not ProvisionableTrait) and then call setProvisionableModels() to indicate which models the Entry Point Model is capable of provisioning. Note that only those core models that are provisionable will actually cause the Provisioner to be called. Models that do not support provisioning but are added to setProvisionableModels() will be ignored.

provision()

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

public function provision(
  \WidgetConnector\Model\Entity\WidgetProvisioner $provisioningTarget,
  string $className,
  object $data,
  ProvisioningEligibilityEnum $eligibility
): array

where

  • provisioningTarget: An entity holding the configuration for the requested provisioning target
  • className: The class of the Entity being provisioned, eg People or Groups
  • data: Data to be provisioned in the format of the Entity being provisioned (including related data), eg \App\Model\Entity\Person
  • eligibility: A ProvisioningEligibilityEnum value indicating provisioning, eligibility (see below)

More information about the data and eligibility rules for Provisionable Objects is available here.

The return value is an array with the following entries:

  • status: ProvisioningStatusEnum value indicating result of provisioning request
  • comment: Human readable descriptive comment of the result
  • identifier: Provisioning Target Specific Identifier, not yet supported (CFM-26)

(warning) provision() should not throw an Exception on error, and should catch any exceptions thrown by code it calls. Instead, an appropriate return array should be constructed using the information from the Exception.

Provisioning Eligibility

The table for the primary object being provisioned, when marshaling the $data object, will also provide a high level indicator of the subject's eligibility to be provisioned. Possible values are:

  • Deleted: The subject has been deleted, and the provisioning target should take appropriate action.
  • Eligible: The subject is eligible for provisioning.
  • Ineligible: The subject is no longer eligible for provisioning, however the provisioning target may wish to retain referential data (such as names or identifiers) in case the subject becomes eligible again later.

More specific information may be obtained by looking at the $data object.

$data may be a deleted entity (most delete actions are soft deletes, see Changelog Behavior for more information), or an entity in a non provisionable status (such as Suspended). Provisioner Plugins should examine the appropriate entity information (eg: $data->deleted or $data->status) and act accordingly.

Example

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

{
  "types": {
    "provisioner": [
      "WidgetProvisioners"
    ]
  }
}

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

use App\Lib\Enum\ProvisioningEligibilityEnum;
use App\Lib\Enum\ProvisioningStatusEnum;
 
class WidgetProvisionersTable extends Table {
  use \App\Lib\Traits\ProvisionerTrait;

  public function initialize(array $config): void {
    ...

    // Declare which primary models we're interested in. Secondary models associated with
    // these primary models (eg: Names, Identifiers) do NOT need to be declared here.
    $this->setProvisionableModels(['People', 'Groups']);
  }

  public function provision(
    \WidgetConnector\Model\Entity\WidgetProvisioner $provisioningTarget,
    string $className,
    object $data,
    string $eligibility
  ): array {
    // Do some stuff here

    return [
      'status'      => ProvisioningStatusEnum::Provisioned,
      'comment'     => __d('widget_connector', 'result.prov.added'),
      'identifier'  => $myWidgetId
    ];
  }
}
 
// $plugin/src/Controller/WidgetProvisionersController.php
 
namespace WidgetConnector\Controller;
 
use App\Controller\StandardPluginController;
 
class WidgetProvisionersController extends StandardPluginController {
  // Standard Cake controller stuff here
}

See Also

  • No labels