How to search for macros and macro parameters in Confluence 4

Do you need to find all pages that use a given macro with given parameters and parameter values? For example, do you need to find all pages that use the Excerpt Include macro to include content from a given page? Or all pages that display the children of another page? Or all pages that display a given PDF file?

In a standard Confluence 4 installation, that is not possible because the macro parameters are not indexed. There is a new plugin available that makes the search possible: the Confluence Macro Indexer plugin.

A quick note before we start

Using the standard Confluence functionality, you can already search for occurrences of a given macro (but not its parameters). Enter the following in the Confluence search box, assuming that your macro name is “x”:

macroName: x*

You don’t need a plugin to use the above syntax. For details, see my previous post: How to search Confluence for usage of a macro

What’s new

The Confluence Macro Indexer plugin enhances the Confluence search, so that you can search for specific macros, macro parameters and/or parameter values. With the plugin installed, your Confluence site will allow a new search field name that you can enter into the Confluence search box, followed by a colon, like this:

wikiMarkup:

The plugin is available for Confluence 4.0 and later. I’m using Confluence 4.3.

How to use the macro search

Before you can use the macro search, you or your administrator must install the plugin onto your Confluence site. Installation structions are at the end of this post.

To use the search:

  1. Enter 'wikiMarkup:' followed by the macro name and/or parameter, into the Confluence search box at top right of the Confluence screen, or on the standard Confluence search screen.
    For example: To find all occurrences of the Include macro that include a page called ‘Introduction to chocolate':

    wikiMarkup:"include:Introduction to chocolate"

    There are more examples below.

  2. Press Enter or choose Search. The search results will appear as usual.

Notes:

  • After installing the plugin (see instructions below), you will need to reindex Confluence to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.
  • The field name is case sensitive. You must enter ‘wikiMarkup:‘, not ‘wikimarkup:‘ or any other combination of case.
  • The macro names, parameter names and parameter values are not case sensitive.
  • You will need to include double quotation marks around the text after the field name, if the text includes special characters such as a colon. For example, enter the following code to find all occurrences of the Include macro that include a page called ‘Introduction':
    wikiMarkup:"include:Introduction"
  • To use the search, you need to know the wiki markup for the macro name, the parameter names, and the accepted parameter values. The Confluence 4.x documentation contains such information for some of the macros. See https://confluence.atlassian.com/display/DOC/Confluence+Wiki+Markup+for+Macros. For the other macros, please refer to the Confluence 3.5 documentation: http://confluence.atlassian.com/display/CONF35/Working+with+Macros.
  • The plugin enhances the search only for macros and macro parameters – not for URLs in links or other such items.
  • The works for user macros too.

Examples

Find all pages that use a given macro

To find all pages that use the Excerpt Include macro:

wikiMarkup:excerpt-include

It works with quotation marks too:

wikiMarkup:"excerpt-include"

Find all pages that include an excerpt from a given page

To find all occurrences of the Excerpt Include macro that include content from a page called ”Introduction to chocolate':

wikiMarkup:"excerpt-include:Introduction to chocolate"

Find all pages that include a given page

To find all occurrences of the Include macro that include a page called ‘Introduction to chocolate':

wikiMarkup:"include:Introduction to chocolate"

Note: In fact, the above search will find the occurrences of the Include macro as well as the Excerpt Include macro.

Find all pages that include any page with a name starting with a given string

To find all occurrences of the Include macro and the Excerpt Include macro that reference any page that has a name starting with ‘Introduction':

wikiMarkup:"include:Introduction"

Find all pages that display a given PDF file using the View PDF macro

To find all occurrences of the View PDF macro that display the file ‘ChocRecipe.PDF':

wikiMarkup:"viewpdf:name=chocrecipe.pdf"

Find all pages that display the children of a given page

To find all occurrences of the Children macro that display the children of a page called “Chocolate home”:

wikiMarkup:"children:page=chocolate home"

Find all occurrences of all macros referencing a specific parameter

You can find all macros that have a specific parameter and a specific value assigned to that parameter. For example: If there are two macros, MacroA and MacroB, that have the parameter "page=My page name", then your search will pick up all pages that contain either MacroA or MacroB.

This search query will pick up all Children macros, just like the previous example. It will also pick up any other macros that have the same “page” parameter.

wikiMarkup:"page=chocolate home"

Screenshots

Searching for all occurrences of the Include and Excerpt Include macros that include content from a page called ”Introduction to chocolate':

Searching for all occurrences of the View PDF macro that displays the file ‘ChocRecipe.PDF':

How does it work?

In order to understand how to use the enhanced search, it’s useful to know exactly what the plugin does.

The plugin converts the macro code from Confluence 4 storage format to Confluence 3 wiki markup, and then adds the result to the Confluence index, thus making it searchable.

Let’s take the Excerpt Include macro as an example. The plugin takes the following code:

<ac:macroac:name="excerpt-include"><ac:parameter ac:name="nopanel">true</ac:parameter><ac:default-parameter>Introduction to chocolate</ac:default-parameter></ac:macro>

and converts it to this:

{excerpt-include:Introduction to chocolate|nopanel=true}

