The Work Order driver with NetIQ Identity Manager (IDM) is both a simple driver while at the same time very complex and confusing. Much of it has to do with there being little to no limits on how you might use it.

There are some good articles to consider reading as you contemplate using a Work Order driver, which you can find at these links:

Aaron Burgemeister a great guy at Novell / NetIQ Technical support wrote these:

• WorkOrder Details

• 1 - WorkOrder Introduction

• 2 - WorkOrder Detail

• Cool Blog - WorkOrder Introduction

• Cool Solutions - WorkOrder Details

I took a stab at this in the past, in this article: Using the Work Order Driver in IDM

I would like to revisit this discussion, mostly because my feelings about the driver have matured over time, as I have been exposed to several OTHER ways to use it. I recently had to explain all this to some clients, and this has lead me to consider that maybe there is a better way to approach. Let's see if I am correct.

First of all there are really two Work Order drivers, which causes confusion in and of itself, there is the Avaya Work Order driver (which to be fair was the original, and you should not be using). Then there is the eponymous Work Order driver, which you should be using. There is also some schema confusion since the Avaya driver uses a different object class (DirXML-nwoWorkOrder) and the proper Work Order driver which I will discuss in this article uses the DirXML-WorkOrder class.

Probably the most confusing thing about the driver is what exactly does it do.

Well the simple answer, out of the box, is it polls every defined interval for existing Work Orders that have a DirXML-DueDate that is in the past, a DirXML-nwoStatus of pending, and then tries to make a DirXML-WorkToDo object out of them. It also looks for those whose DirXML-nwoStatus is complete, and DirXML-nwoDeleteDueDate is in the past to delete. There are two more queries for cleanup error cases that don't matter for this point. That's about it. It looks for Work Order objects that are due, and makes a DirXML-WorkToDo out of them, basically by copying some of the attributes out of them.

This is probably what confuses the heck out of people. Your first reaction ought to be, what then is the point? After all, what makes the Work Orders? What deals with the Work To Do objects? Ay, there's the rub. The answer to those questions are, whatever you want and however you want. That is, the driver itself does not care about those issues. Those are an exercise left to the reader.

In fact for the first time I actually saw this driver used this way recently. There was a Loopback driver used to look at events in the Identity Vault and then when it decided conditions were met it made a DirXML-WorkOrder object with an appropriate DirXML-DueDate. Then the Work Order driver processed it, and that same Loopback driver watched for DirXML-WorkToDo objects and then did something with them, cleaning them up when finished. Thus the Work Order creation, and processing of the To Do objects were outsourced to another driver.

There are however other models you can successfully use.

You could have the Subscriber channel of the Work Order driver event on changes in the vault, and make the DirXML-WorkOrder objects itself, when the conditions are right. Just write the object back to the Source (the Identity Vault, from the Subscriber channel perspective). This will not cause the driver to event on the WorkOrder creation, since the driver itself created it and loopback protection will prevent that from happening. However, on the next polling interval if the DirXML-DueDate is now due, it will event and be processed.

A very common pattern of usage in the Publisher channel would be somewhere in the Create, Placement, or Command Transform as the DirXML-WorkToDo object is in the process of being created, insert rules that do what is needed when a Work Order comes due, and just Veto the event. The problem with this approach is that the shim will decide to mark the Work Order's DirXML-nowStatus as error in that case, instead of completed as you would prefer. I had to work with a system like this that had a lot of heritage, so when the Publisher channel was doing this work, I would write back to the original Work Order object (to the destination in this case, since writing back through the shim does not quite work as you might hope) to the DirXML-Other1 attribute a value that told another driver to go set the DirXML-nwoStatus to completed. I would have preferred to fix the proper issue but complexity and time mitigated against it.

For a client using a Help Desk system that had a Work Order system internal to itself, we actually used a Work Order driver to process the Work Orders mostly in the Subscriber channel, since a JDBC driver to the Help Desk system was creating the Work Orders as synchronized objects from the Help Desk system. This in hindsight was probably the wrong way to go, since we made it a glorified loopback driver instead of a Work Order driver. We also had to process timed delayed events, but that became such a minor point in the process that we should have refactored it all out into a standalone Loopback driver.

Perhaps that is what is so confusing about the driver. You can really do with it whatever you like, and there seem to be pieces missing that are not obvious where they fit in. 

As a subtle point the driver does actually event on the Subscriber channel for DirXML-WorkOrder creates and if DirXML-nwoSendToPublisher is set to true, then the create event for the work order will cause the Publisher channel to process it even if it is not really due and create a Work To Do if appropriate, or at least try. There is also some additional functionality where you can set a DirXML-nwoRepeatInterval to have it repeat and try again and again until it succeeds in building a Work To Do. There is also a DirXML-nwoRepeatCount to keep you out of an infinite loop in this case. However, this was not working in the IDM 4.01 shipping Work Order shim, and there is a bug on it, which reports it fixed but I did not have time to test and verify that it now works, but I will assume they got it right.

