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.EntitiesSubscriptionType
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•
IsSubscribedHow 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.
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
}
}