How to Use Page Properties Macros in Atlassian Confluence

The Page Properties and Page Properties Report macros are perhaps the most useful and underutilized macros in Atlassian Confluence. This blog explains the benefits of using the two macros and walks through how to set them up.

Adopting Confluence

Confluence spaces are set up – Check. You structured your page trees – Check. Only key stakeholders can view your sensitive information through space permissions and page restrictions – Check. Information that was once in silos is now available to the right people – Check. Gone are the days when employees searched for key information in email and Google drive. The office is buzzing with excitement about how easy it is to collaborate and how great it is to have a single place for all company information. Users are updating content and creating new content daily, if not hourly. Confluence adoption is an organization-wide success. But then it happens…

“How can I see all of my projects’ information in one place, at a glance?” “When I search for ‘Project ABC’ status I get over 20 results, and I can’t find the right page!” “Which project deadline is the earliest?”

The joy of collaboration has vanished and in its place appears frustration, annoyance, and defeat.

Frequently Overlooked Macro Solution

Introducing the page properties and page properties report macros. These two macros are perhaps the most useful and underutilized macros in Confluence. They look and sound complex, but in fact – they’re not. These are the macros that you see in a lot of blueprints such as product requirement and decisions blueprints. They allow you to take any content and display it on another page. An experience Confluence user might be thinking: “Wait, how is this any different from the Excerpt and Excerpt Include macros?” The Excerpt macro does in fact take part of a page and allows you to display it on another page with the Excerpt Include, which is similar to what the page properties and page properties report macro do. The latter two macros, however, can take things a bit further and provide an organized index for your users to find information quickly.

How to Use These Macros

To use these macros you must first create a page with a table on it. In the left column of your table insert the headings you would like to appear on the index page. Try to use only the most important information that summarizes the contents of the page. The table on your input page should look something like this:

You must also include a label on the page to match with the label in the output macro (page properties report macro).
Within the macro parameters you can choose an ID for the page properties report to recognize the data. Although this is an option, we highly recommend utilizing it. You can also use this macro to hide information from users viewing the page by ticking the checkbox next to “Hidden”. The Page Properties Report macro can then be placed on another page with the correct label to fetch the information from the Page Properties macro on your input page (the page we created above).
The resulting table should look something like this:
As you can see from the screenshot above, the title of the page is automatically populated into the index, so you don’t need to include the title of the page in your table on the page properties page.

Macros within the Macro

It’s possible to further extend this macro by inserting macros within this macro. One powerful example of this is the Status macro which allows you to have a better looking status than the one shown above.

You can also tag users, as in any other page in Confluence, using the @ symbol and adding their name in order to draw their attention to the page you have created. It is possible to insert almost any macro you would like inside the Page Properties macro to display on your index page. However, as a word of caution, don’t insert macros that render lots of information. Otherwise, your Page Properties Report macro will begin to clutter like the image below:
In the above example we inserted the Page Tree macro which gives an index of the pages in a space. As you can see, the result is less than ideal.

Customization with Blueprints and Templates

When you begin to create a page, by clicking … (on server) or “+” (on cloud), you will notice a list of valuable out-of-the-box templates that Atlassian provides. Confluence has a lot of blueprints and templates that are useful. These include templates like Meeting Notes, How-to Article, Project Plan, and Product Requirements to name just a few. Read more about the difference between blueprints and templates here. Many of these templates already contain the Page Properties macro and create an index page with the Page Properties Report macro. However, every team is different. If you find your users creating the same pages over and over again, it is a good idea to create a template or blueprint for them. If you can’t find what you are looking for in the out-of-the-box list, you can create your own. Once you begin to create a page and realize the template you need is not available, there is an option to “add or customize blueprints for a selected space”. If you click this option you will be taken to the Content Tools section of the space administration in whichever space you are in. Here, you will see a list of all the out-of-the-box Confluence Blueprints that are offered and display any template that a potential add-on have given you.

On this page you can edit or promote these blueprints as you see fit. Another option on this page is to “Create a New Template”. This is slightly different than creating a blueprint. Blueprints require more development effort but also more possibilities for customizations. You can read more about creating your own blueprint here. Alternatively, you might find it easier to use a third party plugin such as Blueprint Creator to create blueprints. 

Once you decide to create a new template, you should strongly consider using the Page Properties macro if you think you will be using this template more than a few times. By inserting a table on the page and surrounding it with the Page Properties macro, all of your users’ pages that are created by this template will have the aggregated information where your corresponding Page Properties Report macro is. To take this one step further, you can insert variables into your table that is in your Page Properties Report macro. Variables create a form-like field which users fill in with information. This keeps everything clear and easy for users as they enter information into your template. The information you need in your corresponding Page Properties Report macro will be impossible for users to miss if they are added as variables. Templates allow all your project managers to use the same company customized page to plan projects and keeps all information in one place. By customizing a template or blueprint, it will help reduce the risk of human error (of inputting information) and keep your information clean, as well as easily available.

Samples of How to Use Blueprints and Templates

From a project management perspective, Andrew Maker uses these macros extensively and details how to make your first Confluence Project Management Dashboard in this article from the Atlassian community. Templates allow HR teams to have pages for each employee to keep the important information for every employee on one page. Another use case of templates with the Page Properties macros is keeping a list of all company departments in a single building. You could quickly find who is responsible for each department and who you would need to get in touch with if you needed to talk to someone in that department. In this case, a Confluence template serves as your internal directory. A final example could be a sales team that has a page for each potential customer. They can use a template with the Page Properties macro surrounding the customer information and see a neat list of all their customers and potential customers on one page. The sales team could use the Status macro within the Page Properties macro to quickly see if the customer is a lead or a current customer. The power of the Page Properties and the Page Properties Report macros provides an endless stream of use cases and possibilities for your team. Templates boost this power by reducing the human labor and keeping things streamlined and concise.

Want More Confluence Macro Tips? Make sure to read, “How to Use Basic Confluence Macros in an Advanced Way” or contact us to learn about our Atlassian training solutions