Source/import options

Here’s a breakdown of the options available when setting up your Entra ID user import. These settings give you control over what gets imported, when, and how.

KeySafe Key

Choose the KeySafe Key you created earlier. This is what allows Hornbill to securely access your Entra ID account.

Query (Optional)

This is where you can enter a filter to limit which users are imported. Make sure you understand the ways of filtering the data you import.

• 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.

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

• 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 the users being imported (e.g. Active, Inactive), and choose when this status should be applied.

User Properties

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

• Supports Mustache templates for custom formatting or combining data.
• Input fields offer auto-complete to help you select fields from your Entra ID source.

Memberships

This section lets you assign imported users to organizational groups in Hornbill.

• Action – When should the user be added to the group?
  • Create – Add user only during Create actions.
  • Update – Add user only during Update actions.
  • Create & Update – Add user during both.
  • Unassign if Assigned – Remove user from the group if already assigned.
• Organization ID – The ID of the group you want to assign.
• Membership – Choose one:
  • Member
  • Team Leader
  • Manager
• Can View Tasks – Should this user be able to see tasks for the group?
• Can Action Tasks – Should this user be able to work on tasks?
• Single Assignment per Group Type – Ensures the user belongs to just one group per type, removing them from others of the same type.

Role Assignments

Assign roles to users as part of the import process.

• Action – When should the role be assigned or removed?
  • Create – Assign role only when the user is newly created.
  • Update – Assign role only during updates.
  • Create & Update – Assign during both.
  • Unassign if Assigned – Remove role if the user already has it.
• Role – The name of the role to assign.

Filter by department

To import only users from the Application Development department:

department eq 'Application Development'

Filter by email domain

To import users whose email address ends with @hornbill.com:

endswith(mail,'@hornbill.com')

Combine filters

You can also combine filters. For example, to bring in users who both:

• Have an email address ending in @hornbill.com and
• Work in the Application Development department:

endswith(mail,'@hornbill.com') and department eq 'Application Development'

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.