.. _interact:

How to Interact with the DQR
====================================================================================================

Once the DQR is generated for a particular event, analysts still need to review and approve it.
In the future, this step may also be completely automated and the DQR will be autonomous. 
However, we are not there yet and several, if not most, technical solutions will only return the `human_input_needed` state.
These must be resolved by an analyst before the DQR is complete for that event.

Currently, analysts interact with the DQR via a command-line client (`dqr-interact`).
This client requires the analyst to specify exactly what they'd like to do (either `comment` or `override`) along with specifications of what should be uploaded.
A simple Python library then formats the result in a standardize JSON structure and uploads it to GraceDb, from which the DQR detects and parses the contents into the html format.
In this way, analysts can resolve `human_input_needed` states or correct other automatically reported states, and comment on existing data quality products in GraceDb.

Currently, we support two forms of interaction with the report.
Both use the same executable: `dqr-interact`, which requires users to specify the GraceID and taskname (name of the technical solution) they'd like to interact with.
Tasknames can be read off of the DQR html as the name contained in the collapsible banner for each technical solution (`dqr-interact` will remove all spaces from the task name for you, but you can do that for yourself if desired).

**See also:** :ref:`executables`.

Override
----------------------------------------------------------------------------------------------------

**Override** means an analyst changes the state of an automatically produced technical solution. 
This could be to resolve `human input needed` states or to change a `pass/fail` state, however the former will likely be the most common.

When an analyst overrides an existing state, their name, the date, and some other basic information is recorded along with the new state.
This serves as record-keeping of who made what decision and when.
Analysts should also comment on to explain why they made the decision they did, although this is not strictly required.

Note, analysts can `override` eachother, and it only the most recent `override` that is reflected in the DQR's html.

**Example use cases are provided in** :ref:`executables`.

Comment
----------------------------------------------------------------------------------------------------

Analysts may wish to comment on a particular technical solution.
For example, when they resolve a `human input needed` state they will want to explain their reasoning.
Comments will be rendered in the DQR's html in the order in which they're uploaded, but the full conversation will be preserved and presented for each technical solution.

**Typical** `comment` **command-lines are provided in** :ref:`executables`.
Note, we expect `comments` for all `override` annotations but this is not strictly required.