This page last changed on Mar 05, 2010 by mdoar.
This document applies to JIRA 4.1. If you are using an older version of JIRA please see Creating and Editing an Issue.

IssueService

JIRA 4.1 has introduced an API level object called the IssueService. This service class is used to perform create, update, delete, and transition operations in JIRA with Issue's. This services methods will make sure that when dealing with Issues that all of JIRA's business rules are enforced. This means that permissions and data validation will be checked, proper events will be fired, and notifications will be triggered.

Plugin developers wanting to perform any of these operations should use the IssueService as it abstracts the normally complicated issue operations into something a bit simpler and it will ensure that you do not put corrupted data into JIRA.

The general format of the service is that there are two methods per operation. One method, the validation method, generates a result object that is used as the parameter to the next "do" method. If validation does not pass then there will be internationalized error messages in the result object that explain what was wrong and you will be unable to invoke the "do" method with this parameter.

The "do" methods also return a result object which will contain the new state of the issue if the operation was successful and errors if something whet wrong during the action.

Getting an instance of the IssueService

You can get an IssueService object either by constructor injection or explicitly via a call like:

IssueService issueService = ComponentManager.getInstance().getIssueService();

Retrieving an issue

Issues can be retrieved using the IssueService either by id or key:

final IssueService.IssueResult issueResult = issueService.getIssue(remoteUser, 10000L);
final MutableIssue mutableIssue = issueResult.getIssue();
//OR
final IssueService.IssueResult issueResult = issueService.getIssue(null, "JRA-1234");
final MutableIssue mutableIssue = issueResult.getIssue();

IssueInputParameters - a builder that specifies issue values

To perform an operation on an issue you will use an instance of com.atlassian.jira.issue.IssueInputParameters as a builder that lets you tell JIRA what you want the issue to look like.

Here is an example of how to use the builder object:

IssueInputParameters issueInputParameters = new IssueInputParametersImpl();
        issueInputParameters.setProjectId(12345L)
            .setIssueTypeId("2");
            .setSummary("This is a summary");
            .setReporterId("joeuser");
            .setAssigneeId("otheruser");
            .setDescription("I am a description");
            .setEnvironment("I am an environment");
            .setStatusId("2");
            .setPriorityId("2");
            .setResolutionId("2");
            .setSecurityLevelId(10000L);
            .setFixVersionIds(10000L, 10001L);

This is used in issue creation, update, and transitions to specify new or updated values.

This builder can be used to add comments (with or without restrictions) to an issue and to set custom field values. See the javadoc for full details.

Creating a new Issue

Once you have setup the issue builder, described above, in the way you would like, then you need to get an instance of the issue service, as described above.

To validate that your issue can be created as specified you must invoke the validateCreate method. If there are any errors (e.g. insufficient permissions, missing required fields, referencing values that do not exist, etc) then there will be i18n'ed messages in the returned result object. See the javadoc on the method for full details.

Once you have a valid CreateValidationResult you can pass this object to the issue service create method. This will create the issue and perform all the related tasks (event publication, issue indexing, etc). The create result will only have errors if there is a severe problem with JIRA (e.g. can't communicate with the DB, the workflow has changed since you invoked validate, etc.). See the javadoc for full details.

Here is an example of how to invoke the service to create the issue we setup above:

IssueService issueService = ComponentManager.getInstance().getIssueService();

CreateValidationResult createValidationResult = issueService.validateCreate(user, issueInputParameters);

if (createValidationResult.isValid())
{
    IssueResult createResult = issueService.create(user, createValidationResult);
    if (!createResult.isValid())
    {
        // Do something
    }
}

Editing an existing Issue

Editing an existing issue is very similar to creating an issue. You will use the same com.atlassian.jira.issue.IssueInputParameters as a builder that lets you tell JIRA what you want to change on the issue.

You must invoke the validateUpdate method with the issue id you wish to update and the IssueInputParameters that contains the changes that you want to apply. This will produce an UpdateValidationResult which you can provide to the update method.

If there are any errors (e.g. insufficient permissions, missing required fields, referencing values that do not exist, etc) then there will be i18n'ed messages in the returned result object. See the javadoc on the method for full details.

Once you have a valid UpdateValidationResult you can pass this object to the issue service update method. This will update the issue and perform all the related tasks (event publication, issue indexing, etc). The update result will only have errors if there is a severe problem with JIRA (e.g. can't communicate with the DB, the workflow has changed since you invoked validate, etc.). See the javadoc for full details.

Here is an example of how to invoke the service to update the summary of an issue with an id of 12345:

IssueInputParameters issueInputParameters = new IssueInputParametersImpl();
issueInputParameters.setSummary("I am a new summary");

IssueService issueService = ComponentManager.getInstance().getIssueService();

UpdateValidationResult updateValidationResult = issueService.validateUpdate(user, 12345L, issueInputParameters);

if (updateValidationResult.isValid())
{
    IssueResult updateResult = issueService.update(user, updateValidationResult);
    if (!updateResult.isValid())
    {
        // Do something
    }
}

Transitioning an existing Issue

Transitioning an issue is much like editing an issue. You will specify an additional parameter, the transition action id, which identifies the transition the issue should make, along with the IssueInputParameters object specifying any values you wish to set while transitioning. You must invoke the validateTransition method on the issue service to generate a TransitionValidationResult. See the javadoc for full details.

If there are any errors (e.g. insufficient permissions, missing required fields, referencing values that do not exist, etc) then there will be i18n'ed messages in the returned result object. See the javadoc on the method for full details.

Once you have a valid TransitionValidationResult you can pass this object to the issue service transition method. This will transition the issue and perform all the related tasks (event publication, issue indexing, workflow post functions, etc). The transition result will only have errors if there is a severe problem with JIRA (e.g. can't communicate with the DB, the workflow has changed since you invoked validate, etc.). See the javadoc for full details.

Here is an example of how to invoke the service to transition an issue with an id of 12345 with a transition with an id of 10000, while also setting the assignee:

IssueInputParameters issueInputParameters = new IssueInputParametersImpl();
issueInputParameters.setAssigneeId("newdude");

IssueService issueService = ComponentManager.getInstance().getIssueService();

TransitionValidationResult transitionValidationResult = issueService.validateTransition(user, 12345L, 10000L, issueInputParameters);

if (transitionValidationResult.isValid())
{
    IssueResult transitionResult = issueService.transition(user, transitionValidationResult);
    if (!transitionResult.isValid())
    {
        // Do something
    }
}

Delete an existing Issue

Deleting an issue is quite easy. You just need to provide the issue service with the id of the issue you wish to delete. You must invoke the validateDelete method and it will generate a DeleteValidationResult. This can be used to invoke the delete method.

If there are any errors (e.g. insufficient permissions, the issue no longer exists, etc) then there will be i18n'ed messages in the returned result object. See the javadoc on the method for full details.

Once you have a valid DeleteValidationResult you can pass this object to the issue service delete method. This will delete the issue and perform all the related tasks (delete associated attachments, comments, worklogs, etc.). The delete result will only have errors if there is a severe problem with JIRA. See the javadoc for full details.

Here is an example of how to invoke the service to delete an issue with an id of 12345:

IssueService issueService = ComponentManager.getInstance().getIssueService();

DeleteValidationResult deleteValidationResult = issueService.validateDelete(user, 12345L);

if (deleteValidationResult.isValid())
{
    ErrorCollection deleteErrors = issueService.delete(user, deleteValidationResult);
    if (deleteResult.hasAnyErrors())
    {
        // Do something
    }
}

Issue Operations without validation

If you for some reason do not want to use the IssueService class, then you should look at the javadoc for the IssueManager class for create, delete, and update, and also at the WorkflowManager for the transition.

However we highly recommend using the IssueService class for these operations since there is a lot of business logic associated with issue operations.

Document generated by Confluence on Mar 27, 2011 18:54