INDEX

Documentation Library

Search for information on Hornbill Documentation.

Filter

Books

All
{{book.title}}
{{book.foundCount}}

Products

{{product.name}} {{docApp.searchFilteredProducts[product.id].returnedCount}}

{{docApp.searchResultFilteredItems.length}} results for "{{docApp.currentResultsSearchText}}" in {{docApp.searchFilterBySpecificBookTitle}}

{{resultItem.title}}

{{resultItem.url}}

{{resultItem.content}}

Have questions about this site?

What is this site?

This website is Hornbill's new product documentation website and is currently under development.
It is intended that all existing and future public-facing documentation we produce will be available to search, browse and share.
Hornbill's current documentation is available at Hornbill Wiki but over time this content will be migrated to this documentation site.
Please feel free to have a look around at any time.

Why has Hornbill created this site?

Hornbill's products have moved on considerably since we introduced it almost 10 years ago. At the time, the MediaWiki tool was sufficient, but we have outgrown it.
Our customers are more enterprise focused and more self-sufficient than ever before, so for 2023 and beyond we have established a new documentation platform and team to drive our documentation initiative forwards.
We are aiming to deprecate the use of Hornbill Wiki for most Hornbill related documentation.
We want to enable our growing partner network with product resources and information, documentation beyond our Wiki approach is required.
We could definitely do with some help, and may even pay for some! If you have domain knowledge and would like to help, please check out our Hornbill Docs Contributor Guide and contact the Hornbill docs team at docs@hornbill.com.

What will this site be good for?

Community contribution will be facilitated, encouraged, and most welcome.
High quality documentation, will be kept up to date as rapidly as our products evolve.
Real-time content search and discovery.
Articles organized into books, books into libraries, creating a more natural and logical structure to our documentation.
Legacy API documentation and various other documentation sources will all be consolidated into a single unified documentation system.
Documentation available in browser as well as printable/viewable as PDF on demand.
Personalized documentation experience, allowing dark/light mode, article subscriptions, social media sharing and other useful features.
Almost all publicly available documentation on docs.hornbill.com will be open-source and available to fork on GitHub, allowing customers to derive their own custom documentation around Hornbill products should they wish to.

What is the timeline for this site?

We have taken the decision to publish and make available early, there is very little content at this time.
As and when we have completed/usable documentation, it will be published here.
We have a host of additional features we wish to add over time, so please watch this space.
We expect most of our existing documentation should be reviewed/migrated to docs.hornbill.com over the coming months.
The documentation project will be ongoing, will continue to expand, evolve and improve day-by-day.

{{docApp.libraryHomeViewProduct.title || docApp.libraryHomeViewProduct.id}}

{{book.title}}

{{book.title}}

More...

Running an Import

Ultimately, the executable will be scheduled in the Windows task scheduler (see later) but to test, gain confidence, and perform an initial upload of users, the utility can be executed from a command prompt window on an ad-hoc basis. The command used to execute the import can contain several command line arguments.

Command Line Arguments

config - The ID of the import configuration to run.
creds - Defaults to false - Set to true to decrypt and output the API key that is stored locally. The utility will prompt you for your Instance ID, and this can only be decrypted by the user who originally performed the encryption, and only on the same machine that it was encrypted on.
debug - Defaults to false - Set to true to output extra information to the log to aid in debugging issues.
dryrun - Defaults to false - Set to true and the API calls to create and update users will not be run. Instead, the API call request payloads will be output to the log file to aid in debugging.
forcerun - Defaults to false - Set to true to to bypass the existing running job check. This should be used if a previous run did not successfully complete and the utility is reporting that an import is in progress.
workers - Defaults to 3 - Allows you to change the number of worker threads used to process the import; increasing this can improve performance on slow import but using too many workers can have a detriment to the performance of your Hornbill instance while the import is running.

Warning

The forcerun argument should ONLY be used when you are certain that another import is not actively in progress. Running multiple imports simultaneously against the same User records can have unexpected, and likely undesired, effects on the imported data.

First Run

When you first run the utility it will prompt you for two vital pieces of information:

The Instance ID (also referred to as the instance name) can be found in the URL used by your organization to access the Hornbill service:
- https://live.hornbill.com/instanceid (case sensitive).
A valid API key. This needs to be created against a Hornbill user account with enough rights to create and update user accounts. Details on how to create an API key can be found in the Hornbill Platform Fundamentals book.

This information will be encrypted and stored locally on the host computer that will run the utility. For each subsequent import run, the utility will decrypt your instance ID and API key from the client and will use those to make the API calls back into Hornbill as necessary to perform the import.

Important

The authentication information can only be decrypted on the computer (physical or virtual) that the encryption was performed on, and by the user that performed the encryption, so please bear this in mind when scheduling your imports.

First Run Example

The following is an example of how the tool will prompt you for your Instance ID and API Key on the first run of the utility:

Testing Overview

There is no substitute for hands-on experience when becoming familiar with the Hornbill import utilities. The User Import - LDAP utility accepts and understands a number of command line arguments that can be used when running the utility from the Windows command line or PowerShell.

Tip

The most important argument when testing is -dryrun=true. When this is provided, no user create or update requests will be sent to Hornbill. Instead, all create or update requests that would have been made into Hornbill are output to a log file, including input parameters, which provides you with an opportunity to review their content and understand any error messages that may occur.

Below are some high level steps to help you build confidence in your configuration:

In the configuration, specify a filter to target a single user object. It’s good practice to initially test against a single, or small set of, user objects, as this allows the dryrun to complete quicker and there is less log content to review.
Perform a dryrun (by executing the utility along with the -dryrun=true command line parameter) - this allows you to confirm that the configuration is correct and that a connection to your LDAP host can be established, without importing any user data into your Hornbill instance.
Review the commind line output and log file for any errors or warnings, and where necessary check and rectify any errors against the Common Error Messages listed in the Troubleshooting LDAP User Imports section of this book.
Continue with dryrun tests until you are happy that all the errors are accounted for.
Perform a live import against a single user object (set -dryrun=false).
Review the imported user account in Hornbill and check all user properties are as expected i.e. email contains an email address etc.
Where necessary, adjust the configuration user property mappings
Loop through steps 5 - 7 as many times as is necessary until you are happy with the information being transported into the Hornbill user account properties.
Amend the UserFilter and/or the scope of the Search variable to target the user objects required for a full import.
Perform a dryrun
Review the commind line output and log file for any errors or warnings, and where necessary check and rectify any errors against Common Error Messages listed in the Troubleshooting LDAP User Imports section of this book.
Continue with dryrun tests until you are happy that all the errors are accounted for.

Command Line Examples

ldap_user_import.exe -config="hornbill-ad-import-for-new-and-active-users" -dryrun=true

.\ldap_user_import.exe -config="hornbill-ad-import-for-new-and-active-users" -dryrun=true

Resetting Encrypted Credentials

Should you wish to use a different Instance ID or API key to what has been previously encrypted, then simply delete the import.cfg file from the folder where the import binary resides. Once you re-run your import from the command line, the utility will again ask for the Instance ID and API Key details just as it would have on its first run.

In This Document

{{docApp.title}}

{{docApp.description}}