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:
- Configure Application Links between your JIRA and Confluence
- Install the special Confluence helper add-on
- Install the JIRA add-on and configure the integration
1. 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 provided by that protocol and Structure.Pages supports this and other available protocols.
2. 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:
Install the add-on from the jar file using the add-on upload functionality. The file you need is called structure-confluence-helper.jar. If you haven't received the link to download it, please contact us at firstname.lastname@example.org and we'll send you the link.
After the Structure.Pages release the add-on will be available on Atlassian Marketplace as a free add-on and should be installed from there.
- 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.
3. Installing and Configuring JIRA Add-On
JIRA add-on for Structure.Pages requires a bit more work:
Install Pages add-on for JIRA the same way you installed the add-on for confluence. The file you need is called structure-pages.jar. In the future it will be available as a paid add-on on the Atlassian Marketplace.
The beta comes with a temporary license, which will work until June 1, 2016. To use Pages after this date you will need to upgrade to the Marketplace version.
Since the add-on is not published yet, the Add-On Manager will show it as Unlicensed and the Free Trial button will not work. Please ignore this. As mentioned above, the plugin will work until June 1.
- 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 admin user for this 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 and select the Confluence Space where the page should be created.
- 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.
Pages Linked to Issues
If you have links between pages and issues, you can visualise them in Structure too. To pull in pages linked to issues in your structure, add the Linked Pages Extender to your structure. Currently you cannot automatically pull in issues linked to pages in a structure, but this will be added in the future versions.
Moving pages between issues in Structure will update the links. If this undesirable, disable editing via Structure in the Linked Pages Extender settings.