|
|
|
|
@ -0,0 +1,294 @@
|
|
|
|
|
---
|
|
|
|
|
title: Task Bot
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
Task Bot (hereinafter the "Application") is a custom utility we developed for [Retro Island Gaming](https://retroisland.ny), but the source code is available for all to use as denoted in our software license.
|
|
|
|
|
|
|
|
|
|
We do NOT offer a public instance of this Application. Instead, please refer to Section 2 for instructions on setting up your own version.
|
|
|
|
|
|
|
|
|
|
## 1. User Documentation
|
|
|
|
|
|
|
|
|
|
This section is for those interacting with a live instance of the Application.
|
|
|
|
|
|
|
|
|
|
### 1.1. User Interactivity
|
|
|
|
|
|
|
|
|
|
Interaction with the Application is done through a series of slash commands ("Commands") exposed via Discord's native UI. The primary function of the Application is to allow users to create and manage "tasks", or records of objectives that must be completed.
|
|
|
|
|
|
|
|
|
|
#### 1.1.1. `assign` Command
|
|
|
|
|
|
|
|
|
|
The `/assign` command allows you to assign a specific Discord user to a task. A task may have multiple assignees.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.1.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `task`: An integer greater than 0, which is the unique identifier of the task you want to edit.
|
|
|
|
|
- `assignee`: The user to assign to (or unassign from) a ticket.
|
|
|
|
|
|
|
|
|
|
##### 1.1.1.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.1.3. Execution
|
|
|
|
|
|
|
|
|
|
Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
|
|
|
|
|
|
|
|
|
|
If a task does not exist, you will be notified.
|
|
|
|
|
|
|
|
|
|
If a task does exist, the Application will determine whether the `assignee` has been added to the task previously or not. If the `assignee` is already on the task, they will be removed. If they are not on the task, they will be assigned. You will be shown a confirmation message indicating which action the Application performed.
|
|
|
|
|
|
|
|
|
|
#### 1.1.2. `complete` Command
|
|
|
|
|
|
|
|
|
|
The `/complete` command allows you to mark a task as completed. Once completed, a task can not be uncompleted. It can still be modified and deleted.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.2.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `task`: An integer greater than 0, which is the unique identifier of the task you want to edit.
|
|
|
|
|
|
|
|
|
|
##### 1.1.2.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.2.3. Execution
|
|
|
|
|
|
|
|
|
|
Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
|
|
|
|
|
|
|
|
|
|
If a task does not exist, you will be notified.
|
|
|
|
|
|
|
|
|
|
If a task does exist, the Application will mark the task as completed and inform you of the success.
|
|
|
|
|
|
|
|
|
|
#### 1.1.3. `create` Command
|
|
|
|
|
|
|
|
|
|
The `/create` command allows you to create a new task.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.2.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.2.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.2.3. Execution
|
|
|
|
|
|
|
|
|
|
Once the command has been called, the Application will construct and show a Discord-powered modal form. There are three fields you must complete.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `TITLE`: The title of the task. This should be a short summary.
|
|
|
|
|
- `DESCRIPTION`: The description of the task. This may be longer, and supports multiple lines.
|
|
|
|
|
- `DUE DATE`: The date the task is due. This must be a format that can be parsed, such as `September 1, 2000`.
|
|
|
|
|
|
|
|
|
|
:::caution
|
|
|
|
|
If the Application cannot parse your `DUE DATE` value, it will fall back to the current date. You can edit this with the `/update` command.
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
When you submit the modal form, the Application will insert a new task into the database and assign it an incremental ID. It will provide this ID to you as confirmation.
|
|
|
|
|
|
|
|
|
|
#### 1.1.4. `delete` Command
|
|
|
|
|
|
|
|
|
|
The `/delete` command allows you to "delete" a task from the database. The task record will remain present, as the incremental ID logic requires records to persist. All information will be scrubbed from the task and replaced with default values.
|
|
|
|
|
|
|
|
|
|
:::danger
|
|
|
|
|
Deleting a task is a very destructive action. You will not be able to undo it. Our support team will not be able to undo it. The data will be purged from our records.
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.4.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `task`: The numerical identifier of the task you wish to delete.
|
|
|
|
|
|
|
|
|
|
##### 1.1.4.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.4.3. Execution
|
|
|
|
|
|
|
|
|
|
Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
|
|
|
|
|
|
|
|
|
|
If a task does not exist, you will be notified.
|
|
|
|
|
|
|
|
|
|
If a task does exist, the Application will mark the task as `deleted`, and set the following default values:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"assignees": [],
|
|
|
|
|
"deleted": true,
|
|
|
|
|
"description": "This task has been deleted.",
|
|
|
|
|
"dueAt": Date,
|
|
|
|
|
"priority": "deleted",
|
|
|
|
|
"tags": [],
|
|
|
|
|
"title": "Deleted Task",
|
|
|
|
|
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
You will receive confirmation when the deletion is complete.
|
|
|
|
|
|
|
|
|
|
#### 1.1.5. `list` Command
|
|
|
|
|
|
|
|
|
|
The `list` command allows you to view your tasks, optionally applying filters to narrow the results.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.5.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.5.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `priority`: Only show tasks which are at this priority level. If omitted, will show all priorities.
|
|
|
|
|
- `tag`: Only show tasks whose tags include this tag. If omitted, will not restrict query by any tags.
|
|
|
|
|
- `assignee`: Only show tasks whose assignees include this user. If omitted, will not restrict query by any assignees.
|
|
|
|
|
- `completed`: Show either complete or incomplete tasks. If omitted, will show incomplete tasks.
|
|
|
|
|
|
|
|
|
|
##### 1.1.5.3. Execution
|
|
|
|
|
|
|
|
|
|
The Application will construct your selected filters into a database query and use that to fetch the tasks.
|
|
|
|
|
|
|
|
|
|
If your query returns no tasks, the Application will notify you to adjust your filters. Otherwise, you will receive a list of task titles and IDs.
|
|
|
|
|
|
|
|
|
|
#### 1.1.6. `priority` Command
|
|
|
|
|
|
|
|
|
|
The priority command allows you to modify the priority level of a task. A task may have one of the following priorities: `Low`, `Medium`, `High`, `Critial`, and `None`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.6.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.6.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.6.3. Execution
|
|
|
|
|
|
|
|
|
|
Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
|
|
|
|
|
|
|
|
|
|
If a task does not exist, you will be notified.
|
|
|
|
|
|
|
|
|
|
If a task does exist, the Application will update the `priority` field and send you a confirmation.
|
|
|
|
|
|
|
|
|
|
#### 1.1.7. `tag` Command
|
|
|
|
|
|
|
|
|
|
The `/tag` command allows you to assign a specific tag to a task. A task may have multiple tags.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.7.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `task`: An integer greater than 0, which is the unique identifier of the task you want to edit.
|
|
|
|
|
- `tag`: The case-sensitive tag to apply.
|
|
|
|
|
|
|
|
|
|
##### 1.1.7.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.7.3. Execution
|
|
|
|
|
|
|
|
|
|
Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
|
|
|
|
|
|
|
|
|
|
If a task does not exist, you will be notified.
|
|
|
|
|
|
|
|
|
|
If a task does exist, the Application will determine whether the `tag` has been added to the task previously or not. If the `tag` is already on the task, it will be removed. If it is not on the task, it will be added. You will be shown a confirmation message indicating which action the Application performed.
|
|
|
|
|
|
|
|
|
|
#### 1.1.8. `update` Command
|
|
|
|
|
|
|
|
|
|
The `/update` command allows you to update an existing task.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.8.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.8.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.8.3. Execution
|
|
|
|
|
|
|
|
|
|
Once the command has been called, the Application will construct and show a Discord-powered modal form. There is one field you MUST complete, and three fields you MAY complete.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `TASK NUMBER`: The numerical identifier of the task you wish to update.
|
|
|
|
|
- `TITLE`: The title of the task. This should be a short summary.
|
|
|
|
|
- `DESCRIPTION`: The description of the task. This may be longer, and supports multiple lines.
|
|
|
|
|
- `DUE DATE`: The date the task is due. This must be a format that can be parsed, such as `September 1, 2000`.
|
|
|
|
|
|
|
|
|
|
If you do not want to update a field, leave it blank and the Application will not modify it.
|
|
|
|
|
|
|
|
|
|
:::caution
|
|
|
|
|
If the Application cannot parse your `DUE DATE` value, it will fall back to the current date.
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
When you submit the modal form, the Application will construct an update query from your fields. It will then try to update the task in the database, using the ID you provide. If it fails to find a record with that ID, it will notify you. Otherwise, it will send a confirmation message.
|
|
|
|
|
|
|
|
|
|
#### 1.1.9. `view` Command
|
|
|
|
|
|
|
|
|
|
The view command allows you to query a task by its ID and see all the information on that task.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
##### 1.1.9.1. Required Arguments
|
|
|
|
|
|
|
|
|
|
- `id`: The numerical ID of the task you wish to view.
|
|
|
|
|
|
|
|
|
|
##### 1.1.9.2. Optional Arguments
|
|
|
|
|
|
|
|
|
|
- `null`
|
|
|
|
|
|
|
|
|
|
##### 1.1.9.3. Execution
|
|
|
|
|
|
|
|
|
|
When you run the command, the bot will fetch the task matching your specified ID from the database. If no task is found, the bot will notify you.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Otherwise, the bot will display an embed containing all of the information about that task.
|
|
|
|
|
|
|
|
|
|
### 1.2. User Access Permissions
|
|
|
|
|
|
|
|
|
|
:::danger
|
|
|
|
|
The Application does not perform any permission validation against users calling commands. All commands are available to all users.
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
If you need to restrict access to specific commands based on a user's permission levels, you can do so through Discord's native UI.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This functionality will allow you to hide commands from users with or without specific roles, or grant scoped access to individual commands and channels. For more instructions on how to leverage this tool, please review [Discord's support article for command permissions](https://support.discord.com/hc/en-us/articles/4644915651095-Command-Permissions).
|
|
|
|
|
|
|
|
|
|
### 1.3. Application Access Permissions
|
|
|
|
|
|
|
|
|
|
The Application should not require any specific Discord permissions to function in your community.
|
|
|
|
|
|
|
|
|
|
### 1.4. Errors
|
|
|
|
|
|
|
|
|
|
We strive to deliver reliable and quality applications, but we are not perfect. If the Application generates an error, it will provide you with a Snowflake ID and a link to [our support server](https://chat.nhcarrigan.com).
|
|
|
|
|
|
|
|
|
|
When you join the server and share the ID with us, we will be able to look up the specific log and determine the cause of the error.
|
|
|
|
|
|
|
|
|
|
Note that not all errors are caused by the Application. Errors can occur for many reasons, including misconfigured permissions on the user side, external platform outages, and more. Our support team will be happy to assist you with any errors that you encounter, but we kindly ask that you demonstrate patience toward our team (many of whom are volunteers).
|
|
|
|
|
|
|
|
|
|
## 2. Technical Documentation
|
|
|
|
|
|
|
|
|
|
:::note
|
|
|
|
|
This section is coming soon!
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
This section is for those interested in running their own instance of the Application.
|
|
|
|
|
|
|
|
|
|
## 3. Legal Documentation
|
|
|
|
|
|
|
|
|
|
:::note
|
|
|
|
|
This section is coming soon!
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
This section is for expansions to our legal policies specific to the Application.
|
Naomi the Technomancer