Around the 2013 to 2014 timeframe a series of enhancement packs were released for Identity Manager 4.02. This was an interesting approach as it added functionality to the product, but was not a product upgrade.

The new stuff came in several forms.

There was the new User App front end interface, code named Aquamarine, released as Home and Provisioning Dashboard. The comment had always been, if you do not like the User App interface, write your own in your portal tool of choice, and when you need to interact with User App use SOAP. Some people did, most people did not. NetIQ released HPD as their attempt at a new user interface. User App is still there in background, there is just a new front end. The new UI elements are designed to render better on mobile devices which is very helpful as well.

There was a replacement for Role Mapping Adminstrator (RMA) that came with IDM 4.0, codenamed Garnet, and released as Catalog Administrator. This uses the same UI elements as HPD for consistency, and tries to make the task of managing Role to Role, and Role to Resource assignments easier, and in fact something you can dump on a business person. The goal was to get IT out of the process of managing Roles and make it easier for a different type of person in the company to manage it.

Access Review came out as a standalone licensed product, which differentiates it from this set, but it tries to manage the issue of Role lifecycles. Shares the same UI, and tries to import users, roles, permissions from IDM and other systems, consider risk factors for particular roles or permissions, and then require reviews on a schedule. This help meets some audit requirements where certain classes of access need to be 'renewed' weekly or the like. (PCI I am looking at you!). Again, this shares the same UI as HPD and CA, which is a nice touch. Consistency is appreciated.

On the mobile front, the project codenamed Citrine was released as the Mobile Approvals App for iPhone. This is meant to ease the burden of approvers of 'stuff' as now they can do it from an app when they get notified, instead of web page, login, etc.

Finally we get to a backend project, codenamed Jade, that was released (sort of) as Permission Collection Reconciliation Service (PCRS). There is no user facing front end to this project, it is mostly policies in drivers that need to be deployed.

There are two aspects of this project. First, without lots of Resources (aka Entitlements with values) or permissions (at a more abstract level) then the Roles model does not have a lot to manage.

Second there was a recognition that Roles might benefit from being slightly more bidirectional. Right now the management of permissions in remote systems via Resources/Entitlements granted by Roles relies on the fact that no one else is managing those things in the remote system out of band. If they are, it becomes very hard to rely on the Role model data to assess permissions and review access.

Thus the goal of PCRS was to make importing Resources easier and then where possible event on changes in the remote system to reflect the changes back in the Roles model.

This code is a set of policies, mostly released on the Delimited Text and Active Directory drivers.

The Delimited text code handles the first case primarily, importing lots of Resource and holders of that Resource. This is done by defining a series of CSV files that will be read to import the current state of the Resources and assignments in whatever system you may have.

Now it happens that those CSV's can double up for use in Access Review as a data source. Of course if you use the PCRS policies to import them into the Role model. no need since that data will already be represented through the IDM connection in Access Review.

The Active Directory driver focuses more on the aspect of keeping the holders of those Resources correct as things change in Active Directory.

Going through the policies that implement this will be interesting, since this mostly resides in a single package for each driver. I will start with the Active Directory driver. The specific package versions I am working with are:

Active Directory Entitlements and Exchange Mailbox Support		2.4.0.20140930152155
Delimited Text Entitlements						2.1.0.20140828163025

The 2.4.0 build for AD seems to come from the package update site, so it is not Designer 4.5 specific.

When you import a driver with this package, a Prompt object writes some text explaining that this requires IDM 4.5 The amusing part is how they get the text into the prompt window. I had seen this before and kind of wondered. So this time I actually went and looked at the NOVLADENTEX-Warning objects content which has this trimmed for brevity content:

<configuration-values>
	<definitions>
		<header display-name="Important Note:"/>
		<header display-name="Designer 4.5 has a fix to address a weighting problem where policies that were"/>
		<header display-name="assigned with similar weights could be deployed in the wrong order."/>
		<header display-name="Please upgrade to Designer 4.5 and perform a 'Migrate Linkages' on the package catalog. "/>
		<header display-name="Once this completes do a compare to your deployed driver in order to verify"/>
		<header display-name="if there will be a change in the policy order."/>
		<header display-name=" "/>
		<header display-name="   "/>
		<header display-name="This version of AD Entitlement and Exchange Mailbox Package requires:"/>
		<header display-name=" * Identity Manager 4.0.2 with Engine Patch 5 (or later) or Identity Manager 4.5"/>
		<header display-name=" * Designer version 4.0.2 Auto Update 3 (or later) or Designer version 4.5"/>
		<header display-name="*  mandatory  "/>
		<definition display-name="test1" hide="true" name="test11" type="string">
			<description>Dummy Text</description>
			<value>Dummy</value>
		</definition>
	</definitions>
