Home

AGNITAS EMM/OpenEMM Extension Development Guide Table of

1. gt dyn name tbl dyn name id target id ID of target group for content block 0 2 no target group gt dyn target tbl target id company id 1 dyn content Content block text dyn order Position of content block within texte module important for order of processing 1 first 2 2 second etc O 2013 AGNITAS AG 42 55 EMM OpenEMM Extension Development Guide 12 20 dyn name tbl Table description 1 0 10 20140709 Contains text module names Content for text modules is saved in table dyn content tbl Column name Description dyn name id mailing id mailing tbl mailing id company id dyn name deleted 12 21 dyn target tbl Table description ID of text module auto generated ID of mailing the text module belongs to gt 1 Name of text module used for parameter name of tag agnDYN Flag for deleted text module 1 deleted Contains code of target groups Column name Description target id ID of target group auto generated company id target shortname target description target sql result set target representation with target group deleted creation date change date 12 22 export predef tbl Table description 1 Name of target group Description of target group SQL code used for the WHERE part of the SQL query to retrieve serialized instance of Java class TargetRepresentationlmpl definition Flag for deleted target group 1 deleted Creation date of this record
2. Table description Contains gender specific salutation textes for title types Column name Description gender title_id title 12 46 title tbl Table description ID of genderlD 0 male 1 female 2 unknown ID of title gt title tbl title id text for salutation Contains title types for tag agnTITLE salutations Column name Description title id ID of title salutation auto generated company id 1 description Description of salutation 12 47 userform tbl Table description Contains userforms Column name Description form id company id formname used in description startaction id endaction id success template error error template returned error code success url success use url success default 0 error url O 2013 AGNITAS AG ID of user form auto generated 1 Name of form should contain no special characters since it will be URLs Description of form ID of action gt rdir_action_tbl action_id executed at start of form processing ID of action gt rdir_action_tbl action_id executed at end of form processing if start action did not return error code Code that is displayed in case of success start action returned no code content is evaluated by Velocity before sent to browser Code that is processed in case of error start action content is evaluated by Velocity before sent to browser URL that is called in case of success if succ
3. id ID of content module category id ID of category gt cm category tbl id company id 1 shortname Name of content module description Description of content module content Structure of content module 13 3 cm content tbl Table description Contains content of CMS placeholders in content modules Column name Description id ID of content element content module id ID of content module gt cm content module tbl id tag name Name of CMS placeholder tag content Content for CMS placeholder tag tag type Type of CMS placeholder tag OZTEXT 1 LABEL 2 IMAGE 3 LINK 13 4 cm_location_tbl Table description Contains positions of content modules within CM templates and target group assignments O 2013 AGNITAS AG 53 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Column name Description id ID of location entry mailing_id ID of mailing gt mailing_tbl mailing_id cm_template_id ID of CM template gt cm_template_tbl id content_module_id ID of content module gt cm content module tbl id target_group_id ID of target group expression gt dyn_target_tbl target_id dyn_name Name of agnDYN tag dyn_order Position of agnDYN tag within CM template 1 first 2 second etc 13 5 cm_mailing_bind_tbl Table description Contains assignments of content modules to mailings Column name Description id ID of assignment content_module_id ID of content module gt cm content module tbl id
4. 1 read only 2 hidden mode edit Edit permission 0 read c write 1 read only 2 hidden O 2013 AGNITAS AG 41 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 12 16 datasource description tbl Table description Contains source ID of recipient profiles When importing a file a new datasource id is generated and entered in table customer 1 tbl for each new recipient Column name Description datasource id ID of datasource sourcegroup id ID of the sourcegroup 2 not used company id 1 description Description of datasource file name creation date Creation date of this record change date Date of last change for this record 12 17 date tbl Table description Formats accepted and used by the tag agnDATE Column name Description type ID used for parameter type of tag agnDATE format Format of Date as accepted by Java class java text SimpleDateFormat like MM dd yyyy 12 18 doc mapping tbl Table description Maps pagekeys of JSPs to certain files in the online user manual for context sensitive online help Column name Description filename Name of target file in directory of online user manual pagekey Name of key used in JSP to reference a certain help topic 12 19 dyn content tbl Table description Contains content blocks for text modules Column name Description dyn content id ID of content block auto generated dyn name id ID of text module the content block belongs to
5. mailing_id ID of mailing gt mailing_tbl mailing_id 13 6 cm media file tbl Table description Contains media files for CM templates content modules and preview images thumbnails Column name Description id ID of media entry cm template id IF of CM template gt cm template tbl id content module id ID of content module gt cm content module tbl id cmtid ID of CM type gt cm type tbl id company id 1 media name Name of media file content Content of media file media type Type of media file O file from dir template media in template ZIP file 2 preview image mime type MIME type of media file image gif image jpeg image png etc 13 7 cm template mailing bind tbl Table description Contains assignments of CM templates to mailings Column name Description id ID of assignment cm template id ID of CM template gt cm template tbl id mailing id ID of mailing gt mailing tbl mailing id 13 8 cm template tbl Table description O 2013 AGNITAS AG 54 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Contains CM templates for CMS Column name Description id ID of CM template company_id 1 shortname Name of CM template description Description of CM template content Content of CM template 13 9 cm_text_version_tbl Table description Contains default text versions for CM based mailings Column name Description id admin_id text 13 10 cm type t
6. 11 Todo List for Next Versions of Extension Architecture provide a template with documentation for a dummy extension introduce and explain handling of extension versions manifest files support version handling but right now versions of extensions are not used by demo extensions include more GUI extension points so that existing JSPs can be enhanced individually with extension output we need your input here where you need additional GUI extension points If you have further questions regarding the extension architecture of EMM OpenEMM or if you have suggestions how to improve this documentation please feel free to contact its author at maschoff openemm org 2013 AGNITAS AG 36 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 12 Appendix A Database Schema of OpenEMM This appendix contains a description of the database tables of OpenEMM 2013 openemm To retrieve the datatypes of the columns of certain tables simply execute gt mysql u root p mysql gt use openemm mysql gt desc name and replace name with the name of the table you are interested in OpenEMM works with company_id 1 only while EMM supports other values for company_id as well in order to offer its users multi tenancy capabilities 12 1 admin_group_permission_tbl Table description Contains individual permissions for admin groups The groups are defined in the admin_group tbl Column name Description admin_group
7. 2 System Extension core navigation 14 4 Extension Points in Detalil ooooconocconocnnnnconnncanoncnnncrnnnrnnnnncrrnnnnnnoranannnnnrrnnnnanananas 16 41 GUI EXtension POINTS rise rires pet ren cerca E ER RM Reges 16 4 2 Navigation Extension Points sise 17 4 3 Feature Extension Point eene enne nene rhe nn rne nn hee nns teen nnne 18 5 Demo EXtensSiONS occconccconnconanconnncnnnnrnnnornnnrnnnnrnnnnrnnncrnnnrnnnnrnnnnrnnnnnrrrnnnnnnnrranananos 20 5 1 Extension hello World cerent een e eae a re eder Fresh a Ei oa 20 5 2 Extension AMINO iri rey de p P ded date cag x rd ede hls lo vette d tre dt 20 5 3 Extension blacklist_wildcard_search Hem 21 5 3 1 Program Flow of Extension ss 22 5 4 Extension mailing statistics export ss 22 5 5 Using the EMM OpenEMM API hene nnne rhe rni hen rn n nnne nnn 23 6 Extending the EMM OpenEMM Database eseseeeeseen nennen nana ann nnn 25 0 1 Tabl e NIME Sirenia nAn e nA aa araea a de Peed Mute s BEA aa 25 6 2 SQL Statement Validation sise 25 7 Working with PermissSiONS ooconccconocconncnnnnconnnrnnnnrnancrnnncnnnnrnnanrnnnnrananannrrnnanannnenss 27 8 Creating extensions for BIRT based statistics EMM only ssssnsssunnnnnnnnnnnnnnnnnn 28 8 1 BIRT Extension Points and Permission Token enna 28 8 2 BIRT Extension ZIP Flint dre tram dd OR RR done 28 8 3 BIRT Configuration nine A id
8. 24 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 6 Extending the EMM OpenEMM Database Some extensions will require the enhancement of the database schema of EMM OpenEMM see appendix A and B for details or need to insert new data If this is the case please make sure that new tables use the extension ID as prefix in their name like dummy contact tb and that new columns in existing tables are identified by this extension prefix as well to avoid overlap of schema enhancements by two different extensions The extension manager of EMM OpenEMM s able to apply extension specific changes to the underlying database automatically To do this you have to provide up to four files containing SQL statements to be processed in directory db of the extension ZIP file install mysql sql SQL statements to be executed if extension is installed and EMM OpenEMM runs on MySQL install oracle sql SQL statements to be executed if extension is installed and EMM OpenEMM runs on Oracle remove mys1l sql SQL statements to be executed if extension is removed and EMM OpenEMM runs on MySQL remove oracle sql SQL statements to be executed if extension is removed and EMM OpenEMM runs on Oracle The extension manager checks which database is used parses and validates the content of the corresponding SQL file and executes the individual SQL statements 6 1 Table Names Because EMM opposed to OpenEMM is a multi tenancy applicati
9. REN Re EEA EE AET Ena beda 54 EA A A tol aerias de die e E FRE Rep re hr Er e RE NON UR n MAX ERR ERA TRU ERE TENERE RES 55 O 2013 AGNITAS AG 2 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 13 10 cm type tbl O 2013 AGNITAS AG 3 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 1 Advantages of an Extension Architecture Almost all big popular software products use an architecture which permits its enhancement via extension code plugins because it makes the software in general more flexible features can be added and removed according to ones own needs modular a lean core and a set of extensions instead of one big monolithic code monster maintainable components can be installed updated and removed independently from each other To become more specific an extension architecture has many advantages for both developers and users Advantages for developers an extension developer does not have to comprehend the whole code of the software but only needs to understand its extension interface consisting of extension points and the extension API the software core does not get bloated with functionality less complexity less dependencies extensions can be maintained independently from the core software and vice versa updates of the software core are easier to execute because the only dependency on existing extensions are the locations of extension points and the signature
10. a request parameter feature is attached like extension do feature dummy featur and sometimes the parameter is missing in the URL but transfered as hidden form field lt input type hidden name feature value dummy feature gt In Struts configuration file struts config xml extension do is mapped to Struts class ForwardAction with parameter extensioninTiles which means that the request is forwarded to Tiles definition extensioninTiles In Tiles configuration file tiles defs xm the generic extension definition extensioninTiles is mapped to path extensionSetupServlet for page setup rendering of application frame and to path extensionServlet for page body rendering of application content O 2013 AGNITAS AG 30 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 In deployment descriptor web xm path extensionSetupServiet is mapped to servlet ExtensionSetupServlet and path extensionServlet is mapped to servlet ExtensionServlet both located in package org agnitas emm extension web Servlet ExtensionSetupServiet first retrieves the value of request parameter feature String feature request getParameter ExtensionConstants FEATURE REQUEST PARAMETER public static final String FEATURE REQUEST PARAMETER feature and after that calls method nvokeFeatureSetupExtension of class ExtensionSystemimpl with parameter feature as extension ID extensionSystem invokeFeatureSetupExtension feat
11. adds the JSP defined as input parameter to the current reponse so that it can access and display attributes set by an extension for the current request Object extension is the extension instance of the current extension taken from the extension registry It offers various get methods to retrieve extension IDs extension point IDs and other parameters Please see the JPF API doc at http jpf sourceforge net api index html for details Object context is the Spring web application context which should be used to retrieve EMM OpenEMM s DAO classes bean classes etc 3 3 1 Setup Feature extension point featurePlugin first calls callback method setup of the gateway class which has to assign message keys to attributes in the request scope This step is separate from the invocation of the extension s code because the attributes are needed early in the rendering process of the GUI to generate the content for the navigation sidebar the active submenu and the tabs menu When the GUI is rendered message keys agnTitleKey and agnSubtitleKey are replaced by the language specifies values from file messages plugin properties via JSP head tag jsp List of navigation and menu attributes sidemenu active active menu item in side menu sidemenu sub active active submenu item in side menu agnTitleKey message key for first text in browser title title tag defaults to Extension if not set agnSubtitleKey message key for second text
12. agn message key message plugin dummy feature gt lt input type text name value gt lt input type submit name lt agn message key button plugin dummy feature gt gt lt form gt lt div gt lt div class grey box bottom gt lt div gt lt div gt The first two lines include the tag libraries for custom tags like agn message and JSTL tags like c url so that the code for the tag can be located JSTL tag c url creates the full URL of the extension system s generic path extension do and assigns it to parameter form url This URL is used by the action parameter of the form tag to define the target of the submit button The used DIV classes make sure that your layout fits neatly into the existing layout Hidden field feature make sure that request parameter feature is set to the ID of the feature extension point to be used The message for the key of the submit button is read from the properties file of the extension with ID dummy_feature If you want to use the powerful third party tag disp ay to show a list or a table in the JSP you should add line 8 taglib uri http displaytag sf net prefix display gt in the JSP header to specify its tag library so that the code for the display tag can be located You may use the tag in the JSP body like this lt display table class list table id item name resultList excludedParams gt lt display column titleKey dummy feature class dummy h
13. deactivated and removed because every extension will need at least one extension point to extend EMM OpenEMM O 2013 AGNITAS AG 15 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 4 Extension Points in Detail As mentioned before in section 3 6 EMM OpenEMM offers three types of extension points GUI extension points to insert output of an extension into an existing JSP Navigation extension points to add new menu items or tabs to the existing navigation Feature extension point to add new code which enhances the functionality 4 1 GUI Extension Points A GUI extension point allows an extension to write output to the GUI of EMM OpenEMM System extension core provides the two GUI extentension points footer and admin view pos2 by default Extension point footer is located at the end of JSP footer jsp lt agn JspExtensionPoint plugin core point footer gt g p plug pP and point admin view pos2 is placed after the first content box of JSP admin view jsp lt agn JspExtensionPoint plugin core point admin view pos2 gt If you want to set your own GUI extension points insert custom tag agn spExtensionPoint anywhere in the designated JSP Tag agn spExtensionPoint uses attributes plugin and point which are required both You can include the tag into an OpenEMM JSP like this 8 taglib uri WEB INF agnitas taglib tld prefix agn gt _ WEDTINF aqgnitas tagiin t1a p g lt agn JspExtensionPoint plugi
14. ed toria net den Pepe Eee Fare a E EUR 41 12 16 datasource description _tbl HH 42 12 17 Cate Cb asses i aeter e iet cats Fes ee iaa RS Re EE ERR ENARRARE cease ERE db em da eT AE n UA RE 42 12 18 doc Mapping lic E E aes rper di Alene ee re ERE ieee 42 12 19 dyn content tbl tia Priore set teet exu revente dana ebrii Re Edu eda Ra dua dead res 42 12 20 dyn niame tbl iterare enin a EM RE dans 43 LZ 2 Tidy target tbls 46a tir et street Edo 43 12 22 export predeTt tbl iiiee ic ice che e rt echo ee KE eon ni nnde e eu Vk an eR Ede PX ME E ERR ERAN des 43 12 23 import column mapping _tbl nennen nennen nennen nnns 44 12 24 import gender Mapping tbl sise 44 12 25 import LOG oli AA ada 44 12 26 1IMport profile tb usi i a is peri eret ANA NENTI RO 45 12 27 login track linia 45 12 28 Maildrop_status livianas er tnn rh hl Ree Erin tan Rr dd aa 45 12 29 malling account tbl 2 nce tiere rn anter eH Rx nbn Ex Ya EDEN Ioa LAE Das pa ber bli 46 12 30 malling backend l g ble nhien hone rere re rere i er erp ei dad dei 46 12 31 mallirig FOE bl oii eee oen e hee eir nex annee dre AAA FRE Nel nd A A nis 46 12 32 mailing euo 47 12 33 mallinglISt tDl 4 5 sin eret tnc ehh dana 47 12 34 fhallloODztbl si eti d t t te enter rne Ai ERR EE E rale dt 48 12 35 MALUtCACK tolerira ta Foe teet a ova Na av ia e aii Desa ES e
15. have chosen JPF instead of the defacto highend standard OSGi because we feel that JPF is less complex than OSGi and that it provides everything that we need but not more 2 1 The Extension APl EMM OpenEMM s very powerful and comes with a rich set of features Accordingly EMM OpenEMM offers lots of interfaces to access bean objects and DAO classes with CRUD methods To prevent re inventing the wheel again we strongly suggest that ou use the existing interfaces You will find the basic bean interfaces in package org agnitas beans and the the CMS bean interfaces in package org agnitas cms beans The basic DAO interfaces are located in package org agnitas dao and the CMS DAO interfaces in package org agnitas cms dao The DAO interfacess provide a Javadoc documentation and the names of properties and signatures of methods of the bean interfaces should be self explanatory We also provide a Javadoc documentation for the Struts action classes in case you want to re use those or just need ideas how to implement certain features In general if you want to know more about the design and the structure of the OpenEMM code you should download the OpenEMM code design guide available at https sourceforge net projects openemm files OpenEMM 20development Please feel free to dig into the wealth of available public properties and methods and use them as you like Only if you come across an deprecated annotation like Deprecated since release 2
16. id ID of admin group gt admin group tbl admin group id security token Permissions of users in admin group 12 2 admin group tbl Table description Contains admin groups The permissions of the groups are registered in admin group permission tbl All admin groups with company id 1 are visible to all companies Column name Description admin group id ID of admin group auto generated company id 1 shortname Name of the admin group description Description of the admin group 12 3 admin permission tbl Table description Contains individual permissions of admins users to assign permission beyond group permissions Column name Description admin id ID of admin gt admin tbl admin id security_token Individual permissions of admins 12 4 admin_tbl Table description Contains info about admins users Permissions for admin_id 1 master user must be defined in table admin_permission_tbl O 2013 AGNITAS AG 37 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Column name Description admin_id ID of admin auto generated company_id 1 username User name for login fullname User name shown in the frontend admin_country Home country of admin us de etc admin_lang Language of admin us de etc admin_timezone Timezone of admin admin_lang_variant Variation of timezone like de_at layout_id User defined layout gt emm_layout_tbl layout_id pwd_hash MD5 hash of password pwd_cha
17. media type email from subject charset mailformat reply and onepixel Contains mailing and template information Column name Description mailing_id mailinglist_id mailinglist_tbl mailinglist id campaign_id campaign mailtemplate_id is template well company id shortname description mailing type creation date change date target expression needs target deleted archived cms has classic content content dynamic template openaction id rdir action tbl action id clickaction id 12 33 mailinglist tbl Table description ID of mailing auto generated ID of mailing list which the mailing is sent to gt ID of campaign archive the mailing belongs to or O for no gt campaign tbl campaign id ID of template the mailing is based on or O gt mailing id 0 mailing 1 template templates are saved in mailing tbl as 1 Name of mailing Description of mailing 0 standard 1 date based 2 event based Creation date of this record Date of last change for this record List with chosen target groups separated with and amp 1 mailing needs to be assigned to target group 1 mailing is flagged as deleted and not shown in GUI 1 mailing is used for online archive flag for type of mailing content 0 clean and right for CMS based 1 filled with classic content defines if changes to template are copied to depending mailings default O no ID of default adection for mail
18. openings gt ID of default action of link clicks gt rdir_action_tbl action_id Contains mailinglist information Column name Description mailinglist_id company_id shortname description O 2013 AGNITAS AG ID of mailinglist auto generated 1 Name of mailinglist Description of mailinglist 47 55 EMM OpenEMM Extension Development Guide 12 34 mailloop_tbl Table description 1 0 10_20140709 Contains mailloop bounce filter information Column name Description rid mailinglist_id form_id shortname description company_id subscribe enable forward forward_enable ar sender ar subject preceded with ar text ar html ar enable change date 12 35 mailtrack tbl Table description ID of mailloop also included in email address of mailloop ID of mailinglist to subscribe to by email subscribe enable 1 gt mailinglist tbl mailinglist id ID of form called on double opt in gt userform tbl form id Name of mailloop Description mailloop 1 Subscribe by email 0 2 disabled 1 enabled Email address to forward mails to which were not filtered Email forwarding 0 disabled 1 enabled Sender address ofautoresponder Subject line of autoresponder if empty original subject is prefix Re Text content of autoresponder HTML content of autoresponder optional Status of auto responder 0 disabled 1 enabled Date of last change for this record Contains a record
19. 012 alternative you should no longer use the property method but choose the provided alternative because the property method will be removed in a later release at the earlist two years later Please note If you want to use classes of packages com agnitas feel free to do so but be aware that in this case your extension will only work with EMM not with OpenEMM To maintain integrity and consistency of database content the code of an extension must never change the content of the database tables directly with SQL statements The only way to use the database tables is using the Extension API or your own DAO classes 2 2 Extension Points O 2013 AGNITAS AG 5 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Generally an extension point enables the core to execute code of an extension An extension point is a pre defined hook in the software core or in a base extension the contact which defines an interface the contract that will be implemented by a class of an extension that was registered for this extension point before To register an extension for an extension point the manifest file of the extension must assign a class of the extension to this extension point When an extension is installed by the extension manager the info of its manifest file are written to the extension registry which in turn is accessed by an extension point to retrieve all classes bound to it In EMM OpenEMM all basic extension points are suppli
20. Date of last change for this record Contains templates for export profiles Column name Description id mailinglist id target id company id shortname description column names customer 1 tbl for export mailinglists should be separator char delimiter char charset O 2013 AGNITAS AG ID of export template ID of mailinglist gt mailinglist tbl mailinglist id ID of target group gt dyn target tbl target id 1 Name of export template Description of export template Semicolon separated list of column names from file Semicolon separated list of mailinglist IDs whose user status added to export file Field separator or tab used in export file Delimiter no or for text in export file Character set used for export 43 55 EMM OpenEMM Extension Development Guide user_status bounced waiting for user_type deleted timestamp_start timestamp_end creation_date_start creation_date_end mailinglist_bind_start mailinglist_bind_end 1 0 10_20140709 Status of recipient s assignment to mailing list 1 active 2 3 Opt out by admin 4 Opt out by user 5 Double opt in confirm 6 blacklisted 7 suspended Type of recipient A admin T test W normal world flag for deleted export template 1 deleted Start date of change period End date of change period Start date of creation period End date of creation period Start date of mailinglist binding period End da
21. EMM OpenEMM Extension Development Guide 1 0 10 20140709 AGNITAS EMM OpenEMM Extension Development Guide Table of Contents 1 Advantages of an Extension Architecture oomcconcccnnoconnnconnoronannnorcnnannnncrrnannancranannos 4 2 Components of the EMM OpenEMM Extension Architecture ss 5 2 1 The Extension ARI serali eater RA bata wens 5 2 2 EXTENSION POINTS una a A ia 5 2 3 Extension Manager vera A e a adda at 6 2 4 EXtension REGISEFY isc a eren A a a depu MT age nee annee anne ee 6 2 5 Extension RepositO Vai ie tte Ree RE RN qai a de iere EXE 6 3 Components of an EMM OpenEMM Extension e sseeessen esee nnnn nane nnn 8 3 1 Components of a Manifest File 8 3 2 Resource Files tirs Foe pup Ie A vene dream isa Dee te net 9 3 2 1 Messages Properties sise 9 3 2 2 Navigation Properties lecitina n EORR See eaa nds 10 3 3 EN E CTI RII 10 Bs BAGO hoa coc eho Ne CEA EM AAA Nn D NO ELEM e ccc 11 3322 In VOKe ict best E ce esed and ebrei dee ita OR Dti etu Eel ve Rc va P Ria 11 3 4 Java Server Pages JSPs enne nnne nine nire senes nennen nas 11 3 5 Structure of an Extension ZIP File sis 12 3 5 1 Default Path SettinGSs ool stent e di re id epe et cec e te cete 13 3 5 2 Path Settings in Manifest File 14 3 6 System EXtensiONS een edo en ea scares te are alic aet i etie 14 3 6 I System Extension COFe one p terere er ei dina HE Teo ER Ed attentes ent Rv ener ue ra 14 3 6
22. EMM OpenEMM comes with two system extensions which contain no own code but provide root extension points via their manifest files These extension points can be be used by other extensions to hook into EMM OpenEMM 3 6 1 System Extension core Manifest file p ugin xml of extension core EMM emm core supplies the global feature extension point featurePlugin which is the entry point for all extensions providing code enhancements for EMM OpenEMM See section 4 3 for more details Furthermore core provides GUI extension points footer and admin view pos2 as examples These extension points may be used by an extension to insert its output in the GUI of EMM OpenEMM Right now there are only two GUI extension points in EMM OpenEMM but we will add more GUI extension points in future releases Section 4 1 demonstrates how you can add your own GUI extension points 3 6 2 System Extension core_navigation 2013 AGNITAS AG 14 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 The manifest file of extension core_navigation EMM emm_core_navigation supplies lots of navigation extension points to extend EMM OpenEMM s navigation sidebar its submenus and all tabs menus The manifest file plugin xml of core navigation lists all available extension points These extension points may be used to integrate new features seemlessly into the GUI of EMM OpenEMM See section 4 2 for more details Both extensions core and core_navigation must not be
23. Java Classes The functionality of an extension is usually implemented by the program code of one or more Java classes The code of an extension is invoked by feature extension point featurePlugin see section 4 3 for details which is bound to a specific class of the extension An extension class which is bound to the feature extension point is called gateway class in this guide because it provides the gateway to the feature code of an extension To implement feature extension point featurePlugin correctly the gateway class of an extension has to implement interface EmmFeatureExtension with its two callback methods public void setup PluginContext pluginContext Extension extension ApplicationContextcontext and public void invoke PluginContext pluginContext Extension extension ApplicationContext context Make sure that first argument is of type org agnitas emm extension PluginContext second argument is of type org java plugin registry Extension third argument is of type org springframework context ApplicationContext Object pluginContext provides three methods public HttpServletRequest getServletRequest O 2013 AGNITAS AG 10 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 public HttpServletResponse getServletResponse public void includeJspFragment String relativeUrl The first two methods offers access to the HTTP request and HTTP response object and method ncludeJspFragment
24. U ent 48 12 36 onepixel log tbi eter pete iia 48 12 37 plugins Blois errare een tele een Ge ee RA PRSE EL ER nda 48 12 38 rair action tbi tiii oed ha dod pee tr abe sde Poe WES EE dan d Agen ra done e x DE xg Pere nn 49 12 39 FOI lO dol Pe 49 12 40 FOI Url ite reb AA Eaa UR DOE Sit x lente E ERE a aAa 49 12 41 rulebased sent tbl eere rl canes e p da reverts 50 12 42 sottbounce emall tb uei iiie rrr a E FEAR AR xr e dira 50 12 43 tag tbl arni oa aee a A A ED REID e repite walt ee eu ii 50 12 44 timestamp AD lanes 50 12 45 title gender li a a eee 51 ura louer 51 12 47 serft rm tbla aand rre erroe dd ena eaei aa eai Eaa aa A 51 12 48 webservice User tbh ns i iet rester aia dus date eua rara den age di deni he dentate beets 52 qp ES EISE To ue aod o yaa r aa a a Ta dl do Taa aa EEn 52 13 Appendix B Database Schema of CMS of OpenEMM nennen 53 131 m Cat gonystbli2 et tp tee nr a etant IA AA 53 132 cm content Mmodule Eliminar geai anr E Ine a D aana aa a eaaa ere 53 13 3 cm content tbl iiiaae da 53 13 4 EM lOCAtiOn tbls aana t e a e a na ute tb dr A R EIER PU RATE Nna 53 13 5 Cm Mailing bind tbi cono etr rere nude test de dt bp er ska cen RE den de 54 13 6 cm media file lia li VA ne a cathe rre A A wile Ps 54 13 7 cm template mailing_bind_tbl HH 54 13 8 cm template tb eee ec n ape rk nr eA bc red
25. a 28 8 4 Deployment of BIRT Extensions sis 29 9 Inside the EMM OpenEMM Extension Architecture sssssssssmsneeneneeemnnsss 30 9 1 Extension Systems aldea 30 9 2 Program FlOW tania ia de Vanne nn A a EUR pd un RAC ARR Vans up 30 9 3 Main Components of the Extension Architecture 32 10 Documentation Requirements for EXtensSi0NS cmmooconnnconnnconncrnnncnnancrnnnnnnnnennanas 35 11 Todo List for Next Versions of Extension Architecture 36 12 Appendix A Database Schema of OpenEMM eeeesseeeem nnn nnn nnns 37 12 1 admin_group_permission_tbl HH Henne 37 122 AMIA QrOU ptp Rs 37 12 3 admin Permission linia a a annees ta epa se px Pase p dense 37 O 2013 AGNITAS AG 1 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 ZA AAN lic a 37 12 5 bounce collect liinda dad A nr E E AA 38 12 0 Dounce A A A 38 12 7 campaign tbl o rc A aid 39 12 8 click stat colors tbl eum et er e pepe AEEA EEA aa FERNER ten ERR eee RENTES 39 12 9 compatiy tDl scritte e Ene RD RE nde Qoi EH Mec Me a pie pate Eye tatu Even ed vus 39 12 10 component tpl RE 40 12 11 config A NN 40 12 12 cust ban tbl ricco iit Fest eot rp en eene fedi des eran eed dnd 40 12 13 Customer binding tbl iiie e oii etre prete aa e ce aA Duke ead 40 12 T4 customer T li ps wei etre ede ie rrt Dark xen nan e rea Od er le ee MER LE LS 41 12 15 customer field tbl iloee trate da rane wes eene
26. ameters invoke executes extension s program code ExtensionManager Utility class with methodes to create and manage extension instances ExtensionSystem Impl Main class to manage extension system extensions and extension points ExtensionSystemBuilder Initializes extension system at launch time of EMM OpenEMM used by listener ExtensionSysteminitializationContextListener ExtensionSystemConfiguration Configuration data for extension architecture used by ExtensionSystemBuilder JspExtension Interface with method invoke for extensions implementing GUI extension points JspRestoreUtil Utility methods to copy JSP files and accompanying files like images JS files etc from backup directory to deployment location LocationTracker Manages locations URLs of extensions PluginContext Impl Context of application like HTTP request and response for use by extension PluginFilenameFilter File name filter for locating extensions Plugininstaller Impl Installs extensions from ZIP files ResourceBundleManager Reads resource bundles for method getPluginResourceBundle of class ExtensionSystemimpl Package org agnitas emm extension annotation DispatchTarget Interface for annotation DispatchTarget convenience annotation inspired by Struts DispatchAction Package org agnitas emm extension dao impl PluginDao Impl Interface DAO class to access meta data of extensions from database table p ugins tbl Package org agnit
27. as emm extension exceptions various classes representing the custom exceptions of the extension architecture O 2013 AGNITAS AG 32 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Package org agnitas emm extension pluginmanager action form e PlugininstallerSelectAction Struts action class to select extension file upload uses plugininstaller select jsp e PlugininstallerSelectForm Struts form bean for action class PlugininstallerSelectAction e PlugininstallerUploadAction Struts action class to initiate extension file upload via Plugininstallerlmpl e PluginManagerAction Struts action class to manage extensions uses pluginmanager list jsp for table of extensions and pluginmanager detail jsp for list of extension details Package org agnitas emm extension sglparser CommandState Represents default parser mode parsing a SQL statement e MultiLineCommentState Represents parser mode parsing a multi line comment indicated by e ParserState Generic interface for all parser mode classes in this packages State e PossibleMultiLineCommentEndState Represents parse mode possibly ending to parse a multi line comment indicated by e PossibleMultiLineCommentState Represents parse mode possibly starting to parse a multi line comment indicated by e PossibleSingleLineCommentState Represents parse mode possibly parsing a single line comment indicated by QuotedStringState R
28. ascript HTML CSS and images The extension manager takes care to put the files from the ZIP file of an extension in the appropriate directories of EMM OpenEMM see section 3 5 3 1 Components of a Manifest File The major components of a manifest file are e unique extension ID version name and vendor of extension the alphanumeric UID will be used for directory names by the extension manager and should be used as prefix for new database tables and fields various attributes like extension name description and file name of messages properties file tag attributes required extensions for this extension by their extension IDs tag requires path to resource files and class files in ZIP file of extension tag runtime definition of GUI navigation or feature extension points for use by subsequent extensions tag extension point definition of bindings of own extension classes to extension points of underlying extensions like system extensions tag extension Below you can see the content of a very simple manifest file taken from system extension core lt xml version 1 0 gt lt DOCTYPE plugin PUBLIC JPF Java Plug in Manifest 1 0 http jpf sourceforge net plugin 1 0 dtd gt lt plugin id core version 0 0 1 vendor Agnitas AG gt lt attributes gt lt attribute id plugin name value EMM core system gt lt attribute id plugin description value System plugin providing core
29. atements Right now the validator checks if the names of new tables created by an extension use the extension ID as prefix and _tbl as suffix and it checks if new columns outside of extension s tables use the extension prefix as well Additionally the validator checks that only those tables are dropped which use the extension ID as prefix and that columns in other tables are dropped only if they use the extension prefix as well This is done to make sure that no core tables no tables from other extensions no core columns and no columns from other extensions will be removed When writing SQL statements for a SQL file please make sure to follow these rules in order to prevent creating a mess in the database 1 Do not alter rename or drop core tables of EMM OpenEMM see appendix A for details 2 Do not modify content of existing core tables of EMM OpenEMM see appendix A for details 3 Ifyou want to create new tables for an extension use the extension ID as prefix and suffix _tbl for all table names like dummy_name_tbl 4 If you add new columns in tables which do not belong to your extension use the extension ID _ as prefix for the column name 5 Do not write ALTER TABLE statements which mix ADD and DROP instructions because they will be rejected by the validator of the extension manager 6 While an ALTER TABLE statement to add new columns may add more than one new column an ALTER TABLE stateme
30. bl Table description ID of text entry ID of admin user gt admin tbl admin id text content Contains CM types content module templates for CMS Column name Description id ID of CM type company id 1 shortname Name of CM type description Description of CM type content Structure of CM type read only read write flag 0 writeable 1 read only is public public private flag 0 visible to own company_id 1 visible to all companies O 2013 AGNITAS AG 55 55
31. de of extensions can be registered that provides its functionality The second and third extension points are GUI extension points and allows an extension to insert output into the footer area and respectively the admin view of EMM OpenEMM 3 2 Resource Files Resource files of an extension provide messages properties for the GUI and navigation properties supply values for the navigation sidebar submenus and tabs menus 3 2 1 Messages Properties You should never hard code messages in the GUI of an application To be able to offer messages in different languages EMM OpenEMM offers a JSP custom tag agn message which is similiar to tag bean message Tag agn message needs two attributes plugin and key Attribute p ugin defines the ID of the extension providing the messages properties file and attribute key is the message key Example lt agn message key key name plugin dummy feature The name of the file providing all messages properties is defined in the manifest file of an extension within the attributes block like this attribute id il8n bundle value messages plugin This means that the default messages file is messages plugin properties And since the extension architecture of EMM OpenEMM support I18n you can also provide localized messages files like messages plugin de properties for a German language GUI or messages plugin fr properties for French O 2013 AGNITAS AG 9 55 EMM OpenEMM Extension Development Guid
32. e 1 0 10 20140709 3 2 2 Navigation Properties The name of the file providing the navigation properties is also defined in the manifest file of an extension For each navigation extension point that has to be implemented a tag extension is needed in the manifest file Tag extension defines the extension name and its extension point that has to be implemented declares an ID for later reference and defines via parameter navigation bundle the name of the file with the navigation properties for the extension point implementation Example lt extension plugin id core navigation point id tabs feature id dummy navigation gt lt parameter id navigation bundle value dummyFeature gt lt extension gt In this case the fictive navigation extension point tabs feature is extended by the navigation content of file dummyFeature properties The content of this file could look like this msg_1 dummy Feature href 1 extension do feature dummy feature point token 1 dummy feature This content defines one new tab with message key dummy Feature which is linked to the feature extension point implementation with ID dummy feature point and is only visible to the user if permission token dummy feature is set for the user Please see chapter 7 to learn how to set permission tokens in the database If you need more than one new menu item or tab you have to name the properties of the second entry with msg_2 href_2 and token_2 and so on 3 3
33. e 1 0 10 20140709 DatabaseScriptsDirectory home openemm plugins pluginid db JspBackupDirectory home openemm plugins pluginid jsp JspBaseDirectory webapps plugins JspWorkingDirectory webapps plugins pluginld PluginBaseDirectory plugins home in emm properties home openemm plugins PluginDirectory home openemm plugins pluginld SystemPluginBaseDirectory webapps WEB INF system plugins SystemPluginDirectory webapps WEB INF system plugins pluginld 3 5 2 Path Settings in Manifest File To make sure that the extension manager finds properties files class files and JAR files in the ZIP file you have to specify their paths relative to directory bin within tag runtime of the manifest file like this lt runtime gt lt library id dummy feature path classes type code gt lt library id dummy feature lib path lib dummy jar type code gt lt runtime gt The first entry defines that resource and class files will be found in subdirectory bin classes and the second entry points to JAR file dummy jar in subdirectory bin lib Basically all entries within tag runtime are added to the classpath of the extension Please be aware that subdirectories in directory bin whose names start with underscore character _ are not copied from the ZIP file for deployment to avoid name collisions because the extension system uses directories starting with _ for internal purposes 3 6 System Extensions
34. eaderClass dummy head name property feature sortable false display table You can find the documentation for the display tag at http www displaytag org We strongly recommend its use because it eases the formatting of list and table output significantly 3 5 Structure of an Extension ZIP File O 2013 AGNITAS AG 12 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 The files of an extension have to be compressed into a single ZIP file with extension zip to produce a valid extension package The pre defined directory structure for an extension ZIP file looks like that plugin xml manifest file of extension README txt optional readme file bin classes property files properties bin classes Java class and interface files class bin lib Java libraries jar db install remove mysq l oracle sql up to 4 files containing SQL statements to install or remove database schema information or content see chapter 6 jsp JSP files jsp jsp html HTML and CSS files html css jsp images images png jpg etc jsp js JavaScript files js doc documentation files txt pdf src source code files java The two directories doc and src are not processed by the extension manager but may be included to provide information for the user like a manual license information or the source code of the class files Best way to generate the ZIP file is to change to the directory level of manif
35. ecipient s profile data could amend the recipient menu with a new menu item wizard New tab an extension implementing a new sub feature should add a new tab to the page with the main feature example a wildcard search for the blacklist should add a new tab blacklist search to the blacklist page see section 5 3 To integrate an extension in the navigation sidebar a submenu or a tabs menu of EMM OpenEMM an extension has to implement the matching navigation extension point This is done by binding the file with the additional navigation properties of the extension to the extension point in the extension s manifest file like this lt extension plugin id core navigation point id point name id dummy gt lt parameter id navigation bundle value dummyFeature gt lt extension gt This example extends fictive navigation extension point po nt_name of extension core navigation with the content of navigation properties file dummyFeature properties Parameter href of the properties file should be defined like this see section 3 2 2 for details href 1 extension do feature dummy feature point This ensures that extension point dummy feature point is invoked once the new menu item or tab gets clicked Of course this only leads to a result if the gateway class of the extension has been registered with feature extension point featurePlugin of core using ID dummy feature point see next section for details Navigation
36. ed by system extensions See section 3 6 for details 2 3 Extension Manager The extension manager GUI term plugin manager is a sub system of the software core with functionality to manage the lifecycle of extensions It is visible for the user of EMM OpenEMM if permission token pluginmanager show is set see chapter 7 for details The lifecycle stages of an EMM OpenEMM extension are Uploaded gt Activated gt Deactivated gt Removed Uploaded The ZIP file of the extension is uploaded its manifest file is parsed compatibility and dependencies are checked the manifest configuration content is stored in the extension registry and the files of the extension are unzipped and copied to the appropriate directories of EMM OpenEMM Activated The extension is registered with all extension points defined in its manifest file and therefore made active If the extension depends on an other extension which is already uploaded but not activated yet this extension is activated as well Deactivated The extension is un registered from all extension points Any other extension which the extension depends on remains activated Removed The extension info are removed from the extension registry and all installed files of the extension are removed from the directories of EMM OpenEMM The initial list view of the extension manager shows a list of all installed extensions The detail view of a single extension shows info like its name version
37. epresents parser mode parsing a quoted string within a SQL statement indicated by quotation character or e SimpleSqlParser Implementation of SQL parser entry point for this package with big constructor to set up parser configuration parses SQL file removes all comments and creates list of SQL statements to be executed e SingleLineCommentState Represents parser mode parsing a single line comment indicated by e StatementBuffer Holds the intermediate result of the parsed SQL statement Package org agnitas emm extension sglparser validator impl e DatabaseScriptValidator Interface for SQL statement validation implemented by class SimpleDatabaseScriptValidator e AlterlableAddColumnValidation Checks if SQL statements adding column s to an existing table use extension ID _ as prefix in column names e AlterlableDropColumnValidation Checks if SQL statements dropping a column dropped from an existing table drop only columns with extension ID as prefix in their names e BasicValidation Implementation of interface StatementValidation with basic validation code to be used by special purpose validator classes e CreateTableValidation Checks if SQL statements creating new tables use extension ID as prefix for table names e DropTableValidation Checks if SQL statements dropping existing tables only drop tables with extension ID as prefix in their names e SimpleDatabaseScriptvalidator Implements int
38. ere O 2013 AGNITAS AG 28 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 extension ZIP files are copied to identical to property birt plugin directory on EMM server side 8 4 Deployment of BIRT Extensions The extension manager of EMM will install and un install BIRT plugins like any other extension However since it is not possible to assign BIRT new Java classes at runtime you have to restart the BIRT server after installation and un installation of a BIRT plugin to activate the change This is what will happen exactly at restart time 1 all rptdesign files installed by extensions will be removed 2 all JAR files installed by extensions will be removed 3 the directory defined in property plugins home will be searched for extension ZIP files and all rptdesign files and JAR files will be unpacked and deployed O 2013 AGNITAS AG 29 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 9 Inside the EMM OpenEMM Extension Architecture While you do not need to know the following technical details to write an extension for EMM OpenEMM it might be interesting for you to get a glimpse behind the curtain Since the extension architecture of EMM OpenEMM is built on top of framework JPF Java Plugin Framework it might be a good idea to have a look at the extensive documentation of this framework as well http jpf sourceforge net 9 1 Extension System Interface ExtensionSystem and its implementation class Exte
39. erface DatabaseScriptValidator entry point for SQL statement validation calls all validation classes for special purpose validation uses state machine pattern e StatementValidation Generic interface for validation classes Package org agnitas emm extension taglib e Extensionl18NTag Custom tag agn message for localized messages in extensions JspExtensionPointTag Custom tag JspExtensionPoint to set GUI extension points within JSPs O 2013 AGNITAS AG 33 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Package org agnitas emm extension util ExtensionUtils Provides some auxiliary getter and setter methods e ExtensionConstants Defines some constants for the extension architecture 18NFactory Factory to supply the appropriate resource bundle e 18NResourceBundle Special resource bundle class to be used by custom tag agn message Package org agnitas emm extension web e ExtensionServlet Servlet to call callback method invoke of an extension see section 8 2 for details ExtensionSetupServlet Servlet to call callback method setup of an extension see section 8 2 for details Package org agnitas taglib e ShowNavigationTag code for custom tag ShowNavigation e used in JSP sidemenu tiles jsp to build navigation sidebar e used in tabsmenu jsp to build tabs menus e modified for the extension architecture to process navigation data from navigation properties files of the core and extensions and to build
40. ess use url 1 flag to indicate if form or URL should be used in case of URL that is called in case of error if error_use_url 1 51 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 error_use_url flag to indicate if form or URL should be used in case of error default 0 12 48 webservice_user_tbl Table description Contains users of webservice API 2 0 Column name Description username Name of user password Password company_id 1 12 49 ws_admin_tbl Table description Contains users of webservice API 1 0 Column name Description ws_admin_id ID of webservice user auto generated username Name of user password Password O 2013 AGNITAS AG 52 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 13 Appendix B Database Schema of CMS of OpenEMM This appendix contains a description of the database tables of the CMS of OpenEMM 2013 openemm_cms To retrieve the datatypes of the columns of certain tables simply execute gt mysql u root p mysql gt use openemm cms mysql gt desc name and replace name with the name of the table you are interested in 13 1 cm_category_tbl Table description Contains all categories of the CMS Column name Description id ID of category shortname Name of category description Description of category company_id 1 13 2 cm content module tbl Table description Contains content modules for CMS Column name Description
41. est file p ugin xml and to create the ZIP file from there with zip r extension name In this case the ZIP utility of Linux recursively compresses all files and subdirectories of the current directory into file extension name zip The extension manager unpacks the ZIP file and copies p ugin xm and all files from directories bin db and jsp into a subdirectory named like the extension ID in directory plugins called extension directory below bin is copied to subdirectory bin db is copied to subdirectory db and jsp is copied to subdirectory jsp of the extension directory The classloader of the extension system is able to load classes from the extension directory which is outside of the webapps directory But since it is not possible to execute the JSPs from outside of the webapps directory the extension manager copies all files from directory jsp additionally to deployment location webapps openemmyplugins into a subdirectory named like the extension ID At startup of EMM OpenEMM the extension system copies all files from all jsp subdirectories in directory plugins to the deployment location again This makes sure that extensions survice an update of the core software because otherwise JSP files would be lost since a core update would overwrite directory webapps openemm plugins 3 5 1 Default Path Settings These are the typical path settings used by OpenEMM 2013 AGNITAS AG 13 55 EMM OpenEMM Extension Development Guid
42. extension points gt lt attributes gt lt requires gt lt import plugin id core navigation gt lt requires gt 1 URL extension point gt lt extension point id featurePlugin gt lt parameter def id class type string gt lt extension point gt lt l Extensi n points for outputs to JSP gt O 2013 AGNITAS AG 8 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 lt extension point id footer gt lt parameter def id class type string gt lt extension point gt lt extension point id admin view pos2 gt lt parameter def id class type string gt lt extension point gt lt plugin gt The XML format of the manifest file is defined by the Document Type Descriptor DTD of the JPF framework You can find the DTD with lots of comments here http jpf sourceforge net dtd html The ID of the extension is core its version is 0 1 0 and developer is Agnitas The extension ID must be unique if in doubt please check with us The following attributes provide a name and description of the extension which are shown in the extension manager Tag requires specifiy any dependencies In this case the manifest file for core specifies that it is dependent on a second extension named core navigation Finally the manifest file specifies three extension points which may be used by other extensions The first extension point is a feature extension point where co
43. extension points can be nested that means the navigation properties file of an extension can contain extension points to extend the navigation of a first level extension by a second level extension Example navigation plugin core navigation navigation extensionpoint navigation main This is in fact the extension point of the main menu of EMM OpenEMM located at the end of navigation properties file sidemenu properties and it is the first extension point defined in plugin xml of system extension core navigation for use by second level extensions lt extension point id navigation main gt lt parameter def id navigation bundle type string gt lt extension point gt 4 3 Feature Extension Point EMM OpenEMM offers one global feature extension point named featurePlugin This is the entry point for all extensions providing code enhancements for EMM OpenEMM All extensions that want to extend the functionality of EMM OpenEMM have to implement this extension point At first the gateway class of an extension has to be bound to the feature extension point like this lt extension plugin id core point id featurePlugin id dummy feature point gt O 2013 AGNITAS AG 18 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 lt parameter id class value com domain emm plugin dummyfeature DummyFeatureExtension gt lt extension gt In this case gateway class DummyFeatureExtension has to implement interface EMMFeatureEx
44. for every recipient and every mail sent out to this recipient big table Does not indicate whether the mail was finally received by the recipient Column name Description mailtrack id ID of mailtracking record auto generated customer id ID of recipient gt customer 1 tbl customer id mailing id ID of mailing gt mailing tbl mailing id status id ID of mailing status gt maildrop status tbl status id company id 1 change date 12 36 onepixel log tbl Table description Date of last change for this record Contains a record for every recipient who opened a mail Column name Description customer id mailing id company id open count ip adr change date 12 37 plugins tbl O 2013 AGNITAS AG ID of recipient gt customer 1 tbl customer id ID of mailing gt mailing tbl mailing id 1 Count of openings for recipient IP address of recipient Date of last change for this record 48 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Table description Contains information on installed plugins Column name Description plugin_id ID of plugin auto generated activate on startup 0 do not activate 1 activate on startup default 12 38 rdir action tbl Table description Contains user defined actions Column name Description action id ID of action auto generated company id 1 shortname Name of action description Description of action action type Scope of act
45. id ID of mailing gt mailing_tbl mailing id maildrop_id ID of maildrop status gt maildrop_status_tbl maildrop_id company id 1 mailtype Mail type of mailing 0 plain text 1 HTML 2 inline HTML status field Mailing type A admin mailing T test mailing w World mailing R date based mailing E event based mail no of mailings Number of sent emails no of bytes Size of all mails of this block in Byte blocknr Number of XML block causing this entry change date Date of last change for this record 12 30 mailing backend log tbl Table description Contains information on how many mails of a mailing have been generated yet Column name Description mailing id ID of mailing gt mailing tbl mailing id status id ID of mailing status gt maildrop status tbl maildrop status id total mails Total number of mails of mailing current mails Number of mails which have been generated creation date Creation date of this record change date Date of last change for this record 12 31 mailing mt tbl Table description Contains the permitted media types for mailings and required configuration parameter for backend processing O 2013 AGNITAS AG 46 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Column name Description mailing_id mediatype param linefeed 12 32 mailing_tbl Table description ID of mailing gt mailing_tbl mailing_id Media type 0 email Configuration data for
46. in browser title title tag defaults to content of attribute name in extension s manifest file if not set agnSubtitleValue optional parameter to insert in browser title title tag agnNavigationKey name of navigation properties file for tabs menu items agnHighlightKey name of highlighted menu item in tabs menu agnNavHrefAppend optional parameter appended to navigation links agnHelpKey optional string for table doc mapping tbl which maps to a dedicated HTML page of the online user manual 3 3 2 Invoke After feature extension point featurePlugin has called method setup of the gateway class callback method nvoke is called to execute the extension s code which in the end generates the extension s output See section 4 3 for more information 3 4 Java Server Pages JSPs JSPs are used to build the GUI of an extension This may be a helpful example for a template of an extension JSP using a form 80 taglib uri WEB INF agnitas taglib tld prefix agn gt O 2013 AGNITAS AG 11 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 8 taglib uri http java sun com jsp jstl core prefix c gt lt c url value extension do var form url gt lt div class grey box container gt lt div class grey box top gt lt div gt lt div class grey box content gt lt form action form url method post gt lt input type hidden name feature value dummy feature point gt lt
47. in this case admin view jsp but the hyphen is replaced by a dot and the file extension is omitted The suffix of the name describes the location of the extension point within the JSP file The top position would be pos1 the second position after the first box would be pos2 the third position after the second box pos3 and so on If in later releases of EMM OpenEMM the GUI is extended and there would be a need to insert extension points between pos2 and pos3 for example these points would carry suffixes like pos23 or pos27 4 2 Navigation Extension Points EMM OpenEMM s navigation sidebar all submenus and all tabs menus provide extension points which are always located at the end of the list i e at the lowest or the righter most position in the navigation sidebar a submenu or a tabs menu Each navigation extension point can be implemented by more than one extension so that it is possible to enhance a menu with more than one item As a rule of thumb you should follow these guidelines New menu item in the navigation sidebar an extension providing a new set of functionality should be integrated as a top level menu item example a CMS module provides a new menu item CMS with submenus New menu item in a submenu an extension introducing a new feature should amend an existing menu with a new menu item O 2013 AGNITAS AG 17 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 example a new wizard to export r
48. ion 0 links only 1 forms only 9 both operations serialized instance of Java class from package org agnitas actions ops with code of action 12 39 rdir log tbl Table description Logs clicks on redirected links in sent mails Column name Description customer id ID of recipient gt customer 1 tbl customer id mailing id ID of mailing gt mailing tbl mailing id url id ID of URL gt rdir url tbl url id company id 1 ip adr IP address of clicking recipient change date Date of last change for this record 12 40 rdir url tbl Table description Contains all measureable mailing links Column name Description url id ID of URL auto generated mailing_id ID of mailing gt mailing_tbl mailing_id action_id ID of associated action gt rdir_action_tbl action_id company_id 1 full_url Genuine URL shortname Name of link measure type Defines which mailtypes will be measured 0 no 1 txt only 2 HTML only 3 both 2013 AGNITAS AG 49 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 relevance Relevance for statistics 0 counted 1 not counted for gross click rate 2 not counted at all 12 41 rulebased sent tbl Table description Contains timestamps of rule based date based mailings to prevent sending more often than daily if senddate in maildrop status tbl is changed Column name Description mailing id ID of rule based date based mailing lastsen
49. l Normalized DSN bounce code 7 possible values 400 420 430 500 510 511 512 dsn DSN bounce code reported back by mailserver or pseudo code 499 for soft bounces 599 for hard bounces change date Date of last change for this record O 2013 AGNITAS AG 38 55 EMM OpenEMM Extension Development Guide 12 7 campaign_tbl Table description 1 0 10 20140709 Contains campaign archive information Column name Description campaign id company id shortname description ID of campaign archive Name of campaign archive Description of campaign archive 12 8 click stat colors tbl Table description Color values for percentage ranges in heatmap Column name Description id ID of color auto generated company id 1 color Color value hex code like FF0000 range start Lower percentage value for range range ed Upper percentage value for range 12 9 company tbl Table description Contains basic information on OpenEMM configuration Column name Description company id 1 shortname Name of company default Agnitas Admin description Description of company default Agnitas status Status of company possible values active and inactive default active creator company id creation date xor key value links of sent timestamp notification email rdir domain http localhost 8080 mailloop_domain local FQDN mailtracking written to max_login_fails login_block_
50. lock Content of component of type 1 3 and 5 as binary emmblock Content of component of type O as text url id URL for image links gt rdir url tbl url id 12 11 config tbl Table description Contains generic configuration parameters like link checker parameters Column name Description class class or script for which the parameter is intended classid ID parameter optional name name of configuration parameter value value of configuration parameter 12 12 cust ban tbl Table description Contains email adresses which must be excluded from mailings blacklist Column name Description company id 1 email email address of recipient creation date Creation date of this record 12 13 customer 1 binding tbl Table description Contains assignments of recipients of customer 1 tbl to mailing lists O 2013 AGNITAS AG 40 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Column name Description customer_id ID of recipient gt customer 1 tbl customer id mailinglist id ID of mailing list gt mailinglist tbl mailinglist id user status Status of recipient s assignment to mailing list 1 active 2 bounced 3 Opt out by admin 4 Opt out by user 5 Double opt in waiting for confirm 6 blacklisted 7 2 suspended user type Type of recipient A admin T test W normal world user remark Comment for assignment like Opt in IP aaa bbb ccc ddd mediatype Media type 0 email exi
51. lopment Guide 1 0 10 20140709 creation_date Creation date of this record 12 26 import profile tbl Table description Contains user defined import profiles Column name Description id ID of import profile auto generated admin id ID of admin user gt admin tbl admin id company id 1 shortname Name of import profile column separator Field separator 0 1 2 3 tab text_delimeter Text delimiter 0 none 1 2 gt file charset Character set used for import 0 ISO8859 1 1 UTF 8 2 Chinese simplified date format Format for date fields 0 dd MM yyyy HH mm 1 dd MM yyyy etc import mode Import mode 0 add only 1 2 add update 2 update only 3 opt out 4 bounced 5 blacklist null_values_action Handling of NULL values 0 overwrite 1 ignore key_column Name of key column used for duplicate checks check for duplicates Type of duplicate check 0 2 import data only 1 2 complete 2 no check mail type Mail type 0 plain text 1 HTML 2 inline HTML report email email address for import reports update all duplicates Flag for duplicate update mode 0 only first 1 all ext email check deprecated 12 27 login track tbl Table description Contains all login tries to track failed logins used for login block Column name Description login track id ID of login try auto generated ip_address IP address of login try username user name used for login try login stat
52. meter def id class type string gt lt extension point gt An extension implementing this extension would define the binding to its gateway class like this lt extension plugin id core point id point name position id dummy gt lt parameter id class value com domain emm plugin dummy DummyExtension gt lt extension gt As an example please have a look at the implementation of extension points footer and admin view pos2 of system extension core by extensions hello world and admin info see sections 5 1 and 5 2 for details After you have inserted a GUI extension point in a JSP file and added its definition to the manifest file of system extension core you do not have to recompile anything A restart of the application is sufficient to activate the new extension point If you create GUI extension points in OpenEMM or need GUI extension points to be created in EMM please contact the author address at the end of this guide with info where your GUI extension point is located so that we will make sure that the next release of EMM OpenEMM provides this extension point out of the box Since it is not possible for us to anticipate all future extension scenarios we will add new GUI extension points on demand Extension point admin view pos2 demonstrates nicely the naming conventions for GUI extension points The first part of the extension point name consists of the name of the JSP file where the extension point is inserted
53. min_info consists of these files 1 Manifest file plugin xml provides configuration and dependency information of extension binds gateway class AdmininfoExtension to GUI extension point admin view pos2 2 Messages properties file messages plugin properties and local versions provides the message which is inserted in the page showing the details of an EMM OpenEMM user account O 2013 AGNITAS AG 20 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 3 Package org agnitas emm plugin admininfo file AdmininfoExtension java in directory src of ZIP file implements method invoke called by GUI extension point admin view pos2 inserts text box with message in JSP admin view jsp via tag JspExtensionPoint message is localized depending on the language of the current EMM OpenEMM user 5 3 Extension blacklist_wildcard_search Extension b acklist wildcard search does not only create output for the GUI of EMM OpenEMM but it implements feature extension point featurePlugin to provide additional functionality in the form of feature blacklist search This feature consists of a new tab Search blacklist in submenu Blacklist of menu Recipients When the new tab is selected the page shows a simple search box to enter the search expression The search expression permits the use of wildcards to indicate a single arbitrary character and to represent an arbitrary sequence of characters After the search butto
54. my feature Make sure to not use a permission token which is already taken by the core software of EMM OpenEMM or by an other extension To be on the safe side use the extension ID as prefix for your premission tokens Please note that a new permission token in the database requires a logout and a login to activate the change to the permission system O 2013 AGNITAS AG 27155 EMM OpenEMM Extension Development Guide 1 0 10 20140709 8 Creating extensions for BIRT based statistics EMM only While OpenEMM simply uses HTML tables to render statistics EMM uses the powerful BIRT framework to create more sophisticated statistics views like 3D pie charts To create a new BIRT based statistic you have to provide a report design file rptdesign and at least one dataset class which provides the values to be displayed within the report design If you want to create an extension enhancing the BIRT based statistics of EMM BIRT plugin you have to follow these guidelines 8 1 BIRT Extension Points and Permission Token To show the content of BIRT extensions in EMM its GUI was extended with additional sub tab Individual f permission statistic individual show is set for a certain EMM user he she will see this new sub tab in tab Statistics of menu Mailing Sub tab Individual lists links to all BIRT extensions for which the user owns the required permissions To allow BIRT extensions to register their code for sub tab Individual system e
55. n core point point name position gt g p plug p P P The first line should be in the header of the JSP and specifies the tag library so that the code for tag agn JspExtensionPoint can be located The second line must be placed in the JSP where the result of an extension should be included and it defines the extension the extension point belongs to usually core and the name of the point so that it can be addressed by an other extension If a JSP is processed to render the GUI tag agn JspExtensionPoint calls method public void invokeJspExtension String pluginName String extensionPointName PageContext pageContext of class ExtensionSystemimpl which forwards the call to method invoke extension pageContext of the gateway class registered for this extension point via the manifest file of an extension Method invoke can write content to the extension point directly with context getOut println Your output here Opposed to a feature extension point a setup method is not called by tag agn JspExtensionPoint since a GUI extension point is located within an existing page and there is no need to set up any navigation attributes A new GUI extension point for system extension core would be defined in its manifest file plugin xml in directory WEB INF system plugins core like this O 2013 AGNITAS AG 16 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 lt extension point id point name position gt lt para
56. n is pushed the blacklist is searched and the result is shown on a new page as a list of email addresses The files of extension blacklist_wildcard search are 1 Manifest file plugin xml provides configuration and dependency information of extension binds gateway class BlacklistWildcardSearchFeature to feature extension point featurePlugin implements navigation extension point tabs blacklist with content of navigation properties file blacklistSearchTabs 2 Messages properties file messages plugin properties and local versions provides messages which are needed by callback method setup of the gateway class and by the JSPs of the extension 3 Navigation properties file blacklistSearchTabs properties provides the navigation properties for new tab Search blacklist 4 Package org agnitas emm plugin blacklistwildcardsearch file BlacklistWildcardSearchFeature java implements callback method setup to set properties for the navigation sidebar the active submenu and the tabs menu extends AnnotateaDispatchingEmmFeatureExtension so that request parameter method defines the name of the method which is called instead of default invocation method nvoke provides method unspecifiedTarget which is called if request parameter method is not set this method forwards to method showForm provides method showForm which simply forwards to JSP blacklist search form jsp to request the search expression provides method search
57. new menu items or tabs with text and links encapsulated by permissions enhanced by method prepareNavigationDataFromExtensionPoints so that the class can not only read core navigation data from navigation properties files but also read navigation data from properties files of extensions uses method getPluginResourceBundle of class ExtensionSystemimpl to read navigation data from properties files of extensions permits more than one level of extensions with nested navigation extension points O 2013 AGNITAS AG 34 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 10 Documentation Requirements for Extensions If you want your self developed extension to be included in the public extension repository at SourceForge you should document it sufficiently These are the minimum requirements for acceptance to the extension repository Unique ID name version and description of extension manifest file required core version and extensions including their versions manifest file state of extension pre alpha alpha beta release candidate stable basic description of functionality incl screenshots with English language GUI name of original developer single person team or company including email address website of original developer software license OpenEMM uses CPAL 1 0 http opensource org licenses cpal 1 0 2013 AGNITAS AG 35 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709
58. nge Last change of password creation date Creation date of this record timestamp Date of last change for this record admin_group id ID of admin group gt admin group tbl admin group id preferred list size Default number of entries in lists default import profile id ID of default import profile gt import profile tbl id 12 5 bounce collect tbl Table description Temporary table used by softbounce processing script softbounce py to minimize queries to very big bounce tbl Column name Description mailtrack id ID of temporary record auto generated customer id ID of mail recipient gt customer 1 tbl customer id mailing id ID of mailing gt mailing tbl mailing id company id 1 status id Type of bounce 90 softbounce change date Date of last change for this record 12 6 bounce tbl Table description Contains all soft and hard bounces without any filtering Hard bounces are registered in the binding table as well Soft bounces are processed daily and entered into another table for further processing 400 other softbounce 420 problems with mailbox 430 problems with mailserver 500 irregular bounce 510 other hardbounce 511 unknown address 512 unknown domain very big table Column name Description bounce id ID of bounce auto generated customer id ID of mail recipient gt customer 1 tbl customer id mailing id ID of mailing gt mailing tbl mailing id company id 1 detai
59. nsionSystemimpl wraps the main functionality of the plugin framework JPF and provides all basic methods startup and shutdown of extension system initialize JPF framework PluginManager PluginRegistry etc activate system extensions install activate deactivate and remove extensions invoke extensions implementing GUI and feature extension points various getter and setter for subsystems of extension system Method getPluginResource of ExtensionSystemimpl uses classloaders of extensions to read resources like JARs and properties files because the extension classloaders know best where to find those resources and allow usage of different JAR file versions in different extensions 9 2 Program Flow When EMM OpenEMM is launched Tomcat parses its deployment descriptor web xm and starts listener ExtensionSystemlnitializationContextListener This listener initializes the extension system activates all system extensions core and core_navigation for now and activates all extensions marked as active in EMM OpenEMM database table plugins tbl column activate on startup 0 do not activate default 1 activate EMM OpenEMM uses MVC framework Struts to separate model and view and templating framework Tiles to render its GUI Normally you could safely ignore Struts and Tiles but in order to fully understand the program flow a few information are necessary Whenever an extension is needed URL path extension do is called Sometimes
60. nt to drop an existing column may only drop a single column or else it will be rejected by the validator 7 Make sure that no table name and no column name is longer than 30 characters in total otherwise Oracle will not accept it O 2013 AGNITAS AG 26 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 7 Working with Permissions Permission tokens are used in EMM OpenEMM to show or hide menu items features or sub features in its GUI In order to show an extension menu item or to show or hide a certain part of a feature the corresponding permission token has to be set in the database If you want a JSP to show the result of code if a certain permission token is set then use custom tag agn ShowByPermission like this lt agn ShowByPermission token dummy feature gt insert your code here lt agn ShowByPermission gt If you want a JSP to hide the result of code if a certain permission token is set use custom tag agn HideNavigation like this lt agn HideByPermission token dummy feature gt insert your code here lt agn HideByPermission gt To set the permission token in the EMM OpenEMM database globally 4 ist the default admin group use INSERT INTO admin group permission tbl admin group id security token VALUES 4 dummy feature And to set the permission token for an individual EMM OpenEMM user use INSERT INTO admin permission tbl admin id security token VALUES id of admin dum
61. oint footerto insert a support message in the footer of EMM OpenEMM Let s have a look at the files of hello world to find out how the extension works in detail 1 Manifest file plugin xml in the root directory of the extension ZIP file providing extension s name Hello World name of messages properties file messages plugin dependency info core because GUI extension point footer is needed path to resource and class files in ZIP file s bin directory classes binding of gateway class HelloWorldExtension to GUI extension point footer of system extension core o 2 Messages properties file messages plugin properties and local versions in directory bin classes of the extension ZIP file provides the message which is included in the footer of EMM OpenEMM s GUI 3 Package org agnitas emm plugin helloworld file HelloWorldExtension java in directory src of the extension ZIP file implements method invoke called by the GUI extension point footer inserts message in GUI footer via tag spExtensionPoint message is localized depending on the language of the current EMM OpenEMM user 5 2 Extension admin_info Extension admin_info is comparable to hello world but it inserts an output which is a little bit more elaborate admin info uses GUI extension point admin view pos2 of extension core to include a text box in JSP admin view jsp which shows the details of an EMM OpenEMM user account Extension ad
62. on some tables are split per company OpenEMM EMM cust ban tbl cust cid ban tb1 without field customer id customer 1 binding tbl customer cid binding tbl customer 1 tbl customer cid tbl mailtrack tbl mailtrack cid tbl onepixel log tbl onepixellog cid tbl rdir log tbl rdirlog cid tbl In case of EMM you have to insert the value of the company ID for expression cid to create the correct table name For instance if you want to read link click data for company_id 3 you have to query table rdirlog 3 tbl OpenEMM knows only company id 1 and uses table rdir log tbl if you want to work with blacklist table cust ban tbl be advised that for EMM this is a global table without column company id If you want to address the blacklist table of a certain company ID please use table cust cid ban tbl For company id 3 this would be table cust3 ban tbl Please also note that field change date in OpenEMM tables is called timestamp in EMM tables If you want to write extensions that work with both OpenEMM and EMM out of the box the best way is to check the software with methods sProjectEMM or isProjectOpenEMM of class Agnutils 6 2 SQL Statement Validation O 2013 AGNITAS AG 25 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 While the extension manager validates the SQL statements of a SQL file to be processed validation is not perfect of course and you should take care to write valid and safe SQL st
63. s of API classes and methods customer specific features do not have to be integrated into the software core when secondary features have to be refactored extended they can be sourced out to an extension keeping the core lean Advantages for users development time for customer specific features implemented as extensions will drop leading to lower costs extensions can be deployed at any time independently from release cycles of the software core users can develop their own extensions users can use extensions developed by third parties if the code of the whole extension system is open source like with EMM OpenEMM it makes comprehension of the extension interface even easier because it provides maxmimum transparency O 2013 AGNITAS AG 4155 EMM OpenEMM Extension Development Guide 1 0 10 20140709 2 Components of the EMM OpenEMM Extension Architecture The EMM OpenEMM extension architecture consist of five components Extension API Extension Points Extension Manager Extension Registry Extension Repository dei m Technically the extension architecture of EMM OpenEMM is based on the fabulous open source framework JPF Java Plugin Framework written by Dmitry Olshansky JPF was inspired by the plugin architecture of Eclipse 2 x before OSGi was introduced and we think that it is a pity that itis no longer maintained actively To learn more about JPF please visit http jpf sourceforge net for details We
64. s with a new Exporttab which provides the functionality to export the values of mailing comparision statistics as CSV files for further analysis You may filter the output written to the CSV file by several criterias type of mailing start date and end date for send time type of statistics values to be exported You can also define several settings for the CSV format like separator text recognition character and charset to be used To analyse the code of this extension have a look at the source code of the Java classes in directory src org agnitas emm plugin mailingstatisticsexport The structure of this extension is similiar to extension b acklist wildcard search but in contrast to the blacklist extension this extension spreads its code over three Java classes Class MailingStatisticsExportFeature is the gateway class of the extension and implements EMM OpenEMM s feature extension point featurePlugin It provides core methods selectProperties to choose the export data and doExport to execute the final export and to create the export file Class MailingStatisticsExportWorker implements a worker thread so that the retrieval of the export data from the database which may take a few minutes is executed as a separate thread Class MailingStatisticsExportDataProvider is the DAO class used to read the requested data from the database 5 5 Using the EMM OpenEMM API Gateway class BlacklistWildcardSearchFeature demonstrates nicel
65. t mailing id ID of mailing that generated hardbounce for user status 2 gt mailing tbl mailing id creation date Creation date of this record change date Date of last change for this record 12 14 customer 1 tbl Table description Contains profile information of recipients This table also holds all user generated columns see table customer field tbl Assignments to mailing lists are saved in customer 1 binding tbl Column name Description customer id ID of recipient email Email address firstname First name lastname Last name title Academic title or title of nobility gender Gender 0 male 1 2 female 2 2 unknown mailtype Mail type 0 plain text 1 HTML 2 inline HTML datasource_id Source for this record only written on insert gt datasource description tbl datasource id creation date Creation date of this record change date Date of last change for this record 12 15 customer field_tbl Table description Contains information on user generated columns fields in customer 1 tbl The combination of company id and col name is the unique ID of the described column Column name Description admin id ID of user gt admin tbl admin id company id 1 col name Name of the column field in customer 1 tbl shortname Name of column field in GUI description Description of column default value Default value for column field if no other value is provided mode insert Insert permission 0 read write
66. t timestamp for last sending of mailing 12 42 softbounce email tbl Table description Contains softbounce count for email addresses and is managed by softbounce processing script softbounce py Column name Description email email address of recipient mailing id ID of mailing gt mailing tbl mailing id company id 1 bnccnt count of softbounces generated by recipient creation date Creation date of this record change date Date of last change for this record 12 43 tag tbl Table description Contains definition of tags for mailing content like agnEMAIL simple or agnDB complex Column name Description tag id ID of tag auto generated company id 1 tagname Name of tag description Description of tag selectvalue Expression to be included in SQL statements which returns content for tag type Type of tag SIMPLE tag without parameters COMPLEX tag with parameters change date Date of last change for this record 12 44 timestamp tbl Table description Helper table to save timestamps from external scripts Used by softbounce processing to restart at that point in time where previous run had finished Column name Description O 2013 AGNITAS AG 50 55 EMM OpenEMM Extension Development Guide timestamp_id description cur prev 1 0 10 20140709 ID of timestamp purpose of timestamp current timestamp previous timestamp optional temptemporary timestamp optional 12 45 title gender tbl
67. te of mailinglist binding period 12 23 import_column_mapping_tbl Table description Contains mapping of columns in import files to database columns for import profiles Column name Description id profile_id file_column db_column mandatory default_value ID of auto generated ID of import profile gt import_profile_tbl id Name of column in import file name of column in customer 1 tbl Flag if column is required 0 2 no 1 yes Default value for column if no value is provided in import file 12 24 import gender mapping tbl Table description Contains mapping of text gender descriptions to numeric gender values for import profiles Column name Description id profile id int gender string gender 12 25 import log tbl Table description Logs import results Column name ID of auto generated ID of import profile gt import profile tbl id Numeric value of gender Alphanumeric value of gender Description log id admin id datasource id company id profile imported lines statistics records O 2013 AGNITAS AG ID of log record auto generated ID of admin user gt admin tbl admin id ID of datasource gt datasource description tbl datasource id 1 List of all parameters of selected import profile Number of imported records List of statistic information on import of existing records new duplicates errors etc 44 55 EMM OpenEMM Extension Deve
68. tension with its two callback methods setup and invoke Alternatively your gateway class may extend class AnnotateaDispatchingEmmFeatureExtension which implements interface EmmFeatureExtension and provides some boilerplate code and offers a convenient way to call different methods via request parameter method Annotation DispatchTarget is used to map certain method parameters to certain methods in the gateway class See demo extension blacklist wildcard search in section 5 3 for more information Of course an extension can offer more than one feature and therefore bind more than one gateway class to feature extension point featurePlugin O 2013 AGNITAS AG 19 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 5 Demo Extensions The best way to really understand how an extension works is to have a look at a real world example Right now three demo extensions exist for EMM OpenEMM hello_world admin info and blacklist_wildcard_search These extensions are quite simple because their purpose is to demonstrate how extensions work using the three types of extension points and the API of EMM OpenEMM The extensions are available as ZIP files for download at SourceForge https sourceforge net projects openemm files OpenEMM 20development 5 1 Extension hello_world Extension hello world extension is aside from system extensions core and core navigation the most simple form of an extension This extension uses GUI extension p
69. thod include spFragment creates a RequestDispatcher as wrapper for the target JSP and uses its include method to insert the target JSP into the response object by adding it to the out buffer of type SPWriter public void includeJspFragment String relativeUrl throws IOException ServletException request getRequestDispatcher plugins this pluginId relativeUrl include request response O 2013 AGNITAS AG 31 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 This allows the target JSP to access and display request attributes set by the extension 9 3 Main Components of the Extension Architecture Libraries JPF JAR files jpf jar jpf boot jar jpf tools jar and jxp jar Listener ExtensionSystemlnitializationContextListener Initializes the extension system and activates all system extensions at launch time of EMM OpenEMM Package org agnitas emm extension impl AnnotateaDispatchingEmmFeatureExtension Implements EmmFeatureExtension provides default method for invoke which uses name of request parameter method to call final invocation method DatabaseScriptExecutor Parses validates and executes SQL script of extension to extend DB schema and or DB content entry point for parsing class SimpleSqlParser in package org agnitas emm extension sglparser EmmFeatureExtension Interface to be implemented by gateway class of extension setup sets navigation par
70. time 300 uid_version 2013 AGNITAS AG 1 Creation date of this record seed value for stronger link encryption if you set change mails will no longer work default Date of last change for this record Email address receiving note for every data export default FQDN for redirect link processing server default FQDN for mailloop processing server default which results in 1 enabled gt for every mailing every recipient s customer id is mailtrack_tbl maximum number of failed loging default 3 number of seconds login is blocked after too many fails default version of link encryption default NULL do not change 39 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 max_recipients maximum number of recipients which is processed to display recipient list for GUI default 10 000 12 10 component tbl Table description Contains content components of mailings big table Column name Description component id ID of component auto generated mailing id ID of mailing gt mailing tbl mailing id target id ID of target group expression gt dyn target tbl target id company id 1 compname Name of component reserved names start with agn agnText agnHtml etc description Description of component comptype Type of component 0 text 1 external image 3 attachment 5 embedded image mtype MIME type of component text plain text html image gif image png etc binb
71. ure applicationContext request response Class ExtensionSystemimpl looks up the requested extension retrieves its pluginContext object and calls callback method setup of this extension featureExtension setup pluginContext extension context The task and the implementation of this method have been explained in section 3 3 1 in detail After servlet ExtensionSetupServiet has rendered the application frame servlet ExtensionServlet retrieves the value of request parameter feature as well and calls method invokeFeatureExtension of class ExtensionSystemimpl extensionSystem invokeFeatureExtension feature applicationContext request response Again class ExtensionSystemimpl looks up the requested extension retrieves its pluginContext object but this time calls callback method nvoke of this extension with featureExtension invoke pluginContext extension context to render the application content with the output of the extension section 4 3 and 5 3 explain in detail how to implement method nvoke To include the output of an extension into a JSP first the output has to be written to attributes of the current request Second class PluginContextimp which implements interface PluginContext provides method include spFragment which may be used like this pluginContext includeJspFragment dummy feature result jsp To include a JSP into the current response so that it can read the request attributes me
72. us 10 successful 20 failed 40 successful during blocking time creation date Creation date of this record 12 28 maildrop status tbl Table description When a normal mailing is sent or when a date based or action based mailing is activated a new record is created for this table The information is used by the backend to build and process the mailing Column name Description status id ID of mailing status auto generated mailing id ID of mailing gt mailing tbl mailing id company id 1 gendate Start time and date for generation of mailing O 2013 AGNITAS AG 45 1 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 senddate Start time and date for sending of mailing blocksize Number of recipients per XML data block step Time span in minutes between sending of consecutive XML data blocks genstatus Status of mailing generation 0 generation is planned for a date in the future 1 generation can be started now 2 generation of mailing in progress 3 generation of mailing is finished genchange Timestamp of last change to field genstatus status_field Type of mailing A admin T test W world normal E event based R rule based date based 12 29 mailing_account_tbl Table description While sending a mailing for every sent block a record with the number size and type of block is written Column name Description mailing_account_id ID of mailing account entry auto generated mailing_
73. vendor and dependency information taken from the extension registry In the detail view a extension can be activated deactivated and removed Via tab Upload new extensions can be uploaded from the file system 2 4 Extension Registry The extension registry is the central storage where the extension manager registers and unregisters extensions The extension registry holds the necessary configuration data from all installed extensions and their manifest files like version info extension points entries for extension points etc 2 5 Extension Repository O 2013 AGNITAS AG 6 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 We plan to offer an extension folder in the OpenEMM project at SourceForge https sourceforge net projects openemm files where public extensions will be available for download O 2013 AGNITAS AG 7 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 3 Components of an EMM OpenEMM Extension A typical extension for EMM OpenEMM consists of e a manifest file plugin xml in XML format holding configuration data to store in the extension registry like version info extension points entries for extension points etc resource files like property files for messages navigation etc Java classes with program code of an extension usually service layer classes DAO layer classes and third party JARs e JSPs to implement the GUI of an extension sometimes accompanied with files for Jav
74. which is the case initially method unspecifiedTarget is called as fallback which in return calls method showForm showForm simply forwards to JSP blacklist search form jsp to request the search expression pluginContext includeJspFragment blacklist search form jsp blacklist search form jsp shows a form so tha the user can enter the search expression If the submit button of the form is pushed link extension do is called with with hidden request parameter feature blacklist wildcard search and method search lt input type hidden name feature value blacklist wildcard search gt lt input type hidden name method value search gt Request parameter feature specifies the ID of the implementation for feature extension point featurePlugin and parameter method defines via DispatchTarget the name of gateway class method to be invoked The search method of gateway class BlacklistWildcardSearchFeature uses the search expression to search the blacklist and returns the search result via request attribute resu tList to JSP blacklist search result jsp pluginContext includeJspFragment blacklist search result jsp 5 4 Extension mailing statistics export O 2013 AGNITAS AG 22 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Extension mailing statistics export is not a simple demo extension but it provides a very useful feature This extension enhances submenu Comparision of EMM OpenEMM menu Statistic
75. which is triggered by the search button of JSP b acklist search form jsp and returns the search result via request attribute resultList to JSP blacklist search result jsp 5 JSP blacklist search form jsp shows form to enter search expression submit button calls generic extension URL with hidden request parameter feature blacklist wildcard search specifies the ID of the feature extension point O 2013 AGNITAS AG 21 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 implementation to be called and method search name of gateway class method to be invoked 6 JSP blacklist search result jsp lists all search result with the help of third party tag display 5 3 1 Program Flow of Extension To better understand how extension b acklist wildcard search works a more detailed description of the program flow follows Iftab Search blacklist is clicked link extension do feature blacklist wildcard search is called In the end target extension do is mapped to callback methods setup and invoke of gateway class BlacklistWildcardSearchFeature see section 8 2 for mapping details Since BlacklistWildcardSearchFeature extends class AnnotateaDispatchingEmmFeatureExtension the value of request parameter method defines the method to be called Annotation DispatchTarget is used to map certain method parameters to certain methods in the gateway class DispatchTarget name show form If method has no value
76. xtension emm core provides special extension point birt statistics mailing If a BIRT extension registers at this extension point the output of this extension will be shown at sub tab Individual Extension point birt statistics mailing uses these three parameters titlekey message key for title of extension its value must be listed in message properties file see section 3 2 1 for details reportdesign name of file providing the BIRT report design rptdesign permissions list of permission token needed to display a link to the BIRT extension in sub tab Individual see chapter 7 for details on permission token 8 2 BIRT Extension ZIP File For BIRT related files use these directories birt rptdesign report design files rptdesign birt scriptlib JAR file s with dataset classes for new report naming convention to prevent name collisions birt plugin pluginld jar 8 3 BIRT Configuration To make sure that the extension manager knows where to put the BIRT related files configuration file emm properties of EMM has to define thes following properties birt plugin directory directory of BIRT server where the extension ZIP files will be copied to birt host user user name to access BIRT server via SSH scp i e BIRT server needs a user of this name without password On the BIRT server side file emm reporting properties needs this property plugins home directory outside of webapps directory to survive updates of BIRT software wh
77. y how to use the API of EMM OpenEMM The header of the class shows which classes of OpenEMM are imported EMM includes all OpenEMM classes import org agnitas beans Admin import org agnitas beans BlackListEntry import org agnitas dao BlacklistDao import org agnitas util AgnUtils import org springframework context ApplicationContext Method getAdmin of class AgnUtils is used to get the data of the current EMM OpenEMM user which is then stored in bean Admin Admin admin AgnUtils getAdmin request The Spring web application context is used to retrieve the implementation of DAO class BlacklistDao BlacklistDao blacklistDao BlacklistDao context getBean BlacklistDao Side note Using the Spring context instead of creating the instance directly is always recommended because EMM might use a different class than OpenEMM This is the case here because of differences in the database schema between EMM and OpenEMM see chapter 6 2013 AGNITAS AG 23 55 EMM OpenEMM Extension Development Guide 1 0 10 20140709 Method getBlacklistedRecipients of BlacklistDao is used to access the blacklist of the company of the current user from the database and the returned entries are stored in a list of type BlacklistEntry List lt BlackListEntry gt list List lt BlackListEntry gt blacklistDao getBlacklistedRecipients admin getCompanyID getList O 2013 AGNITAS AG

AGNITAS EMM/OpenEMM Extension Development Guide Table of

Contents

Download Pdf Manuals

Related Search

Related Contents