Attribute Collection


Historically, Enrollment Flows permitted the collection of Org Identity and CO Person attributes. This was because the original model of external Org Identity attribute collection via protocols like LDAP and SAML could not be well supported, and so deployers could use these attributes to "simulate" the missing Org Identity data. However, this led to a blurring of the two types of attributes.


R3 Enrollment Flows (via an Attribute Collection plugin) will only collect Person (formerly CO Person) attributes via forms. External Identity (formerly Org Identity) attributes will be collected via External Identity Sources (or Enrollment Sources). ie: The Person record will be primary, and will permit the attachment of multiple External Identities, as opposed to R2 Enrollment Flows where Org Identity attributes are arguably primary, and can be copied into CO Person attributes.

Plugin Based Architecture


Enrollment Flows were originally designed as a relatively fixed, but configurable, process to support common enrollment patterns. Over the years, support has been added for more complex use cases, and the configuration driven mechanism for enrollment has become brittle. While Enrollment Wedges were introduced to handle one-off requirements, their use is constrained by the overall flow. Additionally, in many Enrollment Flows numerous steps do not execute, leading to extra elapsed time while the browser processes a series of redirects (made worse with additional plugins) (CO-1663).


R3 Enrollment Flows will be implemented entirely using plugins, where each Enrollment Step maps to a plugin (or more specifically, a plugin model). Similar to jobs, "out of the box" steps will be implemented by a Core plugin. Enrollment Wedges will merge into this plugin infrastructure.

Plugins specify constraints (configuration metadata), including

  • Steps that the plugin step must run before or after
  • Actors that may run the step (Petitioner, Enrollee, Approver, Vetter)
  • Minimum authentication level (Anonymous, CO Person, CO Group Member, etc)

Plugin steps may be configured to run more than once, which should primarily be useful for multiple attribute collection (CO-1002), but may also be useful for other contexts.

Handoff via Actors is managed by the Enrollment Flow engine, and is accomplished via Notifications (sent via email). This process is decoupled from the existing mechanism of Email Confirmation (which is overloaded), though it is conceptually similar to Notify on Approval (but more generic). Handoffs can happen multiple times in any direction. Any time a Handoff is executed, a Redirect option is available to send the no-longer-current Actor to a page with more information.

It may also be useful to handoff a step for background processing (eg: vetting), in which case initial handoff is handled via queueing a job, while continuation of the flow upon completion is handled via Notification.

Notifications may be attached to any Enrollment Step, to be sent at the completion of the Step. Message Templates may be attached to any notification (though not all Message Substitutions may be valid at all times). The Notification Group for each Step may be different, and may be parameterized to support COU specific groups for Enrollment Flows that have a COU context (eg: using the Group name CO:COU:COU Name:Step Label).

Functional Requirements

  1. Common patterns should be supported via out of the box templates, as is the case now for R2 Configurations.
  2. There should be both a "simple" (functionally driven) and "advanced" (low level) configuration mode.
  3. R2 Enrollment Flow Configurations need not transmogrify to R3 Configurations, but guidance should be provided for how to migrate.
  4. Petitions created using R1 and R2 Enrollment Flows should still be readable.

Step Based Authorization

Individual steps within an Enrollment Flow could have their own Group-based authorization, so that certain Steps within a Flow could be run (or skipped) based on the Group memberships of the Petitioner (or Enrollee?).

Support For Inheritance

A commonly requested, but difficult to implement, feature for Enrollment Flows is the ability to override one or two parameters in an Enrollment Flow configuration (eg CO-2042). This is typically a request from deployers with a large number of Enrollment Flows that are functionally similar, but may vary by (eg) the COU configured into the flow.

