Documentation
    {{docApp.userSession.userId}}
    {{docApp.userSession.userName}}
    {{docApp.userSession.email}}
    Issuer : {{docApp.userSession.issuerInstance}}
    Expires : {{new Date(docApp.userSession.validUntil).toLocaleDateString()}}

{{docApp.title}}

{{docApp.description}}

INDEX

Documentation Library

Search for information on Hornbill Documentation.

{{docApp.searchError}}

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

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}}

{{docApp.libraryHomeViewProduct.description}}

  1. {{book.title}}

{{group.title || group.id}}

{{group.description}}

  1. {{book.title}}

{{group.title}}

{{book.title}}
More...

Authentication

The Asset Import utility uses API Keys to authenticate all API calls into Hornbill instances, and KeySafe to securely store credentials for the asset data source.

API Keys

For the utility to read, create and update records via the Hornbill API, it requires an API Key to be securely stored alongside the client.

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.

Important

We strongly recommend that you create a Service Account in your Hornbill instance, and API Keys against that account which can then be used to perform the required API calls back into Hornbill.

Please read the API Key documentation and best practice guide before creating API keys against your user records.

The service account that you create must be of type User (not Basic), and be granted the following roles:

  • User Role - Allows the utility to perform entity actions in the Hornbill platform.
  • Asset Management User - Allows the utility to create and update Asset Management records in Service Manager.
  • Hornbill Service Manager Integrations - Grants several privileges for access to entities and the execution of stored queries. NOTE - This role is only intended for accounts that are used for integrations or to perform data imports, and should not be applied to interactive user accounts.

API Key Rules

The Asset Imports require access to the following Hornbill Platform and application APIs, and your API Key rules should reflect those, plus additional security hardening in the form of IP rules:

admin:getApplicationList
admin:groupGetList2
bpm::iBridgeInvoke
data:entityAddRecord
data:entityBrowseRecords2
data:entityDeleteRecord
data:entityUpdateRecord
data:queryExec
session:getApplicationList
system:logMessage
apps/com.hornbill.core:getSitesList
apps/com.hornbill.suppliermanager/SupplierAssets:addSupplierAsset
apps/com.hornbill.suppliermanager/SupplierContractAssets:addSupplierContractAsset

KeySafe

For the import utility to access data from your source database, authentication credentials are required to be stored in KeySafe.

Note

We recommend that you read the KeySafe documentation before storing credentials in KeySafe.

Once the relevant key has been created, you can then lock access to it down to the API Key created against your service account. See the KeySafe documentation for more information regarding this.

Important

When you have created your KeySafe Key, note down the KeySafe Key ID which can be found in the URL when you are on the key details form in your browser, as this will be needed when configuring your imports. In the example below, 4 is the KeySafe Key ID:

https://live.hornbill.com/yourinstanceid/admin/platform/security/keysafe/4/

Key Types

As the Asset Import utility supports the import of asset data from many different data sources, it must therefore also support many different KeySafe Key types:

  • Azure Resource Query - Used for the following data sources:
    • azureresourcequery - Azure Resource Query, including data from Azure Arc.
  • Certero - Used for the following data sources:
    • certero - Certero IT Asset Management.
  • Database Authentication - Used for the following data sources:
    • mssql - Microsoft SQL Server (2005 or above).
    • mysql - MySQL 4.1 or above, or any version of MariaDB.
    • mysql320 - MySQL Server v3.2.0 to v4.0.
    • odbc - ODBC driver.
    • swsql - Supportworks SQL (Core Services v3.x).
  • Google Workspace - Used for the following data sources:
    • google - Google Workspace Enterprise Chrome OS.
  • LDAP Authentication - Used for the following data sources:
    • ldap - LDAP data sources (including Active Directory).
  • Username + Password - Used for the following data sources:
    • nexthink - Nexthink.
  • VMWare Workspace One UEM - Used for the following data sources:
    • workspaceone - VMware Workspace One UEM.

Tip

The csv - CSV / Text file(s) data source reads its data from the file system (local or network), and therefore does not require Keysafe keys.

Key Type - Azure Resource Query

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of Azure Resource Query.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Click Create Key.
  • Once the Key is created, you will need to connect to Azure Resource Query and your account, in order to authorize the Hornbill App to perform the listed Azure Resource Query options. Click Connect and you will be redirected to the Azure authentication page in a popup window.
  • Log in to your Azure Resource Query account, and then you will be prompted to review the operations you are authorizing the Hornbill App to be allowed to perform with the chosen Azure Resource Query account.
  • Review the scopes/permissions, and click Continue. You will then be returned to your KeySafe key.

