Michel: Created page with "== Introduction == ZCP 7.1 offers a new python plugin framework for the Zarafa Spooler and Dagent. This framework makes it easier for advanced system administrators and develope..."

2012-06-04T14:02:23Z

Created page with "== Introduction == ZCP 7.1 offers a new python plugin framework for the Zarafa Spooler and Dagent. This framework makes it easier for advanced system administrators and develope..."

New page

== Introduction ==

ZCP 7.1 offers a new python plugin framework for the Zarafa Spooler and Dagent. This framework makes it easier for advanced system administrators and developers to integrate systems with the spooler and dagent. The advanced system administrator and developer can easily add new functionality or change some behaviours of the existing system. The plugin framework is based on the programming language Python which means that you need to create your own hook in python.

This wiki article contains a howto and API documentation.

== How it works ==

If the plugin framework in the spooler or dagent is enabled it will search for python files in the directory ''plugin_path'' and look for a specific type of plugin. If the plugins are found it will be verified and loaded. Everytime the spooler or dagent is called it will execute the hooks based on priority. Plugins can validate and change a message on different stages of the spooler and dagent process.

== Design a new Hook ==

What do you need to know before starting develop python plugins for zarafa dagent and spooler.

* The basics of python
* Read the zarafa [http://doc.zarafa.com/trunk/Python_Language_Binding/en-US/html-single/ python-mapi] documentation

If you want to do more advanced development with MAPI its recommend to read the Microsofts MAPI documentation on the internet. This described the different properties, interfaces and some examples in C++. It's relative easy to convert the C++ to the python model because python-mapi implements MAPI as it is described by Microsoft but with the Python design rules.

If you start a new plugin you need atleast the following headers in the new plugin.

Plugin default imports.

<pre>
import MAPI
from MAPI.Util import *
from MAPI.Time import *
from MAPI.Struct import *

from plugintemplates import *
</pre>

=== Creating a Plugin for the Dagent ===

To create a new plugin in the dagent the plugin must inherent from the class IMapiDAgentPlugin. This class has the following functions which can be override.
{| style="border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"
|-
! style="border-style: solid; border-width: 1px "| Function name
! style="border-style: solid; border-width: 1px" align="left" | Description
|-
| style="border-style: solid; border-width: 1px" | PostConverting
| style="border-style: solid; border-width: 1px" | Hook direct after the convert from rfc822 to MAPI
|-
| style="border-style: solid; border-width: 1px" | PreDelivery
| style="border-style: solid; border-width: 1px" | Hook before delivery (per reciepient)
|-
| style="border-style: solid; border-width: 1px" | PreRuleProcess
| style="border-style: solid; border-width: 1px" | Hook in to the MAPI rules, to add, modify or remove user rules
|-
| style="border-style: solid; border-width: 1px" | PostDelivery
| style="border-style: solid; border-width: 1px" | Hook after delivery (per reciepient)
|-
| style="border-style: solid; border-width: 1px" | SendNewMailNotify
| style="border-style: solid; border-width: 1px" | Hook to report the end-user if there is a new mail or not
|}

The zarafa dagent need to extend from the plugin class 'IMapiDAgentPlugin' and override one or more functions of the class.

Example which log the subject of a email:

<pre>class MyDagentPlugin(IMapiDAgentPlugin):

def PostConverting(self, session, addrbook, store, folder, message):
props = message.GetProps([PR_SUBJECT], 0)
self.logger.logInfo("My dagent test, the subject is '%s'" % props[0].Value)

return MP_CONTINUE,
</pre>

=== Creating a Plugin for the Spooler ===

To create a new plugin in the spooler the plugin must inherent from the class IMapiSpoolerPlugin. This class has the following functions which can be override.

{| style="border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"
|-
! style="border-style: solid; border-width: 1px "| Function name
! style="border-style: solid; border-width: 1px" align="left" | Description
|-
| style="border-style: solid; border-width: 1px"| PreSending
| style="border-style: solid; border-width: 1px"| Hook before sending a MAPI message as a rfc822 mail
|}

The Zarafa spooler must be extend from the plugin class 'IMapiSpoolerPlugin' and override one or more functions of the class.

Example which log the subject of a email:
<pre>class MySpoolerPlugin(IMapiSpoolerPlugin):

def PreSending(self, session, addrbook, store, folder, message):
props = message.GetProps([PR_SUBJECT], 0)
self.logger.logInfo("My spooler test, the subject is: '%s'" % props[0].Value)

return MP_CONTINUE,
</pre>

=== Priority of a plugin ===

Every plugin hook can have a priority which have by default the priority 9999. To change the priority of a hook you need to add an attribute prio<hookname> with the value as priority, for example:

<pre>
class MyDagentPlugin(IMapiDAgentPlugin):
prioPostConverting = 10

def PostConverting(self, session, addrbook, store, folder, message):
DoSomeThing()
</pre>

=== Log system ===

The python plugin framework has an internal log system which forward the log information to the Zarafa spooler and Zarafa dagent log. The logger has the following log functions:

{| style="border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"
|-
! style="border-style: solid; border-width: 1px "| Function name
! style="border-style: solid; border-width: 1px "| level
! style="border-style: solid; border-width: 1px" align="left" | Description
|-
| style="border-style: solid; border-width: 1px" | logFatal
| style="border-style: solid; border-width: 1px" | 1
| style="border-style: solid; border-width: 1px" | An (unhandleable) error that results in a hook 'crash'
|-
| style="border-style: solid; border-width: 1px" | logError
| style="border-style: solid; border-width: 1px" | 2
| style="border-style: solid; border-width: 1px" | A handleable error but needs attention
|-
| style="border-style: solid; border-width: 1px" | logWarn
| style="border-style: solid; border-width: 1px" | 3
| style="border-style: solid; border-width: 1px" | A warning
|-
| style="border-style: solid; border-width: 1px" | logNotice
| style="border-style: solid; border-width: 1px" | 4
| style="border-style: solid; border-width: 1px" | Generic information about plugin operation
|-
| style="border-style: solid; border-width: 1px" | logInfo
| style="border-style: solid; border-width: 1px" | 5
| style="border-style: solid; border-width: 1px" | Detailed information about plugin operation
|-
| style="border-style: solid; border-width: 1px" | logDebug
| style="border-style: solid; border-width: 1px" | 6
| style="border-style: solid; border-width: 1px" | Low-level information for developers
|}

Example log:

self.logger.logFatal("Unable to find file '%s'" % (filename) )
self.logger.logInfo("Message includes %d attachment(s)" % (cntattach) )

= API documentation =

== Dagent api class IMapiDAgentPlugin ==

'''Attributes'''

'''prioPostConverting'''
<blockquote>The priority of the PostConverting call. Default 9999</blockquote>
'''prioPreDelivery'''
<blockquote>The priority of the PreDelivery call. Default 9999</blockquote>
'''prioPostDelivery'''
<blockquote>The priority of the PostDelivery call. Default 9999</blockquote>
'''prioPreRuleProcess'''
<blockquote>The priority of the PreRuleProcess call. Default 9999</blockquote>
'''prioSendNewMailNotify'''
<blockquote>The priority of the SendNewMailNotify call. Default 9999</blockquote>

'''Functions'''

Hook direct after the convert from rfc822 to MAPI

def PostConverting(self, session, addrbook, store, folder, message)

'''session'''
<blockquote>The current MAPI session</blockquote>

'''addrbook'''
<blockquote>The addressbook of the user</blockquote>

'''store'''
<blockquote>The users mailbox where the email will be deliverd</blockquote>

'''folder'''
<blockquote>The Folder where the email is created</blockquote>

'''message'''
<blockquote>The actual message which will be deliverd in the mailbox</blockquote>

Hook before delivery (per reciepient)

def PreDelivery(self, session, addrbook, store, folder, message)

'''session'''
<blockquote>The current MAPI session</blockquote>

'''addrbook'''
<blockquote>The addressbook of the user</blockquote>

'''store'''
<blockquote>The users mailbox where the email will be deliverd</blockquote>

'''folder'''
<blockquote>The Folder where the email is created</blockquote>

'''message'''
<blockquote>The actual message which will be deliverd in the mailbox</blockquote>

Hook after delivery (per reciepient)

def PostDelivery(self, session, addrbook, store, folder, message)

'''session'''
<blockquote>The current MAPI session</blockquote>

'''addrbook'''
<blockquote>The addressbook of the user</blockquote>

'''store'''
<blockquote>The users mailbox where the email will be deliverd</blockquote>

'''folder'''
<blockquote>The Folder where the email is created</blockquote>

'''message'''
<blockquote>The actual message which will be deliverd in the mailbox</blockquote>

Hook in to the MAPI rules, to add, modify or remove user rules

def PreRuleProcess(self, session, addrbook, store, rulestable)

'''session'''
<blockquote>The current MAPI session</blockquote>

'''addrbook'''
<blockquote>The addressbook of the user</blockquote>

'''store'''
<blockquote>The users mailbox where the email will be deliverd</blockquote>

'''folder'''
<blockquote>The Folder where the email is created</blockquote>

'''message'''
<blockquote>The actual message which will be deliverd in the mailbox</blockquote>

Hook to report the end-user if there is a new mail or not.

def SendNewMailNotify(self, session, addrbook, store, folder, message)

'''session'''
<blockquote>The current MAPI session</blockquote>

'''addrbook'''
<blockquote>The addressbook of the user</blockquote>

'''store'''
<blockquote>The users mailbox where the email will be deliverd</blockquote>

'''folder'''
<blockquote>The Folder where the email is created</blockquote>

'''message'''
<blockquote>The actual message which will be deliverd in the mailbox</blockquote>

=== Return values ===

The return codes for the dagent plugin.

{| style="border-collapse: collapse; border-width: 1px; border-style: solid; border-color: #000"
|-
! style="border-style: solid; border-width: 1px "| Exit code
! style="border-style: solid; border-width: 1px" align="left" | Description
|-
| style="border-style: solid; border-width: 1px" | MP_CONTINUE
| style="border-style: solid; border-width: 1px" | Continue to the next hook
|-
| style="border-style: solid; border-width: 1px" | MP_FAILED
| style="border-style: solid; border-width: 1px" | Whole process failed
|-
| style="border-style: solid; border-width: 1px" | MP_STOP_SUCCESS
| style="border-style: solid; border-width: 1px" | Stop with the message processing go to the next recipient. Recpient return code OK
|-
| style="border-style: solid; border-width: 1px" | MP_STOP_FAILED
| style="border-style: solid; border-width: 1px" | Stop with the message processing go to the next recipient. Recpient return code failed
|-
| style="border-style: solid; border-width: 1px" | MP_EXIT
| style="border-style: solid; border-width: 1px" | Break all the hook calls and go futher with the mail process
|-
| style="border-style: solid; border-width: 1px" | MP_RETRY_LATER
| style="border-style: solid; border-width: 1px" | Stop Process and retry later
|}

== Spooler api class IMapiSpoolerPlugin ==

'''Attributes'''

'''prioPreSending'''
<blockquote>The priority of the PreSending call. Default 9999</blockquote>

Hook before sending a MAPI message as a rfc822 mail

def PreSending(self, session, addrbook, store, folder, message):

'''session'''
<blockquote>The current MAPI session</blockquote>

'''addrbook'''
<blockquote>The addressbook of the user</blockquote>

'''store'''
<blockquote>The users mailbox where the email will be deliverd</blockquote>

'''folder'''
<blockquote>The Folder where the email is created</blockquote>

'''message'''
<blockquote>The actual message which will be deliverd in the mailbox</blockquote>

Zarafa dagent/spooler plugin howto and API documentation - Revision history

Michel: Created page with "== Introduction == ZCP 7.1 offers a new python plugin framework for the Zarafa Spooler and Dagent. This framework makes it easier for advanced system administrators and develope..."