Accessing Cloud Data Imports

1. On your keyboard use Shift + Ctrl + s to open the configuration search.
2. Type Cloud data.
3. Select Cloud Data Imports from the results.

or

• Navigate to Configuration > Platform Configuration > Data > Cloud Data Imports.

Add a new import configuration

1. If this is your first import configuration, select the option that says No import configurations are set up. Click here to create your first import. Otherwise, at the top right of the configurations list, click + Add New.
2. Give your import a clear and unique name.
3. Select Create.
4. The form for the new import will be displayed.
5. Under the Details section you can optionally add a Description to explain the purpose of the import.
6. Make note of the Import Enabled toggle. Before an import can run, you will need to toggle this to be enabled.

Note: The Save Changes button will remain inactive until all mandatory Data Source fields have been filled.

Choose a data source

1. Select the Data Source section.
2. In the Import field, select the edit icon.
3. In the Hornbill Integration Bridge dialog, select Cloud Data Imports > Users > Entra ID.
4. Click Apply.
5. The Source / Import Options section appears, with settings you can customize.

Credentials settings

1. In the Data Source section, locate the Credentials Settings section.
2. From the Entra ID User Import drop-down, select the KeySafe entry that you created for this import. If this drop-down is empty, you must go back and create your KeySafe entry before continuing.

Note: The Credentials Settings section is only available after a data source has been selected.

Source/Import Options

This section covers the options available when setting up your Entra ID user import. These settings give you control over what gets imported.

Note: The Source/Import Options section is only available after a data source has been selected.

Mandatory fields

Before you can save the Source/Import Options, the following mandatory fields must be completed:

• Action: Create, Update, or Create and Update.
• Account Status
  • Action: Create or Create and Update.
  • User Status: Active, Suspended, or Archived.
• User Properties
  • User Type: Basic, Full, or Managed Service Provider.
  • User Type Action: Create or Create and Update.
  • User ID
  • Handle
• Profile Picture: No processing, update, or clear.

Query

This is where you can enter a query to limit which users are imported.

• Hornbill uses Microsoft’s Graph API to access Entra ID.
• You can write a query using OData to select specific users based on things like department, email domain, etc.

Here are a few examples:

Resources to help you write queries:

• $filter syntax guide
• List of available user fields

Group ID filter

This is where you can provide additional Group IDs, to further filter the list of users returned by your optional Query (as detailed above).

This is a list of group identifiers, and if each user returned by the query is a member of at least one of the groups, then that user will be processed by the data import job. The following Entra ID group properties are supported:

• id
• displayName
• mail

Fields – Additional

If you need extra fields that aren’t included in the default list, you can enter them here. This is useful for pulling in custom or extension attributes.

Action

Choose what Hornbill should do with the users it finds. This is a mandatory field that must be set.

• Create: Only adds new users who don’t already exist in Hornbill.
• Update: Only updates users who already exist in Hornbill.
• Create & Update: Adds new users and updates existing ones.

Account Status

Set the status of a new or existing user. These are mandatory fields that must be set.

• Action: Choose when this status should be applied.
  • Create: Only adds new users who don’t already exist in Hornbill.
  • Create & Update: Adds new users and updates existing ones.
• User Status: Set the status of the user to Active, Suspended, or Archived.

User Properties

Define how user data should map to Hornbill fields during import.

• Supports Mustache templates for custom formatting or combining data.
• Some input fields offer auto-complete to help you select fields from your Entra ID source. If you know the name of the field you can start typing it, otherwise if you start by typing { all available fields will be displayed for you to select from.
• The User Type, User Type Action, User ID, and Handle fields are mandatory and must be set before you can save the Source/Import Options.

About the Action and User Type Action import options. When you are configuring your import in the Data Source tab, it’s possible to configure the import with some inconsistent options. These won’t cause the import to fail, but it’s important to understand the relationship between some of the options available, as sometimes, in order for one option to be effective, a related option must also be configured in a particular way.

• The Action option is the action to perform for the users returned from your data source. (This is the main Action option). You can choose Create, Update, or Create & Update.

  

• In the User Properties option, there are account details you must specify, including User Type Action. This specifies when an update to the user type should be performed. The options are Create, and Create & Update.

  

  This User Type Action is only relevant when the main action is Create or Create & Update. When the main action is Update, there are no user types to create. While you must select an option, it has no bearing on the import.

Manager mapping and advanced queries

When you map the Manager field in your import configuration, Hornbill automatically requests manager details from the Microsoft Graph API alongside each user record. This is the only way to reliably retrieve manager information without making a separate API call for every user being imported.

However, this has an important consequence: Microsoft Graph does not support advanced queries when manager data is being requested at the same time. Advanced queries unlock additional filter operators and the ability to filter on a wider range of properties.

This means:

• If you do not map the Manager field – advanced queries are fully supported, and you can use the extended filter operators and properties described in the advanced queries documentation.
• If you do map the Manager field – Hornbill automatically includes the manager expand in the API request, and advanced queries cannot be used. Your filter must use only the standard OData operators and filterable properties.

If your filtering requirements need advanced query support, consider whether manager data is essential for your import. If it is not, leave the Manager field unmapped to take full advantage of advanced filtering.

Memberships

About memberships and role assignments

When you are configuring your import in the Data Source tab, there are two essential import options you need to be aware of: group memberships and role assignments.

A user can be assigned a membership to an organizational group. An organizational group in Hornbill can be a Department, Company, or Team. The user’s membership to a group can be set as Member, Team Leader, or Manager.

Profile Picture

Choose what Hornbill should do with the users’ profile pictures it finds:

• No Processing – Ignore the image data.
• Update – Take the image data and make it the user’s profile picture in Hornbill.
• Clear – Use this option to remove the image data in Hornbill during the import.

Note: The Clear option in Profile Picture is only relevant when the main action is Update or Create & Update.

Accessing memberOf data in templates

Since memberOf is an array, you can access its values using Mustache template iteration. For example:

{{#memberOf}}
  Group ID: {{id}}
  Group Name: {{displayName}}
  Group Email: {{mail}}
{{/memberOf}}

This will output details for every group the user is a member of.

Mapping examples

Example 1: Mapping a single group name

If you want the first group name:

{{memberOf.0.displayName}}

Example 2: Mapping all group names as a comma-separated list

{{#memberOf}}{{displayName}},{{/memberOf}}

Example output:

HR Team,Finance,IT,

Example 3: Filtering by group type

Map only mail-enabled groups:

{{#memberOf}}
 {{#mailEnabled}}{{displayName}}{{/mailEnabled}}
{{/memberOf}}

Example 4: Mapping all group IDs

{{#memberOf}}{{id}};{{/memberOf}}

Best practices for mapping using memberOf

• Decide if your field should contain one value (e.g. the first group) or multiple values (e.g. a list).
• Use iteration ({{#memberOf}}...{{/memberOf}}) for handling multiple groups.
• Be aware of trailing separators (commas, semicolons) when concatenating multiple values.
• Some fields (like mailEnabled and securityEnabled) are boolean flags — useful for filtering, not direct mapping.

With these patterns, you can flexibly map group membership information from Entra ID into your Hornbill user fields.