Configuring Confluence mappings
In order to create a Confluence mapping, an application link with the Confluence platform needs to be configured.
To access the confluence mapping administration page:
- Go to the Administration menu > Addons > Elements Copy & Sync
- Click on the Fields mapping tab.
- Click Add and select your Confluence instance.
The following page will be displayed:
Page Title
The Page title section allows you to define the title of the Confluence page to be created.
- Issue summary : by choosing this option, new pages will have the issue summary as title.
- Free text : by choosing this option, you can define an arbitrary text with parameters.
If you use Free text, a Content input field will be displayed, where you can set an text of your choice. This text can have parameters that will be replaced before the page is created. For more information about these parameters, see issues fields injected via velocity variables.
When used in an operation, the page title will be editable:
It won't be the case if the operation is run in a post function.
Page content
The Page content section allows you to define the body of the Confluence page to be created.
Three options are available: Issue description, From page and Free text.
Issue description
By choosing this option, the source issue description will be copied to the page body.
If your issues have attachments and you want them available on the page, check the Copy attachments option. This should be the case if your description makes references to issue attachments.
From page
What is it?
With this option, Elements copy and sync will create new pages based on the content of another existing Confluence page. This last page is used as a template.
You can define placeholders for issue fields.
Read this blog post to learn more about this feature.
You can use this option if
- Your new page content depends on the source issue content.
You cannot use option if
- You want your macro parameters to depend on the source issue content.
- You want to apply advanced formatting to the injected variables
How does it work?
Create the reference page
The first step is to create a Confluence page that will be used as a template by Elements copy & sync.
Not a regular Confluence template
In this documentation we will sometimes call this reference page a template. This is not a regular Confluence template, this is a regular Confluence page.
At the moment, Elements Copy & Sync is not able to fetch Confluence templates from the remote Confluence instance.
Confluence page predefined layout
Add variables to the reference page
You can have variables replaced by Elements Copy & Sync when the new page is created.
Variables
The variables used have the syntax of Velocity variables, with one limitation. Velocity control statements are not allowed (#if/#else) and only variables starting with $issue will be evaluated.
These variables have the syntax of velocity variables and must be set into a specific macro, either:
- the status macro
- your own custom user macro.
Depending on your choice (either status or your own macro), Elements Copy & Sync will parse the page content and replace any macro found with the variable evalution if valid.
Please note, that in order to execute the Confluence Operations using this templates, user must have read access to the template page.
Configure the mapping
Once you have created your template, you can configure the mapping:
- Set Source to From page
- In the Page attribute, select the page create previously
- In the variable field select either Status macro or Custom macro (if you want to use your own macro)
Free text
What is it ?
With this option, you can set the XHTML content for the new page.
This is an advanced mode that is the most configurable, but more complicated to use.
You can use this option if
- You need to have variables inside a macro parameter. Ex: inject an issue field in a user macro (ie: inject issue key in the JIRA Issue macro)
- You want issue fields in a title. Ex: issue summary in a heading 1
How does it works ?
Define your layout
Create a page in Confluence, it will be your starting point.
In this page, unlike in the From page option, you do not have to use a macro to define variables for issues fields.
Every velocity variable used in the template will be replaced by issue fields when an Elements Copy & Sync operation will be executed.
Generate the storage format
Once the template is complete, get the Storage format from the page by clicking in the … button in the top right corner.
Choose View storage format
Copy paste the XHTML code and go to the Elements Copy & Sync field mapping configuration page.
Configure the field mapping
Copy paste the display template in the text area related to the Content attribute of the field mapping.
If you have user macros in the template, you can replace hard coded parameters by velocity variable to define injection points.
See the detailed list of Confluence Page Velocity variables you have access to populate your page content.
- The page used for this operation is not required by Elements Copy & Sync and can be deleted after this operation.
This could be a good practice to keep if if you need to change the generated pages content later.
- If you update this page layout, you'll have to manually update your Confluence mapping by getting the new storage content.
Labels
Here you can select the labels that you wish to be added to the Confluence page. You can select the source issue fields whose values will be used as a Confluence labels or write your own custom labels.
That's it! The field mapping can now be used in a Confluence operation.
•••