Subscription API

Return to previous page

  • 4/7/2015
  • 1614 Views

Comments

1614 Views

Subscription API

Last updated 4 years ago

Comments

Common

(Enter the content of this article below)

Advanced

 


Introduction

The Subscription API is a very simple API that allows users to subscribe and unsubscribe to some specific content or concept. It has been included in version 7.2.0.

In this article, we will describe:

• The entities and controllers of the Subscription API

• How it works and how it can be used to integrate subscriptions in a third party module with examples

Namespace

This API can be found under the following namespace: DotNetNuke.Services.Social.Subscriptions

Entities

In this section we will talk about the entities that represent the subscription domain. These entities are located under the namespace: DotNetNuke.Services.Social.Subscriptions.Entities

SubscriptionType

The SubscriptionType class describes a single subscription type. It describes subscriptions related with a specific content, concept or scope. For example: Blog Post Subscriptions, Calendar Created Event Subscriptions, Subscriptions related to all the events that can occur in my Module etc…

This class has the following public properties:

SubscriptionTypeId: the subscription type identifier

SubscriptionName: an unique name for the subscription type

FriendlyName: a friendly name for the subscription

DesktopModuleId: the Desktop Module Id associated with the subscription type. This is an optional field but it should be set if the Subscription Type belongs to a specific module

Subscription

The Subscription class describes a single subscription that represents a registered user subscribed to a specific content or concept.

This class has the following public properties:

SubscriptionId: the subscription identifier

UserId: this represents the subscribed user

PortalId: this represents the portal

SubscriptionTypeId: the type of the subscription

ObjectKey: this represents the content which user is subscribed to. The format of the ObjectKey is up to the consumer. (i.e.: blog:12, where 12 represents the post identifier)

ObjectData: this represents metadata to manage the subscription. The format of the ObjectData is up to the consumer. (i.e.: destinationModule:486, where 486 represents an extra property called Destination Module)

Description: a description for the subscribed item

CreatedOnDate: date when the subscription was created

ModuleId: it associates the subscription with an instance of a module. If set it is used to apply a Security Trimming. If the user does not have VIEW permission on that module the Subscription won't be retrieved by the SubscriptionController

TabId: it associates the subscription with a tab. If set it is used to apply a Security Trimming. If the user does not have VIEW permission on that tab the Subscription won't be retrieved by the SubscriptionController

Subscription Type Controller

The SubscriptionType Controller is responsible to manage Subscription Types. It provides to the developer the following methods:

AddSubscriptionType: creates a new Subscription Type taking in input an instance of SubscriptionType class. If the operation succeeds the SubscriptionTypeId property of the Subscription entity will be filled up with the id that represents the Subscription stored in the database

DeleteSubscriptionType: deletes a Subscription Type from the system taking in input an instance of the SubscriptionType class

GetSubscriptionType: returns a single subscription type that match the where predicate passed to the method as an input parameter

GetSubscriptionTypes: 2 overloads to get a collection of the Subscription Type in the system

Subscription Controller

The Subscription Controller is responsible to manage Subscriptions. It provides to the developer the following methods:

AddSubscription: this method adds a new Subscription taking in input an instance of the Subscription Entity. If the operation succeeds the SubscriptionId property of the Subscription entity will be filled up with the id that represents the Subscription stored in the database

DeleteSubscription: this method deletes a Subscription taking in input an instance of the Subscription Entity

GetUserSubscriptions: this method returns the collection of user’s subscriptions. It takes in input the UserInfo and the portalId parameters. It can also take in input a third parameter to filter the subscriptions by a specific subscription type Id. This method can be helpful to show to the user the list of his/her subscriptions

GetContentSubscriptions: this method returns a collection of subscriptions related to a specific item or event. It takes three parameters that identify the content:

o portalId

o subscriptionTypeId

o objectKey

IsSubscribed: this method checks if a user is subscribed to a specific content. It takes as input parameter an instance of the subscription Entity.

Subscription Security Trimming

As discussed previously, the SubscriptionController works with the TabId and ModuleId field of the Subscription Entity to apply a Security Trimming.

This operation is done in the box in the following methods of the Subscription Controller:

GetUserSubscriptions

GetContentSubscriptions

IsSubscribed

How does Security Trimming work?

We can have four different cases:

1. If the TabId and the ModuleId are not set for the subscription then the security trimming is not applied

2. If the ModuleId is set, the Controller will check if the user associated with the subscription does have the VIEW permission on the module

3. If the TabId is set, the Controller will check if the user associated with the subscription does have the VIEW permission on the Tab

4. If both values are set, the Controller will check only the Module permission

Note: if the module or the tab or the user is deleted, the system won’t remove the related subscriptions automatically. However the security trimming will exclude from the result of the methods all these obsolete subscriptions

Manage Subscriptions

User’s subscriptions can be listed and managed in the user Profile page under the Communications tab.

The section “Manage Subscription” allows the user to see all his/her subscriptions and unsubscribe. The grid shows the Description field and the Subscription Type Friendly Name for each user’s subscriptions.
Below is an image showing an example of 4 subscriptions listed in the Manage Subscription section.

