Let’s talk some more about Packages in Designer 4 – Part 8

geoffc

By: geoffc

February 4, 2011 12:16 pm

Reads: 312

Comments:1

Rating:0

This entry is part 8 of 9 in the series Let's talk some more about Packages in Designer 4

Novell Identity Manager initially came with a Console One plugin to manage policies and stylesheets, back when it was still called DirXML. Then as the product matured and DirXML Script became available we got iManager with plugins to manage it.

When Designer for Identity Manager was released, it really was a game changing paradigm shift for Novell’s product. Being able to take a project offline, work on it, come back, push out (and double check) your changes made how we work on IDM projects totally different. Documentation generation did not hurt either!

Each release of Designer has added new features and functionality. I recently worked through a series on what is new in Identity Manager 4 Advanced Edition (and compared it to what was introduced with IDM 3.5 and 3.6 releases), which you can read here:

Of course most of those features discussed included support for managing them in Designer. In fact, the series on what has changed is more focused on what has changed in Designer. But that was a high level overview and so much more has changed down low in weeds it is going to take a fair bit of work to get through them all.

With Identity Manager 4 Advanced Edition there are some major engine and Designer changes that are yet another example of a paradigm shift, and it can be summed up in one word, Packages. I started talking about Packages in these articles:

There is so much to say about packages, that I wanted to continue on to some more of the interesting features. I realized after I finished the last article that this would really just be a series regurgitating the documentation, so I actually went and checked the documentation to see how much is there. That is when I realized there is almost nothing about building packages in the docs. There is a single long page with almost no useful details in it, so hopefully this series will be a good resource for others. If you see some details in a documentation page missing please be sure to use the Submit Comment button, as there really is a person at the other end of that link. (A busy person usually, but they do often respond).

In the first article Let’s talk some more about Packages in Designer 4 – Part 1 I talked about versioning, base packages, building prompts, interesting linkages, GCV and filter extensions.

In the second article Let’s talk some more about Packages in Designer 4 – Part 2 I talked about more details in the nitty gritty about packages like localization, dependencies and ordering, and finally about the package catalog and what is stored there.

In the third article Let’s talk some more about Packages in Designer 4 – Part 3 I discussed how the process of adding a driver changes with the new package model.

In the fourth article Let’s talk some more about Packages in Designer 4 – Part 4 I discussed options about building packages and some of the states that a package might go through in terms of usage, and in terms of recommended development paths.

In the fifth article Let’s talk some more about Packages in Designer 4 – Part 5 I started looking at the various resource types that can be part of a package, and how they differ from their standard representation in a driver which would include the various new features added to support the package infrastructure. I was able to cover Global Configuration objects and Filter extensions.

In the sixth article Let’s talk some more about Packages in Designer 4 – Part 6 I talked about how objects are named and how a Resource can make changes to the configuration as it is being imported.

In the seventh article Let’s talk some more about Packages in Designer 4 – Part 7 I continued with further examples of how the XSLT in Prompt Resources can manipulate the driver configurations. The documentation on packages is pretty light at the moment, so I have been browsing through the packages included with IDM 4, specifically the Active Directory driver, the Managed Systems Gateway driver (used by Reporting) and the Data Collection Service driver (also used by Reporting), looking for interesting items. In the previous article I found a very simple example of using XSLT in the Target Transformation section of a Prompt resource to set an Engine Control Value. I was able to find something more complicated to work through in that article.

In this article I mostly want to talk about administrivia. Things you ought to know, that are not that important by themselves, but I have not been able to find in the docs.

For example, in Package Developer Mode, once you create a package, while you can change some of the settings, like the name, shortname, and Description, you cannot directly change the version, for that you need to right click on the package version and select New Package version. This is important, as you might think as you were working and fixing issues, it would be nice to just increment the value after a certain amount of changes. This forces a bit more rigidity and probably in a good way, to keep different versions around. Thus you will have a history of your work you can revert too. (You can lead a fish to water, but you cannot make him swim… It only works if you use it.)

What I found interesting was that once it was created, you cannot change the Target (IDVault, DriverSet, or Driver), Category, Group, or whether it is a base package or not. I suppose when you think about it, that makes sense as this would imply a move of the package from one place to another. However you do have the flexibility at create time to create a new Category and Group, since it is such a pain to move one around. Though you could make a new package in the new location and just copy all the contents of the old one into it instead.

In the seventh article I talked a lot about the prompts, and how they work upon some XML that comes from the objects. Well the Package itself has an Initial Settings tab, that you can look at after it is created. I trimmed it down to one line per item referenced. That is, in the Health config I left only the green node. In the Schema definition node I left it with just one attribute and so on and so forth, just so you get a feel for the XML structure. Seeing the structure makes it easier to understand how some of the XSLT might apply to it better. I think this is the content, or at least a similar set of content that the curDoc variable that we discussed in the previous article is referring too. Thus the Target Transformation works on XML that looks like this sample document.

