With the release of Identity Manager 4 Support Pack 1, (IDM 4.01) there were three new drivers added. I have previously written about the Google Apps drivers:
In this series I want to do the same for the Blackboard driver.
I am collecting all these types of driver walk throughs on a Wiki page, and if you feel up to trying the same on your own, please let me know so I can link to it. I think this is an important thing we all need, but is unlikely to ever appear in the documentation.
In the last article I discussed the filter and some of the attributes in play.
Now let's move on to the Subscriber Event Transformation then, shall we.
There are two policy objects.
Let's do them in order.
Set BBObjectType for class User
This rule checks for an operation attribute BBObjectType, and if not available on a User object will set the operation property, BBObjectType to DirXML-BB-Person. This is a bit odd since BBObjectType is not an attribute in the schema nor in the filter so as the first rule in the policy set seeing an op attribute for it would be odd. Perhaps in a <sync> case, except that then the operational attribute would not be there either.
Set BBObjectType for class Group
Now this rule, scoped to Group objects, while equally puzzling in that it looks for an operational attribute BBObjectType that seems like it could never be there, does a couple of checks. It looks like the Group object can represent two different classes of objects in Blackboard. It could represent a course (DirXML-BB-Course) or an Organization (DirXML-BB-Organization).
If the source DN of the current Group is in the GCV defined container for Courses, then the op property BBObjectClass is set to DirXML-BB-Course.
If the source DN of the current Group is in the GCV defined container for Blackboard organizations, then the op property BBObjectClass is set to DirXML-BB-Organization.
This is the sort of thing used later to properly handle object classes, as I am sure we will see somewhere in the Command Transform. (There is a policy object there named Transform Group Attributes to Enrollment Objects, which seems like a pretty likely candidate).
Set BBObjectType for class Enrollment
This does the same thing for the object class DirXML-BB-Enrollment and if the operation attribute BBObjectType is not available it sets an operation property, BBObjectType to DirXML-BB-Enrollment.
Veto if BBObjectType not available
Now if the operation property BBObjectType is not available, then somehow we got an object of the wrong class or location, so we veto.
The most obvious example would be a group that is out of scope and not in the Courses, nor Organizations containers in eDirectory.
This just has a single rule that veto's rename events. I guess Blackboard does not support renames. Interesting. I wonder why that is. Surely they must understand that peoples names change in their lifetime and academic careers. What would be of interest to better understand is what is not allowed in terms of a Rename? Perhaps an object rename is the issue, but a name change of Given Name and Surname would be allowed? This could make sense depending on how they store the unique identifiers in the Blackboard system.
You often see a GUID used instead of the username, since after all the username is changeable, but GUID's are forever.
That wraps up the Event transform policy set. Not much happening there, it would seem. Next up is the Matching Policy Set.
There is only one policy object in this policy set.
Save original className in a local variable
There is actually a comment here, yay, explaining that the matching queries do not go through the schema map, so they want to make a copy of the current object class.
I think actually it is more an issue of the fact that Groups are mapped to two different classes (Courses and Organizations) and therefore we need to use the right class in our query based upon other info in the Group object. Also, Find Matching Object has a missing feature in my view, that it only looks for matches of the current object class. That is, you cannot match for objects of other classes. This would help prevent naming collisions since you could detect them in the Match process.
The Unique Name token had this issue as well for a long time that only recently was added (I think in IDM 4) that allows you to say try all classes. Designer has been updated to support it, but I do not know if iManager has. You will see an extra item in the Unique Name token called Test all objects, which defaults to false. Thus in order to properly test we need to morph the current object class so that we can correctly match, and then later we will set it back.
So set a local variable originalClassName to the current class name.
Match on source name for DirXML-BB-Person
The following rules use the operation property we set back in the Event Transformation, BBObjectType, and looks for DirXML-BB-Person. In which case, the rule fires, and a neat token is used, the Set Operation Class. This is functionally the same as using a Set XML Attribute token of @class-name equals a new class but this is a nicer easier to read approach. Regardless it changes the class of the object in the current event on the fly.
It does this because the Find Matching Object token likes to look for objects that match of the current class (As mapped through the schema map).
The Find Matching is done trying to find the DirXML-BB-p-id, with the Source Name of our current object.
Now this has me wondering. The Schema map does not map DirXML-BB-p-id to anything in Blackboard, and the odds of Blackboards internal schema attribute being named DirXML-BB-p-id is immensely low. This makes me think that the shim is internally mapping Blackboard attributes to this format. This is an interesting approach. My guess is that it is even programmatic rather than a hard coded mapping, and all data in the User table gets DirXML-BB-p- followed by the column name in the database. I imagine they did this because it makes the attribute references cleaner and simpler, but this is IDM and we are adults here and can deal with silly schema names, so I am not entirely sure I understand why they did this. I will report back what I find out.
Match on source name for DirXML-BB-Course
Same basic approach. Back in the Sub Event Transform we set the operation property for a Group object to either DirXML-BB-Course or DirXML-BB-Organization based on the Source DN of the group.
Here we set the class to match the op property BBObjectType and then do a Find Matching token, looking for DirXML-BB-c-id with the value of the current objects Source NAme.
Match on source name for DirXML-BB-Organization
Same as for Courses, but this time with the class DirXML-BB-Organization and the attribute DirXML-BB-o-id matching the current object name.
Match on source name for DirXML-BB-Enrollment
This rule starts out the same, look at the BBObjectType, if its DirXML-BB-Enrollment then set the class to that, start the Find Matching token, but this time it is a bit more complex.
The match criteria is actually two fold. Look at the DirXML-BB-enr-p-ext-key attribute with the current objects values. This uses the token Attribute to get the current value. This is smart as if there is such a value in the current event document (the operation attribute) it uses that, and if not, then it will do a query back to the source. This can be the more efficient approach when you are not certain if the event will contain your attribute, but it often might. The efficiency is that it can save you a query, and queries (especially for non-indexed attributes) can waste large amounts of time, at least in terms of IDM time. If you do not specify in a Find Matching Object token, where the data for the attribute to match on is coming from, it looks in the current event document. Now since you have presumably gotten here due to a real Add event, or else a modify on a non-associated object causing a synthetic add, the engine will have been sure to send all the attributes it has available at that moment. So unless your event is likely to get buried deep in a backlog of events and will change during that time, you should usually be ok with the default.
Set className back to the original class name
After all the Find Matching Objects was done we return the class name to its regularly scheduled programming.
That is the end of the Matching Policy Set, on to the Create policy Set.
There is one rule here
Check for Entitlements
This confirms we are using Entitlements via the GCV use_entitlements being set to true. That this is a DirXML-BB-Person object (Well at least the operation property BBObjectType that was set earlier says it is a DirXML-BB-Person object).
Then if the bbAccount entitlement is not available, then veto. I suppose I should chide the driver developer for not naming the Entitlement object with the Package name, but I just don't have the heart for it. It is a pain typing those silly names, so I am actually glad not to have to in this case.
If the BBObjectType is DirXML-BB-Course, and there is no DirXML-BB-c-course-title available yet, and the GCV auto_title_set is true, then the attribute is added to the event document with the objects name. This is a simple of ensuring we have a value, even if it is not a great value. I imagine having a title for a course can be considered important.
Here we look at DirXML-BB-Organization objects for DirXML-BB-o-title attributes in the event, and auto_set_title is true, we set it to the source name.
Set default email address if not set
For DirXML-BB-Persn objects, then for adds, and no DirXML-BB-p-email and the GCV auto_set_email is true, build an email address from the CN followed by @ then the GCV for the email domain.
This uses the Set Default Attribute Value token, with write back set to true, which is kind of cool. What that means is that in one token, it will check if the named attribute is in the event document, and if not, set it into the destination event, but also write it back to the source. Thus updating both sides. I had never seen this token used before this driver, but it turns out to be a nice simplification to use one token instead of three or four.
Now one further quibble is a test for if operation is add, since this is the Creation policy, the only way to get in here
This rule looks for add events on DirXML-BB-Person type objects where auto_set_roles GCV is true, and the DirXML-BB-p-sys-role is not available, and then adds in the value from the GCV default_user_role.
Same as previous rule, just instead of DirXML-BB-p-sys-role it is doing the work for DirXML-BB-p-portal-role.
This rule makes sure a DirXML-BB-p-id value is set on DirXML-BB-Person type events, and uses the Source Name as the default value.
This rule does the same, but for DirXML-BB-Course type objects, and the attribute DirXML-BB-c-id instead.
Same as the last two, differing in that this is for DirXML-BB-Organization type objects, and the attribute DirXML-BB-o-id.
There three rules do the same thing for the three object classes (as defined by the BBObjectType operation property) for the ext-key attribute. (Prepend DirXML-BB- then the letter for the object class, then a dash and you have the full attribute name).
The destination attribute gets set to the lowercase value of the Source Name, with all spaces replaced with underscores characters.