Communities Scoring and Badges

Overview

The AEM Communities scoring and badges feature provides the ability to identify and reward community members.

The main aspects of scoring and badges are:

• Assign badges to identify the role of a member in the community.

• Basic awarding of badges to members to encourage their participation (quantity of content created).

• Advanced awarding of badges to identify members as experts (quality of content created).

Note that awarding of badges is not enabled by default.

Badges

Badges are placed under a member’s name to indicate either their role or their standing in the community. Badges may either be displayed as an image or as a name. When displayed as an image, the name is included as alternate text for accessibility.

By default, badges are located in the repository at

• /libs/settings/community/badging/images

If stored in a different location, they should be read accessible by everyone.

Badges are differentiated in UGC as to whether they were assigned or were earned according to the rules. Presently, assigned badges appear as text and earned badges appear as an image.

Badge Management UI

The Communities Badges console provides the ability to add custom badges which can be displayed for a member when earned (awarded) or when they take on a specific role in the community (assigned).

Assigned Badges

Role-based badges are assigned by an administrator to community members based on their role in the community.

Assigned (and awared) badges are stored in the selected SRP and are not directly accessible. Until a GUI is available, the only means for assigning role-based badges is to do so with code or cURL. For cURL instructions, see the section titled Assign and Revoke Badges.

Included in the release are three role-based badges:

• moderator
  /libs/settings/community/badging/images/moderator/jcr:content/moderator.png

• group manager
  /libs/settings/community/badging/images/group-manager/jcr:content/group-manager.png

• privileged member
  /libs/settings/community/badging/images/privileged-member/jcr:content/privileged-member.png

  

Awarded Badges

Reward-based badges are awarded by the scoring service to community members based on rules applied to their activity in the community.

In order for badges to appear as a reward for activity, there are two things that must happen:

• Badging must be enabled for the feature component.
• Scoring and badging rules must be applied to the page (or ancestor) on which the component is placed.

Included in the release are three reward-based badges:

• gold
  /libs/settings/community/badging/images/gold-badge/jcr:content/gold.png

• silver
  /libs/settings/community/badging/images/silver-badge/jcr:content/silver.png

• bronze
  /libs/settings/community/badging/images/bronze-badge/jcr:content/bronze.png

  

Custom Badges

Custom badges can be installed using the Badges console and either assigned or specified in badging rules.

When installed from the Badges console, custom badges are automatically replicated to the publish environment.

Enable Scoring

Scoring is not enabled by default. The basic steps for setting up and enabling scoring and awarding of badges are:

• Identify rules for earning points (scoring rules).

• For points accumulated per scoring rules, assign badges (badging rules).

• Apply the scoring and badging rules to a community site.

• Enable badging for community features.

See the Quick Test section to enable scoring for a community site using the default scoring and badging rules for forums and comments.

Apply Rules to Content

To enable scoring and badges, add the properties scoringRules and badgingRules to to any node in the content tree for the site.

If the site is already published, after applying all rules and enabling components, re-publish the site.

The rules that apply to a badging-enabled component are those for the current node or its ancestor.

If the node is of type cq:Page (recommended), then, using CRXDE|Lite, add the properties to its jcr:content node.

Enable Badges for Component

The scoring and bading rules are in effect only for instances of components that have enabled badging by editing the component configuration in authoring mode.

A boolean property, allowBadges, enables/disables the display of badges for a component instance. It is configurable in the component edit dialog for forum, QnA and comment components through a checkbox labeled Display Badges.

Example : allowBadges for Forum component instance

Scoring Rules

Scoring rules are the foundation of scoring for the purpose of awarding badges.

Very simply, each scoring rule is a list of one or more sub-rules. Scoring rules are applied to the community site content to identify the rules to apply when badges are enabled.

Scoring rules are inherited but not additive. For example:

• If page2 contains scoring rule2 and its ancestor page1 contains scoring rule1.

• An action on a page2 component will invoke both rule1 and rule2.

• If both rules contain applicable sub-rules for the same topic/verb:

  • Only the sub-rule from rule2 will affect the score.
  • The scores from both sub-rules are not added together.

When there is more than one scoring rule, the scores are maintained separately for each rule.

Scoring rules are nodes of type cq:Page with properties on its jcr:content node that specify the list of sub-rules that define it.

Scores are stored in SRP.

Scoring Sub-Rules

The scoring sub-rules contain the properties which detail the values for participating in the community.

Each scoring sub-rule identifies:

