.. _addons_metabase: ********* Metabase ********* .. important:: Metabase replaces SpagoBI for business intelligence and reporting in XiVOCC installations. SpagoBI technology is no longer actively maintained in its open-source version and has been deprecated starting with Maia (2024.05). Introduction ============ Metabase is an open-source business intelligence and data visualization tool that provides interactive dashboards and reports for XiVOCC contact center statistics. It connects to the **xivo_stats** database to provide real-time and historical reporting capabilities. The Metabase integration includes: - Pre-configured dashboards and reports for queue and agent statistics - Interactive data exploration tools - Scheduled report delivery via email - LDAP authentication support - Custom report building capabilities Installation ============ .. note:: Installation requires the **xivocc-metabase** package on your XIVOCC system. Itself requires specific docker access. If you don't have those, contact the XiVO team. Install the Metabase package: .. code-block:: bash apt-get install xivocc-metabase This installation will: - Add the Docker override ``10-docker-metabase.override.yml`` in ``/etc/docker/compose``, which defines the ``metabase`` service plus the one-shot ``metabase-setup``, ``metabase-reports`` and ``metabase-serializer`` services (gated behind the ``metabaseInit`` Compose profile) - Create the Metabase PostgreSQL database and user - Generate the Metabase DB password and store it in ``/etc/docker/compose/custom.env`` - On first install only, store the admin credentials and import log level in ``/etc/docker/compose/custom.env`` (``METABASE_ADMIN_USERNAME``, ``METABASE_ADMIN_PASSWORD``, ``METABASE_IMPORT_LOGLEVEL``) - Start the Metabase container, automatically complete the first-run setup (admin user + ``xivo_stats`` database connection) and import the pre-configured reports Accessing Metabase ================== * Metabase is available * From the fingerboard under Statistics ``https://XIVOCC_IP/fingerboard`` * Directly Access the Metabase instance at ``https://XIVOCC_IP/reporting`` * Under port `3000`` in the machine (XiVOCC) holding the metabase container. * Log in * with the admin credentials. Retrieve them from ``/etc/docker/compose/custom.env``: .. code-block:: bash grep METABASE_ADMIN /etc/docker/compose/custom.env * With LDAP credentials if the connection has been made. See :ref:`ldap authentication ` (Re-)Importing Pre-configured Reports ===================================== Pre-configured dashboards and reports are bundled in the ``xivoxc/metabase-reports`` image and imported automatically during installation into the **Rapports exemples** collection. .. _metabase_import_reports: Re-running the Import --------------------- To re-run the setup and import (for example after updating the reports image), trigger the ``metabaseInit`` profile: .. code-block:: bash xivocc-dcomp --profile metabaseInit up metabase-setup metabase-reports metabase-serializer This runs three one-shot containers in order: #. ``metabase-reports`` — copies the report definitions into the ``metabase-reports-data`` Docker volume #. ``metabase-setup`` — waits for Metabase to be healthy, then completes the first-run wizard if it has not been done yet (idempotent: it exits cleanly if Metabase is already set up) #. ``metabase-serializer`` — waits for the ``xivo_stats`` schema sync to complete, then imports the cards and dashboards All three containers exit on their own once finished. Pre-configured Reports ====================== The default report collection includes: **Queue Statistics Reports:** - Queue performance metrics (answered, abandoned, timeout calls) - Average wait time and call duration - Service level metrics - Call distribution by answer type **Agent Reports:** - Agent activity (login, pause, wrap-up time) - Incoming and outgoing calls per agent - Agent performance metrics - Call handling statistics For detailed information about the statistics model and database schema, see :ref:`pack_reporting`. Advanced Configuration ====================== Email Notifications ------------------- Metabase supports scheduled report delivery via email. To configure email: #. Access Metabase as admin #. Go to **Settings** > **Email** #. Configure your SMTP server settings For detailed email configuration instructions, see the official Metabase documentation: `Metabase Email Configuration `_ .. _metabase_ldap_authentication: LDAP Authentication ------------------- For enterprise deployments, you can configure LDAP authentication to use your existing directory service: #. Access Metabase as admin #. Go to **Settings** > **Authentication** #. Configure LDAP settings For detailed LDAP configuration instructions, see the official Metabase documentation: `Metabase LDAP Authentication `_ External Resources ================== - `Metabase Official Documentation `_ - `Metabase Email Setup Guide `_ - `Metabase LDAP Authentication Guide `_ - XiVO Statistics Database Schema: :ref:`pack_reporting` Troubleshooting =============== First follow metabase logs .. code-block:: bash xivocc-dcomp logs -f metabase Connection Issues ----------------- If Metabase cannot connect to the database: - Verify the database credentials in the connection string - Check that the ``xivo_stats`` database exists and is accessible - Ensure the Docker compose stack is running: ``xivocc-dcomp ps`` Import Issues ------------- Try to reimport with more precise ``METABASE_IMPORT_LOGLEVEL``, see :ref:`metabase import ` Uninstall --------- .. code-block:: bash apt purge xivocc-metabase Admin Password Reset -------------------- Consult XiVO support for assistance with password recovery.