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.
On this page:
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.
- Choose
> System. Select Advanced > Services to open a page showing all the configured services. Keyboard shortcut: g + g + start typing services - 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 add a debugging service, click the Built-in Services link followed by the Debugging Service link:
- After completing the fields on the Add Service form, click the Add Service button. This opens the Edit Service page, where you can configure your new service's options. Your service's options will vary depending on the type (i.e. class) of service you chose.
- After completing the remaining options on the Edit Service page, click the Update button to save your new service's options.
Editing service properties
To edit a service's properties:
- Log in as a user with the JIRA System Administrators global permission.
- Choose > System. Select Advanced > Services to open a page showing all the configured services. Keyboard shortcut: g + g + start typing services
- 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.
- Choose > System. Select Advanced > Services to open a page showing all the configured services. Keyboard shortcut: g + g + start typing services
- 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
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 in new JIRA installations (once the setup wizard has been completed). Hence, you may find you already have one.
You can find this class within the following directory of an expanded JIRA source archive (which can be downloaded by JIRA customers from https://my.atlassian.com):<source-installation-directory>/jira-project/jira-components/jira-core/src/main/java/com/atlassian/jira/service/services/export
Jelly service
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 are considering writing a custom service, often a periodically invoked Jelly script may be an easier alternative.
In Linux, the input-file and output-file properties are relative to your system's / folder. Please be careful to select a path that JIRA will have access to.
You can find this class within the following directory of an expanded JIRA source archive (which can be downloaded by JIRA customers from https://my.atlassian.com):<source-installation-directory>/jira-project/jira-components/jira-core/src/main/java/com/atlassian/jira/jelly/service
Mail handler services
JIRA mail handler services are not configurable through JIRA's Services page (with the exception of being able to be removed). For more information about configuring a mail handler in JIRA, including the creation of custom mail handlers, please refer to Creating Issues and Comments from Email.
Custom services
If you are a JIRA developer who wishes to write your own JIRA service, please note that 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.