Image


Subscription API Getting Started

In this section we will see the Subscription API in action. We will do an example supposing that we have built a Blog module and we want allow users subscribe to some blog post and be notified when a comment is added to the blog post.

Note: the example code has not been tested.

How to create a new Subscription Type

The first step will require create a Subscription Type that represents the subscription to a BlogPost.

A subscription type can be created using the AddSubscriptionType method of the SubscriptionTypeController. Module developers could use this in conjunction with IUpgradeable interface. So during module installation or upgrade, the required Subscription type is created.

See example below:


var desktopModuleId = DesktopModuleController.GetDesktopModuleByFriendlyName("MyBlogDesktopModuleFriendlyName").DesktopModuleID;


var subType = new SubscriptionType

{

SubscriptionName = "BlogPostSubscription",

FriendlyName = "Blog Post Subscription",

DesktopModuleId = desktopModuleId

};


SubscriptionTypeController.Instance.AddSubscriptionType(subType);


How to Subscribe

Once that the Subscription Type is created we can provide our module the functionality to allow our users to subscribe to the Blog Post.

See example code below:


// Create Subscription Entity

var subscription = SubscriptionFactory.CreateBlogPostSubscription(UserInfo.UserID, blogPost);

// Add Subscription

SubscriptionController.Instance.AddSubscription(subscription);


The CreateBlogPostSubscription is a Factory method that creates and setup our Subscription Entity for a Blog Post based on our preference. This method is not part of the Subscription API, it has been created to show the example, but as best practice, developers can create its own Create Subscription method to centralize the logic that represents the Subscription for a specific content.

See example code below:


public static Subscription CreateBlogPostSubscription(int userId, BlogPost blogPost)

{

// Get Subscription Type

var desktopModuleId = DesktopModuleController.GetDesktopModuleByFriendlyName("MyBlogDesktopModuleFriendlyName").DesktopModuleID;


var subscriptionType = SubscriptionTypeController.Instance.GetSubscriptionType(

st => st.DesktopModuleId == desktopModuleId &&

st.SubscriptionName == "BlogPostSubscription");


// Create and Setup Subscription Entity

return new Subscription

{

SubscriptionTypeId = subscriptionType.SubscriptionTypeId,

UserId = userId,

PortalId = blogPost.PortalId, // Current Portal

ObjectKey = string.Format("blog:{0}", blogPost.ID), // Our specific format to define the key for identify a blogPost.

Description = blogPost.Title

ModuleId = blogPost.ModuleId, // Current Module Id

TabId = Null.NullInteger

};

}


How to Unsubscribe

Now that the user can subscribe to the Blog Post, we can provide the unsubscribe feature.

The code to implement this process is very similar to the subscribe code. We can reuse the CreateBlogPostSubscription method (see previous section) to create and setup the entity that represents the subscription between the user and the BlogPost.

See example code below:


// Create Subscription Entity

var subscription = SubscriptionFactory.CreateBlogPostSubscription(UserInfo.UserID, blogPost);

// Delete Subscription

SubscriptionController.Instance.DeleteSubscription(subscription);


How to check if the user is subscribed

One nice feature that we could probably want to include in our module is display, in the page where the BlogPost is shown, some info to tell the user if is subscribed to the Blog Post.

The SubscriptionAPI provides the method IsSubscribed to check if the user is already subscribed to a specific content.

See example code below:


// Create Subscription Entity

var subscription = SubscriptionFactory.CreateBlogPostSubscription(UserInfo.UserID, blogPost);


// is subscribed?

if(SubscriptionController.Instance.IsSubscribed(subscription))

{

// tell to the user that is subscribed to the Blog Post

}

else

{

// tell to the user that is NOT subscribed to the Blog Post

}


How notify subscribers

To conclude the subscription integration with our Blog Module, we want now notify subscribed users when a comment is added for a Blog Post.
We will use the Subscription API to get all the subscriptions for the commented Blog Post.

See example code below:


void OnPostBlogCommented(BlogPost blogPost)

{

// Get Subscription Type

var desktopModuleId = DesktopModuleController.GetDesktopModuleByFriendlyName("MyBlogDesktopModuleFriendlyName").DesktopModuleID;


var subscriptionType = SubscriptionTypeController.Instance.GetSubscriptionType(

st => st.DesktopModuleId == desktopModuleId &&

st.SubscriptionName == "BlogPostSubscription");


// Get Blog Post Subscriptions

var subscriptions = SubscriptionController.Instance.GetContentSubscriptions(

blogPost.PortalId,

subscriptionType.SubscriptionTypeId,

string.Format("blog:{0}", blogPost.ID)); // Object Key


foreach (var subscription in subscriptions)

{

// i.e.: Send system notification to subscribed users using the Core Messaging Notification API

}

}
Contents
No sections defined

DNN Digest is our monthly email newsletter. It highlights news and content from around the DNN ecosystem, such as new modules and themes, messages from leadership, blog posts and notable tweets. Keep your finger on the pulse of the ecosystem by subscribing.  


Copyright 2017 by DNN Corp Terms of Use Privacy
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out