I had noticed the Oracle EBS drivers get added to Designer a few patches ago, but never really had much of a chance to look at them. As I have been doing in my driver walkthrough series, I decided to do the Oracle eBusiness HR driver next.

In the first article I made it through the configuration, GCVs, and the started working through the Subscriber channel.

In the second article I finished the Matching policy in the Subscriber channel and got into the Command Transform.

In the third article I finished the Command Transform and started into the Output Transform.

In the fourth article I finished the Output Transform, and started in on the first policy in the Input Transform.

In this article I will continue through the Input Transform. The following policy objects are in the Input Transform:

• NOVLAUDTENTC-itp-SendEntitlementsEvents

• NOVLORAHENT-itp-InitEntitlementConfigurationResource

• NOVLEBSMSI-itp-InitManagedSystemInfo

• NOVLORAHATRK-itp-Publish

• NOVLORAHATRK-itp-WriteAccounts

• NOVLORAHDCFG-itp-ConvertTime

• NOVLORAHDCFG-itp-ModifyDirXML-PersonIdAttribute

• NOVLORAHENT-itp-EntitlementsImpl

Got through the first one, so onwards and upwards with the second and down.

NOVLORAHENT-itp-InitEntitlementConfigurationResource

I am not sure I want to walk through this entirely since I basically did in the article: Converting Entitlements to Resources, more details

which was a response to this article, explaining how to retrofit Resource mapping support into an older driver: Convert Driver Entitlements to New RBPM 3.7 Resource Model

Basically this is the rule that will generate the EntitlementConfiguration object under your driver. This is one of the two rules that mean your Security Equals user needs write permissions to the driver object and down itself. It will create and maintain a brand new object that does not come with the Packaged version of the driver. (The other is the MSysInfo object, more on that in the next policy object).

I am very torn on this topic. The reasons for doing it this way are really two fold as far as I can tell. (If you have another good reason, I would love to hear it). First it needs the DN of each entitlement under the driver, in LDAP format to be specified in the object. If you ever looked at an XML config they had a shorthand for the base DN of the driver/driver set included, so in the XML you did not have to explicitly identify the tree info before you imported it. I always wondered why they did not just add some functionality like this to the import process top get the LDAP DN in a similar fashion.

Second, it is possible to control via GCV's whether you wish to enable a series of settings about how Resources are handled in this driver.
Role mapping, resource mapping, format of the Entitlement payload come to mind initially. These are things you potentially would want to change over time. To be fair I am not sure I have every changed any of these entitlements.

The thing I suppose that annoys me the most is that the code is not really generic. That is, if you went and added a new Entitlement type to the driver, the code does not always handle it nicely. So basically to add a new Entitlement to be supported you are changing policy as well. That seems wrong somehow. I am told that in the Jade project (Permissions Collection and Reconciliation Service) changes that this got better. The old Active Directory driver did a pretty weak job of handling it before. So I look forward to reviewing those one of these days in the future to get a better understanding of what is happening there.

Specifically in this case, there are three if-then statements that handle just the three known Entitlements, UserAccount, Roles, and Responsibilities, with no attempt to even handle any other possible case.

I would prefer a better approach.

Having vented all that, I think I will show a sample of what an EntitlementConfiguration object should look like, since it is important to know when you are troubleshooting.

<entitlement-configuration modified="20140303033113">
        <entitlements>
                <entitlement data-collection="true" dn="CN=Group,CN=Salesforce,CN=driverset1,O=system" parameter-format="idm4" resource-mapping="true" role-mapping="true">
                        <type category="security grouping" id="group" name="group">
                                <display-name>
                                        <value langCode="en">Group</value>
                                </display-name>
                                <sub-type source="read-attr" source-name="Type">
                                        <display-name source-value="Regular">
                                                <value langCode="en"/>
                                        </display-name>
                                        <display-name source-value="Queue">
                                                <value langCode="en"/>
                                        </display-name>
                                </sub-type>
                        </type>
                        <parameters> 
				<parameter mandatory="true" name="ID" source="association"/>
				<parameter mandatory="true" name="ID2" source="src-dn"/>
			</parameters>
			<member-assignment-extensions>
				<query-xml>
					<read-attr attr-name="Members"/>
				</query-xml>
			</member-assignment-extensions>
			<query-extensions>
				<query-xml>
					<operation-data data-collection-query="true"/>
				</query-xml>
			</query-extensions>
			<query-xml>
				<read-attr attr-name="Type"/> 
			</query-xml>
		</entitlement>
