Skip navigation
Currently Being Moderated

4.2 Working with Dashboards

VERSION 5  Click to view document history
Created on: Oct 12, 2011 11:51 AM by Zenoss API - Last Modified:  Oct 12, 2011 12:01 PM by Zenoss API

 2. Working with Dashboards

The following sections provide more information about:

 2.1. Viewing a Dashboard

You can view an existing dashboard if you have the proper permissions. By default, the repository includes the /Dashboards folder where dashboards can be saved.

To view a dashboard:

  1. In the Search field, enter the dashboard name, and then click Search.

    The search results appear in the repository.

  2. Click the dashboard name in the list of results. (Alternatively, right-click the name, and then select View from the context menu.)

    Analytics displays the dashboard. When you mouse over a report in the dashboard, controls appear for that report.

To refresh report content, click . Click to open a report in a new window.

When viewing a dashboard with input controls:

  • An input control may appear as a text field, drop-down, check box, multi-select list box, or calendar icon.

  • If one of the frames in a dashboard does not refer to an input control, that frame does not update when you change the input control's value. Only reports that refer to the input control reflect the change.

  • If the dashboard does not include a Submit button, then any changes to the input control's value take effect immediately.


If a dashboard includes a Print View button, then click this to display the dashboard without the Analytics header and footer. Depending on your Web browser, this also opens your browser's Print window.

 2.2. Creating a Dashboard

Any user can create a dashboard, although user permissions in the repository may limit content and save location.

Read the following sections for more information about creating dashboards:

 2.2.1. Overview

A dashboard can include:

  • Reports in the repository

  • Special content, which includes:

    • Custom URL - Any URL-addressable Web content. Analytics dashboards can point to any Web content, so this feature has nearly-limitless possibilities. For example, you might include a frame that points to the logo on your corporate Web site; when that logo changes, your dashboard will automatically update to reflect the branding change.

    • Free Text - Free-form text entry field. Resizing this type of item changes the size of the font in the label. Use free text items to add titles and instructional text to your dashboard.

    • Controls (single or multiple) - If a report on the dashboard refers to input controls or filters, you can add them to the dashboard. When you add a control, Analytics automatically adds a label for it as well. The input control can be mapped to one or more frames. For example, if multiple reports include the same parameter, the corresponding control is automatically mapped to each of those reports when you add the input control to the dashboard. Controls can also be manually mapped to custom URL frames.


    Multiple controls are those used by more than one report. Single controls are those that correspond to parameters included in a single report.

  • Standard controls, which include:

    • Submit - Applies the values in the dashboard's input controls to the reports that refer to each input control. Analytics refreshes these reports to display the new set of data. If the dashboard does not include a Submit button, then changes to input control values are reflected immediately.

    • Reset - Resets the values of the input controls to the last value selected when the dashboard was saved.

    • Print View - Displays the dashboard without buttons or Analytics' header and footer, and (depending on your browser) opens your browser's Print window.

    • Text Label - Label for an input control. When you add an input control to the dashboard, Analytics automatically adds a text label for it. Resizing this type of item changes only the size of the label; the font size in the label is fixed.

 2.2.2. Creating a Simple Dashboard

To create a simple dashboard:

  1. From the Analytics interface, select Create > Dashboard.

    The dashboard designer appears.

  2. In the Available Content area, navigate to and select the item you want to add to the dashboard.

  3. Select Add to Dashboard.


    Figure 4.1. Add Content to Dashboard

    Add Content to Dashboard

    The content is added to the dashboard.

  4. Hover over the bottom of the right edge of the frame containing the content. When your cursor changes to a resizing icon, click and drag the edge of the frame to resize it as desired.


    Analytics allows you to save a dashboard even if its contents "hang over" the edge of the dashboard area. This is because the dashboard area is meant as a guide. If the content fits in the dashboard area, then you can be sure that any viewer will be able to view the dashboard without using scroll bars. For more information, see the section titled "Screen Sizes."

  5. Click Save to save the dashboard.

    Analytics prompts for the name and save location. By default, the dashboard is saved in the /Dashboards folder with the name "New Dashboard." Enter a name and location, and then click Save.

    Analytics saves the dashboard to the repository.

 2.2.3. Adding Controls to a Dashboard

