Introduction
As of September 28, 2022, the badge functionality of the Gamification app was be enhanced in order to offer a completely revamped way to manage badges in your platform.
This enhanced and improved functionality introduced important changes in your platform improving the flexibility of badges management, opening up to more complex scenarios.
The user interface of the area was redesigned in line with the new platform layout, and many important changes were made to the management of badges.
This article lists the changes introduced by this feature enhancement, as well as the APIs that were changed and developed for this new feature.
The main goal of the refactoring of the badges management was to offer Superadmins a more complete and intuitive management of badges for their users. Learn more on how to create and manage badges.
Collections of Badges
Collections of badges are groups of badges allowing Superadmins to create several campaigns, also simultaneously active in the platform. They allow you to make the associated badges only available to a custom selection of branches or to a custom group of users.
Collections can be useful in different scenarios, such as when you want different sets of badges for different branches or user groups.
As an example, you may want to award badges to:
- the employees completing the “Company Guideline” course
- the users sharing an asset, and
- the users completing the “Safety Course”.
For this purpose, you can create three sets of badges, and manage their availability:
- a Default collection available to the whole company that you can associate with the "Corporate Guidelines" course completion rule, so that anyone in the company can obtain the "Corporate Guidelines" badge upon completing the course.
- a "Europe Branch" collection available only to the European branch that you can associate with the “Security Course” and “Contributor” rules, so that employees of the European branch can get badges upon completing the "Security Course" or sharing an asset.
- a “USA Branch” collection available only to the USA branch that you can associate with the “Security Course”, so that employees of the American branch can get the badge upon completing the "Security Course".
Availability of Existing Badges
In the previous experience, badges were available to the whole company. In order to preserve the same rule when moving to the new management of badges, the existing badges were assigned to the Default collection, available to all users.
You cannot delete the default collection nor change its availability, but you can edit it, changing its name and description and adding or removing associated badges.
Badge Eligibility
When creating a badge, you will be asked to fill in the Badge Eligibility field.
This description allows Superadmins to tell users how to obtain the badge according to the automatic rules the Superadmin can set when configuring the badge.
Users will be able to see this description in their Gamification area even before they obtain the badge and will be thus encouraged to “play the game”.
Badge Code
You will be able to set codes to identify your badges.
Badge Visibility
The User Visibility options allow Superadmins to select whether users will be able to see both the badge and the points associated to it or only points in the Gamification area.
Points-Only Badges
With the new management of badges, it is possible to create “Points-only” badges. This type of badge will not be visible to the learner in their Gamification area, but will only increase the total number of points earned (or decrease it, if you set a negative value for the points-only badge).
Badge Deactivation
You will be able to switch the status of a badge to Unpublished, thus deactivating it. Unpublished badges will no longer be automatically assigned to users, but can still be manually assigned. The badges already assigned to users will remain visible in their Gamification area. You can always reactivate the badge by switching its status back to Published.
Redesigned Badge Images
As of May 24, 2022, you can choose badge images from a much wider image catalog. You can always choose to upload your own images.
Assigning Badges to Users
With the new badge management, you can manually assign also the badges for which you have set automatic assignment.
Changed APIs
This table lists all the APIs that were modified with the new badge functionalities.
API Description |
API Verb |
API Url |
Now the API, when the toggle of the new badges is active, will return the achievement text instead of the eligibility one |
GET |
/share/v1/gamification/assigned_badge/{uuid}/public? |
Now the API, when the toggle of the new badges is active, will return the achievement text instead of the eligibility one in the OG:description |
GET |
/share/v1/gamification/assigned_badge/{UUID}/shared |
The API will now return an error if the badge to be shared is points-only. Points-only badges were not previously available |
GET |
/share/v1/gamification/assigned_badge/{UUID}/shared |
New APIs
This table lists the APIs available for the new badge functionality. These APIs have been fully operational since September 28, 2022.
API Description |
API Verb |
API Url |
Retrieve the list of the badge collections, with filter options |
GET |
/share/v1/gamification/collections |
Retrieve the properties of a badge collection |
GET |
/share/v1/gamification/collections/{id} |
Create a new badge collection |
POST |
/share/v1/gamification/collections |
Update a property of a badge collection (ex: activate or deactivate it) |
PATCH |
/share/v1/gamification/collections/{id_collection} |
Associate badges and collections |
PUT |
/share/v1/gamification/collections/badges |
Delete one or more collections |
DELETE |
/share/v1/gamification/collections/batch |
Update the properties of a collection |
PUT |
/share/v1/gamification/collections/{id_collection} |
Remove associations between badges and collections |
DELETE |
/share/v1/gamification/collections/{id_collection}/badges |
Create a new badge |
POST |
/share/v1/gamification/badges |
Update a property of a badge (ex: activate or deactivate it) |
PATCH |
/share/v1/gamification/badges/{id_badge} |
Delete one or more badges |
DELETE |
/share/v1/gamification/badges/batch |
Retrieve the properties of a badge |
GET |
/share/v1/gamification/badges/{id_badge} |
Retrieve the list of users which have been assigned the {id_badge} badge |
GET |
/share/v1/gamification/{id_badge}/assigned_users |
Retrieve the list of assignments of the {id_badge}badge to the {id_user} user |
GET |
/share/v1/gamification/badges/{id_badge}/users/{id_user}/assigned |
Save the badge and its properties |
PUT |
/share/v1/gamification/badges/{id_badge} |
Retrieve standard and custom images available for use in badges |
GET |
/share/v1/gamification/badges/images |
Delete a specific badge custom image, which has been previously uploaded |
DELETE |
/share/v1/gamification/badges/images/{image_id} |
Associate the {id_badge} badge to the specified users |
PUT |
/share/v1/gamification/badges/{id_badge}/assigned_users/batch |
Remove all the assignments of the {id_badge} badge from the specified users |
DELETE |
/share/v1/gamification/badges/{id_badge}/assigned_users/batch |
Remove specific {id_badge } badge assignments from users |
DELETE |
/share/v1/gamification/badges/{id_badge}/users/{id_user}/assigned_achievement/batch |
Return the training material of a {course_id} course. The list is specific to be used in badges and shall not be used for other purposes |
GET |
/share/v1/gamification/courses/{id_course}/los |