Loading...
Area: Episerver Social
Applies to versions: 1 and higher

Activity streams: Subscriptions

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 Episerver Social platform, subscriptions are managed through a service implementing the interface ISubscriptionService. This service provides the ability to persist and retrieve subscriptions that you define.

Managing subscriptions

In the Episerver Social platform, subscriptions are managed through a service implementing the interface ISubscriptionService. This service provides the ability to persist, retrieve, and remove subscriptions.

Accessing an ISubscriptionService

When the Activity Streams feature is installed to an Episerver 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 to a non-Episerver 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();

Subscribing 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:

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 that 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.

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 is thrown.

In the above 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;
  }

Retrieving 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 example below demonstrates the retrieval of 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); 

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

ISubscriptionService subscriptionService;
// ...

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

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

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 example below demonstrates the retrieval of 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 above 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;
  }

Ordering results

The SubscriptionSortFields class exposes a set of fields upon which a result set of subscriptions may be ordered. These fields may be applied 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 example below 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 the use of criteria, including information on paging and sorting, see Criteria.

Removing 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.

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 more information about the construction of Criteria, see Retrieving subscriptions.

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.

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;
  }

Last updated: Nov 01, 2016