JEMH Installation for Jira 4.x

Before you begin

Some basics

JEMH is not a plugin (yet), it is invoked by a POP or IMAP Service that you have to create, it is not a 'Service' and cannot be installed (will result in not a Jira Service exceptions...). Also, until your mail-server and POP settings are correct, JEMH will do not a lot, JEMH processes mail after its been retrieved by the relevant service.

See below for details on where the config file goes, and how you tell JEMH where it is and what its called.

Configuration Options

You can add handler options through the Jira Service UI, if provided they will override the settings in the config file. Settings applicable to the standard CreateComment handler have been found wanting and are not applicable to JEMH, dont make assumptions, consult the JEMH Usage Guide for detailed information on Configuration Options. Settings that are used should be comma delimited, no spaces.

The Configuration file

The Example configuration file is a starting point, understand what options are applicable or not to your setup.

If you run into trouble

Simplify your config file, try alternate cases. The issue that seems to be biting at the moment is Outlook 2007 HTML mail not being processed correctly, try workarounds e.g. plain text, to get a better feel for the problem before reporting 'it doesn't work'. I'm happy to help on an ad-hoc basis through http://www.getsatisfaction.com/javahollic, if you need hands on support, contact me by email.

JEMH Installation

Add the JEMH JAR

Get the JAR specific for your version of Jira from the top of the page and copy to the Jira WEB-INF/lib folder

Add the ldaputils jar (if you use ldap)

Get the latest ldaputils jar (currently 1.0.13) from the LDAP Util library page, take the example-ldaputil.properties file from the JAR and rename it ldaputil.properties, editing it as appropriate

Setup Logging (optional)

JEMH

Modify / copy-and-modify the WEB-INF/classes/log4j.properties , this will enable logging of all EMH messages to a separate file. Default is DEBUG, other values are 'INFO', 'WARN' and 'ERROR'.

#
# Create a separate appender
#
log4j.appender.EMHFileLog=org.apache.log4j.RollingFileAppender
log4j.appender.EMHFileLog.File=atlassian-jira-emh.log
log4j.appender.EMHFileLog.MaxFileSize=20480KB
log4j.appender.EMHFileLog.MaxBackupIndex=5
log4j.appender.EMHFileLog.layout=org.apache.log4j.PatternLayout
log4j.appender.EMHFileLog.layout.ConversionPattern=%d %t %p [%c{4}] %m%n
log4j.appender.EMHFileLog.Threshold=DEBUG

#
# add entries for the three EMH packages
#
log4j.logger.com.javahollic.jira.emh.service=DEBUG, EMHFileLog
log4j.additivity.com.javahollic.jira.emh.service=false

log4j.logger.com.javahollic.jira.emh.engine=DEBUG, EMHFileLog
log4j.additivity.com.javahollic.jira.emh.engine=false

log4j.logger.com.javahollic.jira.emh.processor=DEBUG, EMHFileLog
log4j.additivity.com.javahollic.jira.emh.processor=false

JIMI

JIMI is in development and doesnt do anything useful yet, just updating docs for my own use

#---------------------------------------
#
# Create a separate appender
#
log4j.appender.JIMIFileLog=org.apache.log4j.RollingFileAppender
log4j.appender.JIMIFileLog.File=atlassian-jira-jimi.log
log4j.appender.JIMIFileLog.MaxFileSize=20480KB
log4j.appender.JIMIFileLog.MaxBackupIndex=5
log4j.appender.JIMIFileLog.layout=org.apache.log4j.PatternLayout
log4j.appender.JIMIFileLog.layout.ConversionPattern=%d %t %p [%c{4}] %m%n
log4j.appender.JIMIFileLog.Threshold=DEBUG

log4j.logger.com.javahollic.jira.im=DEBUG, JIMIFileLog
log4j.additivity.com.javahollic.jira.im=false

log4j.logger.com.javahollic.im.bot=DEBUG, JIMIFileLog
log4j.additivity.com.javahollic.im.bot=false

log4j.logger.com.javahollic.im.transport=DEBUG, JIMIFileLog
log4j.additivity.com.javahollic.im.transport=false

Enabling detailed logging of lower level mail operations in Jira is covered in Logging email protocol details.

1. Make Jira aware of the new handler

   POP / Imap?

   This example shows how to setup with POP, Imap is equally possible, just not documented, to use Imap, reconfigure Dovecot, and instead of modifying .../pop/popservice.xml modify .../imap/imapservice.xml.

   Update WEB-INF/classes/services/com/atlassian/jira/service/services/pop/popservice.xml to include:

   <value>
     <key>com.javahollic.jira.emh.service.CreateOrCommentHandler</key>
     <value>Extendable Mail Handler - CreateOrComment</value>
   </value>
   

