The interactive troubleshooting macro turns the static tree structure of Confluence pages into a dynamic and interactive macro that can be installed at the top level of any section of a space.
How it works
The macro works by looking at all child pages of the current page. It reads the first paragraph of the page as the question to display, and all of its child pages as potential answers to that question. This pattern continues down through until you reach a page that doesn’t have any children.
Anything beyond the first paragraph is treated as more context and helpful answers. This content is not displayed on the macro, but it will include a “See Page” link which will open that specific page. This means that readers can decide to read the information on that page, or continue on down the tree of questions.
How to use
Setup the main page
The best way to start is with the initial landing page. All other pages will fall under this original one. Start with a single paragraph with an initial question. Perhaps something like “Which of these best describes your problem?”.
Underneath that, add the troubleshooting macro onto the page. You can add the macro through the “insert” button on the toolbar and searching for “troubleshooting”. The macro takes no arguments.
Allowing access
The macro does not use, store or process any user information but it is required by the framework. Therefore each user will be presented with a message like this on first load:
To enabled to macro, click “Allow Access” and then “Accept” on the next page.
Adding answers
Now that you have allowed access but have not added any answers or next questions, the page will look something like the below screenshot.
To next step is to create child pages of this original page with some potential answers to the question. The title of the page is important here, because those page titles will be displayed as buttons for readers to select on the main page.
For example, this page structure results in the following options in the troubleshooting page:
Adding content to pages
Now we need to continue on with more questions so that we can better understand the reader’s problem. This is done in the same way as the original question. The first paragraph is the question to ask, with all subpages as potential answers to choose from. This can continue down for as long as you need to get to a specific problem.
Any time you add more than the first paragraph to the page a “See More” link is displayed in the macro. This allows the user to get more context, which might help them to answer the question.