Event handler example: Execute a hook script

When a TeamForge event arrives, this event handler looks to see whether there is a script in the TeamForge file system with the name/operation of the event, and then calls that script with all information from the event contained within environment variables.

This example illustrates how to intercept arbitrary TeamForge events, examine the event’s properties, map them to system environment variables and call a script in the file system with a name corresponding to the intercepted event.

You can use this event handler to customize your TeamForge site’s behavior without any knowledge of the Java programming language as long as you can write scripts in a language that can deal with environment variables, write to standard out/error (to influence what will be displayed in TeamForge’s UI as result of the handler’s execution) and influence the return code (to decide whether to block the event or not).

The code for this example 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/collabnet/ctf/events
- 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>*</type>
	<operation>*</operation>
	<handler>com.collabnet.ctf.events.AsynchronousHookScriptEventListener</handler>
</event>

<event api="6.1" mode="synchronous">
	<type>*</type>
	<operation>*</operation>
	<handler>com.collabnet.ctf.events.SynchronousHookScriptEventListener</handler>
</event>
```
These lines tell TeamForge to register two event handlers, one asynchronous (AsynchronousHookScriptEventListener) and one synchronous (SynchronousHookScriptEventListener) for arbitrary events (wildcard *). It also tells TeamForge that the handler classes will extend the EventHandler60 interface.
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.collabnet.ctf.events.SynchronousHookScriptEventListener</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.

It is possible to register multiple handlers for different events, but you can also use one handler to intercept both synchronous and asynchronous events.