Skip to main content

Adding a custom report

Custom reports provides means to generate reports that are not necessarily sourced from the main instance database.

The custom reports are transparent within the product. Just like built-in reports, they can be saved, scheduled, emailed and exported for later consumption.

When creating custom reports, the following assumptions apply:

  • The custom report is being sourced from a Python script.

  • The language is English. There is no support for internationalization at this time.

  • There is no inherent date handling. All date inputs are valued as inputted with no conversion for timezone.

Creating a custom report

To create a custom report in Python:

  1. Import the report library from IDMLib.

  2. Initialize a report object. This should contain:

    • Report title

    • Report category

    • Report description

    If you want the report to be included under a specific category, use an existing category name when initializing a report object in your Python script. The existing category name is defined in report.py in the \<instance>\idmlib\ directory.

  3. Set the headers of the report table (using add_headers() method).

    The number of headers and their values will not change once this is done.

  4. Construct the search criteria.

    There are methods, defined in report.py in the \<instance>\idmlib\ directory, to add different search fields.

  5. Call the start (cb) method, passing the function name of the callback that will handle the processing of the data.

Registering a custom report

Registering a report is the act of importing the custom report into the report module. Once correctly registered, the custom report should be indistinguishable from a built-in report.

To import the report:

  1. Ensure that Python 3.11.2+ is installed and added to the operating system PATH variable.

  2. To check whether Python recognizes IDMLib:

    1. Open a command line prompt and navigate to the <Program Files path>\Bravura Security\Bravura Security Fabric\<instance>\ directory.

    2. Type python , and press Enter to start the Python interpreter.

    3. On the Python interpreter command line, type from idmlib import report, and press Enter .

    4. If IDMLib is recognized, there should be no error returned.

  3. Copy the script file into the \<instance>\report\ directory.

  4. Log in to Bravura Security Fabric and navigate to Manage the system > Workflow > Options > Plugins.

  5. In the PLUGIN PROGRAM field, specify: .py <Python Installation Path>.

  6. Navigate to Manage the system > Modules > Manage reports (RPT).

  7. In the ALLOWED REPORTS CUSTOM field, type the path, file name and extension of the report script relative to the \<instance>\report\ directory.

    For multiple reports, include the report script names in a comma-separated list.

    For example, if the report script, sample.py is located in \<instance>\report\pam\, then specify pam\sample.py only.

    If the script contains any errors, it will not show up in the Manage reports (RPT) module. The Manage reports > Reports page will display which custom reports have errors detected in them.

Troubleshooting custom reports

A method is provided in order to troubleshoot custom reports. Within the \<instance>\report\ directory, run the following command:

<Script>.py <Action>

where <Script> is the custom report script and <Action> is one of:

Table 1. Custom reports troubleshooting arguments

Argument

Description

-h, –help

Display the help message and exit.

-query

Returns the KVGroup of search criteria to display.

-queryinfo

Returns report title, category, and description details.

-queryheaders

Returns headers defined in script. The number of entries must match the number of header columns defined.

-testinput <testinput>

Generate empty search criteria KVGroup input <testinput>.

-testrun <testrun>

Dumps all query info and executes using search criteria defined in KVGroup file <testrun>

-execute

Executes search query. Expects initial KVGroup.



Sample custom report

A sample report, example-custom-report.py, is located in samples\idmlib\report\.

If you cannot find the sample file, try re-running setup to modify your installation. Sample files are automatically installed with complete (typical) installations. You can select them in custom installations.

In this section: