To get the latest and greatest features in JIRA, please upgrade to JIRA Software. Visit the Migration Hub for more information.


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.

(tick) 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

(info) 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:

  1. Log in as a user with the JIRA System Administrators  global permission.
  2. Choose > System. Select Advanced > Services to open a page showing all the configured services.
    (tick) Keyboard shortcut: g + g + start typing services
  3. 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
      See Sample services for provided service class names.
      (info) 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:
  4. 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.
    (info) Your service's options will vary depending on the type (i.e. class) of service you chose.
  5. 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:

  1. Log in as a user with the JIRA System Administrators global permission.
  2. Choose > System. Select Advanced > Services to open a page showing all the configured services.
    (tick) Keyboard shortcut: g + g + start typing services
  3. 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:

  1. Log in as a user with the JIRA System Administrators  global permission.
  2. Choose > System. Select Advanced > Services to open a page showing all the configured services.
    (tick) Keyboard shortcut: g + g + start typing services
  3. 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 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

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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

18 Archived comments

  1. User avatar


    I let the CreateOrCommentHandler to create new users. Is it possible for these users to not be members of jira-users? I use Jira as a help desk system, and the reporters doesn't need a full Jira account. Since I only have a 50-user license, I have to remove external users from the jira-users group quite often...

    06 Nov 2009
  2. User avatar

    Patrick Harris

    This would be much clearer if your tables had "Required" and "Default" columns. . . technical writer?

    There are a couple of oddities in this document, but one that interests me is the StripQuotes parameter in the CreateOrCommendHandler table, whose value is "(anything)". If memory serves, this value was a boolean with "true" or "false" the possible values; forum discussions bear this out. I want to enable Jira's powerful create or comment functionality (one it's best, if not its best-supported, assets) but I am now left wondering if version 4.1 is looking for an array of strings here (which would be useful), a bool, or if a haiku on technical writing would suffice.

    09 Jul 2010
  3. User avatar

    John Connors

    I also noticed that if you set createusers=false and do not supply reportusername, the service fails. Unfortunately, I see no way for the service to store the sender's email address in the expected location without making each sender a JIR user. This might be useful for a bug tracker, but not for a help desk.

    13 Jul 2010
  4. User avatar

    Markus Lepper

    This page mentions that the re-index service could be activated in the Services section

    I could not find these option in Jira 4.2.2 => How to get the automatic indexing to work?


    26 Jan 2011
    1. User avatar

      Giles Gaskell

      Hi Markus,

      The documentation on the Search Indexing page has been clarified to indicate that it is the index optimisation job that is scheduled to run at midnight.

      Be aware that the index optimisation job is no longer configurable through the Services page (above). You could alter the frequency of the this job by modifying the cron expression in the scheduler-config.xml file (located in the atlassian-jira/WEB-INF/classes subdirectory of your JIRA Installation Directory for JIRA Standalone). (Of course, this would require you to restart JIRA for any changes to take effect.) However, you would need to carry over this configuration over manually upon upgrading JIRA.


      28 Jul 2011
  5. User avatar

    Andy Pook

    The FileService says that it "is configured with the directory to watch". Ummm... how do you set that directory? in 4.2 and above?

    In previous versions there was a "Directory" filed to fill in.

    Now, when editing the service, it says "This service will retrieve data from [jira.home]/mail/". Which is actually inaccurate. Switching on debugging shows that it actually tries to import from [jira.home]/import/mail.

    I really need it to import from my SMTP servers mail drop directory. I do not what to reconfig the SMTP server to drop into Jiras folder as I have other mail for other destinations being dropped there which other services pick up.

    Thanks, in advance for any help

    21 Feb 2011
    1. User avatar

      Todd Parson

      Andy, I'm having this same issue.  Did you reconfigure the SMTP server or did you find another way of getting Jira to look in your SMTP server's mail drop directory?  I can get around this by setting up a Unix shell script to copy the mail file to the correct directory on the Jira server but it seems like there should be a better way of handling this.


      03 Oct 2011
      1. User avatar

        Andy Pook

        I had a conversation on the following ticket

        The bottom line is that this is a "security" thing. It has been deemed more secure if the Jira app cannot access anything outside [jira.home]. I'd much rather be treated like an adult and be allowed to configure my system the way I need it. Anyway...

        First: The path mentioned on the config page "jira.home/mail/" is incorrect the correct path is as mentioned above "jira.home/import/mail". Apparently there is an issue to get this fixed.

        Second: Their "recommended solution" is to configure your mail server (or a sym-link) to drop all messages to the above path. This means that all your mail gets delivered to a Jira owned directory. Seems silly to me. I usually want to configure my SMTP server separately from a ticketing system. Mine receives mail destined for other systems. These are already configured and would need changing because of Jira's rigidity.

        You have a few options:

        • Write a scheduled script to copy mail from your mail drop location to Jira. (You'll need to parse the messages to pick out those destined for Jiira).
        • You could probably do something tricky with mount points and NFS if you're on Linux. I'm on Windows so a little more limited. Luckily for me I have a separate domain and SMTP service for dealing with mail going to these kind of systems.
        • You could write your own version of the FileService and configure it as you like. Not incredibly difficult. But I've got other things to do.
        • If you know your SMTP you could probably get your main mail receiver to forward the right messages to a dedicated SMTP service on your Jira machine and configure it as they suggest (or like below).
        • My option (as it's simple for me) was to reverse their suggestion. Delete their import/mail directory and create a link to my mail drop location.
          This means I don't need to reconfigure the mail server or any other system relying on that location. But obviously means that the drop location needs to be on the same machine. (Though mine is at least on a different spindle.)

        Hope this rant helps a little (smile)

        03 Oct 2011
        1. User avatar

          Todd Parson

          Andy, it definitely helps!  Thanks for the rant.  (smile)

          After playing around with Unix permissions, I got your solution of creating a symbolic import/mail link to sendmail's mail drop location on the server working.  I agree that this isn't ideal but I very much prefer this option to running a scheduled script all day/every day on all Jira servers, rolling my own FileService, and reconfiguring our SMTP server.

          Thanks again for your help!

          03 Oct 2011
  6. User avatar


    Is it possible for the mail service to set Components on projects?  Or some custom fields like Category?  

    04 May 2011
  7. User avatar


    Hello together,

    Jira is a top product!!! 

    But now I´ve got a little problem. We create issues from email and I want to import the "CCs" in the issues, to.  My system is a help desk system, e.g.the customers and "CCs" are not registered in Jira. Is there a way, without using the JEMH? Does anybody have an idea?

    23 May 2011
  8. User avatar


    Any update to the issue of users taking up account seats. JEMH indicates it will work with that plugin, however I find the documentation for that plugin very vauge and I cant find a way to make it work on my system. Any chance I can specify the autoJoinGroup with the CreateorCommentHandler similar to JEMF?


    20 Jul 2011
  9. User avatar

    Ægir Þorvaldsson

    Any news on whether the email service will be able to handle components for a specific project.   As of now, our use case really prevents this, as we will have to go into the issue and set components, labels etc by hand.  

    19 Oct 2011
  10. User avatar


    Is there a way to get JIRA to pull incoming messages from a custom directory?

    Example..   I want to create a service for a issue type named issues

    Messages will be sent via email and delivered to /home/jira/queue/issues/new

    When I create the service that will handle the ticket creation it shows:

    This service will retrieve data from [jira.home]/mail/

    Is there a way that we cann point JIRA to pull from /home/jira/queue/ instead?


    Please help.

    17 Nov 2011
    1. User avatar


      I forgot to mention that the directories are all on the JIRA server.  We have it setup for out mail servers sends emails to the Jira server and then get's filtered via a postfix config to get delivered into thier own respective queues...

      17 Nov 2011
      1. User avatar

        Andy Pook

        The [jira.home]/mail path is hard coded into the service for "security reasons". The only way of using another directory is to delete the current mail directory and create a link (Linux) or junction (Windows) that points to your desired directory.


        See my comment above (from October 3rd)

        18 Nov 2011
  11. User avatar


    i try doing my first service, i learn and follow all the staps in but the result always fail.

    so have you an other link more simple and sure?,

    thank you

    05 Dec 2011
  12. User avatar

    Ishan Liyanage

    We can write services as plugins. No need to deploy them in classes or lib directories.

    07 May 2015
Powered by Confluence and Scroll Viewport