Tuesday, 23 August 2016

A Beginners Guide to OpenIDM - Part 4 - Mappings

Last time we configured a connector to process data from a data source. In this blog we start to bring everything together and will define a mapping that creates objects using the connector.

Mappings define the relationships at the attribute level between data in connector data sources and objects. They also define rules to create attributes where they do not already exist and transform attributes if required.

This blog continues my OpenIDM Beginners series, catch up with the links below:



In OpenIDM mappings consist of a number of logical components:

  • Properties: Defines attribute mappings between source attributes and target attributes, and scripts to create and transform attribute values. Also defines a link qualifier, required to link a single record in the source to multiple different records in the target. Which might be required in some situations e.g. event based HR data feeds where the same user record may appear multiple times.
  • Association: Queries, record validation scripts and association rules that work together define how a source account is linked to a target account. i.e. how OpenIDM knows that Anne's account in the target system maps to Anne's account in the source system, and not Bob's account.
  • Behaviors: Defines the rules that tell OpenIDM what to do in different situations e.g. if an account doesn't exist in the target system, then you might configure a behaviour to create it. This is incredibly powerful and we will explore it further.
  • Scheduling: Schedules for reconciliation operations e.g. run the mapping every hour, day, week etc. This is not the same as livesync (which we touched on last time) which will sync changes between systems as they occur.

Mappings Example

Creating the Mapping

As always with this blog, the best way to learn is to work through an example. We will build upon the existing work done in blogs 1-3 so you will need to complete those first.

Log in as administrator (openidm-admin), navigate to Configure then Mappings:

Then New Mapping:

You should see the following:

A mapping requires a source and a target and data will flow from the source to the target.

You can see there are a number of selectable options on this screen that you can assign as either a source or target:
  • Connectors: Any connectors you have configured, e.g. flat file, database, LDAP.
  • Managed Objects: The managed objects defined in OpenIDM.
So for this example, we want to use the CSV connector configured previously to create new managed users in OpenIDM. Effectively using the CSV data to create user identities.

Click Add to Mapping on the UserLoadCSV connector, this is going to be our source.

Similarly, now click Add to Mapping on the User managed object, this is our target.

You should see the following:

You have probably noticed that the CSV connector has a selectable drop down. There are some connectors where you might be interested in mapping more than one type of object e.g. accounts & groups in the case of LDAP. We have only configured the default _ACCOUNT_ object in this example.

Click Create Mapping.

Mapping Name: You can enter a more friendly mapping name if you like. 
Linked Mapping: If you are creating two mappings in either direction, you should use this to link your second mapping to your first.

Click OK and the mapping should be created:

Configuring the Mapping

We have a mapping, now we need to configure it.

Navigate to the Properties tab and examine the Attribute Grid.

Start by clicking Add Missing Required Properties, this will automatically add those target properties which the connector definition or managed object specify must be populated. Make sure you press Save Properties after doing this.

You should see the required attributes for the managed user schema:

Now we need to configure the source attributes for each of the following target attributes.

Select the userName row:

You should see the following popup:

There are a few tabs here worth spending a moment on:
  • Property List: The source property to map from.
  • Transformation Script:  In line or file based scripts to transform attributes, a common use of this is to generate LDAP distinguished names.
  • Conditional Updates: Advanced logic that allows you to define rules for the conditional update of certain properties on sync. Useful if you want to ensure that a particular property is never over wrote. 
  • Default Values: Simply set a fixed default value for the target, e.g. "true", "active", whatever.
Navigate to the Property List tab and select __NAME__. If you recall this corresponds to the connector we defined in the last blog. Now press Update.

Do the same with the rest of the mappings as below, then press Save Properties. You should end up with something like the below.

We can quickly check if this makes sense before we synchronize, look at Sample source, set the Link Qualifier to default and try entering one of the user ID's in the CSV:

You should see a preview of the mapping result for whichever user you entered.

Next, we need to configure an Association Rule. Navigate to Association then look at Association Rules. Select Correlation Queries

Then Add Correlation Query:

Set the Link Qualifier to default, and look at Expression Builder.

Press + and select userName:

Then press Submit, and Save.

Select Save and Reconcile.

You should see the following:

Expand out In Progress, to see the results of reconciliation:

You can see there were 100 Absent results, you can examine the tooltip to see what this means but briefly it means that the source object has no matching target, i.e. there is no managed user record for all 100s lines in the CSV file. Which makes sense, as this is the first time we have run the reconciliation.

You might have expected that those managed users will now have been created, navigate to Manage, then User:

You should see No Data:

Which might not be what we expected, however lets navigate back to Configure, Mappings and look at the Behaviors tab of our mapping again. Look at Current Policy.

By default, new mapping are set up only to read data and not actually perform any operations, such as user creates.

Look at the policy table:

Now change the Current Policy to Default Actions, and note how the table changes:

Note that the actions have all changed, examine the tooltips to understand what is going on here. I plan to revisit Policies in a later blog because they are incredibly powerful.

For now note that Absent has now changed to Create. So for our situation earlier, we would now expect those 100 Absent users to result in Create operations.

Make sure you press Save before moving on.

Finally, press Reconcile Now to run another reconciliation:

You should see the same results as before, but lets check out our Users again under Manage, User.

If we have done everything correctly, you should now see all of the users from the CSV file created as OpenIDM managed users.

That's all for this blog entry. Next time we will take a look at user creation and self registration.

No comments:

Post a Comment