Summary: Methods | [Expand All]
@PublicApi public interface

WorklogService

com.atlassian.jira.bc.issue.worklog.WorklogService
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

This is the business layer component that must be used to access all WorklogService functionality. This will perform validation before it hands off to the WorklogManager. Operations will not be performed if validation fails.

Summary

Public Methods
Worklog createAndAutoAdjustRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
Persists a new Worklog on the given Issue.
Worklog createAndRetainRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
Persists a new Worklog on the given Issue.
Worklog createWithManuallyAdjustedEstimate(JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountResult worklogAdjustmentAmount, boolean dispatchEvent)
Persists a new Worklog on the given Issue.
Worklog createWithNewRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)
Persists a new Worklog on the given Issue.
boolean deleteAndAutoAdjustRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
Deletes the specified Worklog.
boolean deleteAndRetainRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
Deletes the specified Worklog.
boolean deleteWithManuallyAdjustedEstimate(JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountResult worklogAdjustmentAmount, boolean dispatchEvent)
Deletes the specified Worklog.
boolean deleteWithNewRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)
Deletes the specified Worklog.
Worklog getById(JiraServiceContext jiraServiceContext, Long id)
Used to get a worklog by its id.
List getByIssue(JiraServiceContext jiraServiceContext, Issue issue)
Returns all child worklogs of a specified issue.
List<Worklog> getByIssueVisibleToUser(JiraServiceContext jiraServiceContext, Issue issue)
Returns all child worklogs of a specified issue that the provided user has permission to see.
PagedList<Worklog> getByIssueVisibleToUser(JiraServiceContext jiraServiceContext, Issue issue, int pageSize)
Returns a PagedList over all all child worklogs of a specified issue that the provided user has permission to see.
boolean hasPermissionToCreate(JiraServiceContext jiraServiceContext, Issue issue, boolean isEditableCheckRequired)
Determines if the user has the WORK_ISSUE permission, that timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.
boolean hasPermissionToDelete(JiraServiceContext jiraServiceContext, Worklog worklog)
Determine whether the current user has the permission to delete the supplied worklog, timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.
boolean hasPermissionToUpdate(JiraServiceContext jiraServiceContext, Worklog worklog)
Determine whether the current user has the permission to update the supplied worklog, timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.
boolean isIssueInEditableWorkflowState(Issue issue)
Will return true if the issue is in an editable workflow state.
boolean isTimeTrackingEnabled()
Will return true if JIRA_OPTION_TIMETRACKING is true, false otherwise.
Worklog updateAndAutoAdjustRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
Updates the provided Worklog.
Worklog updateAndRetainRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)
Updates the provided Worklog.
Worklog updateWithNewRemainingEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)
Updates the provided Worklog.
WorklogResult validateCreate(JiraServiceContext jiraServiceContext, WorklogInputParameters params)
Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.
WorklogAdjustmentAmountResult validateCreateWithManuallyAdjustedEstimate(JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountInputParameters params)
Determines whether worklogs are enabled in JIRA and if the user has the required permission as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.
WorklogNewEstimateResult validateCreateWithNewEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateInputParameters params)
Determines whether worklogs are enabled in JIRA and if the user has the required permission as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.
WorklogResult validateDelete(JiraServiceContext jiraServiceContext, Long worklogId)
Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.
WorklogAdjustmentAmountResult validateDeleteWithManuallyAdjustedEstimate(JiraServiceContext jiraServiceContext, Long worklogId, String adjustmentAmount)
Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.
WorklogNewEstimateResult validateDeleteWithNewEstimate(JiraServiceContext jiraServiceContext, Long worklogId, String newEstimate)
Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.
WorklogResult validateUpdate(JiraServiceContext jiraServiceContext, WorklogInputParameters params)
Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToUpdate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to update a worklog for this issue.
WorklogNewEstimateResult validateUpdateWithNewEstimate(JiraServiceContext jiraServiceContext, WorklogNewEstimateInputParameters params)
Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToUpdate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to update a worklog for this issue.

Public Methods

public Worklog createAndAutoAdjustRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)

