.. _resultsdb_directive:


resultsdb_directive - send task results to ResultsDB or check YAML correctness
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. versionadded:: 0.4

Send check output to `ResultsDB <https://fedoraproject.org/wiki/ResultsDB>`_.

If reporting to ResultsDB is disabled in the config (`report_to_resultsdb`
option, disabled by default for the development profile), the directive at
least checks whether the check output is in valid :ref:`resultyaml-format` and logs the
details that would have been reported. For this reason, it's useful to use
resultsdb directive always, even when you don't have any ResultsDB server
configured.


Parameters
----------

.. raw:: html

    <table class="rawhtml" border=1 cellpadding=4>
    <tr>
    <th class="head">parameter</th>
    <th class="head">required</th>
    <th class="head">description</th>
    <th class="head">type</th>
    <th class="head">default</th>
    <th class="head">choices</th>
    </tr>
            <tr>
    <td class="bold"><p>results</p></td>
    <td>yes</td>
    <td><p>The output of the check in the ResultYAML format</p></td>
    <td><p>str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
        </table>

Return Values
-------------

YAML formatted output as taken from input, enhanced with result-id's for each
successfully stored result. The result-id information then can be used by
other directives. If reporting to ResultsDB is disabled, the returned YAML
does not contain this extra field.


Exceptions
----------

* :class:`.TaskotronDirectiveError`: if ``results`` is not in a valid YAML
  format, or when  ``item`` or ``type`` are missing in the YAML's result data
* :class:`resultsdb_api.ResultsDBapiException`: for any errors coming from
  the ResultsDB server



Examples
--------


These two actions first run ``run_rpmlint.py`` and export its YAML output to
``${rpmlint_output}``, and then feed this YAML output to ``resultsdb``
directive::

    - name: run rpmlint on downloaded rpms
      python:
          file: run_rpmlint.py
          callable: run
          workdir: ${workdir}
      export: rpmlint_output

    - name: report results to resultsdb
      resultsdb:
          results: ${rpmlint_output}
      export: resultsdb_output

If ResultsDB reporting is configured in the config file, it will get saved on
the ResultsDB server, otherwise only YAML compliance will get checked and some
summary will be printed out into the log, like this::

    [libtaskotron:resultsdb_directive.py:143] 2014-06-24 13:55:27 INFO    YAML is OK.
    [libtaskotron:resultsdb_directive.py:144] 2014-06-24 13:55:27 INFO    Reporting to ResultsDB is disabled.
    [libtaskotron:resultsdb_directive.py:145] 2014-06-24 13:55:27 INFO    Once enabled, the following would be reported:
    [libtaskotron:resultsdb_directive.py:146] 2014-06-24 13:55:27 INFO    <CheckDetail: {'_outcome': 'PASSED',
     'item': 'xchat-2.8.8-21.fc20.x86_64.rpm',
     'keyvals': {},
     'output': '<stripped out>',
     'report_type': 'koji_build',
     'summary': 'RPMLINT PASSED for xchat-2.8.8-21.fc20.x86_64.rpm'}>
    <CheckDetail: {'_outcome': 'PASSED',
     'item': 'xchat-tcl-2.8.8-21.fc20.x86_64.rpm',
     'keyvals': {},
     'output': '<stripped out>',
     'report_type': 'koji_build',
     'summary': 'RPMLINT PASSED for xchat-tcl-2.8.8-21.fc20.x86_64.rpm'}>