xenial (7) plainbox-template-units.7.gz
NAME
plainbox-template-units - syntax and semantics of Plainbox template unit type
SYNOPSIS
This page documents the Plainbox template units syntax and runtime behavior
DESCRIPTION
The template unit is a variant of Plainbox unit types. A template is a skeleton for defining additional
units, typically job definitions. A template is defined as a typical RFC822-like Plainbox unit (like a
typical job definition) with the exception that all the fields starting with the string template- are
reserved for the template itself while all the other fields are a definition of all the eventual
instances of the template.
Template-Specific Fields
There are four fields that are specific to the template unit:
template-unit:
Name of the unit type this template will generate. By default job definition units are generated
(as if the field was specified with the value of job) eventually but other values may be used as
well.
This field is optional.
template-resource:
Name of the resource job (if it is a compatible resource identifier) to use to parametrize the
template. This must either be a name of a resource job available in the namespace the template
unit belongs to or a valid resource identifier matching the definition in the template-imports
field.
This field is mandatory.
template-imports:
A resource import statement. It can be used to refer to arbitrary resource job by its full
identifier and (optionally) give it a short variable name.
The syntax of each imports line is:
IMPORT_STMT :: "from" <NAMESPACE> "import" <PARTIAL_ID>
| "from" <NAMESPACE> "import" <PARTIAL_ID>
AS <IDENTIFIER>
The short syntax exposes PARTIAL_ID as the variable name available within all the fields defined
within the template unit. If it is not a valid variable name then the second form must be used.
This field is sometimes optional. It becomes mandatory when the resource job definition is from
another provider namespace or when it is not a valid resource identifier and needs to be aliased.
template-filter:
A resource program that limits the set of records from which template instances will be made. The
syntax of this field is the same as the syntax of typical job definition unit's requires field,
that is, it is a python expression.
When defined, the expression is evaluated once for each resource object and if it evaluates
successfully to a True value then that particular resource object is used to instantiate a new
unit.
This field is optional.
Instantiation
When a template is instantiated, a single record object is used to fill in the parametric values to all
the applicable fields. Each field is formatted using the python formatting language. Within each field
the record is exposed as the variable named by the template_resource field. Record data is exposed as
attributes of that object.
The special parameter __index__ can be used to iterate over the devices matching the template-filter
field.
Migrating From Local Jobs
Migration from local jobs is mostly straightforward. Apart from one gotcha the process is as follows:
1. Look at the data that was used to instantiate job definitions by the old local job. Write them down.
2. Ensure that all of the instantiated template data is exposed by exactly one resource. This may be the
commonly-used checkbox device resource job or any custom resource job but it has to be all contained
in one resource. Data that used to be computed partially by the resource and partially by the local
job needs to be computed as additional attributes (fields) of the resource instead.
3. Replace the boilerplate of the local job (typically a cat, here-document piped to run-templates and
filter-templates) with the equivalent template-resource and template-filter fields.
4. Remove the indentation so that all of the job definition is aligned to the left of the paragraph.
5. Re-validate the provider to ensure that everything looks okay.
6. Re-test the job by running it.
The only gotcha is related to step two. It is very common for local jobs to do some additional
computation. For example many storage tests compute the path name of some sysfs file. This has to be
converted to a readily-available path that is provided by the resource job.
EXAMPLES
The following example contains a simplified template that instantiates to a simple storage test. The test
is only instantiated for devices that are considered physical. In this example we don't want to spam the
user with a long list of loopback devices. This is implemented by exposing that data in the resource job
itself:
id: device
plugin: resource
command:
echo 'path: /dev/sda'
echo 'has_media: yes'
echo 'physical: yes'
echo
echo 'path: /dev/cdrom'
echo 'has_media: no'
echo 'physical: yes'
echo
echo 'path: /dev/loop0'
echo 'has_media: yes'
echo 'physical: no'
The template defines a test-storage-XXX test where XXX is replaced by the path of the device. Only
devices which are physical according to some definition are considered for testing. This means that the
record related to /dev/loop0 will be ignored and will not instantiate a test job for that device. This
feature can be coupled with the existing resource requirement to let the user know that we did see their
CD-ROM device but it was not tested as there was no inserted media at the time:
unit: template
template-resource: device
template-filter: device.physical == 'yes'
requires: device.has_media == 'yes'
id: test-storage-{path}
plugin: shell
command: perform-testing-on --device {path}
AUTHOR
Zygmunt Krynicki & Checkbox Contributors
COPYRIGHT
2012-2014 Canonical Ltd