• What activities are being tracked?
• Which specific community function is involved?
• How many points are awarded?

By default, points are awarded to the member taking action unless the sub-rule specifies the owner of the content as receiving the points ( forOwner).

Each sub-rule may be included in one or more scoring rules.

The name of the sub-rule typically follows the pattern of using a subject , object and verb. For example:

• member-comment-create
• member-receive-vote

Sub-rules are nodes of type cq:Page with properties on its jcr:contentnode that specify the verbs and topics .

Included Scoring Rules and Sub-Rules

Included in the release are two scoring rules for the Forum Function (one each for the Forum and Comments components of the Forum feature) :

1. /libs/settings/community/scoring/rules/comments-scoring

   • subRules[] =
     /libs/settings/community/scoring/rules/sub-rules/member-comment-create
     /libs/settings/community/scoring/rules/sub-rules/member-receive-vote
     /libs/settings/community/scoring/rules/sub-rules/member-give-vote
     /libs/settings/community/scoring/rules/sub-rules/member-is-moderated

2. /libs/settings/community/scoring/rules/forums-scoring

   • subRules[] =
     /libs/settings/community/scoring/rules/sub-rules/member-forum-create
     /libs/settings/community/scoring/rules/sub-rules/member-receive-vote
     /libs/settings/community/scoring/rules/sub-rules/member-give-vote
     /libs/settings/community/scoring/rules/sub-rules/member-is-moderated

Notes:

• Both rules and sub-rules nodes are of type cq:Page.

• subRules is an attribute of type String[] on the rule’s jcr:content node.

• sub-rules may be shared among various scoring rules.

• rules should be located in a repository location with read permission for everyone.

  • Rule names must be unique regardless of the location.

Activating Custom Scoring Rules

Any changes or additions made to scoring rules or sub-rules made in the author environment need to be installed on publish.

Badging Rules

Badging rules link scoring rules to badges by specifying:

• Scoring rule
• Score necessary to be awared a specific badge

Badging rules are nodes of type cq:Page with properties on its jcr:content node that correlate scoring rules to scores and badges.

The rules for badging consist of a mandatory thresholds property that is an ordered list of scores mapped to badges. The scores must be ordered in increasing value. For example:

• 1|/libs/settings/community/badging/images/bronze-badge/jcr:content/bronze.png

  • A bronze badge is awared for earning 1 point.

• 60|/libs/settings/community/badging/images/silver-badge/jcr:content/silver.png

  • A silver badge is awarded when 60 points have been accumulated.

• 80|/libs/settings/community/badging/images/gold-badge/jcr:content/gold.png

  • A gold badge is awared when 80 points have been accumulated.

Badging rules are paired with scoring rules, which determine how points accumulate. See the section titled Apply Rules to Content.

The scoringRules property on a badging rule simply restricts which scoring rules can be paired with that particular badging rule.

Included Badging Rules

Included in the release are two Badging Rules that correspond to the Forums and Comments Scoring Rules.

• /libs/settings/community/badging/rules/comments-badging

• /libs/settings/community/badging/rules/forums-badging

Notes:

• rules nodes are of type cq:Page.

• rules should be located in a repository location with read permission for everyone.

  • Rule names must be unique regardless of location.

Activating Custom Badging Rules

Any changes or additions made to badging rules or images made in the author environment need to be installed on publish.

Assign and Revoke Badges

Badges may be assigned to members either using the members console or programmatically using cURL commands.

The following cURL commands show what is necessary for an HTTP request for assigning and revoking badges. The basic format is:

cURL -i -X POST -H header -u signin -F operation -F badge member-profile-url

header = “Accept:application/json”
custom header to pass to server (required)

signin = administrator-id:password
for example : admin:admin

operation = “:operation=social:assignBadge” OR “:operation=social:deleteBadge”

badge = “badgeContentPath=badge-image-file”

badge-image-file = the location of the badge image file in the repository
for example : /libs/settings/community/badging/images/moderator/jcr:content/moderator.png

member-profile-url = the endpoint for the member’s profile on publish
for example : https://<server>:<port>/home/users/community/riley/profile.social.json

Examples:

Assign a moderator badge

curl -i -X POST -H "Accept:application/json" -u admin:admin -F ":operation=social:assignBadge" -F "badgeContentPath=/libs/settings/community/badging/images/moderator/jcr:content/moderator.png" /home/users/community/updcs9DndLEI74DB9zsB/profile.social.json

Revoke an assigned silver badge

