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

IssueInputParameters

com.atlassian.jira.issue.IssueInputParameters
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 represents an issue builder and can be used to provide parameters that can be used to create and update an issue through the IssueService.

Any fields that are set on this object will have the values used for validation and population of the issue object created via the validate methods on the IssueService. This object is forgiving as possible so if you try to set a null value for a field no exceptions will be thrown, the value will just be ignored.

Some users might want to provide a FieldValuesHolder to the validation calls with some pre-populated data, if this is the case then you can set the field values holder on this object and the IssueService will clone the contents and pass them along to any field invocations it might make.

If you wish to indicate to the IssueService that you do not want to validate against all fields configured for the create screen then you can set the setProvidedFields(java.util.Collection) with the field id's that you want to have validated. All other fields that exist on the screen will be populated with the system default.

To construct a new IssueInputParameters object you can call newIssueInputParameters().

NOTE: this object is not thread-safe and is only meant to be used as a transport object.

See Also

Summary

Public Methods
IssueInputParameters addCustomFieldValue(String fullCustomFieldKey, String... values)
Adds a value for a custom field with the specified full key.
IssueInputParameters addCustomFieldValue(Long customFieldId, String... values)
Adds a value for a custom field with the specified id.
void addFieldToForcePresent(String fieldId)
Extra fields to consider present, even if they are not in the actionParams.
boolean applyDefaultValuesWhenParameterNotProvided()
Map<String, String[]> getActionParameters()
This provides the "web-style" parameters that JIRA fields expect to perform their functions.
Long[] getAffectedVersionIds()
String getAssigneeId()
String getCommentValue()
Long[] getComponentIds()
String[] getCustomFieldValue(String fullCustomFieldKey)
String[] getCustomFieldValue(Long customFieldId)
String getDescription()
String getDueDate()
String getEnvironment()
Map<String, Object> getFieldValuesHolder()
Long[] getFixVersionIds()
String getFormToken()
Return form token if it is present in input parameters
@Nullable HistoryMetadata getHistoryMetadata()
String getIssueTypeId()
Long getOriginalEstimate()
Gets the original estimate set.
String getOriginalEstimateAsDurationString()
Gets the original estimate set.
String getPriorityId()
Long getProjectId()
Collection<String> getProvidedFields()
Long getRemainingEstimate()
Gets the remaining estimate set.
String getRemainingEstimateAsDurationString()
Gets the remaining estimate provided

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getOriginalEstimateAsDurationString().

String getReporterId()
String getResolutionDate()
String getResolutionId()
Long getSecurityLevelId()
String getStatusId()
String getSummary()
Long getTimeSpent()
boolean isFieldPresent(String fieldId)
boolean isFieldSet(String fieldId)
boolean onlyValidatePresentFieldsWhenRetainingExistingValues()
Get the flag to designate which fields are to be validated when the retainExistingValuesWhenParameterNotProvided() flag is set to true.
boolean retainExistingValuesWhenParameterNotProvided()
IssueInputParameters setAffectedVersionIds(Long... affectedVersionIds)
void setApplyDefaultValuesWhenParameterNotProvided(boolean applyDefaults)
IssueInputParameters setAssigneeId(String assigneeId)
IssueInputParameters setComment(String comment, Long projectRoleId)
Set a comment value with a project role restriction.
IssueInputParameters setComment(String comment)
Set a comment value with no visibility restrictions.
IssueInputParameters setComment(String comment, String groupId)
Set a comment value with a group restriction.
IssueInputParameters setComponentIds(Long... componentIds)
IssueInputParameters setDescription(String description)
IssueInputParameters setDueDate(String dueDate)
IssueInputParameters setEnvironment(String environment)
void setFieldValuesHolder(Map<String, Object> fieldValuesHolder)
If set the validation will use the seed values from this field values holder.
IssueInputParameters setFixVersionIds(Long... fixVersionIds)
IssueInputParameters setHistoryMetadata(HistoryMetadata historyMetadata)
Allows defining history metadata related to the issue update.
IssueInputParameters setIssueTypeId(String issueTypeId)
IssueInputParameters setOriginalAndRemainingEstimate(String originalEstimate, String remainingEstimate)
Sets both the original and remaining estimate on the issue.
IssueInputParameters setOriginalAndRemainingEstimate(Long originalEstimate, Long remainingEstimate)
Sets both the original and remaining estimate on the issue.
IssueInputParameters setOriginalEstimate(String originalEstimate)
Sets the original estimate on the issue.
IssueInputParameters setOriginalEstimate(Long originalEstimate)
Sets the original estimate on the issue.
IssueInputParameters setPriorityId(String priorityId)
IssueInputParameters setProjectId(Long projectId)
void setProvidedFields(Collection<String> providedFields)
Use this to indicate which fields validation should be performed on, if left alone then the systems configured fields for either create/update will be used.
IssueInputParameters setRemainingEstimate(String remainingEstimate)
Sets the remaining estimate on the issue

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