Persists a new Worklog on the given Issue. This method will auto-adjust the issues remaining estimate based on the value of the time spent on the work.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
worklogResult the WorklogResult generated by the validate call
dispatchEvent whether or not you want to have an event dispatched on Worklog creation @return the created Worklog object, or null if no object created.
Returns
  • the created Worklog object or null if no object was created.

public Worklog createAndRetainRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)

Persists a new Worklog on the given Issue. This method will make no adjustment to the issues remaining estimate.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
worklogResult the WorklogResult generated by the validate call
dispatchEvent whether or not you want to have an event dispatched on Worklog creation @return the created Worklog object, or null if no object created.
Returns
  • the created Worklog object or null if no object was created.

public Worklog createWithManuallyAdjustedEstimate (JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountResult worklogAdjustmentAmount, boolean dispatchEvent)

Persists a new Worklog on the given Issue. This method will adjust the issues remaining estimate by reducing by the adjustmentAmount which has been passed to this method. Before calling this method, you must call validateCreateWithManuallyAdjustedEstimate() to ensure that the creation is OK.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
worklogAdjustmentAmount the Worklog and adjustmentAmount for the issue.
dispatchEvent whether or not you want to have an event dispatched on Worklog creation
Returns
  • the created Worklog object or null if no object was created.
See Also

public Worklog createWithNewRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)

Persists a new Worklog on the given Issue. This method will adjust the issues remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
worklogNewEstimate the Worklog and new estimate for the issue.
dispatchEvent whether or not you want to have an event dispatched on Worklog creation
Returns
  • the created Worklog object or null if no object was created.
See Also

public boolean deleteAndAutoAdjustRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)

Deletes the specified Worklog. This method will auto-adjust the issues remaining estimate by adding the time spent on the deleted worklog.

Parameters
jiraServiceContext containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
worklogResult result of the call to validateDelete(com.atlassian.jira.bc.JiraServiceContext, Long) which contains the Worklog to delete
dispatchEvent whether or not you want to have an event dispatched on Worklog delete
Returns
  • true if the Worklog was successfully deleted, false otherwise

public boolean deleteAndRetainRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)

Deletes the specified Worklog. This method will make no adjustment to the issues remaining estimate.

Parameters
jiraServiceContext containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
worklogResult result of the call to validateDelete(com.atlassian.jira.bc.JiraServiceContext, Long) which contains the Worklog to delete
dispatchEvent whether or not you want to have an event dispatched on Worklog delete
Returns
  • true if the Worklog was successfully deleted, false otherwise

public boolean deleteWithManuallyAdjustedEstimate (JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountResult worklogAdjustmentAmount, boolean dispatchEvent)

Deletes the specified Worklog. This method will adjust the issues remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.

Parameters
jiraServiceContext containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
worklogAdjustmentAmount the Worklog and adjustmentAmount for the issue.
dispatchEvent whether or not you want to have an event dispatched on Worklog delete @return the deleted Worklog object, or null if no object has been deleted.
Returns
  • true if the Worklog was successfully deleted, false otherwise

public boolean deleteWithNewRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)

Deletes the specified Worklog. This method will adjust the issues remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.

Parameters
jiraServiceContext containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
worklogNewEstimate the Worklog and new estimate for the issue.
dispatchEvent whether or not you want to have an event dispatched on Worklog delete @return the deleted Worklog object, or null if no object has been deleted.
Returns
  • true if the Worklog was successfully deleted, false otherwise

public Worklog getById (JiraServiceContext jiraServiceContext, Long id)

Used to get a worklog by its id.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
id uniquely identifies the worklog
Returns
  • returns the worklog for the passed in id, null if not found.

public List getByIssue (JiraServiceContext jiraServiceContext, Issue issue)

Returns all child worklogs of a specified issue.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
issue the specified parent issue (not null)
Returns
  • a List of Worklogs, ordered by creation date. An empty List will be returned if none are found

public List<Worklog> getByIssueVisibleToUser (JiraServiceContext jiraServiceContext, Issue issue)