curl -i -X POST -H "Accept:application/json" -u admin:admin -F ":operation=social:deleteBadge" -F "badgeContentPath=/libs/settings/community/badging/images/silver/jcr:content/silver.png" /home/users/community/updcs9DndLEI74DB9zsB/profile.social.json

Scoring and Badges for Custom Components

Scoring and badging rules may be created for custom components by associating the event topics created for the component with verbs.

Topics and Verbs

When members interact with communities features, events are sent that can trigger asynchronous listeners, like notifications and scoring.

A component’s SocialEvent instance records the events as actions that occur for a topic. The SocialEvent includes a method to return a verb associated with the action. There is an n-1 relationship between actions and verbs.

For the communities components delivered, the following tables describe the verbs defined for each topic available for use in scoring sub-rules.

Calendar Component
SocialEvent topic= com/adobe/cq/social/calendar

Comments Component
SocialEvent topic= com/adobe/cq/social/comment

File Library Component
SocialEvent topic= com/adobe/cq/social/fileLibrary

Forum Component
SocialEvent topic= com/adobe/cq/social/forum

Journal Component
SocialEvent topic= com/adobe/cq/social/journal

QnA Component
SocialEvent topic = com/adobe/cq/social/qna

Reviews Component
SocialEvent topic= com/adobe/cq/social/review

Rating Component
SocialEvent topic= com/adobe/cq/social/tally/rating

Voting Component
SocialEvent topic= com/adobe/cq/social/tally/voting

Moderation-enabled Components
SocialEvent topic= com/adobe/cq/social/moderation

Custom Component Events

For a custom component, a SocialEvent is instantiated to record the component’s events as actions that occur for a topic.

To support scoring, the SocialEvent would need to override the method getVerb() so that an appropriate verb is returned for each action. The verb returned for an action may be one commonly used (such as POST) or one specialized for the component (such as ADD RATING). There is an n-1 relationship between actions and verbs.

Troubleshooting

Badges are not appearing

If scoring and badging rules have been applied to the web site’s content, but badges are not being awared for any activity, ensure badges have been enabled for that component’s instance.

See Enable Badges for Component.

Scoring rule has no effect

If scoring and badging rules have been applied to the web site’s content, and badges are being awarded for some actions, but not others, check that the badging rule has not restricted the scoring rules to which it applies.

See the scoringRules property of Badging Rules.

Case Sensitive Typo

Most of the properties and values, especially the verbs, are case-sensitive. Verbs must be all UPPERCASE when used in a scoring sub-rule.

If the feature is not working as expected, ensure the data has been correctly entered.

Quick Test

It is possible to quickly try scoring and badging using the Getting Started Tutorial (engage) site :

• Access CRXDE Lite on author.

• Browse to the base page:

  • /content/sites/engage/en/jcr:content

• Add the badgingRules property:

  • Name: badgingRules
  • Type: String
  • Select Multi
  • Select Add
  • Enter /libs/settings/community/badging/rules/forums-badging
  • Select +
  • Enter /libs/settings/community/badging/rules/comments-badging
  • Select OK

• Add the scoringRules property:

  • Name: scoringRules
  • Type: String
  • Select Multi
  • Select Add
  • Enter /libs/settings/community/scoring/rules/forums-scoring
  • Select +
  • Enter /libs/settings/community/scoring/rules/comments-scoring
  • Select OK

• Select Save All.

Next ensure the forum and comments components allow badges to be displayed:

• Again using CRXDE Lite.

• Browse to the forum component

  • /content/sites/engage/en/forum/jcr:content/content/primary/forum

• Add allowBadges boolean property, if necessary, and ensure it is true.

  • Name: allowBadges
  • Type: Boolean
  • Value: true

Next, republish the community site.

Finally,

• Browse to the component on the publish instance.

• Sign in as a community member (for example : weston.mccall@dodgit.com / password).

• Post a new forum topic.

• The page must be refreshed for the badge to show.

  • Logout and login as a different community member (for example: aaron.mcdonald@mailinator.com/password).

• Select the Forum.

This should earn the community member a bronze badge visible with their forum post due to the first forums-badging rule’s first threshold being a score of 1.

Additional Information

More information may be found on the Scoring and Badges Essentials page for developers.

For information on the advanced scoring engine, see Advanced Scoring and Badges.

The configurable Leaderboard component and function simplifies the display of members and their scores on a community site.

Business.Adobe.com resources

Ecommerce Integrations Content Insights Targeted Content Managed Cloud Customer Experience Management Digital Asset Management