In this page

What is Color Custom Fields?

(supported since Better PDF Exporter 7.3.0)

Color Custom Fields extends Jira with custom fields that store color values. It makes managing issue attributes that can be intuitively color-coded (e.g. Risk, Impact or Complexity) intuitive and visual.

Color Custom Fields integration features

  • You can export the Color Custom Fields-managed custom field types like Select Color and Picker Color to PDF.

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

Tutorial video

The Better PDF Exporter app enables exporting those to customizable PDF documents:

Color Custom Fields PDF export samples

Jira issue with Color Custom Fields

Jira issue with Color Custom Fields

In this PDF export example, the risk's details are collected into their own section. Note the color-coded fields giving a quick reading and understanding on this particular risk. (For the color-blind, the integration can be configured to display the color name next to the colored rectangle.)

jira-color-custom-fields-export.pdf

Jira issue list with Color Custom Fields

Jira issue list with Color Custom Fields

This PDF is an issue list exported from a JQL search result, with all the risks in a given Jira project. Note that the export reminds to a heat-map kind of visualization, which makes communicating the risk factors with the project stakeholders quick and easy.

jira-color-custom-fields-issue-navigator.pdf

Configuration

Configuring the Color Custom Fields custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Color Custom Fields managed fields and export them accordingly.

Configuring the export format for the Color Custom Fields custom fields

The default behavior is that the color RGB values or color names will be exported (e.g. "#b04c75" or "green"). You can show the color itself in a small solid-filled, colored rectangle by uncommenting this line in the issue-fo.vm and issue-navigator-fo.vm templates: 

## uncomment this to export the colored rectangle
## <fo:inline background-color="$xmlutils.escape($color)" border="thin solid #777777">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;</fo:inline>
$xmlutils.escape($color)

Note that by commenting out the first and the second line, you have the options to export the colored rectangle, the color name, or both. All these will work.

Troubleshooting

I get "StringIndexOutOfBoundsException: String index out of range" error in the PDF

First, this problem can occur only if you enabled the "colored rectangle" export.

The root cause is that, unfortunately, Color Custom Fields does not validate the color RGB strings that its UI allows to select or enter. With some tricks, user can enter invalid RGB values, like "#ffcc99a" (note that instead of 6, it contains 7 characters after the hash mark!).

Although the browser tolerates these and treats them as white color in most cases, the PDF renderer is stricter and it raises this exception for invalid RGB strings: 

java.lang.StringIndexOutOfBoundsException: String index out of range: 9
 at java.lang.String.substring(String.java:1963)
 at org.apache.fop.fo.expr.PropertyTokenizer.nextColor(PropertyTokenizer.java:239)
 at org.apache.fop.fo.expr.PropertyTokenizer.next(PropertyTokenizer.java:175)
 at org.apache.fop.fo.expr.PropertyParser.parseProperty(PropertyParser.java:118)
 at org.apache.fop.fo.expr.PropertyParser.parse(PropertyParser.java:91)
 at org.apache.fop.fo.properties.PropertyMaker.make(PropertyMaker.java:438)
 at org.apache.fop.fo.PropertyList.convertAttributeToProperty(PropertyList.java:413)
 at org.apache.fop.fo.PropertyList.addAttributesToList(PropertyList.java:321)
 at org.apache.fop.fo.FObj.processNode(FObj.java:122)
 ...

How to fix it? Turn off the "colored rectangle" display and enable the "color name" display for the field values, based on the configuration guide above. Now the rendering will succeed even if the RGB string is invalid, and will show you which field value in which issue is the problem. Fix that, and then you can re-enable the "colored rectangle" display.

Learn more about Color Custom Fields