</configuration-values>

They use Header lines for the text. I have to pause at the audacity of that approach. How wonderfully silly a way to do it. Do note this is coming from a guy who uses disabled Trace tokens in policy for inline commenting. I believe I am living in that glass house and actively throwing stones.

But the key is you need IDM 4.0.2 with engine patch 5 or higher, since that is where they added the Startup and Shutdown policy linkage ideas. You get all sorts of interesting possible errors if you deploy this to the wrong version. My favorite I discussed in this article about an Index out of Bounds error:
https://www.netiq.com/communities/cool-solutions/idm-array-index-out-of-bounds-error/

I have also heard that the policy may get imported, but the linkage may get discarded so the policy floats about unlinked as well.

As long as I am discussing Package Prompts, which I normally do not in these walk throughs, I should discuss a particularly clever one. There is a Mapping table, PermissionNameToFile that is part of the Delimited text approach to reading sets of permissions in through a file. When you install the Package, you get a prompt object that when the Package is on the user, shows just the XML of the GCV prompt. So it has a Structured GCV (the <template> node with four fields:

• entitlementName

• assignmentAttribute

• csvFile

• multivalued

When you enter some values during the package installation/upgrade, those values get written to the PermissionNameToFile mapping table object. How that happens is quite interesting. To see it, you need to go to the package catalog, expand the package we are working in (Active Directory Entitlements and Exchange Mailbox Support) which is under Directory, Active Directory, and then expand the 2.4.0.datestamp node, and finally the Resources node, then double click on the PermissionNameToFile-Prompt resource object.

There are four tabs:

• General

• Prompts

• Prompts Transformation

• Target Transformation

General:
This tab has the name, the type (set to Custom, instead of one of the well known values like Remote Loader, Initial Settings, etc), an order value, and finally a Target field, pointed at the Mapping table object. This means when the package prompt is processed, the mapping table file will receive the output if any.

Prompts:
This tab is the same as the content delivered in the Prompt object once the package is on a driver, but there is no Edit XML button at this point.

Prompts Transformation:
This is meant to read the current values on the Target object into a variable, that can be transformed after Admin user input into the content to be written back.

Put another way, this needs to parse the Mapping table XML, into GCV formatted text, display it on the UI as the Package is being added, if any changes are made, (generally removing, adding, or changing an instance of the structured value in this case) get all that info into the variable to be available for the next step.

You can see the guts of what is going on in this trimmed snippet.

<xsl:template match="definition[@name='NameToFileMapping']/value">
	<xsl:copy>
		<xsl:apply-templates select="@*|node()"/>
		<xsl:for-each select="$curDoc//row">
			<instance>
				<definition display-name="Entitlement Name" name="entitlementName" type="string">
					<description>Entitlement name</description>
					<value>
						<xsl:value-of select="./col[1]/text()"/>
					</value>
				</definition>
			</instance>
		</xsl:for-each>
	</xsl:copy>
</xsl:template>

It matches the value node, under the definition node, whose XML attribute name is NameToFileMapping,
I.e: <xsl:template match="definition[@name='NameToFileMapping']/value">

Then it copies (<xsl:copy>) the data as it loops over the $currDoc//row which is $currDoc that has the Mapping table XML, and the <row> nodes exist for each row in the table. Then for each of the 4 values we discussed above, it rebuilds the GCV formatted XML, where the value is copied out mapping table data as:

<xsl:value-of select="./col[1]/text()"/>

That is, col[1] means the first column in the list, since in mapping tables order of the <col> nodes matters as the order defines which column the data is from.

They do the same thing for the other 3 components of the GCV.

This does it over each line of the Mapping Table XML and builds up the proper GCV formatted XML. This XML will be displayed in the Prompt display during package install or upgrade. If you use the GUI to add a new instance, delete one, or change one, then that affects the XML in memory.

Target Transformation:
Once you click Ok on the editing you did (or not) in the GUI, the Target Transformation is applied. This takes the contents of the document held in memory after your editing and does what it is supposed to do, to transform it back properly. This makes a lot of sense in the Remote Loader prompt case where the Remote Loader options you see in Designer are really pulled apart from a single string value in an attribute of the driver. The Prompts Transform reads the string, pulls it apart into its bits, displays them in the right place, and then the Target Transform puts it all back in the proper format.

If you can find older Packages, try and look at the Remote Loader Prompt object, at the Target Transformation and it will look pretty straightforward. Now look at it on a modern package. They found a whole bunch of edge cases they needed to handle and the XSLT got totally out of hand! On the other hand, a good example of XSLT to learn from.

Here we need to transform data in the Structured GCV XML format to the Mapping table XML format.

The guts of it are right here.

<xsl:template match="mapping-table">
	<xsl:copy>
		<xsl:apply-templates select="@*|node()"/>
		<xsl:for-each select="$defsDoc//instance">
			<row>
				<col>
					<xsl:value-of select="./definition[@name='entitlementName']/value/text()"/>
				</col>
				<col>
					<xsl:value-of select="./definition[@name='assignmentAttribute']/value/text()"/>
				</col>
				<col>
					<xsl:value-of select="./definition[@name='csvFile']/value/text()"/>
				</col>
				<col>
					<xsl:value-of select="./definition[@name='multivalued']/value/text()"/>
				</col>
			</row>
		</xsl:for-each>
	</xsl:copy>
</xsl:template>

It helps if you can visualize the Structured GCV XML I find.

<definition display-name="Add Name To File Mapping" instance-separator="
" name="NameToFileMapping" type="structured" value-separator=",">
	<instance>
		<definition display-name="Entitlement Name" name="entitlementName" type="string">
			<description>Entitlement name</description>
			<value/>
		</definition>
		<definition display-name="Entitlement Assignment Attribute" name="assignmentAttribute" type="string">
			<description>Name of attribute containing Entitlement values</description>
			<value/>
		</definition>
		<definition display-name="CSV File" name="csvFile" type="string">
			<description>Path to csv file on local system</description>
			<value/>
		</definition>
		<definition display-name="Multi-valued?" name="multivalued" type="string">
			<description>Can multiple values be assigned for this entitlement? ('true' or 'false')</description>
			<value>true</value>
		</definition>
	</instance>
	<value/>
	<description>Add a value for each entitlement and assignment attribute, and specify the associated CSV file by selecting the ' ' button. </description>
</definition>

There is a parent <definitions> node it is contained in, but this just saves some screen real estate.

So the template copy's as it loops over the $defsDoc variable, all the <instance> nodes, and there is one for each instance of the Structured GCV you added. It then builds the Mapping Table XML knowing that the order of the <col> nodes matter. The first <col> in the XML is the first column of data in the table. Thus we need to shove in as the value there:

<xsl:value-of select="./definition[@name='entitlementName']/value/text()"/>

Which means the text() of the <value> node, under the <definition> node, whose XML attribute name is entitlementName. We see this is the first one in our GCV definition. And the same is true for the other three.

In other words this uses XSLT to convert the GCV XML to the Mapping Table XML. (Not a generic solution since ordering matters and you have to know it, but clever nonetheless).

Well that was all mechanistic about what is happening. How about figuring out why this is happening... What this does is allow during driver creation time (or upgrade) to specify in a GUI all the Entitlements you want to load from CSV files. You can later go add new entries in the mapping table. But as you import the driver there is no other way (so far) of getting input into a Mapping table.

The columns are the names we have seen in the XSLT and GCV definitions.
     entitlementName
     assignementAttribute
     csvFile
     multivalued

I do not yet understand what these are used for, but I hope to get there as I move along through the driver.

There are two other mapping tables but neither has a Prompt object to fill them in. Here are the tables and their columns:

PermissionNameToFile
     entitlementName
     entitlementDN
     resourceDN
     csvFile
     multivalued
     assignmentAttribute

StaticValueEntitlementMap
     entitlementValue
     staticResourceDN

I am going to have to come back to these in a later article since I still do not fully understand their use. But I expect to fix the gap by this process.