Reports refer to input controls that determine the data they return. You can add those controls to a dashboard:

  1. Open a dashboard in the dashboard designer.

  2. In the Available Content area, expand Special Content, and then expand Single Report Controls.

    The input controls associated with the report in the dashboard are listed.

  3. Click an input control, and then select Add to Dashboard.

    The input control is added, by default, above the report.


    You can select and drag one or more input controls and input control labels to any location on the dashboard.

  4. Click Save to save the dashboard.

 2.2.4. Adding a Custom URL to a Dashboard

You can create a frame that displays any URL-addressable content. Such mashups can help you leverage data from many sources in a single, integrated view.

To add a custom URL to a dashboard.

  1. Open the dashboard in the dashboard designer.

  2. In the Available Content list, select Custom URL (in the Special Content folder), and then drag it to the dashboard.

    Analytics prompts you to enter the URL of the Web page you want the frame to display.

  3. Optionally, select control values to pass to the URL.


    For example, suppose you want to include the URL to in your dashboard, and further want it to display the news for a particular country. In this case, you would select the Country option, and then enter "q" in the URL Parameter name field. This maps the dashboard's Country input control to Google's q (query) parameter. Then, when you select a value in the Country input control, Analytics passes that value to so that the news displayed in the frame relates to the selected country.

  4. Click OK to close the custom URL dialog.

  5. Optionally, click the custom URL frame, and then select Auto-refresh Interval from the context menu.

    The menu expands to display options for how frequently Analytics will refresh the frame's content. Smaller values update the frame more frequently. By default, a frame is never automatically refreshed (Auto-refresh Interval is set to Manual Only).

  6. Select a value, and then click Save.

    The dashboard is saved to the repository.

 2.2.5. Refining Dashboard Layout

When your overall layout is complete, you can refine the look and feel of your dashboard.

To refine dashboard layout, you can:

  • Reduce unused space in the dashboard. Draw a selection rectangle around all of the dashboard frames, and then drag one or more frames.

  • Remove unwanted buttons. Hover over the button, and then click it when the hover border appears. From the context menu, select Delete Item.

  • Reposition buttons.

  • Add and edit title text. In the dashboard selector, select Add Title Text from the context menu.

 2.2.6. Dashboard Design Tips

When you are creating or editing a dashboard, keep these tips in mind:

  • You can drag items from the Available Content list and drop them to add them to the dashboard, or use the Available Content context menu Add to Dashboard option.

  • Press the Ctrl key while dragging or resizing items and frames for smoother cursor movement. This disables the default snap-to-grid behavior.

  • Use Ctrl-Click to select multiple frames and items in the dashboard area.

  • Click the Hide Content icon to hide the Available Content list. Display it again by clicking the Show Content icon.

  • Use the Hide Scroll Bars options on the frame context menu when you can size the frame to exactly match its content. This is especially helpful for charts and small crosstabs.

  • The context menu changes depending on your selection. For example, it might include the Delete Item or Delete Frame option, depending on whether you selected a button or a frame. If you select multiple items or frames, the context menu only includes options that apply to all the selected items. For example, if you select a frame and a button, the context menu only includes the Delete Items option; when you select multiple frames, the context menu includes several options that can apply to frames, such as Hide All Scroll Bars and Auto-refresh Interval.

  • You can use the arrow keys to move selected content one grid space at a time. Press the Ctrl key to move the selected content a single pixel at a time.

  • You cannot resize buttons or input controls.

  • When you delete a report with input controls from the dashboard, the controls are also deleted, but their labels remain. Delete them manually. If a custom URL frame is mapped to one of the input controls that was deleted, Analytics shows the default URL without passing the parameter.

  • Drag an item from the Available Content list and drop it on an existing frame to replace the existing content.

  • To create a new version of a dashboard, open it in the designer and click Save As on the Dashboard Selector context menu.

  • A dashboard can include other dashboards, so long as this does not create a circular dependency. Put another way, you cannot add a dashboard to itself.

  • If a report displayed in a dashboard is moved to a new location in the repository or if it is deleted entirely, it is deleted from the dashboard.

  • Select multiple frames to change their sizes all at once. When you drag the edge of one frame, the other frames change size as well.

  • The dashboard designer may seem unwieldy if you design for a screen size as big as or larger than your own; in particular, horizontal scrolling can be awkward. Try hiding the content pane, or using a larger monitor. You can also design the dashboard for your resolution, and then select Use Proportional Sizing from the Dashboard Selector context menu.

  • Not all Web pages support the technology underlying Analytics' dashboards (IFrame). In such cases, the URL frame's behavior may be inconsistent.

  • By default, Analytics assumes that you want to use the HTTP protocol for custom URL frames. However, you can specify that it use the FILE protocol by entering file:// at the beginning of the value in the URL. In this case, Analytics uses the FILE protocol, and looks for the file you specify in the WEB-INF directory. This is helpful for including images.

  • If you have multiple reports that refer to the same input control, but you do not want them to be controlled by a single input control, create two dashboards that each refer to the input control; then create a dashboard that includes those dashboards. Now, users can set the input controls separately for each set of reports.

 2.2.7. Screen Sizes

