JEMH Installation for Jira 3.9.2 - Jira 3.13.x

JEMH Installation

1. 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
2. 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
3. Setup Logging (optional)
   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.dolby.atlassian.jira.service.util.handler=DEBUG, EMHFileLog
   log4j.additivity.com.dolby.atlassian.jira.service.util.handler=false
   
   log4j.logger.com.dolby.atlassian.jira.service.util.handler.emh=DEBUG, EMHFileLog
   log4j.additivity.com.dolby.atlassian.jira.service.util.handler.emh=false
   
   log4j.logger.com.dolby.atlassian.jira.service.util.handler.emh.processor=DEBUG, EMHFileLog
   log4j.additivity.com.dolby.atlassian.jira.service.util.handler.emh.processor=false
   
   log4j.logger.com.dolby.atlassian.jira.service.util.handler.emh.service=DEBUG, EMHFileLog
   log4j.additivity.com.dolby.atlassian.jira.service.util.handler.emh.service=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.dolby.atlassian.jira.service.util.handler.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:
   null
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.

Some example properties are:

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

Service Properties:
null
Service listing after save:
null

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.
as of 0.7, all 'default' fields are prefixed with default, eg defaultPriority etc. for clarity.
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 javaapplication 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.dolby.atlassian.jira.service.util.handler.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)

After configuring you should see something like:

Poker Sequence Diagram