Enrollment Flows will be able select a "parent" Flow from which the complete configuration is inherited. Specifically Steps may be inserted, replaced, or deleted, probably by keying on the order field. For example, if Enrollment Flow 2, specifies Enrollment Flow 1 as its parent, and Enrollment Flow 2 specifies only one step with order 3, then Enrollment Flow 2 will be exactly the same as Enrollment Flow 1 except for the Step at position 3.

  • To add a Step, the child Flow configures a Step with an order number not in use in the parent Flow. (This might suggest a practice of using multiples of 10 to configure orders in parent Flows.)
  • To replace a Step, the child Flow configures a Step with the same order number as the Step it wishes to replace in the parent Flow.
  • To delete a Step, the child Flow replaces the appropriate Step with a "No-op" plugin, or perhaps the configuration supports a flag.

This approach won't actually address CO-2042 specifically (query string parameters), that sort of detail will be plugin specific.

Branching and Jumping

Because detailed logic will be implemented in plugins, it is not possible for the Enrollment Flow infrastructure to know specifics that might be useful to implement branching (if Petition is Approved go to step 3 otherwise go to step 5). Jumping (always go to step 7), however, could be implemented using a plugin since no logic is required.

To support branching, any plugin that might have data useful for branching would need to implement a configuration and a branch decision interface. This might be possible with (eg) a template file and a Plugin::makeBranchDecision($stepConfig, $petitionID): $stepId function. It might also make sense to recommend a convention of naming configuration items with a standard pattern, eg branch_on_denial_step_id or denial_branch_step_id.

Note that plugins will not be able to jump directly to finalize, but only to other Enrollment Flow Steps. See Registry PE TID: Enrollment Flows and Petitions (revision 3) for further discussion.


  1. An implication of this architecture is that some configuration items will move into Plugin configuration. For example, Enrollment Attributes will no longer be attached to the Enrollment Flow itself, but instead to the appropriate plugin configuration for the (Petitioner) Attributes Step (CO-769).
  2. It may also be useful to have an Expiration Flow concept built on the same architecture, triggered by Expiration Policies or manually by an Administrator.

Error Handling


When an error happens during an Enrollment Flow, CoPetitionsController generally redirects to / and renders an unhelpful flash, that also disappears when the user tries to click on it to copy the error. Error conditions can also lead to partially created records.


There will be a well defined error location that (non-stack trace) errors will redirect to, eg: /petitions/error/123. By default, error messages will render inline on this page, rather than in a flash message. Deployments will be able to customize this page, probably via plugins. The error message will also be recorded in the petition.

Administrators will be given a link to examine the error, and select an action:

  1. Expunge the petition and any related objects (CO Person, etc).
  2. Restart the petition from the next appropriate step.
    1. Where the Petitioner or Enrollee has abandoned a Petition, the restart option should send an email allowing the Petitioner or Enrollee to re-enter the Flow.
  3. Terminate the petition and manually complete the record.

Duplicate Detection


There are currently several points where duplicate management takes place, with somewhat different actions as a result:

  1. Duplicate Enrollment Mode, which uses the value $REMOTE_USER to identify duplicate enrollments. The exact action taken depends on the configuration. Use of this capability requires Email Verification and Authentication.
  2. Advisory Matching, which performs "search while you type" simple name matching. This configuration is only supported for Administrator driven enrollments. Selecting an existing CO Person record interrupts the Enrollment Flow in an unintuitive way.
  3. External Matching, which calls out to an ID Match API. In the event of multiple candidate matches, the Petitioner must select an action before the Enrollment Flow can continue.


It may be desirable to support most or all of the current options going forward, however in general they should operate as External Matching currently does, requiring immediate resolution and appropriately linking (or not) the current Petition to an existing Person record (if found).

After terminating the Petition, a new configuration option could allow an Enrollee to be redirected to a Dashboard or other arbitrary page if duplicate detection finds an existing Person record. Alternately, perhaps with the use of "Flow Control Plugins", a new signup enrollment colud be converted to an additional role enrollment.

Invitation and Email Confirmation Validation


Currently email address confirmation and invitation are conflated into the same step, and require clicking on a somewhat phishy looking link sent via email. These links are also susceptible to premature invalidation (eg: by email clients pre-fetching the URL) or confusion (an enrollee starts enrollment on their desktop, but then goes to their phone to check their email).


