Scenario Personal
What this scenario does
Synchronise the employee's personal information.
This is the scenario that creates a new employee in Nmbrs when someone starts in HiBob,
so every other scenario depends on it.
Before you start
- HiBob authorisation is set up (see the HiBob Authorization Guide).
- Nmbrs authorisation is set up (see the Nmbrs Authorization Guide).
- Debtor + Company are configured on the interface's Configuration tab.
Setup
A Setup walkthrough by a BrynQ engineer
This recording is a snapshot in time; the BrynQ UI or template may have shifted slightly since.
Step 1: Verify the unique key
Core concepts:
Summary
The unique key are fields used to identify each employee when comparing HiBob and Nmbrs.
Using the unique key, the interface determines whether to create or update that employee in Nmbrs.
Important:
If both systems already contain employee data, make sure the data of unique key values match exactly before activating the interface. The interface treats a different key value as a completely new employee, not as an update.
In Brynq you can review the unique key by looking at the record with the key highlighted in blue.
The Standard (recommended setup)
By default, the unique key is HiBob's Employee ID, found under the Work section of the employee profile.
In Hibob it corresponds to this field:
In Nmbrs, it corresponds to this field:
What you need to do:
Using this configuration, there is nothing you need to do in BrynQ.
Only verify that the HiBob Employee ID matches the Nmbrs employee number for each employee for already populated systems.
Tip: to match employees across both systems, use a shared field such as email address or BSN as a reference. This is fine for a one time check.
Custom setup - when to deviate from the recommended setup
It may occur that the 'Employee ID' field in Hibob is not suitable for your environments, and instead you have set up a custom field in Hibob to identify unique employees.
This could be because your environment spans multiple entities and you need one overarching custom identifier.
In this case, take the following steps in BrynQ:
- Remove 'Work Employee ID' by clicking the cross.
- Change the source field type to custom.
- Select the custom field as the primary key.
FAQ
1. Can we use other standard fields, like the email, as the unique key?
No, always use a dedicated field in hibob that matches with Nmbrs' "employee number" field.
2. Why can we not use another standard Hibob field and a different Nmbrs field to identify unique employees
Other fields are not reliable employee indicators. For example, emails are not reliable because its domain may change.
Or a typo or format differnce in the BSN could lead to new employees to be created, which is not the intended consequence.
3. What do I need to do if I use the standard fields and my data for the unique keys are aligned?
Nothing, you are set up.
Step 2: Verify Value mappings (draft from this point)
Value mappings translate a HiBob label into the code Nmbrs expects. They live on the individual records inside this scenario and are pre-populated by BrynQ.
Records with a value mapping: Gender, Nationality.
Only touch a value mapping if the run report flags an unmapped value - that is the one signal that the map has a gap for you.
Typical value-mapping examples. These are dummy input-output pairs to show the shape; your interface's mapping is set by BrynQ during onboarding and may include more or fewer entries.
personal_nationality in HiBob → nationality_code_iso in Nmbrs
American | → | US |
Australian | → | AU |
Basotho | → | LS |
Belarusian | → | BY |
Belgian | → | BE |
Bissau-Guinean | → | GW |
Brazilian | → | BR |
British | → | GB |
(more input-output pairs typically appear; open the interface's Mapping tab for the full list.)
home_legal_gender in HiBob → gender in Nmbrs
Female | → | female |
Male | → | male |
Non-binary | → | unspecified |
Other | → | unspecified |
(more input-output pairs typically appear; open the interface's Mapping tab for the full list.)
What happens behind the scenes
These are the things the scenario does between HiBob and Nmbrs beyond a straight copy. You do not configure them - they are baked into the template - but knowing them helps you recognise what you see in the run report.
Some rows are filtered out
- The scenario ignores rows that would not make sense in Nmbrs (for example, non-payroll employees, or contracts that were cancelled before they started).
Employees keep syncing even if a value is missing
- The scenario still writes the record even when the source value is empty or not recognised - the missing value is reported, but the rest of the employee still moves through.
The value is filled in when HiBob leaves it blank
- When HiBob does not supply a value, the scenario writes a sensible default so Nmbrs still accepts the record.
The value is broken up before it is sent
- The scenario splits one HiBob string into the separate pieces Nmbrs stores (for example the address line into street, house number, and addition).
Values this scenario always writes, no matter what HiBob says
Some Nmbrs target fields are pinned by the template. You don't set these - they are BrynQ's opinion of how to shape Nmbrs for a HiBob-driven interface.
| Employee Type | = | payroll |
| Ascription Code | = | 1 |
When to change a mapping
Mapping changes are generally not advised - the template is already wired the way BrynQ recommends for HiBob and Nmbrs. There are four situations where a change is genuinely warranted:
- The standard HiBob field the record reads is wrong for your setup. Point the record at a different standard field via the record's source picker.
- None of HiBob's standard fields fit and you need a custom field. Add the custom field in HiBob first, then swap the source on the record.
- Nmbrs does not need that field for your company. If the target is optional in Nmbrs, remove the record - see About Records for how to drop a record cleanly.
- A field is missing that Nmbrs does need. Add a new record - About Records walks through this.
Full click paths for adding, editing and dropping records live in About Records - How to map fields inside a scenario.
Changing a unique key re-matches every existing record on the next run; never do this on production data.
Testing and validation
What 'done' looks like
- New HiBob employees appear as new Nmbrs employees after the run.
- The BSN field on the Nmbrs employee card matches the value in HiBob.
- The comparison report shows no unexpected 'edited' rows for stable data.
Never test against a production Nmbrs company; use a Demo company until the comparison is clean.
Why does a BSN upload fail even though the value looks valid?
The reason is always in the run log for that specific record. Nmbrs applies its own validation - length, checksum, allowed patterns - and rejects any BSN that doesn't pass. Look at the exact rejection message for the failing record rather than assuming a mapping problem; mapping issues surface earlier and produce different errors.
Why does Nmbrs sometimes reject 'employee number already exists'?
Nmbrs keeps inactive employees around, and their employee numbers stay reserved. When the interface tries to (re)create one, Nmbrs returns 'already exists'. The interface skips that record with a clear message rather than retrying - you decide whether to reactivate the Nmbrs record or assign a new number.
How is the BSN cleaned before upload to Nmbrs?
BSNs from HiBob are automatically formatted before being sent to Nmbrs - leading zeros are added if the value is shorter than nine digits, and hyphens are stripped. For example, a BSN stored as '12-345-678' becomes '123456780'.
What does the Personal topic cover?
Personal syncs identity fields - name, gender, BSN, nationality, birth date, in-service date - from HiBob to Nmbrs. It runs first because later topics assume the employee already exists in Nmbrs. Along the way BSNs are cleaned, prefix and last name are split apart, nationality is translated using the value mapping, and initials are derived from the first name.
Related articles
- FAQ
- Set Up Scenarios in a Template Interface
- About Scenarios - Organizing your interface into topics
- Set Up Scenarios in a Template Interface
- About Records - How to map fields inside a scenario
Sources
Related Articles
Hibob - Nmbrs | Employees: Setting up the interface
Step 1: Set up the new interface by picking the template Example of creating the Hibob - Nmbrs Employees interface using the template Make sure the Hibob and the Nmbrs apps are active. Follow this guide to see how to activate an app if not doing ...