Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Page Script / Toolbar Button Example

 

The page script / toolbar button example adds a button to the toolbar on the Offenses or Offense Summary tabs in JSA. The new button calls a page script when you click it.

When you select an offense in the Offenses or Offense Summary tab, and click the button, information about the selected offense is displayed in an alert.

The following image shows the My Offense Button.

The following image shows the output from using the My Offense Button.

The following table shows the files that are used for this sample app:

Table 1: Sample App Files

Files/Folders

Description

app

The root directory for application files. The app folder contains the following files:

qpylib folder that contains the Python library files that your application can use to connect with JSA API endpoints.

__init__.py - a sample initialization file your app. It creates a Flask instance, imports views from views.py 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 application. This file contains sample code for the sample application.

The /static/js/custom_script.js script that is run when the button is clicked.

__init__.py

Creates an instance of the Flask micro-framework that is used to serve content to JSA.

manifest.json

This file tells JSA what the sample app does.

Manifest.json

The manifest.json file contains the following code:

{ "name":"Page script test App", "description":"An example of to test page scripts", "version":"1.0", "uuid":"4a5d50cc-b9f1-4526-b356-5cb2d60e9467", "rest_methods": [ { "name":"offenseListFunction", "url":"/offenseListFunction", "method":"GET", "argument_names":["context"] } ], "gui_actions": [ { "id":"OffenseListToolbarButton", "text":"My Offense Button", "description":"My Offense Button", "icon":"", "rest_method":"offenseListFunction", "javascript":"my_offense_toolbar_button_action(result)", "groups":["OffenseListToolbar"] }, { "id":"OffenseSummaryToolbarButton", "text":"My Offense Button", "description":"My Offense Button", "icon":"", "javascript":"my_offense_toolbar_button_action(context)", "groups":["OffenseSummaryToolbar"] } ], "page_scripts": [ { "app_name":"SEM", "page_id":"OffenseList", "scripts":["static/js/custom_script.js"] }, { "app_name":"SEM", "page_id":"OffenseSummary", "scripts":["static/js/custom_script.js"] } ], }

The first three objects, name, description, and version, provide basic app information.

The gui_actions object describes a new GUI Action that the user can perform in the JSA user interface. It is abstracted from the underlying representation.

GUI Actions are represented as buttons on page toolbars, or as right-click menu options.

GUI Actions can run a block of JavaScript, invoke a REST method, or both.

The gui_actions block contains sections for both the Offensespage toolbar and the Offense Summary page toolbar.

The Offenses page toolbar section contains the fields that are described in the following table:

Table 2: Offenses Page Toolbar Fields

Field

Description

Value

id

A unique ID for this area within the application

OffenseListToolbarButton

text

The name of the GUI Action that is displayed in the user interface.

My Offense Button

description

A description of the GUI Action that is displayed when your mouse hovers over the item.

My Offense Button

icon

A URL to load, relative to the application root. Only URLs that exist within the app can be referenced.

""

rest_method

The name of the REST method to load this item. This method must be declared in the rest_methods block of the manifest.

offenseListFunction

javascript

A JavaScript code block to run when this action is performed. Either this argument or the REST method argument is required. If both are specified, then the REST method is run first, the results are then passed into the JavaScript code block by using the variable result.

If only the JavaScript argument is specified, a context variable that contains the context of the GUI Action, is passed into the JavaScript code block.

my_offense_toolbar_button _action(result)

groups

A list of one or more GUI Action groups to install the action into. This string is the identifier of the toolbar or right-click menu in JSA. At least one group must be provided.

You can also use a group name in this format ariel:<FIELD_NAME>, where <FIELD_NAME> is the name of a field in the JSA Event or Flow viewer. If this field is specified, the action is installed into the menu of that field, and the context parameter is the contents of the field.

["OffenseListToolbar"]

The Offenses Summary page toolbar section contains the fields that are described in the following table:

Table 3: Offenses Summary Page Toolbar Fields

Field

Description

Value

id

A unique ID for this area within the application

OffenseSummaryToolbarButton

text

The name of the GUI Action that is displayed in the user interface.

My Offense Button

description

A description of the GUI Action that is displayed when your mouse hovers over the item.

My Offense Button

icon

A URL to load, relative to the application root. Only URLs that exist within the JSA app can be referenced.

""

javascript

A JavaScript code block to run when this action is performed. Either this argument or the REST method argument is required. If both are specified, then the REST method is run first, the results are then passed into the JavaScript code block by using the variable result.

