Windows Installation

1. Download the OS and architecture-specific ZIP archive
2. Extract the zip into a folder, e.g. C:\list_import\
3. Open conf.json and add the necessary configuration
4. Open a Command Prompt as Administrator
5. Change directory to the folder containing the utility: C:\list_import\
6. Run a dry run to validate your configuration before importing:

goHornbillSimpleListImport.exe -dryrun=true

Example Configuration File

{
  "HBConf": {
    "APIKeysKeysafeID": 1
  },
  "AppDBConf": {
    "Driver": "mysql",
    "KeysafeKeyID": 2,
    "Encrypt": false
  },
  "Lists": [
    {
      "SQL": "SELECT val, disp FROM swlists",
      "Rebuild": false,
      "Application": "com.hornbill.servicemanager",
      "ListName": "someList",
      "ItemValue": "[val]",
      "DefaultDisplay": "[disp]",
      "Translations": [
        {
          "Language": "en-GB",
          "Display": "[disp]"
        }
      ]
    }
  ]
}

HBConf

Connection information for the Hornbill instance:

• APIKeysKeysafeID — The integer ID of a Keysafe entry of type API Key. This key is used to authenticate all API calls made to your Hornbill instance into the Simple Lists. The Keysafe entry must contain a valid API key created against a user account with sufficient rights.

Your Instance ID and API key are stored securely in an encrypted import.cfg file created on first run — they are not stored in conf.json. See On First Run.

AppDBConf

Connection information for the database (direct or via ODBC) that contains the data to import:

• Driver — The driver to use when connecting to the database:
  • swsql — Supportworks 7.x SQL (MySQL v4.0.16). Also supports MySQL v3.2.0 to <v5.0
  • mysql — MySQL Server v5.0 or above, or MariaDB
  • mssql — Microsoft SQL Server (2005 or above)
  • odbc — An ODBC connection on the machine performing the import
  • csv — An ODBC connection using the Microsoft Access Text Driver, configured to point at a folder containing CSV files
• KeysafeKeyID — The integer ID of a Keysafe entry of type Database Authentication. This entry holds the server address, database name, username, password, and port used to connect to your data source.
• Encrypt — Boolean. Whether the connection between the tool and the database should be encrypted. Note: There is a known bug in SQL Server 2008 and below that causes the connection to fail when encryption is enabled. Only set to true if your SQL Server has been patched accordingly.

Database Authentication Keysafe Entry

The Keysafe entry referenced by AppDBConf.KeysafeKeyID must be of type Database Authentication and contain the following fields:

Lists

A JSON array of objects, each defining a Simple List to populate:

• SQL — The SQL query to retrieve data from the configured data source
• Rebuild — Boolean. If true, the specified list will be deleted in its entirety before new items are inserted
• Application — The technical application name for which the Simple List items are to be added (e.g. com.hornbill.servicemanager for Service Manager)
• ListName — The name of the Simple List within the application. The list will be created if it does not already exist
• ItemValue — The value for each list item. Must be unique within the list; items with duplicate values will be skipped. Use square brackets to reference a column from the SQL result, e.g. [val]
• DefaultDisplay — The display name for each list item. Use square brackets to reference a column from the SQL result, e.g. [disp]
• Translations — A JSON array of translation objects for the display name:
  • Language — The language code (e.g. en-GB). Can be sourced from a SQL column using square brackets
  • Display — The translated display value. Use square brackets to reference a SQL column, e.g. [disp]

Common Errors

• [ERROR] Error Decoding Configuration File:… — Typically caused by a missing quote (") or comma (,) in conf.json. Use an online JSON validator to locate the issue.
• [ERROR] Database Query Error: read tcp … wsarecv: An established connection was aborted… — Most likely caused by incorrect credentials in the Keysafe entry referenced by AppDBConf.KeysafeKeyID. Check the username and password in that entry.
• [ERROR] Database Query Error: driver: bad connection. — As above; verify the database credentials in your Keysafe entry.

Error Codes

v3.0.0 - 2026

See release notes on GitHub.

v2.0.0 - 2025

Initial release