2. Ensure a valid POP Sever is configured
   This is under Global Settings/Mail Servers. If the virtual mailbox approach is used, only one mailbox needs to be setup, in the example shared@jira.myco.net:
   
3. Configure the handler
   Modifiy the two properties files. when done, they should be copied to WEB-INF/classes:
   If you use ldap, the minimum config required is to identify a valid user which is used to validate ldap connections. If not, you don't need this file.
   The EMH config file is just an extension of the properties that a mail handler is given, anything you could put in the Jira UI, you can equally add here. Look at the settings, understand what they do, make changes as appropriate for your needs.
   The contents of the configuration file changes as new features are added and refinements are made, check the 'example-emh.properties' available inside every JAR.

projectAutoAssign=true,issuetype=3,configFile=emh.properties

1. Restart Jira

JEMH Handler Configuration File

The following sections describe the fields that can be used to configure JEMH. Organised by where they are used, in future I will try to expand on the documentation and provide more detailed examples.
An example configuration file is packaged in every JAR, called 'example-emh.properties', contrast this file to your local file for changes.

CommentHandler

AbstractFieldProcessor

JEMH Poker Installation

This JEMH Poker is a simple java application that triggers the JEMH to do an immediate mail retrieval. The current 1.0 release of the JEMH Poker contains a simple file monitor, suitable for most Unix or Linux platforms and associated file-based mail systems. Exchange is an unknown quantity, as Microsoft products are not known for their openness - the approach I took in my organization was to use Exchange purely as a vehicle to get mail to where I could do something useful with it (see setting up Postfix smtp server and Dovecot POP server pages here).

Installation of the remote agent

1. Extract the tgz in /usr/local

   cd /usr/local
   tar xzf filename.tgz
   

2. Make the launch shell script executable

   cd jemh-mail-notifier-......
   chmod +x *.sh
   

3. Link a common name to the current version

   ln -s jemh-mail-notifier-...... jemh-mail-notifier
   

4. Ensure you have Java in your path, the following should give some version information. If not, install Java 1.5+ or modify the script (you should know what to do)

   java -version
   

5. Edit the configuration file emh-poker.properties, set the server (IP address or DNS name) and the port (default is 7777).
6. Run the script as the appropriate user for your environemnt. With Postfix, you may need to be running as Postfix. Running as root is to be avoided, create a service user as follows:

   root@server:/usr/local/jemh-mail-notifier-1.1-SNAPSHOT# adduser --disabled-login --no-create-home -ingroup postfix jirapoker
   Adding user `jirapoker' ...
   Adding new user `jirapoker' (1009) with group `postfix' ...
   Not creating home directory `/home/jirapoker'.
   Changing the user information for jirapoker
   Enter the new value, or press ENTER for the default
   	Full Name []: 
   	Room Number []: 
   	Work Phone []: 
   	Home Phone []: 
   	Other []: 
   Is the information correct? [Y/n] Y
   

Create a SysV startup script in /etc/init.d

Create it as 'jemh-mail-notifier'

#! /bin/sh
### BEGIN INIT INFO
# Provides:          jemh-mail-notifier
# Required-Start:    
# Required-Stop:
# Default-Start:     2
# Default-Stop:
# Short-Description: Monitors a mailbox and poke jira when mail arrives
### END INIT INFO

PATH=/sbin:/bin

. /lib/lsb/init-functions

case "$1" in
  start)
	cd  /usr/local/jemh-mail-notifier
	./run.sh &
	;;
  stop)
	# No-op
        echo Cant stop it from here, use 'ps -ef | grep java' at the prompt
	;;
  *)
	echo "Usage: $0 start" >&2
	exit 3
	;;
esac

To make the service start at bootup:

sudo apt-get install sysvconfig
sysvconfig

Now find the jemh-mail-notifer and enable for startup, click finish to save.

Installing the Jira JEMH Poker Service

The main JEMH includes everything necessary, the only thing that's required is a bit of configuration:

1. Login to Jira as admin
2. Go to the Services screen
3. Add a service:

   Name	JEMH Poker Service
   Class	com.javahollic.jira.emh.service.EMHPokerService
   Delay	1 note: this is essentially the delay in initial startup as Jira starts

4. Select the default port options or change as you see fit (must fix Poker configuration, above)

Installing JIMI

See JIMI Installation for more details. Once installed, as a system admin, after setting up all JEMH components you should see something like:

Login ID's

Different providers require different forms of XMPP_LOGIN. Here is whats known: