Subscriptions

13 min

A user may subscribe to resources or other users within your application. The system records activities related to those resources and users when they occur. That information can subsequently be filtered and retrieved as 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 on 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:

var subscriptionService = ServiceLocator.Current.GetInstance<ISubscriptionService>();

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

Example:

var factory = new EPiServer.Social.ActivityStreams.DefaultActivityStreamsFactory();
var subscriptionService = factory.CreateSubscriptionService();

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 is not specified while creating a Subscription instance, a default value of an empty string is assigned to the subscription type.

Example:

ISubscriptionService subscriptionService;
// ...

var subscriber = Reference.Create("user://identifier/for/a/user");
var targetResourceToFollow = Reference.Create("resource://identifier/for/a/resource");
var subscriptionType = SubscriptionType.Create("resource");
var subscription = new Subscription(subscriber, targetResourceToFollow, subscriptionType);

subscriptionService.Add(subscription);

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 information on how to construct References, including best practices, see References and IDs in Discover the platformDiscover the platform.

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

Example:

ISubscriptionService subscriptionService;
// ...

var subscriber = Reference.Create("user://identifier/for/a/user");
var targetUserToFollow = Reference.Create("user://identifier/for/another/user");
//an optional type may be assigned to the subscription being created that can be used for filtering purposes later.
var subscriptionType = SubscriptionType.Create("user");
var subscription = new Subscription(subscriber, userToFollow, subscriptionType);
//leaving the optional subscriptionType parameter above creates a subscription which has an empty string as its subscription type.

subscriptionService.Add(subscription);

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.

private async Task<Subscription> AddSubscriptionAsync(ISubscriptionService subscriptionService) {
  // ...

  var subscriber = Reference.Create("user://identifier/for/a/user");
  var targetResourceToFollow = Reference.Create("resource://identifier/for/a/resource");
  var subscriptionType = SubscriptionType.Create("resource");
  var subscription = new Subscription(subscriber, targetResourceToFollow, subscriptionType);

  var addSubscriptionTask = subscriptionService.AddAsync(subscription);

  //Do other application specific work in parallel while the task executes.
  //....

  //Wait until the task runs to completion.
  var newSubscription = await addSubscriptionTask;
  return newSubscription;
}

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 let you 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 specified when the subscription was created.

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

The following example demonstrates retrieving a result page of subscriptions for a particular subscriber.

ISubscriptionService subscriptionService;
// ...

var criteria = new Criteria<SubscriptionFilter> {
  Filter = new SubscriptionFilter() {
    Subscriber = Reference.Create("user://identifier/for/a/user")
  }
};
var subcriptionPage = subscriptionService.Get(criteria);

The next example retrieves a result page of subscriptions targeting a particular followed user.

ISubscriptionService subscriptionService;
// ...

var criteria = new Criteria<SubscriptionFilter>
  {
    Filter = new SubscriptionFilter()
      {
        Target = Reference.Create("user://identifier/for/a/user")
      }
  };
var subcriptionPage = subscriptionService.Get(criteria);

The next example retrieves a result page of subscriptions targeting a particular followed resource.

ISubscriptionService subscriptionService;
// ...

var criteria = new Criteria<SubscriptionFilter> {
  Filter = new SubscriptionFilter() {
    Target = Reference.Create("resource://identifier/for/a/resource")
  }
};
var subcriptionPage = subscriptionService.Get(criteria);

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

ISubscriptionService subscriptionService;
// ...

var criteria = new Criteria<SubscriptionFilter> {
  Filter = new SubscriptionFilter() {
    Subscriber = Reference.Create("user://identifier/for/a/user"),
      Type = SubscriptionType.Create("resource");
  }
};
var subcriptionPage = subscriptionService.Get(criteria);

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.

private async Task<ResultPage<Subscription>> GetSubscriptionsAsync(ISubscriptionService subscriptionService) {
  // ...

  var criteria = new Criteria<SubscriptionFilter> {
    Filter = new SubscriptionFilter() {
      Target = Reference.Create("resource://identifier/for/a/resource")
    }
  };

  var getSubscriptionsTask = subscriptionService.GetAsync(criteria);

  //Do other application specific work in parallel while the task executes.
  //....

  //Wait until the task runs to completion.
  var subcriptionPage = await getSubscriptionsTask;
  return subcriptionPage;
}

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 to construct sorting rules associated 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.

var criteria = new Criteria<SubscriptionFilter> {
  // ...
  OrderBy = new List<SortInfo> {
    new SortInfo(SubscriptionSortFields.Subscriber, true),
    new SortInfo(SubscriptionSortFields.Created, false),
  }
};

For details regarding criteria use, including information on paging and sorting, see Criteria in Discover the platformDiscover the platform.

Remove a subscription

To remove a specific instance of a subscription that 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.

ISubscriptionService subscriptionService;
// ...

// Construct or retrieve an ID for an existing subscription.
var subscriptionId = SubscriptionId.Create("...");
subscriptionService.Remove(subscriptionId);

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 information about the construction of Criteria, see Retrieving subscriptions in Activity streamsActivity streams.

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

private async Task RemoveSubscriptionAsync(ISubscriptionService subscriptionService) {
  // ...

  // Construct or retrieve an ID for an existing subscription.
  var subscriptionId = SubscriptionId.Create("...");
  var removeSubscriptionTask = subscriptionService.RemoveAsync(subscriptionId);

  //Do other application specific work in parallel while the task executes.
  //....

  //Wait until the task runs to completion.
  await removeSubscriptionTask;
}

Subscriptions

Manage subscriptions

Access an ISubscriptionService

Subscribe to a target

Retrieve subscriptions

Order results

Remove a subscription