If only the JavaScript argument is specified, a context variable that contains the context of the GUI Action, is passed into the JavaScript code block.

my_offense_toolbar_button_ action(context)

groups

A list of one or more GUI Action groups to install the action into. This string is the identifier of the toolbar or right-click menu in JSA. At least 1 group must be provided.

You can also use a group name in this format ariel:<FIELD_NAME>, where <FIELD_NAME> is the name of a field in the JSA Event or Flow viewer. If this field is specified, the action is installed into the menu of that field, and the context parameter is the contents of the field.

["OffenseSummaryToolbar"]

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

Table 4: Rest_methods Block Fields

Field

Description

Value

name

A unique name for this REST method within the application.

offenseListFunction

url

The URL to access the REST method, relative to the application root. Only URLs within the app are supported.

/offenseListFunction

method

The HTTP method on the named endpoint (GET/POST/DELETE).

GET

argument_names

The names of arguments that this method expects. Arguments that are passed to the method URL are encoded, as either query string parameters or in the PUT/POST body.

["context"]

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

Table 5: Page Scripts Block Fields

Name

Description

Value

app_name

The name of the JSA application you want to include the script into. The wildcard "*" is also supported if it is used with the page_id field, to have a file included in every JSA page.

SEM

page_id

The ID of the JSA page where the script is included. The wildcard "*" is also supported when it is used with the app_namefield. When the wildcard character is used, a file is included on every JSA page.

OffenseList

scripts

The scripts that you want to include, relative to the application root.

["static/js/custom_script.js"]

Views.py

The views.py for this example establishes the Flask routes that are used by the application. The script injects context information from the REST API endpoint into the offense variable. This content is used by the page script.

__author__ = 'IBM' from flask import request from app import app from qpylib import qpylib import json @app.route('/offenseListFunction', methods=['GET']) def offenseListFunction(): qpylib.log("offenseListFunction", "info") offense = request.args.get("context") qpylib.log("context=" + offense, "info") #You can process the data and return any value here, #that will be passed into javascript return json.dumps({'context_passed_to_python_route':offense})

Static/js/custom_script.js

Contains the function that turns the content of the offense variable into a string and displays it within a JavaScript alert dialog.

function my_offense_toolbar_button_action(offense) { alert(JSON.stringify(offense)); }

Script files must be fragments and not fully formed HTML because they are injected in to a fully rendered page.

Note

Be careful how you name functions because apps can share scripts from JSA. It is good practice to add a prefix to the JavaScript function such as the app name.

Page Script Samples

You can use page scripts to link between apps, select rows in a JSA table, and get the IP address of an asset.

How to Link Between Apps

You use the setActiveTab(tabId,url) function from the qradar.js library to link between two apps that are installed on the same JSA Console.

For example, you want to link from MyApp1 to MyApp2. MyApp1 uses the following HTML template with a div tag that calls a JavaScript function:

<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>myApp1</title> <script type="text/javascript" src="static/js/myApp2.js"></script> </head> <body> <div onclick="somejs();"> Link to myApp2</div> </body> </html>

The somejs() function in the static/js/myApp2.js file uses the setActiveTab(tabId,url) function from the qradar.js library:

function somejs() { alert('set active tab'); top.setActiveTab("myApp2_1057","plugins/1057/app_proxy/index"); }

The tabId parameter uses the following format: areasID_applicationID. The areas ID is the value of the id field in the areas block of the myApp2 manifest.json file.

The url parameter uses the following format:

plugins/<applicationID>/app_proxy/<areasURL>

.

The applicationID is assigned when you install your app. You can use the POST /gui_app_framework/application_creation_task endpoint to retrieve the applicationID.

The areasURL is the value of the url field in the areas block of the following myApp2 manifest.json file.

"areas": [ { "id":"myApp2", "text":"myApp2", "description":"The app I am linking to", "url":"index", "required_capabilities":["ADMIN"] } ],

How to Get the Selected Rows in a Table

To get all the selected rows in a table on a JSA page, use the following code in your page script:

var selectedIds = getSelectedRowIds(); var grid = getGrid(); var store = grid.store; var row = grid.row(selectedIds[0], true );

How to Get the IP Address Of the Selected Asset from the Asset Page

To get the IP address of the selected asset from the JSA Asset tab use the following code in your page script:

var assetId = selectedRows[0].id;