Starting with release 1.3, users can define a new type of action in which custom, dynamic code will execute as a result of an Event. This code must be written in the Groovy (http://groovy.codehaus.org/) programming language. We'll refer to events handled in this way as Groovy Events.
Like the standard actions, Groovy Events are configured in the Notices UI. The user creates a Notice entry by first specifying the Event Type to be monitored and the Filter, if any. He then selects "execute code" from the Actions LOV (instead of "send email" or "print"). A text entry area then appears, into which the Groovy code is entered.
Let's jump to a simple example.
Assume we want to write a message to the system log whenever a container is discharged from a vessel. The message should have the container id and its equipment type.
To configure this, we would create a Notice Request for the Discharge Container Event Type:
In closer detail, this is the Groovy code in the Notice Request:
def ctrId = event.getProperty("EquipmentIdFull")
def eqType = event.getProperty("EquipmentType")
println("Container " + ctrId + " of type " + eqType + " was discharged")
Note the reference to "event" in the code above. This is an instance of class GroovyEvent that is passed to your code. This class, defined within N4, provides API's that allow your Groovy code to access the Event. In our example, we use "getProperty()" which is an API that returns properties of the domain entity to which the Event applied. You pass this method the standard N4 Reporting Tag describing the property you want, and it returns the value of that property.
As stated above, your code is passed a GroovyEvent in a variable named "event". GroovyEvent wraps two N4 entities: 1) the "Event", which hold the details of the service event itself, 2) the "Business Object", which is the entity to which the event pertains (the Unit, VesselVisit, Booking, etc.). Your code is also passed an instance of another N4 class called "GroovyApi" This instance is passed in a variable named "api", and provides general API's into N4. Together, "event" and "api" provide access to all N4 functionality that your Groovy code should need, allowing you to:
Obtain properties of the Event
Obtain properties of the Business Object
Update properties of the Business Object
Query for other Events previously applied to the Business Object
Post new Events on the Business Object
Perform (limited) queries on the N4 database
Send messages to outside systems
Errors thrown during groovy code execution can be seen in the Integration Errors screen (../../../../../../../display/sn4o/integration+monitoring).