Along that line it seems like it would be helpful to discuss some of the attributes schema supplies for a Work Order object. The Work Order driver will copy over the attributes on the Work Order, into the Work To Do that it spawns so you can pass more information along. Of course, the src-dn of the Work To Do will be the DN of the Work Order itself, so you can always go back and read the destination attribute (when in the Publisher channel) from the Work Order itself and add it into the Work To Do creation if you need more information.

There are several Time syntax attributes. These all need time written to them via IDM in CTIME, which is a count of seconds since 1970. The Time and Convert Time tokens will handle this conversion in a snap, in fact the first choice in the list of time formats is in fact CTIME. In eDirectory when you have an attribute in Time syntax the LDAP server will expose them in a different format, which confuses the heck out of people. Internally time is stored as a 32 bit integer which is a count of seconds and runs out around 2037 (or 2108 if used unsigned). Via LDAP it appears as 20120223112123Z which is YYYYMMDDHHmmSS then a time zone indicator, but safest to just use Z for Zulu or GMT or UTC time. (I know technically UTC is more complex than simply GMT and includes leap seconds, but for the sake of simplicity, it looks much the same).

• DirXML-DueDate
  
  
  
  • The Due Date attribute seems obvious, when does the work order come due.  Note that the name does NOT start with nwo, unlike most of the other attributes, which is nice and confusing.
  
  

• DirXML-nwoDeleteDueDate
  
  
  
  • Usually when building a WO, I append a period of time to the Due Date.  This is when a successfully processed Work Order would normally be deleted. Usually I store a GCV with the offset value and add it to the Due Date. You would do that in XPATH by $DUE-DATE 2 * 24 * 60 * 60 (2 days worth of seconds).
  
  

• DirXML-nwoCreationDate
  
  
  
  • This is not required, but is useful, especially if you fool around with the DUe Date in Policy which I have had to do.  This way you can know when it was originally created, in case say you decided to postpone it, then wanted to cancel that postponement.
  
  

The rest of the attributes are typically strings or booleans so not much special about their syntax. I will call out any interesting bits as I work through them.

• DirXML-nwoContent
  
  
  
  • Most people I have seen use this to carry a DN of an object that is being referenced.  This approach has a large hole, in that a string pointing at a DN will fail if that object is moved, renamed, or deleted when it comes time to process the Work Order.  Especially since Work Orders are meant to delay events, this is a bad choice.  I often define my own attribute of DN syntax to carry this information.  If it is gone, then do not process the WO since the target object was probably deleted.  If it was renamed or moved the DN attribute is still correct.
  
  

• DirXML-nwoStatus
  
  
  
  • The shim maintains this attribute, it starts as pending, and can have the values:
    
    
    
    • pending
    
    
  • error
  
  
• configured

When complete, it is set by the shim to configured and if anything goes wrong in creating the Work To Do (Like a Veto in the Pub channel) you get set to error by the shim. I am not sure if there are other acceptable values.

• DirXML-nwoDeleteOnError
  
  
  
  • If the DirXML-nwoStatus is error, then if this is true when the work order polls and sees such a work order it will delete it.  If not set, it will not delete it, and it is your problem to clean it up.
  
  

• DirXML-nwoProcessLog
  
  
  
  • Each step the driver takes it will try and log in this attribute.  It will be a short sentence, but a fair number of characters.  If you manage to accumulate more than 25 of these, eDirectory (25 is hard coded into eDirectory) will decide it needs an index and it will add a value index, of type System, which means you cannot ever delete it off that sever.  Even if you cleared the object I think you still cannot get rid of the index.  This is a somewhat expensive index to maintain since it is a fairly long string.
  
  

iManager will show this as the results of the Work Order.

• DirXML-nwoDependantWorkOrder
  
  
  
  • This is pretty neat, since you can make this Work Order depend on another Work Order completing before this one is considered complete.   I have never tested to see how far down you can nest this, but since this ones child will not be complete (configured) until it's child is complete I think it ought to nest properly.
  
  

• DirXML-nwoRepeatCount

• DirXML-nwoRepeatInterval
  
  
  
  • There is a bug in the shipping IDM 4.01 driver, but I think it has been fixed in a patch (WorkOrder Driver 3.5.3 Patch), that kept this from actually working (Editor's note: It was fixed in 4.01 Patch 2, which means the fix is available in 4.02). But the idea is you might want this to repeat if it fails, instead of just ending in an error.  You specify an interval in seconds and a count for the number of times it tries to prevent getting into infinite loops and never finishing.