Dashboard item example

You can use IBM® QRadar® GUI Application Framework to add a dashboard item to your QRadar dashboard.

You might use dashboards to display data that you want to view or use often, for example, you might want to monitor disk usage on your QRadar appliances.

The sample dashboard item app adds a basic dashboard item to the QRadar Dashboard tab.

The following image is a dashboard example that is created by an app in QRadar.

On the Dashboard tab, the sample dashboard item is accessed by using the Add Item menu.

The following image shows the sample dashboard in the Add Item menu.

The dashboard sample app contains the files that are described in the following table:

Table 1. Dashboard sample app files
Files/Folders	Description
app	The root directory for application files. The app folder contains the following files: qpylib contains the Python library files that your application uses to connect to the QRadar API endpoints. __init__.py - a sample initialization that creates a Flask instance, imports views from views.py script and functions from the qpylib library. views.py the main entry point into the web application. This file and the manifest.json file are the only files that are required in every app. Contains sample code for the Dashboard example app. The /static/sampleDashboardItemResponse.json file contains the JSON object that contains the dashboard ID, title, and HTML string.
qradar_appfw_venv	Contains the Python virtual environment where the dependencies are installed.
__init__.py	Creates an instance of the Flask micro-framework that is used to serve content to QRadar.
manifest.json	Describes details about the sample Dashboard Example, which QRadar uses.
run.py	Contains instructions to run the code that is in the /app sub directory.

manifest.json

The manifest.json file contains the following code:

{
  "name":"DashBoard Example",
  "description":"Application to display a new dashboard item",
  "version":"1.0",
  "uuid":"558d7935-f00b-42da-a278-c82abdb12d21",

 "dashboard_items":[
   {
    "text":"QDashBoardExample Item",
    "description":"Sample dashboard item that is a copy of most recent offenses",
    "rest_method":"sampleDashboardItem",
    "required_capabilities":["ADMIN"]
   }
 ], 
 "rest_methods": [
  {
   "name":"sampleDashboardItem",
   "url":"/static/sampleDashboardItemResponse.json",
   "method":"GET",
   "argument_names":[]
   "required_capabilities":["ADMIN"]
   }
 ]
}

The first four objects, name, description, version, and uuid, provide basic application information.

The dashboard_items object describes a new item on the QRadar Dashboard tab. These items are available to users, who can manually add the items to their dashboard.

The dashboard_items block contains the fields that are described in the following table:

Table 2. Dashboard items block
Name	Description	Value
`text`	The name of the dashboard item that is displayed.	QDashBoardExample Item
`description`	A description of the dashboard item that is displayed when your mouse hovers over the dashboard item.	Sample dashboard item that is a copy of most recent offenses
`rest_method`	The name of the REST method to load this item. This method must be declared in the `rest_methods` section of the manifest.	sampleDashboardItem
`required_capabilities`	Instructs QRadar to display the Dashboard Example dashboard item only to users who have administrator privileges.	`["ADMIN"]`

The rest_methods block contains the fields that are described in the following table:

Table 3. REST methods block
Name	Description	Value
`name`	A unique name for this REST method within the app.	sampleDashboardItem
`url`	The URL to access the REST method, relative to the application root. Only URLs within their own application are supported.	/static/sampleDashboardItemResponse.json
`method`	Concise text to display that describes the area. Can optionally point at a resource bundle key, if the application is globalized.	GET
`argument_names`	The names of arguments that this method supports. Arguments are passed to the method URL encoded, as either query string parameters or in the PUT/POST body.	[]
`required_capabilities`	This field instructs QRadar to display the Dashboard Example dashboard item only to users with Administrator privileges.	`["ADMIN"]`

views.py

For this sample app, creates the default routes '/' and '/index', both of which return a simple string. The index route is declared in the url field of manifest.json.

__author__ = 'IBM'

from app import app

@app.route('/')
@app.route('/index')
def index():
    return ""

/app/static/sampleDashboardItemResponse.json

The /app/static/sampleDashboardItemResponse.json file contains the following code:

{"id":"sampleDashboardItem","title":"Sample Dashboard Item",
          "HTML":"<div>This item could contain <b><u>any HTML</u></b>!</div>"}

The JSON object that is returned needs the following data:

An ID for the dashboard item you are creating
A title for the dashboard item
HTML to render the dashboard item