Walking through the Banner Driver - Part 3

In part 1 of this series I started explaining the driver configuration for the Ellucian Banner driver.

In part 2 of this series I started looking at the Global Configuration Variable values.

In this article will continue going through the GCVs and other settings.

There were noticeably different GCVs for some of the more standard packages (Password Synchronization and Account Tracking) that were discussed in the previous article. Now for the actual set of driver specific GCVs.

User Settings GCVs:

Attribute used to match Banner Accounts with eDirectory Accounts, is the first setting, and it has two values in its set; udcIdentifier and CN. That is, when it comes time to match users, do you use CN of some student number like thing.

One interesting thing of note, udcIdentifier is a schema extension, and is not part of base schema, nor does Designer know about it, out of the box. Normally, if you open a new Designer project and drop in an Identity Vault with no connection to the real world ever, you get the base schema, plus most DirXML related schema extensions. Thus it is nice to use Designer's Schema Browser (Right click on an Identity Vault and select Manage Vault Schema) to look at how schema is defined. In this case, it is not included with Designer.

Even more interesting is that they did not extend schema as DirXML-banner-udcIdentifier, rather simply mapped the attributes names straight in. This is not a big deal, and if you felt like it you could globally search and replace in the config and fix that to use your own custom schema attribute.

The major take away from this point is that the schema needs to be extended as part of installing this driver.

Anyway, the choice here will depend on whether you have users with pre-populated student numbers (udcIdentifier) or if the CN is available. Now looking in the schema map, I do not see CN mapped to anything, which leads me to believe the value is synthesized from something, at some point. In fact that leads right into the next GCV settings.

Should the driver Autogenerate a CN when it receives a user from Banner setting, when set to Yes, opens up two more settings.

"How should the driver set the CN value", and "Set the Unique ID Attribute in eDirectory with the generated CN value" are the next two GCVs.

The first setting has a few possible options:

UDC Identifier
First Initial Last Name
First Name Last Initial
First Name Last Name
First Name . Last Name
First Initial Middle Initial Last Name
Last Name First Initial Middle Initial

Now it is worth noting that this is an 'enum' type GCV, that is, an enumeration, where there is a pretty text label shown in the list, but the actual value of the GCV is usually something different.

You can read more about the various different types of GCVs in these articles:

Often the value behind an enum is pretty boring, but in this case it is mighty interesting and looks like the following XML:

<enum-choice display-name="UDC Identifier">UDCIdentifier</enum-choice>
<enum-choice display-name="First Initial Last Name">f1m0l*</enum-choice>
<enum-choice display-name="First Name Last Initial">f*m0l1</enum-choice>
<enum-choice display-name="First Name Last Name">f*m0l*</enum-choice>
<enum-choice display-name="First Name . Last Name">f*m0.l*</enum-choice>
<enum-choice display-name="First Initial Middle Initial Last Name">f1m1l*</enum-choice>
<enum-choice display-name="Last Name First Initial Middle Initial">l*f1m1</enum-choice>

Lets use the last one as an example.
Last Name First Initial Middle Initial has the value of 'l*f1m1'

That is quite interesting, and almost looks like a Regular expression. But I doubt that it is, and instead they have some clever policy that knows 'l' means last name, '*' means take as much as you can, 'f1' means one letter of first name, and 'm1' means one letter of middle initial.

Now I am really looking forward to the policy that implements this, since I expect it to be very clever. However I do not want to jump the gun, and will wait till I get there naturally before exploring that policy. Of course if I find out it is just multiple hardcoded cases, I am gonna find Richard and mock him mercilessly! (I want my cool and clever code in a driver please, not slacker approaches).

