Creating a Management Agent

Continuing in my newbie series of posts, today I am going to step through the creation of a Management Agent. Configuration options differ depending on the type of MA, so in this post I will just look at the options that are common to all.

1. Create the MA

Simple enough – just select the Create Action on the Management Agents tab in Identity Manager.

2. Select the MA type

Again fairly obvious – select the type you want from the drop-down, and then enter a name for the MA.

Names can be changed later, though I recommend you don’t use spaces, even though they are supported. You will be grateful later on when you get into the vbscripting side…

3. Connectivity details

The exact format depends on the type of MA, but there will always be some way to tell ILM how to get in contact with this data source.

4. OU, Object types, attributes, columns..

Next you will have one or more forms which allow you to specify the expected object types and their attributes. Again the format depends on the MA type, so I won’t go into more detail in this post.

Now we get to the options that all MAs have…

5. Connector Filter

The Connector Filter is a way of telling ILM to ignore objects which meet certain criteria, such as an attribute starting with a particular letter. It all looks fairly obvious, however there is one thing to be aware of:

The Connector Filter only stops new objects becoming connected – it does not disconnect objects that are already joined to a metaverse object.

Let me illustrate. Say an organisation has the convention of putting “x-” at the start of account names when the account is no longer in use. You are not interested in these accounts, so you configure a Connector Filter with “Starts with” and “x-“.

Initially everything looks ok. All the “x-” accounts are sitting in the connector space as disconnectors, and the valid accounts have been successfully joined.

But then an account is made inactive and renamed according to the convention – what happens? As it is already joined to an object in the metaverse it will remain joined. The only codeless way you can disconnect it is by completely clearing and re-importing the connector space.

Code note: Use the csobject.Deprovision function in the metaverse rules extension to disconnect the object. Whether this deletes, or just disconnects, the object depends on how you have configured the MA’s Deprovisioning options – described below.

6. Projection Rules

Join and Projection rules are configured on the same form however, as there is a fair amount to say about each, I shall look at them seperately – projection first.

Projection is the process by which an object in the connector space is imported into the metaverse.

It is normally very simple to configure. For each object type in the connector space, you can use the Declared rule to project all of those objects (except where blocked by the Connector Filter) into the metaverse.

You must select a metaverse object type, but it can be different to the CS object type. You could even project several CS objects onto a single metaverse type if you wanted – for example you might want type user and type contact to all be considered person objects in the metaverse (there are often good reasons for doing this).

You also have the option of using a Rules Extension. This is where you write some code to dictate which objects get projected and which don’t.

Code note: Use the ShouldProjectToMV function in the MA rules extension to return a True/False value.

I must admit to having never used a Rules Exension to dictate projection – preferring to do my object selection outside of ILM, and thus keeping decision making out of compiled code.

The final point I will make on projection is this: as much as possible, have only one projection MA per object type, and make sure it’s the most authoritative one.

It’s all about keeping rubbish out of the metaverse or, as Hugh from OCG says, “The Metaverse should be a shrine to good data”! If you are projecting from data sources which have old accounts, test accounts, temporary contractor accounts, and other non-standard rubbish, you may find that, once in your metaverse, these can be almost impossible to detect and remove.

7. Join Rules

Joins form the very fabric of ILM. Without Joins there are no attribute flows, no password sync, and no new objects, as every object created in the system must be connected to something else.

Once you have objects in the metaverse you can being to join to them. If you are lucky, there will be some simple convention already in place allowing you to confidently say that this CS object is the same as that metaverse object because they have the same employeeID, or because the sAMAccountName matches the local part of the email address, etc.

If you are not so lucky you will be attempting to match first names and surnames, and running into all the problems of Elizabeth sometimes being Lizzie, Liza or Betty.

In fact sorting out Joins is such a big topic in itself that I am planning a whole other post on it….

Like with the projection rules, you can have a basic direct join rule (if attributeA = attributeB), or you can use a Rules Extension for more complex pattern matching.

Code note: Use the ResolveJoinSearch function in the MA rules extension.

A typically overlooked point is that you should always join back, even if the MA is one where you only create new objects.

When you provision objects in a connector space, you will find they are born already connected to their metaverse parent. Don’t make the mistake of relying on these joins! You should always plan to be able to wipe your whole connector space, and re-import from the data source. If you have implented join rules, all those objects will be nicely reconnected. Make sure, when provisioning, that you “breadcrumb” all objects with a unique identifier that simplifies any subsequent re-joins.

8. Configure Attribute Flows

Now we can finally have some fun! Synchronising values is what it’s all about, and here you can map out your attribute flows.

I expect this form is quite self-explanatory, and most people will figure it out without too much trouble. The Advanced Attribute Flows require more explanation, but that’s done with code, and I’ll cover it in a different post.

Code note: Advanced flow rules are written into the MapAttributesForImport and the MapAttributesForExport subs of the MA rules extension.

9. Configure Deprovisioning

This form is about what to do if the Deprovision function is called from the metaverse rules extension. You may well need to revisit these options after you’ve figured out what all this rules extension stuff is about.

Make them disconnectors: If you’re not sure, stick with this one. The objects will be unjoined, but nothing gets deleted from the data source.

Make them explicit disconnectors: Don’t delete the object, just disconnect it, and make sure it never gets connected again – unless you clear the connector space that is. Personally I’ve never found a use for this option.

Stage a delete on the object for the next export run: the potentially destructive choice – this will go out into your data source and delete objects. Very, very useful, but approach with care!

Determine with a rules extension: That catch-all option if you need extra configurability. Write your code into the Deprovision function in the MA rules extension.

10. Configure Extensions

If you are planning on using any of the rules extension functions described above you will need to create an extension dll. All you do in this section of the MA configuration is enter the name of the dll, which must be located in the Extensions folder under the ILM program folder.

You may also select, on the same page, if this MA is a target for password sync – but again that’s a subject of another post.

11. And the rest

Save your MA. Then create some Run Profiles, then test it… Lots of fun to be had, but quite enough for this post.