In the Part 5 of this blog series you showed notifications to the user by creating pop up messages. In this blog post you will introduce game design elements Badges, Levels and Leaderboard in the user profile page.
Level describes the status of a user and gamification service allows you to define levels based on a defined point category. Badge is the visual representation of an achievement. Leaderboard displays ranks of players based upon their points.
In order to implement this, first, you will configure the game mechanics using gamification workbench.
Second, you will retrieve user achievements: Points, Badges, Leaderboards and Levels using gamification service APIs.Lastly, you will update the existing Reputation section to show user achievements details.
1. Configure the game mechanics:
The objective of the blog is not to explore game design but to explore its game design elements into an application so you will create a simple game design by using the app file JIRA_App(Part6).zip (contains game mechanics). Game mechanics is packaged in an app named JIRA.
You need to replace the existing app JIRA in the gamification workbench with this.
You can achieve this first by deleting the app JIRA (more information on how to delete an app can be found here.) and then by importing the app file JIRA_App(Part6).zip in your gamification workbench as described here.
Note:
The player’s achievements and game mechanics details will be lost when an app is deleted from the gamification workbench. In case if you want to retain these changes then you can export your app as described here.
The new app JIRA includes entities from the old app JIRA (defined in Part1 ) and few additional entities as described below:
1. A Point named Blocker issues used to track the number of Blocker issues created.
2. Three levels (Level 1, Level 2, Level 3). based on Experience Points (XP) category.
3. Two badges named Testing Expert and Testing Champion
4. Following three rules:
a) TrackBlocker: Tracks the number of Blocker issues created in JIRA.
b) AssignTestingExpert: Assigns Badge TestingExpert to the player when number of Blocker issues created exceeds 10.
c) AssignTestingChampion: Assigns Badge TestingChampion to the player when number of Blocker issues created exceeds 50.
Verify that the app was successfully imported: select JIRA in the top most right corner.
Navigate to tab GAME MECHANICS as shown in the screenshot below.
Verify that the contents of tabs Points, Levels, Badges, Rules are as shown in the screenshots below.
Test game mechanics:
In order to test the game mechanics first you will create players for your app JIRA using API Terminal.
For some of the players, you will send events of type issueCreated and priority Blocker to the gamification service using API terminal.
Create players in app JIRA:
1. Navigate to API terminal in gamification workbench by clicking GAME MECHANICS->Terminal as shown in the screenshot below
2. Provide the following as JSON Input by replacing the contents:
[
{ "method":"createPlayer",
"params":
["chris.s@mail.com",
"Chris"
]
}
]
This API is used to create new player by invoking method createPlayer() of gamification service. Following are the input parameters of this method.
Input parameter | Description |
The unique id for the player to be created. | |
Chris | Name of the player |
| true | To show the player's name to others |
| null | Profile image of the player |
3. Click Execute button to execute the API call and you will get success message as shown in the screenshot below.
4. Repeat steps 2-3 to create following players in the app JIRA.
a) Ivan Novak (ivan.novak@mail.com)
b) Joe Borg(joe.borg@mail.com)
c) Maria Rossi(maria.rossi@mail.com)
5. Navigate to the tab PLAYER. Verify the list of players as shown in the screenshot below.
Send events to gamification service:
1. Provide the following as JSON Input by replacing the contents
[
{
"method": "handleEvent",
"params":
[
{
"type":"issueCreated",
"playerid":"chris.s@mail.com",
"data":{"relevance":"Blocker"}
}
]
}
]
The API handleEvent() is already explained in Test game mechanics section in Part 1 of this blog series.
2. Click Execute button to execute the API call and you will get success message as shown in the screenshot below.
3. Follow steps 1-2 and repeat 11 more times to send 11 more events. This is for player Chris. Repeat 14 times to send 14 events for player Maria Rossi. Repeat 10 times to send 10 events for player Ivan Novak.
4. Verify that Point Blocker issues, Badge Testing Expert and Level have been assigned to the players. Navigate to the tab PLAYERS.
Click on the Chris. You will see Experience points 24 ,Blocker issues 12, Level 1 and Badge Testing Expert in the Achievements & Teams section as shown in the screenshot below
8. Repeat steps 5 to 7 to verify Points, Badges, and Levels for Players Maria Rossi and Ivan Novak.
2. Retrieve user achievements
1. Switch to Eclipse and open the file GamificationProxy.java located at package com.sap.gamification.plugins.servlet.
2. Replace the code in the file GamificationProxy.java with code GamificationProxy.txt.zip provided as additional file to this blog. Unzip the file and copy-and-paste the contents to the fileGamificationProxy.java.
The class GamificationProxy
The class GamificationProxy has a method named getPlayerProfileData() which uses Technical Endpoint to get player details by invoking the method getPlayeRecord().The HTTP POST request will look like the following:
https://<gamification service host>/gamification/api/tech/JsonRPC?
json={"method":"getPlayerRecord","params":["chris.s@mail.com"]}&app=JIRA
Query parameter | Value |
Json | method getPlayerRecord() and parameters (retrieves sum of Points, Levels, Badges etc. for given player) |
App | JIRA (name of the app which contains the game mechanics as defined in the gamification workbench) |
Input parameter | Description |
The unique id of the player |
The class GamificationProxy has a method named getRelativeLeaderboardDetails() which uses Technical Endpoint to retrieve leader board details for a month by invoking gamification service method geLeaderboardForPlayer().
The HTTP POST request will look like the following:
https://<gamification service host>/gamification/api/tech/JsonRPC?
json={"method":" geLeaderboardForPlayer","params":["chris.s@mail.com","Experience Points",1, null, 1445417448230, 1445365800000]}&app=JIRA
Query parameter | Value |
Json | method getLeaderboardForPlayer() and parameters (returns a relative leaderboard which provides name, rank and sum of Experience Points etc. of given user and his neighbors whose ranks either come before and after the given user) |
App | JIRA (name of the app which contains the game mechanics as defined in the gamification workbench) |
Input parameter | Description |
The unique id of the player | |
Experience Points | Name of the point category(on which leaderboard to be calculated) |
1 | how many players before and after the given player should be returned |
1445417448230 | Start month date from which points are taken into account (timestamp). |
1445365800000 | End month date to which points are taken into account (timestamp) |
Test the class GamificationProxy:
The class GamificationProxy defines a method main() to test gamification service API
public static void main(String arg []) throws Exception {
EnvironmentUtility.readEnvironmentValues();
GamificationProxy gamificationProxy= new GamificationProxy();
String playerProfileData = gamificationProxy.getPlayerProfileData("chris.s@mail.com");
System.out.print ("Profile details: \n"+playerProfileData);
String relativeLeaderBoardDetails=gamificationProxy.
getRelativeLeaderBoardDetails("chris.s@mail.com");
System.out.print ("\nLeaderboard details: \n"+relativeLeaderBoardDetails);
}
1. Run the ‘GamificationProxy’ configuration (which you created in the previous blog Part 5) to execute the class GamificationProxy. Following output will be displayed in console.
Profile details:
{"result":{"earnedBadges":[{"name":"TestingExpert","receivedOn":1445418617873,"description":"Testing Expert Badge","showCasePosition":-1,"image":{"id":513351,"mimeType":"png","filename":"TestingExpert.png","url":"/gamification/api/picture/GetPicture?id\u003d513351"}}],
"scores":[{"displayName":"Chris","image":null,"scorer":"chris.s@mail.com","pointName":"Blockerissues","amount":12.0,"rank":0},{"displayName":"Chris","image":null,"scorer":"chris.s@mail.com","pointName":"Experience Points","amount":24.0,"rank":0}],"activeMissions":[],"completedMissions":[],
"currentLevels":[{"name":"1","pointName":"Experience Points","image":null,"description":null,"from":0.0,"to":100.0,"currentPointAmount":24.0}],"teams":[],"isPublic":true,"playerId":"chris.s@mail.com","name":"Chris","image":null},"error":null,"type":null}
Profile details:
Following objects will be used for user profile page:
1. List earnedBadges contains entry name as Testing Expert.
2. List scores contain entry pointName as Experience Points and entry amount as 24 which is the sum ofExperience Points earned by him.
3. List currentLevels contains entry name as 1.
Leaderboard details:
{"result":[{"displayName":"Maria Rossi","image":null,"scorer":"maria.rossi@mail.com","pointName":"Experience Points","amount":28.0,"rank":1},{"displayName":"Chris","image":null,"scorer":"chris.s@mail.com","pointName":"Experience Points","amount":24.0,"rank":2},{"displayName":"Ivan Novak","image":null,"scorer":"ivan.novak@mail.com","pointName":"Experience Points","amount":20.0,"rank":3}],"error":null,"type":null}
Leaderboard details:
Following objects will be used inside the leaderboard for user profile page.
1. List result contains entry displayName as Maria Rossi, amount (sum of Experience points) as 28 and rank as 1.
2. List result contains entry displayName as Chris, amount (sum of Experience points) as 24 and rank as 2.
3. List result contains entry displayName as Ivan Novak, amount (sum of Experience points) as 20 and rank as 3.
Create REST services in JIRA Server for Profile data and Relative leaderboard:
1. The code to create REST service for profile data has been already added in Part4.
2. To create REST Service for Relative leaderboard, add the following lines of code to the method doGet()of class UserAchievementsServlet.
else if (request.getPathInfo().equalsIgnoreCase("/relativeleaderboard")) {
String relativeLeaderBoard = null;
try {
relativeLeaderBoard = gamificationProxy.getRelativeLeaderBoardDetails(playerName);
} catch (Exception e) {
log.error(" Error during accessing relative leaderboard data",e.getMessage());
}
log.info("Relative leaderboard data " + relativeLeaderBoard);
response.getWriter().println(relativeLeaderBoard);
}
3. Update Reputation section
1. Replace the code in the file gamificationProfilePanel.vm located at package new-gamification-plugin\src\main\resources\templates\webpanel with code gamificationProfilePanel.txt.zip provided as the additional file to this blog. Unzip the file and copy-and-paste the contents to the file gamificationProfilePanel.vm.
The file gamificationProfilePanel.vm has functions _getProfileData() and _getLeaderBoard() which retrieves and displays profile data (Experience Points, Level, Badges) and leaderboard details(Rank, Name, Experience Points ) by making Ajax call to the REST service.
Test Integration with JIRA
1. Open a command prompt and run the following set of commands to set environment variables.
set user_name=<HANA Cloud Platform user name>
set user_password=<HANA Cloud Platform password>
set host = < gamification service host>
If you are running this application behind the firewall you also need to set http_proxy_host andhttp_proxy_port by using following commands.
set http_proxy_host= <Http proxy name>
set http_proxy_port= <Http port number>
2. Change directory to the folder jira-gamification-plugin and run the following command
atlas-run
3. Once JIRA has started successfully, open the URL printed in the message.
4. Log in with user chris.s@mail.com and switch to the user profile page (as described in section Test Integration with JIRA in Part4).
5. User achievements would be visible in section Reputation as shown in the screenshot below.
Congratulations!! With this,blog series is complete :smile: :smile: .
I hope that this blog series helped you to understand integration of the SAP HCP gamification service into an application. In case if you have any doubts or need clarifications on anything then please let me know.
All the Best,
Anuj
- SAP Managed Tags:
2 Comments
