|
|
 |
A service is a class that runs periodically within JIRA. Since a service runs inside JIRA, it has the ability to
use all of the JIRA API
— and, as it is written in Java, it can use any Java libraries.
Services are useful because they enable you to integrate with external systems by pulling data into JIRA
periodically. JIRA comes with a number of pre-written services, and custom services can be written and
plugged in at runtime. If you want a service to perform typical operations on JIRA issues (eg. close a list of
issues meeting certain criteria), then the Jelly Service can be configured to run a custom Jelly script.
Registering a Service
Services are set up as follows.
- For custom-written services, make sure your service class is in the classpath where JIRA can see it
— the best locations are usually the WEB-INF/classes or WEB-INF/lib
(as a JAR) directories within the JIRA web application.
- Log in as a user with the 'JIRA System Administrators' global permission.
-
Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the
Administration box on the dashboard:
 
- Under the 'System' sub-menu on the left, click the 'Services'
link.
- Fill out the Add Service form with the following parameters:
- Name
- a descriptive name for this service
- Class
- the fully qualified class of your service. Will likely be of the form
com.atlassian.jira.service.services.type.TypeService. See Sample services for provided service class names.
- Delay
- the delay (in minutes) between service runs
For example, adding a POP Service:
Now click Add Service
-
This will bring up the 'Edit Service' screen to configure the service. Depending on the service, you may now
be required to specify a MessageHandler, a helper class that processes email
messages. MessageHandlers are configured with a parameter string, a comma-separated list of
name=value pairs. Consult the tables below as to what parameters
each MessageHandler accepts.
The following screenshot shows a CreateIssueHandler being attached to a POP Service:
Editing Service Properties
At any time you can edit a service's properties by clicking Edit for that service in the
Services section of the Administration tab.
Mail Service Properties
In addition to Message Handlers, the mail services POP Service and IMAP Service can be further configured with further properties on
how the mail is found and handled.
-
Forward Emails
-
If the mail service is unable to handle a message you can define an email address to forward these messages to. Just add the desired email address into the
'ForwardEmail' textbox.
Note
You will need to configure a SMTP mail server before this functionality can be used.
-
SSL
-
The mail service can be configured to connect to the email server using an SSL connection. To do this select the appropriate SSL connection in the
'Use SSL' select list. If you do not want JIRA to use SSL, select 'No SSL'.
If you are using SSL, you will need to preload the IMAPS/POPS server's public key in JIRA (actually, the Java
virtual machine running JIRA). See Connecting to SSL Services for information on
how to do this.
-
Folder (IMAP Only)
-
For the IMAP Service it is possible to specify the folder you wish JIRA to read when scanning for messages. To do this, add the desired folder name to the
'Folder' field.
Note
If a folder is not specified the mail service will default to 'INBOX'.
Removing a Service
To remove a service, click Del for that service in the Services section of
the Administration tab.
Built-in Services
JIRA has some useful services out the box, which may be used as-is or modified for use in your own environment.
The source of all built-in services is available and should give you good overview of how simple it is to write your own
services. All built-in services are included with JIRA, and need only be configured to be used.
-
Export Service (source)
-
The Export Service is useful for periodically backing up JIRA. It exports all data from JIRA every time it
is run into a directory supplied as a parameter. The export files are timestamped, thus the service can act as a backup
system.
To test this service, add a service with the class
com.atlassian.jira.service.services.export.ExportService. JIRA sets up an ExportService during the setup wizard, so you may find you already have one.
-
POP Service (source)
-
The POP service reads messages from a defined POP3 mail box, and then performs operations within JIRA based
on the message contents. A MessageHandler (see below for more information) is configured for each instance of the POP
Service, which determines how the message is handled.
To test this service, add a service with the class
com.atlassian.jira.service.services.pop.PopService and configure the POP details and message
handler in the properties of the service.
To make the POP service even more useful, you can connect it with the email
notifications sent by JIRA. Simply set the FROM address in the MailListener to be the
same address as the POP mailbox being monitored. This allows you to do things like reply to email
notifications and have your replies added as comments on the issue.
-
IMAP Service (source)
-
Similar to POP service, except that it reads from an IMAP mailbox's "INBOX" instead. Like the POP
service, it removes emails after reading.
To test this service, add a service with the class
com.atlassian.jira.service.services.imap.ImapService and configure the IMAP details and message
handler in the properties of the service.
-
File Service (source)
-
The File service is very much like the POP service above, except that instead of reading emails from a POP
mailbox, they are read from a directory on disk. This is useful because you do not need an anonymous POP
mail box (which could be a potential security risk) to use it. Instead you can simply get your mail server
to dump incoming email messages into a particular directory, which the File service scans periodically.
The setup of this service is identical to the POP Service above, except that the service class is
com.atlassian.jira.service.services.file.FileService and the service is configured with the
directory to watch instead of the POP mailbox details. Both File and POP services can use the same
MessageHandlers.
-
Jelly Service (source)
-
Jelly is a scripting language which allows tasks in JIRA to be automated. The
Jelly Service periodically runs a Jelly script. For example, you could use this to periodically run a
search request, loop through the results and add a comment, change the issue state (see the Jelly examples. If you're considering writing a custom service, often a
periodically invoked Jelly script may be an easier alternative.
JIRA Service classes must all extend com.atlassian.jira.service.JiraService.
Most do so by extending com.atlassian.jira.service.AbstractService or some
more specialised subclass.
Message Handlers
POPService, IMAPService and FileService above use MessageHandlers (API doc) to
perform operations within JIRA based on the format of incoming email messages.
You can design your own MessageHandlers to integrate JIRA with your own processes, and plug them into any of
these three services via the Administration interface. (Please also see Adding
your own email handling classes.)
MessageHandlers are configured with a comma-separated list of name-value pairs, known as the handler
parameters.
There are a number of default message handlers that ship with JIRA, described below:
CreateIssueHandler
com.atlassian.jira.service.util.handler.CreateIssueHandler |
API doc |
Source
This message handler creates a new issue for each incoming message.
CreateIssueHandler parameters
| Parameter | Meaning | Value |
| project | Default project where new issues are created. | Project key, e.g.
JRA |
| issuetype |
Default type for new issues. |
Integer representing issue type:
- Bug
- New Feature
- Task
- Improvement
|
| reporterusername |
Username of default reporter, if sender not recognised. |
JIRA username, e.g. admin |
| createusers |
If a message comes from unrecognised address, create a new JIRA user
with the user name and email address set to the 'From' address of
the message. The password for the new user is randomly generated,
and an email is sent to the new user informing them about their
new account in JIRA.
Note: this parameter is not compatible with
reporterusername. If
createusers is set to true, and the
reporterusername is also
supplied, users will be created if they cannot be found using the
from addresses of the received messages. That is, the
reporterusername will be ignored.
By default (if not supplied), createusers is set to false.
|
true or false |
| notifyusers |
This parameter is only used if createusers is set to true. If notifyusers
is set to false they will not receive a notification that their account has been created via email. The
default value is true to preserve the behaviour before this parameter was added.
By default (if not supplied), notifyusers is set to true.
|
true or false |
| catchemail |
If set, only emails to the specified recipient (To:, Cc:) are processed. |
E.g. issues@mycompany.com |
| ccassignee |
If an email has a Cc address listing an assignable user already present in JIRA, by default JIRA will
assign the issue to that user. In JIRA 3.1 and above, if you do not want this
behaviour, set ccassignee to false.
By default (if not supplied), ccassignee is set to true.
|
true or false |
| bulk |
This option only affects emails with the header 'Precedence' set to 'bulk', performing an action depending on its value as follows:
-
ignore - Ignore the email and do nothing
-
forward - Forward the email to the address set in the "Forward Email" text field
-
delete - Delete the email permanently
Any other values are invalid, and the handler will perform normally.
|
ignore or forward or delete |
CreateOrCommentHandler
com.atlassian.jira.service.util.handler.CreateOrCommentHandler |
API doc |
Source
This message handler creates a new issue, or adds a comment to an existing issue. If the subject contains
an issue key, the message is added as a comment to that issue. If no issue key is found, a new issue is
created in the default project.
CreateOrCommentHandler parameters
| Parameter | Meaning | Value |
| project | Default project where new issues are created. | Project key, e.g.
JRA |
| issuetype |
Default type for new issues. |
Integer representing issue type:
- Bug
- New Feature
- Task
- Improvement
|
| stripquotes |
If set (to anything), quoted text is removed from comments. |
(anything) |
| reporterusername |
Username of default reporter, if sender not recognised. |
JIRA username, e.g. admin |
| createusers |
If a message comes from unrecognised address, create a new JIRA user
with the user name and email address set to the 'From' address of
the message. The password for the new user is randomly generated,
and an email is sent to the new user informing them about their
new account in JIRA.
Note: this parameter is not compatible with
reporterusername. If
createusers is set to true, and the
reporterusername is also
supplied, users will be created if they cannot be found using the
from addresses of the received messages. That is, the
reporterusername will be ignored.
By default (if not supplied), createusers is set to false.
|
true or false |
| notifyusers |
This parameter is only used if createusers is set to true. If notifyusers
is set to false they will not receive a notification that their account has been created via email. The
default value is true to preserve the behaviour before this parameter was added.
By default (if not supplied), notifyusers is set to true.
|
true or false |
| catchemail |
If set, only emails to the specified recipient (To:, Cc:, Bcc:) are processed. |
E.g. issues@mycompany.com |
| ccassignee |
If an email has a Cc address listing an assignable user already present in JIRA, by default JIRA will
assign the issue to that user. In JIRA 3.1 and above, if you do not want this
behaviour, set ccassignee to false.
By default (if not supplied), ccassignee is set to true.
|
true or false |
| bulk |
This option only effects email's with the header "Precedence" set to "bulk", performing an action depending on its value as follows:
-
ignore - Ignore the email and do nothing
-
forward - Forward the email to the address set in the "Forward Email" text field
-
delete - Delete the email permanently
Any other value's are invalid, and the handler will perform normally.
|
ignore or forward or delete |
FullCommentHandler
com.atlassian.jira.service.util.handler.FullCommentHandler |
API doc |
Source
This message handler creates a comment based on the entire body of the email received.
The issue to use is chosen from the first issue key found in the email subject. The author of the comment
is taken from the from address of the email.
FullCommentHandler parameters
| Parameter | Meaning | Value |
| reporterusername |
Username of default reporter, if sender not recognised. |
JIRA username, e.g. admin |
| createusers |
If a message comes from unrecognised address, create a new JIRA user
with the user name and email address set to the 'From' address of
the message. The password for the new user is randomly generated,
and an email is sent to the new user informing them about their
new account in JIRA.
Note: this parameter is not compatible with
reporterusername. If
createusers is set to true, and the
reporterusername is also
supplied, users will be created if they cannot be found using the
from addresses of the received messages. That is, the
reporterusername will be ignored.
By default (if not supplied), createusers is set to false.
|
true or false |
| notifyusers |
This parameter is only used if createusers is set to true. If notifyusers
is set to false they will not receive a notification that their account has been created via email. The
default value is true to preserve the behaviour before this parameter was added.
By default (if not supplied), notifyusers is set to true.
|
true or false |
| catchemail |
If set, only emails to the specified recipient (To:, Cc:, Bcc:) are processed. |
E.g. issues@mycompany.com |
| bulk |
This option only effects email's with the header "Precedence" set to "bulk", performing an action depending on its value as follows:
-
ignore - Ignore the email and do nothing
-
forward - Forward the email to the address set in the "Forward Email" text field
-
delete - Delete the email permanently
Any other value's are invalid, and the handler will perform normally.
|
ignore or forward or delete |
NonQuotedCommentHandler
com.atlassian.jira.service.util.handler.NonQuotedCommentHandler |
API doc |
Source
This message handler also creates a comment, but only uses the "non quoted" lines of the email
body. A quoted line is any line that starts with">" or "|".
The issue to use is chosen from the first issue key found in the email subject. The author of the comment
is taken from the from address of the email.
NonQuotedCommentHandler parameters
| Parameter | Meaning | Value |
| reporterusername |
Username of default reporter, if sender not recognised. |
JIRA username, e.g. admin |
| createusers |
If a message comes from unrecognised address, create a new JIRA user
with the user name and email address set to the 'From' address of
the message. The password for the new user is randomly generated,
and an email is sent to the new user informing them about their
new account in JIRA.
Note: this parameter is not compatible with
reporterusername. If
createusers is set to true, and the
reporterusername is also
supplied, users will be created if they cannot be found using the
from addresses of the received messages. That is, the
reporterusername will be ignored.
By default (if not supplied), createusers is set to false.
|
true or false |
| notifyusers |
This parameter is only used if createusers is set to true. If notifyusers
is set to false they will not receive a notification that their account has been created via email. The
default value is true to preserve the behaviour before this parameter was added.
By default (if not supplied), notifyusers is set to true.
|
true or false |
| catchemail |
If set, only emails to the specified recipient (To:, Cc:, Bcc:) are processed. |
E.g. issues@mycompany.com |
| bulk |
This option only effects email's with the header "Precedence" set to "bulk", performing an action depending on its value as follows:
-
ignore - Ignore the email and do nothing
-
forward - Forward the email to the address set in the "Forward Email" text field
-
delete - Delete the email permanently
Any other value's are invalid, and the handler will perform normally.
|
ignore or forward or delete |
RegexCommentHandler
com.atlassian.jira.service.util.handler.RegexCommentHandler |
API doc |
Source
This message handler creates a comment from an email body - but ignores any part of the email body past a specified marker or separator.
For mail systems like Lotus Notes and Outlook, emails are separated from the quoted email by some predictable text like "---- Original Message ----" or "Extranet\n email.address/DOM/REG/CONT/CORP@CORPMAIL"
The RegexCommentHandler can take any valid regular expression — and in fact filter quoted mails from various different mail systems simultaneously.
- If the pattern is found, it returns the text before the 1st match - and discards the rest of the email body
- If the pattern is not found, it returns the email body unchanged
- If the regex is not specified, it returns the email body unchanged
- If there is any error (i.e. regex expression error), it returns the email body unchanged
RegexCommentHandler parameters
| Parameter | Meaning | Value |
| reporterusername |
Username of default reporter, if sender not recognised. |
JIRA username, e.g. admin |
| createusers |
If a message comes from unrecognised address, create a new JIRA user
with the user name and email address set to the 'From' address of
the message. The password for the new user is randomly generated,
and an email is sent to the new user informing them about their
new account in JIRA.
Note: this parameter is not compatible with
reporterusername. If
createusers is set to true, and the
reporterusername is also
supplied, users will be created if they cannot be found using the
from addresses of the received messages. That is, the
reporterusername will be ignored.
By default (if not supplied), createusers is set to false.
|
true or false |
| notifyusers |
This parameter is only used if createusers is set to true. If notifyusers
is set to false they will not receive a notification that their account has been created via email. The
default value is true to preserve the behaviour before this parameter was added.
By default (if not supplied), notifyusers is set to true.
|
true or false |
| catchemail |
If set, only emails to the specified recipient (To:, Cc:, Bcc:) are processed. |
E.g. issues@mycompany.com |
| splitregex |
Regular expression matching the text separating the mail from any previous mails. Note that the
regexp must begin and end with a delimiter character, typically '/'.. Also note that
currently, commas are not allowed in regexps, as commas are used to separate handler parameters and
there is not (as yet) an escape syntax. |
E.g. /----\s*Original Message\s*----/ or /_____________*/ |
| bulk |
This option only effects email's with the header "Precedence" set to "bulk", performing an action depending on its value as follows:
-
ignore - Ignore the email and do nothing
-
forward - Forward the email to the address set in the "Forward Email" text field
-
delete - Delete the email permanently
Any other value's are invalid, and the handler will perform normally.
|
ignore or forward or delete |
CVSLogHandler
com.atlassian.jira.service.util.handler.CVSLogHandler |
API doc |
Source
This message handler parses CVS Log messages and adds the relevant sections as a comment.
The comment is added to any issue whose key is mentioned in the CVS commit message.
For instance if you commit to CVS with the message "This commit fixes JRA-57 and
JRA-58.", a comment will be added to issues JRA-57 and JRA-58.
The body of the comment includes the commit message entered by the developer and the files involved in
the commit.
Warning
JIRA no longer uses CVSLogHandler for its CVS integration - this
service is kept here purely as an example.
To use this message handler, setup your CVS server to email commit messages using something like SyncMail.
CVSLogHandler parameters
| Parameter | Meaning | Value |
| reporterusername |
Username of default reporter, if sender not recognised. |
JIRA username, e.g. admin |
| createusers |
If a message comes from unrecognised address, create a new JIRA user
with the user name and email address set to the 'From' address of
the message. The password for the new user is randomly generated,
and an email is sent to the new user informing them about their
new account in JIRA.
Note: this parameter is not compatible with
reporterusername. If
createusers is set to true, and the
reporterusername is also
supplied, users will be created if they cannot be found using the
from addresses of the received messages. That is, the
reporterusername will be ignored.
By default (if not supplied), createusers is set to false.
|
true or false |
| notifyusers |
This parameter is only used if createusers is set to true. If notifyusers
is set to false they will not receive a notification that their account has been created via email. The
default value is true to preserve the behaviour before this parameter was added.
By default (if not supplied), notifyusers is set to true.
|
true or false |
| catchemail |
If set, only emails to the specified recipient (To:, Cc:, Bcc:) are processed. |
E.g. issues@mycompany.com |
| bulk |
This option only effects email's with the header "Precedence" set to "bulk", performing an action depending on its value as follows:
-
ignore - Ignore the email and do nothing
-
forward - Forward the email to the address set in the "Forward Email" text field
-
delete - Delete the email permanently
Any other value's are invalid, and the handler will perform normally.
|
ignore or forward or delete |
Message Handlers and Events
The message handlers will dispatch an JIRA event depending on the actions they perform.
For more information on JIRA events please refer to the Notification Schemes section.
The CreateIssueHandler will dispatch an 'Issue Created' event whenever it creates a new issue.
The CreateOrCommentHandler will dispatch one of 'Issue Created', 'Issue Commented' or 'Issue Updated'
events:
- 'Issue Created' event is dispatched whenever it creates a new issue.
- 'Issue Commented' event is dispatched if the issue already exists and a comment is added only.
- 'Issue Updated' event is dispatched if the issue already exists and a comment with attachment(s) is added.
Each of the comment handlers (FullCommentHandler, NonQuotedCommentHandler,
RegexCommentHandler and CVSLogHandler) will dispatch
the 'Issue Commented' event if the message only contains a comment. However, if the message contains an attachment
as well, it will dispatch the 'Issue Updated' event instead.
Building Services from source
To build any of the linked sample code:
- If you have JIRA Standalone, download to the external-source/src/ directory, and read the
instructions in external-source/README.txt) for build instructions.
- If you have the JIRA WAR/Webapp distribution, download the source to the src/ directory. The
code will be compiled into the webapp when build.sh/build.bat is run.
| |
|