IssueInputParameters setRemainingEstimate(Long remainingEstimate)
Sets the remaining estimate on the issue

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

IssueInputParameters setReporterId(String reporterId)
IssueInputParameters setResolutionDate(String resolutionDate)
IssueInputParameters setResolutionId(String resolutionId)
void setRetainExistingValuesWhenParameterNotProvided(boolean retain)
Flag to designate whether existing values should be retained when no parameter is provided.
void setRetainExistingValuesWhenParameterNotProvided(boolean retainExistingValues, boolean onlyValidatePresentFields)
Set flags retainExistingValuesWhenParameterNotProvided() and onlyValidatePresentFieldsWhenRetainingExistingValues().
IssueInputParameters setSecurityLevelId(Long securityLevelId)
void setSkipScreenCheck(boolean skipScreenCheck)
Set the flag to skip screen checks during create or update.
IssueInputParameters setStatusId(String statusId)
IssueInputParameters setSummary(String summary)
IssueInputParameters setTimeSpent(Long timeSpent)
boolean skipScreenCheck()
Get the flag to skip screen checks during create or update.

Public Methods

public IssueInputParameters addCustomFieldValue (String fullCustomFieldKey, String... values)

Adds a value for a custom field with the specified full key. This will put a value in the web-style parameters with a key as provided.

Parameters
fullCustomFieldKey used in the "web-style" parameters as the key, the custom field should expect this value as the key in its populate from parameters method.
values the custom field values, must be in the format the field expects.
Returns
  • this object.

public IssueInputParameters addCustomFieldValue (Long customFieldId, String... values)

Adds a value for a custom field with the specified id. This will put a value in the web-style parameters with a key of the form "customfield_PROVIDED_ID". If you want to specify the key then use the method #addCustomFieldValue(String, String...).

Parameters
customFieldId the unique identifier of the custom field.
values the custom field values, must be in the format the field expects.
Returns
  • this object.

public void addFieldToForcePresent (String fieldId)

Extra fields to consider present, even if they are not in the actionParams. When "setRetainExisitingValuesWhenParameterNotProvided" is true, a field is not considered for update if its parameter is not provided. You can force a field to be considered even if its parameter is not providfed by forcing it to be considered by this setter.

The action post params can also contain an array of fieldIds under the "fieldsToForcePresent" param.

This may be useful if you want to clear a field's value in a single field edit.

Parameters
fieldId the id of the field to force to be present

public boolean applyDefaultValuesWhenParameterNotProvided ()

Returns
  • true if default value should be supplied when a parameter has not been provided. false if the default value should not be applied.

public Map<String, String[]> getActionParameters ()

This provides the "web-style" parameters that JIRA fields expect to perform their functions.

Returns
  • this is a raw map of "web" style input parameters. These parameters are used to allow the fields to attain the user inputted values. This map is of the style: <field_name> <String [] {value}>.

public Long[] getAffectedVersionIds ()

Returns
  • the set affected version id's, null if they do not exist or if they are not valid numbers.

public String getAssigneeId ()

Returns
  • the set assginee, null if one does not exist.

public String getCommentValue ()