Returns all child worklogs of a specified issue that the provided user has permission to see.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
issue the specified parent issue (not null)
Returns
  • a List of Worklogs, ordered by creation date. An empty List will be returned if none are found

public PagedList<Worklog> getByIssueVisibleToUser (JiraServiceContext jiraServiceContext, Issue issue, int pageSize)

Returns a PagedList over all all child worklogs of a specified issue that the provided user has permission to see.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
issue the specified parent issue (not null)
pageSize the number of worklogs per page
Returns
  • a List of Worklogs, ordered by creation date. An empty List will be returned if none are found

public boolean hasPermissionToCreate (JiraServiceContext jiraServiceContext, Issue issue, boolean isEditableCheckRequired)

Determines if the user has the WORK_ISSUE permission, that timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
issue the issue to add the worklog to
isEditableCheckRequired set to true if we require the issue to be in an editable state. This should always be the case except when logging work on transition
Returns
  • true if the user has permission to create a worklog on the specified issue, false otherwise

public boolean hasPermissionToDelete (JiraServiceContext jiraServiceContext, Worklog worklog)

Determine whether the current user has the permission to delete the supplied worklog, timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.

In case of errors, add error messages to the error collection within the servicecontext.

Passing in null worklog or a worklog with null ID will return false and an error message will be added to the error collection.

Passing in null error collection will throw NPE.

This method will return true if the user is a member of the worklog's group/role level (if specified) AND

and false otherwise.

Parameters
jiraServiceContext containing the User who wishes to delete the worklog and the ErrorCollection that will contain any errors in calling the method
worklog the Worklog the user wishes to delete
Returns
  • true if the user has permission to delete the supplied worklog, false otherwise

public boolean hasPermissionToUpdate (JiraServiceContext jiraServiceContext, Worklog worklog)

Determine whether the current user has the permission to update the supplied worklog, timetracking is enabled in JIRA and that the associated issue is in an editable workflow state.

In case of errors, add error messages to the error collection within the servicecontext.

Passing in null worklog or a worklog with null ID will return false and an error message will be added to the error collection.

Passing in null error collection will throw NPE.

This method will return true if the user is a member of the worklog's group/role level (if specified) AND

and false otherwise.

Parameters
jiraServiceContext containing the User who wishes to update the worklog and the ErrorCollection that will contain any errors in calling the method
worklog the Worklog the user wishes to update
Returns
  • true if the user has permission to update the supplied worklog, false otherwise

public boolean isIssueInEditableWorkflowState (Issue issue)

Will return true if the issue is in an editable workflow state.

Parameters
issue the issue to see if it is in an editable store
Returns
  • true if editable, false otherwise

public boolean isTimeTrackingEnabled ()

Will return true if JIRA_OPTION_TIMETRACKING is true, false otherwise.

Returns
  • true if enabled, false otherwise.

public Worklog updateAndAutoAdjustRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)

Updates the provided Worklog. This method will auto-adjust the issues remaining estimate based on the updated value of the time spent on the work.

Parameters
jiraServiceContext containing the User who wishes to update the worklog and the ErrorCollection that will contain any errors in calling the method
worklogResult result of the call to validateUpdate(com.atlassian.jira.bc.JiraServiceContext, WorklogInputParameters) which contains the Worklog to update
dispatchEvent whether or not you want to have an event dispatched on Worklog update
Returns
  • the update Worklog object, or null if no object has been updated.

public Worklog updateAndRetainRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogResult worklogResult, boolean dispatchEvent)

Updates the provided Worklog. This method will make no adjustment to the issues remaining estimate.

Parameters
jiraServiceContext containing the User who wishes to update the supplied worklog and the ErrorCollection that will contain any errors encountered in calling the method
worklogResult result of the call to validateUpdate(com.atlassian.jira.bc.JiraServiceContext, WorklogInputParameters) which contains the Worklog to update
dispatchEvent whether or not you want to have an event dispatched on Worklog update
Returns
  • the updated Worklog object, or null if no object has been updated.

public Worklog updateWithNewRemainingEstimate (JiraServiceContext jiraServiceContext, WorklogNewEstimateResult worklogNewEstimate, boolean dispatchEvent)

