Customizing the Home Page




The layout of the web client home page has been enhancement using widgets and dashboard. Widgets are building blocks in the form of charts, tables, and graphs. Single or multiple widgets can be associated to a dashboard to form a custom dashboard. This section of the document provides details on constructing the home page with widgets and dashboards from scratch. A set of dashboards can be configured to be displayed in a slide show using the CCTV functionality. These features makes the home page a very powerful user-friendly interface to display the all important network monitoring data at first glance on web client startup.



Procedure for Customization


The primary task in creating a custom dashboard is to create the widgets that are to be associated to the Dashboard. Next, the dashboards must be created. And as the last step, the required widgets must be associated to the dashboard. The three basic steps involved in the complete customization of the Home Page is given below:

Creating a Widget


Custom Widgets can be created based on user requirement. Each widget manipulates the data in the desired form to the user. Widget APIs are available to add, modify, and delete Widgets. The following are the steps involved in creating a Widget and associating the Widget to a Dashboard.

      1. Creating the JSP file

      2. Configuring the STRUTS-CONFIG file

      3. Writing a class implementing the DataSource

      4. Configuring in Widget.xml file

Creating the JSP File


The first step to creating Widgets is to create the new JSP page to display the data. The following example code snippet can be used for creating the Widget.


    <%@ taglib uri="http://jakarta.apache.org/struts/tags-tiles" prefix="tiles" %>

    <%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %>


    <table width="97%" cellspacing="0" cellpadding="3" border="0" align="center" style="margin-top: 7px; margin-bottom: 7px;">


     <td nowrap="" valign="middle" align="center" class="configParams" style="padding-left: 10px;">

    <div style="padding: 3px; text-align: center;">

    <a href=#" class="bluelink boldTxt"></a> New widget Added. Customize this JSP for your requirement.







      • Save this file under the jsp directory of a specific module e.g. <NMS_Home>/webclient/<module-name>/jsp/ directory.

      • If you have not configured Web NMS web client for Dynamic Compilation, you need to run the compileJSP.bat file present in <Web NMS Home>/bin folder to compile the newly created JSP file.


Configuring the STRUTS-CONFIG file


Configure the <NMS_Home>/webclient/common/conf/struts-config.xml and <NMS_Home>/webclient/home/conf/home-struts-config.xml file for the newly added widget such that the returning mapping.findForward value has an appropriate <forward> tag associated. Provide the jsp path inside the "/generateWidgets" action path.

      • Example entry in <NMS_Home>/webclient/common/conf/struts-config.xml


    <action path="/generateWidgets" type="com.adventnet.nms.webclient.common.GenerateWidgetAction">



    <forward name="newPage" path="/webclient/common/jsp/newPage.jsp"/>



      • Example entry in <NMS_Home>/webclient/home/conf/home-struts-config.xml


<action path="/generateWidgets" type="com.adventnet.nms.webclient.common.GenerateWidgetAction">



<forward name="newPage" path="/../webclient/common/jsp/newPage.jsp"/>





Writing the Class Implementing DataSource


Write a class implementing the interface com.adventnet.nms.webclient.common.DataSource. The business logic must be written here to fetch the data to be shown in the widget jsp page. The parameter passed to this method (com.adventnet.nms.webclient.home.WidgetParams) will contain the instance of request and response that is passed to the Action class.


The com.adventnet.nms.webclient.common.DataSourceResponse object to be returned from this method has the variable (forward) to set the value for the mapping.findForward option. This value will be used to forward the response to the appropriate page as specified in the struts-config.xml file.



    package com.adventnet.nms.webclient.home.widgets;


    import com.adventnet.nms.webclient.home.DataSource;

    import com.adventnet.nms.webclient.home.DataSourceResponse;

    import javax.servlet.http.HttpServletRequest;

    import javax.servlet.http.HttpServletResponse;

    import javax.servlet.http.HttpSession;

    import com.adventnet.nms.webclient.home.WidgetParams;


    public class NewPageDS implements DataSource


    public DataSourceResponse generateWidgetData(WidgetParams params)


    // TODO Auto-generated method stub

    DataSourceResponse dataSrcResponse = new DataSourceResponse();

    dataSrcResponse.forward="newPage";//No i18n

    return dataSrcResponse;




      • Compile the above class and place it in the WEB-INF/classes directory. The above code snippet simply forwards the request call to the jsp mapped in the struts-config.xml file.

Configuring in Widget.xml File


