Documentation for Confluence 5.8 (Server).
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

User macros are useful if you want to create your own custom macros. These can be to perform specific actions, apply custom formatting and much more. 

User macros are created and managed within Confluence itself, you do not need to develop an add-on. You will need some coding skills though.  

You'll need System Administrator permissions to create and manage user macros. 

On this page:

Related Pages:

Create a User Macro

To add a new user macro:

  1. Go to  > General Configuration > User Macros
  2. Choose Create a User Macro
  3. Enter the macro details (see table below)
  4. Click Add
Macro details fieldDescription
Macro nameThis is the name of the macro, as it appears in the code.

This controls who can see this macro in the macro browser or auto-complete. Options are:

  • Visible to all users
  • Visible only to system administrators

Note that if you select Visible only to system administrators, users will still see the output of the macro on a page, and the macro placeholder will still be visible when a user edits a page. It is only hidden in the macro browser and autocomplete.

All macro information is discoverable, including the macro title, description, parameter names and other metadata. Do not include confidential data anywhere in the definition of a user macro, even if it is marked as visible only to system administrators.

Macro TitleThis is the title that will appear in the macro browser and auto-complete.
DescriptionThis is the description that will appear in the macro browser. The macro browser's search will pick up matches in both the title and description.
CategoriesSelect one or more macro browser categories for your macro to appear in.
Icon URLEnter an absolute URL (for example or path relative to the Confluence base URL (for example /images/icons/macrobrowser/status.png) if you want the macro browser to display an icon for your macro.
Documentation URLIf you have documentation for your macro, enter the URL here.
Macro Body Processing

Specify how Confluence should process the body before passing it to your macro.

The macro body is the content that is displayed on a Confluence page. If your macro has a body, any body content that the user enters will be available to the macro in the $body variable.

Options for processing the macro body include:

  • No macro body
    Select this option if your macro does not have a body.
  • Escaped
    Confluence will add escape characters to the HTML markup in the macro body. Use this if you want to show actual HTML markup in the rendered page. For example, if the body is <b>Hello World</b> it will render as   <b>Hello World</b>.
  • Unrendered
    HTML in the body will be processed within the template before being output. Ensure that HTML is ultimately output by the template.
  • Rendered
    Confluence will recognise HTML in the macro body, and render it appropriately. For example, if the body is <b>Hello World</b> it will render as Hello World.

This is where you write the code that determines what the macro should do.

  • Use HTML and Confluence-specific XML elements in the macro template. Details of Confluence's storage format are in Confluence Storage Format.
  • You can use the Velocity templating language. Here is more information on the Velocity project.
  • If your macro has a body, your template can refer to the macro body text by specifying '$body'.
  • Each parameter variable you use must have a matching metadata definition. Use @param to define metadata for your macro parameters.
  • When using the information passed using parameters, refer to your parameters as $paramXXX where 'XXX' is the parameter name that you specifed in the @param metadata definition.
  • Use @noparams if your macro does not accept parameters.

See User Macro Template Syntax for more information and examples.

Do you need a plugin instead?

If you want to distribute your user macro as a plugin, please refer to the developer's guide to the User Macro plugin module. If you want to create more complex, programmatic macros in Confluence, you may need to write a Macro plugin.

Edit a user macro

To edit a user macro:

  1. Go to  > General Configuration > User Macros
  2. Click Edit next to the relevant macro
  3. Update the macro details
  4. Click Save

Delete a user macro

To delete a user macro:

  1. Go to  > General Configuration > User Macros
  2. The currently configured user macros will appear
  3. Click Delete next to the relevant macro

Before deleting a user macro, you should search for all occurrences of the macro in pages and blog posts. Users will see an 'unknown macro' error if you delete a user macro that is still in use on a page.  

Best practices

This section contains tips and suggestions for best practices when creating your own user macros.

Add a descriptive header to your macro template

We recommend that you include a short description as a comment at the top of the Template field as shown below. 

## Macro title: My macro name
## Macro has a body: Y or N
## Body processing: Selected body processing option
## Output: Selected output option
## Developed by: My Name
## Date created: dd/mm/yyyy
## Installed by: My Name

## Short description of what the macro does

Expose your parameters in the macro browser

The macro browser is the easiest way for users to configure your macro.  You can specify the macro category, link to an icon, define the parameters that the macro browser will use to prompt the user for information, and more.

Supply default values for macro parameters

As you can't guarantee that a user has supplied parameters, one of the first things to do in the macro is check that you have received some value if you expect to rely on it later on in the macro code.

In the example below, the macro expects three parameters, and substitutes sensible defaults if they are not supplied.

Example user macros

 Hello World

This example demonstrates how to create a user macro that displays the text 'Hello World!' and any text that the user places in the body of the macro.

Macro namehelloworld
VisibilityVisible to all users in the Macro Browser
Macro TitleHello World
DescriptionDisplays "Hello World" and the macro body.
CategoriesConfluence Content
Icon URLYou can leave this field blank
Documentation URLYou can leave this field blank
Macro body processingRendered

Enter the code below in the template field - this example will print the text straight onto the page.

If you wanted the text to appear in a panel you could include the relevant AUI message class as shown here.

Using the 'Hello World' macro on a page

Now you can add the macro to your Confluence page using the Macro Browser, or by typing {hello in the editor and selecting the macro from the list of suggestions.

The result is:

If you chose to include a panel, the result would be:



This example demonstrates how to create a user macro that can contain text that is visible when viewing a page, but does not print.

Macro namenoprint
VisibilityVisible to all users in the Macro Browser
Macro TitleNo Print
DescriptionHides text from printed output.
CategoriesConfluence Content
Icon URLYou can leave this field blank
Documentation URLYou can leave this field blank
Macro body processingRendered

Enter the code below in the template field.

Using the 'NoPrint' Macro on a page

Now you can add the macro to your Confluence page using the Macro Browser. Text entered into the body of the macro placeholder will not be printed, but will appear when the page is viewed online.

Making the PDF export recognise the NoPrint macro

See Advanced PDF Export Customisations.


 Colour and Size

This example demonstrates how you can pass parameters to your macro. We'll create a font style macro which has two parameters to allows the user to specify the colour and size of the text contained in the macro body.

Macro namestylish
VisibilityVisible to all users in the Macro Browser
Macro TitleStylish
DescriptionApplies colour and size to text.
CategoriesConfluence Content
Icon URLYou can leave this field blank
Documentation URLYou can leave this field blank
Macro body processingRendered

Enter the code below in the template field. If your macro requires more than one parameter, you can use variables $param0 to $param9 to represent them.

Alternatively, you can also use explicitly-named parameters in your macro. These macro parameters will appear as variables with the name $param<x> where <x> is the name of your parameter. 

 Formatted Panel

This example demonstrates how to write a user macro that creates a panel that is preformatted with specific colours. It will create a panel that looks like this:



Note: The panel's title will be empty if the user does not give a value for the title parameter.

Macro nameformpanel
VisibilityVisible to all users in the Macro Browser
Macro TitleFormatted Panel
DescriptionCreates a panel preformatted with specific colours
Icon URLYou can leave this field blank
Documentation URLYou can leave this field blank
Macro body processingEscaped

Enter the code below in the template field. See below for a more detailed explanation of the code below.

Explanation of the code in the macro template

Below is a breakdown of the user macro template code. 

## @param Title:title=Title|type=string|desc=Title

@param defines the metadata for your macro parameters.

@param Title

This parameter is called "Title".


defines the parameter title that will appear in the macro browser as "Title".


defines the field type for the parameter as a text field.


defines the description of the parameter in the macro browser.

<ac:structured-macro ac:name="panel">

This calls the Confluence Panel macro.

The easiest way to find out the code name of a Confluence macro by viewing the Storage Format of a page containing the macro. You'll need Confluence Administrator permissions to view the storage format.

<ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>
<ac:parameter ac:name="borderStyle">solid</ac:parameter>
<ac:parameter ac:name="borderColor">#6699CC</ac:parameter>
<ac:parameter ac:name="borderWidth">2</ac:parameter>
<ac:parameter ac:name="titleColor">#000000</ac:parameter>

Sets the parameters for the macro: the background colour, border style, border colour, border width and title colour.

To discover the names of the parameters for a Confluence macro, view the storage format as described above.

<ac:parameter ac:name="title">$!paramTitle</ac:parameter>

Enters the value stored in the 'Title' parameter into the title section of the macro.

The ! tells the macro to leave the title blank, when there is no data in the "Title" parameter.


Users can enter data that is stored in the body of the macro. This line enables the macro to access and store the body content passed to your macro.


This command marks the end of the macro.


  1. I can't even make HTML work. It seems to be escaped, and therefore the tags appear in the page. Does anybody know what it takes to get either Confluence markup or html markup to appear when I use $body in the macro?

  2. This is not currently supported, because $param1 contains a string, and thus can't be used as a loop counter.

    If you would like to see this capability in user macros, please file an enhancement request at

    1. Well, it's actually easily doable in Confluence:

      #foreach ($i in [1..$generalUtil.convertToInteger($param0)])
        <b>loop #$i</b><br>

      The above code runs correctly in 1.4.3 (didn't test it in earlier versions but no reason why it should not work).

      I truly wish that Confluence could provide better docs for the objects listed though, 'cause obviously it's too skimpy to be of much help to people.

    1. Anonymous

      No kidding.  It's like they're trying to keep it a secret or something.

  3. This is not possible as all text entered in the body of a user macro is left alone by the renderer.


  4. Yeah, same wish here. I'll check if I could add it to wish list (or it's already there).

    Would it be difficult to implement it? Seems to me that Confluence just needs to pass in an object with a method that runs wiki syntax engine.

    1. A feature request has been raised for this and can be tracked via

      If you would like to see this feature included in confluence, please vote for it.

  5. It's a bit tricky but the following works:

    1. Well, this is even more powerful than any $renderedBody-variable which might be used. Just see here:

      The only problem I have now is that I also want to create Panels containing Wikified-Lists this way. E. g.:

      The <newline> is my problem: How to get a newline-character inside there so that Confluence finally renders a content like this:

      ?? '\n' does not work. It will render a content like:

      Any ideas welcome!

      1. Good hint Mark

        one little bug: you forgot the second " in the line before last:

      2. Did anyone report a workaround for newline in velocity script 'User Macro's?

        I'm using the following patchy workaround, but there must be a better way.

        Now, $newline or #newline() will return a newline character. $newline is faster as the velocity renderer doesn't have to start up and re-render the 'newline' content each time. It actually makes a difference if you are using it in a large loop.

        So mark's code would look like:

        which renders

        * line 1
        * line 2

        and you might want to use it like this, to replace all \n with newline characters:

        1. Depending on your opinion, this code for getting a newline character is a bit cleaner but still patchy.

          1. you need to have a string defined to get at the .format property, #hence set($newline="")
          2. %n is a platform independant newline characters
          3. null is because format requires an object for any replacement codes. We're not using any.
    2. Oops. One step to far. You can even make it much more easy and without errors when rendering such errors in the global-templates-preview:

      1. Hm. Seems as if this only works for simple bodies. I. e. you either have to use the first workaround and ignore the errors in the Global Templates Preview or you get even more complex. The following is an example-macro which just renders the body (but of course you might extend $wiki as you like):

        1. For the different behavior of renderConfluenceMacro and convertWikiToXHtml I raised an issue CONF-4220 which hopefully will be fixed soon.

          The different behavior will show up as soon as e. g. $body contains macros which need access to the current space. E. g. {blog-posts} will fail with just using renderConfluenceMacro (it won't show the news of the current space).

  6. I think it would be a good idea to have a "User Macro Library" just as it has been introduced for the "Scaffolding Macros". They might serve as examples and of course might be of general interest. I think this is better than the alternative to make every User Macro a Confluence Extensions appearing in the Extension Space. Perhaps we could in addition point from the Extension Space to the User Macro-Library instead.

  7. Is there any chance to make the User Macros visible in the Notation Guide? Otherwise they will have to be documented in some of the spaces to make them known to the Confluence-Users.

    I suggest something like JavaDoc, e. g.

    Where the description will appear as rendered Wiki-Content in the Comment-column while the notations are listed (separated by newlines) in the Notation-column.

    1. This feature request is being tracked at CONF-2294. Please go vote for it.

  8. Thanks for the help commenters - here is the hardest little thing I have had to write:

    This provides links the the indicated number of recent log posts. The hard part here was reversing the list. Could not get size, Collections.reverse or even get to function ...

  9. It looks like parameters are now 0-based rather than 1-based. Incrementing i in $parami in all my user macros fixed the problem I had after upgrading from 1.3.5 to 2.1.1.

    1. Btw the following should be fixed in the page (replace bold by param0):

      You can pass parameters to your user macro in the same way as any other macro (separated by | signs), these parameters are provided to your template as param1, param2. . . paramN.

      1. hmm this is odd: with only one parameter, it only works if I use 0 as the start index, but with multiple parameters i can keep using 1 as the start index:


        Could this be a bug?

        1. Even with multiple parameters the first parameter is still $param0 on testing in Confluence 2.1.2.

          That is, the following macro:

          When called like this:



          1. You're right David. User error. Thanks for checking.

  10. Hello,

    I need to have a way to decide whether a page is exported as PDF or not. I thought I might use $action.isPrintableVersion() but this seems to return false for PDF generation. Does anyone know any other way to do this?


    1. There isn't any way to do this at present, but in 2.1.4 you will be able to do:

      #if ($renderContext.outputType == "pdf")
      I'm a PDF
      c'est ne pas un PDF


  11. I'm using the technique I learned on this page to fetch a numeric value from a database, like this:

    The value is returned, but it comes back with leading and trailing newlines. This is a problem, because sometimes I want to follow the value with a "%", as follows. I can't put the "%" inside the macro, because not all invocations of the macro want the "%".

    I've tried trim and replace functions, to no avail (but perhaps I didn't invoke them correctly; I am not a java programmer). Trim seems to ignore the newlines, and when I did $globalHelper.renderConfluenceMacro($query).replace("\n",""), the macro returned "${renderedContent}" (that is, the literal variable name, not the rendered content!)

    Can someone show me how to trim these newlines?

    1. I would expect


      to work.


      replace() expects characters rather than strings, so the code you used above coulsn't find a function to call.

  12. For some reason, replaceAll("\n","") seem to work.

    Here's my code and the output (I've put "x" on either side of \${renderedContent} in the macro, to make more obvious the source of the unwanted space):

    Macro Source
    Page Source (WIKI markup)
    OUTPUT (in browser)
    VIEW SOURCE (in browser)
  13. I think that the position of the "x" characters in the above make clear that the unwanted newline is not in the result of $renderedContent=$globalHelper.renderConfluenceMacro($query), so no manipulation of $renderedContent is going to help. For some reason, the user macro execution process is adding newlines to what I want to return.

    Is there some sort of a context that I can manipulate, to tell it that my output is inline?

    1. Not easily. There's some CSS hacks you can use, eg:

      <span class="inline"> rest of macro output here </span>

      Then use following CSS:

      span.inline {
      display: inline !important;

      Or something along those lines. However, it seems that MSIE doesn't cope well with this (or anything else really, I do wish they'd hurry and get IE 7 out as then web development will be significantly easier as everything runs to one standard).

      The only reliable way we've found is to create a java plugin version of the macro. Fairly easy to do, but a complete pain when all you want is a quick user macro.

      Ideally, we need an "Display inline" checkbox when creating a user macro - there are vast numbers of cases when people want to display just some inline text or whatever, but can't because it gets wrapped in <p> tags by default. For example, you might want a common thing like company name, email address, product name, etc., to be ouput by a user macro = ensures consistency across a big site and also allows you to easily update in one place at a later date. However, the lack of inline ability for user macros (even if you try digging in to the API from them there is still no joy) thwarts every attempt. (sad)

        1. The issue says that it is resolved, but unfortunately only for macros which have a body. I am writing a small macro to create a link to a particular space, and I want it to render after I create the link (so that it will insert the "create page" in the case that the link target doesn't already exist (it is for an acronym space). So my macro doesn't have a body (i.e. {acronym:TLA}) I really don't want it to have to have a body (unecessary typing for my users). So I would still like to see and "Inline" checkbox.

           In the meantime, I used this, which is awkward, but works on both IE and firefox:

          1. I use this. Equally awkward, but with the added features of:

            • works in templates, preview or page views
            • has a friendly 'hover text' indicating that you will navigate to a new space
            • replaces only leading/training <p> tags, not all <p> tags, which isn't important in this use case but helps with other render tasks
            1. I raised another issue for this: CONF-15333.

              I included your workaround in the comments (thanks for providing it) but I really think this should be fixed in confluence. I think there was some confusion in CONF-5456 that caused the issue to be resolved when it wasn't really properly resolved.

  14. Anyway to create link using a custom page template using a user macro?

    An attempt at hacking it in for instance. Sort of works but doesn't pick up the template name.


    1. The create page macro might do what you are after as you can pre-define prefix and postfix for the page title, and if no page title is specified, the user is asked to enter one.

    2. to 'hack' the url and supply a template properly, you require a template ID. See the create-page macro mentioned below.  Also, the linking plugin works well in most cases.

  15. How to enumerate all registered user and get their full names?

    The code above doesn't work (sad)

    1. The property you want is "fullName" so the following may work better:

      #set($users=$content.getUserAccessor().getUsers() )
      #foreach($user in users)
      1. Unfortunately the enumeration doesn't work at all.
        Seems like The getUsers() returns an empty array.

        1. Are you using LDAP or another external user authentication system? I think if you are using LDAP for your user authentication, .getUsers() returns an empty array.

      2. How can i just find the username of the currently logged in user?  this is the code I have write now:

          1. If I have this code in a macro called currentuser:

             and on my page, I put this code:  {currentuser}, what prints on the page is


            So it is not working quite yet...  I would also like to have this working on each page without manually putting the macro on each page...

            1. Hi Jeff,
              here is a small usermacro that gives you information about the current user.
              Get the $user object first and then obtain:
              fullName - full name of an user
              email - user's email (if exists)
              name - user's login name



              1. Oh thats how you do it, thanks!  Where can i find other properties I can grab about the current user or other info?  (using $action.???  or $user.browsertype? etc...)


                1. It would interesting (but perhaps unsafe) if we could obtain the users password through this. This could solve the problem with the Jira bug lists in Confluence when anonymous access is off. Is this possible?

              2. This is great to know.

                Quick question however, is the use of $action.remoteUser security safe?. i.e to find the current user, does this use a call to return the sessions authenticated user, or does it simply extract the name from a cookie or something silly?

                From what I can tell it's using a call through authenticated user or something involving the session info, so it should be safe against someone seeding a username in a form with a REMOTE_USER value. ??

                I only ask because I want to be sure I can use it in a certain way.

                1. $action.remoteUser returns you the Atlassian User "User" object that has been properly authenticated through the session. It's not a String value and cannot be spoofed by simply passing through a variable in the headers or in the URL.

                  The only realistic way I can think of to change user, is to log packet data coming from the confluence server and then hijack the session for the appropriate user. Using SSL would remove that option though.

                  Knowing most users - it would probably be easier just to shoulder surf, or even just bribe them with chocolate.

              3. Actually, i would also be interested in knowing if thre are other parameters that i can use, other than: 




                For instance I'm looking for the CreatedDate parameter. Where can one fine the full list?

  16. I am astonished. With Confluence 2.2 named parameters seem to work. Just tried by try-and-error and got e. g. $paramstyle to refer to the value of argument "style=something".

    It would be nice to know if this is a "first try" or if this is finalized so that we can base new user macros on this new feature. And if so, it should be documented here (smile)

    1. any indication yet if this is a hidden alpha-feature or something that will persist?

  17. Any have a tip how to access the tiny link – e.g., "" – for the current page within a user macro? Thanks!

    1. I'm also interested in this;

      • it was done in a macro: {page-info:tinyurl}
      • and I can get a page url in a user macro:
        • $action.getGlobalSettings().getBaseUrl()$content.getUrlPath()
      • but not a tiny url. This requires a 'new' object, TinyUrl, be created which can't be done in velocity unless there is an available object to return one. I can't see how to get from $content to TinyUrl()
      1. Anonymous

        not exactly a one liner... but it works


        ## this is the example reading the tiny URL, but unfortunately only rendered...
        ##unrender to have only the tiny part remaining

        ##adding the base URL


        1. Anonymous

          not exactly a one liner... but it works...
          and this time I used preview before posting (smile)

      2. Hi,
        Today I did a small macro named "tiny2mail" to send the current page tinylink via email.

        It receives 2 parameters:

        • param0: the texte before the link within the email body
        • param1: the link title

        The macro cotent is :

    2. This might not be a timely response, but it might be useful to anyone who has the same requirement.
      I managed to get it working in a user macro by using these two lines:

      Note: Please ensure that the Macro has a body is unticked and Macro generates HTML markup is selected as the output.

      Hope it helps (smile)
      Husein Alatas

  18. Is there any way to change the text color/size of just the title line in the panel macro?



    1. You will need to modify the panelHeader class in the CSS file (confluence/WEB-INF/classes/styles/site-css.vm).


      1. Anonymous

        I have modified the panelHeader class in the CSS file site-css.vm to include a line...

        color: white;

        But when I use firebug to inspect the area that should have the white text, the css shows the color parameter crossed out.

        I am using Theme Builder 3.x and at one time I had this working using the same css within a style macro but it is no longer working.

        I tried adding it to the Theme Builder CSS for the Layout but that didn't work either.  Any suggestions?

        1. Hi there,

          The suggestion is applicable to only the "Default Theme". If you are using other theme than the default, you may need to look into the associated CSS file of the particular theme.
          If you are using the Theme Builder, I would suggest you to seek assistance from the author at the plugin's Issue Tracker:


  19. Some questions about usermacros:

    1. What's the function to add a label to a page? I want to add an unique automatically generated label to a page to use in template, by writing an usermacro. With add-label macro you can't do this.

    I have

    #set($result = $labelmanager.addLabel($content,new Label("test$pageId")))

    but doesn't work. A counter would be better than the pageId, but is it possible to store a variable on a page? So for each new added page the counter does +1: test1, test2, test3, test4, ..?

    Thanks a lot.

    2. The function to get the templateID if you know the templatename?

    1. 1. There's no way to add a new label from within a user macro, because you can't create new objects in Velocity. You'll need to write a macro plugin to do this.

      2. The PageTemplateManager is responsible for this. The method is getPageTemplate(String name, Space space), where you pass a null space for a global template. However, you can't access this object from user macros either, so you'll need to write a macro plugin if you want to do this.

      The Velocity context for user macros only includes objects used for common operations. Including all the Confluence managers would make page rendering slower and consume more memory. Macro plugins allow full access to everything inside Confluence, and are not difficult to get working with a small bit of Java knowledge.

      1. Anonymous

        So which Confluence managers are available in the Velocity context for user macros?  And once we have that list, how about linking each manager to its documentation page so we can learn how to use it?

        I'm appalled and irritated that the user macro documentation is so woefully sketchy and filled with broken links.

  20. I'm a little confused on how to use the New Code Macro with Javascript.

    On many of your Macro pages, there is a Version area within a table that has the ability to expand or hide info for each version. (hide-desc, show-desc)...There's no macro in the confluence library that does this and the page tree plug in is for different pages. I can't seem to get the New code one to work though. Could someone show me an example of how something like this is done or used.

  21. I'm using a simple macro to automatically generate a link to a url. Here is the content of my macro:

    This works fine except the url is in a <p> block in the generated code, so if I want to use this in line it causes carriage returns around the link.

    Here is a sample of my wiki markup on one page:

    Here the html source of the resulting page:

    Which looks like this:
    This is a link to

    JIRA #123

    using a macro and all of this should be on one line.

    This is a link to JIRA #123 not from a macro.

    1. BTW, my specific question is, how can I prevent the macro from adding the extra <p> tags around the link.


      1. Using HTML code in the macro instead of wiki markup seemed to do the trick.  Something like:

        but I would expect to be able to do this with wiki markup as well...

        Note that with the above I do loose the cute little arrow icon etc which I'm sure I could also add manually in the html code if I wanted.

  22. If I edit site-css.vm, it crashes confluence on the server.  I have disabled velocity caching.  Any thoughts?

    1. Please log a support request at -- thank you

  23. Hello. I'd like to implement "term" user macros that behaves much like metadata macro but displays a tooltip when mouse is over the "term". Its definition should be smth. like
    {term:WMP}Windows Media Player{term}
    . Later, user can define
    and get WMP displayed with some marking, so reader can point a mouse on it and get a tooltip saying "Windows Media Player". I am not sure that such macro is already exist.

    If you know about a macro doing it, please let me know. Otherwise, please guide me how i can display a tooltip like window using Velocity.

    Thank you.

    1. Please try posting this question on our Answers site. -- thank you

  24. It's a pretty common request. Here's another way to do it:

  25. Anonymous


    I want to create a macro that prints the current date along with the macro body - so something like |somemacro| body goes here |somemacro|

    should output

    body goes here  09/11/2007 5:37 PM

    This date only should be printed once - not updated with every edit of the page. I can get the page modified time but that will update on every page edit.

    1. you want a wikipedia-like signature, which requires updating the page content directly, not a user macro.

      • can't do it from a user macro, they are for 'display' only
      • look at the 'sub-section' or 'refactoring' plugins for examples of code to create this sort of thing.
      1. Hey James,

        Where are these plugins detailed?

        Being able to annotate a user ID and time stamp seems like a really basic function for wiki software.
        I had hope that the comments system might provide a solution but the time resolution makes this unsuitable.


  26. Is there a way to get the content of a page (other than the current page) from inside a macro?  (I'd like to at least initially do this in a user macro, but if I need to write a real plugin, I can do that--however, from looking at the docs and the objects available, I don't see any methods that let you specify a page and space and get back the contents.)

    1. Hi Jonathan,

      To my understanding, you wish to display the content of a specific page onto another page. If this is the case, you may wish to use the Include Page macro which enable one to include the content of a defined page onto another.
      If the above is not an option, a suggestion that I can think of is to build a plugin of your own which would serve the purpose. Sorry to say that, this cannot be done using the User macro due to the limitation of the available objects.


      1. Thanks, Tony.

        I don't want to print the entire content of the other page like the include page macro would, but to extract part of that page programmatically and display that.  (FYI, this is for a feature that I'm trying to convert from our previous wiki that extracts definitions from a glossary page.)

        So it sounds like I need to write a real plugin.  

        1. yes and no. A real plugin would be more robust and safer, and probably more performant...but take longer to prototype

          • look at the edit-include user macro
          • it is a user macro that uses an internal renderer to call 'include', and then based on a simple parsing of the result decide whether to show the result, or render a different macro.
          • you could use the built in java string API to do some pretty sophisticated parsing if you want to, instead of just looking for an error message as I have done.
          1. James, that is exactly what I was looking for. Thanks a lot!  (And, BTW, that edit-include functionality is great!)

  27. Does anyone know how to do a $string.replaceAll (or equivalent) with DOTALL in effect, I mean so that . matches anything, including newlines?

    That is:

    if given a multi-line body, will put "got the whole thing" once for each line.  The behavior I need is to replace the entire contents of the body, even if there are newlines in there.

    1. didn't have time to test it or check the syntax, but if you use REGEX directives, perhaps:

      $body.replaceAll("(?si:.*)","got the whole thing")

      s - treat as single lines, i.e. newline is a character
      i - case insensitive match
      m - treat as multiple lines, i.e. break on newline

      these are normally used outside the expression in perl, i.e. "s/.*/text/si", but not java.

  28. HI all -
    Does anyone have any ideas on how to use the useraccessor to pull back ldap information in a user macro? We are using Active Directory and I want to be able to pull back various properties of the user, such as manager and department.
    Many Thanks

    1. Hi Jag,

      Did you mean that you would like to be able to retrieve other user information from the LDAP server such as phone numbers, addresses and other attributes? Unfortunately, Confluence does not support this. Having that said, there is no methods provided in the UserAccessor class that is able to retrieve the additional information from the LDAP server.
      However, you may be interested look at the following improvement request regarding improving our Atlassian User to be able to retrieve additional data:

      Feel free to cast your vote to increase its popularity and add yourself as a watcher so that you will be notified if there are any updates to the issue. Also, you may add comments to improvement issue to truly reflect the importance of the feature to you.


  29. Hi,
    We add usernames as labels on pages to indicate what users in our community need to take action on a page. I wanted to add a 'contentbylabel' macro to all spaces that would reflect what the signed-in user needed to address in that space, based on their username. For example:

    contentbylabel:@user | key=@self

    Unfortunately, Confluence does not support the feature in this macro. Does anyone know how to create a user macro that will do this?

    Many thanks,


    1. Hi Darcy,

      Indeed, the contentbylabel macro does not provide such parameter that meets your requirement.

      that would reflect what the signed-in user needed to address in that space, based on their username.

      You may be interested to look at the getRemoteUser() method available in the ConfluenceActionSupport class (the $action object) to see if it helps.


  30. I am trying to add a macro showing a table of content using the toc-macro, but packed into a box:

    <div class='panelMacro'>
    <table class='infoMacro' width="100%">

    This shows prints {toc} if I set "macro generates HTML". If I set "macro generates wiki markup" I am looking at html codes surrounding my table of content.

    Any idea how I could get what I'd like to have: the table of content inside a box?

    1. Use a macro with a body, and insert $body where you currently have

      . That turns it into a macro that puts anything in a box. For a toc, just type:

      1. Yes, that would be a soultion, but — since I want the users to include only one macro like {mytoc}. I could get it if I define two macros: one to generate the box and one to generate wiki markup, but this leaves a door open to access an intermediate macro, users not intended to use!

        How can I write a macro doing both: expand wiki markup and html?

    2. There are two other ways

      • use wiki markup instead of HTML for the div and table tags, and select 'macro generates wiki markup'
      • create and use a render velocity template macro as follows
        <div class='panelMacro'>
        <table class='infoMacro' width="100%">
      • the contents of the render macro can be found here: render wiki markup from a user macro
      1. We do a similar thing to generate a default 'formatting' for our toc
        Macro: {contents}
        body: no
        output: Macro generates wiki markup

        ## Generate a table of contents, right justified and in a green box
        {float:right|width=300px|background=#E0F0F0}{*}Table of Contents{*}{toc}{float}
        1. Anonymous


          I'm in the same situation with wanting to format a div box around the TOC macro.

          I tried several attempts at using the included 'class' option that TOC has, and can successfully create and format a div as desired.  However, my problem is that the macro does not accept any CSS formats that I try to apply to the list items (list-style-type= square) for example.

          Here is the css:

          border: thin solid red;
          list-style-type: square;

          Which results in a red outlined div, but with the default 'disc' type instead of the 'square'.  The class formatting only applies to the div element, and nothing below that.

          I have also tried doing the suggestions above, but I cannot get a macro within a macro to work either.  Any help would be greatly appreciated!


          1. I'd take this question to the TOC macro page

  31. Anonymous


    Can anyone suggest how to retrieve a page by it's name and space key? The following macros code certainly does not work:

    #set($temp=$pageManager.getPage("SPACEKEY", "PAGETITLE"))

    Retrieving page by id does not work as well.

    Retrieving user works perfectly.

    Thanks in advance!

    1. Hi there,

      You may be interested to look at the following documentation that outlined a list of the objects that can be used in user macros:

      For further information regarding the methods available from the objects, please see our latest Confluence's API.

      Also, the following classes extracted from the API may serve as a reference to you:

      Ideally, if you have further questions regarding customizing Confluence, you can share them in our Answers site, as the users/developers there who have experience in similar issue might share their idea with you.


  32. I'm trying to write a user macro that can do stuff with the page's children, and it seems like I need to get the Page object in order to get the children. It seems like this should work:

    But $page never seems to get set to anything. ($page.getChildren() just prints literally.)

    (Two FYIs: I know I could just use a "children" macro to print this--I'm going to collect the children list and process it in the macro. Also, I can see this kind of thing would be better done in a plugin, but I'm trying to prototype this.)

    Thanks! Jonathan

    1. Hi Jonathan,

      You may be interested to look into the $content object which is also supported in user macro. Having said that the Page object's methods are accessible if the $content object is being used.


  33. Does anyone know how to get an instance of the spaceManager and/or pageManager from within a user macro?

    Specifically, I'm trying to retrieve the blogposts (news items) for a space. The Space object is available, but its method "getBlogPosts" is listed as deprecated, along with the note " use spaceManager.getBlogPosts(space, false) instead". 

    The Action object available appears to be a concrete instance of ConfluenceActionSupport, as opposed to one of its subclasses such as ViewPageAction, which does appear to have methods to retrieve the space/pageManagers.

    Any help would be greatly appreciated!

    1. Hi Chris,

      To my understanding, for Confluence version 2.3 and later, it is advisable to use the "PageManager.getBlogPosts(Space, boolean)" instead of using the "SpaceManager.getBlogPosts(Space, boolean)"in the "getBlogPosts" method. You may want to give a try by using the "PageManager.getBlogPosts(Space, boolean)" method in a user macro and see if it helps. For more information regarding the methods available for the SpaceManager, the following documentation may serve as a reference to you:

      Meanwhile, if you have any queries regarding Confluence customization, I would suggest you to post your queries to Atlassian Answers. From there, others developer/user who have experience on this customization should be able to share their ideas with you.

      Choy Li

  34. How do I write a VM that iterates through a list passed as a parameter.


    1. Hi Hugh,

      I would suggest you to post your queries to Atlassian Answers. From there, others developer/user who have experience in velocity should be able to share their ideas with you.

      Choy Li

  35. When is the core api documentaton online again? I get an error 500.

    1. Hi Alexander,

      I have raised this issue with our system administrators and they are currently looking into it. If you still aren't able to access the site by tomorrow, please send us a report at the link below:

      Sorry for the inconvenience.


      1. And what about the 2.5 javadocs?

        1. Hi Brian,

          The API docs for Confluence 2.5 is available at the following link:

          Choy Li

  36. To embed content from another site into Confluence you can use iFrames. However, since Confluence doesn't allow arbitrary html tags in the wiki markup, this is a prime candidate for user macros:

    Name: iframe
    Macro has body: no
    Template: <iframe src="$src" width="$width" height="$height"></iframe>

    {iframe:src= |height=400px|width=800px}

    1. Anonymous

      This *does not work* in my install of Confluence 2.7.3. It must have been a security fix.

      1. I wasn't aware you could use named parameters in user macros. Also, I don't think you can specify 'px' in dimensions on width/height. Try this instead:

        Name: iframe
        Macro has body: no
        Template: <iframe src="$param0" width="$param1" height="$param2"></iframe>


        1. Upon testing, it seems that the <iframe> is output, but it has no attributes. Very odd behaviour really...if it was for security, why not remove the <iframe> altogether?

          1. yeah, that's weird. not seeing this behaviour on 2.5.7.

          • you can use named parameters in user macros, but they must be prefixed by "param". for example:
          ## create an iframe element
          #if($paramsrc && $paramsrc.length()>0)
          #set($src=$!paramsrc )
          #if($param0 && $param0.length()>0)
          #if($paramwidth && $paramwidth.length()>0)
          #if($param1 && $param1.length()>0)
          #if($paramheight && $paramheight.length()>0)
          #set($height=$!paramheight )
          #if($param2 && $param2.length()>0)
          #if($paramtext && $paramtext.length()>0)
          <div> <div>Remote Content: <a href="${src}">${text}</a></div> <div><iframe src="${src}" width="${width}" height="${height}" style="border:2px solid red;"></iframe></div> </div>


          • works on our 2.5.7 install (and has worked since 2.10)
          • if you want to always use the scr/width/height parameters, and no warning text, you could just use this
            <iframe src="$!{paramsrc}" width="$!{paramwidth}" height="$!{paramheight}" style=""></iframe>
          • works on our 2.5.7 install (and has worked since 2.10)
  37. Is it possible to create a "run-once" user macro that generates wiki markup and inserts it on the page as if the markup was natively written there?

    I'd like to be able to create a user macro to make it easy to generate some formatted links, but I'd also like those links to update if/when pages are moved or renamed later.

    Here's our user macro:

    Ideally I'd like to simply use it on a page like this:

    And end up with the actual wiki code on the page so the links are dynamically updated:

    1. Hi Jessica,

      To my understanding, parameters ($param0....) feature available for the User Macros are static values. Having said that, any changes to the Page title would not reflect the parameters defined in the user Macros.
      Perhaps, you may be interested to look at the Navigation Plugin which provide a similar feature to the "User Macro" that you have created.
      If the above is not an option for you, you might need to create a macro plugin of your own that provides you this feature.


  38. How do you access the entire list of parameters as an array? How am I supposed to know how many parameters there are?

     I am building a macro that is basically a collection of other macros, namely to create a header that is both toc and children. I want to pass the parameters of my macro directly to the constituent toc macro. What is the best pattern for doing this? I would like users to use my macro with toc options exactly as they would use the basic toc macro.


    1. Hi Jason,

      To my understanding, User Macros allows inputting standard parameters($param0-n) based on how it is defined in the macro's template. For any advance parameters to passed on to the macros, we encourage you to create a Macro Plugins of your own instead.
      Should you have further questions regarding customization, feel free to post on our Answers site. Users or developers who have experience in similar customization might share their idea with you.


    2. Did you find an answer to this? I need to do the same thing.

      1. I ended up doing this, which works well for arbitrary number and order of parameters:

        I hope this helps!

  39. I wrote this quickie user macro to hide and display large content in a confluence page (like jiraissues macros). It starts out with the content hidden, but clicking the link toggles between display and hide.


    • Macro Has a Body: true
    • Convert Body Wiki markup to HTML
    • Macro generates HTML Markup

    The id is an arbitrary (but unique for the page) identier. The body is the content you wish to hide/display. This works fine with embedded macros.

    The Code:

    1. This seems very similar to Expand User Macro

      • In the spirit of collaboration and keeping things simple, would you work your macro into the pre-existing Expand User Macro?
      • Tim recently improved the expand user macro to auto-generate a unique id, so a user does not need to provide one.
  40. Anonymous


    How can I have a People Directory button in a new dashboard?

    I found the create space button macro and it works, but i cannot find any macro for people directory button.

    thanks in advance.

    1. Anonymous

      btw, I am using Confluence 2.7

      thanks again!

      1. Hi there,

        I believe you are referring to a new space/page instead of dashboard. Anyway, I am afraid that there is no macro for creating people directory button available at this moment (similar to the create space button macro). However, you can try to create a user macro that will display the same icon for people directory. A simple example would be:

        or in wiki markup:

        Hope this helps.


        1. Anonymous

          Hi Azwandi,

          Thanks, this would do but not when we have to move our new dashboard to another server.  We need something similar to create a space button macro, no hard coding of path so that in the future we're not going to have a broken link.  Any other way?

          1. Hi there,

            A simple way that I can think of is by removing the base URL, as in:


  41. I want to get a list of pages in a macro and according to this I should be using a SpaceManager method. However I can't work out to get the SpaceManager object - as far as I can tell there's no way of getting it from $space, $generalUtil, $action or $page.

    For now I'm using the deprecated method, but would prefer not to. I've noticed a couple of other things like this too where I can't access various managers and have had to use deprecated methods instead.

    Is there any way to get to the SpaceManager object from user macros?

    1. I know your question is quite old.. still, here's an answer:

  42. Is there any way to create a new object in a macro?

    The particular case I wanted was to get a java.util.Date object and I managed to work round it be using this:

    #set($end = $generalUtil.getBuildDate().clone())
    #set($ret = $end.setYear($year))
    #set($ret = $end.setMonth($month))
    #set($ret = $end.setDate($day))

    However it'd be useful to know how to create arbitrary objects for other things in future.

    1. Hi,

      As far as I know, user cannot initiate any Java object in Confluence. However, Confluence allows you to access some of the predefined Confluence objects:

      You can get java.util.Date object, using the following method:



  43. I think the '$page' object is not available.

    1. Hi Peter,

      Indeed, the '$page' object is not available for user macro. Alternatively, one may use the $content object instead which is a supported object when creating a User Macro.


      1. Anonymous

        I was on the same boat as Peter looking for the page object to use in an user macro.

        Thank you, Tony, for your feedback (smile)


  44. Here is some macro code that will display information about the user who created the current page (a toString() dump of the User object), the full name of the creator, and then full name of the last modifier:

    Results look like this:

    user = id:360449 name:admin fullName:John Smith created:2008-08-01 23:26:40.46

    Creator Full Name: John Smith

    Last Modifier Full Name: John Smith

    Code needs to be modified if you want to handle the 'Anonymous' user correctly (i.e. if you allow a non-logged-in user to create/modify a page, etc.).

  45. Hi all,

    i just wondering if there is any way to access the space manager using velocity language because i need to get all spaces and check if the logged user has personal space or not by iterating over them


    1. Hi Mahmoud,

      As far as I know, Confluence does not provide you with an object of spaceManager. The only available objects are mentioned in the explanation of this page.\\

      Kind Regards,


    2. I was able to write a fairly complex macro that uses a report to render newsfeeds (my company didn't like the output of the blog-posts macro and didn't want to learn how to write reports).  So, using the CustomWare reporting plugin, you should be able to find if a given user has a personal space.

  46. Is it possible to use the output of one macro as the parameter of another?

    I want to write a macro that uses the sql-query macro to grab information and then add that information as a label using the add-label macro, but it appears that when the two macros are rendered, the add-label is 'switched off' and put on the page as plain text.

     For example, if I put the following code into a page:

    {add-label:{sql-query}.... {sql-query}}

    The label returned by sql-query is not added to the page and the following is displayed:

    {add-label: LABEL}

    (with LABEL being the data returned by sql-query )

    I've tried setting a Velocity variable equal to the sql-query output, Confluence couldn't render the macro. So,

    #set ( $variablename = {sql-query}....{sql-query} )
    produces the following error:

    Error formatting macro: macroname: com.atlassian.core.exception.InfrastructureException: Error occurred rendering template content

    Has anyone got any ideas? Am I trying to force macro to do something they can't?

    Many thanks,


    1. Hi John,

      Perhaps, you can start off with the Replace and Render Plugin, which allows value injection to macro parameters.


    2. Hello John

      Did you solve your problem. I have exactly the same needs, may be you could help me further. Thanks


  47. Hi,

    I am not sure what the problem at your end is, however, I found that my IE7 will throw an "Automation server can't create object" error whenever I clicked the link. The workaround is to lower the ActiveX security settings of the browser. If you are having trouble creating a user macro for this, the following are the settings that I chose:

    • Tick "Macro has a body" - Escape HTML in macro body
    • Set Output to "Macro generates HTML markup"

    Hope that helps.


  48. Here's a simple macro we created to display Adobe Acrobat PDF files directly on a wiki page, rather than having to download an attachment:

    Hope you find it useful.


  49. Hi,

    I wrote a macro which generates a link that, when clicked, works in tandem with Velocity code which appends a string to the end of the page URL, and adds a specific label to the page. This works great while my space is using the default theme. But I need to use my Theme Builder custom theme. How/where do I place my Velocity code so that my custom theme picks this up, and renders my macro correctly?

    Here's the code I placed within the Page Layout section in the Admin console:

    Here's my little user macro

    which I cite on my page:

    Any help would be awesome! I'm drowning here!


    1. Hi Betsy,

      From the looks of the first bit of velocity code, I think I gave you that in the atlassian forums, good to see you again (smile)

      I can see that you would experience problems with it, I have written a page on how to use the functionality of that bit of code as an user macro (I called it add-label-from-url in my guide), I have made some improvements too, it can handle multiple labels by separating each one with a comma, the only difference in usage is that the user macro uses "addLabel" instead of "addlabel" as the parameter (it is case sensitive).

      Just add the new user macro once created to every page that you want to use it in and it should work.

      Hope this helps you.

      Bo Wang

      1. Bo,

        Thanks so much for getting back to me. I'll give this a try!


  50. Anonymous


    i will add an pagetree on the left side by using an user macro.

    But the tree will be placed at the start of the page.

    If i enter the same code into the confluence page directly, then it works. I compared the html code. The usermacro creates some table tags which are not geneartet if the code is directly in the page.


    1. Using user macro: <table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr></tr></tbody></table>

    2. same line without user macro: <table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>

    1. <td class="confluenceTd"  valign="top" width="80%"></td>
    2. <td class="confluenceTd"  valign="top" width="80%">

    Any suggestions?


    1. Hi,

      Are you following the steps at Adding a Navigation Sidebar? Also, can you provide more insights on the user macro code (1) and the sample wiki markup (2)? It seems like you are using the {section} and {column} macros as well.


  51. Anonymous


    I'm creating a Macro of other Macros and I wanted to know if there was a way to have a parameter fill in with certain text by just having a parameter that I can set to true:

    "Test" Macro

    This macro is designed to automatically build linking tables based on certain labels, and also includes an option to add a page directly that puts the page in the correct place, using the correct template, with the correct labels. Also, I'm using the Visibility plug-in to hide the add a page button from users who are not logged in (annonymous cannot edit on our Wiki, ours is for Corporate use for documentation and various other things.)

    In the above, where I have $paramshow, I'd like to be able to use it as follows: {test:show=true} and I would like it to enter "confluence-users" in itself. In the current form I have to use it this way: {test:show=confluence-users} We will always want that parameter to be confluence users, but want to be able to disable it by not filling it in.

    1. I am afraid that it could not be done. However, you can treat the variable name as $param0, $param1,.... and use velocity script to apply some logic in the user macro code. It should be resulting in the same way as your query, the different is just about the name of the variable.

  52. Anonymous

    Can someone tell me where user macros created on administration console are saved? In database? I just would like to know how I backup them. Thanks,

    1. Indeed, it is stored in the database:

  53. Hi,

    May I know if you in purpose inserting this text Unknown macro:? Please get rid of it.

    I created the following simple script which is about similar with yours and it works fine:

    <script language="JavaScript">
      function testJS(strFile)
    <a href="javascript:testJS('$param0')">$param0</a>

    Maybe there is something wrong when IE creates an object ActiveXObject. Please consult the microsoft for further explanation on using that object.

  54. I am trying to embed Google Spreadsheets into a page via Iframe.  Here is what I did but the page is not loading 

    Page to embed:

    I created a user macro

    In my Wiki page, I added this to the Wiki markup

    My webserver gives me a web page not found$param0

    However, this works

    I suspect that URLs with parameters may not work with my macro.  Please help!!!!

    1. Hi Caesar Chu,

      I have raised a bug here. Please add yourself as a watcher to follow the issue.

      Alternatively, for the time being, you can replace the equals-to sign (=) in the parameters with &#61;

      For example:


  55. Is there any way to create a user macro that can do a date compare?

    I have a server maintenance list, and I want green flags next to servers that have recently been checked out, and red flags next to ones that need it (such as, after 3 months, just change the green flag icon to the red flag icon.)

    Basically, I want to do this (but this doesn't work - $param0 is the date set for when the server was last checked out.)

    Is there any way I can basically do adding or subtracting on the current date and compare it? I realize I may be going about doing this the wrong way, but you can get the basic idea.

    1. I recently had a need to do date math too. Check out my code here:

      Here are some snippets that will help you out:

      You will need a Date object and a Calendar object:

      You need to cast your passed parameter as a Date object (the date format of $param0 must be like MM/DD/YYYY or DD/MM/YYYY depending on your locale):

      Get a date object with the current time -90 days:

      Finally, do date comparison:

      This should get you close. Just a couple tweaks and you should be in business!

      1. Thanks for the help!

        I must admit, I know very little about VTL, only just a little bit from a few simple Confluence User Macros. I'm passing in the date format in MM/dd/yyyy and in the current form, it only changes from the red flag icon to the green flag icon if I put in a date after the current date - which is the reverse of what I wanted, but I fixed that part...

        Oh, and to clarify:

        I want the flag to be green until 90 days have passed, then turn red (I think I had the logic wrong above as well.)

        IE: I set $param0 to be 07/01/2009, and I want the flag to turn red after 09/28/2009 (I think that's 90 days..)

        1. I forgot a line of code that you will need at the top:

          And actually, the logic as written above will show the flags as you need. Basically it is saying:
          If the submitted date ($param0) is before (less than) the current date -90 days, then
          Show red flag
          Show green flag

          1. Okay, I see now.

            Adding that line fixed it - thanks!

  56. Anonymous

    What is the logic behind restricting the creation of user macros to system administrators? In production environments, departments usually only administrate only their own space and not the entire site. We need to create, update and use macros frequently (preferably as easily as templates in MediaWiki) without bothering the admins everytime.

    1. Hi,

      The logic in restricting the creation of user macro only to system administrator is due to security concerns.

      However, I understand the need for such a feature especially for the space admin.
      I have found a similar feature request. Please add yourself as a watcher, vote for this feature and add your own comments to this feature request.
      For further details on how we include new features and improvements, you might want to read this page


  57. Anonymous

    How could I get paramaters passed to a page?  I need to pass a parameter to a page and display data based off of that parameter.  Usually, page parameters are passed with a question mark, like pagename?paramName=paramValue.  How can I access these parameters within Confluence, or, is there another way to pass a parameter to a page?

    Thank You,

    Eric Dion Baker

    1. Hi Eric,

      Try $req.getParameter("paramName") and you should retrieve "paramValue".

      1. Anonymous

        Kevin - PERFECT!!!  Does exactly what I was looking for, thank you!

        Eric Dion Baker

      2. Anonymous

        Kevin (et al) - Is there a way to pass parameters between confluence pages?  Here's my specific example - Using templates, we populate wikis with information from a database, usually by a specific Request Number.  Currently, in the template, we use the @ RequestNumber @ to have the user enter the Request Number.  I would like to gently automate this and supply the Request Number, but sending the ?param=value chokes within a Confluence link.  So, I know that using link-page I can specify a template, is there a similar way to send a variable?

        Thank you,

        Eric Dion Baker (I should just get an account now....)

        1. Just found the "run" macro in an article published 2 days ago that covers this very topic!

  58. Anonymous

    I'm looking to write a macro that would allow the user to customize the output of the current date using a string format (i.e $param0 = "mm/dd/yy" or "yyyy-mm-dd")

    I'm new to VTL and have tried crafting my own using the date math example above but I must admit I'm a bit lost at this point.

    Ideally I'd like to have access to the SimpleDateFormat class.

    Any thoughts?

    1. Anonymous

      Here is one way using Bob Swift's wonderful Scripting plugin (many thanks Bob\!):
      1. Thanks for the compliment (smile). There is an easier solution using the Run Plugin. It is also more secure since the scripting plugin should only be used on specific protected pages - see Macro Security Plugin. If you like, you can wrapper this in a user macro to make it easier for users.

  59. Anonymous

    I could use some tips for setting up a user macro that uses two parameters (project and link) in a SQL query for which the result of the SQL query (a bunch of strings) are to be used to format a URL. The URL is the endresult of the user macro.

    Using the parameters in the SQL statement is not the problem. I used the method splitCommaDelimitedString available in $generalUtil to create a String Array of the SQL query (I ran the SQL macro with the new endColumn=, argument to format the returned values in a comma seperated way):

    The result is a String Array with all the return values of the SQL query. I would like to access the elements in $urlArray to construct the url like this:

    However, I cannot access elements in the String Array directly by specifying there index. I googled for this and it seems that I need the ListTool for this. I don't understand how I can get acess to the ListTool from within Velocity Templates. Or are there better ways to achieve this? It would be even better if I could get access to the column names from the SQL statement but that seems impossible.

    1. Hi, there. Sorry that I do not have an answer for this. May I suggest you to try Atlassian Answers? In my experience, that would be the best channel to ask this question. Hope that helps.

  60. I wanted to create a USER MACRO for creating a   (VAR|list(element1,element2)) and after that form a template just fill the variables... but it shows not as a variable, just like a comboBox.. how can i do a ComboBox for selecting some information and the selected information should be rendered just as text. (no combo boxes) i am talking of using a Template with a combo.. in my template i have my user macro {mycombo:varX} and the varX is the name of the variable... but the selection is not stored....

  61. My User Macro
  62. Hello

    I would like to have Right To Left text. RTL

    I see this

    I tried to create it but it doesn't work

    Does anyone has any experience in creating a macro for RTL?

    Thanks in advance

  63. Anonymous


    I want to get the title of the current page and thought that...


    ...will handle this, but I always get "$title" as output.

    1. Just try "$content.getTitle()" with lower case "g", it must work.

  64. Anonymous

    That was easy. It works :-)

  65. Anonymous

    hi All,

    I would like to create a user macro which 'll have url based on the parameter value passed.


    {ss:1234}, {ss:SAMPL12345}
    where ss:1234 link to one url( ie. , ss:SAMPL123 'll link to another url(

     i feel like

    user macro name: ss

    macro has a body: yes

    type : generate as html markup

    if($param0 matches no)

     { <a href="$param0>$param0</a>
    elsif($param0 matches alphanumeric)

     { <a href="$parm0>$param0</a>
    well i don't know how to write that in velocity language... plz help me how can i do that...

    1. Did you consider using shortcuts ?

      1. Anonymous

        hi ,

        actually the url's which i've mentioned here is just example. But  actually it'll have my client's company url. so how can create using shortcuts.

        1. You can create shortcuts for everything you want. For example, we can imagine your intranet site is "" which is obviously a private website. Imagine this website is taking a parameter for its search engine like "" you juste have to create a shortcut with :

          key : intranet

          expanded value :

          Within a page, you will just have to write [confluence@intranet] and then you will have your link.

          Does this solution fit your requirements ?

          1. Anonymous

            Hi kevin,

            Thanks.. Thanks a lot... it's working....

  66. Anonymous

    Hello All!!

    I need a user macro, so when I click on a picture I can open another page that I want.

    so, i can make this user macro?? Anyone help-me??


  67. Hi,

    the User Macro Library resp. the links to the library entries currently seem to be unavailable.

    On this page the following error message appears:

    Unable to render {children}. Page not found: DISC:User Macros


  68. Is there a way to find out if any view restrictions apply to a page via its ancestors? $content.getContentPermissionSet() explictly does not return any ancestry permission sets.

    I'm trying to use the following macro to display the space name as well as an indication of whether the current page is 'public' (visible to non-logged-in users) or not:



  69. Hi,

    I want to know if an user has permissions to view a page. The next example works so good but only with the current page ($

    How can I do a similar question for any other page?


  70. Hi, I want to create my own user macro (admin screen \-> user macro} displaying blogpost with a certain label. Problem is, I'm unable to retrieve any posts. This is the code i use


    name= sofnews

    Macro has a body

    Use unprocessed macro

    body macro generates html markup

    The result on a page is nothing. (code = /{sofnews/} )

    But on the same page I use the /{blog-list/} macro as a control and there it displays perfectly the blog posts. What am I doing wrong in my code?


  71. Anonymous

    Can anybody tell me how I can find out whether the Usermacro is on the Admin console? I want to create a Usermacro for the Dashboard, but it should not be run in the admin console under "General Configuration" - "Site Welcome Message".

  72. Anonymous

    I have a formular with some textboxes, the user can write anything in it but there are always empty textboxes.

    On the page I can see the empty textboxes and that looks silly. I think it is good to delete these boxes.

    How can I write a macro that delete an empty textbox in a formular?

  73. Hi - it ssems to look like a easy task, but I can’t figure out how to display the space logo on a page. More precisely on top of the navigation of the documentation theme.

    I started using the #logoBlock Macro, but it turns out, that the logo won’t show, when I do turn the logo OFF in the space preferences.

    I would like to have a generic markup not including an image url. I could easily do this with simple markup.

    Do I really have to install the {builder-logo} macro?

    Here is the temporary result

    1. Solved (/)

      The following code will return the space logo url - even if it’s hidden or the global logo.

      I had to dive into the additional objects available for Velocity Language

      1. You saved my day Thomas!

        Greetings from Dornbirn

  74. Anonymous

    Hi, how do i import the following java classes to user macro

    import com.jscape.inet.smtp.*;

  75. Anonymous

    hi, some on tell me, how do i create an email functionality (or macro) to send an email

  76. It would be interesting to know how to reference the Icon URL, if the icon is located in a plugin.

    (Note: I can do this, but I'd rather avoid to hardcore such an URL

    TIA for a tip.

  77. How to extract the contents of space description?

    What I'm trying to do:

    • Display a list of spaces showing the space logo, the space name and the space description by calling a macro and filling in the desired label.
    • Should work in Confluence 3.2 (current version) and 3.5 (upgrade planned this summer)

    This results in the correct space logo, space name and link for the given label, but the description comes up with something unexpected.
    The space description version info instead of the space description (sad)

    spacedesc: SandBox v.12 (22806611)

    The version info displayed changes only when updating the space description so I'm close... but arrrgh... >.<

    Anybody an idea how I fix it? And on a sidetrack, why it supplies the version of the space description and not the description itself?

    1. Try to append ".getDisplayTitle()" to your space description object (you are retrieving an Atlassian object, not a simple string) :


      depending of what you want to display.

      More info :

      1. You rock dude, that did the trick (big grin)
        Thanks a bunch!

        1. Kevin Merigot Your user macro is exactly what I'm look for to display Space Descriptions on the dashboard in Confluence 5.7. However, I can't seem to get it working. I wondered if you were still using it and if you'd upgraded to Confluence 5.x?

  78. Hi guys,

    Trying to write a macro that prints a list of users in a group along with information in their user profiles, for instance their Department or email address. I am really struggling. Would anybody know how to do this or if it's a simple task?


  79. Hi,

    Is it possible to find the user who updates a user macro?



  80. Ok great confluence made us use the mouse like crazy. Was far more comfortable using the wiki markup, as you could do use another text editor with strong find/replace capabilities.


    The macro I had written that used $param0 etc.. aren't usable anymore as they didn't define in the templace the arguments they used.

    How do you configure in the template so that it takes arguments, just not named arguments? (e.g macro uses $paramX where X is a integer)

  81. Anonymous

    I do not understand why it is called a User macro when you have to go the Admin Console to add one?

  82. I desire to know if is possible to use JQuery with user macros or even when we modify normal pages.

    Can you suggest me some interesting way to do that ?

    Thanks in advance


  83. Anonymous

    I would like to use the User Profile macro to display the current user logged in and viewing the page.  We have pages that describe sales sheets, and our sales people would like their contact information to display on the pdf export without having to change the username each time.  Does anybody have a macro to display the same information (name, position, department, email and phone, profile picture is optional)?

  84. Anonymous

    I need to have a user macro that inserts the username and the date of the moment when the macro ist inserted but does not change it's output if the page is edited.

    Second thing is that there should be more than usage in a document each giving back only values of the moment of there first insertion.


    #set ($Date = $content.getCurrentDate().clone())

    #set($result="$ - $Date :")


    works for an non edited page - when edited it changes the output values.

  85. Is it possible to write our own Macros in OnDemand???  I am trying to write templates for my companies upcoming migration to OnDemand.  Currently we are using Scaffolding Plugin and I am aware it will not work in OnDemand.  The OnDemand template feature seems sufficient, but it does not allow options such as list-option that would allow you to customize text displayed based on which option was selected in a drop-down (now $variable) list.  Is there a work around for this?  Any and all help appreciated.  


  86. I would like to create a macro similar to the "Warning" macro but with a different icon. I attempted creating a macro panel and the results are not what I expected and the icon does not appear.

    1. Hi Robin,

      That's exactly what I'm trying to do right now. Did you get anywhere with this?


      1. Not really. I ended up creating a panel and inserting an image as a work around.

        STOP! All Users: Please Read Carefully!

        Before proceeding, make sure you have completed ....................


        • Entered panel title.
        • Border Style = n/a
        • Border Colour = n/a
        • Border Pixel Width = n/a
        • Background Colour = #FA5858
        • Title Background Colour = #FA5858
        • Title Text Colour = n/a

        In the body, I inserted an image I imported. (Above, I attached a weblink.) and the body text is typed in white.

        1. Ah, I see. I'll try that as a workaround - thanks.

  87. <ac:macro ac:name="macro-name" />

    Above line is not working when i add it when i customizing the space content.

    it is rendering as normal text(sad).

    My macro is xhtml-macro. Hence i can't use renderConfluenceMacro(..) .

  88. Hi experts...

    need a little help here.

    I need a set of macros which provide some date arithmetic

    For example, today is 9 July 2013

    What i need is a user macro that when I type {start of week} and give param:

    1. Monday and 1, result will be 8 July 2013

    or Sunday and 1, result will be 7 July 2013

    2. Monday and 7, result will be 14 July 2013 (which is 8 + 7days)

    3. Monday and -1, result will be 7 July 2013 (which is 8 + (-1)day)

    Can anyone help me?

    I also put a question in

    Thanks in advance

  89. Issue if the icon you're referencing is attached to a page, and not publicly accessible:

    User macro place-holder fails to load due to image not being publicly accessible

    CONF-24857 - Allow Confluence to Use Attached Images as User Macro Icon Resolved

  90. Hello Experts,

    I need some Help to get macros run at confluence 5.1.4. that were running when we were on 3.x.

    I our "installed user macros" section there are several macros signed with an "!". "They have to be changed to work with HTML-Templates." or so is the note above this section.

    An Example therefore is the Version-Macro. On the former confluence version it showed the version of a page.

    It only consists of


    What can I do to make this run on confl. 5.1.4?

    With your description I hope to be able to rerun all my other macros to.

    Thanks a lot,


  91. Hi,

    did someone else faced also an issue with the best practice on supply default values for macro parameters? 

    Since we´ve upgraded to Confluence 5.7.4 the check as suggested

    #if (!$spacekey) ... #end


    isn´t working any more.  Findings: I works only with

    #if ($!spacekey == "")   ... #end

    Any idea why?

  92. The NoPrint macro has a serious bug: the info and warning macros no longer render their content. Anyone know of a solution?