Updates the provided Worklog. This method will adjust the issues remaining estimate to be the new value which has been passed to this method, the old remaining estimate value will be lost.

Parameters
jiraServiceContext containing the User who wishes to create a worklog and the ErrorCollection that will contain any errors in calling the method
worklogNewEstimate the Worklog and new estimate for the issue.
dispatchEvent whether or not you want to have an event dispatched on Worklog update @return the updated Worklog object, or null if no object has been updated.
Returns
  • the updated Worklog object, or null if no object has been updated.

public WorklogResult validateCreate (JiraServiceContext jiraServiceContext, WorklogInputParameters params)

Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.

Parameters
jiraServiceContext containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
params parameter object that contains all the values required to validate
Returns
  • WorklogResult which can be passed to the create methods if has permission and the data passed in is valid, null otherwise

public WorklogAdjustmentAmountResult validateCreateWithManuallyAdjustedEstimate (JiraServiceContext jiraServiceContext, WorklogAdjustmentAmountInputParameters params)

Determines whether worklogs are enabled in JIRA and if the user has the required permission as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.

Parameters
jiraServiceContext containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
params parameter object that contains all the values required to validate
Returns
  • WorklogAdjustmentAmountResult the Worklog of which can be passed to the create methods if has permission and the data passed in is valid, null otherwise

public WorklogNewEstimateResult validateCreateWithNewEstimate (JiraServiceContext jiraServiceContext, WorklogNewEstimateInputParameters params)

Determines whether worklogs are enabled in JIRA and if the user has the required permission as determined by calling hasPermissionToCreate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.Issue, boolean) to create a worklog for this issue.

Parameters
jiraServiceContext containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
params parameter object that contains all the values required to validate
Returns
  • WorklogNewEstimateResult the Worklog of which can be passed to the create methods if has permission and the data passed in is valid, null otherwise

public WorklogResult validateDelete (JiraServiceContext jiraServiceContext, Long worklogId)

Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.

Parameters
jiraServiceContext containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
worklogId identifies the worklog that the update validation will occur against
Returns
  • WorklogResult which can be passed to the delete methods if has permission and the data passed in is valid, null otherwise

public WorklogAdjustmentAmountResult validateDeleteWithManuallyAdjustedEstimate (JiraServiceContext jiraServiceContext, Long worklogId, String adjustmentAmount)

Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.

Parameters
jiraServiceContext containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
worklogId identifies the worklog that the delete validation will occur against
adjustmentAmount The value to increase the issues remaining estimate by.
Returns
  • Worklog which can be passed to the delete methods if has permission and the data passed in is valid, null otherwise

public WorklogNewEstimateResult validateDeleteWithNewEstimate (JiraServiceContext jiraServiceContext, Long worklogId, String newEstimate)

Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToDelete(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to delete a worklog for this issue.

Parameters
jiraServiceContext containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
worklogId identifies the worklog that the delete validation will occur against
newEstimate The value to change the issues remaining estimate to.
Returns
  • Worklog which can be passed to the delete methods if has permission and the data passed in is valid, null otherwise

public WorklogResult validateUpdate (JiraServiceContext jiraServiceContext, WorklogInputParameters params)

Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToUpdate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to update a worklog for this issue.

Parameters
jiraServiceContext containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
params parameter object that contains all the values required to validate
Returns
  • WorklogResult which can be passed to the update methods if has permission and the data passed in is valid, null otherwise

public WorklogNewEstimateResult validateUpdateWithNewEstimate (JiraServiceContext jiraServiceContext, WorklogNewEstimateInputParameters params)

Determines whether worklogs are enabled in JIRA and if the user has the required permissions as determined by calling hasPermissionToUpdate(com.atlassian.jira.bc.JiraServiceContext, com.atlassian.jira.issue.worklog.Worklog) to update a worklog for this issue.

Parameters
jiraServiceContext containing the user who wishes to create a worklog and the errorCollection that will contain any errors in calling the method
params parameter object that contains all the values required to validate
Returns
  • WorklogResult which can be passed to the update methods if has permission and the data passed in is valid, null otherwise