Using Simulator in Designer


Novell Identity Manager allows you to use a couple of different languages to manipulate event data. Initially almost all that was available was XSLT, the XML Style Sheets. This approach is still available and useful in some cases. However, with later releases of Identity Manager a new language, DirXML Script has become available.

There are many differences between XSLT and DirXML Script, and many advantages to each. I personally think that DirXML Script has reached the point where it can do everything needed and that XSLT can be avoided at almost all times. So much so, I was looking for a list of things you can only do in XSLT still that you cannot do in DirXML Script. You can read about that here: Open Call: What Can You Do in XSLT that You Cannot Do in DirXML Script?

One of the interesting things that DirXML Script brings with it is a large set of predefined tokens that do things that are useful. I have been slowly writing about many of them as they get added in each new release. (Alas, since the focus of the IDM 4 release was more on delivering support for Packages, there were no new tokens added, however Packages are a cool enough addition I am willing to forgo any new tokens in this release).

Some of the tokens I have written about are listed here:

There are many many more I could write about and probably will one of these days. However, another thing that DirXML Script brings to the table is tracing. That is, much of the work being done, instead of being a black box, where you shove input in, look at the output and decide if it did what you wanted, you can see the sausage being made, with the use of tracing.

To read more about Dstrace and reading Dstrace you can see these articles:

The last three are by a guy at Novell Technical Support and are the best articles on reading DStrace I have seen to date, way better in fact than the documentation, which really does not seem to address the issue well at all.

When using iManager, which also can edit DirXML Script, you make your changes, and they are saved live to the directory. Once you restart the driver, they take affect. However, Designer is in many ways a better editor than iManager, and the process of making a change, saving it, compare it to the tree, restart the driver, trigger an event to test the code change can get tedious.

For large complex rules this is probably fine. For things that need to process a large chain of events between multiple drivers, handing off from one to another there is little other choice. But when you are debugging a simple piece of code that has a complex bit of logic in it, there is nothing better than Simulator in Designer.

With Simulator, you can provide the input document, run it through your rule, and see the results quickly. This lets you quickly iterate through a bunch of possible solutions. I find this really helpful when trying to get a complicated XPATH expression working. I can run through a dozen iterations of what I think should work, through in trace examples to try and see what isn't working and nail down the issue, usually in the time it would take to run through one or two cycles of pushing it out to the directory and restarting the driver.

