Structure.Pages is an extension for Structure plugin that lets you create, manage and organise Confluence pages alongside JIRA issues right inside Structure.
Once you connect your JIRA and Confluence with Application Links and configure Structure.Pages you'll be able work with pages from your Confluence in a similar way you work with issues:
- Find pages that exist in your Confluence using text search or CQL and add them to your structure
- View and edit pages right from the Structure interface in the details panel
- Create new pages right inside the structure
- Organise pages into hierarchy in your structure manually or automatically based on your existing Confluence hierarchy
- Automatically pull in Confluence pages linked to issues in your structure
Structure.Pages provides integration between JIRA and Confluence so its installation requires a bit more work than installation of a plugin that only works with one system. But fear not - follow the steps described below and you'll have it running in no time. And if something goes wrong, please don't hesitate to contact us at email@example.com.
Here's what you'll need to do:
- Make sure you have a compatible Structure version
- Configure Application Links between your JIRA and Confluence
- Install the special Confluence helper add-on and configure Confluence
- Install the JIRA add-on and configure the integration
1. Installing Structure
If you don't have Structure add-on installed, please do it first. Structure provides a way to organize issues and other items into hierarchical lists. It's our base product that Structure.Pages extends, so you need to have it to use Pages.
If you have Structure installed, please check that you have the version that is required by the Structure.Pages add-on you're installing. The latest Structure is typically compatible with the latest Structure.Pages.
2. Setting up Application Links
To make your JIRA and Confluence work together and exchange data you need to set up Application Links. You can find all the details on how they work and how to set them up in Atlassian documentation.
Atlassian recommends using OAuth protocol because of the greater security. Structure.Pages supports OAuth but also other available protocols.
3. Installing Pages Add-On for Confluence and Configuring Confluence
To allow Structure communicate with Confluence you need to install a small add-on for Confluence. This add-on does not require any additional configuration and once installed it will take care of the integration with Structure on the Confluence side. There is also one additional option you need to enable in Confluence. So here is what you need to do:
- Enable Remote API (XML-RPC & SOAP) in Confluence. Use menu Administration | Further Configuration. Structure.Pages needs XML-RPC to access methods not available through the REST API.
Structure.Pages Helper does not interfere with how the users work in Confluence.
4. Installing and Configuring JIRA Add-On
JIRA add-on for Structure.Pages requires a bit more work:
Install Structure.Pages add-on from the Atlassian Marketplace or from Download page.
Obtain a license either from Atlassian Marketplace or from ALM Works. 30-day evaluation licenses are available.
If you have a license from ALM Works, use Administration | Structure | Structure.Pages License menu to install it.
If you got a license from ALM Works, the Add-On Manager may show Structure.Pages as Unlicensed and will suggest to get a free trial license. You can ignore this, since you have a license from ALM Works.
- Once the add-on is installed go to Administration | Structure page and select Confluence Integration in the menu on the left.
- You'll see the list of Confluence instances you can connect to. These are the instances for which you have configured Application Links.
- Click Configure Integration next to the Confluence you want to work with.
Select the System Authentication method. The drop-down shows all authentication types you have configured in the Application Links.
It's recommended to choose the one that would allow Structure.Pages see the most of the Confluence. All users who will work with Confluence via Structure.Pages will see a sub-set of pages that System Authentication permits to see, so if System Authentication permissions are more restrictive than the user permissions, the user won't be able to see some pages that should actually be visible.
OAuth method is preferred here and it's recommended to use a user account with administrative privileges for this type of authentication.
- Select the User Authentication method. These settings are used when a specific user is working with the Confluence through Structure: looking at the search results, creating or editing a page, changing links between issues and pages. Structure.Pages offers authentication methods in order of preference, so the default one is usually the best.
- Click Verify & Save Settings to apply the selected options. If you haven't enabled Remote API in Confluence when you were installing the helper add-on, you'll get a message with instructions how to to do that. Once it's enabled click Verify & Save Settings again to save the settings.
- Once you are done with the configuration you can start working with Confluence in Structure.
Find Existing Pages and Add Them to Your Structure
The simplest way to get started is to add some of the existing pages to your structure:
- Open the structure, which you want to add pages to.
- Open the second panel by clicking the panels toggle button.
- In the second panel you will see ether another Structure or JQL or Text search. Click the structure name or the JQL/Text label next to the search field and select Confluence Pages from the menu.
- You will see the search field, which you can use to search for pages in your Confluence. The search works just like the search field in Confluence itself and you can use the exact same syntax.
- As you type, the results will be shown in the panel.
- Once you have found the pages you need, select them in the search results and add them to the structure using drag-and-drop.
View and Edit Pages
Once the page is in a structure, you can see the page contents and edit it.
To do that simply click this page name in your structure and it will be shown in the panel on the right. You can work with it as if it was a usual Confluence page opened in a browser. You can click Edit to start editing the page contents or use any other available controls.
If you are not logged into the Confluence in the same browser session, you will be prompted to log in. Specify your Confluence Username and Password and click Log in.
Next to the panels toggle button there is a down arrow that opens the menu, where you can select the layout and the action that happens when you click an issue or a page in a structure. If you have Do Nothing option selected, the second panel will not be opened as you click the items in your structure.
Create New Pages
You can create new pages in your Confluence right from the Structure page:
- Select an item in your structure, under which the page should be added.
- Press Enter to create a page on the same level, or Shift+Enter to create it on the level below. You can also use the Add button in the top left corner.
As you press it, the New Item panel is shown. The panel allows to create issues, pages and folders. Switch to the Page tab.
If you've been using the full New Issue dialog to create issues, this dialog will be shown as you press Enter. Click the Switch to panel link to switch to the New Item panel.
Specify the page name, select the Confluence Space where the page should be created and select the template for the page (currently only templates and "Meeting notes" and "Product requirements" blueprints are supported).
Page creation using templates and blueprints is supported for Confluence version 5.9.1 and higher, on older versions only Blank page is available.
- Click Done to create the page.
You can configure some automation rules for pages in your structure in a similar way you do for issues.
You can pull in all child pages of the pages previously added to your structure. To do that you need to switch on the Automation editing mode, select the top-most item that appears at the top of the Structure and then add the Child Pages Extender from the Automation menu.
As you move a child page from one parent page to another in your structure, this page in Confluence will also be moved from one parent page to another. If you want to disable such updates, switch on Automation editing, double-click the Child Pages Extender and select the option for disabling changes via Structure.
Links between pages and issues
If you have links between pages and issues, you can visualise them in Structure too. There are two options available Linked Pages Extender and Issues Under Pages Extender.
Linked Pages Extender
To pull in pages linked to issues in your structure, add the Linked Pages Extender.
Moving pages between issues in Structure will update the links. If this undesirable, disable editing via Structure in the Linked Pages Extender settings.
Issues under Pages Extender
To pull in issues linked to pages in your structure, add the Issues Under Pages Extender.
Moving issues between pages in Structure will update the links. If this undesirable, disable editing via Structure in the Issues Under Pages Extender settings.
You can add both Linked Pages Extender and Issues Under Pages Extender to the same structure to get a complete view of links between pages and issues.