Introduction
Starting with Code Insight 2020 R1, you can create and generate custom reports that are in addition to the three standard reports that come with Code Insight. Custom reports can capture the Code Insight project data that is most relevant to you and in a format that you desire. This article walks you through the process of creating and generating a sample custom report called Files Without Inventory.
Prerequisite
The process of generating custom reports requires that you (or Revenera Services) write scripts that leverage the REST APIs provided by Code Insight to retrieve data for the reports. These scripts must reside on the Code Insight Core Server. To copy the scripts to the Core Server, you need access to the Core Server file system.
How the Custom Reports Framework Works
The Custom Reports Framework enables you to create reports that highlight the Code Insight project data most important for your business needs and to generate these reports in the file format of your choice. You will need a report script that includes (or provides access) to the code that extracts and manipulates the desired project data for your report. The report script and its dependencies, if any, must be copied to a designated location on the Code Insight Core Server. (This article will refer to the report script and its dependencies as the report package.) Once the report package resides on the Core Server, the report must be registered with Code Insight to make it available to all projects in your Code Insight system. After a successful registration, users of any given project can generate and view the new custom report for a given project from the project’s Summary tab.
Summary of the Framework Process
The following outlines the process for creating a custom report through the Custom Report Framework:
- Create the report script includes or invokes the code defining the report content and identifies the formats in which report will be generated.
- Gather the items for the report package.
- Copy the report package to the Core Server.
- Register the new report to your Code Insight system.
- Generate the report from Reports tab for any project in your Code Insight system.
Phase 1: Creating the Script for a Custom Report
In general, the script that you create to generate a custom report includes or calls the code that defines the report contents. This code leverages any of Code Insight REST APIs to retrieve the project data you want to show in the report.
The report script must also contain certain parameters and calls for generating the report. For an explanation of the required script elements, see the "Understanding the Example Script" section, which examines the script used to define and generate the sample report, Files Without Inventory.
Keep in mind that the report script can call files of any type. However, the script itself must be either a .sh, .bat, or .exe file.
Phase 2: Gathering the Artifacts for the Report Package
The next step is to gather the report artifacts into a single folder. These include the report script and all files needed to create the custom report. For an example of what items might be included in a report package, refer to the description of the Files Without Inventory report package in the “Understanding the Example Script” section later in this article.
Phase 3: Copying the Report Package to the Core Server
The next step is to copy the report package to the Code Insight Core Server. The following procedure demonstrates this step using the report package for the example Files Without Inventory report.
About the Sample Report
Files Without Inventory is a simple report that lists all the files in a given project that are not associated with any inventory. The report is designed to be downloaded as an html file.
Caution: This example report is provided by Revenera for demonstration purposes only. However, if you would like to use this report in production, you are strongly recommended to perform the required due diligence of acknowledging this script as a third-party script in your production system.
Steps to Copy the Report Package to the Core Server
The following steps download the Files Without Inventory Report package and then demonstrate how to copy the package to the Core Server:
- Download the report package for Files Without Inventory Report from here. The package is called FilesWithoutInventory.zip.
- Unzip the archive. Two folders are extracted:
- FilesWithoutInventory_ReportPackage --Contains all the files necessary to generate the report.
- Source Files--(For your use only) Contains a copy of the sample source code for Files Without Inventory Report.
- Copy the folder FilesWithoutInventory_ReportPackage to the instance on which the Code Insight Core Server resides.
- Log into the Core Server.
- In the Code Insight installation root folder for the Core Server, create a directory called custom_report_scripts:
<Path_of_CodeInsight_Installation>/custom_report_scripts - Copy the folder FilesWithoutInventory_ReportPackage to this directory.
Phase 4: Registering the Custom Report
Once the report package resides in the proper location on the Code Insight Core Server, register the report. Registration makes the report available to all projects in your Code Insight system.
You must be a Code Insight administrator to register the report.
Steps to Register the Report
Use these steps to register a custom report:
- Use the Code Insight REST API Create Report (POST /reports) to register the new report. You can access this API through the Code Insight Swagger documentation. (The Swagger documentation for the Create Report API is shown in the image below.)
- Provide the appropriate registration information for the report in the API body. See Parameters in the API Body Used to Define a Custom ReportRequest for details.
- Provide your JWT token in the Authorization field.
- Execute the API.
Parameters in the API Body Used to Define a Custom Report
The following parameters in the Create Report API body are used to define a custom report.
| name | Provide the name for the report. For the example report, enter "Files Without Inventory Report". |
| path | Enter the path name of the report script. Note that this value is always relative to the <Path_of_CodeInsight_Installation>/custom_report_ scripts folder. For the example report, enter the following: "FilesWithoutInventory_ReportPackage/FilesWithoutInventoryReport.bat" |
| enabled | Ensure that this is set to "true". |
| order | Enter a number that will reflect the position of the new report in the list of reports on the Reports tab available for any project when you open it. For this demonstration, enter "4" so that the sample report is listed after the three standard Code Insight reports. |
| enableProjectPicker |
Enter "true" if you want the report to include data for a second project so that users can compare data from both projects in the same report. Otherwise, the default is "false". If this parameter is "true", the Framework automatically displays a pop-up window whenever a user selects to generate this report, requiring the user to select a second report from a provided dropdown before report generation can continue. Note that the example Files Without Inventory Report does not use a second report. However, you can update this parameter in the report's definition to enable the second report. |
| reportOptions |
(Optional) Define one or more custom options that users complete before the report is generated. See Parameters Used to Define Custom Report Options for more information. Note that the example Files Without Inventory Report does not include custom options. However, you can update update this parameter in the report's definition to include such options. |
Parameters Used to Define Custom Report Options
The reportOptions parameter in the Create Report API body enables you to define one or more custom report options that users can/must complete before the report is generated. (For example, you might define options that filter project data for the report.) The options you define are displayed on a pop-up window whenever a user selects to generate the report. Once the user completes all required fields, the report generation can continue. (The pop-up window also contains the prompt to select a second project if enableProjectPicker is set to "true". This prompt is defined internally by the Framework, so you will not see its definition listed for reportOptions.)
Note that the example Files Without Inventory Report does not define custom options. However, you can update with the report's definition to create such options.
Provide the following parameters for each custom option you want to define for the report.
| name | Enter an internal name for the option. |
| label | Enter the option name that you want to display in the pop-up window. |
| description | Enter a description of the option that will display when the user click the ? icon next to field. The description should include meaningful information such as the purpose of the option and possible values. |
| type | Set the option type to "text", currently the only type available when creating custom options. |
| defaultValue |
Enter the default value for the option. |
| required |
Enter "true" if the user is required to provide a value for the option to proceed with report generation. (The parameter default is "false".) When one or more fields are required, the Generate Report button on the pop-up remains disabled until all required fields are completed. (Required fields left blank are outlined in red.) |
| order |
Enter a number that will reflect the position of the option in the list of options (defined here) on the pop-up window. Note that, if enableProjectPicker is set to "true", the prompt to select a second project is always positioned after the options you define here. |
Phase 5: Generating the Report
Once a report is successfully registered, you can generate it.
Steps to Generate the Report
User these steps to generate the custom report:
- Launch FlexNet Code Insight.
- Open an already scanned project; or create a new project, upload its codebase, and scan it.
- Navigate to the Reports tab for the project.
- From the list of reports on the Reports tab, select Files Without Inventory Report.
- Click the Generate Selected Report button.
- If you enabled enableProjectPicker to require the selection of a second project or defined custom options for the example report, a pop-up window is displayed, prompting you for the information. See step 6.
- If no additional information is needed, skip to step 7.
- From the pop-up window requesting additional information to run the report, complete the fields as described below.
- If the Include data from Second Project field is displayed, enter the name of the second project whose data will be included along with the data from the current project for comparison purposes. As you type a string, project names containing that string are listed in a dropdown from which you can then select the desired project name. (This is a required field.)
- If other fields are displayed, enter the requested values in those fields. Default values can be overwritten. Click the ? icon next to a field for more information about its purpose and possible values. The Generate Report button on the pop-up remains disabled until all required fields are completed. (Required fields left blank are outlined in red.)
- Click OK from the message box that is displayed, stating that the report will run in the background. The report generation starts.
Once the generation of the report has successfully completed, links are displayed in the View Report and Download Report columns for the report. - Access the report:
- Click View Report. An html version of the report is displayed in your browser. (The contents of the sample report show a list of files currently unassociated with inventory in your project.)
- Click Download Report. A zip file is downloaded, containing the report in the various formats defined in the script. For the sample report, only the html version is included in the download.
Understanding the Example Script
To understand how the report is generated, open the FilesWithoutInventoryReportPackage folder that you previously downloaded. The following files are included in the package:
About the Custom Report Script
The FilesWithoutInventoryReportPackage folder contains the custom report script, FilesWithoutInventoryReport.bat (and the .jar file containing the code for defining the report contents). Recall that when you register a report, the path for this script is passed to the Create Report API. For any custom report, the script that you specify when you register a report is the script that is called each time a report is generated.
Open FilesWithoutInventoryReport.bat in a text editor. The script contains the following code:
@echo off
set projectId=%1
set reportId=%2
set jwt=%3
echo %projectId%
echo %reportId%
echo %jwt%
java -jar %~dp0\FilesWithoutInventoryReport.jar "Files Without Inventory Report" %projectId% %jwt% http://localhost:8888/codeinsight html
curl -H "Authorization: Bearer %jwt%" --form projectId=%projectId% --form reportId=%reportId% --form file=@"toUpload.zip" http://localhost:8888/codeinsight/api/projects/uploadReportIf the report requires the selection of a second project or requests information through custom options (or does both), you must add a fourth variable for reportOptions as shown below.
@echo off
set projectId=%1
set reportId=%2
set jwt=%3
set reportOptions=%4
echo %projectId%
echo %reportId%
echo %jwt%
echo %reportOptions%
As shown in the code, Code Insight passes the following values to the script:
- projectId—The ID of the project for which the report is being generated (referred to as %1 in the script).
- reportId—The ID of the report being generated (referred to as %2 in the script).
- jwt—The JWT token for the user requesting the report (referred to as %3 in the script).
- reportOptions—The ID of the second project (if required) and the value for each custom option (referred to as %4 in the script). The value passed for this variable might look like this:
reportOptions = "{"otherProjectId":"700","cvssVersion":"2","cvssScore":"2"}"
The following statement in the script actually generates the report. It invokes .jar containing the code that, in turn, calls Code Insight REST APIs that extract the project data for the report content. Additonally, this statement identifies the formats in which the report will be generated. (In this example, the report is generated in html format only.) Execution of this statment requires the project ID and your JWT.
java -jar %~dp0\FilesWithoutInventoryReport.jar "My Report Title" %projectId% %jwt% http://localhost:8888/codeinsight htmlThe output of this statement is a file called toUpload.zip, which is an archive of all the generated report files, one for each specified format.
About the toUpload.zip File
The following shows the contents of the toUpload.zip file generated, in this case, for the sample Files Without Inventory report:
The archive includes the following for the sample report. However, the toUpload.zip file will have similar contents for any custom report:
- The file 3536 - acornjs_.zip is the archive that is downloaded when you click the Download Report link for the report on the project Reports tab. This archive contains a file for each report format specified in the script.
- The file 3536 - acornjs_.html is the report version displayed when you click the View Report link for the report on project Reports tab.
Positioning the Report for Viewing and Downloading
Once the report output has been generated, Code Insight must be notified that the report is ready for display and download. This notification is performed by the last line in the code:
curler -H "Authorization: Bearer %jwt%" --form projectId=%projectId% --form reportId=%reportId% --form file=@"toUpload.zip" http://localhost:8888/codeinsight/api/projects/uploadReportThis statement calls the Code Insight REST API uploadReport to inform Code Insight that report execution is complete. It then passes the report to Code Insight to make it available for viewing and downloading.