</emtitlememt-configuration>

The <entitlement> node is key, since it has in its XML attributes the LDAP DN of the entitlement at hand, the settings for:

• data-collection

• role-mapping

• resource-mapping

• parameter-format

It reads the DirXML-Entitlement objects from the driver, so in principle it COULD find new unaccounted for examples, that look something like this for the referenced Entitlement above, which is an example from Salesforce.com driver.

<entitlement conflict-resolution="priority" description="The group entitlement represents public groups and queues in Salesforce.com." display-name="Group">
	<values multi-valued="true">
		<query-app>
			<query-xml>
				<nds dtdversion="2.0">
					<input>
						<query class-name="Group" scope="subtree">
							<search-class class-name="Group"/>
							<read-attr attr-name="Name"/>
							<read-attr attr-name="Type"/>
						</query>
					</input>
				</nds>
			</query-xml>
			<result-set>
				<display-name>
					<token-attr attr-name="Name"/>
				</display-name>
				<description>
					<token-attr attr-name="Type"/>
				</description>
				<ent-value>
					<token-association/>
				</ent-value>
			</result-set>
		</query-app>
	</values>
</entitlement>

Some parts of that Entitlement object are copied in, and other parts come from the GCVs.

Beyond that, read the article about what it is doing in the policy, and see what you think of this approach.

NOVLEBSMSI-itp-InitManagedSystemInfo

This is the second rule that needs permission to write back to the driver object.

Interestingly enough, DirXML-ApplicationSchema that is retrieved by the shim in a getSchema() call during driver startup does not seem to need permissions to the driver object. (Or does it now? Hmm, now I have to go look and test that...)

This writes the MSysInfo DirXML-GlobalConfigDef object back. The shim will ship with a mostly complete one (You provide some of the info about the system) but this will go read the DirXML-ShimAuthServer attribute and get the IP address/name of the target connected server, or if not, parse out the Remote Loader string to get it from there. It will write the driver GUID in, and some other stuff.

If you look at the MSysInfo GCV you will see that there is a section at the bottom that says "Connection and Miscellaneous Information (auto-generated, do not change!)". If you do change it, it will get overwritten on the next driver restart.

This too should be moved to the Startup policy one of these days.

I have written about this object quite heavily in my series on the MSG and DCS drivers so I think I will leave it at that.

NOVLORAHATRK-itp-Publish

These two policy objects are another of the Account Tracking polices that I want to take on by themselves in a standalone set of articles. But at a high level these are trying to decide if an account has switched from disabled to enabled or vica versa. Then it will write that change to DirXML-Accounts, which Sentinel is relying on.

I think I will leave it at that.

NOVLORAHDCFG-itp-ConvertTime

Here we have the following four rules:

• Skip for data collection query output

• Convert the DATE to unix timestamp format during modify

• Convert the DATE to unix timestamp format during add

• Convert the DATE to unix timestamp format during query output

I have the sneaky suspicion I am going to have the same comments as I did on the Output Transform equivalent of this rule, that is they should have properly used Reformat Operation Attribute. But I am open minded, I have not actually looked ahead yet to cheat and see. (Well only a little bit caught my eye).

Skip for data collection query output

This rule checks if the operation property data-collection-query is true. That is a query that the DCS driver is sending into the shim to see what accounts are there, and whatnot so that reporting has up to date info. I would have thought date reformatting would have been useful there? But since it is not writing the result out to a Time syntax attribute, maybe it does not matter? Though I would think that the DCS driver would pass the data along is some normalized date format, probably expecting CTIME if it is normally working with eDirectory.

Convert the DATE to unix timestamp format during modify
Convert the DATE to unix timestamp format during add

