Add new CLI reports

Create new custom reports and add them to the list of available custom reports by committing the new reports to the TeamForge branding repository.

1. Create a folder (with a meaningful name) for the new report anywhere in the system. For example, create a new folder in your home directory: /home/userid/. Let's refer to the newly created folder as 'myNewReport' folder (located at '/home/userid/myNewReport').
2. Create following files inside the 'myNewReport' folder: config.ini, script and example.html.
   Tip: You can either create those files afresh or copy any existing report files (from any immediate child folder under <cli-reports-installation-folder>/pkg folder) and edit them appropriately for your new report. The latter approach is recommended.
   1. Edit config.ini.
      • The file contains key-value pairs.
      • Modify the values in section '[main]' to reflect appropriate title and description for the new report being added. These are mandatory to enlist the new report in the list of available reports.
      • Modify the 'outputType' key to point to the chart type you want to use for this report. You can either use an existing chart type (child folders under <cli-reports-installation-folder>/types folder) or add a new chart type.
      • The key named 'fields' contains comma separated parameters/widgets required for the report configuration. Each value in the comma separated string should be configured in its own section. For example, refer to the comma separated values of the 'fields' key in the <cli-reports-installation-folder>/pkg/agileBurndownChart/config.ini file.

        fields = trackerIds,planId,timeIn,groupBy,excludeWeekends,issueStatus
        
        [trackerIds]
        label = Tracker ID
        type = wizard
        object = tracker
        max = 10
        help = To know the Tracker Id, go to any Tracker and find the ID in the Summary section of the List View. 
        required = true
        
        [planId]
        label = Planning Folder ID
        type  = wizard
        object = plan
        max = 1
        help = To know the Planning Folder Id, go to any Planning Folder and find the ID in the Summary section of the List View.
        

      • As we are still in the early phases of adding the report, you can keep the 'fields' key simple.

        fields = issueStatus

        Tip: It is recommended to start with minimal configuration and then add the required parameters or widgets one-by-one.
   2. Edit the example.html file to reflect a typical chart for the report you are adding.
      • Existing reports use HighCharts for rendering the data.
      • Note that the example.htmlfile does not have any HighCharts script references. Instead, TeamForge project home page has the required HighCharts Javascript references.
   3. Edit the script file so that it creates the SQL query based on the configured parameters.
      • As we are still in the early stages of adding the new report, the file can contain just following code.

        message info Report not implemented yet!

      • It is recommended to start with minimal code in script file and then slowly add more implementation.
3. Add the report (files) to the repository. In TeamForge, custom reports can be added to the CLI reports by committing the report files into the 'branding' repository.
   1. Checkout the branding repository of look project into a local folder (let's refer to this local folder as <workspace-folder>
      • svn checkout --username XX https://<hostname>/svn/repository-internal/branding
      • cd <workspace-folder>/branding
   2. Create a new folder cli/custom-reports/pkg/.
      • mkdir -p cli/custom-reports/pkg/
   3. Copy the myNewReport folder to cli/custom-reports/pkg/.
   4. Run the following commands.
      • svn add cli
      • svn commit -m “adding a new report”

   If the commit was successful, go to your project home page, click Configure: ON > Add New Component > Life Cycle Metrics and you should now be able to see the new report listed in the available list of life cycle metric reports.

   Note that the report you committed into the branding repository will be automatically checked out and added to the CLI reports. You can find the installed version of the checked in files under <cli-reports-installation-folder>/../../cli/custom-reports/.