LP-5613 #2
254
README.md
254
README.md
@ -1,175 +1,193 @@
|
||||
# Badges plugin
|
||||
Let your users show appreciation for their fellow colleagues by granting badges.
|
||||
# Плагин значков для Loop
|
||||
|
||||
## Install
|
||||
Get the latest release from [GitHub](https://github.com/larkox/mattermost-plugin-badges/releases) and [install it manually](https://developers.mattermost.com/integrate/plugins/server/hello-world/#installing-the-plugin) on your server.
|
||||
Позволяет пользователям выражать признательность коллегам, выдавая им значки.
|
||||
|
||||
## Configuration
|
||||
## Установка
|
||||
|
||||
|
||||
Скачайте последний релиз и установите его вручную через системную консоль Loop.
|
||||
|
||||
- **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 |
|
||||
Выполните слэш-команду `/badges create type`, чтобы открыть диалог создания.
|
||||
|
||||
### Creating a badge
|
||||
Run the slash command `/badges create badge` to open the creation dialog.
|
||||
- **Название**: название типа, отображаемое в описании значков.
|
||||
- **Все могут создавать значки**: если отмечено, любой пользователь Loop может создавать значки этого типа.
|
||||
- **Список допущенных к созданию**: username'ы через запятую — кто может создавать значки этого типа.
|
||||
- **Все могут выдавать значки**: если отмечено, любой пользователь Loop может выдавать значки этого типа.
|
||||
- **Список допущенных к выдаче**: username'ы через запятую — кто может выдавать значки этого типа.
|
||||
|
||||
|
||||
### Права доступа
|
||||
|
||||
- **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.
|
||||
Примеры конфигураций (ECC: все могут создавать, CC: список допущенных к созданию, ECG: все могут выдавать, CG: список допущенных к выдаче):
|
||||
|
||||
### 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.
|
||||
| Права | Пример использования | ECC | ECG | CC | CG |
|
||||
|-------|---------------------|-----|-----|----|----|
|
||||
| Только администраторы могут создавать и выдавать | | false | false | пусто | пусто |
|
||||
| Только user1 создаёт, но выдавать может каждый | Значок "Спасибо" от коллег | false | true | user1 | пусто |
|
||||
| Только user1 создаёт, выдают только user2 и user3 | Значок "MVP" — руководство создаёт, тимлиды выдают | false | false | user1 | user2, user3 |
|
||||
| user1 и user2 создают, выдают только свои значки | Командные значки без создания нового типа на каждую команду | false | false | user1, user2 | пусто |
|
||||
| Все создают и выдают только свои значки | | true | false | пусто | пусто |
|
||||
| Все создают и выдают любые значки | | true | true | пусто | пусто |
|
||||
|
||||
|
||||
### Создание значка
|
||||
|
||||
The dialog looks like this:
|
||||
Выполните слэш-команду `/badges create badge`, чтобы открыть диалог создания.
|
||||
|
||||
|
||||
- **Название**: название значка.
|
||||
- **Описание**: описание значка.
|
||||
- **Изображение**: только эмодзи. Укажите имя эмодзи как в сообщении (например `:+1:` или `:smile:`). Кастомные эмодзи тоже поддерживаются.
|
||||
- **Тип**: тип значка. В списке отображаются только типы, для которых у вас есть права на создание.
|
||||
- **Множественный**: можно ли выдавать этот значок одному человеку несколько раз.
|
||||
|
||||
- **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.
|
||||
Открыть диалог выдачи можно двумя способами:
|
||||
- Выполнить команду `/badges grant`.
|
||||
- Нажать **Выдать значок** в поповере профиля пользователя.
|
||||
|
||||
|
||||
- **Пользователь**: кому выдаётся значок.
|
||||
- **Значок**: какой значок выдаётся.
|
||||
- **Причина**: необязательное пояснение (особенно полезно для значков типа "Спасибо").
|
||||
- **Уведомить в этом канале**: если отмечено, бот опубликует сообщение в текущем канале о выдаче значка.
|
||||
|
||||
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.
|
||||
Для создания подписки необходимы права администратора значков. Открыть диалог создания подписки можно двумя способами:
|
||||
- Выполнить команду `/badges subscription create`.
|
||||
- Нажать **Добавить подписку на значки** в меню канала.
|
||||
|
||||
### 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.
|
||||
- **Тип**: тип значков, на который подписывается канал.
|
||||
|
||||
|
||||
|
||||
Для удаления подписки используйте `/badges subscription remove` или **Удалить подписку на значки** в меню канала.
|
||||
|
||||
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.
|
||||
Для редактирования и удаления типов необходимы права администратора значков. Для редактирования и удаления значка — права администратора или создателя значка.
|
||||
|
||||
|
||||
Выполните `/badges edit type --type typeID` или `/badges edit badge --id badgeID`, чтобы открыть диалог редактирования. Автодополнение поможет выбрать нужный значок или тип.
|
||||
|
||||
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.
|
||||
### Список значков
|
||||
|
||||
|
||||
Значки отображаются в нескольких местах. В поповере профиля — до 20 последних полученных значков. При наведении на значок появляется подсказка, при клике открывается панель с деталями значка.
|
||||
|
||||
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.
|
||||
## REST API
|
||||
|
||||
Using the [PluginHTTP](https://developers.mattermost.com/integrate/plugins/server/reference/#API.PluginHTTP) API method, you can create a request to the badges plugin to "Ensure" and to "Grant" the badges needed.
|
||||
Базовый URL: `https://<сервер>/plugins/ru.loop.plugin.achievements`
|
||||
|
||||
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.
|
||||
Все запросы требуют токен в заголовке:
|
||||
```
|
||||
Authorization: Bearer <токен>
|
||||
```
|
||||
|
||||
### Ensure badges
|
||||
URL: `/com.mattermost.badges/papi/v1/ensure`
|
||||
Токен можно получить в настройках аккаунта Loop: **Профиль → Безопасность → Персональные токены доступа**.
|
||||
|
||||
Method: `POST`
|
||||
### Типы значков
|
||||
|
||||
| Метод | Эндпоинт | Описание |
|
||||
|-------|----------|----------|
|
||||
| `GET` | `/api/v1/getTypes` | Список типов, доступных текущему пользователю |
|
||||
| `POST` | `/api/v1/createType` | Создать тип (только администраторы) |
|
||||
| `PUT` | `/api/v1/updateType` | Обновить тип (только администраторы) |
|
||||
| `DELETE` | `/api/v1/deleteType/{typeID}` | Удалить тип и все его значки (только администраторы) |
|
||||
|
||||
### Значки
|
||||
|
||||
| Метод | Эндпоинт | Описание |
|
||||
|-------|----------|----------|
|
||||
| `GET` | `/api/v1/getAllBadges` | Полный список значков |
|
||||
| `GET` | `/api/v1/getUserBadges/{userID}` | Значки конкретного пользователя |
|
||||
| `GET` | `/api/v1/getBadgeDetails/{badgeID}` | Детали значка и список получателей |
|
||||
| `POST` | `/api/v1/createBadge` | Создать значок |
|
||||
| `PUT` | `/api/v1/updateBadge` | Обновить значок |
|
||||
| `DELETE` | `/api/v1/deleteBadge/{badgeID}` | Удалить значок и историю его выдачи |
|
||||
|
||||
### Выдача значков
|
||||
|
||||
| Метод | Эндпоинт | Описание |
|
||||
|-------|----------|----------|
|
||||
| `POST` | `/api/v1/grantBadge` | Выдать значок пользователю |
|
||||
| `POST` | `/api/v1/revokeOwnership` | Отозвать выдачу значка |
|
||||
|
||||
### Подписки
|
||||
|
||||
| Метод | Эндпоинт | Описание |
|
||||
|-------|----------|----------|
|
||||
| `GET` | `/api/v1/getChannelSubscriptions/{channelID}` | Список подписок канала |
|
||||
| `POST` | `/api/v1/createSubscription` | Создать подписку (только администраторы) |
|
||||
| `POST` | `/api/v1/deleteSubscription` | Удалить подписку (только администраторы) |
|
||||
|
||||
---
|
||||
|
||||
## Интеграция с другими плагинами (Plugin API)
|
||||
|
||||
Плагин поддерживает интеграцию с другими плагинами Loop через механизм `PluginHTTP`. Авторизация выполняется автоматически ядром Loop — токен не нужен.
|
||||
|
||||
Доступны два эндпоинта:
|
||||
|
||||
### Ensure — создать значки если не существуют
|
||||
|
||||
URL: `/ru.loop.plugin.achievements/papi/v1/ensure`
|
||||
|
||||
Метод: `POST`
|
||||
|
||||
Body example:
|
||||
```json
|
||||
{
|
||||
"Badges":[
|
||||
"Badges": [
|
||||
{
|
||||
"name":"My badge",
|
||||
"description":"Awesome badge",
|
||||
"image":"smile",
|
||||
"image_type":"emoji",
|
||||
"multiple":true
|
||||
"name": "My badge",
|
||||
"description": "Awesome badge",
|
||||
"image": "smile",
|
||||
"image_type": "emoji",
|
||||
"multiple": true
|
||||
}
|
||||
],
|
||||
"BotId":"myBotId"
|
||||
"BotId": "botUserId"
|
||||
}
|
||||
```
|
||||
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`
|
||||
Создаёт значки, если они ещё не существуют (проверка по имени), и возвращает их с заполненными `id`.
|
||||
|
||||
Method: `POST`
|
||||
### Grant — выдать значок
|
||||
|
||||
URL: `/ru.loop.plugin.achievements/papi/v1/grant`
|
||||
|
||||
Метод: `POST`
|
||||
|
||||
Body example:
|
||||
```json
|
||||
{
|
||||
"BadgeID":"badgeID",
|
||||
"BotId":"myBotId",
|
||||
"UserID":"userID",
|
||||
"Reason":""
|
||||
"BadgeID": "badgeID",
|
||||
"BotId": "botUserId",
|
||||
"UserID": "userID",
|
||||
"Reason": "За крутую работу"
|
||||
}
|
||||
```
|
||||
Grant badges will grant the badge with the badge id provided from the bot to the user defined. Reason is optional.
|
||||
|
||||
Выдаёт значок от имени указанного бота пользователю. `Reason` — необязательное поле.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user