Oh well, exact same complaint as in article 4 of this series. They loop over modify-attr, and then reinvent Reformat Operation Attribute again, just reversing the order of the time conversion. Then in the second rule they loop over add-attr, and do try to use Reformat Operation Attribute but get it wrong, using the Operation Attribute $attributename$ variable, instead of current-value. This means that if there was more than one value for any of those fields, both will be set to the same as the first value.

Convert the DATE to unix timestamp format during query output

This one is a little different, since before they did not handle the query response in an <instance> document case, so they reinvent it a third time to handle the <instance> case, where you get neither an <add-attr> nor <modify-attr> but rather an <attr> node.

The thing that is missed is that in common with all three event types, is that the add-attr, modify-attr, and attr nodes all have XML attributes of attr-name. So my rule from article 4 would work perfectly well to replace all three of these rules in a much simpler and more elegant approach. Of course, the Time conversion would need to be reversed, so lets show that again, with the reversal of time handled:

<do-for-each>
	<arg-node-set>
		<token-xpath expression=".//@attr-name"/>
	</arg-node-set>
	<arg-actions>
		<do-if>
			<arg-conditions>
				<and>
					<if-local-variable mode="regex" name="attributename" op="equal">.*_DATE.*|.*_DT|.*_UPDATED</if-local-variable>
				</and>
			</arg-conditions>
			<arg-actions>
				<do-reformat-op-attr name="$current-node$">
					<arg-value type="string">
						<token-convert-time dest-format="!CTIME" src-format="MM/dd/yyyy hh:mm:ss">
							<token-local-variable name="current-value"/>
						</token-convert-time>
					</arg-value>
				</do-reformat-op-attr>
			</arg-actions>
			<arg-actions/>
		</do-if>
	</arg-actions>
</do-for-each>

I will have to try and track down the author of these policies and try to explain this point to them for future releases. That is also kind of fun, seeing if my changes get taken up in later package versions. So far, sometimes yes, sometimes no.

NOVLORAHDCFG-itp-ModifyDirXML-PersonIdAttribute

There is a single rule in here "Modify DirXML-ebsPersonId during add-association" which is amusing, since the actual class really is DirXML-ebsPersonId, and the rule has it correct but the policy object has it wrong as DirXML-PersonId. Mostly harmless.

If the event is an <add-association> then it sets the destination attribute "DirXML-ebsPersonId" with the value of XPATH of period (.).

So what is that all about? Well the Shim is supposed to return a proposed Association value with an event. That is, if you successfully create an object in the connected system, the shim is supposed to send through the Input Transform (and I think skipping the Publisher Command Transform) an <add-association> event, that has as its text() value, the association value. Thus the current context, period, is the node that contains only text. So when you cast that into a string field, you get the text of the node, which in this case is the association value. Which in this case is the unique identifier in the EBS HR system, which is what the shim should be sending.

If you ever work on a SOAP driver, you will find this really confusing since the shim does not generate an Association value to send back for you, it is up to figure out what that should be, and generate the appropriate <add-association> event yourself to the event flow, so that the engine can properly process it. If you do not, you will end up with unassociated objects which is really just a waste of time.

Alas, I have yet to find anywhere in the docs where this notion is pointed out. This is specific to the SOAP driver, since it is more of a protocol level driver, than a fully functional one. The Delimited text and database ones are also similar in that way, but the text case, it does not a lot of sense to have an association, and in the Database case, the primary key, table name, and schema name are pretty much the keys to defining an object so the shim does send those back in <add-association> case. This makes the SOAP driver somewhat unique in that case.

That was a pretty simple rule, but it gets me wondering, is not the ebsPersonId in the schema, directly mapped to an attribute already? I see it in the filter (Pub sync only) and in the schema map, mapped to P_PERSON_ID. So I am not sure why they would have this rule?

Maybe in the case of a Subscriber channel add, because the entitlement UserAccount was granted, the user is created, but we do not send the DirXML-ebsPersonId into the system, so once added. the returned event of <add-association> is how they get that extra generated piece of information out of EBS and into the driver.

That about wraps up this article, stay tuned for more in the next article in the series.