README.md

Badges plugin

Let your users show appreciation for their fellow colleagues by granting badges.

Install

Get the latest release from GitHub and install it manually on your server.

Configuration

• Badges admin: Every System Admin is considered a badges admin. System Admins can assign the badges admin role to a single person by specifying their username. Only a single badge admin assignment is permitted.

Usage

Creating a type

Badge admins can create different types of badges, and each type of badge can have its own permissions. You must be a badge admin to create a badge type. Run the slash command /badges create type to open the creation dialog.

• Name: The type of badge that's visible in the badges description.
• Everyone can create badge: If you mark this checkbox, every user in your Mattermost instance can create badges of this type.
• Can create allowlist: This list contains the usernames (comma separated) of all the people allowed to create badges of this type.
• Everyone can grant badge: If you mark this checkbox, every user in your Mattermost instance can grant any badge of this type.
• Can grant allowlist: This list contains the usernames (comma separated) of all the people allowed to grant badges of this type.

Permissions details

Badge admins can always create types, create badges for any type, and grant badges from any type, regardless of the permissions in place for a given badge type. A badge creator can always grant the badge they created. Any other user is subject to the permissions defined as part of the badge type.

Some examples of badge permissions by type are included below. Remember that badge admins have full control over badges, and badge creators can always grant badges. The examples below are intended to demonstrate how badge permissions can be configured for non-admin users to get the most out of badges. (ECC: Everyone Can Create, CC: Can Create Allowlist, ECG: Everyone Can Grant, CG: Can Grant Allowlist)

Permissions	Example	ECC	ECG	CC	CG
Only badge admins can create and grant badges		false	false	empty	empty
Only user1 can create badges, but everyone can grant them	for peer appreciation badges, like "Thank you" badge	false	true	user1	empty
Only user1 can create badges, and only user2 and user3 can grant them	lead appreciation badges, like "MVP" badge, where the management create the badges, and the team leads are the ones granting them to their team members	false	false	user1	user2, user3
Only user1 and user2 can create badges, but they can only grant the badges they have created	can be used to have team specific badges without creating a new type for every team	false	false	user1, user2	empty
Everyone can create badges, but can only grant the badges they have created		true	false	empty	empty
Everyone can create and grant any badge		true	true	empty	empty

Creating a badge

Run the slash command /badges create badge to open the creation dialog.

• Name: Name of the badge.
• Description: Description of the badge.
• Image: Only emojis are allowed. You must input the emoji name as you would to add it to a message (e.g. :+1: or :smile:). Custom emojis are also allowed.
• Type: The type of badge. This list will show only types you have permissions to create.
• Multiple: Whether this badge can be granted more than once to the same person.

Details about Multiple

All badges can be assigned to any number of people. What the Multiple setting controls is whether this badge can be granted more than once to the same person. For example, a "Thank you" badge should be grantable many times (many people can be thankful to you on more than one occasion), and therefore, a Thank You badge should have the Multiple option selected. However, a "First year in the company" badge should be granted only once since a user won't celebrate this milestone multiple times at the same company. This type of badge should have the Multiple option unselected.

Granting a badge

There are two ways to open the grant dialog:

• Run the /badges grant command.
• Click on the Grant badge link available in the Profile Popover, visible when you click on someone's username.

The dialog looks like this:

• User: The user you want to grant the badge to (may be prepopulated if you clicked the grant button from the profile popover, or added the username in the command).
• Badge: The badge you want to grant (may be prepopulated if you added the badge id in the command).
• Reason: An optional reason why you are awarding this badge. (Specially useful for badges like "Thank you").
• Notify on this channel: If you select this option, a message from the badges bot will be posted in the current channel, letting everyone in that channel know that you granted this badge to that person. The user that received the badge will always receive a DM from the badges bot letting them know they have been awarded a badge. In addition, the following may happen:
• If Notify on this channel was marked, the badges bot will post a message on the current channel letting everyone know that the user has been awarded a badge.
• If a subscription for this badge type is set, the badges bot will post a message on all subscribed channels letting everyone know that the user has been awarded a badge.

If you try to award a badge that can't be awarded more than once to a single recipient, the badge won't be granted.

Subscriptions

In order to create a subscription, you must be a badges admin. Subscriptions will create posts into a channel every time a badge is granted. There is no limit to the number of subscriptions per channel or per type. There are two ways to open the subscription creation dialog:

• Run the /badges subscription create command.
• Click on the Add badge subscription menu from the channel menu.

The dialog looks like this:

• Type: The type of badges you want to subscribe to this channel.

In order to remove subscriptions, a similar dialog can be opened by using the /badges subscription remove and the Remove badge subscription option from the channel menu.

Editing a deleting badges and types

In order to edit or delete types you must be a badge admin. In order to edit or delete a badge, you must be a badge admin or the creator. Run /badges edit type --type typeID or /badges edit badge --id badgeID to open a dialog pretty similar to the creation dialog. IDs are not human readable, but Autocomplete will help you select the right badge.

The only difference to the creation is one extra checkbox to remove the current type or badge. If you mark this checkbox and click Edit, the badge or type will be removed. When you remove a badge, the badge is deleted permanently, along with any information about who that badge was granted to. When you remove a type, the type and all the associated badges are removed completely.

Badge list

Badges show on several places. On the profile popover of the users, they show up to the last 20 badges granted to that user. Hovering over the badges will give you more information, and cliking on them will open the Right Hand Sidebar (RHS) with the badge details.

The channel header button will open the RHS with the list of all badges.

Clicking on any badge will lead you to the badge details. Here you can check all the users that have been granted this badge.

Clicking on any username on the badge details screen will lead you to the badges granted to that user.

Using the Plugin API to create and grant badges

This plugin can be integrated with any other plugin in your system, to automatize the creation and granting of badges.

Using the PluginHTTP API method, you can create a request to the badges plugin to "Ensure" and to "Grant" the badges needed.

The badges plugin exposes the badgesmodel package to simplify handling several parts of this process. Some important exposed objects:

• badgesmodel.PluginPath (/com.mattermost.badges): The base URL for the plugin (the plugin id).
• badgesmodel.PluginAPIPath (/papi/v1): The plugin api route.
• badgesmodel.PluginAPIPathEnsure (/ensure): The ensure endpoint route.
• badgesmodel.PluginAPIPathGrant (/grant): The grant endpoint route.
• badgesmodel.Badge: The data model for badges.
• badgesmodel.EnsureBadgesRequest: The data model of the body of a Ensure Badges Request.
• badgesmodel.GrantBadgeRequest: The data model of the body of a Grant Badge Request.
• badgesmodel.ImageTypeEmoj (emoji): The emoji image type. Other image types are considered, but we recommend using emojis.

Ensure badges

URL: /com.mattermost.badges/papi/v1/ensure

Method: POST

Body example:

{
   "Badges":[
      {
         "name":"My badge",
         "description":"Awesome badge",
         "image":"smile",
         "image_type":"emoji",
         "multiple":true
      }
   ],
   "BotId":"myBotId"
}

Ensure badges will create badges if they already do not exist, and return the list of badges including the ids. In order to check whether a badge exist or not, it will only check the name of the badge.

Grant badges

URL: /com.mattermost.badges/papi/v1/grant

Method: POST

Body example:

{
   "BadgeID":"badgeID",
   "BotId":"myBotId",
   "UserID":"userID",
   "Reason":""
}

Grant badges will grant the badge with the badge id provided from the bot to the user defined. Reason is optional.