How to create a Confluence page based on a custom macro template

Problem

As a Jira administrator, you want to create a Confluence page from a Jira issue by using a template that gives you full control over the content of the created page.

Solution

Create a Confluence operation and use a field mapping that uses a custom macro template where you can customize and design the page content by passing needed data (issue Summary, Status, Description, Labels, …) as parameters from the Jira issue to the Confluence page.

Tutorial

In Confluence:

You need administrator rights in Confluence in order to perform the following steps:

• Go to the “User Macros” configuration page

• Click on “Create a User Macro”

  • Macro Name: “custom-macro”

  • Visibility: all users

  • Macro Title: “My First Macro”

  • Under “Definition of User Macro”, set “Macro Body Processing” to “Rendered”

  • Paste the following Template:

    CODE

    ## @param variable:title=Variable|type=string|required=true|desc=Elements Copy & Sync variable <a href="https://doc.elements-apps.com/elements-copy-and-sync/latest/fields-mappings/configuring-confluence-mappings/page-velocity-variables" target="_blank">cheat sheet</a>
    <span class="aui-lozenge aui-lozenge-current">$paramvariable<span>

  • Save macro

• Create a Confluence page that will be used as a template and add the previously created custom macro to it.

  • Define the variable(s) you need to inject from the Jira issue, let’s say we need to retrieve the Jira issue Summary and Status

  • This allows you to reference variables, such as $issue.summary, which will be retrieved from the Jira issue from which the Confluence operation is triggered.

  • The macro should be called for each variable that needs to be used in the page

  • Clicking on the “Cheat sheet” link will redirect you to a list of available variables that can be called in this macro.

    

• Publish the page. You have now a Template that can be used in your operation to create the Confluence page based on it
  

  

In Jira

You need administrator rights in Jira in order to configure a Copy&Sync operation (and access the administration page of the app)

Create Confluence mapping

In Copy&Sync administration page, go to “Fields mapping” tab:

• Create a Confluence mapping:

  • Set a name

  • Page title: Issue Summary

  • Page content:

    • Source: From page

    • Select the Space where the custom macro was created

    • Select the page where the custom macro is used.

    • Set “Variables“ to “Custom macro“ and enter the macro name “custom-macro”.
      

      

• Click save

Create Copy&Sync Confluence operation

In Copy&Sync administration page, go to “Operations” tab

• Click “Add” to create a Confluence operation.

• Set the operation name.

• Set the conditions on Display and Activation tabs based on your use case.

• In Target tab:

  • In “Server”, select the Confluence instance

  • Confluence page creation:

    • Parent select mode: Parent page

    • Space: Select a space where the page will be created.

    • Parent page: select a page in the selected space that will be a parent page for all Confluence pages created by this operation.

    • Fields mapping: select the previously created mapping
      

      

• Click Save

That’s it! Create a Jira issue and trigger the previous operation, a Confluence page will be created with issue Summary and Status mentioned in it.