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.

NOTE: Users can manage the custom reports using the Code Insight Reports REST APIs. The APIs enable users to create, update, delete, or retrieve the registration details for any given report. For details, refer to the Reports section in the Code Insight Swagger documentation.

Summary of the Framework Process

The following outlines the process for creating a custom report through the Custom Report Framework:

1. Create the report script that includes or invokes the code defining the report content and identifies the formats in which the report will be generated.
2. Gather the items for the report package.
3. Copy the report package to the Core Server.
4. Register the new report to your Code Insight system.
5. Generate the report from the 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:

1. Download the report package for Files Without Inventory Report from here. The package is called FilesWithoutInventory.zip.
2. 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.
     
     
3. Copy the folder FilesWithoutInventory_ReportPackage to the instance on which the Code Insight Core Server resides.
4. Log into the Core Server.
5. 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
6. 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: 

1. 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.)
2. Provide the appropriate registration information for the report in the API body. SeeParameters in the API Body Used to Define a Custom ReportRequest for details.
3. Provide your JWT token in the Authorization field.
4. Execute the API.

NOTE: You can manage the custom reports using the Reports REST APIs. The APIs enable you to create, update, delete or get custom reports. For more details, refer to the "Reports" section in the Swagger documentation.

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.

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: 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.

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:

1. Launch FlexNet Code Insight.
2. Open an already scanned project; or create a new project, upload its codebase, and scan it.
3. Navigate to the Reports tab for the project.
4. From the list of reports on the Reports tab, select Files Without Inventory Report.
5. 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.
6. 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.)
   When these fields have been properly completed, click Generate Report on the pop-up window.
7. 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.
8. 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

TheFilesWithoutInventoryReportPackage 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/uploadReport

If 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 html

The 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 sampleFiles Without Inventory report:

The archive includes the following for the sample report. However, the toUpload.zipfile 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/uploadReport

This 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.