Simulator works by actually having copies of the core IDM libraries available in Java in Designer, and when you click on Simulator it runs your DirXML Script through the complete engine code. This has some very amusing side effects. For example, in one particular case I was working on an IDM 3.6.1 project but using the shiny and new Designer 4 version. I was using a Replace All token, and storing the value in a local variable. Well it turns out there is a bug in IDM prior to IDM 4 that any special regex like characters (Usually comic book swear words like !@#$%^&*(){}|) might get expanded incorrectly. Usually you see the little box character in trace that indicates it might be a non-ASCII character trying to be displayed. In Designer 3 and 3.5 this bug is accurately reproduced, since those builds literally use the same JAR files the engine is using. However in Designer 4 it is using the JAR files from IDM 4, and it looks like this bug has been fixed. So I was testing in Simulator since I remembered there being an issue around this, it looked good, I deployed the changes, tested again with an event and low and behold it failed. Well it looks like that specific bug was fixed in IDM 4 (which is great to see) but still there in IDM 3.6.1 so I had this odd behavior to account for.

However this is probably a pretty rare case, and using Simulator is worth these possible little issues. But if something works in Simulator but not in the engine, keep in mind this possibility.

You can choose to Simulate at many levels. You just have to select the right context to tell Simulator to run. If you right click on a driver icon in the Modeler view (The one with the pictorial layout of your trees and drivers) and select Simulate from context menu that pops up, you start the process at the entire driver level. I almost never do this, since the queries and whatnot I would need to respond to are too much work to manage as I will discuss in a a moment. However, I recall reading that Designer 4 will now correctly simulate the Input and Output transforms when running the Simulator at this level, which may not have been the case in earlier versions.

From the Outline view, in the Policy flow view (Which is usually described as the Fishbone view) you can select a particular policy set, like the Subscriber Command Transform and simulate the entire Policy Set.

From the Outline view, in the Model Outline view, where the drivers are shown as a tree of objects, you can select a channel (Subscriber or Publisher) and simulate the entire channel in one go.

I usually use it within a single Policy object since in the upper right hand corner of the screen you edit the Policy in, you have a couple of buttons. They are a multi selector for New rules, Deploy, Compare, Simulate, Name space editor, a pair of arrows to let you move rule objects ordering around, and then a crazy option for Tracing followed by Help. I say a crazy option for tracing since I never used it, until I was at a client site looking at Policy, and EVERY single token and place where you could disable trace, it had been disabled. From a manual perspective, this was potentially hours of work to do, especially when you could just disable trace on the parent rule once, instead of disabling it on every single level below it. Turns out iManager and Designer have had this option for a while, and if select to disable trace with this option it goes out and does this, which seems a bit daft.

But as you can see, just as there is a handy Compare button available, there is a handy Simulate button. The icon took me a long time to figure out, since I run at fairly high resolution to get more screen real estate, and thus it is really tiny on my screen, but I think it is meant to represent one of the chevrons used by the Fishbone view to indicate a policy set, and then overlain with a Run triangle in a circle.

Now, once you do this, it launches a window that shows an XDS document editor. There are two views XDS Builder and Source. This is actually really helpful, as XDS Builder knows what an XDS document should look like, and lets you graphically generate a mostly representative event to work with. Then like with Policy Builder, if you need to tweak it, you can pop over to the Source tab, and edit the XML as needed. For example, if you need to simulate 5 or 10 attributes, it gets to be a pain using the GUI. Instead, add the first, change over to the Source view, copy the XML for that attribute, paste it 9 more times, then go change the attribute names and values.

You can just paste in an event from your real Dstrace and work from that. In fact, when working on Input or Output Transform rules that do complex transformations, I usually paste a copy of a sample event into the Comments, so that when I revisit it later, I do not have to go hunt for an event to use in Simulator, I can just copy it from the Comments node and use it.

However, the XDS Builder knows about the various event document types, and you can select from a list, and get a bare bones starter. Then you can flesh it out in the builder UI, selecting an object class from a list, then attributes from a list (Saving you the common embarrassment of attribute name typos). It also knows how to add and remove values correctly for each event time, which helps keep your XDS valid.

One thing I noticed in Designer 4 that I had not noticed before, was that when I started with an Add event, and manually added some complex attributes being added, when I told the XDS Builder to switch to an instance doc, it correctly reformatted my sample document, which was great. I figured I would have to manually fix it up, or start from scratch, but it correctly changed from <add-attr attr-name="CN"> nodes to <modify-attr attr-name="CN"><add-value> to <attr attr-name="CN"> just by toggling my selection in the UI. That was great!

This actually in really handy with the next feature of Simulator. (Remember that I took my <add> event with a bunch of attributes, and converted it to an <instance> event, which is a response to a <query> very easily). If you hit a point in the policy flow, where you use a token like Source Attribute which queries back to the source, or even the more direct Query token, then a query event is generated, and the Simulator UI shows you the <query> event in the same basic window you started with. However, this time at the top there are two tabs, Query and Response. You can manipulate the Query events XDS if you want, or just examine it to be sure it is asking for the right info. But since it does not actually perform a live query, you have to go to the Response tab along the top, and build or provide (remember that <instance> doc I just had available? Well I copied it into a text editor for safe keeping and now can paste it into this window) the response, which would be an <instance> document.

This way you can simulate live queries. Now this gets pretty tedious, if you do not have all the response documents handy to paste in, so I usually do not test more than a single rule at a time, (this is what I was referring to above as to why I almost never simulate an entire driver, channel or even an entire policy set, too many queries to handle).

Designer seems to remember the input document you started with, even after you close the Simulator window to go back and make a change and test again, it seems until you close the Policy editor page for that policy. From the XDS Builder you can save your event documents and load them from the file system. Designer comes with a bunch of them, but I usually provide my own.

Once all the rules are processed, you see the usual level 3 Dstrace. Now that I mention it, I never thought about how you control trace levels in Simulator. I assume it just takes it from the settings for the drivers. Just like it is able to access Global Configuration Variables (GCV) and things like Mapping Tables and the like.

Regardless, now you have a simple trace sample to look at, look for your code to see if it worked, and try to decide what did and did not work, close out of Simulator, make a policy change, save it and try again.

As you can see, this really can help speed up the code development process in IDM.


How To-Best Practice
Comment List