Going forward, Invitation may imply Email Confirmation as a side effect (since it is the same flow, basically) but the two concepts will not be as tightly linked. Instead of embedding nonces into URLs, validation will be via a code sent via email (or text message, etc). For self signup flows, the code will be prompted for inline without interrupting the current page. For invitation flows, a generic entry point will be established (eg: /registry/petitions/reply) that will prompt for the confirmation code and/or an Invitation ID, both of which can be copied from the email or text message. This page can also be independently linked from support pages, providing a verifiable path independent of the email URL.

Setup Assistants Replace Templates


Enrollment Templates were originally created to provide easy-to-duplicate pre-configured Enrollment Flows to simplify setup of new Flows. They rely on Cake's ability to easily duplicate an object and its related models. As Enrollment Flow capabilities increased, not all configurations are easily Templatable. For example, EnvSource relies on an Org Identity Source plugin to be created, which might not exist in a given deployment, and so no Template can be shipped that includes a reference to an Enrollment Source.


Enrollment Templates will be replaced with a Setup Assistant, which provides common enrollment patterns and creates a default plugin configuration suitable for that pattern. Such patterns include:

  • Self Signup with Approval
  • Invitation
  • Conscription
  • Account Linking
  • Additional Role Enrollment

The Setup Assistant can determine if a suitable EnvSource configuration exists, and if so offer an option to use it.

The Setup Assistant can also offer plugin specific options. For example, attribute collection might be "None" (for Account Linking), "Minimum Required" (name, affiliation, etc), or "Standard" (title, organization, etc).

Person Record Creation


Currently, a new CO Person record is created very early in the Enrollment Flow process. This can create noise, in particular for duplicate and erroneous enrollments.


New Person records will only be created once the Petition transitions to or past the Approved status. If a Petition is denied, flagged as a duplicate, or otherwise terminated prior to approval, no new Person record will be created. However, if the Petition was linked to an existing Person that link will remain, and the terminated Petition will be available via the existing Person record.

Because Person attributes can be collected over multiple Steps, the Finalize step will call each Attribute Collector Step in sequence (or maybe all Steps in sequence) asking it to construct the Person record based on the Person record constructed by the previous Step. The final result will be persisted to the Registry. If the Person Selector Step identified an existing Person record to work with, that Person record will be used to start the Person record construction process.

Handling User Closing the Browser


A common failure pattern is for the user to close the browser window, interrupting processing and preventing the user from proceeding with the flow.


One option would be to switch to a Job queue style processing of petitions, where each step would submit an action to be processed, then the browser window would "poll" until processing is complete. The user could re-enter the flow by requesting the URL via a self service tool, or with administrator assistance.

The major downside of this approach is that it would slow down all enrollments, including for the vast majority where the user does not close the window. It would effectively negate the gains from eliminating the lengthy series of redirects.

My Identity Shortcut


Enrollment Flows in Registry v4 have a Enable My Identity Shortcut that causes the Flow to be listed in the user's "My Identity" menu.


The My Identity Shortcut will be replaced with a Dashboard Widget. (CFM-336)



Because Enrollment Flows are almost completely structurally different in PE than v4, Transmogrification will simply create archive versions of legacy flows, for use with the Legacy Petition Renderer Plugin.


Transmogrification will perform the following steps:

  1. Create a new "placeholder" Enrollment Flow with the name of the legacy flow, but no meaningful configuration.
    1. Only flows that have CO Petitions associated with them will be transmogrified.
  2. Create a copy of the v4 Enrollment Flow configuration tables with v4 affixed to their names, eg co_enrollment_flows_v4, and a foreign key to the placeholder flow. Where it is too complicated or not possible to maintain elements of these configurations, they will be dropped.
  3. Create a copy of the v4 Petitions tables with v4 affixed to their names, eg co_petitions_v4, and appropriate foreign key updates (eg: co_person_id becomes person_id, and a link to the placeholder flow inserted)

