Elements Connect Integration

In this page

What is Elements Connect?

(supported since Better Excel Exporter 2.6.0)

Elements Connect integrates external data sources (SQL databases, LDAP, Active Directory, REST APIs, Salesforce, CSV files, etc.) to Jira.

Elements Connect integration features

• You can export the Elements Connect managed custom field types like nFeed, nFeed - Date, nFeed - DateTime, nFeed - User (and even the legacy nFeed [deprecated]) to Excel.
• Better Excel Exporter supports custom reporting on Elements Connect custom fields, using pivot tables, pivot charts and all other Excel features.
• Note that although Better Excel Exporter 2.6.0 supports Jira 6.2 or newer, this particular integration works only with Jira 6.4 or newer (due to Elements Connect).

(Need more features? Tell us in a support ticket!)

Tutorial video

Watch this short introductory video to see how fast you can export your Elements Connect data to Excel:

Elements Connect Excel export samples

Configuration

Configuring the Elements Connect custom fields

There is nothing to do. Better Excel Exporter will automatically recognize the Elements Connect managed fields and export them accordingly.

Configuring the export format for the Elements Connect custom fields

Elements Connect standard fields have customizable "display templates" that show the field values in the web interface. Display templates can contain arbitrary HTML code, but HTML formatting cannot always be represented in Excel. For instance, although multi-value Elements Connect fields are frequently displayed as HTML lists or HTML tables in the web interface, a table cannot be intuitively "fit" into an Excel cell.

Therefore, a transformation converts the value in the web interface to the value in the Excel cell. The default implementation transforms Elements Connect fields to comma-separated lists, regardless their original HTML representation. It simply removes the HTML tags from the HTML representation and concatenates the body texts using comma as separator.

For example, an HTML list:

<ul>
	<li>value1</li>
	<li>value2</li>
	<li>value3</li>
</ul>

will be exported to:

value1, value2, value3

Or an HTML table:

<table>
	<tr>
		<td>value11</td>
		<td>value12</td>
		<td>value13</td>
	</tr>
	<tr>
		<td>value21</td>
		<td>value22</td>
		<td>value23</td>
	</tr>
</table>

will be exported to:

value11, value12, value13, value21, value22, value23

This approach works intuitively in most situations, but if you want full control over the logic, please see the one-line transformer method xmlToDelimitedString() in field-helper-tool.groovy. This accepts the Elements Connect HTML value in the xml argument and the comma character in delimiter, then returns the string value to be inserted to the Excel cell. You can redefine the logic by modifying this method:

/**
 * Returns the body text fragments from the passed XML joined with the delimiter.
 * The XML is not required to be well-formatted and can even be plain text.
 */
private def xmlToDelimitedString(def xml, def delimiter) {
	xml.split(/<.*?>/).collect{ it.trim() }.findAll{ !it.allWhitespace }.join(delimiter)
}

If the transformation is OK, but you want to change the delimiter passed to xmlToDelimitedString, change that at the method invocation in field-helper.groovy:

// Elements Connect custom field types
case "com.valiantys.jira.plugins.SQLFeed:nfeed-standard-customfield-type":
case "com.valiantys.jira.plugins.SQLFeed:com.valiantys.jira.plugins.sqlfeed.user.customfield.type":
case "com.valiantys.jira.plugins.SQLFeed:com.valiantys.jira.plugins.sqlfeed.customfield.type":
	// it is invoked below!
	(value != null) ? xmlToDelimitedString(nFeedDisplayToString(issue, customField), ", ") : null
	break

For instance, to change from comma to line-break, modify the corresponding line to (note that last argument changed!):

(value != null) ? xmlToDelimitedString(nFeedDisplayToString(issue, customField), "\n") : null

Configuring Elements Connect displays for Excel exports

As written above, the transformation from Elements Connect to Excel relies on on the body text fragments separated by HTML tags. Therefore, you can fully control where to insert the commas (or other delimiters) in Excel by adding or removing HTML tags to the display template of the Elements Connect field. Depending on what tags you add, you can also control if those are shown with or without line breaks in the web interface.

This is best explained with some trivial display templates, all using multiple items with two variables {0} (key) and {1} (value):

<!--
	web interface: no line-breaks
	Excel: "key1 - value1, key2 - value2, key3 - value3"
-->
<span>{0} - {1}</span>

<!--
	web interface: no line-breaks
	Excel: "key1, value1, key2, value2, key3, value3"
-->
<span>{0}</span><span>{1}</span>

<!--
	web interface: with line-breaks
	Excel: "key1 - value1, key2 - value2, key3 - value3"
-->
<div>{0} - {1}</div>

<!--
	web interface: with line-breaks
	Excel: "key1, value1, key2, value2, key3, value3"
-->
<div>{0}</div><div>{1}</div>

<!--
	web interface: list items (an <ul> or <ol> element is expected to wrap these, of course)
	Excel: "key1 - value1, key2 - value2, key3 - value3"
-->
<li>{0} - {1}</li>

<!--
	web interface: table cells (a <table> is expected to wrap these, of course)
	Excel: "key1, value1, key2, value2, key3, value3"
-->
<tr><td>{0}</td><td>{1}</td></tr>

Troubleshooting

When I uninstall or disable the Elements Connect app, it also disables the Better Excel Exporter app

This is a very infrequent and random problem, which is deeply rooted in Jira's OSGi component dependency management. Solution: simply re-enable Better Excel Exporter (via the Universal Plugin Manager) and it will work.

There is a "Failed to find the Elements Connect API" warning in my Jira log

Just like previous one, this is rare and random, also related to OSGi and Jira's internal ComponentAccessor returning a null object as Elements Connect API. Solution: simply reinstall Better Excel Exporter and it will work (and it will not happen again). (Note: even with the warning written to the log, the export falls back to a simplified mode and gives a so-so result for the users.)

Learn more about Elements Connect

• Elements Connect product information (at its own vendor)
• Elements Connect documentation
• Elements Connect app page (on the Atlassian Marketplace)