Services

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.

Registering a Service

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:

Log in as a user with the 'JIRA System Administrators' global permission.
Select 'Administration' > 'System' > 'Advanced' > 'Services' (tab) to open the 'Services' page.
Keyboard shortcut: 'g' + 'g' + type 'servi'
In the 'Add Service' form at the bottom of the page, complete the following fields:
- 'Name' — a descriptive name for this service.
- 'Class' — the fully-qualified class name of your service. This is likely to have the form com.atlassian.jira.service.services.type.TypeService
  See Sample services for provided service class names.
  To use one of JIRA's built-in service classes, first click the 'Built-in Services' link to expand the list of service classes and then click the name of the specific class in the list. The fully-qualified class name of the built-in service will be added to the 'Class' field.
- 'Delay' — the delay (in minutes) between service runs.
  For example, to a POP Service, click the 'Built-in Services' link followed by the 'Create issues from POP' link:
After completing the 'Add Service' form's fields, click the 'Add Service' button. This opens the 'Edit Service' page, where you can configure your new service's options.
On the 'Edit Service' page, you may be required to specify a MessageHandler (i.e. 'Handler'), depending on the service you chose. A MessageHandler is 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 to determine the parameter(s) that each MessageHandler accepts. The following screenshot shows a CreateIssueHandler being attached to the example POP Service just created:
After completing the remaining options on the 'Edit Service' page, click the 'Update' button to save your new service's options.

On this page:

The information on this page does not apply to JIRA OnDemand.

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.

Please 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.

Please Note: If a folder is not specified the mail service will default to 'INBOX'.

Editing Service Properties

To edit a service's properties:

Log in as a user with the 'JIRA System Administrators' global permission.
Select 'Administration' > 'System' > 'Advanced' > 'Services' (tab) to open the 'Services' page.
Keyboard shortcut: 'g' + 'g' + type 'servi'
Click the 'Edit' link associated with the service whose properties you wish to edit.

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.

Removing a Service

To remove a service:

Log in as a user with the 'JIRA System Administrators' global permission.
Select 'Administration' > 'System' > 'Advanced' > 'Services' (tab) to open the 'Services' page.
Keyboard shortcut: 'g' + 'g' + type 'servi'
Click the 'Delete' link associated with the service you wish to remove.

Built-in Services

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.

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.

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.

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. This field is case sensitive, and usernames are always lowercase.	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. Please note, setting this parameter also suppresses the generation of the addressee as watcher.	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 when the issue is created. 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`
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 `ccwatcher` parameter to `true` . Please note that users created by the `createusers` parameter cannot be added to an issue's watchers list by the `ccwatcher` parameter. Users must already exist in JIRA's userbase, and must have an email address. By default (if not supplied), `ccwatcher` is set to false.	`true` or `false`
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: `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. The `project` parameter is only relevant for issue creation, not for issue commenting. If an email contains an issue key in the email subject, and that issue exists in the JIRA instance, the handler will add the email as a comment on the issue, regardless of which project the issue is in.	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`
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 `ccwatcher` parameter to `true` . Please note that users created by the `createusers` parameter cannot be added to an issue's watchers list by the `ccwatcher` parameter. Users must already exist in JIRA's userbase, and must have an email address. By default (if not supplied), `ccwatcher` is set to false.	`true` or `false`
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: `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`

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 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: `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`

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 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: `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`

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 first 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. /----\sOriginal 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: `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`

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 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. 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 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: `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`

Message Handlers and Events

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:

'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.

Child pages