This is much the same as you have in a iManager driver export so it is pretty easy to understand if you have ever looked at one of those exports in detail. I had an instance where I needed to roll out an upgrade to a 35 driver project and we had lots of changes. We edited the export file to remove all the password prompting, and libraries and things we knew had not changed, and used that to update the existing configuration.

<?xml version="1.0" encoding="UTF-8"?><ds-attributes>
	<ds-attribute ds-attr-name="name">
		<ds-value>Active Directory Driver</ds-value>
	</ds-attribute>
	<ds-attribute ds-attr-name="application-schema">
		<ds-value>
			<schema-def dn-format="ldap">
				<class-def class-name="user" container="true">
					<attr-def attr-name="accountExpires" multi-valued="false" type="int"/>
					<!-- Trimmed a couple of dozen attributes  -->
				</class-def>
			</schema-def>
		</ds-value>
	</ds-attribute>
	<ds-attribute ds-attr-name="configuration-manifest">
		<ds-value>
			<manifest>
				<DirXML-DriverId>AD</DirXML-DriverId>
				<!--                    password capabilities               -->
				<!-- supports publisher modify password notification when Active Directory password changes -->
				<capability name="password-publish"/>
				<!-- supports subscriber password and modify password commands to change Active Directory password -->
				<capability name="password-subscribe"/>
				<!-- supports subscriber verify password commands by attempting a login to Active Directory -->
				<capability name="password-check"/>
				<health-config>
					<green>
						<and>
							<and>
								<driver-state state="running"/>
								<in-cache-overflow state="false"/>
								<unprocessed-size op="lt" value="2000000"/>
							</and>
							<or>
								<transactions op="gt" over-last="2" source="publisher-reported-events" value="0"/>
								<sample-history minutes="2" op="lt"/>
							</or>
							<or>
								<transactions op="gt" over-last="2" source="subscriber-command-results" transaction="total" value="0"/>
								<sample-history minutes="2" op="lt"/>
							</or>
						</and>
						<actions>
							<generate-event id="1230" level="log-info">
								<event-arguments>
									<event-argument name="value" value="0"/>
									<event-argument name="value3" value="1"/>
									<event-argument name="text2" value='Driver entered "Green" state'/>
								</event-arguments>
							</generate-event>
						</actions>
					</green>
				</health-config>
			</manifest>
		</ds-value>
	</ds-attribute>
	<ds-attribute ds-attr-name="driver-filter-xml">
		<ds-value/>
	</ds-attribute>

	<ds-attribute ds-attr-name="native-module">
		<ds-value>addriver.dll</ds-value>
	</ds-attribute>
	<ds-attribute ds-attr-name="log-events">
		<ds-value/>
	</ds-attribute>
	<ds-attribute ds-attr-name="shim-config-info-xml">
		<ds-value>
			<driver-config name="Active Directory Driver">
				<driver-options>
					<configuration-values>
						<definitions>
							<header display-name="xlfid(NOVLADBASE.initial.settings.param.header.AuthenticationOptions)Authentication Options"/>
							<group>
								<definition display-name="xlfid(NOVLADBASE.initial.settings.param.auth-options)Show authentication options" name="auth-options" type="enum">
									<description>xlfid(NOVLADBASE.initial.settings.param.dscr.auth-options)Show driver authentication options. These parameters control how the driver shim authenticates to the Active Directory domain controller.</description>
									<enum-choice display-name="xlfid(NOVLADBASE.initial.settings.param.choice.auth-options.show)show">show</enum-choice>
									<enum-choice display-name="xlfid(NOVLADBASE.initial.settings.param.choice.auth-options.hide)hide">hide</enum-choice>
									<value>hide</value>
								</definition>
									</definition>
							</group>
						</definitions>
					</configuration-values>
				</driver-options>
			</driver-config>
		</ds-value>
	</ds-attribute>
	<ds-attribute ds-attr-name="global-config-values">
		<ds-value>
			<configuration-values>
				<definitions/>
			</configuration-values>
		</ds-value>
	</ds-attribute>
	<ds-attribute ds-attr-name="global-engine-values">
		<ds-value>
			<configuration-values>
				<definitions>
					<definition display-name="xlfid(NOVLADBASE.initial.settings.ecv.dirxml.engine.retry-interval)Subscriber channel retry interval in seconds" display-name-ref="ecnm_rint" name="dirxml.engine.retry-interval" range-lo="1" type="integer">
						<description description-ref="ecds_rint">xlfid(NOVLADBASE.initial.settings.ecv.dscr.dirxml.engine.retry-interval)The subscriber channel retry interval controls how frequently the DirXML Engine will retry the processing of a cached transaction after the application shim's Subscriber object returns a retry status.</description>
						<value>30</value>
					</definition>
				</definitions>
			</configuration-values>
		</ds-value>
	</ds-attribute>
	<ds-attribute ds-attr-name="shim-auth-id">
		<ds-value/>
	</ds-attribute>
	<ds-attribute ds-attr-name="shim-auth-server">
		<ds-value/>
	</ds-attribute>
	<ds-attribute ds-attr-name="driver-start-option">
		<ds-value>2</ds-value>
	</ds-attribute>
	<ds-attribute ds-attr-name="driver-cache-limit">
		<ds-value>0</ds-value>
	</ds-attribute>