Returns
  • the comment string value if it has been set, null otherwise.

public Long[] getComponentIds ()

Returns
  • the set component id's, null if they do not exist or if they are not valid numbers.

public String[] getCustomFieldValue (String fullCustomFieldKey)

Parameters
fullCustomFieldKey identifies the custom field values you are looking for.
Returns
  • the values for the provided custom field if they exist, null otherwise.

public String[] getCustomFieldValue (Long customFieldId)

Parameters
customFieldId uniquely identifies the custom field value you are looking for.
Returns
  • the values for the provided custom field if they exist, null otherwise.

public String getDescription ()

Returns
  • the set description, null if one does not exist.

public String getDueDate ()

Returns
  • the set due date, null if one does not exist.

public String getEnvironment ()

Returns
  • the set environment, null if one does not exist.

public Map<String, Object> getFieldValuesHolder ()

Returns
  • the provided field values holder or an empty map, never null.

public Long[] getFixVersionIds ()

Returns
  • the set fix version id's, null if they do not exist or if they are not valid numbers.

public String getFormToken ()

Return form token if it is present in input parameters

@Nullable public HistoryMetadata getHistoryMetadata ()

Returns
  • the current history metadata for the update, null if not defined

public String getIssueTypeId ()

Returns
  • the set issue type id, null if one does not exist.

public Long getOriginalEstimate ()

Gets the original estimate set.

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getRemainingEstimate().

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Returns
  • the set original estimate, null if one does not exist or it is not a valid number.

public String getOriginalEstimateAsDurationString ()

Gets the original estimate set.

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getRemainingEstimateAsDurationString().

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Returns
  • the set original estimate, null if one does not exist.

public String getPriorityId ()

Returns
  • the set priority id, null if one does not exist.

public Long getProjectId ()

Returns
  • the set project id, null if one does not exist or if it is not a valid number.

public Collection<String> getProvidedFields ()

Returns
  • the field id's that should be validated, null if not specified.

public Long getRemainingEstimate ()

Gets the remaining estimate set.

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getOriginalEstimate() .

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Returns
  • the set remaining estimate, null if one does not exist or it is not a valid number.

public String getRemainingEstimateAsDurationString ()

Gets the remaining estimate provided

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getOriginalEstimateAsDurationString().

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Returns
  • the set remaining estimate, null if one does not exist.

public String getReporterId ()

Returns
  • the set reporter, null if one does not exist.

public String getResolutionDate ()

Returns
  • the set resolution date, null if one does not exist.

public String getResolutionId ()

Returns
  • the set resolution id, null if one does not exist.

public Long getSecurityLevelId ()

Returns
  • the set security level id, null if one does not exist or it is not a valid number.

public String getStatusId ()

Returns
  • the set status id, null if one does not exist.

public String getSummary ()

Returns
  • the set summary, null if one does not exist.

public Long getTimeSpent ()

Returns
  • the set time spent, null if one does not exist or it is not a valid number.

public boolean isFieldPresent (String fieldId)

Parameters
fieldId identifies the field in question, this will be the getId().
Returns
  • true if the field has been set, even with an empty value, false if not.

public boolean isFieldSet (String fieldId)

Parameters
fieldId identifies the field in question, this will be the getId().
Returns
  • true if a non-null, non-empty value has been set for the field, false if not.

public boolean onlyValidatePresentFieldsWhenRetainingExistingValues ()

Get the flag to designate which fields are to be validated when the retainExistingValuesWhenParameterNotProvided() flag is set to true.

If this flag is true, only fields which are "present" will take part in validation (and subsequently update) on the issue. This allows single-field edits to ignore the validation of other fields on the issue.

If this flag is false, or if retainExistingValuesWhenParameterNotProvided() is false, then all fields on the screen of the current operation will partake in the "validation-update" step.

Returns
  • whether or not to only validate present fields
See Also
  • com.atlassian.jira.bc.issue.IssueService#validateUpdate(com.atlassian.crowd.embedded.api.User, Long, IssueInputParameters)

public boolean retainExistingValuesWhenParameterNotProvided ()

