Skip to end of metadata
Go to start of metadata

Where to begin

Start with downloading the report scripts from the Health Reports source code repository.

Overview

The cPrime Health Report is framework created in Simple Issue Language™ (SIL) and executed using Power Scripts™ - Jira script automation. The report tool examines the user's current Jira system and evaluates it for areas improvement. By default, evaluations are performed Jira's out of the box checks, and additional basic agile principles. However, the Jira administrator as the ability to alter and increase the performed tests to better evaluate there individual system using tests that are more valuable to their individual team.

Overview

Example

To see a full report, PDF see Full Health Report

Troubleshooting

If you are having trouble installing or running Health Report, please open a Help Desk ticket and choose Health Report from the cPrime App field. A member of our support team will contact you to help you solve your issue.

Also, review our more in depth documentation.



Prerequisites

  • User needs to be a Jira admin
  • Add on Power Scripts™ - Jira script automation needs to be installed.
    • Go to Jira Administration --> Add-ons --> Find new apps (or Find new add-ons in older versions or Jira).
    • In the search bar, search for Power Scripts.
    • Click the Free trial button to get a 30 day evaluation license for Power Scripts.
      • Clicking Buy now will walk you through the process of acquiring a 1 year based license in accordance with your Jira instance.
    • Go to Jira Administration --> Add-ons --> SIL Manager to start using Power Scripts.
    • See Power Scripts for Jira documentation to learn more about Power Scripts.

Quick Start

Installation

Installation assumes you have access to the internet. If your instance does not have outside access, see the "Offline Installation" section.

  • Go to Jira Administration --> Add-ons --> SIL Manager
  • Create a new file called installation.sil within silprograms
    • From the file panel, right click on silprograms and click New File
    • Double click silprograms to expand the directory.
  • Copy the contents of the repository's installation.sil file into the newly created file of the same name in the SIL Manager
  • Update the parameters on lines 6-13 to match your system:
    • jiraUrl - URL of local Jira instance. Defaults to current Jira URL. If the instance is a CLOUD environment, user MUST replace with string URL. Example: "https://myInstance..atlassian.net"
    • adminUser - An Jira admin username to use in advanced background calls in Jira
    • adminPass - The password of the admin user
    • mainQuery - The JQL used to drive the agile report. Example: "project in (TEST, DEMO)"
    • mainFilterId - The query filter id used INSTEAD of 'mainQuery' Example: 23422
  • Click the Check button, then the Save button
  • Click the Run button
  • Once execution finishes, click the Refresh button and a new directory should appear called HealthReport

Datasource

Execute Health Report

  • Go to Jira Administration --> Add-ons --> SIL Manager.
  • From the file list, open silprograms/HealthReport/systemHealthCheck.sil.
  • Click the Run button.
  • A Full report (all reports within the reports directory) will be sent to the user that executed the script.
    • The HTML output will also appear within the console to be copied into a file for viewing, if email is not configured.
    • A timestamped copy of the report will also be saved to silprograms/~ directory.
  • Individual reports can be executed from the silprograms/HealthReport/reports directory.


Offline Installation

Initial Installation

  • Download a zipped copy of the Health Report repository from the dropdown next to the branch name in Bitbucket.

Download Zip

  • Move the zip file the server and upzip
  • Copy the unzipped 'silprograms/HealthReport' directory to <JIRA_HOME>/silprograms
  • Copy the contents of the unzipped 'kepler' directory to <JIRA_HOME>/kepler/templates
  • Copy the contents of the repository's installation_offline.sil file into the newly created file of the same name in the SIL Manager
  • Update the parameters on lines 6-13 to match your system:
    • jiraUrl - URL of local Jira instance. Defaults to current Jira URL. If the instance is a CLOUD environment, user MUST replace with string URL. Example: "https://myInstance..atlassian.net"
    • adminUser - An Jira admin username to use in advanced background calls in Jira
    • adminPass - The password of the admin user
    • mainQuery - The JQL used to drive the agile report. Example: "project in (TEST, DEMO)"
    • mainFilterId - The query filter id used INSTEAD of 'mainQuery' Example: 23422
  • Click the Check button, then the Save button
  • Click the Run button
  • Once execution finishes, click the Refresh button and a new directory should appear called HealthReport

Update Installation

  • Make a copy of all files ending in _custom.csv in the <JIRA_HOME>/silprograms/HealthReport/csvFiles directory
  • Repeat the process from the offline installation
  • Restore the backup files to <JIRA_HOME>/silprograms/HealthReport/csvFiles


Confluence Installation

