02-cous.md

---
title: "The COUs"
teaching: 10
exercises: 20
questions:
- "Question here"
objectives:
- "List the objectives"
keypoints:
- "List the key takeaways for the episode"
---

As a collaboration grows in size, it may be useful to create various structures to allow for delegation of person management operations and representation of organizational hierarchy. COmanage supports this through the concept of Collaborative Organization Units (COUs), or COUs. COs can support one or more COUs.

# 2. Collaborative Organization Units (`COUs`:gear:)

Collaborative Organizations Units (or `COUs`:gear:) allow you to define an organizational structure within a CO. While many organizations have natural groups within them, the reason that you would divide your CO into COUs are because there are differences across your CO that necessitates different policies in one or more of the following:

* How individuals join and/or leave the group (_"collaboration" instead of group?_)
* There are different rules about how applications get provisioned or deprovisioned
* Who manages person membership and privileges in the group
* The information stored or used about members of the group 

If your collaboration–a single entity with common goals–has unique requirements among the different groups and/or departments regarding how participants will join those parts of your collaborations, then, you have a CO that contains COUs. If you have only one common set of policies that define how individuals are added or removed from the CO, then you _probably?_ do not have COUs even though you may have groups for simple access control.

`COUs`:gear: may also be used to represent recognized groups of collaborators like departments, divisions, projects; or they may be related to the privileges that those in the group may have, for example, alumni or parents. (The primary purpose of a `COUs`:gear:, however, is to allow for delegation of person management operations. _In the "also" exmaples, it's still delegation of person management operations_)

`COUs`:gear: can be organized in a hierarchy, or a flat structure can be used where each `COUs`:gear: has only the `CO`:gear: as a parent.

# `CO Person Roles`:gear: - a.k.a., associating `CO Persons`:gear: with `COUs`:gear:

Any `CO Person`:gear: in the `CO`:gear: can be part of any of the `COUs`:gear: in the `CO`:gear:. This connection happens through an object called a `CO Person Role`:gear:.

The attributes (information) stored in the `CO Person Role`:gear: object typically include

* Link to the associated `CO Person`:gear: who is connected to the `COU`:gear:
* Link to the person who is sponsoring the `CO Person`:gear:. Sponsors are usually used in relation to guest systems. We'll talk more about sponsors when we talk about enrollment workflows.
* Status
* Role-specific information about the person
  * affiliation (eduPerson)
  * organization, department, & title
* List of physical addresses / phone numbers

These roles also can include information about the percent time the registered person is allocated to this role. (_This is an extended attribute, it is not configured by default._)

`CO Persons`:gear: can have any number of `CO Person Roles`, usually one for each `COU` that the person is part of.

## CO Person Role Status

As with `CO Persons`:gear:, each `CO Person Role`:gear: has a status related to it. The list of possible values is identical to that we reviewed in the previous lesson.

When a `CO Person`:gear: is connected to one or more `CO Person Roles`:gear:, the status of the `CO Person`:gear: is calculated from that of the associated Roles based on the "most preferred" status. "Most preferred" is currently defined as the order in the status table (repeated here from the discussion about `CO Person`:gear: status in the previous lesson.) 

Active statuses are most preferred, followed by expired statuses, followed by invitation statuses.

_Maybe again filter this list like for CO Person status_

Preference | Status | Description
---------- | ------ | -----------
1 | Active | Person or Role is an active member of the organization or collaboration
2 | GracePeriod | Primary association with the organization has ended, but services have not yet been deprovisioned
3 | Suspended | Association with the organization has been (manually) temporarily suspended
4 | Expired | Valid through date has been reached
5 | Approved | 
6 | PendingApproval | The enrollment flow petition is pending approval
7 | Confirmed | 
8 | PendingConfirmation | An invitation or email confirmation was sent via an enrollment flow 
9 | Invited | An invitation was sent via default enrollment 
10 | Pending | 
11 | Denied | The enrollment flow petition was denied 
12 | Declined | The invitation sent via default enrollment was declined 
13 | Deleted | 
14 | Duplicate | The record is a duplicate of another 

# Administrator Roles

## `COU Administrators`:crown:

`COU Administrators`:crown: can be defined for each `COU`:gear:, giving them the ability to perform lifecycle management operations on the `CO People`:gear: who have `CO Person Roles`:gear: associated with the COU that they manage.

---

# Hands on - The organization model - COUs

![Interactive system activity](/assets/img/hands-on-keyboard.png)

Let's add to the organizational model that we're using as an example and its related worksheet, [Modeling Organization :memo:](/files/handouts/CO320-ModelingOrgs.pdf). 

_[INSTUCTOR NOTE: it's a good idea to see which workshop participants have natural COUs in their organizations, and use this opportunity to clarify the purpose of a COU. If no one has natural COUs, the interactive part of this episode can be skipped OR the participants can go through this exercise, creating two COUs and using the content below to highlight a common use case for multiple COUs. If there is time, it is best to keep this section in.]_

Your organization may not need more than one COU. _It probably doesn't make sense to have exactly one COU, at that point just use a CO without COUs_

On this worksheet you will see spaces to describe two COUs. Write the name of two of your COUs in these sections. If your organization doesn't have COUs, lets use these two as examples:

_For a VO oriented example, maybe "Researchers" and "Administrators"?_

field | COU #1 | COU #2
----- | ------ | ------
Name | Main university | Medical school
Description | A sub-unit containing the people and policies related to the **main university**. This is a top-level sub-unit. | A sub-unit containing the people and policies related to the **university's medical school**. This is a top-level sub-unit.
Parent COU | _[blank]_ | _[blank]_

You can optionally include this information on the [COU Planning Worksheet :memo:](/files/handouts/CO320-02_COUPlanningWorksheet.pdf)

[5 min]

---

# Hands on - Create `COUs`:gear:

![Interactive system activity](/assets/img/hands-on-keyboard.png)

We will now implement what you have specified on your worksheets.

## Sign into Registry

1. Using the credentials you specified as part of the COmanage setup (or the `CO Administrator`:crown: that you established in the last section), sign into the system.
2. Navigate to your `CO`:gear:. If necessary, select your `CO`:gear: by selecting **Collaborations** from the menu on the left, and then selecting your Collaboration.

## Create a `COU`:gear:

**REQUIRED ROLE**: `CMP Administrator`:crown: OR `CO Administrator`:crown:

3. In the menu on the left, click on the **Configuration** link to see the list of customizations that you can make. Click on the link labeled **COUs** to see the list of `COUs`:gear: for the `CO`:gear:.

4. Click the **Add a New COU** link above the table to create a new COU. Fill in the form using the values that you included on your worksheet and click the **ADD** button to add the `COU`:gear:.

5. Repeat for the second `COU`:gear:. When you return to the COU List, you will see the two COUs that you created. They can be edited from this page if needed.

## Establish a `COU Administrator`:crown:

Each COU can have its own `COU Administrator`:crown:. Manually designating the administrators is a process similar to the one that we followed to create a `CO Administrator`:crown:.

6. Ensure that you are signed in and are looking at the CO that you created. From the COU list page, you can use the breadcrumb links near the top of the screen to navigate back to your CO. There are two common paths for manually designating `COU Administrators`:crown:. We will use a different process for each of the COUs that we created.
7. From the `CO Person`:gear:
  * From the menu on the left select **People** > **My Population** to see the list of `CO People`:gear: in your `CO`:gear:
  * Click the **Edit** button next to the name of the person you set up in the previous lesson.
  * Scroll to the **Groups** section, and click the **Manage Group Memberships** link. On the list of groups you will now see admins, active, and all groups for each of your `COUs`:gear: as well as those for the full `CO`:gear:
  * Make this person the owner of the admin group for your first `COU`:gear: - check the **Owner** checkbox for (only) the first `COU`:gear: that you created. Click the **SAVE** button to save these changes.
8. From the groups list:
  * From the menu on the left, select **Groups**
  * Click the **Edit** button for the admin group for the second `COU`:gear: that you created to display the group management page.
  * Scroll to the bottom of the page to see the list of group members. Click the **Manage Group Memberships** link to see a list of people that you can add to the group.
  * From the group membership management list, check the "Member" permission to make this person a member of the admin group for the second `COU`:gear: that you created. Click the **SAVE** button to save this change.

![Screen shot - Manage Group Membership](/fig/CO320-02_ManageGroupMembers.png)

CONGRATULATIONS!! You have just created and configured your first COUs.

[15 min]

---

# Terminology & resources

## COmanage Objects :gear:

OBJECT | DESCRIPTION
------ | -----------
`COU`:gear: | an organizational structure within a CO that differs in how individuals join and/or leave the group, how applications get provisioned or deprovisioned, who manages person membership and privileges in the group, or in the information stored or used about members of the group.
`CO Person`:gear: | the representation of a person in COmanage
`CO Person Role`:gear: | the representation of a person's role in COmanage. This object describe the person's role with certain collections of people within your organization or collaboration. These objects are attached to :gear: `CO Person` objects; there may be any number of Roles.

## CO Person Roles :crown:

ROLE | DESCRIPTION
---- | -----------
`COU Administrators`:crown: | Individuals that have the ability to perform lifecycle management operations on the `CO People`:gear: who have `CO Person Roles`:gear: associated with the `COU`:gear:.

## Worksheets

WORKSHEET | DESCRIPTION
--------- | -----------
[Modeling Organization :memo:](/files/handouts/CO320-ModelingOrgs.pdf) | Planning sheet used in this lesson for understanding how the parts of the COmanage Organization fit together.
[COU Planning Worksheet :memo:](/files/handouts/CO320-02_COUPlanningWorksheet.pdf) | Planning worksheet for creating your CO(s). Contains all of the configuration sections at a glance.

## Slides

To be included

---

PREVIOUS SECTION [1. The CO](/_episodes/01-co.md)

NEXT SECTION: [3. About Groups](/_episodes/03-groups.md)

LESSON OVERVIEW: [CO320 - Modeling Your Organization in COmanage](../index.md)

WORKSHOP OVERVIEW: [COmanage Workshop: Managing Identities & Collaborations](https://github.internet2.edu/lpaglione/COmg-trainingOverview/blob/master/README.md)