.. Reminder for header structure:
  Parts (H1)          : #################### with overline
  Chapters (H2)       : ******************** with overline
  Sections (H3)       : ====================
  Subsections (H4)    : --------------------
  Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^
  Paragraphs (H6)     : """"""""""""""""""""
 
.. meta::
  :description: WAPT documentation version 2.7 Quickstart - Installing the WAPT Agent
  :keywords: Quickstart, WAPT, waptwua, wua

.. role:: red
   :class: red-text

.. _quickstart_reporting:
 
#################################################
Quickstart - Reporting Setup |enterprise_feature|
#################################################

.. hint::
 
  This page is a quickstart tutorial to get started with the WAPT Reporting module. For complete and detailed documentation (database structure, external PostgreSQL connection, Grafana dashboards, etc.), refer to the :ref:`wapt_reporting` page.
 
.. note::
 
  Reporting is a feature of **WAPT Enterprise**. Please ensure you have the correct licence before starting this tutorial.
 
********
Overview
********

The WAPT Reporting module lets you write your own SQL queries against your fleet's database, and display the results directly within the WAPT Console.

No one knows better than you what information you need. Reporting allows you to, for example:
 
* List the machines on which a given piece of software is installed (even if it was not deployed through WAPT);
* Identify hosts that haven't been seen for a while;
* Obtain statistics about your fleet (breakdown by OS, by machine type, etc.);
* Create dynamic filters in the ``Inventory`` tab, based on the results of your queries.
 
.. note::
 
  The WAPT PostgreSQL database is accessed in **read-only** mode from the Reporting module: your queries can therefore never modify, delete, or insert data. You can test freely without any risk of damaging your fleet.

 
********************************
How to import and create queries
********************************
 
Import an existing query
========================

.. tab-set::

  .. tab-item:: From a URL

    Go to ``Reporting`` tab :red:`(1)` → ``Import queries…`` :red:`(2)` → ``From URL`` :red:`(3)`. This allows you to retrieve ready-to-use queries from the Tranquil IT repository.

    .. figure:: wapt-resources/quickstart-import_from_URL.png
      :scale: 75%
      :align: center
      :alt: Menu option import from URL

    To begin, select the query ``Free space per computer`` :red:`(1)` → click on ``Import selected queries`` :red:`(2)`

    .. figure:: wapt-resources/quickstart-import_selected_queries.png
      :scale: 75%
      :align: center
      :alt: Import selected queries

    The request will appear in the console and run automatically, you can save this query by clicking on :kbd:`Save`. :red:`(1)`

    .. figure:: wapt-resources/quickstart-URL_query_save.png
      :scale: 50%
      :align: center
      :alt: URL queriy save

    Enter a query name (or keep the suggested name) :red:`(1)` and click :kbd:`OK` :red:`(2)`.

    .. figure:: wapt-resources/quickstart-input_query_name.png
      :scale: 75%
      :align: center
      :alt: Menu option input query name

  .. tab-item:: From a file

    To begin with, we're going to create a file in .json format, which we'll call: **inactive_hosts_8d.json**.

    .. white_toggle::
        :titleen: content of file inactive_hosts_8d.json
        :titlefr: contenu du fichier inactive_hosts_8d.json

        .. code-block::

          [
              {
                  "id": 17,
                  "name": "Inactive hosts 8d",
                  "query": "SELECT\n    uuid,\n    computer_name,\n    last_seen_on\nFROM hosts\nWHERE TO_TIMESTAMP(last_seen_on, 'YYYY-MM-DD') < CURRENT_TIMESTAMP - INTERVAL '8 days'\nORDER BY last_seen_on;",
                  "settings": {
                      "columns": [
                          {
                              "text": "uuid",
                              "width": 250,
                              "visible": true,
                              "position": 0,
                              "propertyname": "uuid",
                              "chartsettings": ""
                          },
                          {
                              "text": "computer_name",
                              "width": 200,
                              "visible": true,
                              "position": 1,
                              "propertyname": "computer_name",
                              "chartsettings": ""
                          },
                          {
                              "text": "last_seen_on",
                              "width": 150,
                              "visible": true,
                              "position": 2,
                              "propertyname": "last_seen_on",
                              "chartsettings": ""
                          }
                      ],
                      "sortcolumn": 2,
                      "sortdirection": 1
                  }
              }
          ]

    Once you have created it, return to the WAPT console.

    Go to ``Reporting`` tab :red:`(1)` → ``Import queries…`` :red:`(2)` → ``From a file`` :red:`(3)`, then select the file.

    .. figure:: wapt-resources/quickstart-import_from_file.png
      :scale: 75%
      :align: center
      :alt: Menu option import from file

    Select the :file:`inactive_hosts_8d.json` :red:`(1)` file from the directory where it was created, by clicking on :kbd:`Open` :red:`(2)`.

    .. figure:: wapt-resources/quickstart-select_query_file.png
      :scale: 75%
      :align: center
      :alt: Select query file

    Import the query by selecting it :red:`(1)` and then clicking on ``import selected queries`` :red:`(2)`:

    .. figure:: wapt-resources/quickstart-import_selected_queries_from_file.png
      :scale: 75%
      :align: center
      :alt: Menu option import selected queries from file

    Click to the new tab call: Inactive hosts since 8 days. :red:`(1)` and save it :red:`(2)`.

    .. figure:: wapt-resources/quickstart-save_query.png
      :scale: 75%
      :align: center
      :alt: Menu option save query

    Enter a query name :red:`(1)` and click :kbd:`OK` :red:`(2)`.

    .. figure:: wapt-resources/quickstart-input_query_name.png
      :scale: 75%
      :align: center
      :alt: Menu option input query name

