NAME

       plainbox-job-units - syntax and semantics of Plainbox manifest entry unit type

SYNOPSIS

       This page documents the syntax of the plainbox manifest entry units

DESCRIPTION

       A  manifest  entry unit describes a single entry in a manifest that 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
       steps.

   File format and location
       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.

   Fields
       Following fields may be used by a manifest entry unit.

       id:    (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.

       name:  (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 _name: Example.

       value-type:
              (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).

       value-units:
              (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 "inch" units.

       resource-key:
              (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)

   Example
       This is an example manifest entry definition:

          unit: manifest entry
          id: has_thunderbolt
          _name: Thunderbolt Support
          value-type: bool

   Naming Manifest Entries
       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
       thunderbolt_supported or tb or whatever we come up with. It's a convention, please stick to it.

   Using Manifest Entries in Jobs
       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:

          unit: job
          id: ...
          plugin: ...
          requires:
           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 2013.com.canonical.plainbox name-space. It has to be
       imported using the imports: 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 2013.com.canonical.checkbox name-space. Note that the name-space  of  the  manifest
       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.

   Collecting Manifest Data
       To  interactively  collect manifest data from a user please include this job somewhere early in your test
       plan: 2013.com.canonical.plainbox::collect-manifest.

   Supplying External Manifest
       The manifest file is stored in $HOME/.local/share/plainbox/machine-manifest.json.   If  the  provisioning
       method  ships  a  valid  manifest  file  there  it  can  be  used  for fully automatic but manifest-based
       deployments.

AUTHOR

       Zygmunt Krynicki & Checkbox Contributors

COPYRIGHT

       2012-2014 Canonical Ltd

0.25                                            January 05, 2016                           PLAINBOX-JOB-UNITS(7)