3. Setting up an Enrollment Workflow

We’ll learn about the Enrollment Workflow🚀 configuration form by working with it. We will start from one of the Enrollment templates.

Hands on - Configure an Enrollment Workflow🚀

REQUIRED ROLE: CMP Administrator👑 -OR- CO Administrator👑

Often a CO Administrator👑 will manage workflows for the CO⚙️. For this exercise, use the persona that holds a CO Administrator👑 role.

Sign into COmanage

1. Using the credentials for a user that holds a CO Administrator👑 role, sign into the system.

2. Before we create a workflow, let’s review what the enrollment options looked like when you enrolled a new person as your CO Administrator⚙️ in a previous lesson.

   • Open the People sub-menu on the left to display the options that you have.
   • At the bottom of this list is an Invite link. If you click on this link, you will be able to invite anyone for whom there is an Org Identity⚙️ defined in the CO⚙️. At the moment we do not have anyone that we can invite, so the system will present an error message. But, that’s okay because we are about to set up a more flexible enrollment process!

   

Navigate to the Enrollment Flows list and check your templates

2. Navigate to the Enrollment Flows list by selecting the Configuration choice from the menu on the left, and selecting the Enrollment Flows link from the CO Configuration menu. This action will display the list of Enrollment Workflows🚀 that have been defined for the CO⚙️ and any available template workflows that are available.
3. If you do not see a list of templates on your enrollment flow list, click the Add/Restore Default Templates link above the table to restore them. Each default flow has the word Template in its name.

Look at one of the templates

4. Take a peak at one of the template workflows to see what one of the forms contains. Click on the Name of the template or the Edit button for the template to display the edit form. We will not edit the template directly, so after you take a look, navigate back to the workflow list. (You can use the breadcrumbs above the page title to go back to the enrollment flows list.)

Create a new workflow from a template

For this example, we will be creating a ‘Self Signup with Approval’ workflow. This type of workflow is useful when you want to be able to individuals to sign up for an account for themselves, but want to approve each person before they are included in groups and provisioning.

5. Find the ‘Self Signup with Approval’ template on the list, and click the Duplicate button for the template to make your own version. This action will make a copy of the template, and will add the copy to the workflow list. You will be able to see which one was created by the name - it will be preceded by the words “Copy of”.

Self Signup with Approval workflow pattern follows the steps as we discussed in the last section:

• The person signing up (Enrollee) starts the enrollment flow by signing into COmanage using the IdP that we set up (you will use one of the personas on your user list from the Slack channel). This action will create the Petition (STEP 1)
• COmanage will set up the Org Identity⚙️ and CO Person⚙️ for the individual and attach them to the Petition (STEPS 3 & 4)
• COmanage will send an email back to the Enrollee (based on the email provided in the SAML attributes) for the Enrollee to confirm their email address. COmanage will process the confirmation when the Enrollee clicks on the link sent in the email address (STEP 5 & 6)
• A notification is sent to the group of people that are designated as Approvers to either approve or deny the enrollment (STEPS 10, 11 & 12)
• An approval notification is sent to the Enrollee (STEP 13)

6. Click the Edit button next to the newly copied workflow to edit it. The first thing that you should do is change the name and status of the workflow.

   When you are done, click the SAVE button at the bottom of the form to save these changes. Note that clicking the SAVE button on this form does not close the workflow that you are working with, allowing you to easily save your work along the way.

   ENROLLMENT FLOW FORM Field A. Name

   Change the Name field to something that will make it easy to know that this is the one that you are working with. You can just remove the words “Copy of " and " (Template)". The resulting name will be something like “Self Signup With Approval”.

   MORE DETAILS: This is the name of the workflow. These names will be displayed to the potential Petitioners who may use them to enroll people. The name that you choose should make sense to this audience. In addition, if you have several workflows that are similar, it is important to make the difference apparent in the name as well.

   ENROLLMENT FLOW FORM Field B. Status

   Change the Status field of the template from Template to Active. This action will make it possible to use the workflow when it is ready.

   MORE DETAILS: There are three options for the Enrollment Workflow🚀 status:

   • Active: This setting is required to be able to use the workflow
   • Template: This setting is used for reference workflows. COmanage provides several templates that can be used when getting started with working with enrollments
   • Suspended: This setting is used for workflows that are no longer or not yet active. This setting is useful if you are actively working on defining a workflow and don’t want it to be used yet.

Exploring the new menu picks

7. Now let’s look at the change this action made to the People sub-menu. On the menu on the left, click the People menu pick to expand the people sub-menu. Here you will notice that the Invite link has been replaced with two new ones, Enroll and CO Petitions

   

8. Click on the Enroll link to display the list of enrollment options. Here you will see all of the active Enrollment Workflows🚀 that are available; so far we have set up one. Notice that the template workflows do not appear on this list.

   If you click the BEGIN button, you will assume the role of the Petitioner and start the workflow. But, since we are setting up a self-signup enrollment, we won’t proceed this way (but feel free to click to see what happens!)