Provide an entry for the new widget in the Widgets.xml file present under <NMS_Home>/conf directory as given below. Widget details are read  from <Web NMS Home>/conf/Widgets.xml file and updated in the database when the server is restarted. On consecutive warm start of the server, only the entries present under the <APPEND> tag will be updated into the database.


    //Adding a Widget



    <WIDGETDATASOURCE CLASSNAME="com.adventnet.nms.webclient.home.widgets.NewPageDS" NAME="Example" DESCRIPTION="New Widget Datasource" DATASOURCE_ID="201"/>



  1. //Adding a Widget with Widget Criteria



    <WIDGET DATASOURCE_ID="201" WIDGET_ID="3001" NAME="Example Widget" DESCRIPTION="Example One" CRITERIA_ID="20"/>


    <PROPERTY NAME="source" VALUE="test"/>





Note: It must be ensured that a widget data source entry for the corresponding DATASOURCE_ID exists.




Note: In-case of an error in the entries within the <APPEND> tag, an error message will be printed in the logs and will proceed to the next entry in the file. Only proper entries within the <APPEND> tag that were inserted into the database will be moved to the corresponding tags in the file. And the wrong entries will remain unmodified. (i.e under the <APPEND> tag).


      • After making the above configurations, restart the server.

Creating a Dashboard


The Dashboards can be created by using the available APIs or providing the dashboard entries in the Dashboard.xml file.


Using API


The addDashboard(userName, dashboardName, description) can be used to create a new dashboard.


    //API :This is used to add the dashboard.

    long dashboardId = HomePageAPI.getInstance().addDashboard(userName,dashboardName, description);


Using XML file


On every user login after cold start of the server, the dashboard details are read from the <Web NMS Home>/users/<user-name>/Dashboards.xml or <Web NMS Home>/html/defaultToAllUsers/Dashboards.xml  file and the details updated in the database. Here, the user based Dashboards.xml file present in the <user-name> directory takes precedence.


On consecutive client logins the Dashboards.xml file is read, and the entries present under the <APPEND> tag will be updated into the database and the dashboard constructed.



    <DASHBOARD COLUMNS_WIDTH="30:35:25" NAME="Example" DESCRIPTION="Example dashboard"/>

    <WIDGETASSOCIATION COLUMN_ID="1" DASHBOARD_NAME="Example" DESCRIPTION="Associated example widget" LEVEL="1" NAME="Test Widget" WIDGET_ID="3001"/>




Associating a Widget to a Dashboard


Using API


