luisgulo/focalboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Transitioning Mattermost Boards > Focalboards plugin docs (#4862)

Browse source 
* Transitioning Boards > Focalboards plugin docs

* Update docs/focalboard-plugin-end-user-guide.md

* Update docs/get-started-with-board-templates.md

* Update docs/get-started-with-board-templates.md

* Update docs/group-filter-sort-boards.md

* Update docs/group-filter-sort-boards.md

* Update docs/share-collaborate.md

* Update docs/import-export-backup-data.md

* Update docs/import-export-backup-data.md

* Fix MD table fomatting

* Added data collection content

* Added Focalboard import notes
This commit is contained in:
Carrie Warner (Mattermost) 2023-09-14 13:35:28 -04:00 committed by GitHub
parent a216e43fab
commit 277ea9facc
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
16 changed files with 805 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
docs/board-metrics.md Normal file
View file

@ -0,0 +1,55 @@
# Board metrics
When you view a board in table or board view, you can use calculations to answer basic metric questions without needing to create complex reports. Hover over the bottom of a column to display the **Calculate** feature, then select the arrow to open the menu options.
You can use calculations to quickly see:
- How many story points are planned for a release.
- How many tasks have been assigned or not assigned.
- How long has the oldest bug been sitting in the backlog.
- The count of cards where particular properties are empty (useful to make sure important info isn’t missing).
- The sum of estimated developer days for features (to make sure your team isn’t overloaded).
- The range of estimated dates (to make sure your milestones all line up).
The calculation options are:
* **Count**: Counts the total number of rows in table view or total number of cards in a column in Board view. Applies to any property type.
* **Count Empty**: Applies to any property type.
- Table View: Counts the total number of empty rows per column selected.
- Board View: Counts the total number of empty values per property specified within the same column.
* **Count Not Empty**: Applies to any property type.
- Table View: Counts the total number of rows with non-empty cells per column selected.
- Board View: Counts the total number of non-empty values per property specified within the same column.
* **Percent Empty**: Applies to any property type.
- Table View: Percentage of empty rows per column selected.
- Board View: Percentage of empty values per property specified within the same column.
* **Percent Not Empty**: Applies to any property type.
- Table View: Percentage of rows with non-empty cells per column selected.
- Board View: Percentage of non-empty values per property specified within the same column.
* **Count Value**: Applies to any property type.
- Table View: Counts the total number of values within the column (helpful for multi-select properties).
- Board View: Counts the total number of values per property specified within the same column.
* **Count Unique Values**: Applies to any property type.
- Table View: Counts the total number of rows with unique values within the column, omitting any duplicates from the count.
- Board View: Counts the total number of unique values per property specified within the same column, omitting any duplicates from the count.
* **Sum**: The sum of any specified number property within the same column.
* **Average**: The average of any specified number property within the same column.
* **Median**: The median of any specified number property within the same column.
* **Min**: The lowest number of any specified number property within the same column.
* **Max**: The highest number of any specified number property within the same column.
* **Range**: Displays the lowest and highest number. Requires a number property.
* **Earliest Date**: Displays the oldest date. Requires any custom date property or the included "Created time" or "Last updated time".
* **Latest Date**: Displays the most recent date. Requires any custom date property or the included "Created time" or "Last updated time".
* **Date Range**: The difference between the most recent date and oldest date within the same column. In Table View, it's labeled simply as "Range" for any date property/column. Requires any custom date property or the included "Created time" or "Last updated time".

17
docs/create-new-board.md Normal file
View file

@ -0,0 +1,17 @@
# Create a new board
If none of the standard templates suit your requirements, you can create a blank board. Select the plus icon at the top of the sidebar, then select **Create New Board** to open the template picker and select the **Create empty board** option.
## Manage board details
If you've created a board, you can edit that board any time. To name or rename a board, select the title area to edit it.
To display board description, hover above the board’s title and select **Show description** to activate the show/hide toggle. Once the description field is displayed, select **Add a description** right below the board title to add or edit the description.
Boards and cards are created with random icons by default. To change or remove icons, select the icon then choose the appropriate action.
All changes you make to boards and cards are saved immediately.
## Create a template from a board
To turn an existing board into a template, hover over the board title in the sidebar. Select the options menu, then select **New template from board**.

4
docs/dev-tips.md
View file

@ -1,6 +1,8 @@
# Developer Tips and Tricks
These tips and tricks apply to developing the standalone Personal Server of Focalboard. For most features, this is the easiest way to get started working against code that ships across editions. For working with Mattermost Boards, refer to the [Mattermost Boards developer's guide](mattermost-boards-dev-guide.md).
These tips and tricks apply to developing the standalone Personal Server of Focalboard. For most features, this is the easiest way to get started working against code that ships across editions.
For working with the Focalboard plugin, refer to the [Focalboard Plugin Developer's Guide](focalboard-dev-guide.md).
## Installation prerequisites

8
docs/mattermost-boards-dev-guide.md → docs/focalboard-dev-guide.md
View file

@ -1,6 +1,6 @@
# Mattermost Boards Developer's Guide
# Focalboard Plugin Developer's Guide
[Mattermost Boards](https://mattermost.com/boards/) is the Focalboard (aka Boards) plugin running in Mattermost. It is pre-packaed, and runs out of the box with Mattermost 6.0 and later.
**Important**: Effective September 15th, 2023, Mattermost Boards transitions to being fully community supported as the Focalboard Plugin. Mattermost will no longer be maintaining this plugin - this includes bug fixes and feature additions. Instead, the plugin is open-sourced and made available indefinitely for community contributions in GitHub.
To build your own version of it:
1. Build [mattermost-plugin](https://github.com/mattermost/focalboard/tree/main/mattermost-plugin) in the [Focalboard repo](https://github.com/mattermost/focalboard)
@ -8,7 +8,7 @@ To build your own version of it:
Here are the steps in more detail:
### Building the Boards plugin
### Building the Focalboard plugin
Fork the [Focalboard repo](https://github.com/mattermost/focalboard), clone it locally, and follow the steps in the readme to set up your dev environment.
@ -55,7 +55,7 @@ First, build and run Mattermost locally:
5. Add an ENV var `MM_SERVICESETTINGS_SITEURL` with the same site URL used in the config
6. Run `make run-server` in Mattermost
Now, to build and deploy the Boards plugin:
Now, to build and deploy the plugin:
1. Clone / fork [mattermost/focalboard](https://github.com/mattermost/focalboard)
2. Install the dependencies (see above)
3. Run:

23
docs/focalboard-plugin-end-user-guide.md Normal file
View file

@ -0,0 +1,23 @@
# Focalboard Plugin End User's Guide
The Focalboard plugin is a deliverable and task management solution to help teams achieve project milestones using a familiar kanban board structure.
This user guide is for anyone looking to use Focalboard to:
- Align work across the organization and drive milestone achievement such as project planning, execution, and task management.
- Keep everyone in your team and organization in the loop to stay on schedule with clearly defined tasks, owners, checklists, and deadlines.
- Increase transparency and keep all resources available including documents, images, and important hyperlinks.
- Track tasks for sprints and features in roadmap planning.
The following end user documentation is available:
- [Get started with board templates](get-started-with-board-templates.md)
- [Create a new board](create-new-board.md)
- [Link boards to Mattermost channels](link-boards-to-mattermost-channels.md)
- [Manage boards](manage-boards.md)
- [Work with cards](work-with-cards.md)
- [Work with board views](work-with-board-views.md)
- [Group, filter, and sort boards](group-filter-sort-boards.md)
- [Board metrics](board-metrics.md)
- [Share and collaborate](share-collaborate.md)
- [Import, export, and back up boards data](import-export-backup-data.md)
- [Manage plugin preferences](manage-plugin-preferences.md)

47
docs/get-started-with-board-templates.md Normal file
View file

@ -0,0 +1,47 @@
# Get started with board templates
## What's a board?
A board is a collection of cards to help you manage your projects, organize tasks, and collaborate with your team all in one place. A board contains cards, which typically track tasks or topics, and views, which define how to display the cards, or a subset of them.
Boards can be displayed and filtered in different views such as kanban, table, calendar, and gallery views to help you visualize work items in the format that makes most sense to you.
## Start from a board template
To create a new board, we strongly recommend starting from a standard board template.
Board templates provide you with a predefined structure so that you can get started quickly. Each template has a different function, but can be customized to suit your use case. When you create a new board from the template picker, select each template’s name to preview it and make sure it suits your requirements. Alternatively, you can create your own board templates.
Select the plus icon at the top of the sidebar, then select **Create New Board** to open the template picker and select a template or a blank board.
Standard board templates include:
- **Content Calendar**: Plan and organize your content creation and publication schedule.
- **Company Goals & OKRs**: Plan your company goals and objectives more efficiently.
- **Competitive Analysis**: Track and stay ahead of the competition.
- **Meeting Agenda**: Use this template for recurring meetings. Queue up items, organize discussions, and plan what to revisit later.
- **Personal Goals**: Categorize and plan your personal goals.
- **Personal Tasks**: Organize your life and track your personal tasks.
- **Project Tasks**: Stay on top of your project tasks, track progress, and set priorities.
- **Roadmap**: Plan your roadmap and manage your releases more efficiently.
- **Sprint Planner**: Plan your sprints and releases more efficiently.
- **Team Retrospective**: Identify what worked well and what can be improved for the future.
- **User Research Sessions**: Manage and keep track of all your user research sessions.
- **Welcome to Boards!**: Onboarding template with guided tour points to help you quickly ramp up on Focalboard.
### Edit board templates
To open the template editor for a specific template, go to the template picker then hover over the custom template and select the pencil icon. Any changes made on the template editor will be automatically saved and visible to team members who have access to the template. If you don't see the pencil icon when hovering over the template, then you don't have the appropriate permissions to edit the template.
**Notes**:
- From v7.2 of the Focalboard plugin, only admins and editors of a custom template can edit the template.
- Prior to v7.2 of the plugin, any member of the channel workspace can edit a custom template in the channel. To limit access to the template, create or export the template to a private channel.
- Custom templates are fully editable, but standard templates cannot be edited or deleted.
## Create a template
To create a new board template select the plus icon at the top of the sidebar to open the template picker, select **Create New Board** and then select **+ New template**.
## Turn a board into a template
To turn an existing board into a template, hover over the board title in the sidebar. Select the options menu, then select **New template from board**.

79
docs/group-filter-sort-boards.md Normal file
View file

@ -0,0 +1,79 @@
# Group, filter, and sort boards
Your boards can be grouped, filtered, and sorted into different views using a range of properties. This gives you a powerful way to track work from various perspectives. For example, easily find tasks assigned to you or a team member using the person or multi-person filters, and keep track of upcoming tasks with date filters.
## Group cards
You can group cards on your board if they utilize the **Select** or **Person** property.
Card grouping is only available in board and table views and you must have at least one **Select** or **Person** property on your board for grouping to work.
### Apply a group
To apply a group, select the **Group by** option at the top of the board, then select any available **Select** or **Person** property to group your cards by.
- In the boards view, cards are automatically grouped into columns by the values from the specified property.
- In the table view, grouped cards will appear in individual sections based on the values from the specified property. Select the arrow to the left of the group name to expand or collapse cards in the group.
### Hide and unhide groups
- To hide a group, select the options menu **(...)** to the right of any group name, then select **Hide**. Additionally, in table view only, you can hide empty groups by selecting the **Group by** option at the top of the board, then selecting **Hide empty groups**.
- To unhide a group, go to the hidden column section towards the right of a board view, select the group you want to unhide, then select **Show**. On table view, select the **Group by** option at the top of the board, then select **Show hidden groups**.
### Ungroup cards
To ungroup cards on table view, select the **Group by** option at the top of the board, then select **Ungroup** from the top of the menu. This will return your table to its default state. Cards can be ungrouped in table view only. Ungrouping is not possible on board view since groups are used to determine what to display.
## Filter cards
You can filter cards on your board if they utilize any of the following property types:
- Select
- Text
- Email
- Phone
- URL
- Date
- Person
- Multi-person
- Created time
- Created by
- Last updated time
- Last updated by
You must have at least one of the property types listed above on your board for filtering to work.
To use filters, you must have the above property types already added to your board. Go to **Filter > Add filter**, and select the property you wish to filter by. You can use the modifiers to get even more granular results.
### Add filters
To add a filter, select the **Filter** option at the top of the board, then select **+ Add filter**. To change the property to filter by, select the name of the first property, then select another property (if available) from the menu.
**Specify the filtering criteria**
- **Includes**: Display cards with any of the specified values.
- **Doesn’t include**: Display all cards without any of the specified values.
- **Is empty**: Display cards with no values assigned to a property.
- **Is not empty**: Display cards with any value assigned to a property.
To add another filtering layer, repeat the steps above with another property to refine your filtering results. Adding another layer will display cards that only match the criteria from the first layer and the second layer.
### Delete filters
To delete a filter, select the **Filter** option at the top of the board, then select **Delete** to the right of each filtering layer. Delete all filtering layers to completely remove filters from the board.
## Sort cards
Sort cards by the card name or by any property available on the card.
Sorting is only available in boards, table, and gallery views.
### Apply sorting
To apply a sort, select the **Sort** option at the top of the board, then select an option from the menu. The cards will be sorted in ascending order by default based on the selected option and the **Sort** menu will display an upward pointing arrow next to the selected option.
To change the sort order to descending order, select the same option again from the **Sort** menu. The cards will now be sorted in descending order and the menu will display a downward pointing arrow next to the selected option.
### Clear sorting
To clear a sort, select the **Sort** option at the top of the board, then select the **Manual** option from the top of the menu.

147
docs/import-export-backup-data.md Normal file
View file

@ -0,0 +1,147 @@
# Import, export, and back up data
## Import data into Focalboard
You can import data from other tools to use with Focalboard.
### Import from Asana
This node app converts an Asana JSON archive into a ``.boardarchive`` file. The script imports all cards from a single board, including their section (column) membership, names, and notes.
1. Log into your Asana account.
2. Select the drop-down menu next to the Asana board's name. Then select **Export/Print > JSON**. This will create an archive file.
3. Save the file locally, e.g. to ``asana.json``.
4. Open a terminal window on your local machine and clone the focalboard repository to a local directory, e.g. to ``focalboard``: ``git clone https://github.com/mattermost/focalboard focalboard``
5. Navigate to ``focalboard/webapp``.
6. Run ``npm install``.
7. Change directory to ``focalboard/import/asana``.
8. Run ``npm install``.
9. From within the same folder, run ``npx ts-node importAsana.ts -i <asana.json> -o archive.boardarchive``. This generates the following data:
```
My-MacbookPro:asana macbook$ npx ts-node importAsana.ts -i ~/Downloads/asana.json -o archive.boardarchive
Board: 1:1 Meeting Agenda Test
Card: [READ ME] Instructions for using this project
Card: [EXAMPLE TASK] Feedback on design team presentation
Card: [EXAMPLE TASK] Finalize monthly staffing plan
Card: [EXAMPLE TASK] Review Q2 launch video outline
Card: [EXAMPLE TASK] Mentor a peer
Found 5 card(s).
Exported to archive.boardarchive
```
10. In Focalboard, open the board you want to use for the export.
11. Select **Settings > Import archive** and select ``archive.boardarchive``.
12. Select **Upload**.
13. Return to your board and confirm that your Asana data is now displaying.
If you don't see your Asana data, an error should be displayed. You can also check log files for errors.
### Import from Notion
This node app converts a Notion CSV and markdown export into a ``.boardarchive`` file. The script imports all cards from a single board, including their properties and markdown content.
**Note**: The Notion export format does not preserve property types, so the script currently imports all card properties as a Select type. You can change the type after importing into Focalboard.
1. From a Notion Board, open the **...** menu at the top right corner of the board.
2. Select `Export` and pick `Markdown & CSV` as the export format.
3. Save the generated file locally, and unzip the folder.
4. Open a terminal window on your local machine and clone the focalboard repository to a local directory, e.g. to ``focalboard``: ``git clone https://github.com/mattermost/focalboard focalboard``
5. Navigate to ``focalboard/webapp``.
6. Run ``npm install``.
7. Change directory to ``focalboard/import/notion``.
8. Run ``npm install``.
9. From within the same folder, run ``npx ts-node importNotion.ts -i <path to the notion-export folder> -o archive.boardarchive``.
10. In Focalboard, open the board you want to use for the export.
11. Select **Settings > Import archive** and select ``archive.boardarchive``.
12. Select **Upload**.
13. Return to your board and confirm that your Notion data is now displaying.
### Import from Jira
This node app converts a Jira ``.XML`` export into a ``.boardarchive`` file. The script imports each item as a card into a single board. Users are imported as Select properties, with the name of the user.
**Notes**:
- Jira ``.XML`` export is limited to 1000 issues at a time.
- The following aren't currently imported: custom properties, comments, and embedded files.
1. Open Jira advanced search, and search for all the items to export.
2. Select **Export > Export XML**.
3. Save the generated file locally, e.g. to ``jira_export.xml``.
4. Open a terminal window on your local machine and clone the focalboard repository to a local directory, e.g. to ``focalboard``: ``git clone https://github.com/mattermost/focalboard focalboard``
5. Navigate to ``focalboard/webapp``.
6. Run ``npm install``.
7. Change directory to ``focalboard/import/jira`.
8. Run ``npm install``.
9. From within the same folder, run ``npx ts-node importJira.ts -i <path-to-jira.xml> -o archive.boardarchive``.
10. In Focalboard, open the board you want to use for the export.
11. Select **Settings > Import archive** and select ``archive.boardarchive``.
12. Select **Upload**.
13. Return to your board and confirm that your Jira data is now displaying.
### Import from Trello
This node app converts a Trello ``.json`` archive into a ``.boardarchive`` file. The script imports all cards from a single board, including their list (column) membership, names, and descriptions.
1. From the Trello Board Menu, select **...Show Menu**.
2. Select **More > Print and Export > Export to JSON**.
3. Save the generated file locally, e.g. to ``trello.json``.
4. Open a terminal window on your local machine and clone the focalboard repository to a local directory, e.g. to ``focalboard``: ``git clone https://github.com/mattermost/focalboard focalboard``
5. Navigate to ``focalboard/webapp``.
6. Run ``npm install``.
7. Change directory to ``focalboard/import/trello``.
8. Run ``npm install``.
9. From within the same folder, run ``npx ts-node importTrello.ts -i <path-to-trello.json> -o archive.boardarchive``.
10. In Focalboard, open the board you want to use for the export.
11. Select **Settings > Import archive** and select ``archive.boardarchive``.
12. Select **Upload**.
13. Return to your board and confirm that your Trello data is now displaying.
### Import from Todoist
This node app converts a Todoist ``.json`` archive into a ``.boardarchive`` file.
1. Visit the open source Todoist data export service at https://darekkay.com/todoist-export/.
2. From the **Options** menu, select **Export As > JSON (all data)**.
3. Uncheck the **Archived** option if checked.
4. Select **Authorize and Backup**. This will take you to your Todoist account. Follow the instructions on screen.
5. Note the name and location of the downloaded ``.json`` file.
6. Open a terminal window on your local machine and clone the focalboard repository to a local directory, e.g. to ``focalboard``: ``git clone https://github.com/mattermost/focalboard focalboard``
7. Navigate to ``focalboard/webapp``.
8. Run ``npm install``.
9. Change directory to ``focalboard/import/todoist``.
10. Run ``npm install``.
11. From within the same folder, run ``npx ts-node importTodoist.ts -i <path-to-todoist.json> -o archive.boardarchive``.
12. In Focalboard, open the board you want to use for the export.
13. Select **Settings > Import archive** and select ``archive.boardarchive``.
14. Select **Upload**.
15. Return to your board and confirm that your Todoist data is now displaying.
## Export from Focalboard
You can export your boards data as a CSV file.
1. Select the options menu to the left of the **New** button at the top of any board.
2. Select **Export to CSV**.
3. Import the CSV file to your tool of choice. The CSV file contains all the cards in that board and their associated properties.
**Notes**:
- If you only see a single entry in the CSV export when the board contains multiple cards, you may have a specific card in context when you exported the file because you were performing a card search. If you have searched for a card, and that card is in context, that’s the only card that will be exported into the CSV file. Clear your search and try exporting to CSV again.
- After importing CSV Focalboard data from one Mattermost instance into another (such as during a migration from Mattermost Cloud to self-hosted), card timestamps will be updated based on the import date, and cards won't correctly identify users whose user IDs differ across Mattermost instances.
## Back up your Focalboard data
If you’d like to back up a board, you can export it as an archive file. You can import that board to another Mattermost team within the same Mattermost instance. Exported and imported board archives include all card content such as properties, comments, descriptions, and image attachments.
1. Select the options menu Options icon to the left of the **New** button at the top of the board
2. Select **Export board archive**.
3. Download the archive file.
4. Navigate to the team or channel workspace where you’d like to add the exported board.
5. Select the Gear icon next to your profile picture, then choose **Import archive**. The board you exported will be added to this team or channel workspace.
**Notes**:
- If you're using a version of the Focalboard plugin older than v6.4, backing up a board results in a ``.focalboard`` file, rather than a ``.boardarchive`` file. When importing a board backup, select the **Select all files** option to select ``.focalboard`` files.
- After importing a Focalboard backup from one Mattermost instance into another (such as during a migration from Mattermost Cloud to self-hosted), card timestamps will be updated based on the import date, and cards won't correctly identify users whose user IDs differ across Mattermost instances.

28
docs/index.md
View file

@ -1,10 +1,30 @@
# Focalboard / Mattermost Boards Contributors Guide
# Focalboard Plugin Documentation
Welcome to the [Focalboard](https://www.focalboard.com) / [Mattermost Boards](https://mattermost.com/boards/?utm_source=focalboard) project!
Welcome to the Focalboard plugin project! We're very glad you want to check it out and perhaps contribute code to this project in GitHub.
We're very glad you want to check it out and perhaps contribute code our repository in GitHub.
## Install the plugin
Our goal is to make your experience as great as possible. Follow these simple steps to contribute:
Visit the [Mattermost Developer Documentation](https://developers.mattermost.com/integrate/plugins/using-and-managing-plugins/#custom-plugins) for details on how to install and enable the Focalboard plugin in your self-hosted Mattermost instance.
## Enable the plugin
Once you've installed the Focalboard plugin, you can enable the plugin in the Mattermost System Console by going to **Plugins > Plugin Management**, and selecting the **Enable** option for the Focalboard plugin.
## Learn what Focalboard plugin data is being collected
See the [plugin data being collected documentation](plugin-data-being-collected.md) for details.
## Use the plugin
See the [Focalboard plugin end user guide](focalboard-plugin-end-user-guide.md) for details on getting started with and using the plugin.
## Manage plugin preferences
See the [manage plugin preferences documentation](manage-plugin-preferences.md) for details.
## Contribute to the Focalboard plugin project
Follow these simple steps to contribute:
1. [Fork the Focalboard repo](https://github.com/mattermost/focalboard), clone it locally, and follow the steps in the README to build. Read the [developer tips & tricks](dev-tips.md) to get started.

24
docs/link-boards-to-mattermost-channels.md Normal file
View file

@ -0,0 +1,24 @@
# Link boards to Mattermost channels
## Link a board to a channel
Boards can be linked to channels and accessed from the channel Apps Bar.
1. Select the **Focalboard** icon from the Apps Bar in a channel to open a right-hand sidebar (RHS).
2. Search for and link boards to the channel.
3. Select **Add** button to open the link boards dialog and search for a board to link.
Once a board is linked to a channel, it's listed in the right-hand pane. Linking a board to a channel automatically grants all channel members access to the board, with the exception of guest accounts. Select a linked board to navigate directly to the board.
**Notes**:
- A channel can be linked to multiple boards, but each individual board can only be linked to one channel at a time.
- Linking the same board to another channel will automatically replaces the link to the previous channel with the new channel.
- Channel members can only search and link boards within the team where they are a board admin.
- If you're using a Focalboard plugin older than v7.2, you won't be able to link a board to a channel. We recommend upgrading to the latest version of the plugin to take full advantage of all plugin features and functionality.
- After upgrading to version v7.2 or later of the Focalboard plugin, your boards automatically appear in the right-hand side pane for easy access.
## Unlink a board from a channel
If you're a board admin, and want to unlink a board from a channel you're in, open linked board, select the options menu, and select **Unlink**.
Alternatively, you can open the **Share** dialog on the board, open the **Role** drop-down menu next to the channel's name and select **Unlink**.

39
docs/manage-boards.md Normal file
View file

@ -0,0 +1,39 @@
# Manage boards
## Access your boards
Open the Boards tab via the product menu in the top left corner of Mattermost to view all the boards for your team. You can select the **Focalboard** icon in the Apps Bar to open the right-hand panel, and display boards linked to the channel or message that you're in.
If you don't see the Apps Bar and your boards layout looks different to what's described, you may be using an older version of Mattermost and/or the Focalboard plugin.
## Find a board
From the top of the boards left hand sidebar, select the **Find Boards** field (CMD+K/CTRL+K) to open the board switcher, and start typing the name of the board you’re looking for.
## Manage sidebar categories
From Focalboard plugin v7.2, you can organize your boards in the left-hand sidebar using custom categories. By default, all boards will appear under the **Boards** category. To manage your categories, open the Options menu next to the category to create, delete, or rename a category. With the exception to the default **Boards** category, all other categories can be renamed or deleted.
After creating categories, you can move your boards to those categories by opening the Options menu next to the board and selecting **Move To…** to select the category where you want the board to be moved.
If you delete a category with boards in it, then those boards will return to the default **Boards** category.
Categories are organized per-user, so you can arrange your boards under categories that make sense to you without impacting boards or categories for other users. If a board is moved to a custom category, then the board will appear under that category for you only. Other users who are members of the board will continue to see the board in their own categories.
### Organize using drag and drop
You can organize both sidebar categories and boards to change the order of both to suit your preference. You can:
- Set the position of a board within a category.
- Drag a board out of one category and drop it into another category.
To do this, select and hold the cursor over the category or board name. Then move the category or board around as needed. Boards moved into a category are sorted to the top of the category by default unless you specifically position the board before releasing the cursor.
### Manage boards in the sidebar
In addition to moving boards to other categories, from the Options menu next to each board name, you can perform the following actions:
- **Delete board**: If you're an admin of the board, you will see an option to delete the board. Deleting the board permanently removes the board from the sidebar of all board members.
- **Duplicate board**: Creates a copy of the board and all the cards on the board. The duplicated board will appear under the same category as the original board. Board members and comments from the original board aren't migrated to the new board.
- **New template from board**: Creates a custom board template of the board and all the cards on the board.
- **Hide board**: Hides the board from your sidebar only. The board will still remain visible on the sidebar for other board members. You can add the board back to your sidebar using the search box (CMD+K/CTRL+K).

5
docs/manage-plugin-preferences.md Normal file
View file

@ -0,0 +1,5 @@
# Manage plugin preferences
## Disable emojis on cards
You can enable or disable random emoji icons for your board and cards by selecting the Gear icon next to your profile picture, then toggling **Random icons on or off**.

46
docs/plugin-data-being-collected.md Normal file
View file

@ -0,0 +1,46 @@
# Plugin data being collected
Boards metadata is collected and sent to Mattermost every 24 hours. Visit the [Focalboard telemetry file](https://github.com/mattermost/focalboard/blob/main/webapp/src/telemetry/telemetryClient.ts) for information about the action and event data collected.
Other telemetry information that Mattermost collects includes:
## Server telemetry
### Boards Plugin Information
- Boards Version and Build Number
- Boards Edition
- Operating System for Boards server
- The server diagnostic ID
### Configuration Information
- ServerRoot is default server root (``true``/``false``)
- Port is default port (``true``/``false``)
- UseSSL (``true``/``false``)
- Database Type
- Single User (``true``/``false``)
### User Count Information
- Registered User Count
- Daily Active User Count
- Weekly Active User Count
- Monthly Active User Count
### Block Count Information
- Block Counts By Type
### Workspace Information
- Workspace Count
## Web app event activity
### Load Board View
- ``UserID``: Unique identifier of the server.
- ``UserActualID``: Unique identifier of the user who initiated the action.
- ``Event``: Type of the event. Only the ``view`` event is currently monitored.
- ``View Type`` (``board``, ``table``, ``gallery``).

93
docs/share-collaborate.md Normal file
View file

@ -0,0 +1,93 @@
# Share and collaborate
You can share boards with your Mattermost teams and within your Mattermost channel conversations.
## Share a board internally
To share a board with team members internally, select **Share** in the top-right corner of the board, then select **Copy link** from the **Share** tab below. Paste the copied link in a channel or direct message to share the board with other team members. Only team members who have permissions to the board will be able to open the board from the shared link.
## Share cards in channel conversations
Cards can be linked and shared with team members directly with Mattermost Channels. When you share a link to a card within a channel, the card details are automatically displayed in a preview. This preview highlights what the card is about at a glance without having to navigate to it.
To share a card, you'll need to copy the card link first:
- Open a card and select the options menu **(...)** at the top right of the card, then select **Copy link**.
- Alternatively, you can open the board view and hover your mouse over any card to access the options menu **(...)** for the card and select **Copy link** from there.
After you've copied the link, paste it into any channel or direct message to share the card. A preview of the card will display within the channel with a link back to the card on the board.
## Control access to boards
Boards belong to teams, and any member of a team can be granted access to a board.
**Note**: If you're using a Focalboard plugin version prior to v7.2, boards are tied to channel workspaces and board membership is determined by channel membership. In this case, roles and permissions information on this page won't be applicable to you.
### Board roles
The level of access to a board is determined by a user’s assigned board role. Individual board membership always gets precedence, followed by highest (most permissive) group role.
- **Admin**: Can modify the board, its contents, and its permissions. By default, board creators are also admins of the board.
- **Editor**: Can modify the board and its contents.
- **Commenter**: Can add comments to cards.
- **Viewer**: Can view the board and its contents but can't comment or edit the board.
| **Board permissions** | **Admin** | **Editor** | **Commenter** | **Viewer** |
|------------------------------------|-----------|------------|---------------|------------|
| Modify permissions | X | | | |
| Delete a board | X | | | |
| Rename a board | X | X | | |
| Add, edit, and delete views | X | X | | |
| Add, edit, and delete cards | X | X | | |
| Comment and delete my own comments | X | X | X | |
| Delete any comment | X | | | |
| View a board | X | X | X | X |
## System admin access
System admins can access any board across the server provided they have the board's URL without having to request permission or be manually added. When a system admin joins a board, their default role is admin. System admins will have an **Admin** label assigned to their name on the participants list.
## Team admin access
Team admins can access any board within their team provided they have the board's URL without having to request permission or be manually added. When a system admin joins a board, their default role is admin. Team admins will have a **Team admin** label assigned to their name on the participants list.
## Manage team access
Board admins can manage team access to their board by selecting **Share** in the top-right corner of the board. On the dropdown next to **Everyone at… Team** option, select a minimum board role for everyone on the team. You can also easily assign the new roles to the entire team and/or to individual team members.
Minimum default board roles reduce permission ambiguity and prevent security loopholes. The minimum default role means that board admins can't assign individual board members a role lower than the team role. If the team role is set to **Editor** then the board admin will only be able to assign the **Editor** or **Admin** role to individual team members. Lower roles will not be available for selection unless the admin changes the minimum board role.
Depending on the role selected, everyone on the team will have access to the board with a minimum of the permissions from the role selected. Users can get elevated permissions based on their individual board membership. The default team access for a newly created board is **None**, which means nobody on the team has access to the board.
## Manage individual board membership
Only board admins can manage user permissions on a board, including adding, changing, and removing members.
To add individual users from the team as explicit members of the board, open the **Share** dialog on the board, search for individual team members, then assign a role to set their permissions for the board. The role for individual board members overrides any role specified for team access.
- To change a board member’s role, open the **Share** dialog, select the role dropdown next to the user’s name, then select another role from the list.
- To remove a member from a board, open the **Share** dialog, select the role dropdown next to the user’s name, then select **Remove member**.
Board admins can also add individual members using the autocomplete list from @mentions and the person properties. To add an individual from the autocomplete list, type their username in an @mention or in the **Person** or **Multi-person** properties, then assign a role to the user from the confirmation dialog, and select **Add to board**.
On boards with team access, board members with **Editor** or **Commenter** roles can also add individuals to the board from the autocomplete list. Board members added in this manner will be assigned the default minimum board role.
## Channel role groups
Board admins can add a channel to a board to grant all its members Editor access. To do this, select **Share** in the top-right corner of the board, search for the channel name, and add it to the board as a user. The default role is Editor. Doing so also [links the board back to the channel](link-boards-to-mattermost-channels) where the board will appear on the channel RHS.
To unlink the channel from the board, open the **Share** dialog, select the role dropdown next to the channel’s name, then select **Unlink**.
Remember, a board can only be linked to one channel at a time. Linking another channel to the same board will automatically remove the link from the previous channel.
## Guest accounts
From version v7.4 of the Focalboard plugin, [Mattermost guest accounts](https://docs.mattermost.com/onboard/guest-accounts.html#guest-accounts) are supported. If you're not able to access this functionality, you may be on an earlier version of the Focalboard plugin.
Guests can:
- Access boards where they're added as an explicit member of the board, but can't manage team access or add channels to boards.
- Access existing boards, but can't create new boards. Guests also don't have access to the template picker and can't duplicate an existing board.
- Search for boards where they're currently an explicit member.
- Be assigned the Viewer, Commenter, or Editor roles, but not the Admin role.
- Only @mention current members on the board.

35
docs/work-with-board-views.md Normal file
View file

@ -0,0 +1,35 @@
# Work with board views
Views display your cards in a board, table, calendar, or gallery layout, optionally filtered and grouped by a property (e.g., priority, status, etc).
To add a new view to a board:
1. From the board header, select the menu next to the current view name.
2. Scroll down and select **+ Add view**.
3. select the new visualization you’d like to use.
The following board views are available.
## Board view
This is a kanban view where cards are grouped into columns. Column groups only work with the **Select** or **Person** properties and display all cards that share the same value from the specified property. The column names are editable, and any changes to the column names are also applied to the value from the property. Cards can be dragged between columns, which will automatically update the property’s assigned value on the card.
## Table view
Displays cards in a table format with rows and columns. Use this view to get an overview of all your project tasks. Easily view and compare the state of all properties across all cards without needing to open individual cards. Each column corresponds to a card property. You can edit cells directly or you can select **Open** to open the card view for that row.
## Gallery view
Displays cards in a gallery format, so you can manage and organize cards with image attachments. Gallery view displays a preview of the first image attached on the card. For cards with no image attachments, a preview of the first description block will be displayed instead.
## Calendar view
To use this view, cards need to have the **Date** property added.
If cards don’t have a custom **Date** property, they’ll be sorted and displayed by the card creation date (default). These cards can’t be moved around the board until a custom **Date** property is added.
If your cards do have a **Date** property and you’re not able to move them around, you may be displaying them by **Created Time** or **Last Updated Time**.
- To add a new card, select the **+** option in the top-left corner of the relevant date.
- To create a date range event, select a start date and then drag to the end date to create a card for that date range event.
- To add a date range to an existing card, hover over the side of the card to display the arrow and drag to the left or right to create a date range.

164
docs/work-with-cards.md Normal file
View file

@ -0,0 +1,164 @@
# Work with cards
## What's a card?
Cards are used on a board to track individual work items. Cards are customizable and can have a number of properties added to them, which are then used as a way to tag, sort, and filter the cards.
A card consists of:
- **A set of properties**: Properties are common to all cards in a board. Board views can group cards by “Select” type properties into different columns.
- **A list of comments**: Comments are useful for noting important changes or milestones.
- **A set of content**: The content of a card can consist of Markdown text, checkboxes, and images. Use this to record detailed specs or design decisions for an item for example.
When working with cards, you can manage properties, add descriptions, attach images, assign them to team members, mention team members, add comments, and so on.
Standard board templates provide some default card properties that can be customized or removed. In the Roadmap template, there's a **Type** property, whereas in the Project Tasks template, there's an **Estimated Hours** property. These properties are not exclusive to any template and can be easily re-created in any of the templates provided.
## Add card descriptions
Card descriptions can include text with Markdown formatting, checkboxes, and visual elements such as images or GIFs, and can be separated into blocks of content. To add a description, open a card, select **Add a description** below the **Comments** section, and start typing in your content.
To add a new content block in the description section, hover over the section and select **Add content**. Then choose from any of the following options:
- **Text**: Adds a new text block that can be formatted with Markdown.
- **Image**: Select and embed an image file into the content block. The following image formats are currently supported: GIF, JPEG, and PNG.
- **Divider**: Adds a divider content block below the previous block.
- **Checkbox**: Adds a checkbox content block. Press Enter/Return after typing in content for your checkbox to add another checkbox within the same block. Please note, Markdown formatting isn't supported within the **Checkbox** content block.
To manage the description content blocks on a card, hover over any existing block and select the options menu |options-icon| to move the block up or down, insert a new block above, or delete the current block. Alternatively, you can hover over any existing block, then select and hold the grid button to drag and drop it to a new position within the description section.
## Attach files to cards
From Focalboard plugin version v7.7, you can attach files to your cards, which other board members can download. There are no limitations to the file types that you can upload.
To upload a file to a card, select **Attach** in the top-right corner of the card. Then select the file you'd like to upload. When your file has been uploaded, you can find it in the **Attachments** section of the card. Select the **+** sign to add additional files to your card.
To delete a file attachment, hover over it and select the 3-dot menu, then select **Delete**. To download the file, select the download icon.
## Add card badges
Card badges are a quick way to view card details without opening up a card. To add them, select **Properties > Comments and Description**. Icons related to the card description, comments, and checkboxes will be displayed on cards with the respective content. Open the card to view the details.
- The description icon indicates that a card has a text description.
- The comment icon displays a number indicating how many comments have been added to a card. When a new comment is added, that number is updated.
- The checkbox icon displays the number of items checked off relative to the total number of checkboxes within the card. When an item is checked off, the icon is automatically updated.
## Comment on a card
Comments allow you to provide feedback and ask questions relevant to the specific work item on the card.
To add a comment, select a card to open the card view, then click on **Add a comment…** to type in your comment, and press **Send** to save the comment to the card. All team members who are `following the card </boards/work-with-cards.html#receive-updates>`_ will receive a notification with a preview of your comment in Mattermost Channels.
From Focalboard plugin v7.4, only board members with the *Commenter* role or higher can comment on a card. Board members assigned the *Viewer* role can view, but not comment on, a card.
## Mention people on cards
You can include a team member on a card by `mentioning them on a card </channels/mention-people.html>`__ the same way you would in Channels. Mentions are supported in the `Comments </boards/work-with-cards.html#comment-on-a-card>`_ and `Description </boards/work-with-cards.html#card-descriptions>`_ sections within a card. The team member you mention will receive a direct message notification from the boards bot with a link to the card you mentioned them on. To mention multiple team members, separate each name with a comma.
## Follow card updates
When you create a card, you automatically follow it. You can @mention someone on a card to add them as a follower. This can be a card you've created or someone else's card. Lastly, you can also follow cards manually using the **Follow** option on the top-right corner of a card. To unfollow a card, select **Following**.
When updates are made to a card you're following, you'll receive a direct message from the boards bot with a summary of the change (e.g. Bob changed status from **In progress** to **Done**) and a link to the card for more detailed information.
You won't get a notification of your own changes made to a card, even if you're following that card.
## Search for cards
You can search through all the cards on a board to find what you’re looking for. Open the board you want to search, then select the **Search cards** field in the top-right of the board.
## Manage card properties
Cards can contain different data fields depending on the purpose of the board. Using card properties, you can customize these data fields to fit your needs and track the information most important to you. For example, in a **Roadmap** board, cards include a **Type** field where you can add categories such as **Bug**, **Epic**, etc. In a **Project Task** board, cards include the **Estimated Hours** field instead.
Properties are displayed in the order they were created and can't be re-ordered.
## Create card properties
To create a new property field open a card and select **Add a property**. Then select the type of property from the drop-down menu. The property type specifies the type of data you plan to capture within that field. When you create new card properties, they're added to all new and all existing cards on the current board.
Properties are automatically added to the board filter list at the top of the page, so ensure you customize all property names to make it easy to filter your board by specific properties later.
## Work with property types
The Focalboard plugin supports a wide range of fully customizable property types:
- **Text** can be used to add short notes to a card. An advantage of the text property over card descriptions is that it can be `shown on the board <https://docs.mattermost.com/boards/work-with-cards.html#toggle-properties-shown-on-a-board>`_ without needing to open the card.
- **Numbers** are useful to capture metrics such as task sizing or effort estimates. Use in conjunction with calculations to get the most out of the number property type.
- **Email** and **Phone** can be used to record contact information.
- **URL** can be used to provide a link to a pull request or relevant website. Clicking on the box of a URL property will automatically open the link in a new tab on your browser. Hover over the box to surface options to copy or edit the URL.
- **Select** and **Multi-select** allows you to create a predefined list of options that can be color-coded and displayed as badges on the card to indicate things like status and priority.
- **Dates** are useful to set and track due dates or milestones. Use the date property to make a card appear on the `Calendar view <https://docs.mattermost.com/boards/work-with-views.html#calendar-view>`_. Set a single date or toggle on the **End date** to set a date range.
- **Person** and **Multi-person** provides a quick way to capture user assignments. Note that this is not available in Personal Desktop.
- **Checkbox** is a toggle property that can be used for assigning simple binary options on a card such as True/False or Yes/No.
- **Created time/Created by/Last updated time/Last updated by** are predefined system properties to help you audit changes on a card. The names of these properties are customizable, but the values are not.
### Rename a property type
The default name for a new property is the name of the property type (e.g. **Date**, **URL**).
To rename a property field, open up a card and select the property name to open an editable field. Enter the new name in the field provided. The change is saved immediately and applied across all cards on the current board.
### Change a property type
To change a property type, select the property then open the **Type** menu and choose a new property type. You’ll be asked to confirm the change from every card on the current board. Changing the type for an existing property will affect values across all cards on the board and may result in data loss.
### Delete a property
To delete properties you no longer need, select the property, then choose **Delete**. You’ll be asked to confirm that you want to remove that property from every card on the current board.
### Define a "Select" or "Multi-select" property
The options on a **Select** and **Multi-select** property type appear as color-coded tags on a card. Options in a **Select** or **Multi-Select** property list are sorted in the order they were created and can't be re-ordered or renamed.
To add and configure the options on these types:
1. Select a card to open the card view.
2. Add a new property, give it a name, and set its type to **Select** (or **Multi-Select**).
3. Select the field box for the property, and start typing the name of a new option. Press Enter to accept. Repeat this step to add additional options.
- To assign a color to or delete an option, select the value and select the options menu **(...)** next to each option name.
- To select an option on the property, select the box and choose one of the values from the menu.
- To remove an option on the property, select the box and chooose the `X` next to the option name you want to remove.
Alternatively, you can also add new options directly from a board:
1. Open a board view.
2. Group by a **Select** property.
3. Scroll to the right of the board and select **+ Add a group**.
This will add a new column, which corresponds to a new value option for the Select property.
### Control what properties are shown on a board
Once you have card properties defined, you have full control over which properties are shown on the board as a preview without having to open the card. Select **Properties** at the top of the board, then enable all properties you want to see at a glance, and hide all properties you don’t want to see.
## Create card templates
Card templates can help reduce repetitive manual input for similar types of work items. Each board can have any number of card templates. To create a new card template:
1. Open the board where you want to add the card template.
2. Select the drop-down arrow next to **New**, then select **New template**.
3. Add a title to the card template.
4. Then assign values to any properties and add a description you wish to have pre-populated when a card is created from the template.
5. Close the card using the **X** in the top left corner.
6. Select the drop-down arrow next to **New**, then select the template you just created.
Alternatively, you can turn any existing card into a template:
1. Open the card you want to use as a template.
2. Select the options menu |options-icon| in the top-right corner of the card.
3. Select **New template from card**.
4. Edit the card as needed, including a helpful name.
5. Close the card using the **X** in the top left corner.
6. Select the drop-down arrow next to **New**, then select the template you just created.
To set a default card template for all new cards created on the board:
1. Select the drop-down arrow next to **New**.
2. Open the options menu |options-icon| next to the card template of your choosing.
3. Select **Set as default**.
**Notes**:
- The card template is applicable only to the board in which it’s created, and isn’t available in other boards within your team workspace.
- Comments on a template don't get populated on to new cards.
- Additionally, properties can't be hidden from a card template at this time. All cards on a board share the same properties, so adding or deleting a property on a template will also apply to all cards on a board.