If you just need to publish static documents, see Publishing Mostly Static Public Content instead.
Registry functionality can be extended with the use of Plugins. Building a Registry Plugin requires knowledge of PHP, CakePHP, and COmanage.
Building a Registry Plugin
- Understand the Cake Framework. You should minimally have worked through the tutorials and examples.
- Understand Cake Plugins. Registry Plugins are just Cake Plugins, with some extra conventions.
- Understand the Registry Data Model.
Instantiated vs Non-Instantiated
There are two basic categories of Plugins supported by COmanage Registry.
- Instantiated plugins must be configured before they can be used. For example, the LDAP Provisioner must be given connection information that is specific to each CO. Creating that configuration is instantiating the plugin.
- Non-Instantiated plugins do not have CO-specific configuration. For example, normalizing whitespace is not CO specific.
This categorization is based on how Registry handles the plugin. An instantiated plugin follows a typical add/edit flow in order to use the plugin, with entry points described in the Additional Requirements By Plugin Type section, below.
It is possible for a non-instantiated plugin to maintain its own configuration, however Registry provides no direct support for configuring non-instantiated plugins.
It is possible that non-instantiated plugins will be converted to instantiated plugins in future releases as Registry capabilities evolve. Such a conversion may require changes to the plugin interfaces.
Set up a new Plugin in the directory
local/Plugin/MyPlugin. You might find it handy to use Cake's
Prior to v1.0.0, Plugins must be placed in
- Create a Model whose name matches the name of the Plugin. In this example, the Model is created at
$cmPluginTypeto indicate the type of the Plugin, from the following options:
Available Since Instantiated?
Authenticator Plugin v3.1.0 Yes
Cluster Plugin v3.3.0 Yes
Invitation Confirmer Plugin v3.1.0 No
Dashboard Widget Plugin v3.2.0 Yes
Data Filter Plugin v3.3.0 Yes
Enrollment Flow Plugin v0.9.4 Yes, as of v4.0.0
Identifier Validation Plugin v2.0.0 Optional
Job Plugin v3.3.0 Yes, when queued
LDAP Schema Plugin v2.0.0 Yes, via LDAP schema configuration
Organizational Identity Sources Plugin v2.0.0 Yes
Any other type of Plugin
As of v2.0.0,
$cmPluginTypemay also be an array.
Here's an example Model:
Plugins have full access to the Registry database. You can create your own additional tables by creating a schema file and placing it in
Plugin/MyPlugin/Config/Schema/schema.xml. The file is specified in ADOdb AXMLS format.
Tables should follow the Cake standard conventions, including
Once the file is created, the database schema will automatically be updated by the normal mechanism:
Foreign Key Dependencies
If you define tables for your plugin, you will almost certainly want foreign keys into the core database schema. For example, your tables may have
co_id to refer to CO People or COs, respectively.
In order for deletes to cascade successfully when the parent object is deleted, you must specify any dependencies your plugin has. (Failure to do so will result in foreign key violation errors when the parent object is deleted.) To do so, define an array
Model/MyPlugin.php, which consists of an array where the keys are the model the foreign key points to and the values are the name of the model they point from.
CoChangelogProvisionerExports. Put another way,
co_changelog_provisioner_exports has a column
co_person_id that is a foreign key to
As of Registry v3.2.0,
$cmPluginHasMany also accepts a standard Cake model dependency array. eg:
Do not hardcode display texts, but instead create lookup files that translate keys into language specific texts. For now, Registry uses a custom mechanism for I18N/L10N (CO-351). Use
_txt(key, array(param1, param2)) in your code to generate language-specific text, and then define those keys in the file
Plugins may define enumerations in
Use of Standard Views
You may use Registry's "standard" views to easily render your pages in the Registry look. Simply create links from
../../../../View/Standard. See core Registry views for examples. Note that you will need to define the language texts
ct.co_X_model.pl to use the standard views, replacing
X with the name of your model.
Registry v3.2.0 introduces Server objects, which are intended to reduce duplicate configuration, and allow multiple plugins (or other components) to share the same server information and state. Plugins should use Server objects for configuration whenever possible. To do so, the CO Administrator is expected to define the Server outside of the Plugin. Then, during configuration, the Plugin should present a list of available Servers of the desired type and store the foreign key reference to that configuration.
To obtain the list of available Server, any model associated with a controller that extends StandardController can set
public $cmServerType = ServerEnum::ServerType
The corresponding view will be passed
$vv_servers, with a list of available servers keyed by
Plugins can add items to Registry's menus. To do so, define in
Model/MyPlugin.php a function
cmPluginMenus() that returns an array. The key in this array is the menu location to append to (see table below), and the value is another array, which defines one or more labels and the corresponding controllers and actions to generate links to. The Plugin infrastructure will automatically append CO IDs and CO Person IDs as appropriate.
Whether or not a Plugin menu is rendered is determined by the default permission as listed below.
Menu Location Key
CO ID Inserted?
CO Person ID Inserted?
|Member of Any CO|
v0.8 - v3.0.0
CO Configuration Menu
|CO Main Menu||Member of CO||v3.2.0|
CO People Menu
Member of CO
|CO Groups Menu||Member of CO||v1.0.0|
My Identities Menu
Member of CO
CO Services Menu
|Member of CO|
v2.0.0 - v3.0.0
Menu Link Icons
As of Registry v3.2.0, icons are required in two contexts:
comain. The icon is specified by a special
icon key in the menu URL array, and references the name of a Material Design icon.
As of Registry v3.2.0, Plugins may implement searching as part of the main search box.
First, declare which plugin models support search in
Model/MyPlugin.php by defining a function
cmPluginSearchModels() that returns an array, keyed on plugin model, of displayField and permissions:
Next, in each supported model add a function
search($coId, $q) that implements the backend search, based on the provided CO ID and unparsed search string. (Be sure to add databases indexes as needed.) Return an array of search results in the same format as
This feature is available since Registry v3.2.0.
When a CO is duplicated, Registry will attempt to copy configuration data, but not operational data (such as CO Person records).
For Instantiated plugins, duplication will attempt to copy plugin configuration. By default, this will involve copying data in the core model for the plugin, eg:
CoFooProvisionerTarget for provisioner plugins or
FooSource for orgidsource plugins. However, it is possible to override this default behavior in order to duplicate additional configuration records associated with the plugin. To do so, in the plugin's core model define $duplicatableModels, which is an array of relevant models and their configuration (parent model and foreign keys). For example:
Duplication does not currently support Non-Instantiated plugins.
Related Actions Links
Adding links to Related Actions is not currently supported. (CO-520)
Exposing Plugin functionality via the REST API is not currently officially supported (CO-521), however as of Registry v3.2.0 it is possible for plugins to expose a REST API. This feature is considered experimental, as future releases may impose structure to standardize or simplify the process.
To expose an API, the plugin will most likely need to defined routing in
$PLUGIN/Config/routes.php. The plugin may use the standard Cake mapResources() call, and may leverage Registry's ApiComponent. For more details, see example plugins or core code. More detailed documentation will be available when REST APIs for plugins are fully supported.
Note that plugin API paths will be prefixed with the plugin name, as with web pages. ie:
Filtering Index Views
Most REST API "View" calls can be filtered somehow, such as view all items by CO or CO Person. Plugins may wish to filter by a Plugin-specific data element. As of Registry v3.3.0, this is possible by declaring
$permittedApiFilters in the appropriate Model file. Note this is the Model associated with the desired REST API (eg:
Model/MyOtherModel.php), which is not necessarily the primary Plugin Model (
The content of
$permittedApiFilters is an array, where each key corresponds to a column (which must be a foreign key) in the Model and the value is the related Model that will implement the desired filtering. By way of example, consider a plugin that implements two models: Boxes and Labels, where Box hasMany Label. To enable the REST API to retrieve all Labels associated with a given Box, add the following to
This will enable the REST call
Additional Requirements By Plugin Type
Plugin Types not listed here have no additional requirements.
- Authenticator Plugins
- Cluster Plugins
- Dashboard Widget Plugins
- Data Filter Plugins
- Enrollment Flow Plugins
- Identifier Validation Plugins
- Invitation Confirmer Plugins
- Job Plugins
- LDAP Schema Plugins
- Normalization Plugins
- Organizational Identity Source Plugins
- Provisioner Plugins