Registry Enrollment Flow Configuration

About Enrollment Flows and Petitions

Every organization has one or more ways of bringing new people into that organization. There are a number of terms used to described this process: application, enrollment, intake, invitation, petition, signup, etc. These processes vary significantly across organizations.

COmanage Registry has a sophisticated, configurable mechanism for representing these processes, and translating them into ways to bring people into a CO's registry. (You can see a representation of the model here.) COmanage Registry refers to these processes as Enrollment Flows, and the execution of these processes as Petitions.

Each CO can define as many Enrollment Flows as it needs to reflect it's specific processes, subject to the COmanage platform configuration. (A CO can also use the very basic default mechanism.) When a new person is to be enrolled, the new person (if self-signup is enabled) or an appropriate administrator creates a Petition to begin the process.

See also: Understanding Registry Enrollment and Linking

Default Enrollment (Invitation)

By default, COmanage Registry operates using an invitation-based enrollment flow. As a CO Admin, you can tell this is in effect by viewing "My Population" for your CO. There will be a button labeled " Invite" at the top of the page.

Defining Enrollment Flows

To customize enrollment, select "CO Enrollment Flows" from your CO's menu. You can define more than one flow, to allow for different enrollment processes.

After you define the basic settings of enrollment (see also the table below for common patterns), define the attributes that will be collected as part of this flow.

Once an Enrollment Flow is defined, the button at the top of the "My Population" page will become " Enroll" instead. Clicking that button will present a menu of available Enrollment Flows to execute.

Creating Organizational Identities As Part of An Enrollment Flow

For COs that will not collect Organizational Identities from authoritative sources (ie: via LDAP or SAML), Enrollment Flows must be configured to collect this data. In order to allow this, the platform must be configured to enable this, via these instructions. Most deployments will likely need to enable this setting. As of v0.9.3, this setting is enabled by default.

Once enabled, CO administrators will be able to add Enrollment Attributes to a CO Enrollment Flow with the type "Organizational Identity".

To facilitate data entry, certain Enrollment Attributes can be configured once in an Enrollment Flow, but populate both the Organizational Identity and the CO Person record. When such an attribute is selected, the option "Copy this attribute to the CO Person record" will become available (as part of editing the Enrollment Attribute).

(See also the platform configuration Pooling Organizational Identities.)

Enrollment Flow Attributes

An Enrollment Flow is just a process for assembling attributes about a person and storing them in records used for day to day operations. Generally speaking, any attribute that can be managed operationally by COmanage Registry (whether attached to a CO Person, a CO Person Role, or an Organizational Identity) can be collected as part of an Enrollment Flow.

The following attributes must be defined:

• COU, if COUs are enabled, and if a new CO Person Role is being created (eg: not needed for account linking)
• Org Identity Name (see note below)
• Org Identity Email Address
• CO Person Name (see note below)
• CO Person Role Affiliation, if a new CO Person Role is being created (eg: not needed for account linking)
• See also the note below about automatically populating ePPN (no need to explicitly define an attribute for this)
• See also Configuring Registry Identifier Assignment (no need to explicitly define an attribute for this)
• See also Registry Platform Configuration

Default Values For Attributes

Certain attributes configured as part of an Enrollment Flow can be assigned default values. (When editing an enrollment attribute, the form will automatically show default value fields when appropriate.) When a Petition is created from the Enrollment Flow, the default values are pre-populated into the form. Default values can also be flagged as not modifiable, in which case the value loaded into the Petition cannot be changed by the Petitioner.

Currently, the following types of attributes may have default values assigned:

• Single valued Organizational Identity attributes (basically, those defined in cm_org_identities)
• Single valued CO Person Role attributes (basically, those defined in cm_co_person_roles)
• Extended Attributes
• CO Group Memberships
  • An Enrollee can only be added to a CO Group as a member ("CO Group Member"), and/or an owner ("CO Group Member and Owner")
    • For "CO Group Member and Owner", the Enrollee will be added as both a member and an owner, except for opt-in groups as described below
  • By setting the default value to be not modifiable, the associated CO Group is fixed; otherwise a Petitioner can add the Enrollee to any available CO Group
  • By setting a default value, flagging it as not modifiable, not hidden, and optional, the CO Group becomes opt-in (by the petitioner)
    • For "CO Group Member and Owner", either or both roles may be selected for opt-in

Attributes that represent dates can receive default values based on

• A fixed date (eg: June 30, 2013)
• The next occurrence of a date (eg: next June 30)
• A specific number of days from the creation of the petition (eg: in 90 days)

In addition, if the Enrollment Flow is configured for Self matching (described below), the Petitioner's name will be pre-populated into the Organizational Identity name fields.

Enrollment Flow Templates

An Enrollment Flow Template is simply an Enrollment Flow that is not Active (and therefore cannot be executed), but can be duplicated to create additional Flows. Any existing Flow may be turned into a Template. (Active Flows may also be duplicated.)

COmanage Registry includes several default Templates. To instantiate these, go to Configuration >> Enrollment Flows and click Add/Restore Default Templates. Note that while the default templates are functional, they are unlikely to be useful for most needs. They are best thought of as starting points, with customization recommended in accordance with the needs of a given deployment.

Petitions and Petition Attributes

The process of executing an Enrollment Flow creates a Petition. The Petition is the record of enrollment – it holds copies of the attributes that were provided at enrollment, even if the values are subsequently changed. History records are also maintained for the Petition, indicating such events as who approved it and when.

Petition-Specific Attributes

