Dashboard Sharing – The Hard Way

<?php

use Icinga\Authentication\Auth;
use Icinga\Authentication\Role;

/** @var \Icinga\Application\Modules\Module $this */

/*
 * Tutorial: Creating Dashboards and Dashlets
 *
 * This section demonstrates the typical pattern for creating dashboards and dashlets.
 *
 * First, create or retrieve a dashboard by its title.
 * Use the `N_` function to mark the title for translation. Note that `N_` does not translate immediately;
 * it only marks the string so it can be translated when the dashboard is displayed.
 * The dashboard title acts as an identifier, so it is not translated at this stage.
 *
 * You can extend dashboards provided by other modules, or create new ones if they don't exist yet.
 * In this example, we create a new dashboard titled "My Incidents", assuming no other module provides it.
 */
$myIncidents = $this->dashboard(N_('My Incidents'), ['priority' => 1]);
/*
 * Choose a variable name that reflects the dashboard's purpose, as you'll use this variable to add dashlets later.
 * The 'priority' option determines the order in which dashboards appear in the tabs:
 * lower values are listed first. If multiple dashboards share the same priority, they are sorted alphabetically by title.
 */

/*
 * Next, add dashlets to your dashboard.
 * For each dashlet, specify a title, a URL, and a priority.
 * You can build the desired URL interactively in Icinga Web and then copy it here.
 * To optimize the dashlet display, append the following parameters to your URL:
 *   - `limit`: sets the maximum number of items shown
 *   - `view=minimal`: displays each item in a single line for a compact view
 */
$myIncidents->add(
    N_('Database Issues'),
    'icingadb/services?service.state.is_problem=y&service.vars.application=db&sort=service.state.severity desc&limit=20&view=minimal',
    1
);

$myIncidents->add(
    N_('Storage Issues'),
    'icingadb/services?service.state.is_problem=y&service.vars.application=storage&sort=service.state.severity desc&limit=20&view=minimal',
    2
);

/*
 * Extending Dashboards from Other Modules
 *
 * You can add dashlets to dashboards defined by other modules. For example, the "Current Incidents" dashboard is provided by Icinga DB.
 * When retrieving an existing dashboard, omit the priority option to preserve the original priority set by the providing module.
 */
$currentIncidents = $this->dashboard(N_('Current Incidents'));

$myIncidents->add(
    N_('Apache Issues'),
    'icingadb/services?service.state.is_problem=y&service.vars.application=apache&sort=service.state.severity desc&limit=20&view=minimal',
    1
);

/*
 * Creating Dashboards Based on User Groups and Roles
 *
 * This section shows how to display dashboards conditionally, depending on the authenticated user's group or role memberships.
 * The following code only runs if a user is logged in.
 */
if (($user = Auth::getInstance()->getUser()) !== null) {
    // Retrieve all groups the user belongs to for easy reference.
    $groups = $user->getGroups();

    /*
     * Example: Show a dashboard only to users in a specific group.
     */
    if (in_array('groupName', $groups)) {
        $groupIncidents = $this->dashboard(N_('Group Incidents'), ['priority' => 20]);

        // Add dashlets to this dashboard as needed.
    }

    /*
     * You can combine group checks for more complex conditions.
     * For example, show a dashboard only if the user is in both group A and B, but not in group C:
     */
    if (in_array('groupA', $groups) && in_array('groupB', $groups) && ! in_array('groupC', $groups)) {
        $groupIncidents = $this->dashboard(N_('Group Incidents'), ['priority' => 20]);

        // Add dashlets here.
    }

    /*
     * Or, show a dashboard if the user is in either group A or group C:
     */
    if (in_array('groupA', $groups) || in_array('groupC', $groups)) {
        $groupIncidents = $this->dashboard(N_('Group Incidents'), ['priority' => 20]);

        // Add dashlets here.
    }

    /*
     * You can apply the same logic to roles.
     * First, extract the role names from the user's roles for easier checking.
     */
    $roles = array_map(fn(Role $role): string => $role->getName(), $user->getRoles());

    /*
     * Example: Show a dashboard only to users with a specific role.
     */
    if (in_array('roleName', $roles)) {
        $roleIncidents = $this->dashboard(N_('Role Incidents'), ['priority' => 20]);

        // Add dashlets here.
    }

    // Continue with additional group or role-based dashboard logic as needed.
}