Zarafa dagent/spooler plugin howto and API documentation

From Zarafa wiki

Jump to: navigation, search

Contents

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 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.

import MAPI
from MAPI.Util import *
from MAPI.Time import *
from MAPI.Struct import *

from plugintemplates import *


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.

Function name Description
PostConverting Hook direct after the convert from rfc822 to MAPI
PreDelivery Hook before delivery (per reciepient)
PreRuleProcess Hook in to the MAPI rules, to add, modify or remove user rules
PostDelivery Hook after delivery (per reciepient)
SendNewMailNotify 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:

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,

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.

Function name Description
PreSending 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:

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,


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:


class MyDagentPlugin(IMapiDAgentPlugin):
	prioPostConverting = 10

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

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:

Function name level Description
logFatal 1 An (unhandleable) error that results in a hook 'crash'
logError 2 A handleable error but needs attention
logWarn 3 A warning
logNotice 4 Generic information about plugin operation
logInfo 5 Detailed information about plugin operation
logDebug 6 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

The priority of the PostConverting call. Default 9999

prioPreDelivery

The priority of the PreDelivery call. Default 9999

prioPostDelivery

The priority of the PostDelivery call. Default 9999

prioPreRuleProcess

The priority of the PreRuleProcess call. Default 9999

prioSendNewMailNotify

The priority of the SendNewMailNotify call. Default 9999

Functions

Hook direct after the convert from rfc822 to MAPI

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

session

The current MAPI session

addrbook

The addressbook of the user

store

The users mailbox where the email will be deliverd

folder

The Folder where the email is created

message

The actual message which will be deliverd in the mailbox


Hook before delivery (per reciepient)

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

session

The current MAPI session

addrbook

The addressbook of the user

store

The users mailbox where the email will be deliverd

folder

The Folder where the email is created

message

The actual message which will be deliverd in the mailbox


Hook after delivery (per reciepient)

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

session

The current MAPI session

addrbook

The addressbook of the user

store

The users mailbox where the email will be deliverd

folder

The Folder where the email is created

message

The actual message which will be deliverd in the mailbox


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

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

session

The current MAPI session

addrbook

The addressbook of the user

store

The users mailbox where the email will be deliverd

folder

The Folder where the email is created

message

The actual message which will be deliverd in the mailbox


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

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

session

The current MAPI session

addrbook

The addressbook of the user

store

The users mailbox where the email will be deliverd

folder

The Folder where the email is created

message

The actual message which will be deliverd in the mailbox


Return values

The return codes for the dagent plugin.

Exit code Description
MP_CONTINUE Continue to the next hook
MP_FAILED Whole process failed
MP_STOP_SUCCESS Stop with the message processing go to the next recipient. Recpient return code OK
MP_STOP_FAILED Stop with the message processing go to the next recipient. Recpient return code failed
MP_EXIT Break all the hook calls and go futher with the mail process
MP_RETRY_LATER Stop Process and retry later


Spooler api class IMapiSpoolerPlugin

Attributes

prioPreSending

The priority of the PreSending call. Default 9999


Hook before sending a MAPI message as a rfc822 mail

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

session

The current MAPI session

addrbook

The addressbook of the user

store

The users mailbox where the email will be deliverd

folder

The Folder where the email is created

message

The actual message which will be deliverd in the mailbox
Personal tools