03-groups.md

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

# 4. About `CO Groups`:gear:

COmanage Groups (`CO Groups`:gear:) are defined at the `CO`:gear: level, and `CO Group Memberships`:gear: are attach to the `CO Person`:gear:. `CO Groups`:gear: provide group functionality enabling actions to be applied to all members of the group at the same time, for example, granting access to an application, joining a mailing list, or expiring membership at the same time. By default, any `CO Person`:gear: can create a new `CO Group`:gear:.

In some cases you will have more sophisticated provisioning needs than can be managed from within COmanage. In these cases, COmanage can be connected to Grouper. _Grouper is really for group management. Provisioning would most likely be another tool, of which there are several to choose from._

The attributes for a `CO Group`:gear: include:

* Name - name of the group
* Description - a helpful way to explain the purpose of the group
* Open vs Closed - An _open_ group is one that allows anyone to join. Participants can self-join, no administrator action is required. Memberships in a _closed_ group can only be set by the group owner.

# Difference between `CO Groups`:gear: and `COUs`:gear:

The major differences between `COUs`:gear: and `CO Groups`:gear: are

Condition | `COUs`:gear: | `CO Groups`:gear:
--------- | ------------ | -----------------
Object creation | Only `CO Administrators`:crown: can create `COUs`:gear: | Any `CO Person`:gear: can create a `CO Group`:gear:
Membership structure | `COU` memberships are connected to `CO Persons`:gear: via a `CO Person Role`:gear: | `CO Group`:gear memberships are connected directly to the `CO Person`:gear:
Object management | `COU`:gear: memberships can be automated using enrollment workflows and expiration Policies (to be explained in the next lesson) | `CO Group`:gear: membership management is simple (for example, manual management by the `CO Group`:gear: Owner, or self-opt in for open `CO Groups`:gear:)
Automatic groups | `COU`:gear: memberships imply `CO Group`:gear: memberships | _None_
Mailing lists | _None_ | Email Addresses can be attached to `CO Groups`:gear: via `CO Email Lists`:gear:

# Group Members & Administrators

A group member is simply a participant in the group. A `CO Person`:gear: can be a member, and owner, both, or neither.

The `CO Person`:gear: who creates a CO Group is automatically set as both a member and owner of the new group. A group owner has permission to add and remove members to and from the group, including closed groups. 

`CO Administrators`:gear: can manage any `CO Group`:gear: within their `CO`:gear:.

# Automatic/Members Groups

We have already been using groups in our examples as we set up administrative roles. COmanage automatically creates groups when creating `COs`:gear: and `COUs`:gear:. These automatic groups include:

* admins - the people who can manage the object and the `CO Persons`:gear: permissions within the object
* all members - all of the `CO Persons`:gear: associated with the object regardless of status (except for those with a Deleted status)
* active members - all of the `CO Persons`:gear: with an Active or Grace Period status associated with the object

# Nested Groups

**Nested Groups** allow the members of one group (the "nested" or source group) to automatically be included as members of another group (the "target" group). Nested Groups only confer group membership, they cannot be used to manage group ownership. Nested Groups are additive only, it is not possible to specify certain members to be excluded from the target group. Nested Groups do not imply any sort of hierarchy.

Nested Groups are not designed to scale to very large groups, and in particular manual reconciliation of a very large group with one or more Nested Groups may be problematic. Deployments experiencing problems working sophisticated group structures may wish to consider a solution such as Grouper.

# `CO Email Lists`:gear:

Email Lists are data structures that associate `CO Groups`:gear: and their memberships with listservs. COmanage does not provide actual message delivery capabilities, but rather maintains metadata about lists in order to provision list management software that support Email List objects. Currently supported email list-aware provisioners include:

