Source code for this example is in Custom event handler example zip file.
Clients can login to see a video example of using custom event handlers from the May 2011 developer webinar.
One example of using the custom event handler would be a plugin that responds to activity going on with GOSS iCM, such as a contributor editing an article. These interactions can then feed through to your own applications, perhaps updating another database with content from GOSS iCM. Doing this is remarkably easy.
Example of forwarding an event to another application
In this example I'll show you how you can forward the event from GOSS iCM to another application.
The code for plugins in GOSS iCM always goes into the /icm/custom folder. In this case we're interested in the /icm/custom/customeventhandler.cfm file. By editing this file we can write custom code to respond to GOSS iCM events. In particular we are passed the following information:
| Type | Detail |
| Action | The operation performed on the content item (Insert, Update, Delete, etc) |
| ItemType | The type of content item (Article, Media, etc) |
| ItemID | The ID of the content item being acted upon |
| User | The ID of the iCM user who performed the action |
| IP | The IP address from where the user performed the action |
| TimeStamp | When the action occurred |
| Local | Whether the action occurred on this server (as opposed to elsewhere in the cluster) |
| Notes | Additional content-specific explanatory information about the event |
I'll now show you how to forward that information on to your own ASP.NET or Java web application to you to extend the use of the data, perhaps using the GOSS iCM API to get more information about a pdf item that has been inserted in to the media library and email it to a specific distribution list. The example shows how GOSS iCM can call another URL (another web application) from its event handler.
Using your development copy of GOSS iCM, you'll want to open up the /icm/custom/customeventhandler.cfm file and copy/paste the following code into it. Be careful not to delete any existing code already in there:
<!--- The following will trigger this event handler to forward any
event information to an external application --->
<cftry>
<cfhttp url="http://<your-server>/eventhandler" method="get">
<cfhttpparam name="action" value="#attributes.action#" type="url">
<cfhttpparam name="itemType" value="#attributes.itemType#" type="url">
<cfhttpparam name="itemId" value="#attributes.itemId#" type="url">
<cfhttpparam name="user" value="#attributes.user#" type="url">
<cfhttpparam name="ip" value="#attributes.ip#" type="url">
<cfhttpparam name="timeStamp" value="#attributes.timeStamp#" type="url">
<cfhttpparam name="local" value="#attributes.local#" type="url">
<cfhttpparam name="notes" value="#attributes.notes#" type="url">
</cfhttp>
<cfcatch>
<cfmail to="#application.notifyError#" from="#application.notifyFrom#" subject="Custom Event Handler Forwarding Error" server="#application.mailServer#" type="text/html">
<h1>An error occurred forwarding the following event information:</h1>
<cfdump var="#attributes#">
<h2>The error is as follows:</h2>
<cfdump var="#cfcatch#">
</cfmail>
<cfrethrow>
</cfcatch>
</cftry>
You can see this in place in the supplied eventhandler.zip file in /icm/icm/custom/customeventhandler.cfm.
You'll want to change the URL specified on the 4th line (in the code snippet above this is http://<your-server>/eventhandler) to your own application. This will make GOSS iCM call your application's web page, passing it URL parameters of 'action', 'itemType', 'itemId', 'user', 'ip', 'timestamp', 'local' and 'notes'. Should it fail then an email will be sent to the error email address you've configured in the autoconfig section of GOSS iCM. This is pretty handy for diagnosing things if it doesn't work first time.
In the supplied eventhandler.zip there are example ASP.NET and Java web application that then handle this request. In both instances there's a single method that you can implement to handle the event. This can be found in /dotnet/src/main/webapp/eventhandler.aspx.cs or /java/src/main/java/com/gossinteractive/eventhandler/EventHandlerServlet.java and has the method signature:
private void icmCustomEventHandler(String action, String itemType,
int itemId, int user, String ip, Date timeStamp, boolean local,
String notes) {// Do something!
}
When I was testing this out I was developing the .NET and Java web applications on my local workstation. To check that my web applications were working I accessed them directly, passing the expected parameters manually on the URLs:
.NET: http://localhost/eventhandler/eventhandler.aspx?action=Insert&itemType=Article&itemId=123&user=456&ip=127.0.0.1&timeStamp=2010-01-01T10:30:00&local=no¬es=notes
Java: http://localhost:8080/eventhandler/eventhandler?action=Insert&itemType=Article&itemId=123&user=456&ip=127.0.0.1&timeStamp=2010-01-01T10:30:00&local=no¬es=notes
This made debugging my ASP.NET and Java code a lot easier - I didn't have to keep editing content in GOSS iCM to trigger the event handler.
Then to link the development GOSS iCM to my development workstation I replaced the url in customeventhandler.cfm with that of my workstation: http://myworkstation/eventhandler/eventhandler.aspx. This then means I can edit an article in my development GOSS iCM and the event is fed through to my custom ASP.NET web application.
You might like to share your own custom event handlers with the GOSS community on GForge.
Conclusion
This is just one, simple example. There are numerous other examples of how the powerful features of custom event handling can improve the online efficiency of your organisations. Creating online efficiencies is an important way of delivering more effective services to customers whilst ensuring service delivery is as cost efficient as possible.
Posted by Ralph Jones, 18th May 2011
