USING SIMPLE TASKLISTS

    CREATING TASKS

    Adding a task to an issue can be done in a few different ways.
    1) By adding it directly from the tasks section
    2) By adding it in an issue field with the JIRA Rich Text Editor
    3) By using the new {task} macro

    Adding a task directly from the tasks section

    The simplest way to add a Task to a JIRA issue is to type it directly into the text field in the tasks section of the Issue and hit enter.

    The textfield supports standard JIRA Wiki markup for mentioning users via @user notation, and linking to Issues via [ABC-1] bracket notation.

    When you hit enter, the task is added to the bottom of the list, and the text field retains focus, thus allowing you to quickly add multiple tasks in quick succession.

    Adding a task with the JIRA Rich Text Editor

    Simple Tasklists integrates with the JIRA Rich Text Editor. This means, tasks can be added through the convenient macros dropdown in the Rich Text Editor, and tasks render inline, so users can edit them visually.

    Does this work in all JIRA versions?

    Due to technical limitations, Rich Text Editor integration is only available from JIRA 7.3 onwards. The Rich Text Editor plugin that Atlassian provides for older JIRA versions (7.2.x and below) lacks the required API and integration points for any other plugins to ehance it.

    For older JIRA instances, or instances without the Rich Text Editor, you an use the {task} macro, detailed below.

    Adding a task with the {task} macro

    If you want a task to be placed somewhere alongside of other text, or in a specific field, you can use the new {task} macro to place tasks in any field using the JIRA Wiki renderer, such as the Issue Description, or Comments.
    The format of the task is: {task}your content here{task}



    Anything you put inside of the macro will show up as part of the tasks.
    This allows you to mention users, link to issues, include icons, or any other macro really.

    If you put the above items into your description, and save your Issue, the result will look like this:

    THE TASKS SECTION/SIDEBAR

    All tasks within a JIRA issue (whether in the description, a comment, or a custom field) are automatically collected, and shown in the Tasks Section on the right side of the Issue Details view.

    Tasks within the tasks section can be reordered via simple drag & drop.
    Simply click on the task body, and begin dragging the task. Drop it in the new location within the list, and the order is saved to the backend.

    MARKING TASKS AS DONE (OR NOT DONE)

    To mark a task as done, simply click the checkbox to the left of the text, and the task will toggle the checked state from unchecked to checked, and vice versa.

    There is no need to edit the issue or the task itself in any way. A simple click is all it takes.
    The result looks like this:

    The state of the checkbox is automatically saved to JIRA behind the scenes, and when you reload the Issue, the checkboxes will show exactly as you left them for anyone that views the Issue.

    What happens if there are multiples of the same task?

    All instances of the same task are automatically checked/unchecked. This means, if you've added a task to the issue description, it will show there as well as the tasks section, and you only have to check it in one spot, and it will automatically be checked everywhere.

    EDITING TASKS

    Tasks can be edited directly from the Tasks section, or inline whereever the {task} macro was placed.

    Editing a Task from the Tasks Section

    To edit a task, hover over it in the tasks section, which will highlight it, and show you the outline of the edit button. Click on the edit icon, and the task will change to a text field, allowing you to edit the content.

    Once done, click on the checkmark below the text field to save your changes.
    All instances of the task are automatically updated with the latest content.

    Editing a task via JIRA Rich Text Editor

    If the task is present in one of the issue fields (description, ..etc) or a comment, edit the field and the Rich Text Editor will render the task inline. Simply change the text, and save the field and the task is updated everywhere.

    Editing a task via the {task} macro

    Alternatively to the above, you can also edit a task by editing the issue description or comment, whichever contains the task you want to edit.
    Change the contents of the {task} macro, and save your changes. The task is updated automatically, and the checked state is preserved.

    This only works with tasks that were created with a {task} macro. If a task was added directly from the tasks section, then there would be no corresponding task macro to edit.

    NOTE:

    You will see that the Simple Tasklists plugin injected an "id" parameter into each task. This is so the plugin can keep track of additional data about each task behind the scenes.
    Be cautious if you're changing the id, as that means you might refer to another task somewhere else, and accidentally overwrite it.

    DELETING TASKS

    To delete a task, simply edit the field that contains the task, and remove the whole {task} macro. Once you save your changes, the task is automatically removed from the field, and from the Tasks Section.

    NOTE:

    It is possible to have multiple instance of the same Task on a JIRA Issue (if one was copied for example). If that is the case, you will need to remove all instances of it, before the task is deleted.

    If a task was created directly from the tasks section, without a macro, it can be deleted from the tasks section directly with these simple steps:

    COPYING TASKS

    Tasks can easily be copied, either within the same JIRA Issue, or to another JIRA Issue if you want to reuse them.

    Simply follow the steps for editing a task above, and copy the markup of the {task} macro (with id and everything), and paste it where you want the copy to be.

    If you copy a task within the same JIRA issue, it creates a reference to the existing task. Thus an issue could contain multiple instances of the same task. This can be useful if you need to quote a task, or refer to it in multiple places. If you mark a task as done, all instances of it are automatically marked as done.

    If you copy a task to another issue, the Simple Tasklists plugin will automatically strip out the old id of the task, and replace it with a new one witin the new Issue. Thus you can easily take previous tasks, and copy/paste them into a new Issue to reuse them.
    It is not possible however to refer to an existing task from another JIRA issue.

    MY TASKS

    Tasks created with Simple Tasklists support mentioning users within them. This is not only a visual benefit, but under the hood, the task actually tracks all the users that are mentioned within a task. The plugin exposes a "My Tasks" section for each JIRA user that automatically lists all the tasks the user is mentioned in.

    NOTE:

    This mechanism makes it possible to designate multiple JIRA users as responsible for a task, something currently not supported in standard JIRA Issues. Simply mention multiple users, and the task will show up within "My Tasks" for each user.

    The "My SimpleTasks" section can be found under the user's dropdown in the main JIRA header. You can see it by expanding the user icon:

    The My Tasks screen is split up by project, allowing users to easily see the tasks they are mentioned in on a per-project basis. The user can interact with tasks here by marking them as done, or easily visit the JIRA Issue where the task was created.

    The tasks can easily be filtered based on done, not done, or all of them, as well as by selecting a specific project from the Projects dropdown.

    PROJECT TASKS

    Similar to the "My Tasks" section that is specific to each user, Simple Tasklists does the same on a project level. The add-on automatically collects all the tasks from every issue into a convenient "Project Tasks" section.

    Tasks are grouped by assignee, and by JIRA issue within each assignee. Tasks not mentioning any users are automatically collected into an unassigned section named "Tasks not associated with any user".

    Tasks can be filtered based on their status and by assignee, or can be searched.

    SEARCHING FOR TASKS VIA JQL

    Simple Tasklists exposes multiple custom fields that allow searching for tasks and issues with tasks via JQL syntax.

    The available 3 fields to query against are:

    • allTasks - a representation of all the tasks within an issue
    • openTasks - any open tasks within an issue
    • closedTasks - any closed tasks within an issue

    These properties/fields are dynamically calculated, and as such always reflect the current state of tasks within each issue. Each field supports the IS, IS NOT, and contains (tilda ~) operators.

    Based on these fields and operators, it is possible to check for the presence (or lack thereof) of tasks, as well as content of tasks. For example:

    allTasks IS NOT EMPTY - this would search issues that have any tasks at all

    openTasks ~ “some text” - this would search the open tasks within issues for the specified text

    To find resolved JIRA issues that still have open tasks, you could do something like this:
    project = "ABC" AND resolution = Fixed AND openTasks IS NOT EMPTY

    To find issues JIRA issues where all tasks are resolved, but the issue is still open, you could do this:
    project = "ABC" AND resolution = Unresolved AND allTasks IS NOT EMPTY and closedTasks IS EMPTY

    TASK HISTORY / AUDIT TRAIL

    Each task keeps track of its own history / audit trail. This includes who performed an action against a task, when it happend, and what the action was, along with relevant details for each action. The task history tracks the following events:

    • task creation
    • task edit (content changes)
    • toggle a task (checked or unchecked)
    • reorder a task
    • delete a task
    Each JIRA issue exposes a new Task History tab, that shows the history of the tasks within the issue.

    The history can be viewed grouped by task, or as an activity stream, where each event is in chronological order. Edit events include the before and after text of the text, so it is possible to track what a task changed from, and to.

    NOTE:

    The task history events are not pushed the to JIRA Activity stream, and the task history is stored independently of the regular issue history (and thus shown in it's own tab).

    This decision was made to avoid making the JIRA activity stream even more chatty (and useless) than it already is, and to avoid polluting the issue history with tons of entries.

    The result is that history/audit trail is available if you need it, but out of sight if you don't need it.
    Additionally, if you remove the plugin, the task history events are removed with it.

    JIRA RICH TEXT EDITOR INTEGRATION

    Simple Tasklists integrates with the JIRA Rich Text Editor that ships with JIRA 7.3 and beyond. This integration makes it easy to add tasks visually while creating or editing an issue.

    Tasks can also be added via the {task} macro, or the regular /t shortcut. The macro is automatically converted from a macro to a fully rendered task that a user can edit visually.

    Additionally, you can easily convert existing content like text, bullet lists, or numbered lists to tasks. Simply highlight the content, and select the "Task" option from the editor dropdown.

    When converting regular text to tasks, the selected text is split based on line breaks. Thus, a long paragraph would convert to a single task with lots of text, and mulit-line text with line breaks would convert to multiple tasks

    For details on inserting a template via the rich text editor, see the Templates Documentation.