You can embed a Structure gadget into a Confluence page to view or edit the structure in Confluence.
Before you can use a Structure gadget on a Confluence page, your Confluence administrator must add Structure gadget to the Confluence configuration. If you try to insert a macro and don't see Structure in the available list, most likely the gadget is not configured.
Adding a Structure Gadget to a Confluence Page
When editing a Confluence page, click Insert/Edit Macro, and select Structure. The macro configuration dialog appears.
Select your gadget configuration:
- Select a Structure. Click arrow down in the Structure selector to view recently used and favorite structures, or start typing the structure name and let the drop-down suggest matching structures.
- Select a View. Click arrow down to choose from views associated with the selected structure, start typing and let Structure suggest matching views, or create a new view. The selected view determines which columns the gadget displays. (You will be able to adjust the view later.)
- Optionally, configure a Filter. The displayed structure will be filtered in the same way as in the Structure Board – see Filter. You can choose between a text filter, JQL, S-JQL, or a saved JQL filter – see Search.
- Optionally, define the Title for this gadget. By default, it is the name of the selected structure.
- Decide how large the gadget is allowed to be and specify the number of Visible Rows. If there are fewer visible rows, the gadget shrinks; if more, a vertical scroll bar appears. Pick any number between 2 and 50.
- Decide whether Confluence users can make changes to the structure or issues (subject to the user's permissions) by selecting or deselecting the Allow Changes checkbox.
- Optionally, if you would like the gadget to have a different View and Visible Rows settings when maximized, select the Alternative settings when maximized checkbox. This allows you to see more information for the same structure when the gadget window is maximized.
- Click Save.
Once you've configured the gadget, specify the appearance of the gadget on the left side of the screen:
- Specify the gadget's width
- Select whether or not it should have a border
Click Insert and you're done!
If you see the Login & approve button, you will need to log in to Jira before you can add the gadget.
A Structure plugin not available message indicates that you do not have any visible structure. This is most likely because you are not logged in.
Using the Gadget
When viewing a structure in a gadget, some of Structure's features will be limited or unavailable:
- Search and the Secondary panel is unavailable
- The toolbar is unavailable
- Only some fields can be edited from within the Structure gadget – see Editing from Gadget
- The displayed Structure gadget is not suitable for printing. Support for a printable Structure gadget is coming later. For now, please use Printable Page to print a structure separately.
- In the current version the Structure Gadget in Confluence is supported, but some issue may occur. This will be fixed in the future versions.
However, many features are still available, including
- Most keyboard shortcuts are functional
- You can rearrange issues with drag-and-drop, if editing is enabled
- You can move, create, edit, and delete issues using the keyboard, if editing is enabled
- You can add, remove and rearrange columns
Customizing Gadget View
Once you have created your gadget, you can customize by adding, removing or rearranging columns – see Customizing Columns.
Once you've made changes to the gadget's view, a new indicator will appear at the bottom of the gadget, along with option revert back to the view's original setting.
In order to save the view, you need to enter Edit mode for the Confluence page and then edit the Structure macro. From there, you have a couple of options for saving your changes.
Click the Save link to apply all the changes you have made to the existing view. The view will be updated everywhere it is in use, in the gadget, on Structure Board, etc. It will also impact all other users with access to that view.
There is no Save As option on the Confluence gadget; however, it can be accomplished using the following method:
- Adjust the gadget's view by adding, removing or rearranging columns – see Customizing Columns for details.
- From the Edit 'Structure' Macro screen, open the gadget configuration by clicking the edit icon.
- Click the New View button, located beside the view selector. An additional form appears – enter the new view name and click Create View.
- If this gadget is going to be visible to other users, make sure they have access to the view you've created by clicking Let everyone use this view.
If the user viewing the gadget does not have Use permission on the configured view, the gadget will show a default view with only Issue Key and Summary as columns.
Open on Structure Board
Working from the Structure Board provides the most unrestricted Structure experience. To get to the Structure Board from a gadget, click the Open link.
The structure will open on Structure Board with the same filters and transformations that were applied in the original gadget. For examples, if the gadget only shows items from a specific project, sorted by Assignee, that's exactly what you'll see on the Structure Board. To review or remove these transformations, click the Transformations button in the panel toolbar.