Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.
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.
Writing a new service?
If you are not extending a built-in JIRA service, you should strongly consider writing your new service using the SAL API. Please see our Plugin Tutorial - Scheduling Events via SAL for more information.
For custom-written services, make sure your service class is in the classpath where JIRA can see it — the best locations are usually the <jira-application-dir>/WEB-INF/classes
or <jira-application-dir>/WEB-INF/lib
subdirectories within of your JIRA Installation Directory (as JAR files).
To set up a JIRA service:
com.atlassian.jira.service.services.
type.Type
Service
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.
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.
Please Note: You will need to configure a SMTP mail server before this functionality can be used.
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.
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.
Please Note: If a folder is not specified the mail service will default to 'INBOX'.
To edit a service's properties:
For example, to change the interval at which email is sent from JIRA, edit the Mail Queue Service and change the Delay from the default value of 1 minute.
To remove a service:
JIRA has some useful services out of the box, which may be used as-is or modified for use in your own environment. The source code for all built-in services is available and should give you a 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.
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.
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.
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.
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 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.
Please Note: 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.
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:
com.atlassian.jira.service.util.handler. CreateIssueHandler | API doc | Source
This message handler creates a new issue for each incoming message.
Parameter | Meaning | Value |
---|---|---|
project | Default project where new issues are created. | Project key, e.g. |
issuetype | Default type for new issues. | Integer representing issue type:
|
reporterusername | Username of default reporter, if sender not recognised. This field is case sensitive, and usernames are always lowercase. | JIRA username, e.g. |
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. |
|
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. |
|
catchemail | If set, only emails to the specified recipient (To:, Cc: ) are processed. | e.g. |
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 when the issue is created. In JIRA 3.1 and above, if you do not want this behaviour, set ccassignee to false. |
|
ccwatcher | If an email has a To, Cc or Bcc address listing a user already present in JIRA, it is possible to automatically add that user to an issue's watchers list, by setting the |
|
bulk | This option only affects emails with the 'Precedence: bulk' or emails with an 'Auto-Submitted' header that is not set to "no". One of the following actions will be performed, depending on the value of this option:
|
|
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.
Parameter | Meaning | Value |
---|---|---|
project | Default project where new issues are created. | Project key, e.g. |
issuetype | Default type for new issues. | Integer representing issue type:
|
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. |
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. |
|
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. |
|
catchemail | If set, only emails to the specified recipient (To:, Cc:, Bcc: ) | e.g. |
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. |
|
ccwatcher | If an email has a To, Cc or Bcc address listing a user already present in JIRA, it is possible to automatically add that user to an issue's watchers list, by setting the |
|
bulk | This option only affects emails with the 'Precedence: bulk' or emails with an 'Auto-Submitted' header that is not set to "no". One of the following actions will be performed, depending on the value of this option:
|
|
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.
Parameter | Meaning | Value |
---|---|---|
reporterusername | Username of default reporter, if sender not recognised. | JIRA username, e.g. |
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. |
|
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. |
|
catchemail | If set, only emails to the specified recipient (To:, Cc:, Bcc: ) | e.g. |
bulk | This option only affects emails with the 'Precedence: bulk' or emails with an 'Auto-Submitted' header that is not set to "no". One of the following actions will be performed, depending on the value of this option:
|
|
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.
Parameter | Meaning | Value |
---|---|---|
reporterusername | Username of default reporter, if sender not recognised. | JIRA username, e.g. |
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. |
|
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. |
|
catchemail | If set, only emails to the specified recipient (To:, Cc:, Bcc: ) are processed. | e.g. |
bulk | This option only affects emails with the 'Precedence: bulk' or emails with an 'Auto-Submitted' header that is not set to "no". One of the following actions will be performed, depending on the value of this option:
|
|
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.
Parameter | Meaning | Value |
---|---|---|
reporterusername | Username of default reporter, if sender not recognised. | JIRA username, e.g. |
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. |
|
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. |
|
catchemail | If set, only emails to the specified recipient (To:, Cc:, Bcc: ) are processed. | e.g. |
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 affects emails with the 'Precedence: bulk' or emails with an 'Auto-Submitted' header that is not set to "no". One of the following actions will be performed, depending on the value of this option:
|
|
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.
Parameter | Meaning | Value |
---|---|---|
reporterusername | Username of default reporter, if sender not recognised. | JIRA username, e.g. |
createusers | If a message comes from an 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. |
|
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. |
|
catchemail | If set, only emails to the specified recipient (To:, Cc:, Bcc: ) | e.g. |
bulk | This option only affects emails with the 'Precedence: bulk' or emails with an 'Auto-Submitted' header that is not set to "no". One of the following actions will be performed, depending on the value of this option:
|
|
The message handlers will dispatch a 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:
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.
To build any of the linked sample code:
build.sh/build.bat
is run.