When you create a dashboard, you can set the screen size to change the dashboard area to match a particular screen resolution. For example, if you are designing a report for end users who use laptops that only display a screen resolution of 800 by 600 pixels, you can set the dashboard area to 800 by 600 pixels to emulate your end users’ screen size.

By default, the dashboard designer supports five standard screen resolutions, which are available under the Screen Size option in the Dashboard Selector context menu. When a dashboard uses fixed sizing, its frames do not resize automatically when the window size changes.

In addition to fixed screen resolutions, dashboards support proportional sizing, which calculates frame sizes using percentages of the total window size, rather than using fixed values. Put another way, when a dashboard uses proportional sizing, its frames resize relative to the size of the browser window. Note that frames do not resize automatically in the designer; proportional sizing is only evident in the end user's view of the dashboard, or when you select a new screen size in the designer.

If a dashboard that uses proportional sizing is bigger than the specified screen size, when the dashboard is viewed, Analytics resizes the frames so that they all appear in the window without requiring the user to use the browser's scroll bars. This may result in a change to the shape of the frames.


Zenoss recommends that you design dashboards using fixed sizing mode. Then, switch to proportional sizing before you save.

In proportional sizing:

  • You can resize free text items to a smaller size, but you cannot make them bigger.

  • The grid turns red when any content hangs over the edge of the dashboard area.

 2.3. Editing a Dashboard

To edit a dashboard:

  1. Select View Repository, and then search for or browse to the dashboard you want to modify.

    By default, the repository includes the /Dashboards folder where you can store your dashboards.

  2. Right-click the dashboard and select Open in Designer... from the context menu.

    The designer appears and displays the dashboard.

  3. Edit the dashboard by adding, removing, resizing, or dragging content.

    For more information about working with dashboard content, see the section titled "Creating a Dashboard."

  4. To save the dashboard, click Save. To create a new version of the dashboard, select Save As from the Dashboard Selector context menu, and then specify a new name.

 2.4. Designing Reports for Dashboards

When defining reports for a dashboard, keep in mind:

  • Charts and small crosstabs are best suited to dashboards. However, you can design table reports that work well in the dashboard. Such reports tend to be very narrow and typically refer to input controls to limit the number of rows they return.

  • The reports should be small, since dashboards typically contain multiple reports. In particular, your reports should not be too wide, as horizontal room is always at a premium in a dashboard.

  • When an Ad Hoc report is displayed on a dashboard, its margins are stripped. You do not need to strip the margins manually when designing the report.

  • If you want a single input control on the dashboard to control the data displayed in multiple reports, the reports themselves need parameters with the same name as the input control. For example, you might have a query-based list of employee names that can be used in both sales reports and human resources report. When defining a parameter in a report, give it a meaningful name that can be reused in other reports. Then, when two reports that include this parameter are added to the dashboard, their input controls appear as Special Content in the Available Content list.

    Storing such input controls in the repository encourages their reuse when reports are designed and added to the repository.

  • If a report's input control is set to display as a radio button set, it is instead displayed as a list of options.

  • If you want to pass a value to an external URL, the URL Parameter Name you specify for the input control must match the name of a parameter that URL can accept. In addition, the value of the input control must also be a value the URL can accept. Beyond these requirements, the target URL is likely to have requirements and limitations. For example, the name of the parameter may be case sensitive; in this case, the value you enter in the URL Parameter Name field is also case sensitive.

    The input control must pass data that the URL can accept. Otherwise, Analytics may not be able to retrieve the correct data from the external URL.

Comments (0)