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.
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.
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
Because employees may work at more than one location at a time, or have more than one contract, it's important that HelloID be able to determine each person's primary contract. Information from this primary contract can be used a number of ways, such as determining which OU an account should be created in, the value of a job title attribute, and so on.
If you need to change the logic, you may drag and drop fields or change their sorting order accordingly. For example, if you want start date to be the highest priority determinant, drag it to the top of the list.
When you are finished with your customizations, select the Save button.
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.
When you are finished with your customizations, select the Save button.