Prerequisites

  • A space needs to be available in Confluence and configured as part of the Health Report installation.
  • The HTML Macro must be enabled in Confluence. See Enabling the HTML Macro for instructions.
  • The space needs to be updated to use Health Report's CSS styling. Use the file style.css and the directions on Styling Confluence with CSS to install the style.
    • Please note that this style is an addition to the current styling of the space and should NOT impact the look and feel of other content in the space.

Parameter Updates

  • Update the parameters on lines 6-9 to match your system:
    • useConfluence - Set to true. Determines if Confluence is being used to publish reports
    • confluenceUrl - The URL of Confluence
    • confluenceUser - An Confluence admin username to use in REST calls
    • confluencePass - The password of the Confluence admin user
    • confluenceSpace - The Confluence space key used to store all the reports, Example: 'TEST'
  • Click the Check button, then the Save button
  • Click the Run button

Updates

To update to the latest version of Health Report

  1. Copy/download the latest version of 'installation.sil'
  2. Ensure that the parameters are correct within 'installation.sil', including any new parameters not in previous versions.
  3. Click the Check button, then the Save button
  4. Click the Run button

The old version will be uninstalled as part of the update.



Advanced Installation

A System Integrity report is also available in the Health Report. It requires that Health Report be able to access Jira's database. Below are steps to update the configuration.

Configure Database

  • Go to Jira Administration --> Add-ons --> Datasources
  • Click + Add Datasource
  • Fill in the Create datasource screen with information about the Jira database
    • This information can be found in JIRA HOME/dbconfig.xml
  • Click the Test button to test the configuration
  • If there are no errors, click the Save button

Datasource

Update Installation to use Database

  • Repeat the first 4 steps from Installation
  • Update the following additional parameters
    • useDatabase - Set to true. Determines if a database connection is required for installation of Health Report.
    • dataBaseType - The type of database. Example: Postgres, MySQL, SQL Server, Other/
    • dataBaseSchema - A schema used by the SQL queries. May be required in MS SQL Server installations. POSTGRES and MySQL does not require.
    • dataSourceName - The name of the data source of a connection to the Jira database from Configure Database.

Advanced Configuration

Additional configurations can be done in the CSV files of the report. The CSV files exist in HealthReport/csvFiles and end in '_custom.csv'. Updating the various custom CSV files allows administrators to alter existing test queries, add additional tests, change the layout of the reports.

IMPORTANT NOTES

  1. If an id is used in the '_custom.csv' file that appears in the corresponding default file, the configuration in the custom file will override the original.
  2. Any information added to the '_custom.csv' files will be preserved as part of Health Report update.
  3. Customizations added to the non- '_custom.csv' files will be removed on the next update of Health Report.

CSV File Break down

  • configs.csv: Main configuration file. Contains main query/filter information that can be used as global reuse in other CSV files queries.
    • id: Unique identifier of the configuration. Name can be used in other queries by using $id of config$. Example: $mainFilter$.
    • name: Name of the configuration .
    • description: Information about config.
    • query: Evaluation to use for the configuration. Typically a JQL query.
    • type: jql or sil. Query type. SIL will eventually execute a provided SIL script for test.
    • filterId: The id of a JQL filter. If this value is present it will be used instead of the query provided.
  • Checks_custom.csv: The tests to be run as part of the agile evaluation.
    • id: Unique identifier of the test.
    • name: Name of the test that appears in the report.
    • query: Evaluation to use for the test. Typically a JQL query.
    • type: jql or sil. Query type. SIL will eventually execute a provided SIL script for test.
    • section: The unique identifier the test should appear in the report. See sections.csv.
    • metic: The unique identifier of the metric used to evaluate the results of the query against. See metrics.csv.
    • disable: Set to 'true' if the check should be skipped during execution.
    • description: A short summary of what the check is testing.
  • metics_custom.csv: The evaluatation results used to determine if a test has passed or failed.
    • id: Unique identifier of the metric.
    • name: Name of the metric.
    • query: Main body of the metric. Either a JQL query OR a SIL script with parameters. If a SIL configuration, parameters can be passed by using "|" separators, where the first value is the location of the SIL script to run and all other values parameters required to execute the script. All SIL scripts MUST return a numeric value for evaluation.
      • Example: ./HealthReport/metricScripts/sprintMetric.sil|parmeter1|parameter2
    • type: States the type of metric. jql OR sil.
    • value: Default value of metric execution.
    • lower_threshold: Minimum value the metric must have to pass.
    • upper_threshold: Maximum value the metric can have to pass.
  • sections_custom.csv: Produces a section layout that tests will appear in a report. Report sections will appear in the order they appear in CSV.
    • id: Unique identifier of the section.
    • name: Name of the section as it appears in the report.
    • description: Information about section.
    • disable: Set to 'true' if the section should be skipped during execution.

Test Advanced Configuration

Follow the steps from Execute Health Report to generate a new report with the updated configurations.

  • No labels