Hornbill Report Runner

From Hornbill
Jump to navigation Jump to search

About the Hornbill Report Runner

This utility provides a quick and easy method of running reports on your Hornbill instance, and retrieving the report output files for storage locally.

The tool will run reports that exist on your Hornbill instance, wait for the reports to complete, then retrieve all files that were created as part of the report run (as defined within the report itself, for example PDF, CSV, XLS etc).

Open Source

The Hornbill Report Runner utility is provided open source under the Hornbill Community Licence and can be found Here on GitHub.

Installation

Windows

  • Download the ZIP archive
  • Extract the ZIP archive into a folder you would like the application to run from e.g. 'C:\hornbill_reporting'.

Configuration

Example JSON File: 

{
    "APIKey": "yourapikey",
    "InstanceID": "yourinstanceid",
    "Reports":[
        {
            "ReportID":6,
            "ReportName":"Change Requests",
            "DeleteReportInstance": true,
            "ReportFolder":"//some/network/drive"
        },
        {
            "ReportID":5,
            "ReportName":"Scheduled Changes",
            "DeleteReportInstance": true,
            "ReportFolder":"//some/network/drive"
        }
    ]
}
  • "APIKey" - A Valid API Assigned to a user with enough rights to run and retrieve the report (case sensitive)
  • "InstanceId" - Instance ID (case sensitive)
  • "Reports" - An array containing objects defining the reports to be run and retrieved:
    • "ReportID" - The integer ID of the report to be run
    • "ReportName" - The name of the report to be run
    • "DeleteReportInstance" - Boolean true or false, to define if the report run instance should be removed after the report run has completed
    • "ReportFolder" - The network or local drive location where you with to save the output report files

Execute

Command Line Parameter: - file This should point to your json configration file and by default looks for a file in the current working directory called conf.json. If this is present you don't need to have the parameter.

'goHornbillReportRunner_x64.exe -file=conf.json'

Preparing to run the tool

  • Open conf.json and add in the necessary configration;
  • Open Command Line Prompt as Administrator;
  • Change Directory to the folder with goHornbillGetReport.* executables 'C:\hornbill_reporting';
  • Run the command:
    • On 32 bit Windows PCs: goHornbillReportRunner_x86.exe
    • On 64 bit Windows PCs: goHornbillReportRunner_x64.exe
  • Follow all on-screen prompts, taking careful note of all prompts and messages provided.

API Key Rules

This utility uses (API keys):

  • reporting:reportRun
  • reporting:reportRunGetStatus
  • reporting:reportRunDelete

Troubleshooting

Logging Overview

All logging output is saved in the log directory, in the same directory as the executable. The file name contains the date and time the import was run reporting_20181004162344.log'

Common Error Messages

Below are some common errors that you may encounter in the log file and what they mean:

  • [ERROR] Error Decoding Configuration File:..... - this will be typically due to a missing quote (") or comma (,) somewhere in the configuration file. This is where an online JSON viewer/validator can come in handy rather than trawling the conf file looking for that proverbial needle in a haystack.

Error Codes

  • 100 - Unable to create log File
  • 101 - Unable to create log folder
  • 102 - Unable to Load Configuration File

HTTP Proxies

If you use a proxy for all of your internet traffic, the HTTP_PROXY and HTTPS_PROXY Environment variables need to be set. These environment variables hold the hostname or IP address of your proxy server. It is a standard environment variable and like any such variable, the specific steps you use to set it depends on your operating system.

For windows machines, it can be set from the command line using the following:
set HTTP_PROXY=HOST:PORT

set HTTPS_PROXY=HOST:PORT
Where "HOST" is the IP address or host name of your Proxy Server and "PORT" is the specific port number. IF you require a username and password to go through the proxy, the format for the setting is as follows:
set HTTP_PROXY=username:password@HOST:PORT

set HTTPS_PROXY=username:password@HOST:PORT

URLs to White List

Occasionally on top of setting the HTTP_PROXY variable the following URLs need to be white listed to allow access out to our network

Scheduling Overview

Windows

You can schedule goHornbillReportRunner_x64.exe to run with any optional command line argument from Windows Task Scheduler.

  • Ensure the user account running the task has rights to goHornbillReportRunner_x64.exe and the containing folder.
  • Make sure the Start In parameter contains the folder where goHornbillReportRunner_x64.exe resides in otherwise it will not be able to pick up the correct path.

Change Log

  • v1.0.0 - 04/10/2018
    • Initial Release
Retrieved from "https://wiki.hornbill.com/index.php?title=Hornbill_Report_Runner&oldid=27608"