DX UIM Business Intelligence Multi-Line Chart widget - ODATA Usage Example

Products

• DX Unified Infrastructure Management (Nimsoft / UIM)

Issue/Introduction

The DX UIM Business Intelligence Portlet that ships with DX UIM 23.4.6 and higher includes a new Multi-Line Chart Widget.

This article demonstrates how to use this widget with the new ODATA API data source.

Environment

• DX UIM - 23.4.6 (aka 23.4 CU6) or higher

• DX UIM Business Intelligence portlet (formerly Dashboard Designer)

 

Resolution

The Multi-Line Chart can be used to display multiple series at once, similar to the existing Line Chart widget, but with more flexibility for creating dynamic reports.

Two data sources are supported:

1. ODATA API
2. SQL 

Both datasources require a return of values labeled as "sampletime" and "samplevalue" to create a line chart.  

This KB focuses on the ODATA API.   

ODATA API

Note: Before you can use the UIM ODATA API to build reports/dashboards you must ensure that you have enabled the UIMBI datasource connection as described in techdocs.

In this example, we will create a simple dashboard that shows CPU and Memory Usage data for a selected set of robots.

The Multi-Line Widget is intended to be used alongside a Context Selector widget, so we will set that up first.


Setting Up The Context Selector

1. Drag and drop a Context Selector to your canvas.
   
   
   Resize the widget to make room for multiple selectors.
   
   
   
   
2. Select the widget and navigate to Widget Properties (wrench icon).
   
   
3. There is already one default selector for Time.  Click the Plus (+) above to add another selector.
   
   
   
   
4. Choose "Time Range" for the Selector Type.  The parameter name TimeRange should auto-populate.
   
   
   
   
5. Now highlight the original "Time" selector and press the Trash Can icon to delete it.
   
   
6. Click the Plus (+) again to add another selector and this time choose "Date Time".
   
   
7. For the parameter name on this selector enter: StartDate
   
   
   
8. Double-Click "Date Time" to rename the selector and rename it to something like "Start Date".
   
   
9. Repeat steps 6-8, creating another Date Time selector.  Name this one "End Date" and for the parameter name enter: EndDate
   
   
   
10. Finally, click the Plus (+) one more time and this time, add a "Drop Down" selector.  Double-Click the selector name and rename it something like "Device Name". For this selector, choose the following options:
    
    Data Type: String
    Sorting Options: Alpha-Numerical
    Parameter Name: CsId
    
    
11. Select the bullet for "Get values from ODATA data source", select the UIMBI connection and click the Plus (+) to add a new ODATA Query.
    
    
    
12. Give the query a name like "Device List" and choose MasterDevice for the Entity Set.  Under Entity Columns, select Name and CsId.
    
    
    
    
13.  This will automatically populate the OData Query window with the following string:
    /MasterDevices?&$select=CsId,Name&$format=json
    
    Edit this and reverse the order of CsId and Name so that our Drop Down will display the device names correctly.
    
    
    
    
14. Set the "Order" to Sort By Name Ascending.
    
    
    
    
15. Click Create.
    
    At this point, save your dashboard, and go to Live View.  Click the Device Name dropdown and verify that it shows the list of devices.
    
    

Note: If you see a list of numbers here instead of device names, go back and edit the OData Query above (see Step 13) and you will likely find that the query still says "CsId,Name" instead of "Name,CsId".  Reverse the order again and click Update Query. Do not click on the Test Query button or the change will be reverted.  You can go back and edit the query and then click the Test button to make sure it returns data, but you must save it with the changes prior to clicking Test Query.

Setting Up The Multi-Line Chart

Once you have verified that the dropdown list of devices is working, edit the dashboard and follow these steps:

1. Drag-and-drop the Multi-Line Chart Widget to your Canvas.
   
   
   
   
   
