User Guide
- László Czomba
- Ferenc Szabó
JIRA issues and tasks
as you type…
on the fly in Confluence
Create multiple JIRA issues and tasks by simple tables
in any project you want without restrictions.
Table of Contents |
|---|
Why IssueCreate?
Our main objective with IssueCreate macro is to facilitate your tasks creation in business situations e.g. meeting or brainstorming sessions, action planning workshops, etc. in Confluence.
Primarily, based on our experience, IT people can easily use Jira but the Jira user interface is not comfortable enough for those on the business side.
Additionally, the built-in Jira macro does not provide the possibility to fill all types of fields, only summary and description.
Therefore, we have come up with a solution to respond to this challange – the macro enables you to create as many Jira tasks as you need from Confluence with simple tables that have been equipped with useful functions.
How to get started?
The following animation shows how easy it is to get started with IssueCreate.
Insert the macro to the page.
Choose a project or accept the default.
(If a Jira project is specified in the current space, that will be selected automatically as default.)Select issue type(s) you need or accept the default.
(The default issue type is Task, but it can be modified in IssueCreate Configuration.
The macro will take care of the rest and select the related required fields.)Optionally, you can reorder the fields by dragging.
After pushing the Insert button, your IssueCreate table is ready to use.
1. Add the macro to your page and accept default parameters or modify them |
|---|
 |