Returns
  • true if the issues value should be retained when a parameter has not been provided, false if the missing parameter should be treated as an update.

public IssueInputParameters setAffectedVersionIds (Long... affectedVersionIds)

Parameters
affectedVersionIds sets the affected version id's= on the issue.
Returns
  • this object.

public void setApplyDefaultValuesWhenParameterNotProvided (boolean applyDefaults)

Parameters
applyDefaults true if default value should be supplied when a parameter has not been provided. false if the default value should not be applied.

public IssueInputParameters setAssigneeId (String assigneeId)

Parameters
assigneeId sets the assignee id for the issue.
Returns
  • this object.

public IssueInputParameters setComment (String comment, Long projectRoleId)

Set a comment value with a project role restriction.

Parameters
comment the comment value.
projectRoleId the id of the project role the comment must be restricted by.
Returns
  • this object.

public IssueInputParameters setComment (String comment)

Set a comment value with no visibility restrictions.

Parameters
comment the comment value.
Returns
  • this object.

public IssueInputParameters setComment (String comment, String groupId)

Set a comment value with a group restriction.

Parameters
comment the comment value.
groupId the group name that the comment must be restricted by.
Returns
  • this object.

public IssueInputParameters setComponentIds (Long... componentIds)

Parameters
componentIds sets the components id's on the issue.
Returns
  • this object.

public IssueInputParameters setDescription (String description)

Parameters
description sets the description for the issue.
Returns
  • this object.

public IssueInputParameters setDueDate (String dueDate)

Parameters
dueDate the formatted string that JIRA will accept as a date that will be set on the issue.
Returns
  • this object.

public IssueInputParameters setEnvironment (String environment)

Parameters
environment sets the environment of the issue.
Returns
  • this object.

public void setFieldValuesHolder (Map<String, Object> fieldValuesHolder)

If set the validation will use the seed values from this field values holder.

Parameters
fieldValuesHolder provides the seed values for the field values holder.

public IssueInputParameters setFixVersionIds (Long... fixVersionIds)

Parameters
fixVersionIds sets the fix version id's on the issue.
Returns
  • this object.

public IssueInputParameters setHistoryMetadata (HistoryMetadata historyMetadata)

Allows defining history metadata related to the issue update. This is only relevant for changes that generate history entries (transitions and updates).

Parameters
historyMetadata the metadata to save with the history change
Returns
  • this object

public IssueInputParameters setIssueTypeId (String issueTypeId)

Parameters
issueTypeId sets the issue type for the issue.
Returns
  • this object.

public IssueInputParameters setOriginalAndRemainingEstimate (String originalEstimate, String remainingEstimate)

Sets both the original and remaining estimate on the issue.

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method has no effect.

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Parameters
originalEstimate the new original estimate, e.g. "1d 5h" for 1 day and 5 hours
remainingEstimate the new remaining estimate, e.g. "1d 5h" for 1 day and 5 hours
Returns
  • this object

public IssueInputParameters setOriginalAndRemainingEstimate (Long originalEstimate, Long remainingEstimate)

Sets both the original and remaining estimate on the issue.

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method has no effect.

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Parameters
originalEstimate the new original estimate. The units used are determined by JIRA_TIMETRACKING_DEFAULT_UNIT.
remainingEstimate the new remaining estimate.The units used are determined by JIRA_TIMETRACKING_DEFAULT_UNIT.
Returns
  • this object

public IssueInputParameters setOriginalEstimate (String originalEstimate)

Sets the original estimate on the issue.

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Parameters
originalEstimate the new original estimate on the issue, e.g. "1d 5h" for 1 day and 5 hours
Returns
  • this object.

public IssueInputParameters setOriginalEstimate (Long originalEstimate)

Sets the original estimate on the issue.

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Parameters
originalEstimate the new original estimate on the issue. The units used are determined by JIRA_TIMETRACKING_DEFAULT_UNIT.
Returns
  • this object.

public IssueInputParameters setPriorityId (String priorityId)

Parameters
priorityId sets the priority for the issue.
Returns
  • this object.

