Page is a Work in Progress
Characteristics found in this use case:
- A single platform managed by a VO with only one CO and two COUs.
- Enrollment processes are self-sign up for the majority of users; researchers use an invitation-based enrollment workflow.
- Individuals use primarily social identity providers.
- Apps include email lists and project-specific applications.
- Administrators need to use audit capabilities for grant reporting on demographics and usage.
Before you login to the COmanage Registry to start configuring the environment for your VO, consider the following questions:
- Do you want someone to approve the requests to join, or do you want this to be purely self-signup? If the former, that increases the workload of the administrator, but if you do purely self-signup, you may have an increase in duplicate enrollments or other bad data added to the system.
Step-by-step Guide to Creating a New CO
Once the collaboration platform and its components have been installed and your first administrative users added, it's time to start configuring it to support your collaboration(s). The first step is to create a CO.
Go to the COmanage Registry URL (address TBD for your site; for the sake of this documentation, this will be https://comanage.example.net/registry).
Login. Note that your account will need to be a Platform Administrator account in order to create new COs.
At the top of the screen, there should be a drop down menu called 'Platform'. Click on the 'CO' option in that menu. This will take you to the "COmanage Registry: COs" page
On the COs page, click on "Add CO".
- Enter in the name of the CO, a brief description, and if you are ready for this to be immediately active, leave the status as 'Active'.
For more information on setting up a CO, see Setting Up Your First CO in the Technical Manual.
Step-by-step Guide on How to Configure a CO
After a CO has been created, there are a variety of options available to configure it to meet the needs of a particular collaboration. Adjust the configuration to meet the needs of your particular collaboration.
- On the COmanage Registry home page, there is a table of COs. Click on the one to be configured.
- On the CO page, click on the drop down menu, 'Configuration' and then 'CO Settings'.
- Review the default settings and modify based on the needs of your CO.
CO Configuration Options
| Parameter | Description | Default setting |
|---|---|---|
| Disable Expiration | Disable automatic (scheduled) expirations. This setting does not impact manual expirations | |
| Enable Normalization | Data entered into a form field is standardized into a structure more consistent with human language. For additional details, see Normalizing Data in the COmanage Technical Manual. | On |
| Enable NSF Demographics | COmanage Registry supports the collection of NSF Demographic Information. This information is attached to the CO Person record, meaning it is unique per-CO. For additional details, see Collecting NSF Demographics in the COmanage Technical Manual. | Off |
| Invitation Validity (Minutes) | When confirming an email address (done via an "invitation"), the length of time (in minutes) the confirmation link is valid for (default is 1 day = 1440 minutes) | 1440 |
| Address Required Fields | This sets the minimum information needed for a person's address within a CO. | Street |
| Name Required Fields | This sets the minimum information needed for a person's name within a CO. | Given Name |
| Name Permitted Fields | This sets all the allowed information for a person's name within a CO. | Honorific, Given, Middle, Family, Suffix |
| Terms and Conditions Mode | How to handle Terms and Conditions at login, if any are defined. See Terms and Conditions | Do Not Enforce |
| Sponsor Eligibility Mode | Which CO People are eligible to sponsor CO Person Roles | CO or COU Admin |
Step-by-step Guide to Configuring the Self Signup Enrollment Flow
Before a new administrator can be added and before people can begin to access the tools available to the CO, the CO must have enrollment flows configured and users invited to the system.
A self-registration enrollment flow is designed to require as little intervention from an administrator as possible. After the enrollment flow is created, a common URL is available that can be posted to a website, emailed to a mailing list, or otherwise made broadly available so that anyone can request to join. Part of the work flow includes whether or not an administrator needs to approve the petitions as the final step in allowing people to join the collaboration.
For more detail on enrollment flows and their details, see Registry Enrollment Flow Configuration in the COmanage technical manual.
These instructions assume a CO has been created by the platform administrator.
- From the COmanage Registry home page, click on the CO listed in the table.
- In the drop down menu under the name of the CO, click on 'Configuration' and then 'Enrollment'.
- If the resulting page is blank, click on 'Add/Restore Default Templates'.
- Choose the 'Self Signup with Approval' template to duplicate by clicking on the 'Duplicate' link next to the template.
When you have created a copy of that enrollment flow, click on Edit, then rename the enrollment flow and review the options.
You will need to change the status of the new enrollment flow to 'Active'. Renaming it is also a good idea.
These are the default templates. Note that they are best thought of as starting points; customization is recommended in accordance with the needs of a given deployment.
| Default flow | Description |
|---|---|
| Account Linking (template) | An Account Linking enrollment flow is used by an end-user (in this case, making them the 'Petitioner') who is already in the CO when they want to link an additional organizational identity to their record. |
| Additional Role (template) | |
| Conscription with Approval (template) | A Conscription enrollment flow is used by an administrator (in this case, making the administrator the 'Petitioner') to add a new user (an 'Enrollee'), possibly with CO admin approval but without enrollee confirmation. |
| Invitation (template) | An Invitation enrollment flow is used by an administrator (in this case, making the administrator the 'Petitioner') to add a new user (an 'Enrollee'), possibly with CO admin approval, and always with enrollee confirmation. |
| Self Signup with Approval (template) | In this case, the end-user is also Petitioner; they can follow a workflow and invite themselves to the CO with no approval process required before activation. |
Options within the Self Signup with Approval Enrollment Flow
| Name | You must rename the enrollment workflow. The name should be unique and reasonably self-explanatory. In this case, simply removing the word template may be sufficient. |
| Status | This must be changed from "Template" to either "Active" (if you are ready for users to start using it) or "Suspended" (if you would like to hold off on having potential users start enrolling). |
| Petitioner Enrollment Authorization Authorization required to execute this enrollment flow, see Enrollment Authorization for details | By default in this workflow, this is set to "none" as no particular authorization is required to run this enrollment workflow; anyone can use it at any time. |
| Identity Matching Identity Matching policy for this enrollment flow, see Identity Matching for details | For this type of enrollment workflow, set this to "Self". |
Require Approval For Enrollment (Members of this Group are authorized approvers (or else CO/COU admins by default)) | To require approval, leave the check box selected. |
| Require Confirmation of Email Confirm email addresses provided by sending a confirmation URL to the address | This basic confirmation step helps ensure accurate user data in the registry. |
| Invitation Validity (Minutes) When confirming an email address (done via an "invitation"), the length of time (in minutes) the confirmation link is valid for (default is 1 day = 1440 minutes) | The invitation itself should be time-bounded for basic security reasons. The default is to have this be one day, but if your use case suggests longer is better, you can configure it that way. |
| Subject For Verification Email Subject line for email message sent as part of verification step. | This is configurable, and along with the email body and from address, should be adjusted for your collaboration. COmanage can use regular expressions to automatically fill in some of the detail (like the CO name). Remember that this email will need to get passed spam filters. |
| Verification Email Body Body for email message sent as part of verification step. Max 4000 characters. | This is configurable, and along with the email subject and from address, should be adjusted for your collaboration. COmanage can use regular expressions to automatically fill in some of the detail (like the CO name). Remember that this email will need to get passed spam filters. |
| Require Enrollee Authentication Require enrollee to authenticate in order to complete their enrollment | This is another verification step which, by default, is turned off in this workflow. |
| From Address For Notifications Email address notifications will come from | This is configurable, and along with the email subject and body, should be adjusted for your collaboration. COmanage can use regular expressions to automatically fill in some of the detail (like the CO name). Remember that this email will need to get passed spam filters. |
| Notification Group Group to notify on new petitions and changes of petition status. (This is an informational notification. Separate notifications will be sent to approvers and enrollees, as appropriate.) | While one person or group may be responsible for approving petitions, a larger group may be interested to see when the changes in status for incoming users. |
| Notify On Approved Status 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. |
| Subject For Approval Email Subject line for email message sent after Petition is approved. | This is configurable, and along with the email subject and body, should be adjusted for your collaboration. COmanage can use regular expressions to automatically fill in some of the detail (like the CO name). Remember that this email will need to get passed spam filters. |
| Approval Email Body Body for email message sent after Petition is approved. Max 4000 characters. | This is configurable, and along with the email subject and body, should be adjusted for your collaboration. COmanage can use regular expressions to automatically fill in some of the detail (like the CO name). Remember that this email will need to get passed spam filters. |
| Introduction Optional text to display at the top of a Petition form | This text might offer the enrollees some more information about the CO and explain the registration process. |
| Conclusion Optional text to display at the bottom of a Petition form, before the Submit button | This text might inform users of the next steps for participating in the collaboration, including pointers to relevant URLs or descriptions of mailing lists |
| Terms and Conditions Mode* How to handle Terms and Conditions at enrollment, if any are defined. See Terms and Conditions | If your collaboration has particular end user agreements or requirements on the intellectual property ownership of information, this may be a useful feature for you to apply to your VO. |
| Submission Redirect URL URL to redirect to after Petition is submitted by someone who is not already in the CO. | |
| Confirmation Redirect URL URL to redirect to after the email address associated with the Petition is confirmed. Leave blank for account linking enrollment. | |
| Ignore Authoritative Values Ignore authoritative values for this attribute, such as those provided via environment variables, SAML, or LDAP |