The next animation demonstrates how to create issues with IssueCreate macro.
Start filling in the table with issues.
Use the issue types that you have selected while inserting the macro.
Use the built-in Confluence usermention and datepicker features to give the Assignee and Due date (as well as any other user and date type field).
Use parent type hierarchy or epic links if you want.
Save the page and the issues will be created in your Jira.
(It is possible to create issues while you edit the page as well by clicking on the frame of the macro and pushing the Create issue(s) button.)
2. Create tasks or issues |
|---|
|
Tooltips
Wherever possible, the macro gives autocomplete values to the available options even if that is a multi-choice field type.
If you need a hint about suitable values for a field, you can move the cursor to the column name.
The tooltip gives information about the usage and some suggestions (see the related part in the Parameters section regarding the number items).
Usage
IssueCreate can be inserted to any page like any other macro in Confluence.
Use Insert > Other Macros menu button or start typing after a curly bracket ( {issuec ), as it is described in details in Confluence documentation.
You can customize the macro with the desired issue types and fields, etc. (see Parameters).
By accepting the default values, you can start using the macro immediately.
After IssueCreate has been inserted into a page you can fill in the table with tasks and issues that you have previously parameterized.
Extra fields can be added or removed at any time later on.
Understand the different columns (fields) and their behavior
Most of the Jira fields are supported. You can find the complete list here Supported fields.
Below in the table the typical fields and their functions are explained.
Column | Description |
|---|---|
Row number | The first column in the table always displays the row number. |
Issue | It is a designated column for the JIRA macro references of the created tasks. |
Issue type | The issue type column is inserted automatically as required when more than one issue types from the parameter list have been selected. |
Assignee and other user fields | Users can be selected by mentioning (@<name selection>). |
Description (and other rich text types) | If the text has been formatted in Confluence, IssueCreate will keep the formatting and the attached picture(s). |
Due date and other date fields | Use the built-in datepicker (// ), to specify a due date. |
Parent, epic | Two different links can be created with the macro. These are the parent and epic links.
|
Select fields | The macro supports autocompletion where there are predefined values. For such fields a hint will be inserted into the first row with the first five possible values in alphabethical order. The header of the actual column displays tooltip the same way. |
Labels | Handling labels differs from other select fields. The possible values are refreshed automatically during typing, so the list of labels is always up-to-date. Moreover, non-existing labels can also be added. |
Project | The project column is different from the others. If you need a new macro for a different project, you can select the desired project from the dropdown and a macro will be inserted automatically with the same parameters. If you select a project that has a macro on the page, the cursor will jump there and a new row will be added. |
Reporter | The reporter of the task is the current user by default. The reporter can be changed if the current user has the necessary permission. |
Epic name | If there is no epic name column or it is not filled, the macro will automatically use the summary for this purpose. It works the same way for summary while creating epic type tasks. |
Edit the table
The ways of editing the table with the toolbar are limited. You have the option to insert/delete rows or colour cells, however, you are not able to insert/delete columns, merge cells etc. Modifications can be made by editing the macro.
Insert a new row
You can insert a new row with the toolbar as well as with ALT+up/down key combinations. The new row will have the same parameters and issue type as the one where the insertion has been performed. The macro will automatically adjust the row numbers and references. You cannot perform the insertion of rows from the header.
Delete a row
You can delete rows with the toolbar. In case there is a reference to the given row, it will not be deleted until the reference is removed. Otherwise the row will be deleted and the macro will automatically adjust the row numbers and references. The header as well as the last row cannot be deleted.
Create issues
The aim of the macro is to create Jira issues. The processing of the table is based on the references between the rows, the current order of the rows is not relevant. The processing will skip the rows in which the issue creation has been previously successful and the issue column contains any Jira macro. After an issue has been created, a Jira macro related to the new task will be displayed in the issue column. If the issue creation fails, the macro will show an error message in the cell.
Save the page
If the 'Create on save' option is selected in the settings, the macro will automatically create the tasks when the page is saved.
Create issues while editing the page
You have the possibility to create issues while editing the page by clicking on ‘Create Issue(s)’.
Parameters
The behavior of IssueCreate macro is determined by parameters introduced in the table below.
Parameter | Description |
|---|---|
JIRA connection | This setting is not always visible. It becomes necessary if more than one Jira applications are connected to Confluence. If only one link exists, that will be used and the parameter will be hidden. |
Project | The list of projects available for the current user. You can select a project in which the tasks you defined in the table will be created. By default the project linked to the space will be selected. After inserting the macro, the project cannot be changed. |
Issue type | It contains the list of issue types available in the project. Depending on what you want to create, you can select the issue types here. You can select more, even all of them. While creating the list of different types, the macro tries to select the default type, or if it is not on the list, the first element will be chosen. If no issue type is selected during the setting, the macro will act as if the first item were chosen. |
Field selection | This parameter helps with field selection. You can choose from two different values: recommended or all. After setting this parameter, the field selection can still be changed. |
Field | The selected fields will be displayed as columns in the table. The list includes fields that are available for at least one selected issue type. (For example, the parent field will not be listed until the sub-task type is selected.) |
Advanced parameters | |
Show issue summaries | This parameter controls the behavior of Jira macros created in the table. If this checkbox is selected, the inserted Jira macro will include the summary of the issue. |
Replace issue references with Macro | By selecting this option, the macro converts Jira task references to Jira macro. |
Create on save | If this parameter is selected, the macro will be processed when the page is saved. (see Usage → Create issues section) |
Autocomp. rows - suggestions (in header) | The number of displayed items in the header of the columns is specified by the given number in this parameter. |
Autocomp. rows - items (in cell) | Regarding the completion of autocomplete type cells, the number of displayed items on the list is specified by the given number in this parameter. |
Modify parameters
You have the option to modify the parameters of the macro after it has been inserted. But there are some restrictions: the Jira link and the project cannot be modified, additionally, issue types that are used in the table cannot be removed, either. Any modification will be applied by saving. Before you save the macro, you can revert the modifications. After saving, the data in the columns you deleted will be lost.
Preview of IssueCreate table in macro parameters window
The preview shows the current appearance of the table. There is no need to refresh the preview manually after each modification, it will be refreshed automatically.
There is a limitation: the user macro is not displayed in the preview.
Work with templates
The macro can be used in templates. Moreover, it is possible to insert a generalized macro to templates. This generalization can be activated by leaving the Jira link and the project parameters blank. If you create a page that is based on this type of template, the missing link and the project parameter values will be defined by the project linked to the space. All the available issue types will be selected. After a page is created, there is an option to change the macro parameters but the modification will not affect the macro of the template.