9. Click on the CO Petitions link to display all of the enrollment Petitions. There aren’t any yet, though we’ll come back to this screen to review and approve self-enrollments when we have some.

Enabling the start the workflow (STEP 1) - setting up the Petitioner

NOTE: We will be setting up the enrollment to follow the order of the steps that we just reviewed. Using this method necessitates a bit of jumping around in the screens, but more closely ties it to what you already know. Once you are familiar with Enrollment Workflows, you likely will setup your workflows by just filling out the workflow form and then configuring other needed components. We can try this alternate method next if there is time and interest.

With the self-sign up flow that we are creating, we want to restrict who can self signup to those who are already a part of our organization, i.e., they already have accounts that allow they to sign in using the Shibboleth instance that we set up. (i.e., any of the users listed on the Workshop Users list pinned to the Slack channel.) We’ll need to set up a few things to make this possible:

10. Configuring who can begin an enrollment: This process sets who can be a Petitioner for this Enrollment Workflow🚀.

    • Return to the enrollment flow list: CO Configuration menu > Enrollment Flows
    • Click the Edit button for the flow you have been configuring (Self Signup with Approval) - Ensure that you are working with the workflow with the status of Active, not with a Template

    ENROLLMENT FLOW FORM Field C. Petitioner Enrollment Authorization

    Set the value for the Petitioner Enrollment Authorization field to the value of Authenticated User. Click the SAVE button at the bottom of the form to save your change.

    MORE DETAILS: Notice that This field specifies the roles for the people who can serve as the Petitioner, i.e., that can execute this workflow. Various authorization levels can be selected to determine who may initiate a given Enrollment Flow. The possible values include:

    • Authenticated User: Any authenticated user, whether or not there is an existing CO Person record.
    • 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.

    Any setting other than None will trigger authentication if the user is not already authenticated.

Select the Enrollee (STEP 2) - selecting an existing CO Person for this enrollment

11. We do not need this step since we are creating a new CO Person⚙️ through this enrollment.

    ENROLLMENT FLOW FORM Field D. Identity Matching

    Set the Identity Matching field to None.

    MORE DETAILS: This field indicates how an existing CO Person⚙️ or Org Identity⚙️ is selected for this enrollment flow. 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. 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.

Select the Org Identity (STEP 3)

For this step in a Self Signup Enrollment, we do not want to select an existing Org Identity⚙️. Instead, we want to do the next two steps

12. Create an Org Identity from the Login Source for the person that just logged in

    Set up an Organizational Identity Source

    This process configures the information received from a Source so that it can be used to create and supplement the Organizational Identity Source Record⚙️ and Org Identity:gear.

    • Go to the CO Configuration menu by clicking the Configuration link in the menu on the left.
    • Click on the Organizational Identity Sources link to display the list of Sources that are configured. (at the moment there should be none.)
    • Click on the Add Organizational Identity Source link above the table to open a form to configure a Source. Here we will configure the Source for our IdP’s SAML assertions (Only a sub-set of the fields are listed here):

    Field	Value	Description
    Description	Environment by SAML assertion	This name should be descriptive of the source
    Plugin	EnvSource	We will use the EnvSource Plugin to configure and store the information received from a SAML assertion.
    Status	Active	The Source configuration can either be Active or Suspended
    Sync Mode	Manual	Indicates when/how information is synced between the Organizational Identity Source⚙️ and the Organizational Identity Source Record⚙️
    Sync on Login	CHECKED	Indicates that the Organizational Identity Source Record⚙️ should be synced from the Source during the login process

    • Click the ADD button to save the configuration. This action will provide the opportunity to match the fields from the SAML assertion (represented by “ENV” variables) to the fields in the Organizational Identity Source⚙️ object.
    • Since we will be using the ePPN as the identifier for login, check the Login checkbox for the Identifier (ePPN) field to make this configuration.
    • Click the SAVE button to store these changes.

13. Use this Source and Org Identity for this step

    Attach the Organizational Identity Sources so it can be used for this enrollment

    Since we are using the Organizational Identity Source⚙️ that we just configured to indicate those who have successfully logged in, we need to attach this configuration to the workflow.

    • Return to the enrollment flow list: CO Configuration menu > Enrollment Flows
    • Click the Edit button for the flow you have been configuring (Self Signup with Approval) - Ensure that you are working with the workflow with the status of Active, not with a Template
    • From the edit form for the workflow that you are configuring, click on the Attach Org Identity Sources at the top of the form to display the list of Sources that can be linked to this enrollment. (There shouldn’t be any listed yet.)

    

    • Click the Add Enrollment Source at the top of the table to add a new Source

    

    • Fill in the form that is presented. Here we will configure the Enrollment Source to indicate that it is being used for authentication for this Enrollment Petition:

    Field	Value	Description
    Organizational Identity Source	Environment by SAML assertion	We are using the Source configuration that we just set up (it will be the only one available so far)
    Org Identity Mode	Authenticate	We are using this Source for authentication purposes
    Order	blank	If there is more than one Enrollment Sources, you can set the order in which they are queried.

    • Click the SAVE button to save the Enrollment Source.
    • Using the breadcrumbs above the header, navigate back to your Enrollment configuration, “Self Signup With Approval”

