Generate usernames in midPoint for new users

Table of Contents

Up until now, you sourced usernames from the target Active Directory application. This approach works well for existing accounts that already have the username populated in Active Directory. But what about new users? Once the HR department registers a new user in the HRIS, the account arrives to midPoint, but it has no place from which to obtain the username.

Let us change that. Similarly to passwords, midPoint can generate usernames as well. The difference here is that passwords are random strings, while usernames consist, typically, of the first and last names and possibly some numbers. For this reason, you are going to use a script for this task.

What awaits you in this module

To generate usernames, you will:

  1. Archive both the HRIS and AD inbound mappings for the name attribute as they will not be needed any longer.

  2. Use the Person object template to define a new mapping for username generation. The mapping will be weak so that it does not overwrite existing values.

  3. Create new users in the source HRIS resource.

  4. Use a simulated import to check whether the username generation works correctly.

  5. Create a recurring HRIS reconciliation task to import new users automatically on regular basis.

When you are done, you will have automated generation of usernames that are sAMAccountName-compatible, and set up an interval-based recurring reconciliation task to import the HRIS accounts without a human operator like you needing to import the users manually.

1. Archive obsolete mappings

In the beginning, you have used the empnum containing employee number from the HR source system as a unique value for the name attribute (which needs to be unique as per midPoint requirements). Later on, after you have connected Active Directory, you have replaced it with uid which contains usernames, at least in our example training data.

However, you have already reconciled all the pre-existing users so there is no need for either of the mappings because they would be useless for new users. This means you can archive them.

To archive the HRIS mapping:

  1. Go to the source HRIS resource > Accounts > mapping configuration.

  2. In Inbound mappings, find the empnum-to-name mapping that copies the empnum attribute from the HRIS to the focal object name attribute.

  3. Set its Lifecycle state to Archived.

When done, do exactly the same with the inbound-uid-username-to-name AD mapping you used to copy the AD usernames in uid to the name focus attribute in midPoint.

We use the Archived lifecycle state here to indicate that the mapping is unlikely to be active again. For temporary mapping deactivation, you could use the Suspended state. All Archived, Suspended, and Draft states represent deactivation and configurations in these states are not used, but midPoint has those three states to express different reasons for deactivation. Refer to Object Lifecycle for more information on the topic.

2. Add username mapping to Person object template

Object template is a configuration object in midPoint you can use to run mappings whenever a focal object, such as a user, is created or updated in midPoint.

Refer to Object Template and Person Archetype for more details.

The Person object template already contains out-of-the-box a mapping to generate a full name. You have seen it in action when you assigned the Person archetype to users imported from the HRIS.

What you are after now is a mapping that would take the given name and surname, and generate a username in the jsmith82 format that conforms to the Active Directory sAMAccountName restrictions. Such a username consists of the first letter from the given name, concatenates it with the surname, and takes 8 characters from the result. Moreover, if the result is not unique in the system (e.g., Alice Baker and Andrew Baker result both in abaker), the username is to contain up to two digits to become unique. It is a usual to start with the number iterator at 2 to make the usernames more human friendly and intuitive: abaker, abaker2, abaker3, …

Person object template mapping to generate jsmith82-style usernames
Figure 1. Person object template mapping to generate jsmith82-style usernames

To add a new mapping to generate the jsmith82 usernames:

  1. In Object templates > All object templates, select Person Object Template.

  2. In Mappings, click New to create a new mapping.

    • If you use the preconfigured Docker images for this guide, the username mapping is already there. Inspect it to see how it works.

  3. Name the mapping, e.g., generate-name-jsmith-8-2.

  4. Set Strength to weak so that the mapping does not overwrite existing usernames.

  5. Set Lifecycle state to Active.

    • You can safely activate the mapping for it is weak and will never overwrite existing values.

  6. Select givenName and familyName from Focus in Source.

  7. Set the expression to Script.

    • See the script below.

  8. Set Target to name as that is the uniquely identifying attribute for focal objects (users).

  9. Click Done in the mapping details and Save in the overview screen to save your settings.

The script to use for generating jsmith82 usernames
tmpGivenName = basic.trim(basic.norm(basic.stringify(givenName))) (1)
tmpFamilyName = basic.trim(basic.norm(basic.stringify(familyName))) (1)
tmpGivenNameInitial = tmpGivenName?.take(1) (2)
return (tmpGivenNameInitial + tmpFamilyName?.replaceAll(" ", ""))?.take(8) + iterationToken (3)
1 Take the normalized version of the name string and remove leading and trailing white characters using trim().
2 Truncate the first name only to one character. This is safe even if firstName is empty, but it cannot be null.
3 Concatenate the first name initial with the surname, shorten the result to 8 characters if needed, remove white spaces, and add the iteration token.

3. Add new users to HRIS to test username generation

With the object template mapping ready, it is time to put it to test. Create new users in your source HR information system and import them to midPoint.

If you use the training Docker images prepared for this guide, use the Demo HR app web interface. Otherwise, register new users to your own source system; you can use the data from below for inspiration. The instructions below are for the Demo HR app.

  1. In the Demo HR app, click Register user at the top of the screen.

  2. Fill in the values according to the table below.

  3. Add each user by clicking Register user beneath the form.

  4. Once you add all users, click Export users to CSV file at the bottom of the user list screen to export the users.

Table 1. Users to be added

First name

Louise

Andreas

Clara

Clara

Jacques

Surname

Callahan

Baker

Whiteherring

Whiteherring

Smith

Employee number

9000

9001

9002

9003

9004

Locality

White Stone City

Job

222#Export/Import Coordinator

EmpType

FTE

Status

In

4. Simulate importing new users to midPoint

Before you put the new configuration to production, verify it works using simulations.

Perform an import preview of a single user. You can repeat the preview import for multiple new users.

Follow this guide: Create and Run Tasks in GUI

Once the import finishes, observe the name attribute being filled in with a proper username instead of the employee number.

Result of preview import operation showing successfully generated username
Figure 2. Result of preview import operation showing successfully generated username

5. Automate importing users to midPoint

After you verify generating the usernames works, import the users to midPoint for real. You will create a recurring reconciliation task in order to automate the whole process. A reconciliation task is more suitable than import because it is going to handle removed users as well.

Follow this guide: Create and Run Tasks in GUI

  1. In the HRIS resource, create a new reconciliation task with the simulation toggle off.

  2. Name it, e.g., HR Reconciliation.

  3. Set the schedule interval to, e.g., 60 seconds.

    • This makes the task automated, running every 60 seconds. Every time new accounts appear in the source CSV, they get automatically imported to midPoint. In a real scenario, you would probably set the interval to minutes or hours, depending on the amount of identities you would be managing.

  4. Save the task and run it.

Wait until the task finishes its first run and head over to Users > Persons to see the newly added users and their generated jsmith82-style usernames.

You can filter them out, e.g., by the employee number (mapped to personalNumber) using the advanced filter like this:

Query to filter users by their personalNumber attribute
personalNumber startsWith '900'
Users newly imported to the HRIS resource with jsmith82-style usernames generated by midPoint
Figure 3. Newly imported users in the HRIS resource with jsmith82-style usernames generated by midPoint

Next steps

You have automated sAMAccountName-compatible username generation. You have also automated reconciliation of the source HR application with midPoint, which means that every time a user is created in and exported from the HRIS, the account is imported to midPoint as well.

The next step is to ensure that every person in midPoint has an account in Active Directory provisioned automatically.

link

Was this page helpful?
YES NO
Thanks for your feedback