* LDAP Provisioning Plugin (_I don't think this is implemented yet..._)
* Mailman Provisioning Plugin

`CO Email Lists`:gear: in COmanage include

* A name - The list name will typically become the left hand side of the list's email address
* A description to make the list purpose easier to understand
* A status of active or suspended

To manage the lists of people associated with the mailing list, `CO Groups`:gear: are used to indicate both list membership and roles for the list. The following are currently supported:

* Members
* Administrators
* Moderators

As an example, if you create a `CO Email Lists`:gear: called "Researchers" and attach the `CO Group`:gear: "Biologists" as the mailing list's **members group**, then any active `CO Person`:gear: who is a member of the Biologists group will be subscribed to the Researchers list in the mailing list management software. The actual privileges assigned to members, administrators, and moderators are determined by the specific mailing list software.

---

# Hands on - The organization model - CO Groups

![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). We'll also use the example people that you modeled in the last lesson ([ Modeling People :memo:](https://github.internet2.edu/lpaglione/COmg-CO310-modelPeople/blob/master/files/handouts/CO310-ModelingPeople.pdf)) for inspiration for the groups that you will create.

On the Modeling Organization :memo: worksheet, draw the relationship of a few groups that your example people are in. Some questions to consider:

* What `COs`:gear: are the groups in?
* Which of the groups will need mailing lists? 
* Do you need special groups to moderate and/or be administrators of mailing lists?
* Are any of these groups nested? 
* Who are the natural owners of the groups?
* Which groups are open (can be joined by anyone), and which are closed?

Draw an image showing the relationship of the groups to the other organizational structures that you created.

[10 min]

---

# Hands on - CO Group Settings

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

Now that you have a picture that describes the relationship of the groups to the other structures, select one or two of the groups, and plan them out more fully using the [Modeling Organization :memo:](/files/handouts/CO320-03_COGroupPlanningWorksheet.pdf) worksheet.

Here you will outline the metadata for each group, and will specify in more detail information about nested groups and/or email lists if needed.

If you specify that this group is part of a set of nested groups, also fill in a worksheet for the nested group(s).

If you specify that this group has an email list, fill in a worksheet for any related groups, for example, the group of administrators and/or moderators for the mailing list.

(10 min)

---

# Hands on - Create a `CO Group`:gear:

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

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

**REQUIRED ROLE**: any Active `CO Person`:gear:

## 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 `CO Group`:gear:

3. In the menu on the left, click on the **Groups** link to display the current list of `CO Groups`:gear:, including the automatic groups.

4. Click the **Add Group** link above the table to create a new group. Fill in the form using the values that you included in the metadata section of your worksheet, and click the **ADD** button to add the `CO Group`:gear:.

5. Repeat this process for any other `CO Groups`:gear: that you created worksheets for.

## Configure the `CO Group`:gear:

6. From the list of `CO Groups`:gear:, prepare to edit one of the groups that you just created by clicking on the **Edit** button in the **Actions** column on the right.

7. If you have indicated that your group is part of nested groups, click on the **Add Nested Group** link to configure the nesting relationship. When setting the relationship, you will need to start from the Target Group. On the worksheet, you will add the groups in section 6 to the group that you are editing. i.e., every group that you add, will have its members included in the group that you opened. This step assumes that you have already create the groups that you intend to nest.

![Screen Shot - click to add your nested groups](/fig/CO320-03_NestedGroups.png)

## Configure email lists

If you have indicated that your group should have an email list, you will configure it in the email lists section.

8. In the menu on the left, select **Email Lists**. Click the **Add Email List** link above the table to configure a new email list.

9. Using section C of your CO Group worksheet, fill in the form to configure your new email list. This step assumes that you have already the groups that will be used as members, administrators and moderators for the mailing list.

## Group membership 

We will be reviewing group membership as part of the enrollment workflows in the next lesson.

## Reconciling group memberships

In general, nested group memberships and memberships of automatic groups are updated in real time as needed. However, If an automatic group or a group with nested groups appears to have incorrect group memberships, the group may be manually reconciled to fix incorrect memberships. To reconcile a group, edit the desired group and click **Reconcile**.

Manually reconciling a group will not automatically reconcile related groups. For example, if Group A has nested Group B which in turn has nested Group C, and Group C is manually reconciled, it will probably be necessary to also manually reconcile Group B.

[15 min]

---

< TO BE UPDATED >

# Terminology & resources

## COmanage Objects

OBJECT | DESCRIPTION
------ | -----------
`CO Person`:gear: | the representation of a person in COmanage
`CO Group`:gear: | a specific COmanage organizational structure for representing certain collections of `CO Persons`:gear:

## Worksheets

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

## Slides

To be included

---

NEXT SECTION: [2. The COU](/_episodes/02-cous.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)