HacknPlan can be integrated with Discord to execute commands from the Discord server and receive notifications and updates. These are basic commands that allow you to quickly create items or make the most common day-to-day changes without leaving Discord. Also, it allows members of your community to report bugs and make suggestions.

The integration supports two types of commands:

• Team commands: These commands allow users in the development team to execute commands from Discord as if they were doing it from HacknPlan, such as create a task, add a comment, move items to a different stage and so on. The availability of these commands is limited by the user permissions in HacknPlan, and they require that the HacknPlan user and the Discord user are linked.
• Community commands: These commands can be executed by users who are not part of the development team in HacknPlan. They are useful to allow your community members to report bugs or make suggestions.

Creating an integration

To integrate a project and a Discord server, go to Administration -> Integrations in HacknPlan and click “New” on the Discord panel. This will launch the Discord authorization flow, where you have to select your server and accept the required permissions the HacknPlan bot will have.

Important To guarantee all the functionality works correctly, all the permissions the authorization process requires for our bot should be accepted, otherwise some of the features may throw errors.

Once the authorization is complete, you’ll be redirected to HacknPlan and the integration configuration will appear.

Community commands:

The first thing you can configure is the category and board that will be used to create work items using the two available community commands (report-bug and suggest-feature). By default, the system is configured to create tasks of category Bug (if present in your project) for the report-bug command, and User stories for the suggest-feature command. Also, both commands send the items to the backlog by default. You can modify these values to accommodate the commands to your workflow.

Team members:

For team commands to work properly, you need to link the users in the Discord server with their equivalent in HacknPlan. This will allow those users to execute slash commands as if they were doing it from HacknPlan.

When you create an integration, your user account is automatically linked, but the rest of the team has to request access from Discord and then be linked and validated in HacknPlan. To do that, follow these steps:

• Every team member has to execute the /request-access slash command in your Discord server for each project. This gives HacknPlan “permission” from the Discord user to link the account.
• Go to the Discord integration, click edit, and then, for each unassigned Discord user, select the equivalent HacknPlan user and click “Validate”.
• Save the changes.

Note that you can revoke any user access to the Discord integration by clicking on the trash can icon next to each team member.

Note Initially, we allowed to assign HacknPlan users to Discord users unilaterally from the integration configuration dialog. Then, the Discord team informed us this practice didn’t follow their policies and had to change it so Discord users requested access. However, users who created their integrations before this change can still assign users like before, but all new integrations will use the new method.

Discord configuration

Besides the permissions applied on the HacknPlan side, you can also configure the HacknPlan bot in Discord to fine-tune who and where can use the commands.

Important For all commands to work properly, the HacknPlan bot or role must be added to the channel or channels where you want it to be available.

In Discord, go to Server Settings -> Integrations and click “Manage” in the HacknPlan entry:

Roles and members

Here you can choose which roles and members can use the commands. Note that you can override this configuration at command level, so the best option is to configure the roles and members here that most of the commands will use, and then override the exceptions. For instance, a typical configuration would be removing the permissions for @everyone and add your team roles or users, so you can use the team commands. Then you can override this configuration for the report-bug and suggest-feature commands to allow other users outside the team to use them.

Channels

Just like the roles and members, configure the channels where most of the commands can be used (team commands) and then fine-tune the exceptions (community commands).

Commands

In this section, you can override the general configuration for each command and set their own role and member permissions and allowed channels. Make sure each type of user can only use the commands that make sense in the channels where it makes sense. If there are commands you don’t need at all, you can disable them here by removing access to @everyone.

Team Commands

The team commands allow the members of the HacknPlan project to execute actions as themselves from Discord.

create-task

Creates a new task.

• Params:
  • project (only if multiple projects are integrated with the server)
  • board
  • category
  • title
  • assign-to (optional)
  • description (optional)
  • sync (if true, creates a thread and automatically posts updates, optional)

create-subtask

Creates a subtask on a given task.

• Params:
  • project (only if multiple projects are integrated with the server)
  • task (by title or id)
  • title

create-story

Creates a new user story.

• Params:
  • project (only if multiple projects are integrated with the server)
  • board
  • title
  • assign-to (optional)
  • description (optional)
  • sync (if true, creates a thread and automatically posts updates, optional)

create-story-task

Creates a new task on a given user story.

• Params:
  • project (only if multiple projects are integrated with the server)
  • story (by title or id)
  • category
  • title
  • assign-to (optional)
  • description (optional)
  • sync (if true, creates a thread and automatically posts updates, optional)

create-board

Creates a new board (admin only).

• Params:
  • project (only if multiple projects are integrated with the server)
  • title
  • description (optional)
  • sync (if true, creates a thread and automatically posts updates, optional)

change-stage

Changes the stage of a work item.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)
  • stage

change-importance

Changes the importance level of a work item.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)
  • importance

add-comment

Adds a comment to a work item.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)
  • comment

assign-user

Assigns a user to a work item.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)
  • assign-to (the user who will be assigned)

send-to-board

Sends a work item to another board.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)
  • board

send-to-backlog

Sends a work item to the backlog.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)

log-work

Logs work on a work item

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)
  • duration
  • comment (optional)

toggle-subtask

Toggles the status of a subtask.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)
  • subtask

view-item

Displays a work item.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)
  • sync (if true, creates a thread and automatically posts updates, optional)

view-board

Displays a board.

• Params:
  • project (only if multiple projects are integrated with the server)
  • board
  • sync (if true, creates a thread and automatically posts updates, optional)

list-subtasks

Lists the subtasks of a work item.

• Params:
  • project (only if multiple projects are integrated with the server)
  • workitem (by title or id)

list-story-tasks

Lists the subtasks of a work item.

• Params:
  • project (only if multiple projects are integrated with the server)
  • story (by title or id)

Community commands

The community commands are those which don’t require to have a HacknPlan user linked to the Discord user who executes the command. The purpose of these commands is to allow your community members post basic work items to HacknPlan.

Unlike the team commands that are fully constructed using slash command parameters, the community commands launch a small modal where users can enter the title and the description of the item they’re creating, for a more user friendly experience.

report-bug

Creates a community-reported bug.

• Params:
  • project (only if multiple projects are integrated with the server)
• Fields:
  • title
  • description

suggest-feature

Creates a feature request.

• Params:
  • project (only if multiple projects are integrated with the server)
• Fields:
  • title
  • description