</ds-attributes>

What is new is the use of xlfid nodes, which represents a way of referencing a localized string, so on display you get a language specific version, not just the default of English. These are the things that will get exported to a file for generating the localization information, and when done imported back in as was discussed in the second article in this series.

One problem I ran into is related to building a third party driver, and leveraging the work Novell has already done. For example, the Password Management package is pretty much the same in every driver. (Well the Notes driver I happen to know needs a minor tweak to be sure to send the old password, but that would work with all the other drivers as well). Thus if I were building my own package it would be nice to use the Novell package that is already out there, tested, and supported. However, because the ‘driver this applies to’ setting is part of the package, and the package has been released, it is basically a read only package, and I cannot reuse the Novell package, since it does not apply to my driver.

What I would need to do would be to copy Novell’s package, if I wanted to use it as is, generate my own version of it, make my base driver apply to it, and release all that as my own set of packages. This feels pretty duplicative at the moment. I have reported this issue and we shall see what comes of it. You can see this, when you go to add a dependency to your package, and you browse the catalog, you are only allowed to select packages that know about your package and allow it.

Initially I wrote: “You can see from the screen shot that although I am in the Dependencies tab of my custom driver, I can browse down to an appropriate package to make it dependent on, but I am not given an Ok button to select it, it is greyed out.

Alex M corrected me to note that I did not drill down far enough, to the package version level. I.e. Make it dependent on version 1.1.7 of the Package. Thanks Alex!

There is an additional tweak needed if you are releasing a third party driver. In the case of most third party drivers, there is a shim involved. The primary reason for that is often more mundane than technical. I know of a driver a third party releases that is basically the SOAP driver with a custom configuration. But a configuration can be copied (as we have seen with Packages, that is kind of the whole point) and cannot be licensed, in an enforceable manner. Thus they compile a custom shim that includes a license requirement and some minor bit of functionality. In the example I am discussing they basically do the schema map in a Java class instead of in the Schema map rule. This is supported and proper, and allows them to add a license requirement to use their driver.

However, Designer has a configuration setting for custom driver shims, and if you were adding your own, you would need to update it.

This does not yet seem to part of the package configuration and looks like you may still have to document adding this information by hand for your customers. Which is a bit annoying. I am told this sort of additional metadata is one of those things they intend to include, but this really is a 1.0 release for Packaging. You see this when you go to build a new package, and specify it is a Base package. You see the Supported Driver types. This is referring to the shims, and you need to add your custom shim to the preferences for it to appear. I added Testing as an example, which you can see in the screen shot.

For the first release of Packaging, you can still develop packages that are useful. The use case there would be if I were doing a project for a client, I could start with the various drivers I need, via their base packages, exclude the content I intend to modify (like matching, and placement policies) and then bundle up all my extra configuration data into a package.

This way I could deliver a JAR file to a client, that they could import into Designer, and deploy. It would lock down the content, so I know they have not ‘fiddled’ with it,. It would allow me to offer easy upgrades. When they report an issue, then we can build and test a fix in the development lab, and when done, build a 1.0.1 package with the fix, send it off, they import to the package catalog in their local Designer project, and then they get an upgrade option, and they pick up all the fixes.

While this is not 100% of the way there yet, the functionality available will be very useful, and I look forward to using it more and more. Better than anything else, this approach breaks down the content from one large monolithic configuration file, where it is a big deal to make any changes to smaller units of distribution, that can be modified and updated more easily. They can be distributed easier, and thus bug fixes can be delivered faster.

Each package can include a Readme file, which the default packages use to explain some of the work done in them and fixes included. This means a bug fix release can document what was changed and why.

This also means that my personal pet peeve, the lack of comments explaining WHY things are done in policies a particular way, is more easily resolved. If the task is defined as add comments to every policy in the Active Directory driver, well that is a large task. If the task is defined as comment on the Password Management package, and then everybody using it for any driver gets a benefit then the job is much easier and smaller, and the pay back is much higher.

I think time will tell how Novell uses this new functionality and if it works out as well as I hope.

VN:F [1.9.22_1171]
Rating: 0.0/5 (0 votes cast)
Series Navigation<< Let’s talk some more about Packages in Designer 4 – Part 7Let’s talk some more about Packages in Designer 4 – Part 9 >>

Tags: ,
Categories: Identity Manager, IDM Designer, Technical Solutions

Disclaimer: As with everything else at NetIQ Cool Solutions, this content is definitely not supported by NetIQ, so Customer Support will not be able to help you if it has any adverse effect on your environment.  It just worked for at least one person, and perhaps it will be useful for you too.  Be sure to test in a non-production environment.

1 Comment

  1. By:alexmchugh

    Where you say “I can browse down to an appropriate package to make it dependant on, but I am not given an Ok button to select it, it is greyed out.”

    The trick is to browse one level further (to the specific version of the package) and then the “OK” button is enabled.

    I’ve tested this with Designer 4.0 and 4.0.1

Comment