Communities Scoring and Badges communities-scoring-and-badges

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

Note that awarding of badges is not enabled by default.

Badges 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

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

Awarded Badges 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:

Included in the release are three reward-based badges:

Custom Badges 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 enable-scoring

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

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 apply-rules-to-content

To enable scoring and badges, add the properties scoringRules and badgingRulesto 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:contentnode.

Enable Badges for Component 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 example-allowbadges-for-forum-component-instance

Scoring Rules 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:

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:contentnode that specify the list of sub-rules that define it.

Scores are stored in SRP.

Scoring Sub-Rules scoring-sub-rules

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

Each scoring sub-rule identifies

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:

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

Notes:

Activating Custom Scoring Rules 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

Badging rules link scoring rules to badges by specifying:

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

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

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

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

Included Badging Rules included-badging-rules

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

Notes:

Activating Custom Badging Rules 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 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: /etc/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: examples

Assign a moderator badge assign-a-moderator-badge

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

Revoke an assigned silver badge revoke-an-assigned-silver-badge

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

Scoring and Badges for Custom Components 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 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 actionsthat occur for a topic. The SocialEvent includes a method to return a verbassociated with the action. There is an n-1 relationship between actionsand verbs.

For the communities components delivered, the following tables describe the verbsdefined for each topicavailable 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 custom-component-events

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

To support scoring, the SocialEvent would need to override the method getVerb() so that an appropriate verbis 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 actionsand verbs.

Troubleshooting troubleshooting

Badges are not appearing 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 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 scoringRulesproperty of Badging Rules.

Case Sensitive Typo 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 quick-test

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

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

Next, republish the community site.

Finally,

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