Key Type - Certero

Keys of this type require a Certero API Key to be created against a user account that has permission to fetch assets before the details can be stored in KeySafe, and eventually be used by the Asset Import Utility.

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of Certero.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Populate the following fields on the form:
    • API Key Name - The username for the API Key associated with a user account that has permission to fetch assets.
    • API Key - An API Key associated with a user account that has permission to fetch assets``.
    • API Endpoint - The API Endpoint for your Cerero account.
  • Click Create Key.

Key Type - Cynerio

Keys of this type require a Cynerio API Key to be created against a user account that has permission to fetch assets before the details can be stored in KeySafe, and eventually be used by the Asset Import Utility.

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of Cynerio.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Populate the following fields on the form:
    • Access Token URL - Your Cynerio account-specific authentication URL, in the format: https://your-portal-login.cynerio.com
    • API URL - Your Cynerio account-specific API endpoint URL, in the format: https://your-cynerio-account.cyner.io
    • Client ID - The Client ID for your Cynerio integration application
    • Client Secret - The Client Secret for your Cynerio integration application
  • Click Create Key.

Key Type - Database Authentication

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of Database Authentication.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Populate the following fields on the form:
    • Server - The IP address or hostname of your database host.
    • Port - The port used to connect to your database.
    • Database - The database name/ID.
    • Username - The username of the account that should be used to authenticate the connection to your database.
    • Password - The password for the above account.
  • Click Create Key.

Key Type - Google Workspace

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of Google Workspace.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Click Create Key.
  • Once the Key is created, you will need to connect to Google Workspace and your account, in order to authorize the Hornbill App to perform the listed Google Workspace options. Click Connect and you will be redirected to Google Workspace in a popup window.
  • Log in to your Google Workspace account, and then you will be prompted to review the operations you are authorizing the Hornbill App to be allowed to perform with the chosen Google Workspace account.
  • Select the scopes/permissions relevant to the import, and click Continue. You will then be returned to your KeySafe key.

Key Type - Microsoft Intune

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of Microsoft Intune.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Click Create Key.
  • Once the Key is created, you will need to connect to Microsoft and your account, in order to authorize the Hornbill App to perform the listed Intune options. Click Connect and you will be redirected to Microsoft in a popup window.
  • Log in to your Microsoft Intune account, and then you will be prompted to review the operations you are authorizing the Hornbill App to be allowed to perform with the chosen Intune account.
  • Select the scopes/permissions relevant to the import, and click Continue. You will then be returned to your KeySafe key.

Key Type - LDAP

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of LDAP Authentication.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Populate the following fields on the form:
    • Host - The IP address or hostname of your LDAP host.
    • Port - The port to access your LDAP through. 389 (LDAP) and 636 (LDAPS) are commonly used values.
    • Username - The username of the account that should be used to authenticate the connection to your LDAP.
    • Password - The password for the above account.
  • Click Create Key.

Key Type - Username + Password

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of Username + Password.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Populate the following fields on the form:
    • Username - The username of the account that should be used to authenticate the connection to your account.
    • Password - The password for the above account.
    • API Endpoint - The service API endpoint.
  • Click Create Key.

Key Type - VMWare Workspace One UEM

VMware Workspace One UEM requires an oAuth Client to be created before the details can be stored in KeySafe, and eventually be used by the Asset Import Utility. See the VMware client creation documentation for more information.

  • In Hornbill, navigate to Configuration > Platform Configuration > KeySafe.
  • Click + Create New Key.
  • Choose a key type of VMWare Workspace One UEM.
  • Give the KeySafe key a Title.
  • Optionally add a Description.
  • Populate the following fields on the form:
    • Domain - The Domain with your Workspace One UEM domain, for example, https://cn1498.awmdm.com.
    • Region - The region ID where your VMware Workspace One UEM account is hosted. This can be found in the VMware Workspace One UEM URL, for example, emea.
    • Client ID - The Client ID of your VMware oAuth Client.
    • Client Secret - The Client Secret of your VMware oAuth Client.
  • Click Create Key.
  • Version {{docApp.book.version}}
  • Node {{docApp.node}} / {{docApp.build}}
In This Document