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


A user may subscribe to resources or other users within your application. When that occurs, the system generates a record of activities related to those resources and users. That information can subsequently be filtered and retrieved in the form of a feed.

In the Optimizely Community API, subscriptions are managed through a service implementing the interface `ISubscriptionService`. This service provides the ability to persist and retrieve subscriptions that you define.

## Manage subscriptions

In the Optimizely Community API, subscriptions are managed through a service implementing the interface `ISubscriptionService`. This service provides the ability to persist, retrieve, and remove subscriptions.

## Access an ISubscriptionService

When the Activity Streams feature is installed to an Optimizely Content Management System (CMS) site, with the feature's site integration package, you can get an instance of the Subscription 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:



## Subscribe to a target

If a subscriber wants to follow the activity occurring on a resource, such as a page or a product within the application, or the activities of another user within the application, use the `Add(Subscription)` method. This method accepts an instance of the `Subscription` class, which identifies the subscribing user and the target to which they want to subscribe. An instance of the `Subscription` class can be created using the specifications below:

  • `Subscriber` – Reference of the user subscribing to a target entity in an application.

  • `Target` – Reference of the target entity being followed by the subscriber.

  • `Type` – An optional subscription type for categorizing subscriptions that can be used for filtering purposes later. If a subscription type not is specified while creating a `Subscription` instance, a default value of an empty string is assigned to the subscription type.

Example:



If a subscription already exists for the specified combination of subscriber and target resource to be followed, a `DuplicateSubscriptionException` is thrown.

Note

You cannot add a subscription with the same combination of subscriber and target as that of an existing subscription, even if the subscription being added has a different subscription type. In other words, the target of a subscription represents an application-wide, unique reference. If your application requires subscribing to entities such as users and resources, design your reference scheme such that each reference can be represented uniquely.

For more information on how to construct `References`, including best practices, see _References and IDs_ in [Discover the platform](🔗).

If a subscriber wants to follow the activities of another user within the application, use the example below.

Example:



If a subscription already exists for the specified combination of subscriber and target user to be followed, a `DuplicateSubscriptionException` occurs.

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



## Retrieve subscriptions

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

The Filter property of the `Criteria<SubscriptionFilter>` class accepts an instance of the `SubscriptionFilter` class. This class contains the specifications, which allow you to refine the result set of `Subscriptions` that you want to retrieve.

The properties of `SubscriptionFilter` include:

  • `Target` –Assigning a value (`Reference`) to this property refines a result set to subscriptions that follow the identified target.

  • `Subscriber` – Assigning a value (`Reference`) to this property refines a result set to subscriptions where the identified user is the subscriber.

  • `Type` – Assigning a value (`SubscriptionType`) to this property refines a result set to subscriptions where the identified type is the subscription type that was specified when the subscription was created.

The specifications of the `SubscriptionFilter` 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 following example demonstrates the retrieval of a result page of subscriptions for a particular subscriber.



In the next example, a result page of subscriptions targeting a particular followed user is retrieved.



In the next example, a result page of subscriptions targeting a particular followed resource is retrieved.



To retrieve subscriptions based on the previously-set subscription type, use the `Type` property of the `SubscriptionFilter`. The following example demonstrates the retrieval of a result page of subscriptions for a particular subscriber and subscription type.



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



## Order results

The `SubscriptionSortFields` class exposes a set of fields, upon which you can order a result set of subscriptions. You can apply these fields in the construction of sorting rules that you associate with your criteria. These fields include:

  • `SubscriptionSortFields.Created`

  • `SubscriptionSortFields.Subscriber`

  • `SubscriptionSortFields.Target`

  • `SubscriptionSortFields.Type`

  • `SubscriptionSortFields.Id`

The following example demonstrates how to apply sorting rules to order your result set by subscriber, alphabetically in ascending order. A fallback rule, subsequently ordering results with the same subscriber according to the date of their creation, is also added.



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

## Remove a subscription

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



You can remove one or more existing subscriptions using the additional overload of the `Remove` method, `Remove(Criteria<SubscriptionFilter>`), which removes any subscription (user or resource) identified by the specified `SubscriptionFilter`.

For more information about the construction of Criteria, see _Retrieving subscriptions_ in [Activity streams](🔗).

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