Blog posts by Benjamin Schaefer2017-09-12T19:15:28.0000000Zhttps://world.optimizely.com/blogs/benjamin-schaefer/Optimizely WorldGetting started with Activity Streams: Part 1<p><strong>Overview</strong></p>
<p>This is the first post in a series that will provide deeper insight into the Episerver Social Activity Streams functionality. This post targets how Activity Streams has been implemented within Social Alloy. Upcoming posts will look specifically at <span>best practices for working with </span>the Activity Streams APIs and alternative use cases for where Activity Streams can add business value.</p>
<p><strong>Introduction</strong></p>
<p>The engagement of digital community members can take many forms. Reviewing a product, joining a group, adding a comment or friending another member, among many others. While each activity is unique, the ability to broadcast, and promote your community's engagement can be a powerful tool for any digital marketer.</p>
<p>Episerver Social Activity Streams provide the functionality to:</p>
<ul>
<li>Easily publish activities related to your user’s actions.</li>
<li>Allow users to engage with these published activities through subscriptions.</li>
<li>Return related information for activities that were published to subscribed users.</li>
</ul>
<p>Conveniently, the Episerver Social Alloy demo site has an implementation of a typical use case for Activity Streams. This post will look at how the CommentBlock, SubscriptionBlock and FeedBlock in Social Alloy tie into Activity Streams on the pre-populated Silver Resellers Group page. To follow along, I encourage you to investigate the Social Alloy GitHub repo found here:</p>
<p><a href="https://github.com/episerver/SocialAlloy">https://github.com/episerver/SocialAlloy</a></p>
<p>And to experiment with this functionality take advantage of the demo account portal for Episerver Social. Sign up here:</p>
<p><a href="https://social.episerver.net">https://social.episerver.net</a></p>
<p><strong>Background</strong></p>
<p>Before we jump into the implementation of Activity Streams it is useful to understand some of key terms that relate to this feature.</p>
<p><span style="text-decoration: underline;">Activities</span>: Activities signify an event or action occurring within your application. The Episerver Social platform allows for activities to be published within an application, resulting in the generation of corresponding feed items for subscribing users.</p>
<p><span style="text-decoration: underline;">Subscriptions</span>: Users 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.</p>
<p><span style="text-decoration: underline;">Feeds</span>: A feed represents a record of activities occurring within the application. As an activity is added to the system, the platform generates feed items for users subscribed to the entity upon which the activity occurred.</p>
<p><span style="text-decoration: underline;">Actor</span>: A reference for the user or system that triggers an activity</p>
<p><span style="text-decoration: underline;">Target</span>: A reference for what was acted upon. The target can take many forms such as a page, a system event, or user action. </p>
<p>With these terms in mind, we can begin to see the relationship between all of the components needed to implement a robust streaming activity system.</p>
<p><strong>Implementation</strong></p>
<p>The CommentBlock in Social Alloy can be configured for Activity Stream functionality. The CommentBlock can create an activity for each comment that is added to a page where the block resides. The block configuration code is here:</p>
<pre class="language-csharp"><code>/// <summary>
/// Configures whether an activity should be sent to the Episerver Social Activity Streams system.
/// </summary>
[Display(
GroupName = SystemTabNames.Content,
Order = 1)]
public virtual bool SendActivity { get; set; }
/// <summary>
/// Sets the default configuration values.
/// </summary>
/// <param name="contentType">Type of the content.</param>
public override void SetDefaultValues(ContentType contentType)
{
base.SetDefaultValues(contentType);
ShowHeading = false;
Heading = "Comments";
CommentBoxRows = 5;
CommentMaxLength = 500;
CommentsDisplayMax = 10;
SendActivity = true;
}</code></pre>
<p>The CommentBlockController contains the logic for adding an activity to Social when a new comment has been added. SocialAlloy abstracts its interaction with Episerver Social into repository implementations. These repositories have knowledge of the application’s business logic and models, which they manage through Episerver Social. Adding an activity requires an actor, a target ,and extension data. For this implementation, the actor will be the user id of the comment author, the target will be the page id where the CommentBlock resides, and the extension data will be the additional relevant information for the event of a comment being added to the system. The only additional information needed in this scenario is the comment body. The activity creation code is here</p>
<pre class="language-csharp"><code>private void AddCommentActivity(PageComment comment)
{
try
{
var commentActivity = new PageCommentActivity { Body = comment.Body };
this.activityRepository.Add(comment.AuthorId, comment.Target, commentActivity);
}
catch (SocialRepositoryException ex)
{
AddMessage(MessageKey, new MessageViewModel(ex.Message, ErrorMessage));
}
}</code></pre>
<p>An example of a CommentBlock directly tied to activity creation can be seen on the Silver Reseller Group page. Additionally, this page has a Subscription Block that contains functionality for a user to subscribe or unsubscribe to activities that occur on this page.</p>
<p><img alt="Silver Resellers Group" src="/link/174e959f2b294225a6d2ece5e6487571.aspx" height="1027" width="1290" /></p>
<p>By clicking subscribe on the SubscriptionBlock, users can indicate that they want to be informed of all activities that occur on the SilverResellers Group page. A user may have multiple subscriptions to different targets. In Social Alloy, there are three pre-configured Resellers Group pages with activity creation that users can subscribe to. The handling of adding or removing a subscription for a user on a page can be found in the SubscriptionBlockController.cs in the HandleAction method:</p>
<pre class="language-csharp"><code>/// <summary>
/// Handle subscribe/unsubscribe actions.
/// </summary>
/// <param name="actionName">The action.</param>
/// <param name="formViewModel">The form view model.</param>
/// <returns>The action result.</returns>
private ActionResult HandleAction(string actionName, SubscriptionFormViewModel formViewModel)
{
var subscription = new PageSubscription
{
Subscriber = this.userRepository.GetUserId(this.User),
Target = this.pageRepository.GetPageId(formViewModel.CurrentPageLink),
};
try
{
if (actionName == Action_Subscribe)
{
this.subscriptionRepository.Add(subscription);
}
else
{
this.subscriptionRepository.Remove(subscription);
}
AddMessage(MessageKey, new MessageViewModel(SubmitSuccessMessage, SuccessMessage));
}
catch (SocialRepositoryException ex)
{
AddMessage(MessageKey, new MessageViewModel(ex.Message, ErrorMessage));
}
return Redirect(UrlResolver.Current.GetUrl(formViewModel.CurrentPageLink));
}</code></pre>
<p class="informationBox">Note: The activity targets the page that the SubscriptionBlock is on. This is the same target as the activity that is generated by the CommentBlock when it has been configured for activity generation on comment submission. This relationship between activity target and subscription target helps to explain the creation of feed items for a subscribed user. If an activity has the same target as the target that a user is subscribed to, a feed item will be generated.</p>
<p>When a user has subscribed to the Silver Reseller Group page, a feed item will be generated for them every time a contributor on this page adds a comment. To see these feed items, a user can use the top level menu to navigate to their Profile page. This page will provide the user with a feed of information relating to the activities they have subscribed to. To display feed items, the Profile page uses the FeedBlock. Below shows the FeedBlock code for retrieving the feed items associated with the logged in user. </p>
<pre class="language-csharp"><code>/// <summary>
/// Gets the activity feed for the logged in user
/// </summary>
/// <param name="currentBlock">The current frontend block instance.</param>
/// <param name="blockViewModel">a reference to the FeedBlockViewModel to
///populate with activity feed for the logged in user and errors, if any</param>
private void GetSocialActivityFeed(FeedBlock currentBlock, FeedBlockViewModel blockViewModel)
{
try
{
var userId = userRepository.GetUserId(this.User);
if (!String.IsNullOrWhiteSpace(userId))
{
blockViewModel.Feed =
this.feedRepository.Get(new CommunityFeedFilter
{
Subscriber = userId,
PageSize = currentBlock.FeedDisplayMax
});
}
else
{
blockViewModel.Messages.Add(new MessageViewModel(ErrorGettingUserIdMessage, ErrorMessage));
}
}
catch (SocialRepositoryException ex)
{
blockViewModel.Messages.Add(new MessageViewModel(ex.Message, ErrorMessage));
}
}</code></pre>
<p>As more comments are added to the page(s) that a user is subscribed to, more feed items will be retrieved by the Feed API and displayed in the FeedBlock. Within the Social Alloy demo, other blocks can also be configured to generate activities. If a user has subscribed to a page with those blocks in Social Alloy, the FeedBlock will display those related feed items as well.<br /><img alt="Profile page highlighted" src="/link/77f5a7fbc51b47ee8a33d32f23e081f3.aspx" height="892" width="1280" /></p>
<p><span class="informationBox">Note: A feed item will encapsulate the extension data of the activity that was originally added to the system. This allows developers tremendous flexibility for the information that can be conveyed within a user's feed. In the example above, an activity was added which contained the comment body as its extension data. The FeedBlock displays that content as well as the comment author (actor) and page where that comment was added (target). This information originated from the comment that was added using the CommentBlock on the SilverResellers Group page.</span></p>
<p>This implementation of activity creation, user subscription, and feed generation is <span>rudimentary </span>but should help to illustrate the power of the Activity Streams functionality within Episerver Social for building connected online communities. </p>
<p>For more information regarding Activity Streams, please take a look at the developer documentation here:</p>
<p><a href="/link/8541347b3a51455a82f0b5466841e7f1.aspx">http://world.episerver.com/documentation/developer-guides/social/activity-streams-introduction/</a></p>2017-09-12T19:15:28.0000000ZBlog postWorking with Episerver Social References<p>Episerver Social is a stand-alone platform that provides unparalleled control over the construction of models used to deliver social content. Social has two ways to uniquely reference content stored within it.</p>
<ul>
<li>An Id that is generated when a model is persisted into the Social system.</li>
<li>A Reference, a means of identifying relationships between social content and application entities.</li>
</ul>
<p>One aspect of building a maintainable social application is ensuring that you apply a consistent scheme for representing the relationships between your application and its social content. References must be capable of uniquely identifying your application's entities, being easily interpreted by your application, and robust enough to support your application's inevitable future changes.</p>
<p>Example use cases for References might include the following:</p>
<ul>
<li>Referencing a third-party platform that Social is interacting with (for example, Episerver, Ektron, SAP, etc.)</li>
<li>Referencing a third-party provider that Social is being used with (for example, Commerce, Cms, ERP, etc.)</li>
<li>Referencing unique user Ids</li>
<li>Referencing unique product/variant Ids</li>
</ul>
<p>To ensure the consistent construction of a reference a developer might find it advantageous to standardize the way references are created. Here are three guidelines to help you to create references.</p>
<p>1. Build an easily expandable mechanism for handling strings that will be used most often.</p>
<div>
<pre class="language-csharp"><code>//Outline the standard platforms that will be in use with Social.
public static class Platform
{
public const string Episerver = "Episerver";
public const string Ektron = "Ektron";
public const string Salesforce = "Salesforce";
public const string SAP = "SAP";
public const string Microsoft = "Microsoft";
}
//Outline the standard providers that exist for your platforms and will be referenced by your builder.
public static class Provider
{
//Episever and Ektron
public const string CMS = "CMS";
public const string Commerce = "Commerce";
//Salesforce
public const string Demandware = "Demandware";
public const string SalesCloud = "SalesCloud";
public const string Pardot = "Pardot";
//SAP
public const string ERP = "ERP";
public const string Anywhere = "Anywhere";
//Microsoft
public const string Sharepoint = "Sharepoint";
public const string Dynamics = "Dynamics";
} </code></pre>
</div>
<p>2. Build an efficient way to assemble the relevant strings needed for your Social References.</p>
<div>
<pre class="language-csharp"><code>// This class builds up a string from the relevant details of a product in a third party system.
public class ProductReferenceBuilder
{
public string Platform { get; set; }
public string Provider { get; set; }
public string ProductId { get; set; }
public string Variant { get; set; }
public ProductReferenceBuilder AddPlatform(string platform)
{
Platform = platform;
return this;
}
<br /> public ProductReferenceBuilder AddProvider(string provider)
{
Provider = provider;
return this;
}
<br /> public ProductReferenceBuilder AddProductId(string productId)
{
ProductId = productId;
return this;
}
<br /> public ProductReferenceBuilder AddVariantId(string variant)
{
Variant = variant;
return this;
}
<br /> public Reference Build()
{
ProductReferenceValidation();
var referenceString = $"Product://{Platform}/{Provider}/{ProductId}/{Variant}";
return Reference.Create(referenceString);
}
<br /> private void ProductReferenceValidation()
{
if (string.IsNullOrWhiteSpace(Platform) ||
string.IsNullOrWhiteSpace(Provider) ||
string.IsNullOrWhiteSpace(ProductId) ||
string.IsNullOrWhiteSpace(Variant))
{
throw new Exception("Missing field value for ProductReference");
}
}
<br />// This class builds up a string from the relevant details of a user in a third-party system.
public class UserReferenceBuilder
{
public string Platform { get; set; }
public string Provider { get; set; }
public string UserId { get; set; }
<br /> public UserReferenceBuilder AddPlatform(string platform)
{
Platform = platform;
return this;
}
<br /> public UserReferenceBuilder AddProvider(string provider)
{
Provider = provider;
return this;
}
<br /> public UserReferenceBuilder AddUserId(string userId)
{
UserId = userId;
return this;
}
<br /> public Reference Build()
{
ProductReferenceValidation();
var referenceString = $"User://{Platform}/{Provider}/{UserId}";
return Reference.Create(referenceString);
}
<br /> private void ProductReferenceValidation()
{
if (string.IsNullOrWhiteSpace(Platform) ||
string.IsNullOrWhiteSpace(Provider) ||
string.IsNullOrWhiteSpace(UserId))
{
throw new Exception("Missing field value for UserReference");
}
}
<br /> private void ProductReferenceValidation()
{
if (string.IsNullOrWhiteSpace(Platform) ||
string.IsNullOrWhiteSpace(Provider) ||
string.IsNullOrWhiteSpace(UserId))
{
throw new Exception("Missing field value for UserReference");
}
}
}
</code></pre>
</div>
<p>3. Add unit tests for your reference related classes to ensure that the creation of a reference matches what is expected.</p>
<div>
<pre class="language-csharp"><code>[TestClass]
public class ProductBuilderTest
{
[TestMethod]
public void ProductReferenceBuilder_Build_ReturnsProperlyConstructedReference()
{
var expectedProductReference = Reference.Create("Product://Episerver/Commerce/ProductId/VarientId");
var actualProductReference = new ProductReferenceBuilder().AddPlatform(Platform.Episerver)
.AddProvider(Provider.Commerce)
.AddProductId("ProductId")
.AddVariantId("VarientId")
.Build();
Assert.IsTrue(expectedProductReference == actualProductReference);
}</code></pre>
<p> </p>
<pre class="language-csharp"><code> [TestMethod]
public void UserReferenceBuilder_Build_ReturnsProperlyConstructedReference()
{
var expectedProductReference = Reference.Create("User://Microsoft/Dynamics/UserId");
var actualProductReference = new UserReferenceBuilder().AddPlatform(Platform.Microsoft)
.AddProvider(Provider.Dynamics)
.AddUserId("UserId")
.Build();
Assert.IsTrue(expectedProductReference == actualProductReference);
}
}</code></pre>
</div>
<p>By employing these guidelines, developers can create reusable code to help construct references consistently. <br />Additional information on Episerver Social Reference can be found at: <br /><a href="/link/a09c5c7c7ca54b9b8bcb06d846cf9031.aspx#referenceandIDs">http://world.episerver.com/documentation/developer-guides/social/social_platform-overview/discovering-the-platform/#referenceandIDs</a>.<br /> </p>2017-04-13T16:44:37.9900000ZBlog postImplementing Membership Moderation using Episerver Social<p><strong> Summary:</strong></p>
<p>The goal of this tutorial is to outline how to implement moderation for group membership admission. The tutorial describes an interconnected relationship between four social services: groups, members, workflows and workflow items.</p>
<p><strong>Prerequisites</strong></p>
<p>A working Episerver SocialAlloy site. This repo can be pulled from the <a title="Github" href="https://github.com/episerver/SocialAlloy">Episerver Github page</a>.</p>
<p><strong>Example of Membership Moderation</strong></p>
<p><strong><img alt="Image pic1.png" src="/link/63a78add400147798543b2be66ac9e0a.aspx" height="284" width="272" /></strong></p>
<p>The Silver Reseller GroupAdmissionBlock on the Silver Reseller CommunityPage in the SocialAlloy starter site has an existing workflow associated with it. All users who request to join this group are entered into membership moderation.</p>
<p><img alt="Image pic2.png" src="/link/27c89a842678449eb904cf63800e7f42.aspx" height="430" width="641" /></p>
<p>A user has been entered into the workflow for the Silver Resellers Group. This group has an existing workflow associated that has an initial state of “Pending.” The two actions that can be taken on that state that are “Accept” and “Ignore”.</p>
<p><img alt="Image pic3.png" src="/link/cce8baef29ed483ebaa0c2c83e49760e.aspx" height="430" width="645" /></p>
<p>If the “Accept” action is taken, the member admission entity enters into a new state called “Accepted”. The available actions from this state are “Approve” and “Reject”.</p>
<p> <img alt="Image pic4.png" src="/link/a723f5b64cb64e458c72f12085d9dcf1.aspx" height="356" width="630" /></p>
<p>If the “Approve” action is taken, the member enters into a new state called “Approved”. No additional actions can be taken once this state is reached. This is one potential end to the community membership workflow. If a moderator had taken either the “Ignore” or “Reject” actions, the outcome to the member request would be “Rejected”.</p>
<p><strong>Before Creating a Moderation Strategy</strong></p>
<p>It is important to clearly identify the business process that you are looking to translate into a workflow. The Social Framework provides methods to create and interact with a workflow. However, the relevant entities of a workflow can differ greatly between use cases.</p>
<p>For this tutorial, the business process that has been outlined is the moderation of group membership. Within the SocialAlloy site, distinct constructs have been created to abstract the site specific models and logic from those of the Social Framework. Communities encapsulate the relevant information about a group. Communities allow for the membership of CommunityMembers (a class used to convey the details of a member). Communities that desire a way to moderate the admission of CommunityMembers require the support of a CommunityMembershipWorkflow. The CommunityMembershipWorkflow model defines the essential components for CommityMembership moderation within the SocialAlloy site.</p>
<p>Managing the business specific components with a clearly-defined process in advance of implementing the Social Framework will result in an uneventful and enjoyable development experience.</p>
<p><strong>Building a workflow</strong></p>
<p>The SocialAlloy starter site is seeded with existing groups. These groups have corresponding workflows that allow for membership requests into the group to be moderated. An example of method used to add a workflow can be seen below:</p>
<div>
<pre class="language-csharp"><code>/// <summary>
/// Adds a workflow to the underlying repository
/// </summary>
/// <param name="community">The community that will be associated with the workflow</param>
public void AddWorkflow(Community community)
{
// Define the transitions for workflow:
// Pending -> (Accept) -> Accepted
// | |-- (Approve) -> Approved
// | `- (Reject) -> Rejected
// `---> (Ignore) -> Rejected
var workflowTransitions = new List<WorkflowTransition>
{
new WorkflowTransition(new WorkflowState("Pending"), new WorkflowState("Accepted"), new WorkflowAction("Accept")),
new WorkflowTransition(new WorkflowState("Pending"), new WorkflowState("Rejected"), new WorkflowAction("Ignore")),
new WorkflowTransition(new WorkflowState("Accepted"), new WorkflowState("Approved"), new WorkflowAction("Approve")),
new WorkflowTransition(new WorkflowState("Accepted"), new WorkflowState("Rejected"), new WorkflowAction("Reject"))
};
// Save the new workflow with custom extension data which
// identifies the community it is intended to be associated with.
<br /> var membershipWorkflow = new Workflow(
"Membership: " + community.Name,
workflowTransitions,
new WorkflowState("Pending")
);
<br /> var workflowExtension = new MembershipModeration { Group = community.Id };
if (membershipWorkflow != null)
{
try
{
this.workflowService.Add(membershipWorkflow, workflowExtension);
}
catch (SocialAuthenticationException ex)
{
throw new SocialRepositoryException("The application failed to authenticate with Episerver Social.", ex);
}
catch (MaximumDataSizeExceededException ex)
{
throw new SocialRepositoryException("The application request was deemed too large for Episerver Social.", ex);
}
catch (SocialCommunicationException ex)
{
throw new SocialRepositoryException("The application failed to communicate with Episerver Social.", ex);
}
catch (SocialException ex)
{
throw new SocialRepositoryException("Episerver Social failed to process the application request.", ex);
}
}
}</code></pre>
</div>
<p>There are four separate sections to this method that are important to take note of.</p>
<ol>
<li>The construction of the list of WorkflowTransitions.
<ul>
<li>The Workflow object takes a list of WorkflowTransitions. A WorkflowTransition describes the action required to move from one state to another within the workflow A WorkflowTransition consists of two WorkflowStates and one WorkflowAction. The WorkflowStates reflect where the entity in the workflow is coming from and where it is going to when the associated WorkflowAction is taken.</li>
<li>The transitions for a workflow cannot contain duplicate entries with identical combinations of From and To state.</li>
<li>An example of a WorkflowTransition is when an entity is in a “Pending” state and can be moved into an “Accepted” state by taking the WorkflowAction of “Accept”.</li>
</ul>
</li>
<li>The construction of the Workflow object.
<ul>
<li>In addition to a list of WorkflowTransitions, the Workflow object needs a name and an initial state to be properly constructed. An initial WorkflowState is the starting state for any entity entered into this workflow.</li>
<li>It is important to note that the initial state of the workflow being added must match either the <strong>From</strong> or the <strong>To</strong> state of at least one of the workflow transitions.</li>
</ul>
</li>
<li>The construction of the MembershipModeration extension data.
<ul>
<li>The MembershipModeration extension data is used to persist relevant information about the group with which the workflow is associated.</li>
</ul>
</li>
<li>The adding of the workflow and the workflow extension data to the Social system.
<ul>
<li>When using any Social Services, you must anticipate the possibility that a Social exception might be thrown. Organizations need to determine in advance how to handle Social exceptions.</li>
<li>While there is a return value for a Workflow Service Add, this demo was designed to not use the persisted composite.</li>
</ul>
</li>
</ol>
<p><strong>Adding a Moderated Member</strong></p>
<p>The GroupAdmissionBlock facilitates the addition of members to groups within SocialAlloy. When a group is created with membership moderation, the block internally calls the AddAModeratedMember method on the CommunityMemberModerationRepository when a user requests membership to the group.</p>
<div>
<pre class="language-csharp"><code> /// <summary>
/// Submits a membership request to the specified group's
/// moderation workflow for approval.
/// </summary>
/// <param name="member">The member information for the membership request</param>
public void AddAModeratedMember(CommunityMember member)
{
// Define a unique reference representing the entity
// under moderation. Note that this entity may be
// transient or may not yet have been assigned a
// unique identifier. Defining an item reference allows
// you to bridge this gap.
// For example: "members:/{group-id}/{user-reference}"
var targetReference = this.CreateUri(member.GroupId, member.User);
// Retrieve the workflow supporting moderation of
// membership for the group to which the user is
// being added.
var moderationWorkflow = this.GetWorkflowFor(member.GroupId);
// The workflow defines the intial (or 'start') state
// for moderation.
var initialState = moderationWorkflow.InitialState;
// Create a new workflow item...
var workflowItem = new WorkflowItem(
WorkflowId.Create(moderationWorkflow.Id), // ...under the group's moderation workflow
new WorkflowState(initialState), // ...in the workflow's initial state
Reference.Create(targetReference) // ...identified with this reference
);
var memberRequest = memberAdapter.Adapt(member);
try
{
this.workflowItemService.Add(workflowItem, memberRequest);
}
catch (SocialAuthenticationException ex)
{
throw new SocialRepositoryException("The application failed to authenticate with Episerver Social.", ex);
}
catch (MaximumDataSizeExceededException ex)
{
throw new SocialRepositoryException("The application request was deemed too large for Episerver Social.", ex);
}
catch (SocialCommunicationException ex)
{
throw new SocialRepositoryException("The application failed to communicate with Episerver Social.", ex);
}
catch (SocialException ex)
{
throw new SocialRepositoryException("Episerver Social failed to process the application request.", ex);
}
}</code></pre>
</div>
<p>The AddAModeratedMember method can be divided into four distinct sections:</p>
<ol>
<li>Creation of a unique URI used to track the progression of a member being moderated for group admission.</li>
<li>Retrieval of the workflow for the group to which a user is requesting membership.</li>
<li>A Workflow item is constructed to encapsulate three important parts:
<ul>
<li>the unique identifier for the workflow associated with the group</li>
<li>the initial state of the associated workflow</li>
<li>the unique URI to track progression of an entity through the workflow</li>
</ul>
</li>
<li>The addition of the WorkflowItem to the Social system by using the WorkflowItem Service Add method. A WorkflowItem captures the state and data of an entity within a moderation workflow.</li>
</ol>
<p><strong>Interacting with existing workflows</strong></p>
<p>Below is an example of a Moderation View. This is a standard moderation interface that allows a user to select from a list of existing Workflows, displays existing membership requests for a workflow, and acts on available actions for each member request.</p>
<div>
<pre class="language-csharp"><code> <div class="row">
<div class="span12">
<div>
@using (Html.BeginForm("Index", "Moderation", FormMethod.Get))
{
<div>Choose a group to moderate:</div>
<div>
@Html.DropDownListFor(x => x.SelectedWorkflow,
new SelectList(
Model.Workflows,
"Id",
"Name",
Model.Workflows.First().Id), new { @class = "MakeWide" })
</div>
<div><input type="submit" value="View" /></div>
}
</div>
</div>
</div>
<div class="row">
<div class="span12">
<div>
<h4>Membership Requests</h4>
<p>
There are membership requests which may be pending your approval.
</p>
</div>
<table class="table table-striped">
<thead>
<tr>
<th>User</th>
<th>State</th>
<th>Date</th>
<th>Actions</th>
</tr>
</thead>
@foreach (var item in Model.Items)
{
<tr>
<td>
@item.UserName
</td>
<td>
@item.State
</td>
<td>
@item.Created
</td>
<td>
@using (Html.BeginForm("Index", "Moderation", FormMethod.Post))
{
<input type="hidden" name="userId" value="@Html.AttributeEncode(item.User)" />
<input type="hidden" name="communityId" value="@Html.AttributeEncode(item.Group)" />
<input type="hidden" name="workflow" value="@Html.AttributeEncode(Model.SelectedWorkflow.Id)" />
if (item.Actions.Count() == 0)
{
<p class="muted">No actions available</p>
}
foreach (var action in item.Actions)
{
<input type="submit" name="workflowAction" value="@action" />
}
}
</td>
</tr>
}
</table>
</div>
</div></code></pre>
</div>
<p>The CommunityMemberModerationRepository was<span> built with</span> a Get method that returns <span>everything you need to build a moderation screen.</span></p>
<div>
<pre class="language-csharp"><code> /// <summary>
/// Returns a view model supporting the presentation of group
/// membership moderation information.
/// </summary>
/// <param name="workflowId">Identifier for the selected membership moderation workflow</param>
/// <returns>View model of moderation information</returns>
public CommunityModerationViewModel Get(string workflowId)
{
try
{
// Retrieve a collection of all workflows in the system with MembershipModeration extension data.
var allWorkflows = this.GetWorkflows();
// Retrieve the workflow specified as the selected one.
// If no workflow is selected, default to the first
// available workflow.
var selectedWorkflow = string.IsNullOrWhiteSpace(workflowId)
? allWorkflows.FirstOrDefault()
: allWorkflows.FirstOrDefault(w => w.Id.ToString() == workflowId);
// Retrieve the current state for all membership requests
// under the selected moderation workflow.
var currentWorkflowItems = this.GetWorkflowItemsFor(selectedWorkflow);
<br /> var workflowItemAdapter = new CommunityMembershipRequestAdapter(selectedWorkflow, this.userRepository);
<br /> return new CommunityModerationViewModel
{
Workflows = allWorkflows.Select(workflowAdapter.Adapt),
SelectedWorkflow = workflowAdapter.Adapt(selectedWorkflow),
Items = currentWorkflowItems.Select(workflowItemAdapter.Adapt)
};
}
catch (SocialAuthenticationException ex)
{
throw new SocialRepositoryException("The application failed to authenticate with Episerver Social.", ex);
}
catch (MaximumDataSizeExceededException ex)
{
throw new SocialRepositoryException("The application request was deemed too large for Episerver Social.", ex);
}
catch (SocialCommunicationException ex)
{
throw new SocialRepositoryException("The application failed to communicate with Episerver Social.", ex);
}
catch (SocialException ex)
{
throw new SocialRepositoryException("Episerver Social failed to process the application request.", ex);
}
}</code></pre>
</div>
<p>The retrieval of the CommunityModerationViewModel consists of three major parts.</p>
<ol>
<li>Retrieving all available workflows in the system by calling the GetWorkflows method in the CommMakeWide" }) </div> <div><input type="submit" value="View" /></div> } unityMemberModerationRepository. This method uses the Workflow Service Get method. When all workflows are returned, it is possible to select the one that matches the workflow id provided. Also, by retrieving all workflows, allow the UI to display available workflows in the moderation selection dropdown.</li>
<li>GetWorkflowItemsFor method is then called and invokes the WorkflowItem Service Get method using <a title="CompositeCriteria" href="/link/a09c5c7c7ca54b9b8bcb06d846cf9031.aspx#composite_criteria" target="_blank">CompositeCriteria</a>. CompositeCriteria encapsulates the specifications by which platform entities, composed with extension data, should be retrieved. The CompositeCriteria used here look similar to this:<br /><br />
<div>
<pre class="language-csharp"><code> var criteria = new CompositeCriteria<WorkflowItemFilter, AddMemberRequest>
{
Filter = new WorkflowItemFilter
{
ExcludeHistoricalItems = true, // Include only the current state for the requests
Workflow = workflow.Id, // Include only items for the selected group's workflow
},
PageInfo = new PageInfo { PageSize = 30 }, // Limit to 30 items<br /> };
// Order the results alphabetically by their state and then
// by the date on which they were created.
criteria.OrderBy.Add(new SortInfo(WorkflowItemSortFields.State, true));
criteria.OrderBy.Add(new SortInfo(WorkflowItemSortFields.Created, true)); </code></pre>
</div>
</li>
</ol>
<ul>
<li>The Get request only returns WorkflowItems in their current state that are associated with the requested workflow.</li>
<li>The values being returned are ordered by state name then by WorkflowItem creation date.</li>
</ul>
<p> 3. Populating the ModerationViewModel requires:</p>
<ul>
<ul>
<li>all workflows that were retrieved in step 1</li>
<li>the populated selected workflow that was requested</li>
<li>all WorkflowItems associated with the requested Workflow</li>
</ul>
</ul>
<p>** It is important to note that this example uses an adapter class that works with available objects to produce a different, client suitable object that the view can interpret.</p>
<p><strong>Moderate a workflowitem</strong></p>
<p>When looking to moderate a specific workflow item, an interface needs to display available items to moderate and actions that may be taken on them. This shows an example of how displaying those items and actions could be done.</p>
<div>
<pre class="language-csharp"><code> @foreach (var item in Model.Items)
{
<tr>
<td>
@item.UserName
</td>
<td>
@item.State
</td>
<td>
@item.Created
</td>
<td>
@using (Html.BeginForm("Index", "Moderation", FormMethod.Post))
{
<input type="hidden" name="userId" value="@Html.AttributeEncode(item.User)" />
<input type="hidden" name="communityId" value="@Html.AttributeEncode(item.Group)" />
<input type="hidden" name="workflow" value="@Html.AttributeEncode(Model.SelectedWorkflow.Id)" />
<br /> if (item.Actions.Count() == 0)
{
<p class="muted">No actions available</p>
}
foreach (var action in item.Actions)
{
<input type="submit" name="workflowAction" value="@action" />
}
}
</td>
</tr>
}</code></pre>
<div> </div>
</div>
<p>Once a moderator has taken an action on an item in moderation, that action must be managed in a meaningful way within the Social Framework. For this tutorial, a Moderate method was created in the CommunityMembershipModerationRepository to account for what should happen when an item in moderation is acted upon.</p>
<div>
<pre class="language-csharp"><code> /// <summary>
/// Takes action on the specified workflow item, representing a
/// membership request.
/// </summary>
/// <param name="workflowId">The id of the workflow </param>
/// <param name="action">The moderation action to be taken</param>
/// <param name="userId">The unique id of the user under moderation.</param>
/// <param name="communityId">The unique id of the community to which membership has been requested.</param>
public void Moderate(string workflowId, string action, string userId, string communityId)
{
var membershipRequest = GetMembershipRequest(userId, communityId);
var populatedWorkflowId = WorkflowId.Create(workflowId);
var requestReference = Reference.Create(CreateUri(membershipRequest.Group, membershipRequest.User));
try
{
var transitionToken = this.workflowService.BeginTransitionSession(populatedWorkflowId, requestReference);
try
{
// Retrieve the moderation workflow associated with
// the item to be acted upon.
var workflow = this.workflowService.Get(populatedWorkflowId);
// Leverage the workflow to determine what the
// resulting state of the item will be upon taking
// the specified action.
//retrieve the current state of the workflow item once the begintransitionsession begins.
var filter = new WorkflowItemFilter { Target = requestReference };
var criteria = new Criteria<WorkflowItemFilter> { Filter = filter };
var workflowItem = this.workflowItemService.Get(criteria).Results.Last();
// Example: Current State: "Pending", Action: "Approve" => Transitioned State: "Approved"
var transitionedState = workflow.Transition(workflowItem.State, new WorkflowAction(action));
var subsequentWorkflowItem = new WorkflowItem(
workflow.Id,
transitionedState,
requestReference
);
this.workflowItemService.Add(subsequentWorkflowItem, membershipRequest, transitionToken);
// Perform any application logic given the item's
// new state.
if (this.IsApproved(subsequentWorkflowItem.State))
{
memberRepository.Add(memberAdapter.Adapt(membershipRequest));
}
}
finally
{
this.workflowService.EndTransitionSession(transitionToken);
}
}
catch (SocialAuthenticationException ex)
{
throw new SocialRepositoryException("The application failed to authenticate with Episerver Social.", ex);
}
catch (MaximumDataSizeExceededException ex)
{
throw new SocialRepositoryException("The application request was deemed too large for Episerver Social.", ex);
}
catch (SocialCommunicationException ex)
{
throw new SocialRepositoryException("The application failed to communicate with Episerver Social.", ex);
}
catch (SocialException ex)
{
throw new SocialRepositoryException("Episerver Social failed to process the application request.", ex);
}
}</code></pre>
</div>
<p>The Moderate method takes:</p>
<ul>
<li>a unique identifier for the associated workflow</li>
<li>the action that was taken by the moderator</li>
<li>a unique identifier for the user requesting membership to a community</li>
<li>the unique identifier for the associated community</li>
</ul>
<p>The method can be broken down into 8 simple steps.</p>
<ol>
<li>The construction of a unique URI (the same URI from the step 1 in the AddAModeratedMember method) for the workflow request.</li>
<li>The BeginTransitionSession method in the WorkflowService must be called in advance of any WorkflowItem transition.
<ul>
<li>Requests exclusive access to add workflow items for a target within a particular workflow. If another client already has secured access to that target, a TransitionSessionDeniedException is thrown.</li>
<li>The TransitionSessionToken returned in this operation is used in the addition of a new WorkflowItem.</li>
</ul>
</li>
<li>Retrieval of the most recent WorkflowItem by the Workflow Service by using the Get method.</li>
<li>Using the Workflow Transition method, the transitioned state is constructed from the current WorkflowItem state and the requested action.</li>
<li>Construction of a new WorkflowItem with the workflow identifier, the transitioned state, and the unique URI (constructed in step 1).</li>
<li>The new WorkflowItem is added to the system with the populated AddMemberRequest and TransitionSessionToken.</li>
<li>This tutorial has a conditional check when moderating to see if the new WorkflowItem is in a state of approved (one possible end of the workflow). Only when the admission state has reached "accepted" is the member added to the MemberRepository.</li>
<li>Once the Add method has successfully updated the state of the admission request and no error is encountered, the EndTransitionSession method in the WorkflowService should be called.
<ul>
<li>The EndTransitionSession method is passed the TransitionSessionToken that was constructed in step 2.</li>
<li>This method ends the transition session, relinquishing exclusive access to add workflow items to the target.</li>
</ul>
</li>
</ol>
<p><strong>Essential files for Group Membership Moderation Tutorial</strong></p>
<p><strong>File Type</strong>: Controller<br /><strong>Location</strong>: SocialAlloy/Social/Controllers/<br /><strong>Name / Descriptio</strong>n:</p>
<ul>
<li>ModerationController.cs – used to update the CommunityModerationViewModel</li>
</ul>
<p><strong>File Type</strong>: Model<br /><strong>Location</strong>: SocialAlloy/Social/Models/<br /><strong>Name/ Description</strong>:</p>
<ul>
<li>CommunityMembershipWorkflow.cs - encapsulates SocialAlloy specific details of a Group Workflow</li>
<li>CommunityModerationViewModel.cs - relays moderation details from the ModerationController to the Moderation view</li>
<li>Community.cs - describes a group model used by the SocialAlloy site.</li>
<li>CommunityMember.cs – describes a member model used by the SocialAlloy site</li>
</ul>
<p><strong>File Type</strong>: View:<br /><strong>Location</strong>: SocialAlloy/Views/Social/Moderation<br /><strong>Name / Description:</strong></p>
<ul>
<li>Index.cshtml – Generates outputs to the user based upon the values of the CommunityModerationViewModel</li>
</ul>
<p><strong>File Type</strong>: Repository<br /><strong>Location</strong>: SocialAlloy/Social/Repositories/Moderation<br /><strong>Name / Description:</strong></p>
<ul>
<li>ICommunityMemberModerationRepository.cs – The interface describing operations that manage community membership moderation</li>
<li>CommunityMemberModerationRepository.cs - Implements operations that manage community membership moderation with the Episerver Social Framework</li>
<li>ICommunityMemberRepostiory.cs – The interface that describes a component capable of persisting and retrieving community member data</li>
<li>CommunityMemberRepository.cs - Persists and retrieves community member data to and from the Episerver Social Framework</li>
</ul>
<p>* Repositories in the SocialAlloy site are responsible for the sole point of interaction with the Social API. Social constructs have been abstracted away by site specific entities in order to separate the business logic of the site from the Social API integration points.</p>
<p><strong>File Type</strong>: Extension Data<br /><strong>Location</strong>: EPiServer.SocialAlloy.ExtensionData/Membership<br /><strong>Name / Description:</strong></p>
<ul>
<li>AddMemberRequest.cs - a serializable class representing a request for membership to a group. It is intended to support the moderation process around group membership.</li>
<li>MemberExtensionData.cs- Custom extension data used in saving member details for members associated with groups.</li>
<li>MembershipModeration.cs - Intended to identify the relationship between a moderation workflow and the group which it supports for moderating membership requests. This serves as an extension data added to workflows</li>
</ul>
<p>* It is important to note that the extension data for the SocialAlloy site has been moved to its own project by design. Compartmentalizing extension data and adding that project into a site solution ideally make namespaces more stable and less susceptible to changing over time. Additionally, by separating the extension data, it should be very easy for a user to reference the same POCOs in their staging site that they are referencing in their production site.</p>2017-03-17T15:10:16.4230000ZBlog post