Windows

• Download the archive containing the import executables
• Extract zip into a folder you would like the application to run from e.g. C:\hornbill_contact_processing\
• Open conf.json and add in the necessary configuration
• Open Command Line Prompt as Administrator
• Change Directory to the folder containing the extracted files C:\hornbill_contact_processing\
• Run the command relevant to the computer you are running this on:
  • process-registered-contacts.exe -dryrun=true

Host

The program that performs the import is fairly lightweight and doesn�t require much in the way of hardware to run. It can be run on virtualized or physical hardware running any version of Windows currently supported by Microsoft, but basic guidelines are as follows:

• Operating System - Microsoft Windows, 32 or 64-bit, current/LTS, desktop/server
• CPU - Intel-compatible, one or more cores
• RAM - 4GB minimum

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 hostname 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 and HTTPS_PROXY variables, the following URLs may need to be white-listed to allow access out from your network to the required endpoints in the Hornbill network:

• https://files.hornbill.com/instances/INSTANCENAME/zoneinfo - Allows access to lookup your Instance API Endpoint
• https://files.hornbill.co/instances/INSTANCENAME/zoneinfo - Backup URL for when files.hornbill.com is unavailable
• https://mdh-p01-api.hornbill.com/INSTANCENAME/xmlmc/ - This is your Instance API Endpoint, where mdh-p01-api is specific to your region and instance. See the API Concepts documentation for more information.
• https://api.github.com/repos/hornbill/asset-rel-import/tags- Allows the utility to self-update. Optional
• https://\*.hornbill.com/\* - allows access to the required Hornbill instance information and API endpoints
• https://api.github.com/repos/hornbill/\* - allows the utility to self-update

User

Every action within Hornbill must be performed in the context of a user account. The user account must possess roles for the platform and applications that you are granting access to via the import utility. The above comment about roles refers to the Hornbill Security Model when associating roles with user accounts. This security measure prevents you from inflating your session rights or granting a user more rights than you have yourself.

Contact Admin - Allows the utility to update and remove Contact records.

API Key Rules

This utility requires access to the following Hornbill Platform APIs, and your API Key rules should reflect those, plus additional security hardening in the form of IP rules:

admin:contactDelete
admin:portalAccountGetContacts
admin:portalSetContactAccess
bpm:autoTaskRun
data:entityUpdateRecord
system:logMessage

bpm:autoTaskRun is only required if you use the SummaryAutoTask functionality.

Domain Black List

DomainBlackList - array of strings - listing any blacklisted domains. Registered contacts with email addresses from these domains will be deleted.

Domain White List

DomainWhiteList - array of strings - listing any whitelisted domains. Registered contacts with email addresses from these domains will automatically be approved with their email address set as their login id and taking on the setting of MFA as determined in the configuration file.

Multi Factor Authentication

MFA - What form of Authentication the registered contact should use.

• 0: Disabled (default) - the password set on registration is to be used.
• 1: Email
• 2: Authentication App

Summary Auto Task

SummaryAutoTask - string - The name of the ( servicemanager ) Global AutoTask to be triggered.

The AutoTask will need the following Inputs:

• dryrun - boolean - whether the utility is run in dryrun mode. One would probably want to put some logic in the AutoTask to ignore dryruns.
• errorCount - integer - amount of errors which occurred during the running of the utility.
• skipCount - integer - amount of registered contacts which were skipped (i.e. are still registered - and to be manually progressed). One would probably want to monitor this, for instance notifying an individual if there are (a certain amount of) results here.
• removalCount - integer - amount of registered contacts which have been removed (because their domains were blacklisted).
• registeredCount - integer - amount of registered contacts which have been approved (because their domains were whitelisted).

Command Line Parameters

• file - Defaults to conf.json - Name of the Configuration file to load
• dryrun - Defaults to false - Set to True and there won’t be any changes to the contacts. The log file WILL contain what the utility would have done, this is to aid in debugging the initial connection information.
• debug - Defailts to false - set to true to increase debug logging output
• concurrent - defaults to 1. This is to specify the number of requests that should be imported concurrently, and can be an integer between 1 and 10 (inclusive). 1 is the slowest level of import, but does not affect performance of your Hornbill instance, and 10 will process the import much more quickly but could affect performance.
• version - shows version of tool (and ends)
• logprefix - Add prefix to log file
• creds - defaults to false - Returns stored API Key and ends")

Testing

If you run the application with the argument dryrun=true then no requests will be logged - the XML used to raise requests will instead be saved in to the log file so you can ensure the data mappings are correct before running the import.

process-registered-contacts.exe -dryrun=true

Logging

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 ‘Contact Registration Processor 2025-08-07T16-03-47+01-00.log’

Error Codes

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