Define mapping and synchronization rules

Last modified 10 Dec 2025 21:16 +01:00
Table of Contents

Before you can import any user accounts, you need to define user data handling rules, as well as specify synchronization rules on how to behave when users are discovered, updated, deleted, and so on.

What awaits you in this module

You are about to create two sets of rules telling midPoint how to manage the HRIS application data. Firstly, you need to define synchronization rules.

Synchronization situation is what happens when midPoint correlates (synchronizes) its object repository with a remote resource, such as the HRIS. Newly discovered accounts not yet seen by midPoint are unmatched, accounts removed from the resource are deleted, etc. Read more on the topic:

Each synchronization situation can have some reaction from midPoint, such as linking a new focal object to a discovered account. You are now about to define reactions to synchronization situations.

Secondly, you will create mapping rules, telling midPoint which source attribute maps to which focal object attribute. Mapping rules are basically a mapping table telling midPoint which "external" (application resource) attribute (e.g., surname) corresponds to which "internal" (focus) attribute (e.g., familyName).

See Mapping to learn more about the topic.

Lastly, you will configure midPoint so that it can only read from the HRIS application, not write to it. This is an additional data protection layer should you make a mistake when you deploy the configuration to production.

1. Set synchronization rules

Firstly, tell midPoint what to do in what synchronization situation.

Follow this configuration guide: Resource wizard: Object type synchronization

Define these rules:

Name Situation Reaction Lifecycle state Comments

add-focus-for-unmatched

Unmatched

Add focus

Active

The account from CSV does not exist in midPoint yet, so create the user (focus) in midPoint.

link-unlinked

Unlinked

Link

Active

There is a focus for the account but it is not linked to the shadow of the account yet, let us link it. This is not used during the first import, but it is necessary for later when the account shadows are in midPoint already.

synchronize-linked

Linked

Synchronize

Active

Synchronize the data between the remote account and the focus based on mappings.

At this point, both the synchronization and mapping rules can be set as Active because the whole resource is still in the Proposed lifecycle state. You can consider lifecycle states as hierarchical. Refer to Object Lifecycle for more details about lifecycle states.

2. Map user data

Secondly, you need to map the resource-side account attributes to the attributes of user focal objects in midPoint.

Follow this configuration guide: Resource Wizard: Object Type Mappings

Use inbound mappings because you are pulling attributes from the HRIS application to midPoint.

Below are the rules to define.

The resource-side attribute names (ie., Source) match those used in the MID-301 course training data. If you use your own systems, adjust the source names as needed.
Table 1. Mappings for HRIS accounts data manipulation
Name Source Expression Target Lifecycle state Comments

empnum-to-name

empnum

As is

name

Active

The name attribute values must be unique, hence the employee number is the best choice now. Later, you will generate unique usernames.

empnum-to-personalNumber

empnum

As is

personalNumber

Active

empnum is also important for employee identification, so we map it to a dedicated attribute. It will stay there even after you create unique usernames.

firstName-to-givenName

firstName

As is

givenName

Active

First and last names are used to construct a full name.

surname-to-familyName

surname

As is

familyName

Active

locality-to-locality

locality

As is

locality

Active

User location will be later used with the full name for a last-resort correlation.

status-to-lifecycleState

status

Script

lifecycleState

Active

Translate textual status to midPoint user lifecycle state. Find the script to use beneath the table. Click Show script to edit the script.
The status-to-lifecycleState mapping conversion script
switch (input) {
   case 'In': (1)
      'active'
      break

   case 'Long-term leave': (1)
      'suspended'
      break

   case 'Former employee': (1)
      'archived'
      break
}
1 Adjust to the corresponding values of the attribute in your system. These values are used in the MID-301 training data.
Inbound mappings for the HR resource
Figure 1. Inbound mappings for the HR resource
Naming conventions for mapping names

You may be curious about why we name the mappings as shown above. At first glance, it seems unnecessary to name the mapping surname-to-familyName since it is evident that it takes surname as input and outputs its content to familyName.

You are correct, but the rationale behind this naming convention is that mapping names must be unique within the object type. This approach helps to ensure that.

As for spaces vs. dashes—you can use either, but dash signs are generally the saver option. Treat mapping names as filenames.

3. Make the resource read-only

If you are dealing with a resource the data of which you do not want to change, it is best to adjust the configured capabilities of the resource so that mistakes cannot happen.

  1. In your HR resource, go to  Details.

  2. Disable the Create, Update, and Delete capabilites.

    • You can disable Create and Delete by clicking their respective buttons. As for the Update capability, you need to select Enabled: False in the modal that appears after clicking the capability button.

  3. Click Save at the top left.

hris resource capabilities
Figure 2. Resource capabilities screen with the Create, Update, and Delete capabilities highlighted and disabled as per the instructions above

Next steps

With this configuration finished, you are now ready to import users to midPoint.

Import users from the HR system

Was this page helpful?
YES NO
Thanks for your feedback