The associateWidget(dashboardId, widgetId, name,criteriaProps , description; can be used to associate a widget to a dashboard.


    //API :This is used to add the dashboard.

    long dashboardId = HomePageAPI.getInstance().associateWidget(dashboardId, widgetId, name,criteriaProps , description);



Deassociating a Widget from a Dashboard


A widget that is associated to a dashboard can be de-associated using the deAssociateWidget(associationId, dashboardId) method.



    //API :This is used to de-associate the widget from the dashboard.

    boolean result = HomePageAPI.getInstance().deAssociateWidget(associationId, dashboardId);



Associating a Dashboard to a Tree Node


A Dashboard can be associated to a tree node to display widgets related to a specific module. For example, a fault specific dashboard can be created to display a dashboard with fault related widgets on clicking on this tree node. To achieve this, entries must be added in the Tree.xml and Dashboards.xml files.


Provide an entry for the tree node in Dashboards.xml as follows:


    <DASHBOARD COLUMNS_WIDTH="30:40:30" NAME="Fault Dashboard" DESCRIPTION="Overview" IMAGE="/webclient/home/images/overview.gif" TREENODE_ID="Fault Dashboard"/>



Note: The updated entries in the <Web NMS Home>/users/<user-name>/Dashboards.xml or <Web NMS Home>/html/defaultToAllUsers/Dashboards.xml  will be read on the cold start of the server. To add a new dashboard without reinitializing the server add the enclose the particular entry within the <APPEND> tag.  On restart of the server the entries present within this APPEND tag will be updated in the database.


Alternatively you can use the DBXMLTool.bat/sh available in the <WebNMS Home>/bin/developertools folder to update the Dashboard related entries.



Provide an entry for the dashboard in Tree.xml as follows:    


    <DEVICE Client="All" DEFAULT-CLOSE-OPERATION="DISPOSE_ON_CLOSE" ICON-FILE="images/faulttreeicon.png" ID="Fault" IMAGE-NAME="images/faultmain.gif" INIT-ON-STARTUP="false" MODULE-NAME="Default" PANEL-KEY="Fault" PANEL-NAME="com.adventnet.nms.util.ImagePanel" TAB="true" TARGET="center" TREE-NAME="Fault Management" URL="jsp/ShowImage.jsp?imageName=../images/faultmain.gif">

    <LEVEL-1 ID="Fault Dashboard" URL="/home/Homepage.do?treenodeId=Fault Dashboard" Client="HTML" TREE-NAME="Fault Dashboard"/>

    <LEVEL-1 Client="All" ICON-FILE="images/event.png" ID="Events" .../>

    <LEVEL-1 Client="All" ICON-FILE="images/alarm.png" ID="Alerts" .../>



     //The treenodeId is passed as a request parameter. This parameter value must match with the Dashboard's TREENODE_ID property.



On updating the configuration files as stated above, when the FaultDashboard tree node is clicked, a dashboard with the fault related widgets will appear.



Note: To avoid reinitialising the database on providing a new entry in the Tree.xml file, you can use the DBXMLTool.bat/sh available in the <WebNMS Home>/bin/developertools folder to update the database with the updated Tree.xml entries.



A dashboard which is associated to a tree node cannot be used as a normal dashboard. This dashboard can be invoked from the tree node only.


Converting a Normal Dashboard to a Tree Dashboard


Modify an existing entry in Dashboards.xml by including the TREENODE_ID attribute attribute as follows:


     <DASHBOARD COLUMNS_WIDTH="30:40:30" NAME="Overview" IMAGE="/webclient/home/images/overview.gif" DESCRIPTION="Overview"  TREENODE_ID="Performance Dashboard"/>


Ensure that an entry for Performance Dashboard is present in Tree.xml as follows:


     <LEVEL-1 ID="Performance Dashboard" URL="/home/Homepage.do?treenodeId=Performance Dashboard" Client="HTML" TREE-NAME="Performance Dashboard"/>


Run DBXMLTool.sh/bat, and update database for the user. Both the Dashboard.xml and the Tree.xml files must be updated. And the client restarted. Now when the corresponding user logs in, the Performance dashboard will appear in the corresponding tree and not in the home page.


Converting a Tree Dashboard to a Normal Dashboard


There are two ways in which a tree dashboard modified to a normal dashboard.

Option 1:

Remove tree dashboard entry from Tree.xml for the corresponding user and update the database (for Tree.xml) using DBXMLtool.

Option 2:

Remove entry for tree node Id in Dashboards.xml and update the database (for Dashboards.xml) using DBXMLtool. If no dashboard is associated with tree, then remove entry from Tree.xml and update database for Tree.xml as well.


Deleting a Dashboard


A dashboard can be deleted using the deleteDashboard() method.


      //API :This is used to delete the widget from the dashboard.

      boolean result=HomePageAPI.getInstance().deleteDashboard(id);


For viewing the dashboards, please refer to the User Guide section on Viewing Dashboards.


Working with CCTVs


The CCTV feature available in Web Client helps to view the required dashboards repeatedly at defined intervals. The addition and deletion of CCTVs can be achieved using APIs.


Creating a CCTV


There are two ways in which a CCTV can be created. Using the available APIs and through the Dashboards.xml XML file.


Using API

The addCctv() method is used to add the CCTV.


    long id =HomePageAPI.getInstance().addCctv(userName, name, interval, description);


Using XML

The entries related to CCTV is also provided in the <Web NMS Home>/users/<user-name>/Dashboards.xml or <Web NMS Home>/html/defaultToAllUsers/Dashboards.xml.
The entries will be read on server startup and the details updated in the database.

On consecutive client logins, the Dashboards.xml file is read, and the entries present under the <APPEND> tag will be updated into the database and the CCTV constructed.



    <CCTV NAME="Example Cctv" TIME_INTERVAL="5" DESCRIPTION="Example View"/>


    <CCTVVIEWS CCTV_NAME="Example Cctv" DASHBOARD_NAME="Example"/>




Adding Dashboards to CCTV


Dashboards can be associated to a CCTV using the addCctvViews(cctv, dashboardIds) method.


    //API :This is used to associated the dashboards to the added cctv

    boolean result = HomePageAPI.getInstance().addCctvViews(cctv, dashboardIds);



Deleting a CCTV


CCTVs can be deleted using the deleteCctv(cctvId) method.


    //API :This is used to delete the CCTV.

    boolean result =HomePageAPI.getInstance().deleteCctv(cctvId);




Copyright © 2013, ZOHO Corp. All Rights Reserved.