It is possible to collect additional attributes as part of an Enrollment Flow that stay within the Petition, but do not become part of the CO Person's operational record. For example, an Enrollment Flow might ask an applicant to provide a sentence explaining why they are interested in joining.

These Enrollment Attribute types are labeled "(Petition Use Only)" when adding a new Enrollment Attribute to an Enrollment Flow.

Enrollment Authorization

Various authorization levels can be selected to determine who may initiate a given Enrollment Flow.

• CO Admin: Only a CO Admin for the CO. CO Admins can always initiate any Enrollment Flow within the CO.
• CO Group Member: Any member of the specified CO Group.
• CO or COU Admin: Any CO or COU Admin in the CO.
• CO Person: Any person who is a member of the CO.
• COU Admin: Any COU Admin for the specified COU.
• COU Person: Any person who is a member of the specified COU.
• None: No authorization required. Useful for self-signup patterns.

Identity Matching

COmanage Registry can perform identity matching when enrollment is performed. This is the process of checking for existing CO People that might match the person being enrolled. Note that matching only happens during the execution of an enrollment flow, now when manually adding a new CO Person. The following matching policies are available:

• None: No matching is performed.
• Advisory: Potential matches are identified, but Registry does not take any action. See more on Advisory Matching, below. This should only be enabled for Administrator (or other trusted user) driven enrollments.
• Automatic: If highly likely matches are found, Registry automatically links the Enrollee to the existing CO Person. If probable matches are found, the Petitioner is given an opportunity to select one. This option is not currently implemented. (CO-298)
• Select: The Petitioner chooses an existing CO Person from the list of all CO People. This is useful for additional role enrollment, and should only be enabled for Administrator (or other trusted user) driven enrollments.
• Self: The new enrollment is automatically linked to the Petitioner. Used for self service account linking and additional role enrollment.

Advisory Matching

Advisory matching currently only works when the following conditions are met:

1. Advisory matching is configured for the enrollment flow.
   
2. The field where data is entered is either a given or family name field.  If an enrollment flow is configured to collect more than one type of name, only the first set of name fields emitted will be enabled for Advisory Matching.
3. At least 3 characters are entered into the field.

Duplicate Enrollments

COmanage Registry can detect duplicate enrollments under limited circumstances. (Alternately, duplicates can be manually resolved.) When enrollee authentication is required (see below), the authenticated identifier is used to check for prior enrollments. What happens when a duplicate enrollment is detected is configurable on a per-Enrollment Flow basis:

• Flag as Duplicate: The Petition and associated CO Person/Role are flagged as Duplicates.

• Create New Role: The CO Person Role data from the Petition is used to create a new Role for the existing CO Person.

• Create New Role If Different COU: If COUs are enabled and the CO Person Role data from the Petition is for a COU that the existing CO Person is not already associated with, then a new Role is created for the existing CO Person. Otherwise, the Petition and associated CO Person/Role are flagged as Duplicates.

See also Automatic Linking.

Email Verification (Confirmation) and Authentication

Email Verification (Confirmation) will result in an email being sent to the email address enrolled. A URL is included in the email, and the enrollee must click on the URL to verify the email address. (An Org Identity email address must be collected as part of the Enrollment Flow.)

Authentication requires the enrollee to authenticate as part of the enrollment process. The authentication is linked to the identity via an email invitation, and so authentication currently requires email verification. This may change in a future release.

If authentication is enabled, the authenticated identifier will automatically be added to the Enrollee's Organizational Identity (currently forced to type ePPN, CO-460) and flagged for login, if the identifier is not already part of the record.

Terms and Conditions

COmanage Registry can require agreement to Terms and Conditions as part of an Enrollment Flow. Authentication must be required.

Redirect Targets

At certain points in an Enrollment Flow, it is possible to define Target URLs where the petitioner or enrollee is sent.

• After a Petition is submitted, if the Petitioner is not already a member of the CO (eg: self signup), then the Petitioner will be sent to the URL specified via Submission Redirect URL (if any).
• After the Enrollee confirms their email address (by clicking the link sent to them), they will be sent to the URL specified via Confirmation Redirect URL (if any). This setting should not be used for Account Linking enrollment.

When a redirect is issued to one of these URLs, the session variable CoPetition.id will also be set. This allows a potential target URL within COmanage Registry to determine which Petition is currently in process. This is particularly useful for custom Plugins that wish to add functionality to the Enrollment Flow.  This functionality is no longer present from v0.9.4. Use Enroller Plugins instead.

Target URLs outside of the Registry environment will not have access to the petition information.

Comments

Administrators reviewing a Petition may add comments to the petition. To do so, retrieve the appropriate Petition and click "Add Comment". The comment will be visible in the Petition History (to anyone with permission to view Petition History).

Approval

An Enrollment Flow can require approval before an Enrollee becomes active. If approval is enabled, then the following people may approve a Petition:

1. If an approval group is selected for the Enrollment Flow, then any CO Person in that group may approve the Petition.
2. Otherwise
   1. Any CO Admin for the CO may approve the Petition
   2. A COU Admin may approve the Petition when one of the following conditions is met
      1. If the Enrollment Flow defines a specific COU whose COU Admins may execute the flow, then any of those COU Admins may approve the Petition
      2. If no such COU is specified but the Petition is attached to a COU (via an Enrollment Flow Attribute), then COU Admins for that COU may approve the Petition
      3. If no specific COU is defined, then any COU Admin for the CO may approve the Petition.

CO Person Status

When a Petition is approved/completed and the associated CO Person Role becomes active, the overall status for the associated CO Person will be recalculated.

Common Enrollment Patterns