public IssueInputParameters setProjectId (Long projectId)

Parameters
projectId sets the project id for the issue.
Returns
  • this object.

public void setProvidedFields (Collection<String> providedFields)

Use this to indicate which fields validation should be performed on, if left alone then the systems configured fields for either create/update will be used.

Parameters
providedFields a collection of getId()'s which identify the fields.

public IssueInputParameters setRemainingEstimate (String remainingEstimate)

Sets the remaining estimate on the issue

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Parameters
remainingEstimate the remaining estimate on the issue, e.g. "1d 5h" for 1 day and 5 hours
Returns
  • this object

public IssueInputParameters setRemainingEstimate (Long remainingEstimate)

Sets the remaining estimate on the issue

If (JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

Parameters
remainingEstimate the remaining estimate on the issue. The units used are determined by JIRA_TIMETRACKING_DEFAULT_UNIT.
Returns
  • this object

public IssueInputParameters setReporterId (String reporterId)

Parameters
reporterId sets the reporter id for the issue.
Returns
  • this object.

public IssueInputParameters setResolutionDate (String resolutionDate)

Parameters
resolutionDate the formatted string that JIRA will accept as a date that will be set on the issue.
Returns
  • this object.

public IssueInputParameters setResolutionId (String resolutionId)

Parameters
resolutionId sets the resolution for the issue.
Returns
  • this object.

public void setRetainExistingValuesWhenParameterNotProvided (boolean retain)

Flag to designate whether existing values should be retained when no parameter is provided.

Note: setting this flag here will assume that validation of fields should still occur, even if they were not specified. To change this, please use setRetainExistingValuesWhenParameterNotProvided(boolean, boolean) instead.

Parameters
retain true if non-provided parameters should have the values retained, false otherwise.
See Also

public void setRetainExistingValuesWhenParameterNotProvided (boolean retainExistingValues, boolean onlyValidatePresentFields)

Set flags retainExistingValuesWhenParameterNotProvided() and onlyValidatePresentFieldsWhenRetainingExistingValues().

The latter is only relevant when the former is true.

Parameters
retainExistingValues true if non-provided parameters should have the values retained, false otherwise.
onlyValidatePresentFields whether or not to only validate present fields
See Also

public IssueInputParameters setSecurityLevelId (Long securityLevelId)

Parameters
securityLevelId sets the security level id on the issue.
Returns
  • this object.

public void setSkipScreenCheck (boolean skipScreenCheck)

Set the flag to skip screen checks during create or update.

By default, the Issue Service only allows setting values to fields which appear on the screen of the operation which you are performing (e.g. the Edit screen). By enabling this flag, the Issue Service will skip this check.

Parameters
skipScreenCheck whether or not we are skipping screen check
See Also
  • com.atlassian.jira.bc.issue.IssueService#validateUpdate(com.atlassian.crowd.embedded.api.User, Long, IssueInputParameters)
  • com.atlassian.jira.bc.issue.IssueService#validateCreate(com.atlassian.crowd.embedded.api.User, IssueInputParameters)

public IssueInputParameters setStatusId (String statusId)

Parameters
statusId sets the status of the issue.
Returns
  • this object.

public IssueInputParameters setSummary (String summary)

Parameters
summary sets the summary for the issue.
Returns
  • this object.

public IssueInputParameters setTimeSpent (Long timeSpent)

Parameters
timeSpent sets the time spent on the issue.
Returns
  • this object.

public boolean skipScreenCheck ()

Get the flag to skip screen checks during create or update.

By default, the Issue Service only allows setting values to fields which appear on the screen of the operation which you are performing (e.g. the Edit screen). By enabling this flag, the Issue Service will skip this check.

Returns
  • whether or not we are skipping screen check
See Also
  • com.atlassian.jira.bc.issue.IssueService#validateUpdate(com.atlassian.crowd.embedded.api.User, Long, IssueInputParameters)
  • com.atlassian.jira.bc.issue.IssueService#validateCreate(com.atlassian.crowd.embedded.api.User, IssueInputParameters)