The rest of the enum values all make sense, and it is clear how the value maps to the pattern of the name. (Clearly not a Regex, as a I see the First Name period last name cases is f*m0.l* and a period is NOT a literal in Regex. It does seem that you need a f, m, or l character for first, middle, and last followed by a length indicator, where 0, 1, and * seem to be options. Finally, somehow periods seem allowed. This should be really fun to see how they implement it.

Ok, I could not resist and I peeked ahead. The policy of interest in the NOVLBNNRUSER-pub-itp-GenerateUsername policy object and it has a very concise simple way of parsing that looks pretty clever. In 10 set local variable statements they get it all. Well done, very clever. I look forward to dissecting it in detail later. Even in the quick look I took, I can see the approach taken, and it is very clever. I approve. (As if anyone actually cares what I think in this realm).

The next setting "Set the Unique ID Attribute in eDirectory with the generated CN value" is simply a question of whether the Unique ID should be set the same as CN or not. UniqueID is important since most LDAP tools prefer to look at UniqueID and not CN (CN can be multivalued, UniqueID ought not to be, though eDirectory allows it. UniqueID is supposed to be globally unique in the tree, while CN might not be.) In the olden days, NWadmin (who remembers that tool!) used to NOT set UniqueID on new users, but Console1 did the job (as does iManager).

I am not sure of the user case where I would not set UniqueID the same, but it is nice having the option. Options are good.

In part 2 of this series I discussed an ECMA Script function included with this driver that parsed telephone numbers, and here we get the ability to describe that format. Back then I noted the format string has the characters CATXS:

C	Country Code
A Area Code
T Telephone Number
X Extension Number
S Subscriber Number

And here the default is (AAA)TTTTTTTT which looks normal for North American phones. (Are there any other countries than the US and Canada?). But as discussed before this format string allows the driver to parse the number from the format from one format to another. I did not look to see where this is called, but I am guessing it is used to send phone numbers back to Banner in the proper crazy format. Who ever heard of caret as a delimiter? As I think about it though, it is probably likely that the shim is expecting the caret as the delimiter and using position as well to properly send the values to Banner. As I noted in part 1, this concept is not unique to Banner, as SAP User Modules, and Workday HRIS (SaaS HR app) both do something similar. Amusingly, SAP HR is fine with whatever string you enter, it is only the UM (User Module) where phone is vaguely unimportant that seems to care. Probably a sign of yet another way that SAP was built from a mish mash of components or products.

If you ever want to learn advanced IDM concepts, I highly recommend trying to read through the SAP drivers, the shipping packaged ones have some really awesome complex bits in them, where you will learn plenty of tricks.

The GCV has an awesome explanation in the definition, which is worth repeating here:

The Phone number attributes in Banner are broken into five separate pieces.

Many Places don't use all of these for the phone number. So the purpose of this GCV is to describe the format your phone numbers are in so the driver can parse out your numbers and place them in Banner format. This is done by writing out in text using letters the format used in the IDVault. Each Letter corresponds to a part of the phone number in Banner. The five sections and their corresponding letter are as follows:

Country Code 'C', Area Code 'A', Telephone Number 'T', Extension 'X', Subscriber Number 'S'.

These can be put in a string that represents the Format in the IDV. Here are some examples:

(801)861-4000 This is an area code with a phone number. and would be represented like this:


The Resulting values in Banner would be:
Country Code = Blank
Area Code = 801
Telephone Number = 861-4000
Extension = Blank
Subscriber Number = Blank

801-861-4000x8888 This is a area code with a telephone number and an extension:


The Resulting values in Banner would be:
Country Code = Blank
Area Code = 801
Telephone Number = 861-4000
Extension = 8888
Subscriber Number = Blank

I love it when there is a good explanation for a setting. This is so rare these days I have to call it out as totally outstanding. Well done.

Next up is "Format of InstitutionRole Attribute", which comes with the explanation as follows:

When Banner sends the Institution Roles attribute to IDM it is a contrived attribute based on SQL queries inside the BEIS configuration. The configuration can determine what information is sent. The roles come through as a string made of three pieces of information. The first piece is the defined Role Name for example STUDENT. The second piece is the source Table in the Banner system that the information comes from such as INTCOMP. The third and final piece is the Institution Name defined inside of BEIS. Which most often is only defined when there are different Institutions within the Banner system.

Each value then comes out with all three pieces put together and separated with a ";". This nomenclature is a little hard to read and in a lot of cases is not needed. In many cases the first piece, the role name, is the only part that is needed inside the IDM system. The purpose of this GCV is to determine how many of the piece to actually send to IDM.

Thus you can see that while they get three pieces of data, they give you the choice of only really consuming 1, 2, or 3 parts of it. (Always with the Role, since that is actually the interesting part. Again, a very nice and clever option to have, sign of a well thought out driver configuration. As a policy snob, (and herring snob as well, if you find this article helpful, please consider sending me some interesting kosher herring... Someone really did mail me herring once!) these are signs I look for to demonstrate the skill of the policy writer. Alas, sometimes the opposite is very painfully obvious. But that is the nice thing about Packages, fixing it is not that hard, and making things better can happen quicker than patches are released, just by updating packages with better content.

The next setting "Replacement Character for semi-colon Institution Role delimiter" tells us, that if more than just the role name is used in IDM this GCV determines which attribute to replace the semi-colon with to make it more readable. By default the semi-colon is replaced with a "_" character. If this is set back to a semi-=colon it will not change the value.

This is again a nice little option, to make your life easier out of the box.

That about wraps up the GCVs as far as I can tell. Next up, lets start in the Input Transform, since this is a mostly Publisher channel driver. Stay tuned for part 4 where I will begin walking through the Input Transform.


How To-Best Practice
Comment List
Related Discussions