Introduction

After you add a source system, you need to configure it. This article covers the configuration and management options that are common to all source systems. For information about a specific source system, please see the other articles in this section or use the search feature.

Manage a source system

On the Source Systems Overview, find the source system that you wish to configure and select its wrench icon. This will take you to the configuration screen for that system.

The configuration screen's tabs are documented below.

Common source system tabs

General

The General tab allows you to update the name and description of the source system.

System

Under the System tab, you can modify the details of HelloID's connection to the system. These details vary between source systems. For the PowerShell source system, see Configure a custom PowerShell source system.

Person / Contract

The Person tab lets you configure how personnel data from the source system is mapped onto fields within HelloID Person records. Likewise, the Contract tab lets you configure how employment and contract information is mapped onto these same Persons. The two tabs work very similarly.

Each field (1) can contain a Fixed (static) value, a Field value pulled directly from the source data, or a Complex value. Complex values are calculated by JavaScript that is run during the import. Learn more about complex field mappings here. Each field also has a Require this field toggle. This toggle's functionality is described in the Blocked persons section. Each custom field has a Convert Value To String toggle. You must enable this toggle if you plan to use the custom field to determine the primary contract.

Preview the the field mappings by selecting a Person from the preview tool (2). On the Contract tab, use the < and > buttons to page between contracts.

Additional fields can be added with the Map additional field tool (3). They are appended to the end of the field list. Learn more about the Map additional field tool here.

Export or import a JSON definition of your mappings using the Export and Import buttons (4), to easily clone them to another source system. Learn how to clone mappings here.

Contracts

Contracts are sub-objects within Persons objects. They contain the person's employment details. Each person object can contain zero, one, or multiple contracts. Each contract specifies a single term/position of employment, including job title, start date, end date etc. They include departments as sub-objects.

You build contract objects in source mappings, based on raw contract data imported as part of the persons import script, as well as raw department data imported via the departments import script.

You can use contracts in the following ways:

In conditions of business rules, to narrow the scope of a business rule.
In target system mappings (e.g., in accounts scripts of PowerShell target systems, or Active Directory / Azure AD Target mappings).
In sub-permissions, to dynamically select sub-permissions based on the contract(s) that are currently in-conditions of the associated business rule.

