Chaining Keys with Keychains

This guide will help you get a better understanding of keychains and suppliers.

Suggested Reading

Read these guides first before continuing:

Understanding Keychains

The key (excuse the pun) to understanding Reporting is to understand how keychains work.

To recap, keychains are basically keys from suppliers that are chained together with the ">" character.

For example, this keychain: "content:modifier > user:picture", which we used in the Showing Recently Updated Pages in a Table guide.

So in this context, the content:modifier key is calling the modifer parameter from the Content Supplier to find out which user updated the page.

Because the modifier parameter from the Content Supplier returns a User type value, we can then "chain" a parameter from the User Supplier, in this case the picture parameter, to retrieve the profile image of the user that updated the page. 

Example 1: Counting the Number of Characters (Including Spaces) in the Page Title

Let's find out how many characters (including spaces) there are in the title of this page.

  1. First, we'll have to find to ask Reporting to retrieve the title.
    Create a Report Info macro.
    For the Key, type in "content:title"
    This means we're using the Content Supplier to retrieve the properties of Title parameter, which is of the Text type.

  2. You should now have this:



    which should result in the following text:

    "Chaining Keys with Keychains"

  3. Now that we have the title, let's ask Reporting to actually count the characters in the title.
    Edit the Report Info macro you created.

  4. Amend the Key parameter so it now looks like this: "content:title > text:size"
    This means that we are now passing the value of the content:title to the Text Supplier, to retrieve the Size parameter.
     
  5. You should now have this:



    Which should result in this:

    "28"

  6. And now we know that the title of this page (Chaining Keys with Keychains) contains 28 characters, including spaces.

Example 2: Finding Out How Many Pages Were Created by the Creator of the Current Page

Let's find out how many pages the creator of this page (Ted Mahsun) has created in this Confluence instance.

  1. First, let's get Reporting to retrieve the creator name.
    Create a Report Info macro.
    For the Key, type in "content:creator".
    This means we're using the Content Supplier to retrieve the properties of Creator parameter, which is of the User type.
    Let's also make the creator name a hyperlink to his profile by ticking the Link To Item checkbox.

  2. You should now have this:

     

    which should result in the following:

    "Ted Mahsun"

  3. Now, create another Report Info macro.
    For the Key, type in "content:creator > user:authored pages count".
    This means that we are now passing the value of the content:creator to the User Supplier, to retrieve the Authored Pages Count parameter.

  4. You should now have this:



    which should result in this:

    "1352"

  5. Let's make this more readable.
    String the two Report Info macros that you created together with some relevant words to form a sentence.

    For example:



    which should result in this:

    "Ted Mahsun has written 1352 pages in this Confluence instance."

Example 3: Displaying the Image of the Person Who Last Updated the Page

Now let's try something else. Let's display the avatar image of the person who last modified this page.

  1. Create a Report Image macro.

  2. For the Key, type in "content:modifier > user:picture".
    This means we are using the Content Supplier to retrieve the properties of the Modifier parameter (which is of the User type).
    And then we chain that onto the User Supplier to retrieve the properties of the Picture parameter.

  3. You should now have this:



    which will render this: