Hornbill Clean Utility

About the Hornbill Clean Utility

The utility provides a quick and easy method of removing all request and/or asset records from a specified Hornbill instance.

WARNING

This utility permanently deletes all request and/or asset records from a specified Hornbill instance, and records of entities that are associated to the deleted requests/assets. It is intended to be used only by an administrator of a Hornbill instance at the appropriate stage of the switch-on process, to remove demonstration and test data prior to go-live.

This utility SHOULD NOT be used to delete request or asset data from Hornbill Instance that holds production data!

Open Source

The Hornbill Cleaner Utility is provided open source under the Hornbill Community Licence and can be found Here on GitHub

Installation Overview

Windows Installation

• Download the archive containing the cleaner executable, configuration file and license;
• Extract the ZIP archive into a folder you would like the application to run from e.g. 'C:\hornbill_cleaner\'.

Configuration Overview

The configuration of this utility is managed through a JSON file (conf.json), which is supplied with each release:

"UserName": "admin",
"Password": "password",
"URL": "https://eurapi.hornbill.com/instancename/xmlmc/",
"CleanRequests": false,
"CleanAssets": false,
"RequestClass": "Change Request"

• UserName: This is the username which will be used to connect to your Hornbill instance. This user should have the appropriate roles associated to it, to be able to remove request and asset entity records.
• Password: This is the password for the supplied username.
• URL : This is the url of the API endpoint of your instance. It must be https, and include /xmlmc/ at the end of the url. You must replace "instancename" with the name of your Hornbill instance.
• CleanRequests : Set to true to remove all Service Manager Requests (and related entity data) from a Hornbill instance
• CleanAssets : Set to true to remove all Assets (and related entity data) from a Hornbill instance
• RequestClass : Specify the class of the requests you wish to delete

Running the utility

When you are ready to clear-down your request and/or asset records:

• Open conf.json and add in the necessary configration;
• Open Command Line Prompt as Administrator;
• Change Directory to the folder with hornbillCleaner.exe 'C:\hornbill_cleaner\';
• Run the command:

hornbillCleaner.exe

• Follow all on-screen prompts, taking careful note of all prompts and messages provided.

Post Utility Actions

After the Hornbill Clean Utility has been run successfully, there are a couple of things to consider:

Hornbill Actions

After the Hornbill Clean utility has been run successfully, you should contact Hornbill to allow us to perform our final checks to ensure all data has been correctly removed from all the database tables.

To do this, please contact us via our [[1]] (we will require the Primary or Secondary Technical Support contact on our records to be able to submit this). Once Hornbill have completed the final post-cleardown checks, we will let you know to confirm.

Resetting Application Auto Values

After the Hornbill Clean utility has been run successfully, you may like to reset the relevant application Auto Values such as the request reference number. This is not essential, more a personal preference.
The Application Auto Values can be reset via Hornbill Administration > Home > System > Data > Auto Values.

• itsmRequestsAutoId - Request Reference Number
• itsmAssetAutoId - Asset Auto ID

Click the "Reset Counter" button to reset the Auto Value

Command Line Parameters

• -file - This is the name of the Configuration file to load. If this parameter is not specified, by default the utility will look for `conf.json'
• -blocksize x - Where x is the number of records that should be retrieved and deleted as "blocks". If this parameter is not specified, the default is 3, and under normal circumstances this should not need to be overridden.

Trouble Shooting

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

• SQL Query was unsuccessful - this occurs when the utility is prevented from running the query to obtain the list of requests to delete. This happens when the system setting security.database.allowSqlQueryOperation is set to false (OFF). To successfully run the utility, this setting must be set to true (ON). It can be found in Hornbill Administration > System > Settings > Advanced, and filter on "security".

Logging Overview

All logging output is saved to the Hornbill instance, in a log called Hornbill_Clean, and can be accessed from within the Hornbill Administration tool.

HTTP Proxies

If you use a proxy for all of your internet traffic the HTTP_PROXY Environment variable should be set in the command line using the following:

set HTTP_PROXY=HOST:PORT

Change Log

• v1.0.3 - 03/08/2016
  • Features:
    • Added parameter within configuration file, to specify class of requests to delete
    • Improved performance of request deletion
    • Improved error output to display

• v1.0.2 - 08/06/2016
  • Features:
    • Reduced record block size default down to 3
    • Improved logging output

• v1.0.1 - 12/05/2016
  • Features:
    • Reduced record block size default down to 20
    • Added flag to allow default block-size to be overridden at runtime

• v1.0.0 - 10/03/2016
  • Initial Release