Here are some important things you need to know about the new Vault 2011 feature that allows you to queue up a job on a lifecycle state change.
Configuring the system
Obviously you need to have the Job Server enabled. So that's the first step. You can enable this feature in the Global admin settings.
The next thing you need to know is that each life cycle transition has 0 to N custom jobs associated with it. When a file moves through a transition, a job will be added to the queue for each association.
To set up which jobs fire for which transitions, I suggest using the Lifecycle Event Editor, which is included in the util directory of the SDK. You can also use the Web Service API function UpdateLifeCycleStateTransitionJobTypes in Document Service Extensions.
My Vault 2011 SDK video tour has a demo of the Lifecycle Event Editor.
Keep in mind that this mechanism only applies to custom job types. The built-in job types, property sync and DWF generate, are configured through different mechanisms.
- Events are not handled in real time. The job will instantly go on the queue after the file moves through the transition. However, you don't know when the job will get processed. If there is a large backlog, it might be hours before your handler runs.
- Jobs are fired on a per-file basis. For example, let's say you want to send out an email when a file gets released. If someone Releases a 1000 part assembly, it will result in 1000 jobs on the queue. You need to make sure that your handler doesn't send out 1000 emails. Much better is to send out 1 email listing the 1000 files.
- Transitions are specific to a lifecycle definition. For example, if you set the jobs for WIP->Released in the Flexible Release Process, it will have no impact on files using the Basic Release Process.
Writing the job handler
Any job put on the queue this way will have two parameters. It will have the "FileId" value and the "LifeCyleTransitionId" value. These two pieces of information should allow your code to find out anything else it needs to.
Again, your handler might be running hours after the file was transitioned, so you should handle cases like the file being deleted, or the File ID not pointing to the latest version.
Other than that, things should be the same as any other job handler. See the SDK documentation for more information of the Job Processor API.