plainbox-job-units - syntax and semantics of Plainbox manifest entry unit type
This page documents the syntax of the plainbox manifest entry units
A manifest entry unit describes a single entry in a manifest
describes the machine or device under test. The purpose of each entry is to
define one specific fact. Plainbox uses such units to create a manifest that
associates each entry with a value.
The values themselves can come from multiple sources, the simplest one is the
test operator who can provide an answer. In more complex cases a specialized
application might look up the type of the device using some identification
method (such as DMI data) from a server, thus removing the extra interaction
Manifest 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.
Following fields may be used by a manifest entry unit.
- (mandatory) - Unique identifier of the entry. This field is
used to look up and store data so please keep it stable across the
lifetime of your provider.
- (mandatory) - A human readable name of the entry. This
should read as in a feature matrix of a device in a store (e.g.,
"802.11ac wireless capability", or "Thunderbolt
support", "Number of hard drive bays"). This is not a
sentence, don't end it with a dot. Please capitalize the first letter. The
name is used in various listings so it should be kept reasonably short.
The name is a translatable field so please prefix it with _ as in
- (mandatory) - Type of value for this entry. Currently two
values are allowed: bool for a yes/no value and natural for
any natural number (negative numbers are rejected).
- (optional) - Units in which value is measured in. This is
only used when value-type is equal to natural. For example a
"Screen size" manifest entry could be measured in
- (optional) - Name of the resource key used to store the
manifest value when representing the manifest as a resource record. This
field defaults to the so-called partial id which is just the
id: field as spelled in the unit definition file (so without the
name space of the provider)
This is an example manifest entry definition:
unit: manifest entry
_name: Thunderbolt Support
To keep the code consistent there's one naming scheme that should be followed.
Entries for boolean values must use the has_XXX
naming scheme. This
will allow us to avoid issues later on where multiple people develop manifest
entries and it's all a bit weird what them mean has_thunderbolt
or whatever we come up with. It's a
convention, please stick to it.
Manifest data can be used to decide if a given test is applicable for a given
device under test or not. When used as a resource they behave in a standard
way, like all other resources. The only special thing is the unique name-space
of the resource job as it is provided by plainbox itself. The name of the
resource job is: 2013.com.canonical.plainbox
. In practice a simple job
that depends on data from the manifest can look like this:
manifest.has_thunderbolt == 'True' and manifest.ns == '2013.com.canonical.checkbox'
imports: from 2013.com.canonical.plainbox import manifest
Note that the job uses the manifest
job from the
name-space. It has to be imported using the
field as it is in a different name-space than the one the
example unit is defined in (which is arbitrary). Having that resource it can
then check for the has_thunderbolt
field manifest entry in the
name-space. Note that the name-space of the
job is not related to the manifest.ns
value. Since any
provider can ship additional manifest entries and then all share the flat
name-space of resource attributes looking at the .ns
attribute is a way
to uniquely identify a given manifest entry.
To interactively collect manifest data from a user please include this job
somewhere early in your test plan:
The manifest file is stored in
. If the provisioning
method ships a valid manifest file there it can be used for fully automatic
but manifest-based deployments.
Zygmunt Krynicki & Checkbox Contributors
2012-2014 Canonical Ltd