Creating widgets from a Generic API data source
You can use the Generic API to create widgets that fetch data from IBM® QRadar® APIs and QRadar apps with exposed APIs.
Before you begin
Your administrator must configure QRadar Proxy for your account, and you need a valid authentication token so that you can connect to QRadar.
About this task
APIs return either a JSON array (when there are multiple results) or a JSON object (when there is only one result). Returned JSON objects are converted into a JSON array that contains one element.
- Click Configure dashboard.
The Configure dashboard screen displays a library of available widgets, with details about each widget.
- Click Create new widget.
- On the New Dashboard Item page, enter a name and a description for the widget.
- Select Generic API from the data source list in the
Query section, and enter an API endpoint, such as one of the following
For more information, see Tips for creating Generic API queries for dashboard charts.
- Optional: Add parameters to the Generic API query.
- Insert existing parameters in the statement. Click the Insert Parameter icon, and then click Insert for each relevant parameter.
- To change the default value of the parameter, click the View
Parameters icon, and click Save after you set the default
When you change the default value for a parameter, you're changing the value everywhere the parameter is used in your workspace, except in expanded or pinned dashboards and widgets. If you don't set the value as the default value, the updated change applies only to the current session. However, if you set the value as the default, the current session value also uses that value.
The predefined SYSTEM:accountId parameter returns the account ID of the user who is logged in. System parameters are read only and you cannot change the default value.
The predefined SYSTEM:timerange:start and SYSTEM:timerange:end parameters represent the start and stop times in milliseconds based on the value of the SYSTEM:timerange selection, such as 'Last 30 minutes'. These parameters are used for time-based charts that track cases. For example, cases over time by type. The API for this type of time chart might look like the following example:
- To add a parameter to your workspace, click Add, give the
parameter a name and default value, if needed, and then click Save.
After you add parameters to a widget on a dashboard for the first time, the Parameters card appears on the dashboard. If you remove parameters from the widget, and no other widget in that dashboard uses the parameter, the Parameters card disappears.
- Pick a refresh time for how often you poll the data source. The default
refresh time is every 5 minutes. The shorter the refresh time, the greater the performance impact on
QRadar. The refresh time
starts after the query is completed.
For example, if the query takes 3 minutes to complete, the refresh time starts only after the 3-minute run ends.
- If the root object in the returned JSON is not the array you want to plot, enter a Results mapping to define which key contains the relevant data you want to plot. For more information, see Tips for creating Generic API queries for dashboard charts.
- Optional: If the returned JSON includes a title mapping, set Use title from the result set to On. For more information, see Tips for creating Generic API queries for dashboard charts.
- Click Run Query.
When you first create the widget, you can't configure the charts if no data results are returned. Try making the criteria in the fields less strict and run the query again.
Create a dashboard chart in the Views section.
Because you can create multiple views and charts from the same query, give the view a unique name. By default, the chart's title and status on the title bar are displayed; to hide them, click the More options icon and switch the settings to Off.
Select a chart type and configure the relevant properties. For use cases to help you decide
which chart type to use, see Widget chart types.
Chart type Instructions Bar Creating a bar chart Big Number Creating a big number chart Geographic Creating a geographic chart Pie Creating a pie chart Scatter Creating a scatter chart Tabular Creating a tabular chart Time Series Creating a time series chart
Preview how the chart looks and then click Save.
Tip: The labels for the chart come from the queries that are used. If they are unintelligible in the preview, edit the labels in the View section.