It then adds the above text to the Confluence index.

How to install the plugin

You can install the plugin via the Confluence plugin manager, just like any other plugin.You need Confluence System Administrator permissions to do this.

If your Confluence site is open to the Internet:

  1. In Confluence, choose “Browse” > “Confluence Admin” > “Plugins”.
  2. Choose “Install Plugins”.
  3. Type “macro indexer” in the search box on the “Install Plugins” tab, and choose “Search”.
  4. Click the plugin name “Confluence Macro Indexer” to see the plugin details.
  5. Choose “Install”.
  6. When the plugin is successfully installed, rebuild the Confluence index to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.

If your Confluence site cannot access the Internet:

  1. Download the plugin JAR from tha Atlassian Marketplace: https://marketplace.atlassian.com/plugins/com.atlassian.confluence.plugins.confluence-macro-indexer-plugin
  2. Save the JAR file somewhere on your local computer.
  3. In Confluence, choose “Browse” > “Confluence Admin” > “Plugins”.
  4. Choose “Install Plugins”.
  5. Choose “Upload Plugin”, browse to the saved JAR file, and upload it.
  6. When the plugin is successfully installed, rebuild the Confluence index to ensure that all macros on existing pages are added to the index. See the guide to administering the Confluence content index.

The Confluence Macro Indexer plugin installed

About these ads

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 4 September 2012, in Confluence, technical writing, wiki and tagged , , , , , , , , , , . Bookmark the permalink. 7 Comments.

  1. Shannon Greywalker

    Shouldn’t all this be in the doc for the new plugin itself? And is this plugin (and its doc) referenced from the standard Confluence doc page about searching in Confluence? (https://confluence.atlassian.com/display/DOC/Searching+Confluence)

    While I appreciate the intent of this blog, frankly it’s too many disparate sources to remember to look through when I need to figure out how to do something in Confluence. Either some of this info should be moved into the Confluence doc proper, or else this blog and its contents should be _prominently_ linked to from all closely-related locations within the official Confluence doc.

    Just my two cents, from a reader-access perspective. :)

  2. Shannon Greywalker

    Also, I must say I find it…strange…that to provide this functionality, the plugin designer had to resort to converting 4.0 XML storage format back to 3.x wiki markup as part of the “implementation details” of the plugin. Why couldn’t you simply index and search the XML markup itself? Wasn’t that one of the points of evolving Confluence markup to XML in the first place?

  3. Shannon Greywalker

    Finally, I’m always confused when I see on the Marketplace description for an Atlassian-developed and provided plugin the term “No vendor support”. That makes no sense to me. If it’s by Atlassian, why is there no vendor support? Can I rely on this plugin in a production environment if it has no vendor support?

    • Hallo Shannon

      Thank you for the suggestion of linking to the plugin from the documentation page, “Searching Confluence”. Good idea. Done.

      This is my personal blog. It’s about things of interest to technical writers, and it’s particularly related to tools and techniques, because I find the technical side of tech writing very interesting. The tool I use is Confluence, therefore much of the blog is about Confluence, and aspects that I think other technical writers will find useful. That includes plugins and tools written by myself, community developers, Atlassians, other technical writers, to enhance the Confluence functionality. I would have blogged about this plugin whether or not it was supported by Atlassian, and whether or not it was part of the Confluence app.

      A Google search will find the “how to” tips and tricks that I and others have contributed to general Confluence knowledge. It’s similar to what Rhonda Bracey does for Word, and Colum McAndrew for RoboHelp. Of course, things could get a bit murky because I work for Atlassian. It’s great that Atlassian allows me to blog like this, and I try to keep the lines clear between my blog and the official docs.

      To answer the question about why the information in this post is not in the official Confluence documentation: The plugin is not supported by Atlassian (yes, I know that’s a problem in itself) and in general we don’t document unsupported tools.

      Why isn’t the plugin documentation located somewhere else? The plugin developer found it difficult to find a suitable location, so we decided on my blog as a handy spot since I was planning to blog about the plugin anyway.

      I’ve added a comment on this issue in the Atlassian issue tracker, asking if there are any plans to include the extended macro search in the Confluence app itself, rather than as a plugin. That would solve the issue that the functionality is not supported:

      https://jira.atlassian.com/browse/CONF-24568

      Cheers
      Sarah

  4. I like the simplicity of the “macroName:” search syntax. I’m really pleased it works on user macros too.

    Is anyone else seeing the search engine proposing a “did you mean” option when you use this though? I get Did you mean: mucronate:

    I never knew there was such a term. I shall have to thank Confluence next time I try this in Scrabble! ;)

    • Ha ha, I had seen the “did you mean” suggestion but hadn’t thought of the Scrabble possibilities. Prompted by your comment, I’ve looked up “mucronate” now too: it means “ending abruptly in a sharp point”. Heh.

  5. Hello,

    I have successfully used the Macro Indexer plugin by referencing the Include macro to simulate your example above; however, I have not been able to use it with the Excel macro. I would like to know what pages I have that use the Excel macro to call a specific sheet within a specific file. Is this possible?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 1,470 other followers

%d bloggers like this: