Some interesting messages when importing a workflow

NetIQ Identity Manager has followed an interesting evolutionary path over time. It started as a simple object and attribute synchronization engine with DirXML 1.0 and more features have been added over time. One of the more interesting enhancements has been the addition of the Roles Based Provisioning Module (RBPM) which is really several things all lumped together.

The front end interface for it all is the User Application (User App) from which several different components fork off. There is the web interface itself, used for white pages, User self service (password, and attribute changes), and requesting access to resources. While serviceable, this has not been the favorite for many folk. The good news is, that there is a new web interface coming, shown at BrainShare, and getting closer as the latest patches show (For example, Engine Patch 2 and User App 4.02 Patch C release notes have said they are required to support the new end user interface), that redoes the interface. It looked pretty good at BrainShare, so looking forward to seeing it in action once it is released. (This used to be known as the Aquamarine project) On top of that the Approvals App has been available in the Apple App store for a few months now, and lets you manage approvals in an App. (This used to be known as the Citrine project).

There are some interesting out of the box interactions. For example, there are some simple approval workflows that can be required by a Role or Resource request to ensure you get approval from your manager before the Role or Resource is granted. Ok, that is a bit circular, but the point is, the term approval, becomes an action of approval which can be logged and audited and that is the key point. It is all about having someone to blame. If a rogue user gets access do to an approval, there is someone to hold responsible for letting him have the access. (The old someone's throat to choke).

What is nice about this out of the box approach is that there is little to no work to be done in the PRD. The stuff available in a PRD contains a ton of functionality and can be customized to an amazing extent. Alas, never enough customization, as someone always wants more, but the things you can do are quite amazing. The interface for working on a PRD is full of tabs, different windows and views, which are all very confusing at first (and even later, sometimes I cannot find stuff I know is there, and have to go hunting in the usual locations)

Most people find it sufficiently confusing that I felt the need to write this short series on where all the 'stuff' is, in the PRD editor.

There are little pieces you need all over the screen, sometimes in the Properties window (Bottom left, select the Properties tab), sometimes in the Data Item Mapping view (Right click an item, select Show Data Item Mappings), as well as having tabs upon tabs in the main view. Heck if you use an Integration Activity, you get several more nested levels of tabs available. It is literally the definition of confusing, but oddly powerful, once you get used to it.

Don't get me started on the Integration Activity! That is actually one of my favorite parts of it all, but goodness that is a confusing interface to develop in.

With the release of IDM 4.x a new concept called Packages was introduced to the product. Usually people think of it as a way to add a new driver or apply customizations to a driver. However in this case, it is customizations for the PRD specific pieces that are of interest to me in this article.

This can be quite nice since it makes staging your work from one environment (Say Development or QA) to another (say Production) much easier. Rather than exporting each piece you changed (or even figuring out what you changed) you work along, sync the content to the package. As you work on it and the content changes, the changed item will get flagged as customized, at which point you can right click and Revert Customization if you did not mean it, or Sync to Package if you did. Each time you add or sync content to a package, it is remembered, and if you go to the Properties page of your version of the Package, in the Package Catalog. there is a Readme page. This is my favorite, and least used page. Here is where you describe what this package does, contains, and what changed since the last version. If people did this more completely I would not have to write articles explaining what changed in various packages. There is a button called Append Changelog that will paste in, all the changes made to this package, in terms of objects added, removed, synced, and reverted from the Package. This allows you to remember all the changes you made, and possibly document each change.

Ironically, in earlier Designer releases (4.01 before Auto Update 2 I recall), if you used Version Control, and shared a project with Linux and Windows user. it was sometimes possible to get an improper line feed or carriage return character in the file it stores the changed information, that would make the SVN components refuse to synchronize the project, but that is since fixed.

When all your customization work is done, go to the package catalog and build your package. Test it on a sample User App driver instance in your project, and if all looks good then just the package is needed to define all the changes in QA or Production. One heads up though, the version of User App you build against is the only one the package will work against. I am still trying to figure out how you are supposed to upgrade. My current theory is you would add the package built against a 4.01 User App and deploy it. Make a new package version. Then remove all the content from this package. Thus version 1.0.0 has all your content for User App 4.01. But version 1.0.1 has no content at all. Then upgrade your User App to 4.02 and the content should have been upgraded as well. Now make a version 1.0.2 against this driver, and see if you can add back in the content. I think you might run into a version issue still, as the package itself might be tagged as for User App 4.01. In which case you would have to make a new package entirely to add the content back into. This is a fairly major bug in my eyes, and has been reported.

With Packaging, the details are the killers, but they are not that bad in this case. For example, if you normally would modify the DAL (Directory Abstraction Layer) to add an attribute to the default User class for querying, you really should reconsider. Instead, make a new Entity entry (acmeUser for example) and define all the attributes you need there. Then find all your IDVault.get() style function calls and change the syntax in your workflow from:

IDVault.get(recipient , 'user', 'Email')

to something more like:

IDVault.get(recipient , 'acmeUser', 'Email')

In your forms, you would have to change the syntax more like:

IDVault.get(null, dn, user, attribute)

to more like:

IDVault.get(null, dn, acmeUser, attribute)

Of course if you happen to have any Entity Actions in your workflow, in the Properties tab (Bottom left, one of the four in the default layout) you should change the Entity type you are referring too from user to acmeUser as well. Be aware that any ECMA defined in the Entity Action will be lost when you make the switch so back it up in a text editor first.

If you add your own DAL Entity for all your work, you can then add it to your package, and not dirty the base User Application package. It is important to avoid dirtying the base package as NetIQ Support is very likely to ask you to return to Factory mode, if you think you have a bug, and that would of course throw away any changes in the default user DAL Entity. Which would have the side effect of killing any workflows or forms that relied upon the functions that use the Entity entries in the DAL.

Now officially you are supposed to use Project Checker and clean up any errors before you deploy stuff in the RBPM space, but if you have ever looked at Project Checker's output you will likely see thousands of issues. The deeper you read, the more cosmetic you realize most things are. For example, you will likely have dozens or hundreds of localization errors. That is, every field and string on the Provisioning side can have values for all languages. If you are a cultural imperialist like we are here in North America, you probably defined just your values in your default language and nothing else. You will be amazed at how many of these warnings there are. To be fair, you can filter out the Warnings, which helps a fair bit. I admit that I usually throw my code over the fence into the User App, via a deploy, and test, before considering Project Checker for any errors. But when it does fail, the Project Checker is a good tool to examine to see what hints you can get.

Probably my major complaint is you cannot run it focused on a single object. I would love to say, Project Check this PRD. Sure it might need to look at the DAL, if any queries are made using it, but keep it focused, the results short, sweet, and most of all faster.

I recently was testing a Packaged PRD I was working, which is what spawned this article, and when I tried to apply it to a new test User App driver in Designer, I got the following errors:

The following changes were made to the Provisioning Request Definition 'Get Customer and Invoice Numbers':

Changes to existing forms:

  • The field 'CustomerNumber' has a property 'display-entitydef' which is attempting to use an invalid entity name 'CustomerInvoice'. Resetting the value to a blank.

  • The field 'CustomerNumber' has a property 'display-exp' which uses an attribute whose entity is invalid. Resetting the value to a blank.

  • The field 'InvoiceNumber' has a property 'display-entitydef' which is attempting to use an invalid entity name 'CustomerInvoice'. Resetting the value to a blank.

  • The field 'InvoiceNumber' has a property 'display-exp' which uses an attribute whose entity is invalid. Resetting the value to a blank.

Changes to existing Data Item Mappings:

  • Data-Item map for the entity activity 'Activity1' has reference to an invalid attribute 'MyAppUser' and has been removed.

This happened when I applied the package, and basically lost data in the model. The good news was, I had it packaged, so once I figured out the issue, I could build a new package version, and just upgrade in my test case. Or more likely Uninstall and then Install it again.

It turns out none of these issues were found in Project Checker, because the User App I built this on, had the proper DAL entries, I just forgot to include them in my package. This was a nice second level check for errors, even if I remain unconvinced that 'fixing' the data by removing it was the right option. I would have preferred to have my PRD in an error state, so that I could then add in the DAL entries, and get it to work. With the changes Designer made, had I not been using Packages which would let me try again easily, I could have lost real work.

In this case, my DAL entries for CustomerInvoice, which has two attributes CustomerNumber and InvoiceNumber were somehow lost. Also I had a custom User class in the DAL to support the MyAppUser attribute and that got lost somehow as well.

I was able to remove the package, add it back again, and this time it got the bits it needed, which was overall a bit of an odd error. But it was an interesting error, and it is clear what the cause is for the error is, at least in terms of the immediate problem.

If you have run into any interesting error messages like this, it is worth considering writing an article to share what you figured out, and better, how you figured out what the issue really was caused by.


How To-Best Practice
Comment List