Set the Petitioner Attribute (STEP 4)

14. Here we will set up what attributes will be collected to set up the CO Person⚙️ for this newly enrolled person.

    Edit the enrollment attributes

    • From the edit form for the workflow that you are configuring, click on the Edit Enrollment Attributes at the top of the form to display the list of Attributes that will be used to populate the CO Person:gear.

    

    • You will need to make changes to the list that you see. Since you already set up the Org Identity⚙️ using the Sources configuration, the values here need to connect to the CO Person⚙️ instead. In addition, you will need some adjustments to the default configurations:

      • COU - Click the Edit button to set a default value to be one of your COUs, ensure that the field is not modifiable (Unchecked), and make the field hidden (checked).

      

      • Name - Click the Edit button to change the Attribute to Name (Official, CO Person). You will also need to set the Environment Variable that you set up in the Source configuration, ENV_OIS_NAME, to be the default value for the Name.

      

      • Email - Click the Edit button to change the Attribute to Email (Official, CO Person). You will also need to set the Environment Variable that you set up in the Source configuration, ENV_OIS_MAIL, to be the default value for the Email.

      

      • Affiliation - Click the Edit button to set a default value (Member), ensure that the field is not modifiable (Unchecked), and make the field hidden (checked).

      

      • Organization - If you remember, we did not set up an explicit organization within SAML, so this attribute will be blank. Click on the Delete button to remove this attribute.

      • Group Membership - Add a group that you want to give members the option to be enrolled in.

        • Click on the Add Enrollment Attribute to add a new attribute
        • Give this attribute a descriptive name (for example, Group Member)
        • Select Group Member (CO Person) as the Attribute
        • Make this attribute optional (change Required to the value Optional) - this selection will allow the individual to choose upon enrollment if they want to be a Member or not or not.
        • Set the Default Value to the group that you want to give these self signup Enrollees the option to join.
        • Ensure that the values for Modifiable and Hidden (are Unchecked) - this will mean that the Enrollee will see this field, and will not be able to change the default value.
        • Click the SAVE button to save your choices

      

Send & Process Email Confirmation (STEPS 5 & 6)

15. Set up email confirmation to the address provided by the SAML attributes (the mailinator email). A URL is included in the email, and the Enrollee must click on the URL to verify the email address.

    • Return to the Workflow edit form for the Enrollment Flow that you are configuring.

    F. Require Confirmation of Email

    Set the Email Confirmation Mode to Review. Set the Require Enrollee Authentication to be checked. Set the Duplicate Enrollment Mode to be Flag as Duplicate so an administrator can review potential problems.

    MORE DETAILS: Confirm email addresses provided by sending a confirmation URL to the address. This basic confirmation step helps ensure accurate user data in COmanage. The following modes are supported:

    • Automatic: Verification takes places as soon as the enrollee clicks on the email link
    • None: No verification takes place
    • Review: After the enrollee clicks on the email link, the petition record is displayed for the enrollee to review before confirming or declining

    If this value is anything other than None, a set of fields appear to set up the communication that will be sent. You can customize this message and adjust how long the individual has to click on the link before the link is no longer valid (you set up the default when configuring your CO⚙️)

    Once the Enrollee has clicked on the URL to validate the email address, the enrollment flow continues

Send & Process the Approver Notification (STEPS 10, 11 & 12)

16. Ensure that the workflow requires approval and set who will process the approvals.

    E. Require Approval for Enrollment

    Set the Require Approval for Enrollment checkbox to be checked. Leave the Approvers as blank so the approval is done by CO Administrators👑 or COU Administrators👑

    MORE DETAILS: If administrator approval is required, a Petition must be approved before the Enrollee becomes active. (Members of this Group are authorized approvers (or else CO/COU admins by default)) To require approval, leave the check box selected.

Finalize the process (STEP 14)

17. Enable the Enrollee to be notified when approved when their Petition is approved.

    M. Notify On Approved Status

    Set the Notify On Approved Status checkbox to be checked.

    Notify enrollee when Petition is approved. While not necessarily required, this is generally a good idea to help manage the user’s expectations and keep them informed of the process.

---

A Note about Notifications and Messages

Enrollment Flows can trigger various Notifications at key stages, including confirmation, approval, and finalization. While these messages could be defined in each flow, the preferred approach is to define Message Templates, and then reference that template from the Enrollment Flow configuration.

We will not review message templates in depth in this workshop, though can discuss them more toward the end of the workshop if time and interest allow.

---