My First JIRA Service

A service that runs at regular intervals is a much wanted feature in any web application. It is more so if it is one that can be managed with user configured parameters and without having to reboot etc. JIRA offers a mechanism to add new services on to it that runs at regular intervals after every start-up. It lets us do things related to JIRA and things independent of it. It lets us integrate with third party applications. It lets us do wonders!

There are built-in services in JIRA. Export Service, POP Service etc to name a few. Here we are going to see how we can add a custom service on to JIRA

As opposed to the other JIRA plug-in modules, services don't need a plug-in descriptor. Instead it uses a configurations XML. It is typically a jar file with the related classes , files and a configuration xml.

Let us write a configuration XML to start with:

<someservice id="jtricksserviceid">
    <description>My New Service</description>
    <properties>
    </properties>
</someservice>

This is a simple configuration XML that doesn't take any properties. It has a root element and a unique id both which can be custom names of your pick. The root element we have is someservice and id is jtricksserviceid. The description, as the name suggests, is just a short description of the service. Properties tag holds the different properties you want to associate with the service. These properties will be entered by the user while configuring the service. We will see more on that later.

Now let us put the xml file under src/main/resources/com/jtricks/services.

Let us now create the same package com.jtricks.services under src/main/java. The package can of-course be different but just to be in sync I am using the same.

The next step is to create a Java class JTricksService. The class should extend AbstractService which implements JIRAService.

Following are the only 2 mandatory methods that you need to implement:

public void run() {
    System.out.println("Running the JTricks service!!");
}

public ObjectConfiguration getObjectConfiguration() throws ObjectConfigurationException {
    return getObjectConfiguration("MYNEWSERVICE", "com/jtricks/services/myjtricksservice.xml", null);
}

Here run is the key method that is executed when the service runs at regular intervals.

The other key, mandatory method is getObjectConfiguration(). We get the configurations from the XML we have written earlier in this method. All we need to do here is to call the parent class's getObjectConfiguration method by passing 3 things. The first argument is a unique ID (which need not be same as the id in XML file). This id is used as key while saving the configurations internally. The second argument is the path to the configuration XML file we wrote earlier. The third argument is a Map using which you can add user parameters on to the object configuration.
Note: The third argument is mostly null in case of services as these user parameters are not used anywhere. It is meaningful in other places of JIRA like portlets but not in the case of services.

Now you can compile these two files in to a jar and drop it under WEB-INF/classes. See here for more information on services, to see how to configure the service etc. Once it is configured, wait till the delay is over and see it in action!

Let us now have a look at how to add more parameters in addition to the default delay parameter. The first things is to modify the XML file. Add the new property tags in to it. The modified file will look like this:

<someservice id="jtricksserviceid">
    <description>My New Service</description>
    <properties>
        <property>
            <key>Tutorial</key>
            <name>The tutorial you like</name>
            <type>string</type>
        </property>
    </properties>
</someservice>

As you can see, a new property 'Tutorial' is added which is of type string. Now we need to modify the class to retrieve this property.

In the Java class, let us add a new class variable tutorial to hold this property and initiate it in the init method.

@Override
public void init(PropertySet props) throws ObjectConfigurationException {
    super.init(props);

    if (hasProperty(TUTORIAL)) {
        tutorial = getProperty(TUTORIAL);
    } else {
        tutorial = "I don't like tutorials!";
    }
}

The init method checks if the property is configured and available and if so, assigns the value to tutorial variable.

Let us now modify the run method to print the value of the new property:

@Override
public void run() {
    System.out.println("Running the JTricks service!! Tutorial? " + tutorial);
}

The init method will be called whenever the service is configured/re-configured and the property value we enter on the JIRA Admin GUI is retrieved and stored in the class variable for use in the run method.

You can also optionally override the destroy method to do anything you want before the service is removed!

Now, re-build the jar and drop in under WEB-INF lib. Restart to see how the service works now. You might have noticed that the service prints "Running the JTricks service!! Tutorial? I don't like tutorials!" when it runs as the tutorial property is not configured yet. Go to the Administration > Services area, edit the service to enter a value under 'The tutorial you like' field. Assuming you entered "JTricks Tutorials", you will see the output as "Running the JTricks service!! Tutorial? JTricks Tutorials".

Well, that is our first simple service. Rest is up to you to develop your complex, super efficient service! Njoy!!

As usual, feel free to add your comments and download the full source below.

services-plugin.zip
File Size:	4 kb
File Type:	zip

Download File

---