AN INTRODUCTION TO TASKLIST TEMPLATES

    Frequently, we run into the situation where we have a set of tasks we need to use over and over again. Testing & verification steps for example. Or deployment procedures, and so forth. To solve this issue, we've added the ability for JIRA Users to create reusable Templates.

    Regular JIRA users can only create templates within the current project, while JIRA administrators can create global templates, available to all JIRA projects.

    Tasklist Templates come in two flavors.
    1) Task Templates
    These are templates consisting of tasks only.
    2) Content Templates
    These are templates consisting of any content you want. Text, macros, JIRA markup, tasks, ..etc

    CREATING TEMPLATES

    Templates can be created by any JIRA user. Simply navigate to the Project Tasks section of the project you wish to add the template to, and click on the gear icon.

    Which will lead you to the Manage Templates screen, where you can see all the existing global templates, as well as templates for the current project.

    To add a new template, simply click the "New Template" button, which will bring up the template creation screen.

    The template creation screen provides a lot of inline help to guide users along. But read on for a more thorough explanation of the various fields.

    Type:
    The "Type" designates the type of template you're creating (or editing). Task Templates consist of only tasks, while Content Templates can consist of any content, not just tasks.

    NOTE:

    Once a template has been created, the type can't be changed.

    Name:
    The name of a template serves 2 purposes. The first is to provide users with a way to identify a template, so they know which template they are using. The second purpose is for the Tasklist add-on to identify which template to insert when using a {tasklist} macro. As such, the template name must be unique within the JIRA instance. (for more details, see the Inserting a Template section).

    Description:
    The description is purely for informational purposes, and can be used to provide your users with additional details about a template.

    Project:
    The project designates whether a template is available globally to ALL JIRA projects, or whether a template is only available to a single, specific project.
    You can always edit a template and change the project the template belongs to.

    NOTE:

    A template can only belong to either all projects, or a single project. If you change which project a template belongs to, existing tasks within Issues are unaffected, but users from the old project obviously won't have access to the template anymore, and won't be able to create new tasks with it.

    A note about global templates

    To create global templates, available to all JIRA projects, you will need JIRA administrator privileges.

    TASK TEMPLATES

    Task templates consist of an arbitrary amount of tasks. Each task can contain any text you wish, from JIRA markup like bold text, underlines, and header, to bulleted lists, or other macros like panels and noformat.

    Just like tasks created within an Issue, tasks within templates can mention other Issues, as well as JIRA users. Thus, you can easily add tasks to a template that are automatically associated with a specific user.

    Of course, sometimes you need to associate a task with a specific user, but you won't know who that user is in advance when you create a template. For example, when you want to create a task for the reporter of a JIRA issue. For this purpose, we've added the ability to have variables within your tasks.
    This allows you to construct user mentions within a task dynamically. Some of the available variables are:

    Variable Explanation
    $assignee.name$ Inserts the username of the current assignee of the JIRA issue the task is being inserted in. Like 'ademoss' for example.
    $assignee.displayName$ Inserts the full name of the current assignee of the JIRA issue the task is being inserted in. Like 'Anthony De Moss' for example.
    $reporter.name$ Inserts the username of the reporter of the JIRA issue the task is being inserted in. Like 'ademoss' for example.
    $reporter.displayName$ Inserts the username of the current assignee of the JIRA issue the task is being inserted in. Like 'Anthony De Moss' for example.


    You can use the assignee.name and reporter.name to construct dynamic user mentions. A sample of this would be:

         [~$reporter.name$], needs to review this issue when done


    When the template is inserted into a JIRA issue, and the task is created, the Simple Tasklists addon would look at the reporter, and automatically insert the username of the reporter in place of the variable.

    CONTENT TEMPLATES

    Unlike Task Templates, Content templates consist of a block of text & markup. It's almost like writing a JIRA issue, or Comment, and saving it as a template.

    Content Templates can use any content you wish, from JIRA markup, to macros, as well as content variables. These types of templates are ideal when you need more than just tasks. Perhaps you want to provide some instructions to go along with your tasks, or you want to group multiple tasks into a panel, with a title, or you want to provide additional details about a task.

    In order to add tasks to a Content template, simply use the {task} macro the same way you would in a JIRA comment, or other fields. (See the Creating Tasks section for more details). You can preview the template content inline, to see what would be inserted.

    When the template is inserted, all the content you're written is automatically inserted, and macros and markup you've added will get evaluated and rendered properly.

    Just like Task Templates above, Content Templates can make use of variables, and thus easily mention assignee and reporter by name, which will get evaluated dynamically when the template is inserted.

    TIP

    Content templates can be used for more than just decorating your Task with additional information. You could use them to create pre-defined comments for QA staff, or pre-made answers for your Service Desk agents. The possibilities are endless.

    INSERTING A TEMPLATE INTO A JIRA ISSUE

    Inserting a template can be done in one of two ways. Either directly from the Tasks section, by opening up the template selection dialog, or by using the {tasklist} macro.

    To use the template selection dialog, follow these steps:

    Notice that selecting a template shows you the template content before inserting. This allows you make any necessary changes before continuing. Any variables will automatically be resolved at this time, so you can see what the outcome would be.
    Once you're happy, you can decide whether you want to copy the template content, and then paste it into whatever field you want, or whether you want to directly insert the template content as a comment into the current issue.

    TIP

    Task templates can be inserted as a comment, as well as directly into the sidebar (without generating a comment), while Content templates can only be inserted as a comment.

    Alternatively, we also provide a {tasklist} macro that works similar to the {task} macro.
    Put the name of the template inside the tasklist macro like this:

      {tasklist}testing steps{tasklist}

    This will automatically resolve the template, and insert the template whever the macro was placed.

    If you are on JIRA 7.3 or beyond, the Rich Text Editor automatically resolves the {tasklist} macro, and renders it as a content block. While visually editing, the macro will look like this:

    RTE template inserted

    CAPTION: sample caption goes here ||

    Once you save the field, the macro resolves, and the template is inserted. If you then edit the field, you will see regular tasks.

    CREATING A TEMPLATE FROM EXISTING TASKS

    Templates can be created from scratch, as described above, or you can also create a template from existing tasks within an issue. Simply click on the "Templates" button within the tasks section of an issue, and select "new Template from the tasks below".

    EDITING & DELETING TEMPLATES

    Templates can be edited or deleted from the Manage Templates Screen.

    Deleting a template or editing a template does not impact any of the existing tasks that have already been created from this template. Instead, it only impacts the template going forward. Thus, you don't have to worry about the impact that changes could have on existing content.

    Within a Task template, you can rename, edit, remove, or reorganize individual tasks, as well as add new ones. The moment you save, the template will reflect your changes, and the next time the template is inserted somewhere, the latest changes will be used.

    The same is true for Content Templates. Simply change the markup, and once you're happy with your changes, save the template, and you're good to go.

    IMPORTANT

    Permissions for who can edit or delete a template are VERY basic. As such, any user with access to a project level template can edit or delete that template.
    Global templates on the other hand can only be edited or deleted by a JIRA administrator.

    ADVANCED FUNCTIONALITY

    Want to automatically insert a template or tasks when an issue changes in a specific way? For example add verification steps when a bug is created? Or add testing steps when an issue enters the "Ready for Testing" status? Then take a look at our JIRA Automation Integration for a step-by-step guide on how to set this up.