Proposed Plugins


The Approver will present the collected attributes for review (and possibly modification) and approval. It will be possible for multiple approvals to be (sequentially) required by instantiating the Plugin multiple times.

Attribute Collector

The Attribute Collector will present a form consisting of the configured attributes for that instance. The collected attributes will not immediately be transferred to a Person record – this is a change from the v4 behavior. (The Finalizer will handle this.) The Attribute Collector may be instantiated multiple times, each of which may be completed by a different actor (petitioner, enrollee, approver). Subsequent values will replace earlier values.

Authenticator Issuer

The Authenticator Issuer allows the Enrollee to establish Authenticators during Enrollment.

Duplicate Detector

The Duplicate Detector will handle duplicate detection, potentially using different methodologies at different points in the flow. See above for additional discussion.

Email Confirmer

The Email Confirmer will handle email confirmation, based on the set of Email Addresses collected by the Attribute Collector and/or the External Identity Linker. (The latter will require Pipelines to not overwrite the verified status during sync.)

External Identity Linker

The External Identity Linker will replace the Enrollment Source functionality of v4. Various models will be supported.

  • For Self-Signup style enrollments with EnvSource, the Pipeline will create a new Person record (or match against an existing one) and attach the new External Identity to it.
  • For Invitation style enrollments with EnvSource, the Petitioner will create a new Person record (or match against an existing one) before the Linker runs, so that the Pipeline executed by the Linker will attach the new External Identity to an existing Person.
  • For eligibility style enrollments, the Pipeline will attach the new External Identity to the already existing Person.


The Finalizer will handle all administrative tasks required to complete an approved Petition. The Finalizer always runs last, it cannot be manually configured to run earlier. Tasks performed include:

  • Creating a new Person record, if required
  • Assigning Identifiers
  • Provisioning
  • Converting the Petition to read-only (Finalized) status
  • Redirect to Return URL, if configured

Identifier Assigner

The Identifier Assigner will assign Identifiers to the enrollee.

Identity Matcher

The Identity Matcher will call to an Identity Match API to determine if an existing Person record already represents the enrollee.

Information Renderer

The Information Renderer will allow the rendering of informational text on an interstitial page. This replaces the Introduction and Conclusion text, and is more generally available at any point.

Invitation Accepter

The Invitation Accepter will send invitations from the Petitioner to the Enrollee, and render enough information for the Enrollee who has received the invitation to join a CO to determine whether to accept or decline the invitation to join. As a side effect, the Invitation Accepter may also process Email Confirmation. This is a separate plugin, however, so deployers may completely replace it if desired.

Legacy Petition Renderer

The Legacy Petition Renderer will not be used in active Enrollment Flows, but will instead be used to render archived Petitions generated from Registry v4 and earlier. Transmogrification will link old Petitions to a “placeholder” Enrollment Flow that uses the Legacy Petition Renderer, enabling an administrator to view a Person record, select the list of associated Petitions, and then view the old Petition record.


The No-Op Plugin will be used when a child Flow wishes to delete a Step from a parent Flow.

Person Selector

The Person Selector will allow the Petitioner to select an existing Person record to attach the Petition to.

Terms and Conditions Presenter

The Terms and Conditions Presenter Plugin will provide the T&C functionality currently implemented in two different places in Registry v4. Note the transition of this functionality to a plugin suggests it will not be possible to render in line with the Petition Attributes, which are collected via a different plugin.

Flows vs Policies

Enrollment Flows are intended to be interactive workflows to create new Person and Person Role identities. Expiration Policies are automated processes for adjusting the status of Person Role identities. Both concepts have been available in Registry for some time.

It may be desirable to incorporate their opposites into the same mechanisms, ie: Activation Policies to provide automated processes for enabling Person Roles and Offboarding Flows to create an interactive workflow for removing access.

InteractiveEnrollment FlowsOffboarding Flows
AutomatedActivation PoliciesExpiration Policies

See Also

  • No labels