2. Navigate to the Widget Properties (wrench icon).
   
   
3. Under the "Chart" section give the chart an appropriate title, for example "CPU Usage".  If desired, adjust the other options here as you see fit.  For example, on a chart that shows percentages, you might set a Min. Value of 0 and a Max Value of 100.
   
   
4. Under "Data Source", set the type to ODATA and select the UIMBI connection and then click the Plus (+) to add a new query.
   
   
5. Name the query something meaningful like "CPU Usage" and for the Entity Set, choose "metricReport".
   
   
6. This will auto-populate a query that shows the expected parameters.  We need to change some of the parameters as follows:
   
   GroupId should be set to -1 to disregard this parameter, as we are giving a list of CsIds and not a group;
   
   MetTypes must be set to a value that reflects the metric we want - in this case '1.5:1|QOS_CPU_USAGE' - see the Additional Information section below for more information about how to determine the appropriate value to use.
   
   CiNames should be set to an empty string as we are only querying by Metric Types here.
   
   The remaining values can be left as-is, and they will be passed the values set in the respective parameters by the dropdowns in the Conext Selector.
   
   When you are finished, the ODATA query you have should be as follows:
   
   /metricReport(GroupId=-1,CsIds='${CsIds}',MetTypes='1.5:1|QOS_CPU_USAGE',CiNames='',TimeRange=${TimeRange},StartDate=${StartDate},EndDate=${EndDate})?&$format=json
   
   
   Here is a full breakdown of what the parameters above indicate:
   
   

   GroupId	set to -1 to disregard this parameter, as we are giving a list of CsId's and not a group
   CsId	use the value of the ${CsIds} parameter which is set by the selections in the Device Name drop down
   MetTypes	specifies what metric type we want, in this case CPU Usage.  (See below for details)
   CiNames	set to an empty string since we are looking for a report based on specific metrics
   TimeRange	set by the Time Range drop down and specifies the period for which to return data
   StartDate/EndDate	when "Custom" is selected in Time Range, the parameters ${StartDate} and ${EndDate} which are set by the Context Selector are used to determine the period for which to return data

   
   
   
   
7. Click Create to finish creating the query.
   
   
8. Save and publish the dashboard.

At this point you should have a working dashboard that allows you to select one or more devices from the Drop Down and set a date range and populate the chart.

To add additional charts to display e.g. Memory and Disk metrics, repeat the same steps 1-7 above, with the following changes:

Step 3:  Give a different name for the chart, e.g. "Memory Usage" or "Disk Free"

Step 5: For the "MetTypes" parameter use a different value, e.g.:


MetTypes='1.1:98|QOS_DISK_FREE'

Note that it is also possible to combine multiple metrics on a single chart by passing a comma-separated list, e.g.:

/metricReport(GroupId=-1,CsIds='${CsId}',MetTypes='1.5:1|QOS_CPU_USAGE,1.1:98|QOS_DISK_FREE',CiNames='',TimeRange=${TimeRange},StartDate=${StartDate},EndDate=${EndDate})?&$format=json

This will allow multiple metrics to appear on a single chart for easy correlation and comparison.

Note: in DX UIM 23.4.7 and higher, the metricReport function contains an additional parameter, aggregationInterval which can be set to a number of minutes, or "null" to display Raw Data.

The aggregation works the same way as in the Metric Viewer which is described here.

Additional Information

For more information on how to know what to use for the MetTypes parameter, you can navigate your browser to the following URL-

http://[HOST_OR_IP]/uimdataservices/v1/MasterMetrics/

This will output an XML list of all available metric types.  The value for d:MetricTypeQoS is the value to use for the MetTypes parameter.

For example, for QOS_DISK_FREE, the value would be '1.1:98|QOS_DISK_FREE'

You can filter on a specific value by adding the following string (substituting the name of the QoS as needed):

?$filter=contains(QosName,'QOS_DISK_FREE')

This is a "contains" match so you can do a partial search if you are not sure of the exact name.

e.g to list all QoS with "CPU":

http://[HOST_OR_IP]/uimdataservices/v1/MasterMetrics?$filter=contains(QosName,'CPU')

 

The following SQL query can also be used to generate a list of available metrics and the corresponding MetType value:

select distinct met.ci_metric_type, q.qos
from s_qos_data q, cm_configuration_item_metric met
where q.ci_metric_id = met.ci_metric_id