Event Scripting

The event scripting service adds language support to MultiNet

Scripts are developed in Terrapin Script, a language based on Javascript. Scripts can be attached to System Events or mailboxes. Scripts can modify the behaviour of MultiNet and add functionality.

Examples of real-world scripting solutions include:

• Integrating Terrapin MultiNet with other business systems. As an example email support is added for report distribution
• Automatic processing of emails. For example Form results from a website are automatically decoded on receipt and applied to a database.
• Customisation of core processing For example email routing logic is amended to determine the recipient of an email from its subject line

An online script library (which can be accessed within the administration client) provides solutions for many common scripting requirements. All scripts can be downloaded and installed without charge.

The service includes an embedded debugging environment which enables scripts to be interrogated as they execute. All standard debugging facilities are supported including step into, step over, breakpoints and object drill down.

Terrapin Script

Terrapin Script is an implementation of the popular Javascript language used by many Internet applications. Terrapin Script extends Javascript so that it better describes the type of objects encountered in a MultiNet system, however, fundamentally, the languages are the same. Anyone familiar with Javascript will be comfortable working with Terrapin Script.

Like Javascript, Terrapin Script is an object orientated language. Objects are defined which allow scripts to manipulate MultiNet users, email, files, system settings as well as the traditional objects offered by Javascript.

Object	Description
Array	A collection of objects structured so that each object has a specific position within the collection and can be identified by a 0 based index.
Boolean	true or false
Buffer	A block of memory or a sequence of bytes. Used to represent any non-textual data. Operates similarly to a string, however, it does not depend on the interpretation that a byte may be presented as a character.

Object	Description
ContentDisposition	A mime content property This property describes how a mime part of a multipart entity should be interpreted by the mail reader. Equivalent to the Content-Disposition mime header in an email part
ContentId	A mime content property which provides a mechanism for the mime part to be referenced by other parts in the same message. Equivalent to the Content-Id mime header
Date	A Date
EmailAddress	An email address.
EmailMessage	An email message. Because this object inherits from MimeEntity, an EmailMessage IS a MimeEntity and so all the properties and method of a MimeEntity are available to the EmailMessage object. An EmailMessage object may or may not be attached to 'real' email. An EmailAddress object which is attached draws its properties from the real email as known to the MultiNet server.
EncodingType	A mime content property which identifies how the mime part has been encoded. Equivalent to the Content-Transfer-Encoding mime header.

Object	Description
File	A file. File objects can be opened, written to, read from and closed. By default files are opened for exclusive write access (other processes can read the file but not write to it while it is open in the script).
Function	A group of statements which may be called from within the body of a script. A function can optionally take one or more arguments and can also optionally return a value
Math	A placeholder for math functions. Instances of this object are never created. All methods and properties are static
MimeEntity	Part of a Mime encoded email. A Mime encoded email comprises one or more Mime Entities or Parts. A simple, plain text email with no attachments is a single Mime Entity (the email itself). As attachments or added to the email, or more complex message formats are used, then the number of Mime Entities in an email increases. Every Mime Entity has a Mime Type property. The Mime Type describes how a Part should be treated by an email client. Certain Mime Types indicate that the part should be viewable as part of the message itself. Other types indicate that the part is an attachment, while another type (multipart) indicates that the part is an envelope for one or more other parts.

Object	Description
MimeProperty	Represents a standard email or mime entity header
MimeType	A mime content property which describes the data in a mime part so that a receiving email client can determine how it should render the data to the user. Equivalent to the Content-Type mime header.
Number	A numeric value
Object	Base class for all other objects
RegExp	A regular expression
String	A series of alphanumeric characters.
System	The MultiNet system, providing access to users, system properties and functions
SystemPropertySet	A group of related system properties. A SystemPropertySet object is obtained using the System.getPropertySet method. The properties of the SystemPropertySet object depend on the property set which was requested, each one corresponding to a MultiNet system property

Object	Description
User	A MultiNet user. User objects can be obtained from the System.users array.

System Events

Scripts can either be attached to a System Event or one or mailboxes. Scripts which are attached to mailboxes are executed whenever email is posted to one of the associated mailboxes.

Scripts which are attached to system events are executed whenever the event occurs. Scripts can change the default processing which occurs at the associated event depending on the script's return value. The following events are defined:

Event	Description
Connection Scheduler	Called approximately every 10 seconds. The script can offer a time for the next internet connection or can request a connection immediately.
Daily Processing	Called every day at approximately midnight (or when the MultiNet server is first run after that time). Scripts placed at this event handler typically undertake periodic housekeeping tasks such as executing batch interfaces with other systems.
MailPreprocessor	All non-system email passes through the email preprocessor. The email processor can examine the email, modify it, or delete it, before it is released to a user or the outgoing mail queue. 5 stages are defined in the preprocessor which allow scripts to run at various stages of the core email processing

Event	Description
On Connect	Called whenever a connection is made to the Internet.
Outgoing Mail Preprocessor	Called whenever email is posted the Outgoing mail queue. The script has access to the original email, and details of the sender and recipient.
POP3 Pickup Mail Router	Called when an email has been received from a POP3 source and MultiNet is attempting to derive routing information from the email headers. If a script at this event can override default routing rules by offering one or more email addresses as a return value
Unrouted Mail Handler	Called whenever email is to be distributed internally but an internal recipient cannot be identified. Normally the email will be posted to the default mailbox. A script attached to this handler is given the opportunity to suggest an alternative address.

Index of Technical Papers