Once the query is created, it appears in the left panel :red:`(1)`. To rerun a query, simply click the :kbd:`Execute` button. :red:`(2)`
You have now tested importing queries via URL or file.

.. figure:: wapt-resources/quickstart-queries_from.png
  :scale: 75%
  :align: center
  :alt: Menu option input query name

Créer sa première requête
=========================
 
To begin, go to ``Reporting`` tab :red:`(1)` → ``New query`` :red:`(2)`. A new tab opens called**New query** :red:`(3)`.

.. figure:: wapt-resources/quickstart-new_queries.png
  :scale: 75%
  :align: center
  :alt: Create new query

We're going to enter the following content into this new query:

.. code-block::
    
  SELECT
      computer_name,
      os_name,
      uuid,
      os_version
  FROM hosts
  WHERE os_name LIKE 'Windows 11%%'

The purpose of this query is to list all machines in the fleet that are running Windows 11.

Then, save the query :red:`(1)`, give it a name :red:`(2)`, and click OK :red:`(3)`.

.. figure:: wapt-resources/quickstart-new_queries_save.png
  :scale: 75%
  :align: center
  :alt: save new query

Once the query is created, it appears in the left panel :red:`(1)`. To rerun a query, simply click the :kbd:`Execute` button. :red:`(2)`

.. figure:: wapt-resources/quickstart-queries_from(2).png
  :scale: 75%
  :align: center
  :alt: Menu option input query name

*****************
Using the results
*****************
 
Result in the query window
==========================
 
The result is displayed directly in the query window. You can:
 
* export it to a spreadsheet (:guilabel:`Export to spreadsheet` button, generates a *.csv* file);
* duplicate it, share it, or export it to a file to hand off to a colleague.

Creating a filter in the Inventory tab
======================================
 
You can turn a query into a dynamic filter in the Inventory tab, to directly display the machines matching it.
 
1. Make sure your query returns a column identifying each machine (typically ``host_id`` or ``uuid``). :red:`(1)`
2. In the query result, right-click that column, then click :guilabel:`Choose as Host UUID`. :red:`(2)`
3. Save the query. :red:`(3)`

.. figure:: wapt-resources/quickstart-create_filter_query.png
  :scale: 75%
  :align: center
  :alt: create filter query

4. Go to the Inventory tab :red:`(1)`, check ``More options`` :red:`(2)` in the panel, then select your query in the filter :guilabel:`SQL query` field. :red:`(3)`.

.. figure:: wapt-resources/quickstart-display_filter_query.png
  :scale: 75%
  :align: center
  :alt: display filtrer query

You now have a dynamic list of machines, based on the result of your query.
 
*************
Going further
*************
 
This page only covers getting started with Reporting. The complete documentation (:ref:`wapt_reporting`) covers, among other things:
 
* setting up :ref:`Grafana dashboards connected to the WAPT database <grafana>`, for a visual overview of your fleet;
* :ref:`normalizing software names <normalizing_software_names>`, to group under a single name software that appears differently depending on its version or architecture, making your version-tracking queries more reliable;
* More query examples (machines by chassis type, most installed software, machines not seen for a long time, etc.).

