HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket


In the Optimizely Community API, a group is represented with the **Group** class.

An instance of the Group class is constructed with a name (string) and a description (string). An example of this construction is below:



Groups are managed through a service implementing the interface `IGroupService`. This service provides the ability to persist, retrieve, update, and remove groups that you define.

## Access an IGroupService

When the Groups feature is installed to an Optimizely CMS site with the feature's site integration package, you can get an instance of this service from the inversion of control (IoC) container.

Example:



When the feature is installed to a non-Optimizely CMS site, you can get an instance of a service from the default `factory` class provided in the package.

Example:



## Add a group

To add a group, use the `Add(Group)` method of the `IGroupService`. This method accepts an instance of the `Group` class and returns a reference to a new instance of that class, which has been populated with any additional, system-generated, data (for example, a unique ID).



In the above example, the request to add a group is invoked synchronously. An example of adding a group asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Update a group

To update a group, which was previously added through the platform, use the `Update(Group)` method of the `IGroupService`.



If the `Group` to be updated does not exist, a `GroupDoesNotExistException` is thrown.

In the above example, the request to update a group is invoked synchronously. An example of updating a group asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



If the identified `Group` is a Composite Group, its name and description are updated and its associated extension data remains intact. For information on Composite Groups, see Extending Groups with Composites.

## Retrieve a group

To retrieve a specific instance of a `Group`, which has previously been added through the platform, use the `Get(GroupId)` method of `IGroupService`. This method accepts an instance of the `GroupId` class, which identifies the `Group` to retrieve. It returns the instance of the `Group` class corresponding to that identifier.



If the requested `Group` cannot be found, a `GroupDoesNotExistException` is thrown.

In the above example, the request to retrieve a group is invoked synchronously. An example of retrieving a group asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



To retrieve a collection of groups, which were previously added through the platform, use the `Get(Criteria<GroupFilter>`) method. This method accepts an instance of `Criteria`, which contains the specifications necessary to retrieve the desired groups.

The `Filter` property of the `Criteria <GroupFilter>` class accepts an instance of the `GroupFilter` class. This class contains the specifications that let you refine the result set of groups that you want to retrieve.

The properties of the `GroupFilter` include:

  • `Name` – Assigning a value (`String`) to this property refines a result set to `Groups` with the specified name.

  • `GroupIds` – Assigning a value (`IEnumerable<GroupId>`) to this property refines a result set to `Groups` with IDs included in that collection.

The specifications of the `GroupFilter` may be applied in conjunction with one another. Each specification which is assigned a value in the filter further refines the result set (that is, a logical AND).

The example below demonstrates the retrieval of a result page of `Groups`, which exist in a set of identified groups.



In the above examples, the request to retrieve groups is invoked synchronously. An example of retrieving groups asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



The `GroupSortFields` class exposes a set of fields upon which a result set of groups may be ordered. These fields may be applied in the construction of sorting rules that you associate with your criteria. These fields include:

  • `GroupSortFields.Created`

  • `GroupSortFields.Id`

  • `GroupSortFields.Name`

The example below demonstrates how to apply sorting rules to order a result set by name, alphabetically from A-Z. A fallback rule, subsequently ordering results with the same name according to when they were created from newest to oldest, is also added.



For more details regarding the use of criteria, including information on paging and sorting, see _Criteria_ in [Discovering the platform](🔗).

## Remove a group

To remove a specific instance of a group, which has previously been added through the platform, use the `Remove(GroupId)` method. This method accepts an instance of the `GroupId` class, which identifies the `GroupId` to be removed. The result is the deletion of the group corresponding to that ID.


  • If members or content are still associated with the group, the group cannot be deleted.

  • If the group being removed has existing members in the system when the remove operation is attempted, a `MemberStillExistsException` is thrown.

  • If the group being removed has existing content associations in the system when the remove operation is attempted, an `AssociationStillExistsException` is thrown.

Remove existing members and content before removing a group.

In the above example, the request to remove a group is invoked synchronously. An example of removing a group asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



## Extend groups with composites

A group, in its simplest form, is just a named aggregation of users and content. You may need to associate additional information with `Groups` to further describe and shape them. For example, if you are leveraging groups within your application to represent an athletic team, you might capture information describing the team's location, mascot, or the date when it originally formed.

Like many of the other Optimizely Community API features, you can extend a `Group` with data of your design by creating a Composite. See _Composites_ in [Discover the platform](🔗).

### Add a composite group

To save a Composite Group which you have defined, use the `Add<TExtension>(Group, TExtension)` method of the `IGroupService`. This method accepts an instance of the Group class and an instance of `TExtension`. It returns a new instance of `Composite\<Group,TExtension>`.

Consider the following class, which represents a sample of extension data:



In the example below, a group is composed with an instance of this extension class:



In the above example, the request to add a group is invoked synchronously. An example of adding a group asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Update a composite group

To update a specific instance of a Composite Group, which was previously added through the platform, use the `Update(Group,TExtension)` method of the `IGroupService`.

Consider the following class, which represents a sample of extension data:



In the example below, an existing group is updated with a new instance of this extension class:



If a Group with the specified ID cannot be found, a `GroupDoesNotExistException` is thrown.

In the above example, the request to update a group is invoked synchronously. An example of updating a group asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Retrieve a composite group

To retrieve a specific instance of a Composite Group, which was previously added through the platform, use the `Get<TExtension>(GroupId)` method. This method accepts an instance of the `GroupId` class, which identifies the `Group` to retrieve. It returns the instance of the `Composite\<Group,TExtension>` class corresponding to that identifier.



If a Composite Group with the specified ID and extension type cannot be found, a `GroupDoesNotExistException` is thrown.

In the above example, the request to retrieve a group is invoked synchronously. An example of retrieving a group asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



To retrieve a collection of Composite Groups, which were previously added through the platform, use the `Get<TExtension>(CompositeCriteria\<GroupFilter,TExtension>)` method. This method accepts an instance of `CompositeCriteria\<GroupFilter,TExtension>`, which contains the specifications to retrieve the desired Groups.

The `Filter` property of the `CompositeCriteria\<GroupFilter,TExtension>` class accepts an instance of the `GroupFilter` class. This class contains the specifications that let you refine the result set of `Groups` that you want to retrieve.

The `ExtensionFilter` property of the `CompositeCriteria\<GroupFilter,TExtension>` class accepts a `FilterExpression`, which lets you specify a Boolean expression to further refine the result set by values represented within your extension data. For information on this type of filter, see _Composite Criteria_ and _Filter composites_ in [Discovering the platform](🔗).

Consider the following class, which represents a sample of extension data:



In the example below, a page of `Groups` composed with AthleticTeam is retrieved, where the Established property of that extension data contains a date after "1/1/2015".



In the above example, the request to retrieve groups is invoked synchronously. An example of retrieving groups asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



The fields of your extension data may also be applied when sorting a result set. The example below demonstrates the use of an extension data field in the definition of a sorting rule.