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


A group is a named aggregation of users and content. You associate resources with a group by adding them as an association.

In the Optimizely Community API, an association is represented with the `Association` class.

Associations are managed through a service implementing the interface `IAssociationService`. This service provides the ability to persist, retrieve, and remove Associations that you define.

For information on the Optimizely Community Async API, see _Async API_ in [Discovering the platform](🔗).

## Access an IAssociationService

When the `Groups` feature is installed to an Optimizely Content Management System (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 within the package.

Example:



## Add an association

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



If the identified group cannot be found, a `GroupDoesNotExistException` is thrown.

If the association already exists, a `DuplicateAssociationException` is thrown.

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



## Validate an association

To validate that a resource is an association of a group, use the `IsAssociated(GroupId,Reference)` of the `IAssociationService`. This method accepts an instance of the `GroupId` class, identifying the target group, and an instance of the `Reference` class, identifying the target resource. The method returns a Boolean, indicating whether or not the identified resource is an association of the identified group.



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



## Remove an association

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



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



## Retrieve an association

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



If the requested `Association` cannot be found, an `AssociationDoesNotExistException` is thrown.

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



You can retrieve a collection of associations, which have previously been added through the platform, by using the `Get(Criteria<AssociationFilter>)` method. This method accepts an instance of `Criteria<AssociationFilter>`, which contains the specifications necessary to retrieve the desired `Associations`.

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

The properties of the `AssociationFilter` include:

  • `Group` – Assigning a value (`GroupId`) to this property refines a result set to Associations of the identified group

  • `Resource` – Assigning a value (`Reference`) to this property refines a result set to Associations associated with the identified resource.

The specifications of the `AssociationFilter` 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 Associations which were assigned to a group.



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



The `AssociationSortFields` class exposes a set of fields upon which a result set of associations may be ordered. You can apply these fields to construct sorting rules that you associate with your criteria. These fields include:

  • `AssociationSortFields.Group`

  • `AssociationSortFields.Id`

  • `AssociationSortFields.Resource`

The example below demonstrates how to apply sorting rules to order your result set by group ID, in ascending order.



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

## Extend associations with composites

An `Association` is simply a relationship between a resource and a group. You may need to associate additional information with Associations to further describe and shape them. Continuing an earlier example, where a group represents an athletic team, an association may be leveraged to associate relevant documents (roster, scorecards, and so on) with the team. You might want to capture information describing or categorizing those documents.

Just as you can extend a `Group` with data of your design, an Association may also be extended by creating a Composite. see _Composites_ in [Discovering the platform](🔗).

### Add a composite association

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

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



In the example below, an `Association` is composed with an instance of this extension class:



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



### Update a composite association

To update a specific instance of a Composite Association, which was previously added through the platform, use the `Update<TExtension>(AssociationId, TExtension)` method of the `IAssociationService`. This method accepts an instance of the `AssociationId` class and an instance of `TExtension`. It returns a new instance of `Composite\<Association,TExtension>`.

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



For this example, the `IAssociationService` must be properly implemented.



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



### Retrieve a composite association

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



If a Composite Association with the specified ID and extension type cannot be found, an `AssociationDoesNotExistException` is thrown.

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



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

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

The `ExtensionFilter` property of the `CompositeCriteria\<AssociationFilter,TExtension>` class accepts a `FilterExpression` that lets you specify a Boolean expression to further refine the result set by values represented in your extension data. For information on this type of filter, see _Composite criteria_ and "Filtering composites\* in [Discover the platform](🔗).

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



In the example below, a page of Associations composed with TeamDocument is retrieved, where the document is categorized as a lineup:



In the above example, the request to retrieve associations is invoked synchronously. An example of retrieving associations 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 in the sorting of your result set. The example below demonstrates the use of an extension data field in the definition of a sorting rule.



For details about criteria, including information on paging and sorting, see _Criteria_ in [Discover the platform](🔗).