Event handler example: Comment on associations

This event handler adds a comment to a tracker item whenever an association is added to or deleted from this tracker item.

This example illustrates how to intercept a specific event, trigger a follow-up action by calling TeamForge web services, and add a comment based on the formatting template which is specified as part of a property file.

The code for example one can be found here.

Tip: You can treat a JAR file like a zip file: just extract it with your favorite zip program and have a look at the files that are part of it.

When you extract the JAR file you'll find a structure like this:
- com/vasoftware/sf/plugin
- This directory contains the class file of your event handler. There may be additional directories containing Java class files. If you like to include Java libraries, you have to unpack their JAR files and add their class files (including directory structure) in the event handler JAR.
- META-INF/event.xml
- This file contains the events and operations your handler class will intercept. It is also common to have additional files in the META-INF directory, such as property files to control the behavior of the event handler.
This example event handler is provided as-is (i.e. not supported as part of any TeamForge release). As with all event handlers, use it at your own risk. CollabNet cannot guarantee any SLAs on third-party code.

Tip: If you want to change the behavior of custom event handlers at runtime (without redeploying the JAR file), you may want to look at the TeamForge integration data API. For the purpose of this example, we will stick with property files.
In the event.xml file, you will find some lines like this:
```
<event api="6.1" mode="asynchronous">
    <type>relationship</type>
    <operation>*</operation>
    <handler>com.vasoftware.sf.plugin.AsynchronousRelationshipEventListener</handler>
</event>
```
This tells the event handling framework that the class AsynchronousRelationshipEventListener is responsible for intercepting events of type “relationship” (aka associations) for every possible operation. The handler will be called after the event has happened (asynchronous mode) and the passed data structures will be compatible with the events format defined in TeamForge 6.0 (in other words, the event handler extends the EventHandler60 class). If you only want to intercept certain operations, you can specify those instead of the wildcard character (*). Supported operations are usually create, update, move and delete, but every event can define its own operations.
The config.properties file is used to control the formatting of the comment that gets added when an association has been modified. The initialize-method of the handler class (AsynchronousRelationshipEventListener) shows how property files can be parsed within a custom event handler.
By default, the user triggering the event is also the user executing the event handler. If you want to run your event handler with a different user account, specify it in the user element, like this:
```
  
<event api="6.1" mode="synchronous">
    <type>*</type>
    <operation>*</operation>
    <handler>com.vasoftware.sf.plugin.AsynchronousRelationshipEventListener</handler>
    <user>foo</user>
</event>
```
Note: Be careful with this option, because running code on behalf of a different user opens the door for all kind of exploits if you do not check the user’s input properly. Also, this option will not allow you to access the original user’s session id any more, but you can always create a new session with a super user account (credentials saved in a property file) if you have to.