In fields which support double curly brace syntax, access contract objects using {{Person.Contracts.#.}}. In PowerShell code, access the primary contract object using $p.PrimaryContract..

Raw data

The Raw data tab lets you see the most recent data that HelloID has imported from the source system, without any modifications, filters, or mappings. This is useful for troubleshooting, as you can see the data in an untouched state.

Thresholds

The Thresholds tab lets you automatically block imports when the amount of added, removed, or blocked Persons exceeds a specified value. When an import occurs for a source system and the amount of activity exceeds a threshold, the import is blocked until manually approved. In this way, thresholds function as safety nets. They reduce the likelihood of a major mistake in the provisioning process if a source system contains bad or missing data.

You can set separate thresholds for added, removed, and blocked Persons using the respective Enabled toggles. Thresholds can be specified in absolute (count) or relative (percentage) terms and are triggered on an equal-to-or-greater-than basis. If you set both absolute and relative thresholds, they are evaluated with OR logic.

When a threshold is triggered during an import, warnings are shown on the source systems overview screen. A new snapshot is created with a Blocked import.

To manually override the threshold block, select the yellow Approve import button and select the Yes button on the confirmation dialog box. This approves the Blocked import (without performing a new import).

Note that thresholds are triggered before any Persons are imported. For example, if an addition threshold is set to 10 Persons but 100 new Persons are present, zero Persons will be imported (rather than 10 being imported and the remaining 90 being blocked).

Blocked persons

Each mapped field on the Person and Contract tabs has a Require this field toggle. When this toggle is turned on, any Person with an empty mapping for that field will not be imported.

Instead, Persons blocked in this way are listed on the Blocked persons tab. (This tab does not list Persons blocked by Addition or Removal thresholds.)

Select a Person from the left-hand list to see which fields failed validation:

To see a side-by-side comparison of raw and mapped data, select the report icon button next to Validation results:

There are two ways to resolve blocked Persons:

Fix the original personnel data in your external source system, or;
Fix the field's mapping on the Person or Contract tab, so that the produced value is no longer empty.

After doing so, perform a manual import. If successful, the blocked Persons will no longer be listed on this tab.

Note that when Person(s) are blocked in this way, the rest of the import proceeds normally. Unaffected Persons are still imported. This works in contrast to thresholds which, when triggered, block the entire import. You may, however, create thresholds for blocked Persons if you wish to block the entire import when a certain number (or percentage) of Persons are individually blocked due to empty mappings. To do so, use the Blocked Persons toggle on the Thresholds tab.

Logging

The Logging tab contains logs from the last three imports. This is useful for debugging your Persons and/or Departments import scripts in custom PowerShell source systems.

This information is also included in snapshot logs.

During manual imports of PowerShell source systems, up to 100,000 logs are kept, at all log levels. During scheduled imports of PowerShell source systems, only 100 log entries are kept, and only entries at the Write-Warning and Write-Error levels.

Perform a manual import

On the Source Systems Overview, select the Start import button for the relevant source system. This fetches raw data from the source system and creates a new snapshot.

When the import finishes, a new snapshot is added to Source > Snapshots.

To schedule a recurring import instead, see Schedule source system imports & enforcements.

Cancel a manual import

To cancel a manual import while it is in progress, select its Cancel import button.

All pending changes are discarded. The system's tile and the corresponding record in Source > Snapshots are marked Cancelled.

Import raw data

To fetch a system's latest data without creating a new snapshot, edit the system and then select the Import Raw Data button.

This populates data into the Person and Contract tabs (as well as the Raw Data tab), so you can test & preview your mappings. It is helpful when you want to experiment with the latest data from your source system, without making any changes to the current set of Persons. In particular, you may want to make liberal use of this feature while you're configuring a newly-added source system.

A complementary feature is manually create a snapshot, which re-applies all source system configurations and mappings to your Persons, without fetching any new data from your source systems.

Delete a source system

If you no longer need or want a source system in HelloID, you may remove it. On the Source Systems Overview, find the source system that you wish to delete and select its trashcan button.

Once removed, the Person records that were imported from that system will be orphaned and slated for removal on the next import.

Manage global source system configurations

On the Source Systems Overview, you will find the Configuration pane. This area allows you to configure settings that apply globally across all source systems. To modify a configuration item, click its wrench icon.

After modifying these settings, create a new snapshot to apply them to your Persons.

Display Name

HelloID supports four different display name patterns for source systems. Each is denoted by one of the following abbreviations.

B
Birth name
P
Partner name
BP
Birth name - Partner name
PB
Partner name - Birth name

You may configure the contents of each of these patterns, or use the provided defaults. If you wish to customize a pattern, you can drag fields from the Person Fields section into any of the text boxes in the Format section, or provide static values. Results can be seen in real time in the Preview section after selecting a person record.

When you are finished with your customizations, select the Save button.

Primary Contract

The primary contracts affects the following:

The primary contract's Manager field determines the person's primary manager, if the primary manager option is set to From Primary Contract.
You can access the primary contract in PowerShell using the shortcut $p.PrimaryContract. instead of having to index into the array (contracts[0]).

To change the primary contract determinant, drag and drop contract fields. For example, if you want start date to be the highest priority determinant, drag it to the top of the list. Use the Ascending/Descending toggles to reverse the sort order for the values of the relevant field.

Custom contract fields are supported, but only for the string data type.

Only active contracts can be primary contracts. If the primary contract determinant would select an inactive contract for a person's primary contract, HelloID automatically chooses the next closest match which is active.

When you are finished with your customizations, select the Save button. Primary contracts of persons will be updated during the next snapshot.

Primary Manager

This area allows you to change how HelloID determines each person's manager. By default, the manager's information is taken directly from the person's contract record. However, you can configure HelloID to be more granular by getting the manager's information from the person's department, or the hierarchy of their departmental structure.