Exporter Unit

The purpose of exporter units is to provide an easy way to customize the plainbox reports by delegating the customization bits to providers.

Each exporter unit expresses a binding between code (the entry point) and data. Data can be new options, different Jinja2 templates and/or new paths to load them.

File format and location

Exporter entry units are regular plainbox units and are contained and shipped with plainbox providers. In other words, they are just the same as job and test plan units, for example.

Fields

Following fields may be used by an exporter unit.

id:
(mandatory) - Unique identifier of the exporter. This field is used to look up and store data so please keep it stable across the lifetime of your provider.
summary:
(optional) - A human readable name for the exporter. This value is available for translation into other languages. It is used when listing exporters. It must be one line long, ideally it should be short (50-70 characters max).
entry_point:
(mandatory) - This is a key for a pkg_resources entry point from the plainbox.exporters namespace. Allowed values are: jinja2, text, xlsx, json and rfc822.
file_extension:
(mandatory) - Filename extension to use when the exporter stream is saved to a file.
options:

(optional) - comma/space/semicolon separated list of options for this exporter entry point. Only the following options are currently supported.

text and rfc822:
  • with-io-log
  • squash-io-log
  • flatten-io-log
  • with-run-list
  • with-job-list
  • with-resource-map
  • with-job-defs
  • with-attachments
  • with-comments
  • with-job-via
  • with-job-hash
  • with-category-map
  • with-certification-status
json:

Same as for text and additionally:

  • machine-json
xlsx:
  • with-sys-info
  • with-summary
  • with-job-description
  • with-text-attachments
  • with-unit-categories
jinja2:
No options available
data:
(optional) - Extra data sent to the exporter code, to allow all kind of data types, the data field only accept valid JSON. For exporters using the jinja2 entry point, the template name and any additional paths to load files from must be defined in this field. See examples below.

Example

This is an example exporter definition:

unit: exporter
id: my_html
_summary: Generate my own version of the HTML report
entry_point: jinja2
file_extension: html
options:
 with-foo
 with-bar
data: {
 "template": "my_template.html",
 "extra_paths": [
     "/usr/share/javascript/lib1/",
     "/usr/share/javascript/lib2/",
     "/usr/share/javascript/lib3/"]
 }

The provider shipping such unit can be as follow:

├── data
│   ├── my_template.css
│   └── my_template.html
├── units
    ├── my_test_plans.pxu
    └── exporters.pxu

Note that exporters.pxu is not strictly needed to store the exporter units, but keeping them in a dedicated file is a good practice.

How to use exporter units?

In order to call an exporter unit from provider foo, you just need to use in in the launcher.

Example of a launcher using custom exporter unit:

#!/usr/bin/env checkbox-cli

[launcher]
launcher_version = 1

[transport:local_file]
type = file
path = /tmp/submission.html

[exporter:my_html]
unit = com.foo.bar::my_html

[report:local_html]
transport = local_file
exporter = my_html

For more information about generating reports see Generating reports